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

發行項
10/16/2024

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

注意

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

參考文件 | 程式庫原始程式碼 (定型) (預測) | 套件 (NuGet) (定型) (預測) | 範例

必要條件

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

建立環境變數

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

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

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

提示

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

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

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

重要

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

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

Windows
Linux

setx VISION_TRAINING_KEY your-training-key

setx VISION_TRAINING_ENDPOINT your-training-endpoint

setx VISION_PREDICTION_KEY your-prediction-key

setx VISION_PREDICTION_ENDPOINT your-prediction-endpoint

setx VISION_PREDICTION_RESOURCE_ID your-resource-id

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

export VISION_TRAINING_KEY=your-training-key

export VISION_TRAINING_ENDPOINT=your-training-endpoint

export VISION_PREDICTION_KEY=your-prediction-key

export VISION_PREDICTION_ENDPOINT=your-prediction-endpoint

export VISION_PREDICTION_RESOURCE_ID=your-resource-id

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

建立新的 C# 應用程式

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

安裝用戶端程式庫

建立新專案後，以滑鼠右鍵按一下 [方案總管] 中的專案解決方案，然後選取 [管理 NuGet 套件]，以安裝用戶端程式庫。在開啟的套件管理員中，選取 [瀏覽]、核取 [包含發行前版本]，然後搜尋 Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training 和 Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction。選取最新版本，然後選取 [安裝]。

建立新的 C# 應用程式

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

dotnet new console -n custom-vision-quickstart

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

dotnet build

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

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

安裝用戶端程式庫

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

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

提示

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

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

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

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

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

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

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

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

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

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

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

驗證用戶端

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

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

建立新的自訂視覺專案

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

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

將標記新增至專案

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

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

上傳並標記影像

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

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

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

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

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

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

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

}

為專案定型

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

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

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

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

提示

使用選取的標記進行訓練

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

發佈目前的反覆項目

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

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

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

測試預測端點

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

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

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

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

執行應用程式

Visual Studio IDE
CLI

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

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

dotnet run

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

Creating new project:
        Uploading images
        Training
Done!

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

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

清除資源

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

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

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

下一步

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

測試和重新定型模型

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

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

注意

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

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

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

參考文件 (訓練)(預測)

必要條件

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

建立環境變數

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

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

提示

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

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

重要

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

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

Windows
Linux

setx VISION_TRAINING_KEY your-training-key

setx VISION_TRAINING_ENDPOINT your-training-endpoint

setx VISION_PREDICTION_KEY your-prediction-key

setx VISION_PREDICTION_ENDPOINT your-prediction-endpoint

setx VISION_PREDICTION_RESOURCE_ID your-resource-id

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

export VISION_TRAINING_KEY=your-training-key

export VISION_TRAINING_ENDPOINT=your-training-endpoint

export VISION_PREDICTION_KEY=your-prediction-key

export VISION_PREDICTION_ENDPOINT=your-prediction-endpoint

export VISION_PREDICTION_RESOURCE_ID=your-resource-id

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

設定

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

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

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

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

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

取得範例影像

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

建立自訂視覺專案

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

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

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

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

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

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

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

    ctx = context.Background()

    trainer := training.New(training_key, endpoint)

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

在專案中建立標記

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

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

上傳並標記影像

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

注意

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

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

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

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

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

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

訓練及發佈專案

此程式碼會在預測模型中建立第一個反覆項目，然後將該反覆項目發佈至預測端點。提供給已發佈反覆項目的名稱可用來傳送預測要求。反覆項目要等到發佈後才可在預測端點中使用。

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

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

使用預測端點

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

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

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

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

執行應用程式

執行 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/) 的標記是否適當。您也可以返回自訂視覺網站，然後查看新建立專案的目前狀態。

清除資源

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

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

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

下一步

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

測試和重新定型模型

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

注意

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

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

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

參考文件 | 程式庫原始程式碼 (訓練) (預測)| 成品 (Maven) (訓練) (預測) | 範例

必要條件

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

建立環境變數

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

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

提示

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

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

重要

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

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

Windows
Linux

setx VISION_TRAINING_KEY your-training-key

setx VISION_TRAINING_ENDPOINT your-training-endpoint

setx VISION_PREDICTION_KEY your-prediction-key

setx VISION_PREDICTION_ENDPOINT your-prediction-endpoint

setx VISION_PREDICTION_RESOURCE_ID your-resource-id

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

export VISION_TRAINING_KEY=your-training-key

export VISION_TRAINING_ENDPOINT=your-training-endpoint

export VISION_PREDICTION_KEY=your-prediction-key

export VISION_PREDICTION_ENDPOINT=your-prediction-endpoint

export VISION_PREDICTION_RESOURCE_ID=your-resource-id

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

設定

建立新的 Gradle 專案

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

mkdir myapp && cd myapp

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

gradle init --type basic

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

安裝用戶端程式庫

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

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 Key Vault。如需詳細資訊，請參閱 Azure AI 服務安全性一文。

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

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

物件模型

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

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

程式碼範例

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

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

驗證用戶端

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

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

建立自訂視覺專案

建立新的自訂視覺專案

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

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

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

    return project;
}

將標記新增到您的專案

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

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

    Trainings trainer = trainClient.trainings();

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

上傳並標記影像

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

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

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

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

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

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

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

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

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

為專案定型

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

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

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

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

發佈目前的反覆項目

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

測試預測端點

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

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

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

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

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

執行應用程式

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

gradle build

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

gradle run

清除資源

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

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

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

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

下一步

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

測試和重新定型模型

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

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

注意

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

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

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

參考文件 (訓練)(預測)| 套件 (npm) (訓練)(預測) | 範例

必要條件

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

建立環境變數

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

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

提示

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

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

重要

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

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

Windows
Linux

setx VISION_TRAINING_KEY your-training-key

setx VISION_TRAINING_ENDPOINT your-training-endpoint

setx VISION_PREDICTION_KEY your-prediction-key

setx VISION_PREDICTION_ENDPOINT your-prediction-endpoint

setx VISION_PREDICTION_RESOURCE_ID your-resource-id

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

export VISION_TRAINING_KEY=your-training-key

export VISION_TRAINING_ENDPOINT=your-training-endpoint

export VISION_PREDICTION_KEY=your-prediction-key

export VISION_PREDICTION_ENDPOINT=your-prediction-endpoint

export VISION_PREDICTION_RESOURCE_ID=your-resource-id

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

設定

建立新的 Node.js 應用程式

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

mkdir myapp && cd myapp

執行命令 npm init，以使用 package.json 檔案建立節點應用程式。

npm init

安裝用戶端程式庫

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

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

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

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

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

提示

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

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

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

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

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

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

物件模型

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

程式碼範例

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

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

驗證用戶端

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

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

建立新的自訂視覺專案

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

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

將標記新增至專案

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

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

上傳並標記影像

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

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

const sampleDataRoot = "Images";

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

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

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

await Promise.all(fileUploadPromises);

重要

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

為專案定型

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

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

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

發佈目前的反覆項目

此程式碼會將定型的反覆運算發佈至預測端點。提供給已發佈反覆項目的名稱可用來傳送預測要求。反覆項目要等到發佈後才可在預測端點中使用。

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

測試預測端點

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

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

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

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

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

})()

執行應用程式

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

node index.js

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

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

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

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

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

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

下一步

測試和重新定型模型

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

注意

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

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

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

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

必要條件

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

建立環境變數

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

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

提示

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

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

重要

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

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

Windows
Linux

setx VISION_TRAINING_KEY your-training-key

setx VISION_TRAINING_ENDPOINT your-training-endpoint

setx VISION_PREDICTION_KEY your-prediction-key

setx VISION_PREDICTION_ENDPOINT your-prediction-endpoint

setx VISION_PREDICTION_RESOURCE_ID your-resource-id

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

export VISION_TRAINING_KEY=your-training-key

export VISION_TRAINING_ENDPOINT=your-training-endpoint

export VISION_PREDICTION_KEY=your-prediction-key

export VISION_PREDICTION_ENDPOINT=your-prediction-endpoint

export VISION_PREDICTION_RESOURCE_ID=your-resource-id

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

設定

安裝用戶端程式庫

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

pip install azure-cognitiveservices-vision-customvision

建立新的 Python 應用程式

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

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

提示

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

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

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

物件模型

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

程式碼範例

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

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

驗證用戶端

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

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

建立新的自訂視覺專案

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

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

publish_iteration_name = "classifyModel"

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

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

將標記新增至專案

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

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

上傳並標記影像

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

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

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

print("Adding images...")

image_list = []

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

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

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

注意

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

為專案定型

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

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

提示

使用選取的標記進行訓練

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

發佈目前的反覆項目

反覆項目要等到發佈後才可在預測端點中使用。下列程式碼會讓模型的目前反覆運算可供查詢。

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

測試預測端點

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

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

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

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

執行應用程式

執行 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/) 的標記是否適當。您也可以返回自訂視覺網站，然後查看新建立專案的目前狀態。

清除資源

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

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

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

下一步

測試和重新定型模型

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

開始使用自訂視覺 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} 取代您的有效 Face 金鑰。
將 {endpoint} 取代為對應至您金鑰的端點。

注意

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

您會收到如下的 JSON 回應。將專案的 "id" 值儲存至暫存位置。

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

將標記新增至專案

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

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

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

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

您會取得如下的 JSON 回應。將每個標籤的 "id" 值儲存至暫存位置。

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

上傳並標記影像

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

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

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

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

為專案定型

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

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

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

提示

使用選取的標記進行訓練

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

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

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

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

發佈目前的反覆項目

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

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

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

測試預測端點

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

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

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

傳回的 JSON 回應會針對包含套用至影像的模型列出每個標籤，以及每個標籤的可能性分數。

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

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

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

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

下一步

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

測試和重新定型模型

共用方式為

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

必要條件

建立環境變數

設定

建立新的 C# 應用程式

安裝用戶端程式庫

驗證用戶端

建立新的自訂視覺專案

將標記新增至專案

上傳並標記影像

為專案定型

發佈目前的反覆項目

測試預測端點

執行應用程式

清除資源

下一步

必要條件

建立環境變數

設定

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

取得範例影像

建立自訂視覺專案

在專案中建立標記

上傳並標記影像

訓練及發佈專案

使用預測端點

執行應用程式

清除資源

下一步

必要條件

建立環境變數

設定

建立新的 Gradle 專案

安裝用戶端程式庫

建立 Java 檔案

物件模型

程式碼範例

驗證用戶端

建立自訂視覺專案

將標記新增到您的專案

上傳並標記影像

為專案定型

發佈目前的反覆項目

測試預測端點

執行應用程式

清除資源

下一步

必要條件

建立環境變數

設定

建立新的 Node.js 應用程式

安裝用戶端程式庫

物件模型

程式碼範例

驗證用戶端

建立新的自訂視覺專案

將標記新增至專案

上傳並標記影像

為專案定型

發佈目前的反覆項目

測試預測端點

執行應用程式

下一步

必要條件

建立環境變數

設定

安裝用戶端程式庫

建立新的 Python 應用程式

物件模型

程式碼範例

驗證用戶端

建立新的自訂視覺專案

將標記新增至專案

上傳並標記影像

為專案定型

發佈目前的反覆項目

測試預測端點

執行應用程式

清除資源