快速入門：使用自訂視覺 SDK 或 REST API 建立影像分類專案

發行項
11/23/2024

開始使用適用於 .NET 的自訂視覺用戶端程式庫。請遵循下列步驟來安裝套件，並試用建立影像分類模型的程式碼範例。您可以建立專案、新增標記、定型專案，以及使用專案的預測端點 URL，以程式設計方式進行測試。請使用此範例作為自行建置影像辨識應用程式的範本。

注意

如果您想要在不撰寫程式代碼的情況下建置和定型分類模型，請參閱以瀏覽器為基礎的指引。

參考檔 |定型和預測的連結庫原始碼 |用於定型和預測 | 範例的套件（NuGet）

必要條件

Azure 訂用帳戶。您可以免費建立一個訂用帳戶。
Visual Studio IDE 或目前版本的 .NET Core。
擁有 Azure 訂用帳戶之後，請在 Azure 入口網站中建立自訂視覺資源，以建立定型資源和預測資源。
- 您可以使用免費定價層 (F0) 來試用服務，之後可升級至付費層以用於實際執行環境。

建立環境變數

在此範例中，您會在執行應用程式的本機電腦上將認證寫入環境變數。

前往 Azure 入口網站。如果您在部署成功的必要條件一節中建立自訂視覺資源，請選取 [後續步驟] 底下的 [移至資源] 按鈕。您可以在資源 [金鑰] 和 [端點] 頁面的 [資源管理] 底下，找到您的金鑰和端點。您必須取得定型資源和預測資源以及 API 端點的金鑰。

您可以在 Azure 入口網站中預測資源的 [屬性] 索引標籤上找到預測資源識別碼，該識別碼名為 [資源識別碼]。

提示

您也可以使用 https://www.customvision.ai 來取得這些值。登入之後，請選取右上方的 [設定] 圖示。在 [設定] 頁面上，您可以檢視所有金鑰、資源識別碼和端點。

若要設定環境變數，請開啟主控台視窗，然後遵循作業系統和開發環境的指示進行。

若要設定 VISION_TRAINING KEY 環境變數，請以您的定型資源的其中一個金鑰取代 <your-training-key>。
若要設定 VISION_TRAINING_ENDPOINT 環境變數，請將 <your-training-endpoint> 取代為定型資源的端點。
若要設定 VISION_PREDICTION_KEY 環境變數，請以您的預測資源的其中一個金鑰取代 <your-prediction-key>。
若要設定 VISION_PREDICTION_ENDPOINT 環境變數，請將 <your-prediction-endpoint> 取代為預測資源的端點。
若要設定 VISION_PREDICTION_RESOURCE_ID 環境變數，請將 <your-resource-id> 取代為預測資源的資源識別碼。

重要

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求 (英文)。

Windows
Linux

setx VISION_TRAINING_KEY <your-training-key>

setx VISION_TRAINING_ENDPOINT <your-training-endpoint>

setx VISION_PREDICTION_KEY <your-prediction-key>

setx VISION_PREDICTION_ENDPOINT <your-prediction-endpoint>

setx VISION_PREDICTION_RESOURCE_ID <your-resource-id>

新增環境變數之後，您可能需要重新啟動讀取環境變數的任何執行中程式，包括主控台視窗。

export VISION_TRAINING_KEY=<your-training-key>

export VISION_TRAINING_ENDPOINT=<your-training-endpoint>

export VISION_PREDICTION_KEY=<your-prediction-key>

export VISION_PREDICTION_ENDPOINT=<your-prediction-endpoint>

export VISION_PREDICTION_RESOURCE_ID=<your-resource-id>

新增環境變數之後，請從主控台視窗執行 source ~/.bashrc，讓變更生效。

建立新的 C# 應用程式

使用 Visual Studio，建立新的 .NET Core 應用程式。

安裝用戶端程式庫

建立新項目之後，請以滑鼠右鍵按兩下方案總管中的專案方案，然後選取 [管理 NuGet 套件]，以安裝客戶端連結庫。在 開啟的套件管理員中選取 [流覽 ]，然後核 取 [包含發行前版本]，然後搜尋 Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training 和 Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction。選取最新版本，然後選擇 [ 安裝]。

建立新的 C# 應用程式

在主控台視窗中 (例如 cmd、PowerShell 或 Bash)，使用 dotnet new 命令建立名為 custom-vision-quickstart 的新主控台應用程式。此命令會使用單一原始程序檔建立簡單的 Hello World C# 專案： program.cs。

dotnet new console -n custom-vision-quickstart

將目錄變更為新建立的應用程式資料夾。您可以使用下列命令來建置應用程式：

dotnet build

建置輸出應該不會有警告或錯誤。

...
Build succeeded.
 0 Warning(s)
 0 Error(s)
...

安裝用戶端程式庫

在應用程式目錄中，使用下列命令安裝適用於 .NET 的自訂視覺用戶端程式庫：

dotnet add package Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training --version 2.0.0
dotnet add package Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction --version 2.0.0

提示

想要立刻檢視整個快速入門程式碼檔案嗎？您可以在 GitHub 上找到該檔案，其中包含本快速入門中的程式碼範例。

從專案目錄中中開啟 program.cs 檔案，並新增下列 using 指示詞：

using Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction;
using Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training;
using Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training.Models;
using System;
using System.Collections.Generic;
using System.IO;
using System.Linq;
using System.Threading;

在應用程式的方法中 main ，建立變數，以從環境變數擷取資源的密鑰和端點。您也會宣告一些要在稍後使用的基本物件。

// Retrieve the environment variables for your credentials:
private static string trainingEndpoint = Environment.GetEnvironmentVariable("VISION_TRAINING_ENDPOINT");

private static string trainingKey = Environment.GetEnvironmentVariable("VISION_TRAINING_KEY");
private static string predictionEndpoint = Environment.GetEnvironmentVariable("VISION_PREDICTION_ENDPOINT");
private static string predictionKey = Environment.GetEnvironmentVariable("VISION_PREDICTION_KEY");

private static string predictionResourceId = Environment.GetEnvironmentVariable("VISION_PREDICTION_RESOURCE_ID");

private static List<string> hemlockImages;
private static List<string> japaneseCherryImages;
private static Tag hemlockTag;
private static Tag japaneseCherryTag;
private static Iteration iteration;
private static string publishedModelName = "treeClassModel";
private static MemoryStream testImage;

在應用程式的 main 方法中，針對本快速入門中使用的方法新增呼叫。您稍後會實作這些。

CustomVisionTrainingClient trainingApi = AuthenticateTraining(trainingEndpoint, trainingKey);
CustomVisionPredictionClient predictionApi = AuthenticatePrediction(predictionEndpoint, predictionKey);

Project project = CreateProject(trainingApi);
AddTags(trainingApi, project);
UploadImages(trainingApi, project);
TrainProject(trainingApi, project);
PublishIteration(trainingApi, project);
TestIteration(predictionApi, project);
DeleteProject(trainingApi, project);

驗證用戶端

在新方法中，使用您的端點和金鑰來具現化定型和預測用戶端。

private static CustomVisionTrainingClient AuthenticateTraining(string endpoint, string trainingKey)
{
    // Create the Api, passing in the training key
    CustomVisionTrainingClient trainingApi = new CustomVisionTrainingClient(new Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training.ApiKeyServiceClientCredentials(trainingKey))
    {
        Endpoint = endpoint
    };
    return trainingApi;
}
private static CustomVisionPredictionClient AuthenticatePrediction(string endpoint, string predictionKey)
{
    // Create a prediction endpoint, passing in the obtained prediction key
    CustomVisionPredictionClient predictionApi = new CustomVisionPredictionClient(new Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction.ApiKeyServiceClientCredentials(predictionKey))
    {
        Endpoint = endpoint
    };
    return predictionApi;
}

建立新的自訂視覺專案

此下一段程式碼會建立影像分類專案。建立的項目會顯示在自訂視覺網站上。當您建立專案時，請參閱 CreateProject 方法來指定其他選項 (如建置分類器 Web 入口網站指南中所述)。

private static Project CreateProject(CustomVisionTrainingClient trainingApi)
{
    // Create a new project
    Console.WriteLine("Creating new project:");
    return trainingApi.CreateProject("My New Project");
}

將標記新增至專案

這個方法會定義您定型模型的標記。

private static void AddTags(CustomVisionTrainingClient trainingApi, Project project)
{
    // Make two tags in the new project
    hemlockTag = trainingApi.CreateTag(project.Id, "Hemlock");
    japaneseCherryTag = trainingApi.CreateTag(project.Id, "Japanese Cherry");
}

上傳並標記影像

首先，下載此專案的範例影像。將範例影像資料夾的內容儲存到您的本機裝置。

然後定義 Helper 方法，以在此目錄中上傳影像。您可能需要編輯 GetFiles 自變數，以指向影像儲存的位置。

private static void LoadImagesFromDisk()
{
    // this loads the images to be uploaded from disk into memory
    hemlockImages = Directory.GetFiles(Path.Combine("Images", "Hemlock")).ToList();
    japaneseCherryImages = Directory.GetFiles(Path.Combine("Images", "Japanese_Cherry")).ToList();
    testImage = new MemoryStream(File.ReadAllBytes(Path.Combine("Images", "Test", "test_image.jpg")));
}

接下來，定義上傳影像的方法，並根據其資料夾位置套用標籤。影像已排序。您可以反覆地或以批次 (每個批次最多 64 個) 方式上傳和標記影像。此程式碼片段包含兩者的範例。

private static void UploadImages(CustomVisionTrainingClient trainingApi, Project project)
{
    // Add some images to the tags
    Console.WriteLine("\tUploading images");
    LoadImagesFromDisk();

    // Images can be uploaded one at a time
    foreach (var image in hemlockImages)
    {
        using (var stream = new MemoryStream(File.ReadAllBytes(image)))
        {
            trainingApi.CreateImagesFromData(project.Id, stream, new List<Guid>() { hemlockTag.Id });
        }
    }

    // Or uploaded in a single batch 
    var imageFiles = japaneseCherryImages.Select(img => new ImageFileCreateEntry(Path.GetFileName(img), File.ReadAllBytes(img))).ToList();
    trainingApi.CreateImagesFromFiles(project.Id, new ImageFileCreateBatch(imageFiles, new List<Guid>() { japaneseCherryTag.Id }));

}

為專案定型

此方法會建立專案中的第一個定型反覆運算。其會查詢服務，直到定型完成為止。

private static void TrainProject(CustomVisionTrainingClient trainingApi, Project project)
{
    // Now there are images with tags start training the project
    Console.WriteLine("\tTraining");
    iteration = trainingApi.TrainProject(project.Id);

    // The returned iteration will be in progress, and can be queried periodically to see when it has completed
    while (iteration.Status == "Training")
    {
        Console.WriteLine("Waiting 10 seconds for training to complete...");
        Thread.Sleep(10000);

        // Re-query the iteration to get it's updated status
        iteration = trainingApi.GetIteration(project.Id, iteration.Id);
    }
}

提示

使用選取的標記進行訓練

您可以選擇只在已套用的標記子集上進行訓練。您可以在尚未套用足夠的特定標記，但其他套用的標記已足夠時執行此操作。在 TrainProject 呼叫中，使用 trainingParameters 參數。建構 TrainingParameters，並將其屬性設定SelectedTags為您想要使用之標籤的識別碼清單。此模型將訓練為僅辨識該清單上的標記。

發佈目前的反覆項目

此方法會讓模型的目前反覆運算可供查詢。您可以使用模型名稱作為參考，以傳送預測要求。您必須針對 predictionResourceId 輸入自己的值。您可以在 Azure 入口網站中資源的 [屬性] 索引標籤上找到預測資源識別碼，該識別碼名為 [資源識別碼]。

private static void PublishIteration(CustomVisionTrainingClient trainingApi, Project project)
{
    trainingApi.PublishIteration(project.Id, iteration.Id, publishedModelName, predictionResourceId);
    Console.WriteLine("Done!\n");

    // Now there is a trained endpoint, it can be used to make a prediction
}

測試預測端點

這部分的指令碼會載入測試影像、查詢模型端點，並將預測資料輸出至主控台。

private static void TestIteration(CustomVisionPredictionClient predictionApi, Project project)
{

    // Make a prediction against the new project
    Console.WriteLine("Making a prediction:");
    var result = predictionApi.ClassifyImage(project.Id, publishedModelName, testImage);

    // Loop over each prediction and write out the results
    foreach (var c in result.Predictions)
    {
        Console.WriteLine($"\t{c.TagName}: {c.Probability:P1}");
    }
}

執行應用程式

Visual Studio IDE
CLI

按一下 IDE 視窗頂端的 [偵錯] 按鈕，以執行應用程式。

使用 dotnet run 命令從您的應用程式目錄執行應用程式。

dotnet run

應用程式在執行時，應會開啟主控台視窗並寫入下列輸出：

Creating new project:
        Uploading images
        Training
Done!

Making a prediction:
        Hemlock: 95.0%
        Japanese Cherry: 0.0%

接著，您可以確認測試影像 (位於 Images/Test/ 中) 是否已正確加上標記。按任意鍵以結束應用程式。您也可以返回自訂視覺網站，然後查看新建立專案的目前狀態。

清除資源

如果您想要實作您自己的影像分類專案 (或改為嘗試物體偵測專案)，則建議您刪除此範例中的樹木識別專案。免費訂用帳戶可使用兩個自訂視覺專案。

在自訂視覺網站上，瀏覽至 [專案]，然後選取 [我的新專案] 底下的資源回收筒。

面板的螢幕擷取畫面，該面板標示為 [我的新專案] 並有資源回收筒圖示。

現在，您已了解如何在程式碼中完成物件偵測程序的每個步驟。此範例會執行單一的訓練反覆項目，但您通常必須對模型進行多次訓練和測試，以便提升其精確度。

測試和重新定型模型

什麼是自訂視覺服務？
此範例的原始程式碼位於 GitHub
SDK 參考文件

本指南提供指示和範例程式碼，可協助您開始使用適用於 Go 的自訂視覺用戶端程式庫來建置影像分類模型。您將建立專案、新增標籤、將專案定型，並使用專案的預測端點 URL 以程式設計方式加以測試。請使用此範例作為自行建置影像辨識應用程式的範本。

注意

如果您想要在不撰寫程式代碼的情況下建置和定型分類模型，請參閱以瀏覽器為基礎的指引。

使用適用於 Go 的自訂視覺用戶端程式庫可執行下列作業：

建立新的自訂視覺專案
將標記新增至專案
上傳和標記影像
為專案定型
發佈目前的反覆項目
測試預測端點

（訓練）和（預測）的參考檔

必要條件

Azure 訂用帳戶。您可以免費建立一個訂用帳戶。
Go 1.8 或更新版本。
擁有 Azure 訂閱之後，在 Azure 入口網站中建立自訂視覺資源，以建立定型和預測資源。
- 您可以使用免費定價層 (F0) 來試用服務，之後可升級至付費層以用於實際執行環境。

建立環境變數

在此範例中，您會在執行應用程式的本機電腦上將認證寫入環境變數。

前往 Azure 入口網站。如果您已成功部署在 [必要條件] 區段中建立自訂視覺資源，請選取 [後續步驟] 底下的 [移至資源] 按鈕。您可以在資源 [金鑰] 和 [端點] 頁面的 [資源管理] 底下，找到您的金鑰和端點。您必須取得定型資源和預測資源以及 API 端點的金鑰。

您可以在 Azure 入口網站中預測資源的 [屬性] 索引標籤上找到預測資源識別碼，該識別碼名為 [資源識別碼]。

提示

若要設定環境變數，請開啟主控台視窗，然後遵循作業系統和開發環境的指示進行。

若要設定 VISION_TRAINING KEY 環境變數，請以您的定型資源的其中一個金鑰取代 <your-training-key>。
若要設定 VISION_TRAINING_ENDPOINT 環境變數，請將 <your-training-endpoint> 取代為定型資源的端點。
若要設定 VISION_PREDICTION_KEY 環境變數，請以您的預測資源的其中一個金鑰取代 <your-prediction-key>。
若要設定 VISION_PREDICTION_ENDPOINT 環境變數，請將 <your-prediction-endpoint> 取代為預測資源的端點。
若要設定 VISION_PREDICTION_RESOURCE_ID 環境變數，請將 <your-resource-id> 取代為預測資源的資源識別碼。

重要

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求 (英文)。

Windows
Linux

setx VISION_TRAINING_KEY <your-training-key>

setx VISION_TRAINING_ENDPOINT <your-training-endpoint>

setx VISION_PREDICTION_KEY <your-prediction-key>

setx VISION_PREDICTION_ENDPOINT <your-prediction-endpoint>

setx VISION_PREDICTION_RESOURCE_ID <your-resource-id>

新增環境變數之後，您可能需要重新啟動讀取環境變數的任何執行中程式，包括主控台視窗。

export VISION_TRAINING_KEY=<your-training-key>

export VISION_TRAINING_ENDPOINT=<your-training-endpoint>

export VISION_PREDICTION_KEY=<your-prediction-key>

export VISION_PREDICTION_ENDPOINT=<your-prediction-endpoint>

export VISION_PREDICTION_RESOURCE_ID=<your-resource-id>

新增環境變數之後，請從主控台視窗執行 source ~/.bashrc，讓變更生效。

設定

安裝自訂視覺用戶端程式庫

若要使用自訂視覺 for Go 撰寫影像分析應用程式，您需要自訂視覺服務用戶端連結庫。在 PowerShell 中執行下列命令：

go get -u github.com/Azure/azure-sdk-for-go/...

或者，如果您使用 dep，請在存放庫內執行：

dep ensure -add github.com/Azure/azure-sdk-for-go

取得範例影像

此範例會使用 GitHub 上的 Azure AI 服務 Python SDK 範例存放庫中的影像。將此存放庫複製或下載到您的開發環境。請記住其資料夾位置以便執行後續步驟。

建立自訂視覺專案

在您偏好的專案目錄中建立名為 sample.go 的新檔案，接著在您偏好的程式碼編輯器中開啟。

在指令碼中新增下列程式碼，以建立新的自訂視覺服務專案。

當您建立專案時，請參閱 CreateProject 方法來指定其他選項 (如建置分類器 Web 入口網站指南中所述)。

import(
    "context"
    "bytes"
    "fmt"
    "io/ioutil"
    "path"
    "log"
    "time"
    "github.com/Azure/azure-sdk-for-go/services/cognitiveservices/v3.0/customvision/training"
    "github.com/Azure/azure-sdk-for-go/services/cognitiveservices/v3.0/customvision/prediction"
)

var (
    training_key string = os.Getenv("VISION_TRAINING_KEY")
    prediction_key string = os.Getenv("VISION_PREDICTION_KEY")
    prediction_resource_id = os.Getenv("VISION_PREDICTION_RESOURCE_ID")
    endpoint string = os.Getenv("VISION_ENDPOINT")    

    project_name string = "Go Sample Project"
    iteration_publish_name = "classifyModel"
    sampleDataDirectory = "<path to sample images>"
)

func main() {
    fmt.Println("Creating project...")

    ctx = context.Background()

    trainer := training.New(training_key, endpoint)

    project, err := trainer.CreateProject(ctx, project_name, "sample project", nil, string(training.Multilabel))
    if (err != nil) {
        log.Fatal(err)
    }

在專案中建立標記

若要在專案中建立分類標記，請在 sample.go 結尾新增以下程式碼：

// Make two tags in the new project
hemlockTag, _ := trainer.CreateTag(ctx, *project.ID, "Hemlock", "Hemlock tree tag", string(training.Regular))
cherryTag, _ := trainer.CreateTag(ctx, *project.ID, "Japanese Cherry", "Japanese cherry tree tag", string(training.Regular))

上傳並標記影像

若要將範例影像新增到專案，在標記建立之後插入下列程式碼。此程式碼會上傳每個影像及其對應標記。您最多可以在單一批次中上傳 64 個影像。

注意

您必須根據 Azure AI 服務 Go SDK 範例專案稍早的下載位置，來變更影像的路徑。

fmt.Println("Adding images...")
japaneseCherryImages, err := ioutil.ReadDir(path.Join(sampleDataDirectory, "Japanese Cherry"))
if err != nil {
    fmt.Println("Error finding Sample images")
}

hemLockImages, err := ioutil.ReadDir(path.Join(sampleDataDirectory, "Hemlock"))
if err != nil {
    fmt.Println("Error finding Sample images")
}

for _, file := range hemLockImages {
    imageFile, _ := ioutil.ReadFile(path.Join(sampleDataDirectory, "Hemlock", file.Name()))
    imageData := ioutil.NopCloser(bytes.NewReader(imageFile))

    trainer.CreateImagesFromData(ctx, *project.ID, imageData, []string{ hemlockTag.ID.String() })
}

for _, file := range japaneseCherryImages {
    imageFile, _ := ioutil.ReadFile(path.Join(sampleDataDirectory, "Japanese Cherry", file.Name()))
    imageData := ioutil.NopCloser(bytes.NewReader(imageFile))
    trainer.CreateImagesFromData(ctx, *project.ID, imageData, []string{ cherryTag.ID.String() })
}

訓練及發佈專案

此程式碼會在預測模型中建立第一個反覆項目，然後將該反覆項目發佈至預測端點。提供給已發佈反覆項目的名稱可用來傳送預測要求。在預測端點中無法取得反覆專案，直到它發佈為止。

fmt.Println("Training...")
iteration, _ := trainer.TrainProject(ctx, *project.ID)
for {
    if *iteration.Status != "Training" {
        break
    }
    fmt.Println("Training status: " + *iteration.Status)
    time.Sleep(1 * time.Second)
    iteration, _ = trainer.GetIteration(ctx, *project.ID, *iteration.ID)
}
fmt.Println("Training status: " + *iteration.Status)

trainer.PublishIteration(ctx, *project.ID, *iteration.ID, iteration_publish_name, prediction_resource_id))

使用預測端點

若要將影像傳送到預測端點並擷取預測，在檔案結尾處新增以下程式碼：

    fmt.Println("Predicting...")
    predictor := prediction.New(prediction_key, endpoint)

    testImageData, _ := ioutil.ReadFile(path.Join(sampleDataDirectory, "Test", "test_image.jpg"))
    results, _ := predictor.ClassifyImage(ctx, *project.ID, iteration_publish_name, ioutil.NopCloser(bytes.NewReader(testImageData)), "")

    for _, prediction := range *results.Predictions    {
        fmt.Printf("\t%s: %.2f%%", *prediction.TagName, *prediction.Probability * 100)
        fmt.Println("")
    }
}

執行應用程式

使用下列命令來執行應用程式：

go run sample.go

應用程式的輸出應該會類似下列文字：

Creating project...
Adding images...
Training...
Training status: Training
Training status: Training
Training status: Training
Training status: Completed
Done!
        Hemlock: 93.53%
        Japanese Cherry: 0.01%

接著，您可以確認測試影像 (位於 <base_image_url>/Images/Test/) 的標記是否適當。您也可以返回自訂視覺網站，然後查看新建立專案的目前狀態。

清除資源

如果您想要實作您自己的影像分類專案 (或改為嘗試物體偵測專案)，則建議您刪除此範例中的樹木識別專案。免費訂用帳戶可使用兩個自訂視覺專案。

在自訂視覺網站上，瀏覽至 [專案]，然後選取 [我的新專案] 底下的資源回收筒。

面板的螢幕擷取畫面，該面板標示為 [我的新專案] 並有資源回收筒圖示。

測試和重新定型模型

開始使用適用於 Java 的自訂視覺用戶端程式庫來建置影像分類模型。請遵循下列步驟來安裝套件，並試用基本工作的程式碼範例。請使用此範例作為自行建置影像辨識應用程式的範本。

注意

如果您想要在不撰寫程式代碼的情況下建置和定型分類模型，請參閱以瀏覽器為基礎的指引。

使用適用於 Java 的自訂視覺用戶端程式庫可執行下列作業：

建立新的自訂視覺專案
將標記新增至專案
上傳和標記影像
為專案定型
發佈目前的反覆項目
測試預測端點

參考檔 |適用於（訓練）和（預測）的連結庫原始程式碼 |成品（Maven）用於（訓練）和（預測） | 範例

必要條件

Azure 訂用帳戶。您可以免費建立一個訂用帳戶。
Java 開發工具組（JDK）的目前版本。
Gradle 建置工具，或其他相依性管理員。
擁有 Azure 訂閱之後，在 Azure 入口網站中建立自訂視覺資源，以建立定型和預測資源。
- 您可以使用免費定價層 (F0) 來試用服務，之後可升級至付費層以用於實際執行環境。

建立環境變數

在此範例中，您會在執行應用程式的本機電腦上將認證寫入環境變數。

您可以在 Azure 入口網站中預測資源的 [屬性] 索引標籤上找到預測資源識別碼，該識別碼名為 [資源識別碼]。

提示

若要設定環境變數，請開啟主控台視窗，然後遵循作業系統和開發環境的指示進行。

若要設定 VISION_TRAINING KEY 環境變數，請以您的定型資源的其中一個金鑰取代 <your-training-key>。
若要設定 VISION_TRAINING_ENDPOINT 環境變數，請將 <your-training-endpoint> 取代為定型資源的端點。
若要設定 VISION_PREDICTION_KEY 環境變數，請以您的預測資源的其中一個金鑰取代 <your-prediction-key>。
若要設定 VISION_PREDICTION_ENDPOINT 環境變數，請將 <your-prediction-endpoint> 取代為預測資源的端點。
若要設定 VISION_PREDICTION_RESOURCE_ID 環境變數，請將 <your-resource-id> 取代為預測資源的資源識別碼。

重要

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求 (英文)。

Windows
Linux

setx VISION_TRAINING_KEY <your-training-key>

setx VISION_TRAINING_ENDPOINT <your-training-endpoint>

setx VISION_PREDICTION_KEY <your-prediction-key>

setx VISION_PREDICTION_ENDPOINT <your-prediction-endpoint>

setx VISION_PREDICTION_RESOURCE_ID <your-resource-id>

新增環境變數之後，您可能需要重新啟動讀取環境變數的任何執行中程式，包括主控台視窗。

export VISION_TRAINING_KEY=<your-training-key>

export VISION_TRAINING_ENDPOINT=<your-training-endpoint>

export VISION_PREDICTION_KEY=<your-prediction-key>

export VISION_PREDICTION_ENDPOINT=<your-prediction-endpoint>

export VISION_PREDICTION_RESOURCE_ID=<your-resource-id>

新增環境變數之後，請從主控台視窗執行 source ~/.bashrc，讓變更生效。

設定

建立新的 Gradle 專案

在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中，為您的應用程式建立新的目錄，並瀏覽至該目錄。

mkdir myapp && cd myapp

從您的工作目錄執行 gradle init 命令。此命令會建立 Gradle 的基本組建檔案，包括 build.gradle.kts，將在執行階段使用 build.gradle.kts，來建立及設定應用程式。

gradle init --type basic

出現選擇 DSL 的提示時，請選取 [Kotlin]。

安裝用戶端程式庫

找出 build.gradle.kts，並使用您慣用的 IDE 或文字編輯器加以開啟。然後，在其中複製下列組建組態。此群組態會將項目定義為 Java 應用程式，其進入點為類別 CustomVisionQuickstart。這會匯入自訂視覺程式庫。

plugins {
    java
    application
}
application { 
    mainClassName = "CustomVisionQuickstart"
}
repositories {
    mavenCentral()
}
dependencies {
    compile(group = "com.azure", name = "azure-cognitiveservices-customvision-training", version = "1.1.0-preview.2")
    compile(group = "com.azure", name = "azure-cognitiveservices-customvision-prediction", version = "1.1.0-preview.2")
}

建立 Java 檔案

在您的工作目錄中執行下列命令，以建立專案來源資料夾：

mkdir -p src/main/java

瀏覽至新的資料夾，並建立名為 CustomVisionQuickstart.java 的檔案。在您慣用的編輯器或 IDE 中開啟該檔案，並新增下列 import 陳述式：

import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.UUID;

import com.google.common.io.ByteStreams;

import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Classifier;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Domain;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.DomainType;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.ImageFileCreateBatch;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.ImageFileCreateEntry;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Iteration;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Project;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Region;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.TrainProjectOptionalParameter;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.CustomVisionTrainingClient;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.Trainings;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.CustomVisionTrainingManager;
import com.microsoft.azure.cognitiveservices.vision.customvision.prediction.models.ImagePrediction;
import com.microsoft.azure.cognitiveservices.vision.customvision.prediction.models.Prediction;
import com.microsoft.azure.cognitiveservices.vision.customvision.prediction.CustomVisionPredictionClient;
import com.microsoft.azure.cognitiveservices.vision.customvision.prediction.CustomVisionPredictionManager;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Tag;

提示

想要立刻檢視整個快速入門程式碼檔案嗎？您可以在 GitHub 上找到該檔案，其中包含本快速入門中的程式碼範例。

在應用程式的類別中 CustomVisionQuickstart ，建立變數，從環境變數擷取資源的密鑰和端點。

// retrieve environment variables
final static String trainingApiKey = System.getenv("VISION_TRAINING_KEY");
final static String trainingEndpoint = System.getenv("VISION_TRAINING_ENDPOINT");
final static String predictionApiKey = System.getenv("VISION_PREDICTION_KEY");
final static String predictionEndpoint = System.getenv("VISION_PREDICTION_ENDPOINT");
final static String predictionResourceId = System.getenv("VISION_PREDICTION_RESOURCE_ID");

重要

切記，完成時從程式碼中移除金鑰，且切勿公開發佈金鑰。在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure Key Vault。如需詳細資訊，請參閱 Azure AI 服務安全性一文。

在應用程式的 main 方法中，針對本快速入門中使用的方法新增呼叫。稍後您會定義這些項目。

Project project = createProject(trainClient);
addTags(trainClient, project);
uploadImages(trainClient, project);
trainProject(trainClient, project);
publishIteration(trainClient, project);
testProject(predictor, project);

物件模型

下列類別和介面會處理自訂視覺 Java 用戶端程式庫的一些主要功能。

名稱	描述
CustomVisionTrainingClient	此類別會處理模型的建立、定型和發佈。
CustomVisionPredictionClient	此類別會處理您的模型查詢，以進行影像分類預測。
ImagePrediction	此類別會定義單一影像上的單一預測。其中包含物件識別碼和名稱的屬性，以及信賴分數。

程式碼範例

這些程式碼片段說明如何使用適用於 Java 的自訂視覺用戶端程式庫來執行下列工作：

驗證用戶端
建立新的自訂視覺專案
將標記新增至專案
上傳和標記影像
為專案定型
發佈目前的反覆項目
測試預測端點

驗證用戶端

在您的 main 方法中，使用端點和密鑰具現化定型和預測用戶端。

// Authenticate
CustomVisionTrainingClient trainClient = CustomVisionTrainingManager
        .authenticate(trainingEndpoint, trainingApiKey)
        .withEndpoint(trainingEndpoint);
CustomVisionPredictionClient predictor = CustomVisionPredictionManager
        .authenticate(predictionEndpoint, predictionApiKey)
        .withEndpoint(predictionEndpoint);

建立自訂視覺專案

下一個方法會建立影像分類專案。所建立的專案會顯示在您稍早瀏覽過的自訂視覺網站上。當您建立專案時，請參閱 CreateProject 方法多載來指定其他選項 (如建立偵測器 Web 入口網站指南中所述)。

public static Project createProject(CustomVisionTrainingClient trainClient) {
    System.out.println("ImageClassification Sample");
    Trainings trainer = trainClient.trainings();

    System.out.println("Creating project...");
    Project project = trainer.createProject().withName("Sample Java Project").execute();

    return project;
}

將標記新增到您的專案

此方法會定義您將用來定型模型的標記。

public static void addTags(CustomVisionTrainingClient trainClient, Project project) {

    Trainings trainer = trainClient.trainings();

    // create hemlock tag
    Tag hemlockTag = trainer.createTag().withProjectId(project.id()).withName("Hemlock").execute();
    // create cherry tag
    Tag cherryTag = trainer.createTag().withProjectId(project.id()).withName("Japanese Cherry").execute();
}

上傳並標記影像

首先，下載此專案的範例影像。將範例影像資料夾的內容儲存到您的本機裝置。

public static void uploadImages(CustomVisionTrainingClient trainClient, Project project) {
    Trainings trainer = trainClient.trainings();
    System.out.println("Adding images...");
    for (int i = 1; i <= 10; i++) {
        String fileName = "hemlock_" + i + ".jpg";
        byte[] contents = GetImage("/Hemlock", fileName);
        AddImageToProject(trainer, project, fileName, contents, hemlockTag.id(), null);
    }

    for (int i = 1; i <= 10; i++) {
        String fileName = "japanese_cherry_" + i + ".jpg";
        byte[] contents = GetImage("/Japanese_Cherry", fileName);
        AddImageToProject(trainer, project, fileName, contents, cherryTag.id(), null);
    }
}

先前的程式碼片段利用兩個協助程式函式，將影像擷取為資源串流，然後上傳到服務 (您最多可以在單一批次中上傳 64 個影像)。

private static void AddImageToProject(Trainings trainer, Project project, String fileName, byte[] contents,
        UUID tag, double[] regionValues) {
    System.out.println("Adding image: " + fileName);
    ImageFileCreateEntry file = new ImageFileCreateEntry().withName(fileName).withContents(contents);

    ImageFileCreateBatch batch = new ImageFileCreateBatch().withImages(Collections.singletonList(file));

    // If Optional region is specified, tack it on and place the tag there,
    // otherwise
    // add it to the batch.
    if (regionValues != null) {
        Region region = new Region().withTagId(tag).withLeft(regionValues[0]).withTop(regionValues[1])
                .withWidth(regionValues[2]).withHeight(regionValues[3]);
        file = file.withRegions(Collections.singletonList(region));
    } else {
        batch = batch.withTagIds(Collections.singletonList(tag));
    }

    trainer.createImagesFromFiles(project.id(), batch);
}

private static byte[] GetImage(String folder, String fileName) {
    try {
        return ByteStreams.toByteArray(CustomVisionSamples.class.getResourceAsStream(folder + "/" + fileName));
    } catch (Exception e) {
        System.out.println(e.getMessage());
        e.printStackTrace();
    }
    return null;
}

為專案定型

此方法會建立專案中的第一個定型反覆運算。其會查詢服務，直到定型完成為止。

public static void trainProject(CustomVisionTrainingClient trainClient, Project project) {
    System.out.println("Training...");
    Trainings trainer = trainClient.trainings();

    Iteration iteration = trainer.trainProject(project.id(), new TrainProjectOptionalParameter());

    while (iteration.status().equals("Training")) {
        System.out.println("Training Status: " + iteration.status());
        Thread.sleep(1000);
        iteration = trainer.getIteration(project.id(), iteration.id());
    }
    System.out.println("Training Status: " + iteration.status());
}

發佈目前的反覆項目

public static String publishIteration(CustomVisionTrainingClient trainClient, Project project) {
    Trainings trainer = trainClient.trainings();
    // The iteration is now trained. Publish it to the prediction endpoint.
    String publishedModelName = "myModel";
    trainer.publishIteration(project.id(), iteration.id(), publishedModelName, predictionResourceId);
}

測試預測端點

此方法會載入測試影像、查詢模型端點，並將預測資料輸出至主控台。

// load test image
public static void testProject(CustomVisionPredictionClient predictor, Project project) {

    byte[] testImage = GetImage("/Test", "test_image.jpg");

    // predict
    ImagePrediction results = predictor.predictions().classifyImage().withProjectId(project.id())
            .withPublishedName(publishedModelName).withImageData(testImage).execute();

    for (Prediction prediction : results.predictions()) {
        System.out.println(String.format("\t%s: %.2f%%", prediction.tagName(), prediction.probability() * 100.0f));
    }
}

執行應用程式

您可以使用下列命令來建置應用程式：

gradle build

使用 gradle run 命令執行應用程式：

gradle run

清除資源

如果您想要清除和移除 Azure AI 服務訂用帳戶，則可以刪除資源或資源群組。刪除資源群組也會刪除與其相關聯的任何其他資源。

如果您想要實作您自己的影像分類專案 (或改為嘗試物體偵測專案)，則建議您刪除此範例中的樹木識別專案。免費訂用帳戶可使用兩個自訂視覺專案。

在自訂視覺網站上，瀏覽至 [專案]，然後選取 [我的新專案] 底下的資源回收筒。

面板的螢幕擷取畫面，該面板標示為 [我的新專案] 並有資源回收筒圖示。

測試和重新定型模型

什麼是自訂視覺服務？
此範例的原始程式碼位於 GitHub

本指南提供指示和範例程式碼，可協助您開始使用適用於 Node.js 的自訂視覺用戶端程式庫來建置影像分類模型。您可以建立專案、新增標記、定型專案，以及使用專案的預測端點 URL，以程式設計方式測試專案。請使用此範例作為自行建置影像辨識應用程式的範本。

注意

如果您想要在不撰寫程式代碼的情況下建置和定型分類模型，請參閱以瀏覽器為基礎的指引。

使用自訂視覺用戶端連結庫進行下列Node.js：

建立新的自訂視覺專案
將標記新增至專案
上傳和標記影像
為專案定型
發佈目前的反覆項目
測試預測端點

（訓練）和（預測）的參考檔 |（訓練）和（預測）範例的套件（npm） |

必要條件

Azure 訂用帳戶。您可以免費建立一個訂用帳戶。
最新版的 Node.js。
擁有 Azure 訂閱之後，在 Azure 入口網站中建立自訂視覺資源，以建立定型和預測資源。
- 您可以使用免費定價層 (F0) 來試用服務，之後可升級至付費層以用於實際執行環境。

建立環境變數

在此範例中，您會在執行應用程式的本機電腦上將認證寫入環境變數。

您可以在 Azure 入口網站中預測資源的 [屬性] 索引標籤上找到預測資源識別碼，該識別碼名為 [資源識別碼]。

提示

若要設定環境變數，請開啟主控台視窗，然後遵循作業系統和開發環境的指示進行。

若要設定 VISION_TRAINING KEY 環境變數，請以您的定型資源的其中一個金鑰取代 <your-training-key>。
若要設定 VISION_TRAINING_ENDPOINT 環境變數，請將 <your-training-endpoint> 取代為定型資源的端點。
若要設定 VISION_PREDICTION_KEY 環境變數，請以您的預測資源的其中一個金鑰取代 <your-prediction-key>。
若要設定 VISION_PREDICTION_ENDPOINT 環境變數，請將 <your-prediction-endpoint> 取代為預測資源的端點。
若要設定 VISION_PREDICTION_RESOURCE_ID 環境變數，請將 <your-resource-id> 取代為預測資源的資源識別碼。

重要

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求 (英文)。

Windows
Linux

setx VISION_TRAINING_KEY <your-training-key>

setx VISION_TRAINING_ENDPOINT <your-training-endpoint>

setx VISION_PREDICTION_KEY <your-prediction-key>

setx VISION_PREDICTION_ENDPOINT <your-prediction-endpoint>

setx VISION_PREDICTION_RESOURCE_ID <your-resource-id>

新增環境變數之後，您可能需要重新啟動讀取環境變數的任何執行中程式，包括主控台視窗。

export VISION_TRAINING_KEY=<your-training-key>

export VISION_TRAINING_ENDPOINT=<your-training-endpoint>

export VISION_PREDICTION_KEY=<your-prediction-key>

export VISION_PREDICTION_ENDPOINT=<your-prediction-endpoint>

export VISION_PREDICTION_RESOURCE_ID=<your-resource-id>

新增環境變數之後，請從主控台視窗執行 source ~/.bashrc，讓變更生效。

設定

建立新的 Node.js 應用程式

在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中，為您的應用程式建立新的目錄，並瀏覽至該目錄。

mkdir myapp && cd myapp

執行命令 npm init，以使用 package.json 檔案建立節點應用程式。按 ENTER 多次以完成此程式。

npm init

安裝用戶端程式庫

若要撰寫具有 Node.js 自訂視覺的影像分析應用程式，您需要自訂視覺 npm 套件。若要加以安裝，請在 PowerShell 中執行下列命令：

npm install @azure/cognitiveservices-customvision-training
npm install @azure/cognitiveservices-customvision-prediction

您應用程式的 package.json 檔案會隨著相依性而更新。

建立名為 index.js 的檔案，並匯入下列程式庫：

const util = require('util');
const fs = require('fs');
const TrainingApi = require("@azure/cognitiveservices-customvision-training");
const PredictionApi = require("@azure/cognitiveservices-customvision-prediction");
const msRest = require("@azure/ms-rest-js");

提示

想要立刻檢視整個快速入門程式碼檔案嗎？您可以在 GitHub 上找到該檔案，其中包含本快速入門中的程式碼範例。

為資源的 Azure 端點和金鑰建立變數。

// retrieve environment variables
const trainingKey = process.env["VISION_TRAINING_KEY"];
const trainingEndpoint = process.env["VISION_TRAINING_ENDPOINT"];

const predictionKey = process.env["VISION_PREDICTION_KEY"];
const predictionResourceId = process.env["VISION_PREDICTION_RESOURCE_ID"];
const predictionEndpoint = process.env["VISION_PREDICTION_ENDPOINT"];

同時新增專案名稱的欄位，以及非同步呼叫的逾時參數。

const publishIterationName = "classifyModel";
const setTimeoutPromise = util.promisify(setTimeout);

物件模型

名稱	描述
TrainingAPIClient	此類別會處理模型的建立、定型和發佈。
PredictionAPIClient	此類別會處理您的模型查詢，以進行影像分類預測。
預測	此介面會定義單一影像上的單一預測。其中包含物件識別碼和名稱的屬性，以及信賴分數。

程式碼範例

這些程式碼片段說明如何使用適用於 JavaScript 的自訂視覺用戶端程式庫來執行下列工作：

驗證用戶端
建立新的自訂視覺專案
將標記新增至專案
上傳和標記影像
為專案定型
發佈目前的反覆項目
測試預測端點

驗證用戶端

使用端點和金鑰將用戶端物件具現化。使用金鑰建立 ApiKeyCredentials 物件，並使用該物件與您的端點建立 TrainingAPIClient 和 PredictionAPIClient 物件。

const credentials = new msRest.ApiKeyCredentials({ inHeader: { "Training-key": trainingKey } });
const trainer = new TrainingApi.TrainingAPIClient(credentials, trainingEndpoint);
const predictor_credentials = new msRest.ApiKeyCredentials({ inHeader: { "Prediction-key": predictionKey } });
const predictor = new PredictionApi.PredictionAPIClient(predictor_credentials, predictionEndpoint);

建立新的自訂視覺專案

啟動新的函式，以包含所有的自訂視覺函式呼叫。新增下列程式碼，以建立新的自訂視覺服務專案。

(async () => {
    console.log("Creating project...");
    const sampleProject = await trainer.createProject("Sample Project");

將標記新增至專案

若要在專案中建立分類標記，請在函式中新增以下程式碼：

const hemlockTag = await trainer.createTag(sampleProject.id, "Hemlock");
const cherryTag = await trainer.createTag(sampleProject.id, "Japanese Cherry");

上傳並標記影像

首先，下載此專案的範例影像。將範例影像資料夾的內容儲存到您的本機裝置。

若要將範例影像新增到專案，在標記建立之後插入下列程式碼。此程式碼會上傳每個影像及其對應標記。

const sampleDataRoot = "Images";

console.log("Adding images...");
let fileUploadPromises = [];

const hemlockDir = `${sampleDataRoot}/Hemlock`;
const hemlockFiles = fs.readdirSync(hemlockDir);
hemlockFiles.forEach(file => {
    fileUploadPromises.push(trainer.createImagesFromData(sampleProject.id, fs.readFileSync(`${hemlockDir}/${file}`), { tagIds: [hemlockTag.id] }));
});

const cherryDir = `${sampleDataRoot}/Japanese_Cherry`;
const japaneseCherryFiles = fs.readdirSync(cherryDir);
japaneseCherryFiles.forEach(file => {
    fileUploadPromises.push(trainer.createImagesFromData(sampleProject.id, fs.readFileSync(`${cherryDir}/${file}`), { tagIds: [cherryTag.id] }));
});

await Promise.all(fileUploadPromises);

重要

您必須根據您下載 Azure AI 服務 Python SDK 範例存放庫的位置來變更影像sampleDataRoot的路徑（）。

為專案定型

此程式碼會建立預測模型的第一個反覆運算專案。

console.log("Training...");
let trainingIteration = await trainer.trainProject(sampleProject.id);

// Wait for training to complete
console.log("Training started...");
while (trainingIteration.status == "Training") {
    console.log("Training status: " + trainingIteration.status);
    await setTimeoutPromise(1000, null);
    trainingIteration = await trainer.getIteration(sampleProject.id, trainingIteration.id)
}
console.log("Training status: " + trainingIteration.status);

發佈目前的反覆項目

此程式碼會將定型的反覆運算發佈至預測端點。提供給已發佈反覆項目的名稱可用來傳送預測要求。在預測端點中無法取得反覆專案，直到它發佈為止。

// Publish the iteration to the end point
await trainer.publishIteration(sampleProject.id, trainingIteration.id, publishIterationName, predictionResourceId);

測試預測端點

若要將影像傳送到預測端點並擷取預測，請在函式新增以下程式碼。

const testFile = fs.readFileSync(`${sampleDataRoot}/Test/test_image.jpg`);

const results = await predictor.classifyImage(sampleProject.id, publishIterationName, testFile);

// Show results
console.log("Results:");
results.predictions.forEach(predictedResult => {
    console.log(`\t ${predictedResult.tagName}: ${(predictedResult.probability * 100.0).toFixed(2)}%`);
});

然後，關閉您的自訂視覺函式並加以呼叫。

})()

執行應用程式

使用快速入門檔案上使用 node 命令執行應用程式。

node index.js

應用程式的輸出應該會類似下列文字：

Creating project...
Adding images...
Training...
Training started...
Training status: Training
Training status: Training
Training status: Training
Training status: Completed
Results:
         Hemlock: 94.97%
         Japanese Cherry: 0.01%

接著，您可以確認測試影像 (位於<sampleDataRoot>/Test/) 是否已正確加上標記。您也可以返回自訂視覺網站，然後查看新建立專案的目前狀態。

如果您想要實作您自己的影像分類專案 (或改為嘗試物體偵測專案)，則建議您刪除此範例中的樹木識別專案。免費訂用帳戶可使用兩個自訂視覺專案。

在自訂視覺網站上，瀏覽至 [專案]，然後選取 [我的新專案] 底下的資源回收筒。

面板的螢幕擷取畫面，該面板標示為 [我的新專案] 並有資源回收筒圖示。

本指南說明如何在程序代碼中完成物件偵測程式的每個步驟。此範例會執行單一的訓練反覆項目，但您通常必須對模型進行多次訓練和測試，以便提升其精確度。

測試和重新定型模型

開始使用適用於 Python 的自訂視覺用戶端程式庫。請遵循下列步驟來安裝套件，並試用建立影像分類模型的程式碼範例。您將建立專案、新增標籤、將專案定型，並使用專案的預測端點 URL 以程式設計方式加以測試。請使用此範例作為自行建置影像辨識應用程式的範本。

注意

如果您想要在不撰寫程式代碼的情況下建置和定型分類模型，請參閱以瀏覽器為基礎的指引。

使用適用於 Python 的自訂視覺用戶端程式庫可執行下列作業：

建立新的自訂視覺專案
將標記新增至專案
上傳和標記影像
為專案定型
發佈目前的反覆項目
測試預測端點

參考文件 | 程式庫來源程式碼 | 套件 (PyPI) | 範例

必要條件

Azure 訂用帳戶。您可以免費建立一個訂用帳戶。
Python 3.x。
- 您安裝的 Python 應包含 pip。您可以在命令列上執行 pip --version 來檢查是否已安裝 pip。安裝最新版本的 Python 以取得 pip。
擁有 Azure 訂閱之後，在 Azure 入口網站中建立自訂視覺資源，以建立定型和預測資源。
- 您可以使用免費定價層 (F0) 來試用服務，之後可升級至付費層以用於實際執行環境。

建立環境變數

在此範例中，您會在執行應用程式的本機電腦上將認證寫入環境變數。

您可以在 Azure 入口網站中預測資源的 [屬性] 索引標籤上找到預測資源識別碼，該識別碼名為 [資源識別碼]。

提示

若要設定環境變數，請開啟主控台視窗，然後遵循作業系統和開發環境的指示進行。

若要設定 VISION_TRAINING KEY 環境變數，請以您的定型資源的其中一個金鑰取代 <your-training-key>。
若要設定 VISION_TRAINING_ENDPOINT 環境變數，請將 <your-training-endpoint> 取代為定型資源的端點。
若要設定 VISION_PREDICTION_KEY 環境變數，請以您的預測資源的其中一個金鑰取代 <your-prediction-key>。
若要設定 VISION_PREDICTION_ENDPOINT 環境變數，請將 <your-prediction-endpoint> 取代為預測資源的端點。
若要設定 VISION_PREDICTION_RESOURCE_ID 環境變數，請將 <your-resource-id> 取代為預測資源的資源識別碼。

重要

如果您使用 API 金鑰，請將其安全地儲存在別處，例如 Azure Key Vault。請勿在程式碼中直接包含 API 金鑰，且切勿公開張貼金鑰。

如需 AI 服務安全性的詳細資訊，請參閱驗證對 Azure AI 服務的要求 (英文)。

Windows
Linux

setx VISION_TRAINING_KEY <your-training-key>

setx VISION_TRAINING_ENDPOINT <your-training-endpoint>

setx VISION_PREDICTION_KEY <your-prediction-key>

setx VISION_PREDICTION_ENDPOINT <your-prediction-endpoint>

setx VISION_PREDICTION_RESOURCE_ID <your-resource-id>

新增環境變數之後，您可能需要重新啟動讀取環境變數的任何執行中程式，包括主控台視窗。

export VISION_TRAINING_KEY=<your-training-key>

export VISION_TRAINING_ENDPOINT=<your-training-endpoint>

export VISION_PREDICTION_KEY=<your-prediction-key>

export VISION_PREDICTION_ENDPOINT=<your-prediction-endpoint>

export VISION_PREDICTION_RESOURCE_ID=<your-resource-id>

新增環境變數之後，請從主控台視窗執行 source ~/.bashrc，讓變更生效。

設定

安裝用戶端程式庫

若要使用適用於 Python 的自訂視覺撰寫影像分析應用程式，您需要自訂視覺用戶端連結庫。安裝 Python 之後，請在 PowerShell 或主控台視窗中執行下列命令：

pip install azure-cognitiveservices-vision-customvision

建立新的 Python 應用程式

建立新的 Python 檔案，並匯入下列程式庫。

from azure.cognitiveservices.vision.customvision.training import CustomVisionTrainingClient
from azure.cognitiveservices.vision.customvision.prediction import CustomVisionPredictionClient
from azure.cognitiveservices.vision.customvision.training.models import ImageFileCreateBatch, ImageFileCreateEntry, Region
from msrest.authentication import ApiKeyCredentials
import os, time, uuid

提示

想要立刻檢視整個快速入門程式碼檔案嗎？您可以在 GitHub 上找到該檔案，其中包含本快速入門中的程式碼範例。

為資源的 Azure 端點和金鑰建立變數。

# retrieve environment variables
ENDPOINT = os.environ["VISION_TRAINING_ENDPOINT"]
training_key = os.environ["VISION_TRAINING_KEY"]
prediction_key = os.environ["VISION_PREDICTION_KEY"]
prediction_resource_id = os.environ["VISION_PREDICTION_RESOURCE_ID"]

物件模型

名稱	描述
CustomVisionTrainingClient	此類別會處理模型的建立、定型和發佈。
CustomVisionPredictionClient	此類別會處理您的模型查詢，以進行影像分類預測。
ImagePrediction	此類別會定義單一影像上的單一物件預測。其中包含物件識別碼和名稱的屬性、物件的周框方塊位置，以及信賴分數。

程式碼範例

這些程式碼片段說明如何使用適用於 Python 的自訂視覺用戶端程式庫來執行下列工作：

驗證用戶端
建立新的自訂視覺專案
將標記新增至專案
上傳和標記影像
為專案定型
發佈目前的反覆項目
測試預測端點

驗證用戶端

使用您的端點和金鑰將訓練具現化並預測用戶端。使用 ApiKeyServiceClientCredentials 密鑰建立物件，並將其與您的端點搭配使用，以建立 CustomVisionTrainingClient 和 CustomVisionPredictionClient 物件。

credentials = ApiKeyCredentials(in_headers={"Training-key": training_key})
trainer = CustomVisionTrainingClient(ENDPOINT, credentials)
prediction_credentials = ApiKeyCredentials(in_headers={"Prediction-key": prediction_key})
predictor = CustomVisionPredictionClient(ENDPOINT, prediction_credentials)

建立新的自訂視覺專案

在指令碼中新增下列程式碼，以建立新的自訂視覺服務專案。

當您建立專案時，請參閱 create_project 方法來指定其他選項 (如建置分類器 Web 入口網站指南中所述)。

publish_iteration_name = "classifyModel"

credentials = ApiKeyCredentials(in_headers={"Training-key": training_key})
trainer = CustomVisionTrainingClient(ENDPOINT, credentials)

# Create a new project
print ("Creating project...")
project_name = uuid.uuid4()
project = trainer.create_project(project_name)

將標記新增至專案

若要在專案中新增分類標記，請新增以下程式碼：

# Make two tags in the new project
hemlock_tag = trainer.create_tag(project.id, "Hemlock")
cherry_tag = trainer.create_tag(project.id, "Japanese Cherry")

上傳並標記影像

首先，下載此專案的範例影像。將範例影像資料夾的內容儲存到您的本機裝置。

若要將範例影像新增到專案，在標記建立之後插入下列程式碼。此程式碼會上傳每個影像及其對應標記。您最多可以在單一批次中上傳 64 個影像。

base_image_location = os.path.join (os.path.dirname(__file__), "Images")

print("Adding images...")

image_list = []

for image_num in range(1, 11):
    file_name = "hemlock_{}.jpg".format(image_num)
    with open(os.path.join (base_image_location, "Hemlock", file_name), "rb") as image_contents:
        image_list.append(ImageFileCreateEntry(name=file_name, contents=image_contents.read(), tag_ids=[hemlock_tag.id]))

for image_num in range(1, 11):
    file_name = "japanese_cherry_{}.jpg".format(image_num)
    with open(os.path.join (base_image_location, "Japanese_Cherry", file_name), "rb") as image_contents:
        image_list.append(ImageFileCreateEntry(name=file_name, contents=image_contents.read(), tag_ids=[cherry_tag.id]))

upload_result = trainer.create_images_from_files(project.id, ImageFileCreateBatch(images=image_list))
if not upload_result.is_batch_successful:
    print("Image batch upload failed.")
    for image in upload_result.images:
        print("Image status: ", image.status)
    exit(-1)

注意

您必須根據您下載 Azure AI 服務 Python SDK 範例存放庫的位置，變更影像的路徑。

為專案定型

此程式碼會建立預測模型的第一個反覆運算專案。

print ("Training...")
iteration = trainer.train_project(project.id)
while (iteration.status != "Completed"):
    iteration = trainer.get_iteration(project.id, iteration.id)
    print ("Training status: " + iteration.status)
    print ("Waiting 10 seconds...")
    time.sleep(10)

提示

使用選取的標記進行訓練

您可以選擇只在已套用的標記子集上進行訓練。您可以在尚未套用足夠的特定標記，但其他套用的標記已足夠時執行此操作。在train_project呼叫中，將選擇性參數selected_tags設定為您想要使用之標記的標識符字串清單。此模型將訓練為僅辨識該清單上的標記。

發佈目前的反覆項目

在預測端點中無法取得反覆專案，直到它發佈為止。下列程式碼會讓模型的目前反覆運算可供查詢。

# The iteration is now trained. Publish it to the project endpoint
trainer.publish_iteration(project.id, iteration.id, publish_iteration_name, prediction_resource_id)
print ("Done!")

測試預測端點

若要將影像傳送到預測端點並擷取預測，在檔案結尾處新增以下程式碼：

# Now there is a trained endpoint that can be used to make a prediction
prediction_credentials = ApiKeyCredentials(in_headers={"Prediction-key": prediction_key})
predictor = CustomVisionPredictionClient(ENDPOINT, prediction_credentials)

with open(os.path.join (base_image_location, "Test/test_image.jpg"), "rb") as image_contents:
    results = predictor.classify_image(
        project.id, publish_iteration_name, image_contents.read())

    # Display the results.
    for prediction in results.predictions:
        print("\t" + prediction.tag_name +
              ": {0:.2f}%".format(prediction.probability * 100))

執行應用程式

使用下列命令來執行應用程式：

python CustomVisionQuickstart.py

應用程式的輸出應該會類似下列文字：

Creating project...
Adding images...
Training...
Training status: Training
Training status: Completed
Done!
        Hemlock: 93.53%
        Japanese Cherry: 0.01%

接著，您可以確認測試影像 (位於 <base_image_location>/images/Test/) 的標記是否適當。您也可以返回自訂視覺網站，然後查看新建立專案的目前狀態。

清除資源

如果您想要實作您自己的影像分類專案 (或改為嘗試物體偵測專案)，則建議您刪除此範例中的樹木識別專案。免費訂用帳戶可使用兩個自訂視覺專案。

在自訂視覺網站上，瀏覽至 [專案]，然後選取 [我的新專案] 底下的資源回收筒。

面板的螢幕擷取畫面，該面板標示為 [我的新專案] 並有資源回收筒圖示。

現在您已經知道如何在程式碼中完成影像分類程序的每個步驟。此範例會執行單一的訓練反覆項目，但您通常必須對模型進行多次訓練和測試，以便提升其精確度。

測試和重新定型模型

什麼是自訂視覺服務？
此範例的原始程式碼位於 GitHub
SDK 參考文件

開始使用自訂視覺 REST API。請遵循這些步驟來呼叫 API，並建置影像分類模型。您將建立專案、新增標籤、將專案定型，並使用專案的預測端點 URL 以程式設計方式加以測試。請使用此範例作為自行建置影像辨識應用程式的範本。

注意

自訂視覺最容易透過用戶端程式庫 SDK，或透過瀏覽器架構的指導方針使用。

使用 REST API 的自訂視覺用戶端連結庫來：

建立新的自訂視覺專案
將標記新增至專案
上傳和標記影像
為專案定型
發佈目前的反覆項目
測試預測端點

必要條件

Azure 訂用帳戶。您可以免費建立一個訂用帳戶。
擁有 Azure 訂閱之後，在 Azure 入口網站中建立自訂視覺資源，以建立定型和預測資源。
- 您需要您建立的資源中的密鑰和端點，才能將應用程式連線到自訂視覺。您稍後會在快速入門中將金鑰和端點貼到程式碼中。
- 您可以使用免費定價層 (F0) 來試用服務，之後可升級至付費層以用於實際執行環境。
PowerShell 6.0 版以上，或類似的命令列應用程式。

建立新的自訂視覺專案

您將使用如下所示的命令來建立影像分類專案。所建立的專案會顯示在自訂視覺網站上。

curl -v -X POST -H "Training-key: {subscription key}" "https://{endpoint}/customvision/v3.3/Training/projects?name={name}"

將命令複製到文字編輯器，並進行下列變更：

將取代 {subscription key} 為您的有效金鑰。
將 {endpoint} 取代為對應至您金鑰的端點。

注意

2019 年 7 月 1 日之後建立的新資源會使用自訂的子網域名稱。如需詳細資訊和完整的區域端點清單，請參閱 Azure AI 服務的自訂子網域名稱。
將 {name} 取代為您的專案名稱。
選擇性地設定其他 URL 參數，以設定專案所使用的模型類型。如需選項，請參閱建立專案 API 。

如下列範例所示的 JSON 回應隨即出現。將專案的 "id" 值儲存至暫存位置。

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "description": "string",
  "settings": {
    "domainId": "00000000-0000-0000-0000-000000000000",
    "classificationType": "Multiclass",
    "targetExportPlatforms": [
      "CoreML"
    ],
    "useNegativeSet": true,
    "detectionParameters": "string",
    "imageProcessingSettings": {
      "augmentationMethods": {}
    }
  },
  "created": "string",
  "lastModified": "string",
  "thumbnailUri": "string",
  "drModeEnabled": true,
  "status": "Succeeded"
}

將標記新增至專案

使用下列命令來定義您將定型模型的標記。

curl -v -X POST -H "Training-key: {subscription key}" "https://{endpoint}/customvision/v3.3/Training/projects/{projectId}/tags?name={name}"

再次插入您自己的金鑰和端點 URL。
以您自己的專案識別碼取代 {projectId}。
請將 {name} 取代為您要使用的名稱。

針對您想要在專案中使用的所有標籤重複此流程。如果您使用的是所提供的範例影像，請新增 "Hemlock" 和 "Japanese Cherry" 標籤。

如下列範例所示的 JSON 回應隨即出現。將每個標籤的 "id" 值儲存至暫存位置。

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "description": "string",
  "type": "Regular",
  "imageCount": 0
}

上傳並標記影像

接下來，下載此專案的範例影像。將範例影像資料夾的內容儲存到您的本機裝置。

使用下列命令來上傳影像並套用標籤，一次用於「鐵杉」的影像，而其他分別用於「日本櫻花」的影像。如需更多選項，請參閱從資料建立影像 API。

curl -v -X POST -H "Content-Type: multipart/form-data" -H "Training-key: {subscription key}" "https://{endpoint}/customvision/v3.3/Training/projects/{projectId}/images?tagIds={tagArray}"
--data-ascii "{binary data}"

再次插入您自己的金鑰和端點 URL。
以您自己的專案識別碼取代 {projectId}。
使用標籤識別碼來取代 {tagArray}。
然後，使用您要標記之影像的二進位資料填入要求的主體。

為專案定型

這個方法會將模型定型在您上傳的標記影像上，並傳回目前專案反覆項目的標識碼。

curl -v -X POST -H "Content-Type: application/json" -H "Training-key: {subscription key}" "https://{endpoint}/customvision/v3.3/Training/projects/{projectId}/train"

再次插入您自己的金鑰和端點 URL。
以您自己的專案識別碼取代 {projectId}。
使用標籤識別碼來取代 {tagArray}。
然後，使用您要標記之影像的二進位資料填入要求的主體。
選用其他 URL 參數。如需選項資訊，請參閱定型專案 API。

提示

使用選取的標記進行訓練

您可以選擇只在已套用的標記子集上進行訓練。您可以在尚未套用足夠的特定標記，但其他套用的標記已足夠時執行此操作。將選用的 JSON 內容新增至要求的主體。以您要使用的標籤識別碼填入 "selectedTags" 陣列。

{
  "selectedTags": [
    "00000000-0000-0000-0000-000000000000"
  ]
}

JSON 回應包含已定型專案的相關資訊，包括反覆項目識別碼 ("id")。複製此值供下一個步驟使用。

{
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "string",
  "status": "string",
  "created": "string",
  "lastModified": "string",
  "trainedAt": "string",
  "projectId": "00000000-0000-0000-0000-000000000000",
  "exportable": true,
  "exportableTo": [
    "CoreML"
  ],
  "domainId": "00000000-0000-0000-0000-000000000000",
  "classificationType": "Multiclass",
  "trainingType": "Regular",
  "reservedBudgetInHours": 0,
  "trainingTimeInMinutes": 0,
  "publishName": "string",
  "originalPublishResourceId": "string"
}

發佈目前的反覆項目

此方法會讓模型的目前反覆運算可供查詢。您可以使用傳回的模型名稱作為參考，以傳送預測要求。

curl -v -X POST -H "Training-key: {subscription key}" "https://{endpoint}/customvision/v3.3/Training/projects/{projectId}/iterations/{iterationId}/publish?publishName={publishName}&predictionId={predictionId}"

再次插入您自己的金鑰和端點 URL。
以您自己的專案識別碼取代 {projectId}。
將 {iterationId} 取代為上一個步驟中所傳回的 ID。
以要指派給預測模型的名稱取代 {publishedName}。
以您自己的預測資源識別碼取代 {predictionId}。您可以在 Azure 入口網站中資源的 [屬性] 索引標籤上找到預測資源識別碼，該識別碼名為 [資源識別碼]。
選用其他 URL 參數。請參閱發佈反覆項目 API。

測試預測端點

最後，使用此命令測試您的已定型模型，方式是上傳新的影像，以使用標籤分類。您可以在稍早下載範例檔案的 [測試] 資料夾中使用映像。

curl -v -X POST -H "Training-key: {subscription key}" "https://{endpoint}/customvision/v3.3/Training/projects/{projectId}/iterations/{iterationId}/publish?publishName={publishName}&predictionId={predictionId}"

再次插入您自己的金鑰和端點 URL。
以您自己的專案識別碼取代 {projectId}。
將 {publishedName} 取代為上一個步驟中使用的名稱。
將本機影像的二進位資料新增至要求主體。
選用其他 URL 參數。請參閱分類影像 API。

傳回的 JSON 回應會列出模型套用至影像的每個標記，以及每個標記的機率分數。

{
  "id": "00000000-0000-0000-0000-000000000000",
  "project": "00000000-0000-0000-0000-000000000000",
  "iteration": "00000000-0000-0000-0000-000000000000",
  "created": "string",
  "predictions": [
    {
      "probability": 0.0,
      "tagId": "00000000-0000-0000-0000-000000000000",
      "tagName": "string",
      "boundingBox": {
        "left": 0.0,
        "top": 0.0,
        "width": 0.0,
        "height": 0.0
      },
      "tagType": "Regular"
    }
  ]
}

如果您想要實作您自己的影像分類專案 (或改為嘗試物體偵測專案)，則建議您刪除此範例中的樹木識別專案。免費訂用帳戶可使用兩個自訂視覺專案。

在自訂視覺網站上，瀏覽至 [專案]，然後選取 [我的新專案] 底下的資源回收筒。

面板的螢幕擷取畫面，該面板標示為 [我的新專案] 並有資源回收筒圖示。

現在，您已完成使用 REST API 執行影像分類流程的每個步驟。此範例會執行單一的訓練反覆項目，但您通常必須對模型進行多次訓練和測試，以便提升其精確度。

測試和重新定型模型

共用方式為

快速入門：使用 自訂視覺 SDK 或 REST API 建立影像分類專案

必要條件

建立環境變數

設定

建立新的 C# 應用程式

安裝用戶端程式庫

驗證用戶端

建立新的自訂視覺專案

將標記新增至專案

上傳並標記影像

為專案定型

發佈目前的反覆項目

測試預測端點

執行應用程式

清除資源

相關內容

必要條件

建立環境變數

設定

安裝自訂視覺用戶端程式庫

取得範例影像

建立自訂視覺專案

在專案中建立標記

上傳並標記影像

訓練及發佈專案

使用預測端點

執行應用程式

清除資源

相關內容

必要條件

建立環境變數

設定

建立新的 Gradle 專案

安裝用戶端程式庫

建立 Java 檔案

物件模型

程式碼範例

驗證用戶端

建立自訂視覺專案

將標記新增到您的專案

上傳並標記影像

為專案定型

發佈目前的反覆項目

測試預測端點

執行應用程式

清除資源

相關內容

必要條件

建立環境變數

設定

建立新的 Node.js 應用程式

安裝用戶端程式庫

物件模型

程式碼範例

驗證用戶端

建立新的自訂視覺專案

將標記新增至專案

上傳並標記影像

為專案定型

發佈目前的反覆項目

測試預測端點

執行應用程式

相關內容

必要條件

建立環境變數

設定

安裝用戶端程式庫

建立新的 Python 應用程式

物件模型

程式碼範例

驗證用戶端

建立新的自訂視覺專案

將標記新增至專案

上傳並標記影像

為專案定型

發佈目前的反覆項目

測試預測端點

執行應用程式

清除資源

快速入門：使用自訂視覺 SDK 或 REST API 建立影像分類專案