快速入门：使用自定义视觉 SDK 进行图像分类 - Foundry Tools

入门使用 .NET 的自定义视觉客户端库。按照以下步骤安装包，并试用用于生成图像分类模型的示例代码。可以创建项目、添加标记、训练项目，并使用项目的预测终结点 URL 以编程方式对其进行测试。使用此示例作为用于生成自己的图像识别应用的模板。

注意

如果要在不编写代码 的情况下 生成和训练分类模型，请参阅基于浏览器的指南。

参考文档 | 训练和预测的库源代码 | 用于训练和预测的包（NuGet） | 样本

先决条件

一个 Azure 订阅。可以免费创建一个。
Visual Studio IDE 或当前版本的 .NET Core。
获得Azure订阅后，请在 Azure 门户中创建 Custom Vision 资源以创建训练资源和预测资源。
- 可以使用免费定价层（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。

重要

我们建议使用 Azure 资源的托管标识进行 Microsoft Entra ID 身份验证，以避免将凭据随云中运行的应用程序一起存储。

请谨慎使用 API 密钥。不要直接在代码中包括 API 密钥，并且从不公开发布。如果使用 API 密钥，请安全地将其存储在Azure 密钥保管库中，定期轮换密钥，并使用基于角色的访问控制和网络访问限制来限制对Azure 密钥保管库的访问。有关在应用中安全地使用 API 密钥的详细信息，请参阅 API 密钥和 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 ，使更改生效。

创建新的 C# 应用程序

使用Visual Studio创建新的 .NET Core 应用程序。

安装客户端库

创建新项目后，右键单击 解决方案资源管理器 中的项目解决方案并选择 Manage NuGet 包来安装客户端库。在打开的包管理器中选择 Browse，然后选中 Include 预发行版，然后搜索 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");
}

上传和标记图像

首先，下载此项目的示例映像。将 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%

然后，可以验证测试图像（在 图像/测试中找到）是否已正确标记。按任意键退出应用程序。还可以返回到自定义视觉网站并查看新创建项目的当前状态。

清理资源

如果想要实现自己的图像分类项目（或改为尝试对象检测项目），则可能需要从此示例中删除树标识项目。免费订阅可以创建两个自定义视觉服务项目。

在 Custom Vision 网站上，导航到 Projects 并选择“我的新Project”下的垃圾桶。

一个标记为“我的新项目”的面板的截图，带有垃圾桶图标。

现在，你已经了解了如何在代码中完成对象检测过程的每一步。此示例执行单个训练迭代，但通常需要多次训练和测试模型，以便使其更准确。

测试和重新训练模型

本指南提供说明和示例代码，帮助你开始使用适用于 Go 的自定义视觉客户端库来生成图像分类模型。你将创建一个项目、添加标记、训练项目，并使用项目的预测终结点 URL 以编程方式对其进行测试。使用此示例作为用于生成自己的图像识别应用的模板。

注意

如果要在不编写代码 的情况下 生成和训练分类模型，请参阅基于浏览器的指南。

使用适用于Go的自定义视觉客户端库来：

创建新的自定义视觉项目
向项目添加标记
上传和标记图像
训练该项目
发布当前迭代
测试预测终结点

参考文档：（训练）和（预测）

先决条件

一个 Azure 订阅。可以免费创建一个。
转到 1.8 或更高版本。
获得Azure订阅后，请在 Azure 门户中创建 Custom Vision 资源以创建训练和预测资源。
- 可以使用免费定价层（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。

重要

我们建议使用 Azure 资源的托管标识进行 Microsoft Entra ID 身份验证，以避免将凭据随云中运行的应用程序一起存储。

请谨慎使用 API 密钥。不要直接在代码中包括 API 密钥，并且从不公开发布。如果使用 API 密钥，请安全地将其存储在Azure 密钥保管库中，定期轮换密钥，并使用基于角色的访问控制和网络访问限制来限制对Azure 密钥保管库的访问。有关在应用中安全地使用 API 密钥的详细信息，请参阅 API 密钥和 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 ，使更改生效。

设置

安装自定义视觉客户端库

若要使用自定义视觉 for Go 编写图像分析应用，需要自定义视觉服务客户端库。在 PowerShell 中运行以下命令：

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

或者，如果使用 dep，请在存储库中运行：

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

获取示例图像

此示例使用 GitHub 上的 Foundry Tools 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 张图像。

注意

需要根据之前下载 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 网站上，导航到 Projects 并选择“我的新Project”下的垃圾桶。

一个标记为“我的新项目”的面板的截图，带有垃圾桶图标。

现在，你已经了解了如何在代码中完成对象检测过程的每一步。此示例执行单个训练迭代，但通常需要多次训练和测试模型，以便使其更准确。

测试和重新训练模型

开始使用用于Java的自定义视觉客户端库来生成图像分类模型。按照以下步骤安装包并试用基本任务的示例代码。使用此示例作为用于生成自己的图像识别应用的模板。

注意

如果要在不编写代码 的情况下 生成和训练分类模型，请参阅基于浏览器的指南。

使用自定义视觉Java客户端库来：

创建新的自定义视觉项目
向项目添加标记
上传和标记图像
训练该项目
发布当前迭代
测试预测终结点

参考文档 | （训练）和（预测）的库源代码| （训练）和（预测）的构件（Maven） | 示例

先决条件

一个 Azure 订阅。可以免费创建一个。
Java开发工具包（JDK）的当前版本。
Gradle 生成工具或其他依赖项管理器。
获得Azure订阅后，请在 Azure 门户中创建 Custom Vision 资源以创建训练和预测资源。
- 可以使用免费定价层（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。

重要

我们建议使用 Azure 资源的托管标识进行 Microsoft Entra ID 身份验证，以避免将凭据随云中运行的应用程序一起存储。

请谨慎使用 API 密钥。不要直接在代码中包括 API 密钥，并且从不公开发布。如果使用 API 密钥，请安全地将其存储在Azure 密钥保管库中，定期轮换密钥，并使用基于角色的访问控制和网络访问限制来限制对Azure 密钥保管库的访问。有关在应用中安全地使用 API 密钥的详细信息，请参阅 API 密钥和 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 密钥保管库。有关详细信息，请参阅 Foundry 工具安全文章。

在应用程序的 main 方法中，添加对本快速入门中使用的方法的调用。稍后将定义这些内容。

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

对象模型

以下类和接口处理自定义视觉Java客户端库的某些主要功能。

名字	描述
CustomVisionTrainingClient	此类处理模型的创建、训练和发布。
CustomVisionPredictionClient	此类处理用于图像分类预测的模型查询。
ImagePrediction	此类定义对单一图像的单一预测。它包括对象 ID 和名称的属性以及置信度分数。

代码示例

这些代码片段演示如何使用用于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();
}

上传和标记图像

首先，下载此项目的示例映像。将 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());
}

发布当前迭代

此方法使模型的当前迭代可用于查询。可以使用模型名称作为发送预测请求的引用。需要为 predictionResourceId 输入自己的值。可以在Azure门户的资源Properties选项卡上找到预测资源 ID，列为Resource ID。

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”下的垃圾桶。

一个标记为“我的新项目”的面板的截图，带有垃圾桶图标。

现在，你已经了解了如何在代码中完成对象检测过程的每一步。此示例执行单个训练迭代，但通常需要多次训练和测试模型，以便使其更准确。

测试和重新训练模型

什么是自定义视觉？
可以在 GitHub

本指南提供说明和示例代码，帮助你开始使用自定义视觉客户端库来生成图像分类模型 Node.js。可以创建项目、添加标记、训练项目，并使用项目的预测终结点 URL 以编程方式对其进行测试。使用此示例作为用于生成自己的图像识别应用的模板。

注意

如果要在不编写代码 的情况下 生成和训练分类模型，请参阅基于浏览器的指南。

使用用于 Node.js 的自定义视觉客户端库可以：

创建新的自定义视觉项目
向项目添加标记
上传和标记图像
训练该项目
发布当前迭代
测试预测终结点

（训练）和（预测）的参考文档 | （训练）和（预测） | 示例的包 (npm)

先决条件

一个 Azure 订阅。可以免费创建一个。
Node.js 的当前版本。
获得Azure订阅后，请在 Azure 门户中创建 Custom Vision 资源以创建训练和预测资源。
- 可以使用免费定价层（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。

重要

我们建议使用 Azure 资源的托管标识进行 Microsoft Entra ID 身份验证，以避免将凭据随云中运行的应用程序一起存储。

请谨慎使用 API 密钥。不要直接在代码中包括 API 密钥，并且从不公开发布。如果使用 API 密钥，请安全地将其存储在Azure 密钥保管库中，定期轮换密钥，并使用基于角色的访问控制和网络访问限制来限制对Azure 密钥保管库的访问。有关在应用中安全地使用 API 密钥的详细信息，请参阅 API 密钥和 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

安装客户端库

若要使用用于 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	此类处理用于图像分类预测的模型查询。
预测	此接口功能定义对单个图像的单次预测。它包括对象 ID 和名称的属性以及置信度分数。

代码示例

这些代码片段演示如何使用适用于 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");

上传和标记图像

首先，下载此项目的示例映像。将 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 示例存储库的位置更改图像的路径（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 网站上，导航到 Projects 并选择“我的新Project”下的垃圾桶。

一个标记为“我的新项目”的面板的截图，带有垃圾桶图标。

本指南演示如何在代码中完成对象检测过程的每一步。此示例执行单个训练迭代，但通常需要多次训练和测试模型，以便使其更准确。

测试和重新训练模型

入门使用适用于 Python 的自定义视觉客户端库。按照以下步骤安装包，并试用用于生成图像分类模型的示例代码。你将创建一个项目、添加标记、训练项目，并使用项目的预测终结点 URL 以编程方式对其进行测试。使用此示例作为用于生成自己的图像识别应用的模板。

注意

如果要在不编写代码 的情况下 生成和训练分类模型，请参阅基于浏览器的指南。

使用 Python 的自定义视觉客户端库以便：

创建新的自定义视觉项目
向项目添加标记
上传和标记图像
训练该项目
发布当前迭代
测试预测终结点

参考文档 | 库源代码 | 软件包 | 示例

先决条件

一个 Azure 订阅。可以免费创建一个。
Python 3.x。
- Python安装应包括 pip。可以通过在命令行上运行 pip --version 来检查是否安装了 pip。通过安装最新版本的 Python 获取 pip。
获得Azure订阅后，请在 Azure 门户中创建 Custom Vision 资源以创建训练和预测资源。
- 可以使用免费定价层（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。

重要

我们建议使用 Azure 资源的托管标识进行 Microsoft Entra ID 身份验证，以避免将凭据随云中运行的应用程序一起存储。

请谨慎使用 API 密钥。不要直接在代码中包括 API 密钥，并且从不公开发布。如果使用 API 密钥，请安全地将其存储在Azure 密钥保管库中，定期轮换密钥，并使用基于角色的访问控制和网络访问限制来限制对Azure 密钥保管库的访问。有关在应用中安全地使用 API 密钥的详细信息，请参阅 API 密钥和 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 ，使更改生效。

设置

安装客户端库

若要使用用于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"]
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	此类处理用于图像分类预测的模型查询。
ImagePrediction	此类定义单一图像上的单一对象预测。它包括对象 ID 和名称的属性、对象的边界框位置以及置信度分数。

代码示例

这些代码片段演示如何使用用于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(prediction_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")

上传和标记图像

首先，下载此项目的示例映像。将 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 网站上，导航到 Projects 并选择“我的新Project”下的垃圾桶。

一个标记为“我的新项目”的面板的截图，带有垃圾桶图标。

现在，你已经了解了如何在代码中完成图像分类过程的每一步。此示例执行单个训练迭代，但通常需要多次训练和测试模型，以便使其更准确。

测试和重新训练模型

开始使用自定义视觉 REST API。按照以下步骤调用 API 并生成图像分类模型。你将创建一个项目、添加标记、训练项目，并使用项目的预测终结点 URL 以编程方式对其进行测试。使用此示例作为用于生成自己的图像识别应用的模板。

注意

自定义视觉可通过客户端库 SDK 或基于浏览器的指南轻松使用。

使用 REST API 的自定义视觉客户端库可以：

创建新的自定义视觉项目
向项目添加标记
上传和标记图像
训练该项目
发布当前迭代
测试预测终结点

先决条件

一个 Azure 订阅。可以免费创建一个。
获得Azure订阅后，请在 Azure 门户中创建 Custom Vision 资源以创建训练和预测资源。
- 要将您的应用程序连接到 Custom Vision，您需要从创建的资源中获取密钥和终结点。稍后将在快速入门中将密钥和终结点粘贴到代码中。
- 可以使用免费定价层（F0）试用该服务，稍后升级到生产付费层。
PowerShell 版本 6.0+ 或类似的命令行应用程序。

创建新的自定义视觉项目

你将使用如下所示的命令来创建图像分类项目。创建的项目将显示在自定义视觉网站上。

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

将命令复制到文本编辑器并进行以下更改：

将 {subscription key} 替换为有效密钥。
将 {endpoint} 替换为与密钥对应的终结点。

注意

2019 年 7 月 1 日之后创建的新资源将使用自定义子域名称。有关详细信息和区域终结点的完整列表，请参阅 Foundry 工具的自定义子域名称。
将 {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}"

同样，插入自己的密钥和终结点 URL。
将 {projectId} 替换为您自己的项目 ID。
将 {name} 替换为你想要使用的标签的名称。

对项目中使用的所有标记重复此过程。如果使用提供的示例图像，请添加标记 "Hemlock" 和 "Japanese Cherry"。

将显示类似于以下示例的 JSON 响应。将 "id" 每个标记的值保存到临时位置。

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

上传和标记图像

接下来，下载此项目的示例映像。将 sample Images 文件夹的内容保存到本地设备。

使用以下命令上传图像并应用标记;一次用于“Hemlock”图像，并单独用于“日本樱桃”图像。有关更多选项，请参阅 “从数据 API 创建映像 ”。

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

同样，插入自己的密钥和终结点 URL。
将 {projectId} 替换为您自己的项目 ID。
将{tagArray}替换为标签的ID。
然后，使用要标记的图像的二进制数据填充请求的正文。

训练该项目

此方法根据上传的标记图像训练模型，并返回当前项目迭代的 ID。

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} 替换为您自己的项目 ID。
将{tagArray}替换为标签的ID。
然后，使用要标记的图像的二进制数据填充请求的正文。
（可选）使用其他 URL 参数。有关选项，请参阅 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}"

同样，插入自己的密钥和终结点 URL。
将 {projectId} 替换为您自己的项目 ID。
将 {iterationId} 替换为上一步中返回的 ID。
将 {publishedName} 替换为您想分配给预测模型的名称。
将 {predictionId} 替换为你自己的预测资源 ID。可以在Azure门户的资源Properties选项卡上找到预测资源 ID，列为Resource ID。
（可选）使用其他 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} 替换为您自己的项目 ID。
将 {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"
    }
  ]
}

如果想要实现自己的图像分类项目（或改为尝试对象检测项目），则可能需要从此示例中删除树标识项目。免费订阅可以创建两个自定义视觉服务项目。

在 Custom Vision 网站上，导航到 Projects 并选择“我的新Project”下的垃圾桶。

一个标记为“我的新项目”的面板的截图，带有垃圾桶图标。

现在，你已使用 REST API 完成图像分类过程的每一步。此示例执行单个训练迭代，但通常需要多次训练和测试模型，以便使其更准确。

测试和重新训练模型

快速入门：使用自定义视觉 SDK 或 REST API 创建图像分类项目

先决条件

创建环境变量

设置

创建新的 C# 应用程序

安装客户端库

对客户端进行身份验证

创建新的自定义视觉项目

向项目添加标记

上传和标记图像

训练该项目

发布当前迭代

测试预测终结点

运行应用程序

清理资源

相关内容

先决条件

创建环境变量

设置

安装自定义视觉客户端库

获取示例图像

创建自定义视觉项目

在项目中创建标记

上传和标记图像

训练并发布项目

使用预测终结点

运行应用程序

清理资源

相关内容

先决条件

创建环境变量

设置

创建新的 Gradle 项目

安装客户端库

创建Java文件

对象模型

代码示例

对客户端进行身份验证

创建自定义视觉项目

向项目添加标签

上传和标记图像

训练该项目

发布当前迭代

测试预测终结点

运行应用程序

清理资源

相关内容

先决条件

创建环境变量

设置

创建新的 Node.js 应用程序

安装客户端库

对象模型

代码示例

对客户端进行身份验证

创建新的自定义视觉项目

向项目添加标记

上传和标记图像

训练该项目

发布当前迭代

测试预测终结点

运行应用程序

相关内容

先决条件

创建环境变量

设置

安装客户端库

创建新的Python应用程序

对象模型

代码示例

对客户端进行身份验证

创建新的自定义视觉项目

向项目添加标记

上传和标记图像

训练该项目

发布当前迭代

测试预测终结点

运行应用程序

清理资源

相关内容