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

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

注意

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

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

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

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

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • Visual Studio IDE 或目前版本的 .NET Core
  • 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立自訂視覺資源,以建立定型和預測資源及取得您的金鑰和端點。 部署完成後,按一下 [移至資源] 按鈕。
    • 您需要來自所建立資源的金鑰和端點,以將應用程式連線至自訂視覺。 您稍後會在快速入門中將金鑰和端點貼到下列程式碼中。
    • 您可以使用免費定價層 (F0) 來試用服務,之後可升級至付費層以用於實際執行環境。

設定

建立新的 C# 應用程式

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

安裝用戶端程式庫

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

提示

想要立刻檢視整個快速入門程式碼檔案嗎? 您可以在 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 方法中,為資源的金鑰和端點建立變數。 您也會宣告一些要在稍後使用的基本物件。

// You can obtain these values from the Keys and Endpoint page for your Custom Vision resource in the Azure Portal.
private static string trainingEndpoint = "PASTE_YOUR_CUSTOM_VISION_TRAINING_ENDPOINT_HERE";
private static string trainingKey = "PASTE_YOUR_CUSTOM_VISION_TRAINING_SUBSCRIPTION_KEY_HERE";
// You can obtain these values from the Keys and Endpoint page for your Custom Vision Prediction resource in the Azure Portal.
private static string predictionEndpoint = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_ENDPOINT_HERE";
private static string predictionKey = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_SUBSCRIPTION_KEY_HERE";
// You can obtain this value from the Properties page for your Custom Vision Prediction resource in the Azure Portal. See the "Resource ID" field. This typically has a value such as:
// /subscriptions/<your subscription ID>/resourceGroups/<your resource group>/providers/Microsoft.CognitiveServices/accounts/<your Custom Vision prediction resource name>
private static string predictionResourceId = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_RESOURCE_ID_HERE";

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;

重要

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

您可以在 Azure 入口網站中資源的 [ 屬性 ] 索引標籤上找到預測資源識別碼,並將其列為 資源識別碼

切記,完成時從程式碼中移除金鑰,且切勿公開發佈金鑰。 在生產環境中,請考慮使用安全的方式來儲存及存取您的認證。 如需詳細資訊,請參閱認知服務 安全性 文章。

在應用程式的 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);

物件模型

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

程式碼範例

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

驗證用戶端

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

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

上傳和標記影像

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

注意

您需要一組更廣泛的影像來完成訓練嗎? Trove 是 Microsoft Garage 專案,可讓您收集和購買影像集以供訓練使用。 收集影像之後,您可以下載影像,然後以一般方式將其匯入至自訂視覺專案。 如需深入了解,請造訪 Trove 頁面

然後定義 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}");
    }
}

執行應用程式

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

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

Creating new project:
        Uploading images
        Training
Done!

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

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

清除資源

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

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

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

後續步驟

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

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

注意

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

使用適用于 Go 的自訂視覺用戶端程式庫:

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

參考檔 (定型) (預測) |程式庫來源程式碼 (定型) (預測)

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • Go 1.8+
  • 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立自訂視覺資源,以建立定型和預測資源及取得您的金鑰和端點。 部署完成後,按一下 [移至資源] 按鈕。
    • 您需要來自所建立資源的金鑰和端點,以將應用程式連線至自訂視覺。 您稍後會在快速入門中將金鑰和端點貼到下列程式碼中。
    • 您可以使用免費定價層 (F0) 來試用服務,之後可升級至付費層以用於實際執行環境。

設定

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

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

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

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

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

取得範例影像

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

建立自訂視覺專案

建立名為 sample 的新檔案,並在慣用的程式碼編輯器中開啟

在指令碼中新增下列程式碼,以建立新的自訂視覺服務專案。 在適當的定義中插入訂用帳戶金鑰。 此外,請從自訂視覺網站的 [設定] 頁面取得您的 [端點 URL]。

當您建立專案時,請參閱 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 = "<your training key>"
    prediction_key string = "<your prediction key>"
    prediction_resource_id = "<your prediction resource id>"
    endpoint string = "<your endpoint URL>"
    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 個影像。

注意

您必須根據認知服務 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) 來試用服務,之後可升級至付費層以用於實際執行環境。

設定

建立新的 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 類別中,為資源的金鑰和端點建立變數。

final static String trainingApiKey = "PASTE_YOUR_CUSTOM_VISION_TRAINING_SUBSCRIPTION_KEY_HERE";
final static String trainingEndpoint = "PASTE_YOUR_CUSTOM_VISION_TRAINING_ENDPOINT_HERE";
final static String predictionApiKey = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_SUBSCRIPTION_KEY_HERE";
final static String predictionEndpoint = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_ENDPOINT_HERE";
final static String predictionResourceId = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_RESOURCE_ID_HERE";

重要

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

您可以在 Azure 入口網站中資源的 [ 屬性 ] 索引標籤上找到預測資源識別碼,並將其列為 資源識別碼

完成時,請記得從程式碼中移除金鑰,且不要公開張貼金鑰。 在生產環境中,請考慮使用安全的方式來儲存及存取您的認證。 如需詳細資訊,請參閱認知服務 安全性 文章。

在應用程式的 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();
}

上傳和標記影像

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

注意

您需要一組更廣泛的影像來完成訓練嗎? Trove 是 Microsoft Garage 專案,可讓您收集和購買影像集以供訓練使用。 收集影像之後,您可以下載影像,然後以一般方式將其匯入至自訂視覺專案。 如需深入了解,請造訪 Trove 頁面

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

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

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

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

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

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

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

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

為專案定型

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

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

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

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

發佈目前的反覆項目

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

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

測試預測端點

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

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

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

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

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

執行應用程式

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

gradle build

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

gradle run

清除資源

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

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

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

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

後續步驟

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

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

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

注意

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

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

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

參考文件 (訓練) (預測) | 程式庫原始程式碼 (訓練) (預測) | 套件 (npm) (訓練) (預測) | 範例

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • 最新版的 Node.js
  • 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立自訂視覺資源,以建立定型和預測資源及取得您的金鑰和端點。 部署完成後,按一下 [移至資源] 按鈕。
    • 您需要來自所建立資源的金鑰和端點,以將應用程式連線至自訂視覺。 您稍後會在快速入門中將金鑰和端點貼到下列程式碼中。
    • 您可以使用免費定價層 (F0) 來試用服務,之後可升級至付費層以用於實際執行環境。

設定

建立新的 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 端點和金鑰建立變數。

const trainingKey = "PASTE_YOUR_CUSTOM_VISION_TRAINING_SUBSCRIPTION_KEY_HERE";
const trainingEndpoint = "PASTE_YOUR_CUSTOM_VISION_TRAINING_ENDPOINT_HERE";
const predictionKey = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_SUBSCRIPTION_KEY_HERE";
const predictionResourceId = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_RESOURCE_ID_HERE";
const predictionEndpoint = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_ENDPOINT_HERE";

重要

前往 Azure 入口網站。 如果您在 [必要條件] 區段中建立的自訂視覺訓練資源已成功部署,請按一下 [後續步驟] 底下的 [前往資源] 按鈕。 您可以在資源的 金鑰和端點 頁面中找到您的金鑰和端點。

您可以在 Azure 入口網站中資源的 [ 屬性 ] 索引標籤上找到預測資源識別碼,並將其列為 資源識別碼

完成時,請記得從程式碼中移除金鑰,且不要公開張貼金鑰。 在生產環境中,請考慮使用安全的方式來儲存及存取您的認證。 如需詳細資訊,請參閱認知服務 安全性 文章。

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

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

上傳和標記影像

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

注意

您需要一組更廣泛的影像來完成訓練嗎? Trove 是 Microsoft Garage 專案,可讓您收集和購買影像集以供訓練使用。 收集影像之後,您可以下載影像,然後以一般方式將其匯入至自訂視覺專案。 如需深入了解,請造訪 Trove 頁面

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

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

重要

您必須根據認知服務 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) 來試用服務,之後可升級至付費層以用於實際執行環境。

設定

安裝用戶端程式庫

若要使用適用於 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 端點和訂用帳戶金鑰建立變數。

# Replace with valid values
ENDPOINT = "PASTE_YOUR_CUSTOM_VISION_TRAINING_ENDPOINT_HERE"
training_key = "PASTE_YOUR_CUSTOM_VISION_TRAINING_SUBSCRIPTION_KEY_HERE"
prediction_key = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_SUBSCRIPTION_KEY_HERE"
prediction_resource_id = "PASTE_YOUR_CUSTOM_VISION_PREDICTION_RESOURCE_ID_HERE"

重要

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

您可以在 Azure 入口網站中資源的 [ 屬性 ] 索引標籤上找到預測資源識別碼,並將其列為 資源識別碼

切記,完成時從程式碼中移除金鑰,且切勿公開發佈金鑰。 在生產環境中,請考慮使用安全的方式來儲存及存取您的認證。 如需詳細資訊,請參閱認知服務 安全性 文章。

物件模型

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

程式碼範例

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

驗證用戶端

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

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

上傳和標記影像

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

注意

您需要一組更廣泛的影像來完成訓練嗎? Trove 是 Microsoft Garage 專案,可讓您收集和購買影像集以供訓練使用。 收集影像之後,您可以下載影像,然後以一般方式將其匯入至自訂視覺專案。 如需深入了解,請造訪 Trove 頁面

若要將範例影像新增到專案,在標記建立之後插入下列程式碼。 此程式碼會上傳每個影像及其對應標記。 您最多可以在單一批次中上傳 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)

注意

您必須根據認知服務 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/ ) 的標記是否適當。 您也可以返回自訂視覺網站,然後查看新建立專案的目前狀態。

清除資源

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

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

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

後續步驟

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

開始使用自訂視覺 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 日之後建立的新資源會使用自訂的子網域名稱。 如需詳細資訊和完整的區域端點清單,請參閱認知服務的自訂子網域名稱

  • {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
}

上傳和標記影像

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

注意

您需要一組更廣泛的影像來完成訓練嗎? Trove 是 Microsoft Garage 專案,可讓您收集和購買影像集以供訓練使用。 收集影像之後,您可以下載影像,然後以一般方式將其匯入至自訂視覺專案。 如需深入了解,請造訪 Trove 頁面

使用下列命令來上傳影像並套用標籤,一次用於「鐵杉」的影像,而其他分別用於「日本櫻花」的影像。 如需更多選項,請參閱從資料建立影像 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 執行影像分類流程的每個步驟。 此範例會執行單一的訓練反覆項目,但您通常必須對模型進行多次訓練和測試,以便提升其精確度。