자습서: 사용자 디렉터리 빌드(미리 보기)

사람 디렉터리 인식 작업에 대 한 얼굴 데이터를 저장 하는 구조화 된 접근 방식을 제공 합니다. 이를 통해 개별 얼굴을 추가하고, 시각적으로 유사한 얼굴을 검색하고, 사람 프로필을 만들 수 있습니다. 이러한 프로필과 얼굴을 연결하고 새 얼굴 이미지를 알려진 개인과 일치시킬 수 있습니다. 이 설정은 이미지 및 비디오에서 유연한 얼굴 일치 및 ID 인식을 모두 지원합니다.

데이터 스토리지 권장 사항

안전하고 확장 가능한 액세스를 위해 모든 얼굴 이미지를 Azure Blob Storage에 저장하는 것이 좋습니다. API를 호출할 때 얼굴 URL이 Blob Storage에서 이러한 저장된 이미지를 참조하는지 확인합니다.

등록

등록에는 다음 단계가 포함됩니다.

빈 사용자 디렉터리 만들기
사용자 추가
얼굴 추가 및 사용자와 연결

빈 사용자 디렉터리 만들기

새 사용자 디렉터리를 만들려면 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",
    "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 Storage에 저장된 이미지의 파일 경로입니다.
- 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
  }
}

사용자 디렉터리 사용

개인 디렉터리를 만들고 선택적 사람 연결을 사용하여 얼굴 이미지를 추가한 후 다음 두 가지 주요 작업을 수행할 수 있습니다.

사람 식별: 디렉터리에 등록된 사용자와 얼굴 이미지를 일치시키고 가장 가능성이 큰 ID를 결정합니다.
비슷한 얼굴 찾기: 디렉터리에 저장된 모든 얼굴 항목에서 시각적으로 유사한 얼굴을 검색합니다.

이러한 기능은 다양한 애플리케이션에 대해 강력한 얼굴 인식 및 유사성 일치를 가능하게 합니다.

사람 식별

디렉터리에 등록된 사용자와 입력 얼굴을 비교하여 가장 가능성이 높은 사람 일치를 식별합니다.

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 Storage에 저장된 입력 얼굴 이미지의 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 Storage에 저장된 입력 얼굴 이미지의 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 Tools의 Azure Content Understanding 비디오 솔루션(미리 보기)을 사용하여 비디오 콘텐츠에서 개인을 식별하는 방법을 알아보세요.

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-09-16