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

開始使用 .NET 的 Custom Vision 客戶端函式庫。請依照以下步驟安裝套件，並試用建立影像分類模型的範例程式碼。你可以建立專案、新增標籤、訓練專案，並利用專案的預測端點網址來程式化測試。請以此範例作為打造自己影像辨識應用程式的範本。

註

如果你想建立並訓練 一個不 寫程式碼的分類模型，請參考瀏覽器指引。

參考文件 | 用於訓練和預測的函式庫原始碼 | 訓練和預測的套件 (NuGet) | 範例

先決條件

一個 Azure 訂閱。你可以免費創建一個。
Visual Studio IDE或目前版本的 .NET Core。
一旦你訂閱了Azure，請在Azure入口建立一個自訂視覺資源，建立訓練資源和預測資源。
- 你可以先用免費價格等級F0（）試用服務，之後再升級到付費等級以進行生產。

建立環境變數

在這個例子中，你會把憑證寫入執行該應用程式的本地機器上的環境變數。

前往 Azure 入口網站。如果您在前置條件區塊中建立的自訂願景資源成功部署，請選擇下一步步驟中的「前往資源」按鈕。你可以在資源的 「金鑰與端點 」頁面，在 資源管理下找到你的金鑰和端點。你需要取得訓練資源和預測資源的金鑰，以及 API 端點。

你可以在Azure入口網站預測資源的Properties分頁中找到預測資源 ID，標示為 Resource ID。

提示

您也可以使用 https://www.customvision.ai 來獲取這些數值。登入後，選擇右上角 的設定 圖示。在設定頁面，你可以查看所有金鑰、資源 ID 和端點。

要設定環境變數，請開啟主控台視窗，並依照作業系統和開發環境的指示操作。

若要設定 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>替換為你的預測資源的資源 ID。

重要

我們建議使用 Microsoft Entra ID 搭配 Azure 資源的受控身份驗證，以避免將憑證儲存在雲端執行的應用程式中。

使用 API 金鑰時要小心。不要直接把 API 金鑰放進程式碼裡，也絕對不要公開發佈。如果使用 API 金鑰，請將它們安全存放在 Azure Key Vault，定期更換金鑰，並透過基於角色的存取控制和網路存取限制來限制對 Azure Key Vault 的存取。欲了解更多如何在應用程式中安全使用 API 金鑰的資訊，請參見 API 金鑰搭配 Azure Key Vault。

如需了解更多有關 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 套件]，以安裝用戶端程式庫。在打開的套件管理器中選擇 Browse，然後勾選 Include prerelease，並搜尋 Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training 和 Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction。選擇最新版本，然後選擇安裝。

建立一個新的 C# 應用程式

在主控台視窗（例如 cmd、PowerShell 或 Bash）中，使用 dotnet new 指令建立一個名為 custom-vision-quickstart的主控台應用程式。此指令建立一個簡單的 Hello WorldC# 專案，僅有一個原始碼檔案：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;
}

建立新的客製化願景專案

接下來的程式碼會建立一個影像分類專案。所建立的專案會顯示在 Custom Vision 網站上。請參考 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");
}

上傳與標籤圖片

首先，下載本專案的範例圖片。將 sample 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 為你想使用的標籤的 ID 清單。模型會訓練只辨識該清單上的標籤。

發佈目前版本

此方法使模型的當前迭代可供查詢。你可以用模型名稱作為參考，來發送預測請求。你需要為 predictionResourceId 輸入自己的值。你可以在Azure入口網站的資源Properties標籤中找到預測資源 ID，標示為 Resource ID。

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/ 中）是否被正確標記。按任意鍵退出應用程式。你也可以回到 Custom Vision 網站，查看你新建立專案的現況。

清理資源

如果你想實作自己的影像分類專案（或嘗試物件偵測專案），建議刪除此範例中的樹識別專案。免費訂閱最多可進行兩個自訂視覺專案。

在 Custom Vision 網站，前往 Projects，選擇「我的新Project」下的垃圾桶。

標示為「我的新Project」面板的截圖，並附上垃圾桶圖示。

現在你已經看到物體偵測過程的每個步驟都可以用程式碼完成。這個範例執行一次訓練迭代，但通常你需要多次訓練和測試模型，才能讓它更準確。

測試與重新訓練模型

什麼是客製化視覺？
此範例的原始碼可在 GitHub
SDK 參考文件

本指南提供說明與範例程式碼，幫助您開始使用 Go 的 Custom Vision 用戶端函式庫來建立影像分類模型。你會建立專案、加入標籤、訓練專案，並利用專案的預測端點網址來程式化測試。請以此範例作為打造自己影像辨識應用程式的範本。

註

如果你想建立並訓練 一個不 寫程式碼的分類模型，請參考瀏覽器指引。

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

建立新的客製化願景專案
為專案新增標籤
上傳與標籤圖片
對專案進行訓練
發佈目前版本
測試預測端點

（訓練）及（預測）的參考文件

先決條件

一個 Azure 訂閱。你可以免費創建一個。
升級到 1.8 或更高版本。
一旦你有Azure訂閱，請在Azure入口建立一個自訂視覺資源，建立訓練與預測資源。
- 你可以先用免費價格等級F0（）試用服務，之後再升級到付費等級以進行生產。

建立環境變數

在這個例子中，你會把憑證寫入執行該應用程式的本地機器上的環境變數。

你可以在Azure入口網站預測資源的Properties分頁中找到預測資源 ID，標示為 Resource ID。

提示

您也可以使用 https://www.customvision.ai 來獲取這些數值。登入後，選擇右上角 的設定 圖示。在設定頁面，你可以查看所有金鑰、資源 ID 和端點。

要設定環境變數，請開啟主控台視窗，並依照作業系統和開發環境的指示操作。

若要設定 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>替換為你的預測資源的資源 ID。

重要

我們建議使用 Microsoft Entra ID 搭配 Azure 資源的受控身份驗證，以避免將憑證儲存在雲端執行的應用程式中。

如需了解更多有關 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 ，讓變更生效。

設定

安裝 Custom Vision 用戶端函式庫

要撰寫帶有 Custom Vision for Go 的影像分析應用程式，你需要 Custom Vision 服務客戶端函式庫。請在 PowerShell 中執行以下指令：

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

或者，如果你使用 dep，請在你的儲存庫中執行：

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

取得範例圖片

此範例使用了 Foundry Tools Python SDK Samples 倉庫中的圖片，該資料庫位於 GitHub。將此儲存庫複製或下載到您的開發環境中。記得它的資料夾位置，方便後續步驟使用。

創建自訂願景專案

在你偏好的專案目錄中建立一個名為 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 張圖片。

註

你需要根據你之前下載的 Foundry Tools 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/ 中>）是否被正確標記。你也可以回到 Custom Vision 網站，查看你新建立專案的現況。

清理資源

如果你想實作自己的影像分類專案（或嘗試物件偵測專案），建議刪除此範例中的樹識別專案。免費訂閱最多可進行兩個自訂視覺專案。

在 Custom Vision 網站，前往 Projects，選擇「我的新Project」下的垃圾桶。

標示為「我的新Project」面板的截圖，並附上垃圾桶圖示。

現在你已經看到物體偵測過程的每個步驟都可以用程式碼完成。這個範例執行一次訓練迭代，但通常你需要多次訓練和測試模型，才能讓它更準確。

測試與重新訓練模型

開始使用 Custom Vision 的 Java 用戶端函式庫來建立影像分類模型。請依照以下步驟安裝套件，並嘗試範例程式碼來執行基本任務。請以此範例作為打造自己影像辨識應用程式的範本。

註

如果你想建立並訓練 一個不 寫程式碼的分類模型，請參考瀏覽器指引。

使用 Custom Vision 用戶端函式庫用於 Java：

建立新的客製化願景專案
為專案新增標籤
上傳與標籤圖片
對專案進行訓練
發佈目前版本
測試預測端點

參考文件 | 用於 (訓練) 與 (預測) 的程式庫原始程式碼 | 用於 (訓練) 與 (預測) |樣本的成品 (Maven)

先決條件

一個 Azure 訂閱。你可以免費創建一個。
目前版本的 Java 開發套件（JDK）。
Gradle 建置工具，或其他相依管理工具。
一旦你有Azure訂閱，請在Azure入口建立一個自訂視覺資源，建立訓練與預測資源。
- 你可以先用免費價格等級F0（）試用服務，之後再升級到付費等級以進行生產。

建立環境變數

在這個例子中，你會把憑證寫入執行該應用程式的本地機器上的環境變數。

你可以在Azure入口網站預測資源的Properties分頁中找到預測資源 ID，標示為 Resource ID。

提示

您也可以使用 https://www.customvision.ai 來獲取這些數值。登入後，選擇右上角 的設定 圖示。在設定頁面，你可以查看所有金鑰、資源 ID 和端點。

要設定環境變數，請開啟主控台視窗，並依照作業系統和開發環境的指示操作。

若要設定 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>替換為你的預測資源的資源 ID。

重要

我們建議使用 Microsoft Entra ID 搭配 Azure 資源的受控身份驗證，以避免將憑證儲存在雲端執行的應用程式中。

如需了解更多有關 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，這些檔案在執行時用於建立與配置您的應用程式。

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 這類安全的憑證儲存和存取方式。更多資訊請參閱 Foundry Tools 安全性文章。

在應用程式的方法 main 中，新增此快速啟動中所用方法的呼叫。你之後會定義這些。

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

物件模型

以下的類別與介面處理了 Custom Vision Java 用戶端函式庫的一些主要功能。

名稱	描述
CustomVisionTrainingClient	這堂課負責你的模型的創建、訓練與發佈。
CustomVisionPredictionClient	這個類別負責查詢你的模型以進行影像分類預測。
影像預測	此類別定義單一影像上的單一預測。它包含物件 ID 與名稱的屬性，以及信心分數。

程式碼範例

這些程式碼片段展示了如何使用 Custom Vision 用戶端函式庫執行以下任務Java：

驗證客戶端
建立新的客製化願景專案
為專案新增標籤
上傳與標籤圖片
訓練專案
發佈目前版本
測試預測端點

驗證客戶端

在你的 main 方法中，利用端點和鍵數實例化訓練與預測客戶端。

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

建立自訂願景專案

這個方法創建了一個影像分類專案。建立的專案會出現在你先前造訪的 Custom Vision 網站上。請參考 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();
}

上傳與標籤圖片

首先，下載本專案的範例圖片。將 sample 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());
}

發佈目前版本

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 服務訂閱，可以刪除該資源或資源群組。刪除資源群組也會刪除與之相關的其他資源。

如果你想實作自己的影像分類專案（或嘗試物件偵測專案），建議刪除此範例中的樹識別專案。免費訂閱最多可進行兩個自訂視覺專案。

在 Custom Vision 網站，前往 Projects，選擇「我的新Project」下的垃圾桶。

標示為「我的新Project」面板的截圖，並附上垃圾桶圖示。

現在你已經看到物體偵測過程的每個步驟都可以用程式碼完成。這個範例執行一次訓練迭代，但通常你需要多次訓練和測試模型，才能讓它更準確。

測試與重新訓練模型

什麼是客製化視覺？
此範例的原始碼可在 GitHub

本指南提供說明與範例程式碼，幫助您開始使用 Custom Vision 用戶端函式庫，Node.js 建立影像分類模型。你可以建立專案、新增標籤、訓練專案，並利用專案的預測端點網址來程式化測試。請以此範例作為打造自己影像辨識應用程式的範本。

註

如果你想建立並訓練 一個不 寫程式碼的分類模型，請參考瀏覽器指引。

使用 Node.js 的 Custom Vision 客戶端函式庫來：

建立新的客製化願景專案
為專案新增標籤
上傳與標籤圖片
對專案進行訓練
發佈目前版本
測試預測端點

（訓練）與（預測）的參考文件 | 用於（訓練）與（預測）的 |

先決條件

一個 Azure 訂閱。你可以免費創建一個。
目前的 Node.js 版本。
一旦你有Azure訂閱，請在Azure入口建立一個自訂視覺資源，建立訓練與預測資源。
- 你可以先用免費價格等級F0（）試用服務，之後再升級到付費等級以進行生產。

建立環境變數

在這個例子中，你會把憑證寫入執行該應用程式的本地機器上的環境變數。

你可以在Azure入口網站預測資源的Properties分頁中找到預測資源 ID，標示為 Resource ID。

提示

您也可以使用 https://www.customvision.ai 來獲取這些數值。登入後，選擇右上角 的設定 圖示。在設定頁面，你可以查看所有金鑰、資源 ID 和端點。

要設定環境變數，請開啟主控台視窗，並依照作業系統和開發環境的指示操作。

若要設定 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>替換為你的預測資源的資源 ID。

重要

我們建議使用 Microsoft Entra ID 搭配 Azure 資源的受控身份驗證，以避免將憑證儲存在雲端執行的應用程式中。

如需了解更多有關 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

安裝用戶端函式庫

要撰寫帶有 Custom Vision for Node.js的影像分析應用程式，你需要 Custom Vision 的 npm 套件。要安裝它們，請在 PowerShell 中執行以下指令：

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

你的應用程式 package.json 檔案會更新依賴關係。

建立一個名為 index.js S 的檔案並匯入以下函式庫：

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	這個類別負責查詢你的模型以進行影像分類預測。
預測	此介面定義單一影像上的單一預測。它包含物件 ID 與名稱的屬性，以及信心分數。

程式碼範例

這些程式碼片段展示了如何使用 JavaScript 的 Custom Vision 用戶端函式庫完成以下任務：

驗證客戶端
建立新的客製化願景專案
為專案新增標籤
上傳與標籤圖片
訓練專案
發佈目前版本
測試預測端點

驗證客戶端

用你的端點和金鑰實例化客戶端物件。用你的金鑰建立一個 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");

上傳與標籤圖片

首先，下載本專案的範例圖片。將 sample 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);

重要

你需要根據你下載 Foundry Tools Python SDK Samples 倉庫的位置，更改圖片的路徑（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/ 中找到>）是否被正確標記。你也可以回到 Custom Vision 網站，查看你新建立專案的現況。

如果你想實作自己的影像分類專案（或嘗試物件偵測專案），建議刪除此範例中的樹識別專案。免費訂閱最多可進行兩個自訂視覺專案。

在 Custom Vision 網站，前往 Projects，選擇「我的新Project」下的垃圾桶。

標示為「我的新Project」面板的截圖，並附上垃圾桶圖示。

本指南說明物體偵測過程的每個步驟都可以用程式碼完成。這個範例執行一次訓練迭代，但通常你需要多次訓練和測試模型，才能讓它更準確。

測試與重新訓練模型

開始使用 Python 的 Custom Vision 客戶端函式庫。請依照以下步驟安裝套件，並試用建立影像分類模型的範例程式碼。你會建立專案、加入標籤、訓練專案，並利用專案的預測端點網址來程式化測試。請以此範例作為打造自己影像辨識應用程式的範本。

註

如果你想建立並訓練 一個不 寫程式碼的分類模型，請參考瀏覽器指引。

使用 Python 的 Custom Vision 用戶端函式庫來：

建立新的客製化願景專案
為專案新增標籤
上傳與標籤圖片
對專案進行訓練
發佈目前版本
測試預測端點

參考文件 | 函式庫原始碼 | 套件（PyPI） | Samples

先決條件

一個 Azure 訂閱。你可以免費創建一個。
Python 3.x。
- 你的Python安裝應該包含pip。你可以透過命令列執行 pip --version 來確認你有沒有安裝 PIP。安裝最新版本的 Python 來取得 PIP。
一旦你有Azure訂閱，請在Azure入口建立一個自訂視覺資源，建立訓練與預測資源。
- 你可以先用免費價格等級F0（）試用服務，之後再升級到付費等級以進行生產。

建立環境變數

在這個例子中，你會把憑證寫入執行該應用程式的本地機器上的環境變數。

你可以在Azure入口網站預測資源的Properties分頁中找到預測資源 ID，標示為 Resource ID。

提示

您也可以使用 https://www.customvision.ai 來獲取這些數值。登入後，選擇右上角 的設定 圖示。在設定頁面，你可以查看所有金鑰、資源 ID 和端點。

要設定環境變數，請開啟主控台視窗，並依照作業系統和開發環境的指示操作。

若要設定 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>替換為你的預測資源的資源 ID。

重要

我們建議使用 Microsoft Entra ID 搭配 Azure 資源的受控身份驗證，以避免將憑證儲存在雲端執行的應用程式中。

如需了解更多有關 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 ，讓變更生效。

設定

安裝用戶端函式庫

要用 Custom Vision for Python 撰寫影像分析應用程式，你需要 Custom Vision 客戶端函式庫。安裝 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"]
prediction_endpoint = os.environ["VISION_PREDICTION_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	這個類別負責查詢你的模型以進行影像分類預測。
影像預測	此類別定義單一影像上的單一物件預測。它包含物件 ID 與名稱、物件的邊界框位置，以及信心分數的屬性。

程式碼範例

這些程式碼片段展示了如何使用 Python 的 Custom Vision 用戶端函式庫來完成以下操作：

驗證客戶端
建立新的客製化願景專案
為專案新增標籤
上傳與標籤圖片
訓練專案
發佈目前版本
測試預測端點

驗證客戶端

使用您的端點和金鑰將訓練具現化並預測用戶端。用你的金鑰建立 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(prediction_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")

上傳與標籤圖片

首先，下載本專案的範例圖片。將 sample Images 資料夾的內容儲存到本地裝置。

要將範例圖片加入專案，請在標籤建立後插入以下程式碼。此程式碼會上傳每張圖片及其對應標籤。一次最多可以上傳 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)

註

你需要根據你下載 Foundry Tools 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 設為你想使用的標籤的 ID 字串清單。模型會訓練只辨識該清單上的標籤。

發佈目前版本

反覆項目要等到發佈後才可在預測端點中使用。以下程式碼使模型的當前迭代可供查詢。

# 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(prediction_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/ 中>）是否有適當標籤。你也可以回到 Custom Vision 網站，查看你新建立專案的現況。

清理資源

如果你想實作自己的影像分類專案（或嘗試物件偵測專案），建議刪除此範例中的樹識別專案。免費訂閱最多可進行兩個自訂視覺專案。

在 Custom Vision 網站，前往 Projects，選擇「我的新Project」下的垃圾桶。

標示為「我的新Project」面板的截圖，並附上垃圾桶圖示。

現在你已經看到影像分類流程的每個步驟都可以用程式碼完成。這個範例執行一次訓練迭代，但通常你需要多次訓練和測試模型，才能讓它更準確。

測試與重新訓練模型

什麼是客製化視覺？
此範例的原始碼可在 GitHub
SDK 參考文件

開始使用 Custom Vision REST API。請依照以下步驟呼叫 API，建立影像分類模型。你會建立專案、加入標籤、訓練專案，並利用專案的預測端點網址來程式化測試。請以此範例作為打造自己影像辨識應用程式的範本。

註

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

使用 REST API 的自訂視覺客戶端函式庫來：

建立新的客製化願景專案
為專案新增標籤
上傳與標籤圖片
對專案進行訓練
發佈目前版本
測試預測端點

先決條件

一個 Azure 訂閱。你可以免費創建一個。
一旦你有Azure訂閱，請在Azure入口建立一個自訂視覺資源，建立訓練與預測資源。
- 你需要從你建立的資源中取得金鑰和端點，才能將應用程式連接到自訂視覺。你會在快速入門後面把你的金鑰和端點貼到程式碼裡。
- 你可以先用免費價格等級F0（）試用服務，之後再升級到付費等級以進行生產。
PowerShell 6.0+ 版本，或類似的命令列應用程式。

建立新的客製化願景專案

你會使用類似以下指令來建立影像分類專案。所建立的專案會顯示在 Custom Vision 網站上。

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

將指令複製到文字編輯器，並進行以下修改：

替換 {subscription key} 成您的合法的金鑰。
用對應你金鑰的端點替換 {endpoint}。

註

2019 年 7 月 1 日後新增的資源將使用自訂子網域名稱。欲了解更多資訊及完整區域端點清單，請參閱 Foundry Tools 的自訂子網域名稱。
請用你的專案名稱來取代 {name} 。
可選擇性地設定其他 URL 參數，以設定專案使用的模型類型。請參閱 Create Project 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}"

同樣地，插入你自己的金鑰和端點網址。
用你自己的專案編號來取代 {projectId} 。
請將 {name} 替換為你想使用的標籤名稱。

對你想在專案中使用的所有標籤重複這個過程。如果你使用提供的範例圖片，請加上標籤 "Hemlock" 和 "Japanese Cherry"。

會出現類似以下範例的 JSON 回應。將每個標籤的"id"值儲存到臨時位置。

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

上傳與標籤圖片

接著，下載本專案的範例圖片。將 sample Images 資料夾的內容儲存到本地裝置。

請使用以下指令上傳圖片並套用標籤;一次用於「鐵杉」影像，另一次為「日本櫻桃」影像。更多選項請參閱「從資料建立影像」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}"

同樣地，插入你自己的金鑰和端點網址。
用你自己的專案編號來取代 {projectId} 。
用標籤的 ID 替換 {tagArray} 。
接著，在請求的正文中填滿你想標記的圖片的二進位資料。

對專案進行訓練

這個方法會根據你上傳的標籤圖片訓練模型，並回傳當前專案迭代的 ID。

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

同樣地，插入你自己的金鑰和端點網址。
用你自己的專案編號來取代 {projectId} 。
用標籤的 ID 替換 {tagArray} 。
接著，在請求的正文中填滿你想標記的圖片的二進位資料。
可選擇使用其他網址參數。請參閱 Train Project API 以獲得選項。

提示

使用選定的標籤進行訓練。

您可以選擇只在已套用的標記子集上進行訓練。如果您尚未套用足夠的特定標記，但已套用足夠的其他標記，則您可能需要執行此動作。在請求內容中加入可選的 JSON 內容。用你想用的標籤 ID 填充陣列。"selectedTags"

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

JSON 回應包含你訓練好的專案資訊，包括迭代 ID（"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}"

同樣地，插入你自己的金鑰和端點網址。
用你自己的專案編號來取代 {projectId} 。
用前一步回傳的 ID 來替換 {iterationId} 。
將 {publishedName} 替換為您想給預測模型指派的名稱。
用你自己的預測資源 ID 來取代 {predictionId} 。你可以在Azure入口網站的資源Properties標籤中找到預測資源 ID，標示為 Resource ID。
可選擇使用其他網址參數。請參閱發佈迭代 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}"

同樣地，插入你自己的金鑰和端點網址。
用你自己的專案編號來取代 {projectId} 。
請用你在前一步用的名字來替代 {publishedName} 。
將你本地映像檔的二進位資料加入請求本體。
可選擇使用其他網址參數。請參閱 Classify Image 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"
    }
  ]
}

如果你想實作自己的影像分類專案（或嘗試物件偵測專案），建議刪除此範例中的樹識別專案。免費訂閱最多可進行兩個自訂視覺專案。

在 Custom Vision 網站，前往 Projects，選擇「我的新Project」下的垃圾桶。

標示為「我的新Project」面板的截圖，並附上垃圾桶圖示。

現在你已經用 REST API 完成了影像分類的每一個步驟。這個範例執行一次訓練迭代，但通常你需要多次訓練和測試模型，才能讓它更準確。

測試與重新訓練模型

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-05-04

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

先決條件

建立環境變數

設定

建立一個新的 C# 應用程式

安裝用戶端函式庫

驗證客戶端

建立新的客製化願景專案

為專案新增標籤

上傳與標籤圖片

對專案進行訓練

發佈目前版本

測試預測端點

執行應用程式

清理資源

相關內容

先決條件

建立環境變數

設定

安裝 Custom Vision 用戶端函式庫

取得範例圖片

創建自訂願景專案

在專案中建立標籤

上傳與標籤圖片

培訓並發佈專案

使用預測端點

執行應用程式

清理資源

相關內容

先決條件

建立環境變數

設定

建立一個新的 Gradle 專案

安裝用戶端函式庫

建立一個 Java 檔案

物件模型

程式碼範例

驗證客戶端

建立自訂願景專案

為你的專案新增標籤

上傳與標籤圖片

對專案進行訓練

發佈目前版本

測試預測端點

執行應用程式

清理資源

相關內容

先決條件

建立環境變數

設定

建立新的 Node.js 應用程式

安裝用戶端函式庫

物件模型

程式碼範例

驗證客戶端

建立新的客製化願景專案

為專案新增標籤

上傳與標籤圖片

對專案進行訓練

發佈目前版本

測試預測端點

執行應用程式

相關內容

先決條件

建立環境變數

設定

安裝用戶端函式庫

建立一個新的 Python 應用程式

物件模型

程式碼範例

驗證客戶端

建立新的客製化願景專案

為專案新增標籤

上傳與標籤圖片

對專案進行訓練

發佈目前版本

測試預測端點

執行應用程式

清理資源

相關內容