你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

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

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

注意

若要在不编写代码的情况下构建和训练分类模型，请改为参阅基于浏览器的指南。

参考文档 | 库源代码（训练）（预测） | 包 (NuGet)（训练）（预测） | 示例

先决条件

• Azure 订阅 - 免费创建订阅
• Visual Studio IDE 或最新版本的 .NET Core。
• 拥有 Azure 订阅后，请在 Azure 门户中创建自定义视觉资源，以创建训练和预测资源。
  • 可以使用免费定价层 (F0) 试用该服务，然后再升级到付费层进行生产。

创建环境变量

在此示例中，你将凭据写入运行应用程序的本地计算机上的环境变量。

转到 Azure 门户。 如果在“先决条件”部分中创建的自定义视觉资源已成功部署，请选择“后续步骤”下的“转到资源”按钮。 在资源的“密钥和终结点”页的“资源管理”下可以找到密钥和终结点。 你需要获取培训资源和预测资源这两者的密钥，以及 API 终结点。

可以在 Azure 门户中预测资源的“属性”选项卡上找到列为“资源 ID”的预测资源 ID。

提示

还可以使用 https://www.customvision.ai/ 来获取这些值。 登录后，请选择右上角的“设置”图标。 在“设置”页上，可以查看所有密钥、资源 ID 和终结点。

注意

请不要直接在代码中包含密钥，并且绝不公开发布密钥。 有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要设置环境变量，请打开控制台窗口，按照操作系统和开发环境的说明进行操作。

1. 若要设置 VISION_TRAINING KEY 环境变量，请将 your-training-key 替换为训练资源的其中一个密钥。
2. 若要设置 VISION_TRAINING_ENDPOINT 环境变量，请将 your-training-endpoint 替换为训练资源的终结点。
3. 若要设置 VISION_PREDICTION_KEY 环境变量，请将 your-prediction-key 替换为预测资源的其中一个密钥。
4. 若要设置 VISION_PREDICTION_ENDPOINT 环境变量，请将 your-prediction-endpoint 替换为预测资源的终结点。
5. 若要设置 VISION_PREDICTION_RESOURCE_ID 环境变量，请将 your-resource-id 替换为预测资源的资源 ID。

Windows

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

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

Linux

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，使更改生效。

设置

Visual Studio IDE

新建 C# 应用程序

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

安装客户端库

创建新项目后，右键单击“解决方案资源管理器”中的项目解决方案，然后选择“管理 NuGet 包”，以安装客户端库 。 在打开的包管理器中，选择“浏览”，选中“包括预发行版”并搜索 Microsoft.Azure.CognitiveServices.Vision.CustomVision.Training 和 Microsoft.Azure.CognitiveServices.Vision.CustomVision.Prediction 。 选择最新版本，然后选择“安装”。

CLI

新建 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 属性设置为要使用的标记的 ID 列表。 模型将训练成只识别该列表中的标记。

发布当前迭代

此方法使模型的当前迭代可用于查询。 可以将模型名称用作发送预测请求的引用。 需要为 predictionResourceId 输入自己的值。 可以在 Azure 门户中资源的“属性”选项卡上找到列为“资源 ID”的预测资源 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

单击 IDE 窗口顶部的“调试”按钮，运行应用程序。

CLI

从应用程序目录使用 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 门户。 如果在“先决条件”部分中创建的自定义视觉资源已成功部署，请选择“后续步骤”下的“转到资源”按钮。 在资源的“密钥和终结点”页的“资源管理”下可以找到密钥和终结点。 你需要获取培训资源和预测资源这两者的密钥，以及 API 终结点。

可以在 Azure 门户中预测资源的“属性”选项卡上找到列为“资源 ID”的预测资源 ID。

提示

还可以使用 https://www.customvision.ai/ 来获取这些值。 登录后，请选择右上角的“设置”图标。 在“设置”页上，可以查看所有密钥、资源 ID 和终结点。

注意

请不要直接在代码中包含密钥，并且绝不公开发布密钥。 有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要设置环境变量，请打开控制台窗口，按照操作系统和开发环境的说明进行操作。

1. 若要设置 VISION_TRAINING KEY 环境变量，请将 your-training-key 替换为训练资源的其中一个密钥。
2. 若要设置 VISION_TRAINING_ENDPOINT 环境变量，请将 your-training-endpoint 替换为训练资源的终结点。
3. 若要设置 VISION_PREDICTION_KEY 环境变量，请将 your-prediction-key 替换为预测资源的其中一个密钥。
4. 若要设置 VISION_PREDICTION_ENDPOINT 环境变量，请将 your-prediction-endpoint 替换为预测资源的终结点。
5. 若要设置 VISION_PREDICTION_RESOURCE_ID 环境变量，请将 your-resource-id 替换为预测资源的资源 ID。

Windows

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

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

Linux

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/中找到）是否已正确标记。 也可返回到自定义视觉网站，查看新创建项目的当前状态。

清理资源

如果你希望实现自己的图像分类项目（或改为尝试对象检测项目），可能希望从此示例中删除树识别项目。 免费订阅允许创建两个自定义视觉项目。

在自定义视觉网站上，导航到“项目”，然后在“我的新项目”下选择垃圾桶。

后续步骤

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

测试和重新训练模型

• 什么是自定义视觉？
• SDK 参考文档（训练）
• SDK 参考文档（预测）

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

注意

若要在不编写代码的情况下构建和训练分类模型，请改为参阅基于浏览器的指南。

使用适用于 Java 的自定义视觉客户端库可以：

• 创建新的自定义视觉项目
• 将标记添加到项目中
• 上传和标记图像
• 定型项目
• 发布当前迭代
• 测试预测终结点

参考文档 | 库源代码（训练）（预测）| 项目 (Maven)（训练）（预测） | 示例

先决条件

• Azure 订阅 - 免费创建订阅
• 最新版本的 Java 开发工具包 (JDK)
• Gradle 生成工具，或其他依赖项管理器。
• 拥有 Azure 订阅后，请在 Azure 门户中创建自定义视觉资源，以创建训练和预测资源。
  • 可以使用免费定价层 (F0) 试用该服务，然后再升级到付费层进行生产。

创建环境变量

在此示例中，你将凭据写入运行应用程序的本地计算机上的环境变量。

转到 Azure 门户。 如果在“先决条件”部分中创建的自定义视觉资源已成功部署，请选择“后续步骤”下的“转到资源”按钮。 在资源的“密钥和终结点”页的“资源管理”下可以找到密钥和终结点。 你需要获取培训资源和预测资源这两者的密钥，以及 API 终结点。

可以在 Azure 门户中预测资源的“属性”选项卡上找到列为“资源 ID”的预测资源 ID。

提示

还可以使用 https://www.customvision.ai/ 来获取这些值。 登录后，请选择右上角的“设置”图标。 在“设置”页上，可以查看所有密钥、资源 ID 和终结点。

注意

请不要直接在代码中包含密钥，并且绝不公开发布密钥。 有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要设置环境变量，请打开控制台窗口，按照操作系统和开发环境的说明进行操作。

1. 若要设置 VISION_TRAINING KEY 环境变量，请将 your-training-key 替换为训练资源的其中一个密钥。
2. 若要设置 VISION_TRAINING_ENDPOINT 环境变量，请将 your-training-endpoint 替换为训练资源的终结点。
3. 若要设置 VISION_PREDICTION_KEY 环境变量，请将 your-prediction-key 替换为预测资源的其中一个密钥。
4. 若要设置 VISION_PREDICTION_ENDPOINT 环境变量，请将 your-prediction-endpoint 替换为预测资源的终结点。
5. 若要设置 VISION_PREDICTION_RESOURCE_ID 环境变量，请将 your-resource-id 替换为预测资源的资源 ID。

Windows

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

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

Linux

export VISION_TRAINING_KEY=your-training-key

export VISION_TRAINING_ENDPOINT=your-training-endpoint

export VISION_PREDICTION_KEY=your-prediction-key

export VISION_PREDICTION_ENDPOINT=your-prediction-endpoint

export VISION_PREDICTION_RESOURCE_ID=your-resource-id

添加环境变量后，请从控制台窗口运行 source ~/.bashrc，使更改生效。

设置

创建新的 Gradle 项目

在控制台窗口（例如 cmd、PowerShell 或 Bash）中，为应用创建一个新目录并导航到该目录。

mkdir myapp && cd myapp

从工作目录运行 gradle init 命令。 此命令将创建 Gradle 的基本生成文件，包括 build.gradle.kts，在运行时将使用该文件创建并配置应用程序。

gradle init --type basic

当提示你选择一个 DSL 时，选择 Kotlin。

安装客户端库

找到 build.gradle.kts，并使用喜好的 IDE 或文本编辑器将其打开。 然后在该文件中复制以下生成配置。 此配置将项目定义为一个 Java 应用程序，其入口点为 CustomVisionQuickstart 类。 它将导入自定义视觉库。

plugins {
    java
    application
}
application { 
    mainClassName = "CustomVisionQuickstart"
}
repositories {
    mavenCentral()
}
dependencies {
    compile(group = "com.azure", name = "azure-cognitiveservices-customvision-training", version = "1.1.0-preview.2")
    compile(group = "com.azure", name = "azure-cognitiveservices-customvision-prediction", version = "1.1.0-preview.2")
}

创建 Java 文件

从工作目录运行以下命令，以创建项目源文件夹：

mkdir -p src/main/java

导航到新文件夹，并创建名为 CustomVisionQuickstart.java 的文件。 在喜好的编辑器或 IDE 中打开该文件并添加以下 import 语句：

import java.util.Collections;
import java.util.HashMap;
import java.util.List;
import java.util.UUID;

import com.google.common.io.ByteStreams;

import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Classifier;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Domain;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.DomainType;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.ImageFileCreateBatch;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.ImageFileCreateEntry;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Iteration;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Project;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Region;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.TrainProjectOptionalParameter;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.CustomVisionTrainingClient;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.Trainings;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.CustomVisionTrainingManager;
import com.microsoft.azure.cognitiveservices.vision.customvision.prediction.models.ImagePrediction;
import com.microsoft.azure.cognitiveservices.vision.customvision.prediction.models.Prediction;
import com.microsoft.azure.cognitiveservices.vision.customvision.prediction.CustomVisionPredictionClient;
import com.microsoft.azure.cognitiveservices.vision.customvision.prediction.CustomVisionPredictionManager;
import com.microsoft.azure.cognitiveservices.vision.customvision.training.models.Tag;

提示

想要立即查看整个快速入门代码文件？ 可以在 GitHub 上找到它，其中包含此快速入门中的代码示例。

在应用程序的 CustomVisionQuickstart 类中，创建从环境变量中检索资源的密钥和终结点的变量。

// retrieve environment variables
final static String trainingApiKey = System.getenv("VISION_TRAINING_KEY");
final static String trainingEndpoint = System.getenv("VISION_TRAINING_ENDPOINT");
final static String predictionApiKey = System.getenv("VISION_PREDICTION_KEY");
final static String predictionEndpoint = System.getenv("VISION_PREDICTION_ENDPOINT");
final static String predictionResourceId = System.getenv("VISION_PREDICTION_RESOURCE_ID");

重要

转到 Azure 门户。 如果在“先决条件”部分中创建的自定义视觉资源已成功部署，请选择“后续步骤”下的“转到资源”按钮。 你可前往资源的“密钥和终结点”页，找到密钥和终结点。 你需要获取培训资源和预测资源这两者的密钥，以及适用于培训资源的 API 终结点。

可以在 Azure 门户中资源的“属性”选项卡上找到列为“资源 ID”的预测资源 ID 。

重要

请记住在完成后将密钥从代码中删除，永远不要公开发布这些密钥。 对于生产来说，请使用安全的方式存储和访问凭据，例如 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	此类定义对单一图像的单一预测。 它包括对象 ID 和名称的属性，以及可信度分数。

代码示例

这些代码片段演示如何使用适用于 Java 的自定义视觉客户端库执行以下任务：

• 对客户端进行身份验证
• 创建新的自定义视觉项目
• 将标记添加到项目中
• 上传和标记图像
• 定型项目
• 发布当前迭代
• 测试预测终结点

验证客户端

在 main 方法中，使用终结点和密钥来实例化训练和预测客户端。

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

创建自定义视觉项目

T## 创建新的自定义视觉项目

下一个方法将创建图像分类项目。 创建的项目将显示在以前访问过的自定义视觉网站上。 请查看 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());
}

发布当前迭代

此方法使模型的当前迭代可用于查询。 可以将模型名称用作发送预测请求的引用。 需要为 predictionResourceId 输入自己的值。 可以在 Azure 门户中资源的“属性”选项卡上找到列为“资源 ID”的预测资源 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 服务订阅，可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。

• Portal
• Azure CLI

如果你希望实现自己的图像分类项目（或改为尝试对象检测项目），可能希望从此示例中删除树识别项目。 免费订阅允许创建两个自定义视觉项目。

在自定义视觉网站上，导航到“项目”，然后在“我的新项目”下选择垃圾桶。

后续步骤

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

测试和重新训练模型

• 什么是自定义视觉？
• 可以在 GitHub 上找到此示例的源代码

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

注意

若要在不编写代码的情况下构建和训练分类模型，请改为参阅基于浏览器的指南。

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

• 创建新的自定义视觉项目
• 将标记添加到项目中
• 上传和标记图像
• 定型项目
• 发布当前迭代
• 测试预测终结点

参考文档（训练）（预测） | 库源代码（训练）（预测） | 包 (npm)（训练）（预测） | 示例

先决条件

• Azure 订阅 - 免费创建订阅
• 最新版本的 Node.js
• 拥有 Azure 订阅后，请在 Azure 门户中创建自定义视觉资源，以创建训练和预测资源。
  • 可以使用免费定价层 (F0) 试用该服务，然后再升级到付费层进行生产。

创建环境变量

在此示例中，你将凭据写入运行应用程序的本地计算机上的环境变量。

转到 Azure 门户。 如果在“先决条件”部分中创建的自定义视觉资源已成功部署，请选择“后续步骤”下的“转到资源”按钮。 在资源的“密钥和终结点”页的“资源管理”下可以找到密钥和终结点。 你需要获取培训资源和预测资源这两者的密钥，以及 API 终结点。

可以在 Azure 门户中预测资源的“属性”选项卡上找到列为“资源 ID”的预测资源 ID。

提示

还可以使用 https://www.customvision.ai/ 来获取这些值。 登录后，请选择右上角的“设置”图标。 在“设置”页上，可以查看所有密钥、资源 ID 和终结点。

注意

请不要直接在代码中包含密钥，并且绝不公开发布密钥。 有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要设置环境变量，请打开控制台窗口，按照操作系统和开发环境的说明进行操作。

1. 若要设置 VISION_TRAINING KEY 环境变量，请将 your-training-key 替换为训练资源的其中一个密钥。
2. 若要设置 VISION_TRAINING_ENDPOINT 环境变量，请将 your-training-endpoint 替换为训练资源的终结点。
3. 若要设置 VISION_PREDICTION_KEY 环境变量，请将 your-prediction-key 替换为预测资源的其中一个密钥。
4. 若要设置 VISION_PREDICTION_ENDPOINT 环境变量，请将 your-prediction-endpoint 替换为预测资源的终结点。
5. 若要设置 VISION_PREDICTION_RESOURCE_ID 环境变量，请将 your-resource-id 替换为预测资源的资源 ID。

Windows

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

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

Linux

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 文件创建一个 node 应用程序。

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

上传和标记图像

首先，下载此项目的示例图像。 将示例图像文件夹的内容保存到本地设备。

要将示例图像添加到项目，请在创建标记后插入以下代码。 此代码会上传具有相应标记的每个图像。

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/中找到）是否已正确标记。 也可返回到自定义视觉网站，查看新创建项目的当前状态。

如果你希望实现自己的图像分类项目（或改为尝试对象检测项目），可能希望从此示例中删除树识别项目。 免费订阅允许创建两个自定义视觉项目。

在自定义视觉网站上，导航到“项目”，然后在“我的新项目”下选择垃圾桶。

后续步骤

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

测试和重新训练模型

• 什么是自定义视觉？
• 可以在 GitHub 上找到此示例的源代码
• SDK 参考文档（训练）
• SDK 参考文档（预测）

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

注意

若要在不编写代码的情况下构建和训练分类模型，请改为参阅基于浏览器的指南。

使用适用于 Python 的自定义视觉客户端库可以：

• 创建新的自定义视觉项目
• 将标记添加到项目中
• 上传和标记图像
• 定型项目
• 发布当前迭代
• 测试预测终结点

参考文档 | 库源代码 | 包 (PyPI) | 示例

先决条件

• Azure 订阅 - 免费创建订阅
• Python 3.x
  • 你的 Python 安装应包含 pip。 可以通过在命令行上运行 pip --version 来检查是否安装了 pip。 通过安装最新版本的 Python 获取 pip。
• 拥有 Azure 订阅后，请在 Azure 门户中创建自定义视觉资源，以创建训练和预测资源。
  • 可以使用免费定价层 (F0) 试用该服务，然后再升级到付费层进行生产。

创建环境变量

在此示例中，你将凭据写入运行应用程序的本地计算机上的环境变量。

转到 Azure 门户。 如果在“先决条件”部分中创建的自定义视觉资源已成功部署，请选择“后续步骤”下的“转到资源”按钮。 在资源的“密钥和终结点”页的“资源管理”下可以找到密钥和终结点。 你需要获取培训资源和预测资源这两者的密钥，以及 API 终结点。

可以在 Azure 门户中预测资源的“属性”选项卡上找到列为“资源 ID”的预测资源 ID。

提示

还可以使用 https://www.customvision.ai/ 来获取这些值。 登录后，请选择右上角的“设置”图标。 在“设置”页上，可以查看所有密钥、资源 ID 和终结点。

注意

请不要直接在代码中包含密钥，并且绝不公开发布密钥。 有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要设置环境变量，请打开控制台窗口，按照操作系统和开发环境的说明进行操作。

1. 若要设置 VISION_TRAINING KEY 环境变量，请将 your-training-key 替换为训练资源的其中一个密钥。
2. 若要设置 VISION_TRAINING_ENDPOINT 环境变量，请将 your-training-endpoint 替换为训练资源的终结点。
3. 若要设置 VISION_PREDICTION_KEY 环境变量，请将 your-prediction-key 替换为预测资源的其中一个密钥。
4. 若要设置 VISION_PREDICTION_ENDPOINT 环境变量，请将 your-prediction-endpoint 替换为预测资源的终结点。
5. 若要设置 VISION_PREDICTION_RESOURCE_ID 环境变量，请将 your-resource-id 替换为预测资源的资源 ID。

Windows

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

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

Linux

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	此类定义单一图像上的单一对象预测。 其中包括对象 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(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 设置为要使用的标记的 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(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} 替换为有效的人脸密钥。
• 将 {endpoint} 替换为与密钥对应的终结点。

  注意

  2019 年 7 月 1 日之后创建的新资源将使用自定义子域名。 有关详细信息和区域终结点的完整列表，请参阅 Azure AI 服务的自定义子域名。

• 将 {name} 替换为项目的名称。
• （可选）设置其他 URL 参数来配置项目将使用哪种类型的模型。 相关选项，请参阅 CreatProject API。

你将收到如下所示的 JSON 响应。 将项目的 "id" 值保存到临时位置。

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

将标记添加到项目中

使用以下命令定义将在其上训练模型的标签。

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

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

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

你将收到如下所示的 JSON 响应。 将每个标签的 "id" 值保存到临时位置。

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

上传和标记图像

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

使用以下命令上传图像并应用标签；对“Hemlock”图像使用一次，并分别用于“Japan Cherry”图像。 有关更多选项，请参阅从数据创建图像 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 参数。 相关选项，请参阅训练项目 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 门户中资源的“属性”选项卡上找到列为“资源 ID”的预测资源 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"
    }
  ]
}

如果你希望实现自己的图像分类项目（或改为尝试对象检测项目），可能希望从此示例中删除树识别项目。 免费订阅允许创建两个自定义视觉项目。

在自定义视觉网站上，导航到“项目”，然后在“我的新项目”下选择垃圾桶。

后续步骤

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

测试和重新训练模型

• 什么是自定义视觉？
• API 参考文档（训练）
• API 参考文档（预测）