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

教程：生成人员目录

2025-05-20

人员目录提供了一种结构化方法，用于存储人脸数据以用于识别任务。它允许你添加单个人脸、搜索视觉上相似的人脸，以及创建个人资料。可以将人脸与这些配置文件相关联，并将新的人脸图像与已知个人匹配。此设置支持跨图像和视频的灵活人脸匹配和标识识别。

展示人员目录中注册和搜索流程的图表。

数据存储建议

为了安全且可缩放的访问，建议将所有人脸图像存储在 Azure Blob 存储中。进行 API 调用时，请确保人脸 URL 引用 Blob 存储中存储的图像。

注册

注册涉及以下步骤：

创建空人员目录
添加人员
添加人脸并与某人关联

创建空的个人目录

若要创建新人员目录，请向 API 终结点发送 PUT 请求。此目录用作存储人脸和关联人员的容器。

PUT {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}?api-version=2025-05-01-preview
Content-Type: application/json

{
  "description": "A brief description of the directory",
  "tags": {
    "project": "example-project",
    "owner": "team-name"
  }
}

personDirectoryId：资源中目录的唯一用户定义标识符。
description：（可选）目录用途的简短说明。
tags：（可选）键值对，以帮助组织和管理目录。

API 将创建目录并返回确认响应。

200 OK

{
  "personDirectoryId": "{personDirectoryId}",
  "description": "A brief description of the directory",
  "createdAt": "2025-05-01T18:46:36.051Z",
  "lastModifiedAt": "2025-05-01T18:46:36.051Z",
  "tags": {
    "project": "example-project",
    "owner": "team-name"
  },
  "personCount": 0,
  "faceCount": 0
}

添加人员

若要识别或管理个人，需要创建人员个人资料。创建后，可以将人脸与此人相关联。

POST {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/persons?api-version=2025-05-01-preview
Content-Type: application/json

{
  "tags": {
    "name": "Alice",
    "age": "20"
  }
}

personDirectoryId：步骤 1 中创建的目录的唯一标识符。
tags：用于描述人员（例如其姓名或年龄）的键值对。

API 返回唯一标识已创建人员的 personId。

200 OK

{
  "personId": "4f66b612-e57d-4d17-9ef7-b951aea2cf0f",
  "tags": {
    "name": "Alice",
    "age": "20"
  }
}

添加人脸并与人员关联

你可以向目录添加人脸，并选择性地将其与现有人员相关联。该 API 支持图像 URL 和 base64 编码的图像数据。

POST {endpoint}/contentunderstanding/personDirectories/{personDirectoryId}/faces?api-version=2025-05-01-preview
Content-Type: application/json

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/container/face.jpg",
    // "data": "<base64 data>",
    "imageReferenceId": "face.jpg",
    "targetBoundingBox": {
      "left": 33,
      "top": 73,
      "width": 262,
      "height": 324
    }
  },
  "qualityThreshold": "medium",
  "personId": "{personId}"
}

personDirectoryId：在步骤 1 中创建的人员目录的唯一标识符。
faceSource：指定人脸图像。
- url：存储在 Azure Blob 存储中的映像的文件路径。
- data：Base64 编码的图像数据作为 url 的可选替代。
- imageReferenceId：（可选）图像的用户定义标识符。此标识符可用于跟踪图像的源或将其映射到其他数据。
- targetBoundingBox：（可选）图像中人脸的大致位置。如果省略，API 会检测并使用最大人脸。
qualityThreshold：（可选）筛选人脸质量（low或mediumhigh）。默认值为 medium，这意味着仅存储中等或高质量的人脸。质量较低的人脸会被系统拒绝。
personId：（可选）要与人脸关联的现有人员的 personId。

API 返回一个 faceId，它使用检测到的人脸 boundingBox 唯一标识已创建的人脸。

{
  "faceId": "{faceId}",
  "personId": "{personId}",
  "imageReferenceId": "face.jpg",
  "boundingBox": {
    "left": 30,
    "top": 78,
    "width": 251,
    "height": 309
  }
}

搜索

创建人员目录并使用可选人员关联添加人脸图像后，可以执行两个关键任务：

标识人员：将人脸图像与目录中的已注册人员匹配，并确定最有可能的身份。
查找视觉上相似的人脸：在目录中所有存储的人脸条目中搜索相似的人脸。

这些功能为各种应用程序启用可靠的人脸识别和相似性匹配。

识别一个人

通过将输入人脸与目录中的已注册人员进行比较来确定最有可能的人员匹配。

POST {endpoint}/contentunderstanding/personDirectory/{personDirectoryId}/persons:identify?api-version=2025-05-01-preview
Content-Type: application/json

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/container/unknown.jpg",
    "targetBoundingBox": { ... }
  },
  "maxPersonCandidates": 1
}

faceSource.url：存储在 Azure Blob 存储中的输入人脸图像的 URL。
faceSource.targetBoundingBox：（可选）图像中人脸的近似边界框。如果省略，API 将检测最大的人脸。
maxPersonCandidates：（可选）要返回的候选人数上限。默认值为 1。

API 将返回检测到的人脸边界框以及最可能的候选人。

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "personCandidates": [
    {
      "personId": "{personId1}",
      "tags": {
        "name": "Alice",
        "age": "20"
      },
      "confidence": 0.92
    }
  ]
}

detectedFace.boundingBox：输入图像中检测到的人脸的边界框。
personCandidates：潜在匹配项的列表，每个匹配项都有一个 personId、关联的 tags，以及一个指示匹配可能性的 confidence 分数。

查找相似人脸

从目录中所有存储的人脸条目中查找视觉上相似的人脸。

POST {endpoint}/personDirectory/{personDirectoryId}/faces:find?api-version=2025-05-01-preview
Content-Type: application/json

{
  "faceSource": {
    "url": "https://mystorageaccount.blob.core.windows.net/container/target.jpg",
    "targetBoundingBox": { ... }
  },
  "maxSimilarFaces": 10
}

faceSource.url：存储在 Azure Blob 存储中的输入人脸图像的 URL。
faceSource.targetBoundingBox：（可选）图像中人脸的近似边界框。如果省略，API 将检测最大的人脸。
maxSimilarFaces：（可选）返回的相似人脸数量最多为多少。默认值为 1000，最大限制为 1000。

API 将返回检测到的人脸边界框以及目录中最相似的人脸。

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "similarFaces": [
    {
      "faceId": "{faceId}",
      "boundingBox": { ... },
      "confidence": 0.92,
      "imageReferenceId": "face.jpg"
    }
  ]
}

detectedFace.boundingBox：输入图像中检测到的人脸的边界框。
similarFaces：相似人脸的列表，每个人脸都有一个 faceId、boundingBox、confidence 分数和一个指示源图像的 imageReferenceId。

后续步骤

了解如何使用 Azure AI 内容理解视频解决方案（预览版）识别视频内容中的个人。

通过