Руководство: Создание каталога людей (предварительный просмотр)

Важно

Предварительная версия API 2024-12-01-preview и 2025-05-01-preview будет прекращена к 15 июля 2026 года. Если вы по-прежнему используете API предварительной версии, обновите код, чтобы выбрать последнюю версию 2025-11-01 (GA)API.

Версии 2024-12-01-preview API и 2025-05-01-preview доступны в общедоступной предварительной версии. Эти предварительные версии предоставляются без соглашения об уровне обслуживания и не рекомендуются для производственных рабочих нагрузок. Дополнительные сведения см. в разделе Supplemental Terms of Use for Microsoft Azure Previews и Microsoft Products and Services Data Protection Addendum (DPA).

Каталог пользователя предоставляет структурированный подход к хранению данных лиц для задач распознавания. Он позволяет добавлять отдельные лица, искать визуально похожие лица и создавать профили пользователей. Вы можете связать лица с этими профилями и сопоставить новые изображения лиц с известными людьми. Эта настройка поддерживает как гибкое сопоставление лиц, так и распознавание удостоверений в изображениях и видео.

Схема, иллюстрирующая процессы регистрации и поиска в каталоге пользователя.

Рекомендация по хранилищу данных

Для безопасного и масштабируемого доступа сохраните изображения лиц в Хранилище BLOB-объектов Azure. При вызове API убедитесь, что URL-адреса лиц ссылаются на эти сохраненные изображения.

Регистрации

Регистрация включает в себя следующие действия.

  1. Создание пустого каталога пользователя
  2. Добавление лиц
  3. Добавление лиц и связывание их с человеком

Создание пустого каталога пользователя

Чтобы создать каталог пользователя, отправьте запрос в 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: путь к файлу образа, хранящегося в Хранилище BLOB-объектов Azure.
    • 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
  }
}

Использовать каталог персон

После создания каталога лиц и добавления изображений лиц с необязательными ассоциациями с лицами, можно выполнить две ключевые задачи:

  1. Идентифицируйте человека: сопоставьте изображение лица с зарегистрированными лицами в каталоге и определите наиболее вероятную личность.
  2. Поиск похожих лиц: поиск визуально похожих лиц во всех сохраненных записях лиц в каталоге.

Эти возможности обеспечивают надежное распознавание лиц и сопоставление сходства для различных приложений.

Схема, иллюстрирующая процессы поиска в каталоге пользователя.

Идентификация человека

Определите наиболее вероятные совпадения лиц, сравнивая входные данные с зарегистрированными лицами в каталоге.

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: URL-адрес входного изображения лица, хранящегося в Хранилище BLOB-объектов Azure.
  • 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: URL-адрес входного изображения лица, хранящегося в Хранилище BLOB-объектов Azure.
  • 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 Content Understanding in Foundry Tools video solutions (preview).

  • Last updated on