快速入門：使用自訂視覺客戶端連結庫或 REST API 建立影像分類專案

發行項
01/23/2024

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

注意

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

參考檔 |連結庫原始碼（訓練）（預測） |套件（NuGet）（訓練）（預測） | 範例

必要條件

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

建立環境變數

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

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

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

提示

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

警告

請勿將金鑰直接包含在您的程式代碼中，且絕不會公開發佈。如需更多驗證選項 (例如 Azure Key Vault)，請參閱 Azure 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 取代為預測資源的資源識別碼。

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 方法，以在建立專案時指定其他選項（如建置分類器入口網站指南中所述）。

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");
}

上傳並標記影像

首先，下載此專案的範例映射。將範例 Images 資料夾的內容儲存至本機裝置。

然後定義協助程式方法，以上傳此目錄中的影像。您可能需要編輯 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/）中已正確標記。按任意鍵以結束應用程式。您也可以返回自訂視覺網站，並查看新建立專案的目前狀態。

清除資源

如果您想要實作自己的影像分類專案（或改為嘗試物件偵測專案），您可以刪除此範例中的樹狀結構識別專案。免費訂用帳戶允許兩個自訂視覺專案。

在自訂視覺網站上，流覽至 [專案]，然後選取 [我的新專案] 底下的垃圾桶。

Screenshot of a panel labeled My New Project with a trash can icon.

下一步

現在您已在程式代碼中完成影像分類程式的每個步驟。此範例會執行單一定型反覆專案，但您通常需要多次定型和測試模型，才能使其更精確。

測試及重新定型模型

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

注意

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

使用適用於 [移至] 的自訂視覺用戶端連結庫：

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

參考文件 (定型)(預測)

必要條件

Azure 訂用帳戶 - 免費建立一個訂用帳戶
Go 1.8+
擁有 Azure 訂閱之後，在 Azure 入口網站中建立自訂視覺資源，以建立定型和預測資源。
- 您可以使用免費定價層（F0）來試用服務，稍後再升級至生產環境的付費層。

建立環境變數

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

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

提示

警告

請勿將金鑰直接包含在您的程式代碼中，且絕不會公開發佈。如需更多驗證選項 (例如 Azure Key Vault)，請參閱 Azure 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 取代為預測資源的資源識別碼。

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 方法，以在建立專案時指定其他選項（如建置分類器入口網站指南中所述）。

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("")
    }
}

執行應用程式

執行 sample.go。

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/）中已適當標記。您也可以返回自訂視覺網站，並查看新建立專案的目前狀態。

清除資源

如果您想要實作自己的影像分類專案（或改為嘗試物件偵測專案），您可以刪除此範例中的樹狀結構識別專案。免費訂用帳戶允許兩個自訂視覺專案。

在自訂視覺網站上，流覽至 [專案]，然後選取 [我的新專案] 底下的垃圾桶。

Screenshot of a panel labeled My New Project with a trash can icon.

下一步

現在您已瞭解如何在程序代碼中完成物件偵測程式的每個步驟。此範例會執行單一定型反覆專案，但您通常需要多次定型和測試模型，才能使其更精確。

測試及重新定型模型

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

注意

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

使用適用於 Java 的自訂視覺用戶端連結庫來：

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

參考檔 |連結庫原始碼（訓練）（預測）|成品（Maven）（訓練）（預測） | 範例

必要條件

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

建立環境變數

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

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

提示

警告

請勿將金鑰直接包含在您的程式代碼中，且絕不會公開發佈。如需更多驗證選項 (例如 Azure Key Vault)，請參閱 Azure 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 取代為預測資源的資源識別碼。

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。

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

您可以在 Azure 入口網站的 [資源標識符] 索引標籤上找到預測資源標識符，並列為 [資源標識符]。

重要

當您完成時，請記得從程式碼中移除密鑰，且絕不會公開發佈密鑰。針對生產環境，請使用安全的方式來儲存和存取您的認證，例如 Azure 金鑰保存庫。如需詳細資訊，請參閱 Azure AI 服務安全性一文。

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

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

物件模型

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

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

程式碼範例

這些代碼段示範如何使用適用於 Java 的自訂視覺客戶端連結庫來執行下列工作：

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

驗證用戶端

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

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

建立自訂視覺專案

T## 建立新的自訂視覺專案

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

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();
}

上傳並標記影像

首先，下載此專案的範例映射。將範例 Images 資料夾的內容儲存至本機裝置。

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());
}

發佈目前的反覆專案

這個方法可讓模型的目前反覆專案可供查詢。您可以使用模型名稱作為傳送預測要求的參考。您必須為輸入自己的值 predictionResourceId。您可以在 Azure 入口網站的 [資源標識符] 索引標籤上找到預測資源標識符，並列為 [資源標識符]。

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 服務訂用帳戶，則可以刪除資源或資源群組。刪除資源群組也會刪除與其相關聯的任何其他資源。

如果您想要實作自己的影像分類專案（或改為嘗試物件偵測專案），您可以刪除此範例中的樹狀結構識別專案。免費訂用帳戶允許兩個自訂視覺專案。

在自訂視覺網站上，流覽至 [專案]，然後選取 [我的新專案] 底下的垃圾桶。

Screenshot of a panel labeled My New Project with a trash can icon.

下一步

現在您已瞭解如何在程序代碼中完成影像分類程式的每個步驟。此範例會執行單一定型反覆專案，但您通常需要多次定型和測試模型，才能使其更精確。

測試及重新定型模型

什麼是自訂視覺？
您可以在 GitHub 上找到此範例的原始程式碼

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

注意

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

使用適用於 .NET 的自訂視覺用戶端連結庫來：

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

參考文件（訓練）（預測） |連結庫原始碼（訓練）（預測） |套件（npm）（訓練）（預測） | 範例

必要條件

Azure 訂用帳戶 - 免費建立一個訂用帳戶
目前版本的 Node.js
擁有 Azure 訂閱之後，在 Azure 入口網站中建立自訂視覺資源，以建立定型和預測資源。
- 您可以使用免費定價層（F0）來試用服務，稍後再升級至生產環境的付費層。

建立環境變數

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

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

提示

警告

請勿將金鑰直接包含在您的程式代碼中，且絕不會公開發佈。如需更多驗證選項 (例如 Azure Key Vault)，請參閱 Azure 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 取代為預測資源的資源識別碼。

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 檔案建立節點應用程式。

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");

上傳並標記影像

首先，下載此專案的範例映射。將範例 Images 資料夾的內容儲存至本機裝置。

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

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/）中<已適當標記。您也可以回到自訂視覺網站，並查看新建立專案的目前狀態。

如果您想要實作自己的影像分類專案（或改為嘗試物件偵測專案），您可以刪除此範例中的樹狀結構識別專案。免費訂用帳戶允許兩個自訂視覺專案。

在自訂視覺網站上，流覽至 [專案]，然後選取 [我的新專案] 底下的垃圾桶。

Screenshot of a panel labeled My New Project with a trash can icon.

下一步

測試及重新定型模型

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

注意

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

使用適用於 Python 的自訂視覺用戶端連結庫來：

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

參考文件 | 庫原始程式碼 | 套件（PyPI）範例 |

必要條件

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

建立環境變數

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

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

提示

警告

請勿將金鑰直接包含在您的程式代碼中，且絕不會公開發佈。如需更多驗證選項 (例如 Azure Key Vault)，請參閱 Azure 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 取代為預測資源的資源識別碼。

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方法來指定其他選項（如建置分類器入口網站指南中所述）。

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")

上傳並標記影像

首先，下載此專案的範例映射。將範例 Images 資料夾的內容儲存至本機裝置。

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))

執行應用程式

執行 CustomVisionQuickstart.py。

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/）中已正確標記。您也可以回到自訂視覺網站，並查看新建立專案的目前狀態。

清除資源

如果您想要實作自己的影像分類專案（或改為嘗試物件偵測專案），您可以刪除此範例中的樹狀結構識別專案。免費訂用帳戶允許兩個自訂視覺專案。

在自訂視覺網站上，流覽至 [專案]，然後選取 [我的新專案] 底下的垃圾桶。

Screenshot of a panel labeled My New Project with a trash can icon.

下一步

測試及重新定型模型

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

注意

自訂視覺最容易透過用戶端連結庫 SDK 或瀏覽器型指引使用。

使用適用於 .NET 的自訂視覺用戶端連結庫來：

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

必要條件

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 參數，以設定專案將使用的模型類型。如需選項，請參閱 CreatProject 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
}

上傳並標記影像

接下來，下載此專案的範例映射。將範例 Images 資料夾的內容儲存至本機裝置。

使用下列命令來上傳影像並套用標記;一次用於「Hemlock」影像，並分別用於「日本櫻桃」影像。如需更多選項，請參閱從數據 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} 為上一個步驟中傳回的標識碼。
將取代 {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"
    }
  ]
}

如果您想要實作自己的影像分類專案（或改為嘗試物件偵測專案），您可以刪除此範例中的樹狀結構識別專案。免費訂用帳戶允許兩個自訂視覺專案。

在自訂視覺網站上，流覽至 [專案]，然後選取 [我的新專案] 底下的垃圾桶。

Screenshot of a panel labeled My New Project with a trash can icon.

下一步

現在您已使用 REST API 完成影像分類程式的每個步驟。此範例會執行單一定型反覆專案，但您通常需要多次定型和測試模型，才能使其更精確。

測試及重新定型模型

快速入門：使用 自訂視覺 客戶端連結庫或 REST API 建立影像分類專案

必要條件

建立環境變數

設定

建立新的 C# 應用程式

安裝客戶端連結庫

驗證用戶端

建立新的自訂視覺專案

將標籤新增至專案

上傳並標記影像

將專案定型

發佈目前的反覆專案

測試預測端點

執行應用程式

清除資源

下一步

必要條件

建立環境變數

設定

安裝 自訂視覺 客戶端連結庫

取得範例影像

建立 自訂視覺專案

在專案中建立標記

上傳並標記影像

定型和發佈專案

使用預測端點

執行應用程式

清除資源

下一步

必要條件

建立環境變數

設定

建立新的 Gradle 專案

安裝客戶端連結庫

建立 Java 檔案

物件模型

程式碼範例

驗證用戶端

建立自訂視覺專案

將標籤新增至您的專案

上傳並標記影像

將專案定型

發佈目前的反覆專案

測試預測端點

執行應用程式

清除資源

下一步

必要條件

建立環境變數

設定

建立新的Node.js應用程式

安裝客戶端連結庫

物件模型

程式碼範例

驗證用戶端

建立新的自訂視覺專案

將標籤新增至專案

上傳並標記影像

將專案定型

發佈目前的反覆專案

測試預測端點

執行應用程式

下一步

必要條件

建立環境變數

設定

安裝客戶端連結庫

建立新的 Python 應用程式

物件模型

程式碼範例

驗證用戶端

建立新的自訂視覺專案

將標籤新增至專案

上傳並標記影像

將專案定型

發佈目前的反覆專案

測試預測端點

執行應用程式

清除資源

下一步

快速入門：使用自訂視覺客戶端連結庫或 REST API 建立影像分類專案

安裝自訂視覺客戶端連結庫

建立自訂視覺專案