教學：建立個人目錄（預覽）

人員目錄提供結構化方法來儲存臉部數據以進行辨識工作。它可讓您新增個別臉部、搜尋視覺效果類似的臉部，以及建立人員配置檔。您可以將臉部與這些檔案關聯，並將新的臉部影像與已知的個人匹配。此設定支援跨影像和影片的彈性臉部比對和身分識別辨識。

數據記憶體建議

為了安全且可調整的存取，建議您將所有臉部影像儲存在 Azure Blob 記憶體中。進行 API 呼叫時，請確定臉部 URL 參考 Blob 記憶體中儲存的影像。

註冊

註冊牽涉到下列步驟：

建立空的人員目錄
新增人員
新增臉部並與人員建立關聯

建立空的人員目錄

若要建立新的人員目錄，請將要求傳送 PUT 至 API 端點。此目錄用於存放臉部影像及其相關人員的資料。

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",
    "employeeId": "E12345"
  }
}

personDirectoryId：步驟 1 中建立之目錄的唯一標識符。
tags：用來描述人員的索引鍵/值組，例如其名稱或年齡。

API 會傳回 personId，唯一識別所建立的人員。

200 OK

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

新增臉部並與個人建立關聯

您可以將臉部新增至目錄，並選擇性地將它與現有人員產生關聯。 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、 medium或 high）。默認值為 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",
        "employeeId": "E12345"
      },
      "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 指出來源圖像。

後續步驟

探索如何利用 Foundry 工具中的 Azure 內容理解影片解決方案（預覽）來識別影片中的個人。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-09-16