더 많은 등록 사용자를 처리할 수 있도록 크기 조정

아티클
01/29/2025

주의

Face 서비스 액세스는 책임 있는 AI 원칙을 지원하기 위해 자격 및 사용 기준에 따라 제한됩니다. Face 서비스는 Microsoft 관리 고객 및 파트너만 사용할 수 있습니다. 얼굴 인식 접수 양식을 사용하여 액세스를 적용합니다. 자세한 내용은 얼굴 제한 액세스 페이지를 참조하세요.

이 가이드에서는 기존 PersonGroup 및 FaceList 개체에서 LargePersonGroup 및 LargeFaceList 개체로 각각 스케일 업하는 방법을 보여 줍니다. PersonGroups는 무료 계층에 최대 1,000명, 유료 계층에 최대 10,000명까지 수용할 수 있으며, LargePersonGroups는 유료 계층에 최대 100만 명까지 수용할 수 있습니다.

Important

새로운 개발에는 최신 데이터 구조인 PersonDirectory가 권장됩니다. 최대 2천만 개의 ID를 보유할 수 있으며 수동 학습이 필요하지 않습니다. 자세한 내용은 PersonDirectory 가이드를 참조하세요.

이 가이드에서는 마이그레이션 프로세스를 설명합니다. 여기서는 PersonGroup 및 FaceList 개체, Train 작업 및 얼굴 인식 함수에 대해 기본적으로 이해하고 있다고 가정합니다. 이러한 주제에 대해 자세히 알아보려면 얼굴 인식 개념 가이드를 참조하세요.

LargePersonGroup과 LargeFaceList는 총괄하여 대규모 작업이라고 합니다. LargePersonGroup은 최대 100만 명의 사람을 포함할 수 있으며, 각 사람마다 최대 248개의 얼굴이 있습니다. LargeFaceList는 최대 100만 개의 얼굴을 포함할 수 있습니다. 대규모 작업은 기존의 PersonGroup 및 FaceList와 비슷하지만 새 아키텍처로 인해 몇 가지 차이점이 있습니다.

샘플은 C#으로 작성되었습니다.

참고 항목

Identification 및 FindSimilar에 대한 Face 검색 성능을 대규모로 사용하도록 설정하려면 LargeFaceList 및 LargePersonGroup을 전처리하도록 Train 작업을 도입합니다. 학습 시간은 실제 용량에 따라 초 단위에서 약 30분까지 다양합니다. 학습 기간 동안 성공적인 학습 작업이 이전에 수행된 경우 Identification 및 FindSimilar를 수행할 수 있습니다. 단점은 대규모 학습으로의 새 게시 마이그레이션이 완료될 때까지 새로 추가된 사람과 얼굴이 결과에 표시되지 않는 것입니다.

1단계: 코드 마이그레이션

이 섹션에서는 PersonGroup 또는 FaceList 구현을 LargePersonGroup 또는 LargeFaceList로 마이그레이션하는 방법에 중점을 둡니다. LargePersonGroup 및 LargeFaceList는 디자인 및 내부 구현에서 PersonGroup 및 FaceList와 다르지만 API 인터페이스는 이전 버전과의 호환성을 위해 유사합니다.

데이터 마이그레이션은 지원되지 않습니다. 대신 LargePersonGroup 또는 LargeFaceList를 다시 만듭니다.

PersonGroup을 LargePersonGroup으로 마이그레이션

PersonGroup에서 LargePersonGroup으로의 마이그레이션은 간단합니다. 정확히 동일한 그룹 수준 작업을 공유합니다.

PersonGroup 또는 Person 관련 구현의 경우 API 경로 또는 SDK 클래스/모듈만 LargePersonGroup 및 LargePersonGroupPerson으로 변경해야 합니다.

PersonGroup의 모든 얼굴과 사람을 새 LargePersonGroup에 추가합니다. 자세한 내용은 얼굴 추가를 참조하세요.

FaceList를 LargeFaceList로 마이그레이션

FaceList API	LargeFaceList API
만들기	만들기
삭제	삭제
Get	가져오기
List	List
업데이트	업데이트
-	학습
-	학습 상태 가져오기

앞의 테이블은 FaceList와 LargeFaceList 간 목록 수준 작업의 비교입니다. 표시된 대로 FaceList와 비교할 때 LargeFaceList에는 Train(학습) 및 Get Training Status(학습 상태 가져오기)라는 새 작업이 제공됩니다. LargeFaceList 학습은 FindSimilar 작업의 전제 조건입니다. FaceList에는 학습이 필요하지 않습니다. 다음 코드 조각은 LargeFaceList의 학습을 기다리는 도우미 함수입니다.

/// <summary>
/// Helper function to train LargeFaceList and wait for finish.
/// </summary>
/// <remarks>
/// The time interval can be adjusted considering the following factors:
/// - The training time which depends on the capacity of the LargeFaceList.
/// - The acceptable latency for getting the training status.
/// - The call frequency and cost.
///
/// Estimated training time for LargeFaceList in different scale:
/// -     1,000 faces cost about  1 to  2 seconds.
/// -    10,000 faces cost about  5 to 10 seconds.
/// -   100,000 faces cost about  1 to  2 minutes.
/// - 1,000,000 faces cost about 10 to 30 minutes.
/// </remarks>
/// <param name="largeFaceListId">The Id of the LargeFaceList for training.</param>
/// <param name="timeIntervalInMilliseconds">The time interval for getting training status in milliseconds.</param>
/// <returns>A task of waiting for LargeFaceList training finish.</returns>
private static async Task TrainLargeFaceList(
    string largeFaceListId,
    int timeIntervalInMilliseconds = 1000)
{
    HttpClient httpClient = new HttpClient();
    httpClient.DefaultRequestHeaders.Add("Ocp-Apim-Subscription-Key", SUBSCRIPTION_KEY);

    // Trigger a train call.
    await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/largefacelists/{largeFaceListId}/train", null);

    // Wait for training finish.
    while (true)
    {
        await Task.Delay(timeIntervalInMilliseconds);
        string? trainingStatus = null;
        using (var response = await httpClient.GetAsync($"{ENDPOINT}/face/v1.0/largefacelists/{largeFaceListId}/training"))
        {
            string contentString = await response.Content.ReadAsStringAsync();
            trainingStatus = (string?)(JsonConvert.DeserializeObject<Dictionary<string, object>>(contentString)?["status"]);
        }

        if ("running".Equals(trainingStatus))
        {
            continue;
        }
        else if ("succeeded".Equals(trainingStatus))
        {
            break;
        }
        else
        {
            throw new Exception("The train operation is failed!");
        }
    }
}

이전에 얼굴이 추가되고 FindSimilar가 있는 FaceList의 일반적인 사용법은 다음과 같았습니다.

// Create a FaceList.
const string FaceListId = "myfacelistid_001";
const string FaceListName = "MyFaceListDisplayName";
const string ImageDir = @"/path/to/FaceList/images";
using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["name"] = FaceListName, ["recognitionModel"] = "recognition_04" }))))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    await httpClient.PutAsync($"{ENDPOINT}/face/v1.0/facelists/{FaceListId}", content);
}

// Add Faces to the FaceList.
Parallel.ForEach(
    Directory.GetFiles(ImageDir, "*.jpg"),
    async imagePath =>
    {
        using (Stream stream = File.OpenRead(imagePath))
        {
            using (var content = new StreamContent(stream))
            {
                content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
                await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/facelists/{FaceListId}/persistedfaces?detectionModel=detection_03", content);
            }
        }
    });

// Perform FindSimilar.
const string QueryImagePath = @"/path/to/query/image";
var results = new List<HttpResponseMessage>();
using (Stream stream = File.OpenRead(QueryImagePath))
{
    var response = await faceClient.DetectAsync(BinaryData.FromStream(stream), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: true);
    var faces = response.Value;
    foreach (var face in faces)
    {
        using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["faceId"] = face.FaceId, ["faceListId"] = FaceListId }))))
        {
            content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
            results.Add(await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/findsimilars", content));
        }
    }
}

LargeFaceList로 마이그레이션하는 경우 다음과 같이 됩니다.

// Create a LargeFaceList.
const string LargeFaceListId = "mylargefacelistid_001";
const string LargeFaceListName = "MyLargeFaceListDisplayName";
const string ImageDir = @"/path/to/FaceList/images";
using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["name"] = LargeFaceListName, ["recognitionModel"] = "recognition_04" }))))
{
    content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
    await httpClient.PutAsync($"{ENDPOINT}/face/v1.0/largefacelists/{LargeFaceListId}", content);
}

// Add Faces to the LargeFaceList.
Parallel.ForEach(
    Directory.GetFiles(ImageDir, "*.jpg"),
    async imagePath =>
    {
        using (Stream stream = File.OpenRead(imagePath))
        {
            using (var content = new StreamContent(stream))
            {
                content.Headers.ContentType = new MediaTypeHeaderValue("application/octet-stream");
                await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/largefacelists/{LargeFaceListId}/persistedfaces?detectionModel=detection_03", content);
            }
        }
    });

// Train() is newly added operation for LargeFaceList.
// Must call it before FindSimilar to ensure the newly added faces searchable.
await TrainLargeFaceList(LargeFaceListId);

// Perform FindSimilar.
const string QueryImagePath = @"/path/to/query/image";
var results = new List<HttpResponseMessage>();
using (Stream stream = File.OpenRead(QueryImagePath))
{
    var response = await faceClient.DetectAsync(BinaryData.FromStream(stream), FaceDetectionModel.Detection03, FaceRecognitionModel.Recognition04, returnFaceId: true);
    var faces = response.Value;
    foreach (var face in faces)
    {
        using (var content = new ByteArrayContent(Encoding.UTF8.GetBytes(JsonConvert.SerializeObject(new Dictionary<string, object> { ["faceId"] = face.FaceId, ["largeFaceListId"] = LargeFaceListId }))))
        {
            content.Headers.ContentType = new MediaTypeHeaderValue("application/json");
            results.Add(await httpClient.PostAsync($"{ENDPOINT}/face/v1.0/findsimilars", content));
        }
    }
}

앞에서 설명한 대로 데이터 관리와 FindSimilar 부분은 거의 동일합니다. 유일한 예외는 FindSimilar가 작동하기 전에 LargeFaceList에서 전처리 Train 작업 새로 고침을 완료해야 한다는 것입니다.

2단계: 학습 제안 사항

Train 작업은 FindSimilar 및 Identification의 속도를 향상시키지만 특히 대규모 작업인 경우 학습 시간이 저하됩니다. 다음 표에는 서로 다른 규모에서 예상되는 학습 시간이 나와 있습니다.

얼굴 또는 사람에 대한 크기	예상 학습 시간
1,000	1-2초
10,000	5-10초
100,000	1-2분
1,000,000	10-30분

대규모 기능을 더 잘 활용하려면 다음 전략을 사용하는 것이 좋습니다.

2a단계: 시간 간격 사용자 지정

TrainLargeFaceList()에서와 같이 무한 학습 상태 확인 프로세스를 지연시키는 시간 간격(밀리초)이 있습니다. 더 많은 얼굴이 있는 LargeFaceList의 경우 큰 간격을 사용하면 호출 수 및 비용을 감소시킵니다. LargeFaceList의 예상 용량에 따라 시간 간격을 사용자 지정합니다.

동일한 전략이 LargePersonGroup에도 적용됩니다. 예를 들어 100만 명의 사람을 사용하여 LargePersonGroup을 학습시키는 경우 timeIntervalInMilliseconds는 60,000(1분 간격)일 수 있습니다.

2b단계: 소규모 버퍼

LargePersonGroup 또는 LargeFaceList의 사람 또는 얼굴은 학습된 후에만 검색할 수 있습니다. 동적 시나리오에서 새 사람 또는 얼굴은 지속적으로 추가되고 즉시 검색할 수 있어야 하지만, 학습은 원하는 것보다 오래 걸릴 수 있습니다.

이 문제를 완화하려면 소규모의 추가 LargePersonGroup 또는 LargeFaceList를 새로 추가된 항목에 대한 버퍼로만 사용합니다. 이 버퍼는 크기가 작으므로 학습하는 시간이 더 짧습니다. 이 임시 버퍼에 대한 즉시 검색 기능이 작동해야 합니다. 마스터 학습을 더욱 드문 간격으로 실행하여 마스터 LargePersonGroup 또는 LargeFaceList에 대한 학습과 함께 이 버퍼를 사용합니다. 예를 들어 한밤중과 매일이 있습니다.

예제 워크플로:

마스터 컬렉션인 마스터 LargePersonGroup또는 LargeFaceList를 만듭니다. 버퍼 컬렉션인 버퍼 LargePersonGroup 또는 LargeFaceList를 만듭니다. 버퍼 컬렉션은 새로 추가된 사람 또는 얼굴입니다.
새 사람 또는 얼굴을 마스터 컬렉션 및 버퍼 컬렉션 모두에 추가합니다.
새로 추가된 항목이 적용되도록 버퍼 컬렉션만 짧은 시간 간격으로 학습시킵니다.
마스터 컬렉션 및 버퍼 컬렉션 모두에 대해 Identification 또는 FindSimilar를 호출합니다. 결과를 병합합니다.
버퍼 컬렉션 크기가 임계값까지 증가하거나 시스템 유휴 시간에 증가하는 경우 새 버퍼 컬렉션을 만듭니다. 마스터 컬렉션에 대한 Train 작업을 트리거합니다.
마스터 컬렉션에 대한 Train 작업이 완료되면 이전 버퍼 컬렉션을 삭제합니다.

2c단계: 독립형 학습

상대적으로 긴 대기 시간이 허용되면 새 데이터를 추가한 직후 Train 작업을 트리거할 필요가 없습니다. 대신 Train 작업은 기본 논리에서 분할되고 정기적으로 트리거될 수 있습니다. 이 전략은 대기 시간이 허용되는 동적 시나리오에 적합합니다. Train 빈도를 더 줄이기 위해 이 전략을 정적 시나리오에 적용할 수 있습니다.

TrainLargeFaceList와 비슷한 TrainLargePersonGroup 함수가 있다고 가정합니다. System.Timers에서 Timer 클래스를 호출하여 LargePersonGroup에 대한 독립 실행형 학습을 구현하는 일반적인 방법은 다음과 같습니다.

private static void Main()
{
    // Set up standalone training at regular intervals.
    const int TimeIntervalForStatus = 1000 * 60; // 1-minute interval for getting training status.
    const double TimeIntervalForTrain = 1000 * 60 * 60; // 1-hour interval for training.
    var trainTimer = new Timer(TimeIntervalForTrain);
    trainTimer.Elapsed += (sender, args) => TrainTimerOnElapsed("mylargepersongroupid_001", TimeIntervalForStatus);
    trainTimer.AutoReset = true;
    trainTimer.Enabled = true;

    // Other operations like creating persons, adding faces, and identification, except for Train.
    // ...
}

private static void TrainTimerOnElapsed(string largePersonGroupId, int timeIntervalInMilliseconds)
{
    TrainLargePersonGroup(largePersonGroupId, timeIntervalInMilliseconds).Wait();
}

데이터 관리 및 식별 관련 구현에 대한 자세한 내용은 얼굴 추가를 참조하세요.

요약

이 가이드에서는 데이터가 아니라 기존 PersonGroup 또는 FaceList 코드를 LargePersonGroup 또는 LargeFaceList로 마이그레이션하는 방법을 알아보았습니다.

LargeFaceList에 Train 작업이 필요하다는 점을 제외하고는 LargePersonGroup 및 LargeFaceList가 PersonGroup 또는 FaceList와 비슷하게 작동합니다.
대규모 데이터 세트에 대한 동적 데이터 업데이트에 적합한 Train 전략을 사용합니다.

방법 가이드에 따라 PersonGroup에 얼굴을 추가하거나 PersonGroup에서 Identify 작업을 수행하는 스크립트를 작성하는 방법을 알아봅니다.

다음을 통해 공유

더 많은 등록 사용자를 처리할 수 있도록 크기 조정

1단계: 코드 마이그레이션

PersonGroup을 LargePersonGroup으로 마이그레이션

FaceList를 LargeFaceList로 마이그레이션

2단계: 학습 제안 사항

2a단계: 시간 간격 사용자 지정

2b단계: 소규모 버퍼

2c단계: 독립형 학습

요약

피드백

추가 리소스

다음을 통해 공유

더 많은 등록 사용자를 처리할 수 있도록 크기 조정

1단계: 코드 마이그레이션

PersonGroup을 LargePersonGroup으로 마이그레이션

FaceList를 LargeFaceList로 마이그레이션

2단계: 학습 제안 사항

2a단계: 시간 간격 사용자 지정

2b단계: 소규모 버퍼

2c단계: 독립형 학습

요약

관련 콘텐츠

피드백

추가 리소스