Partilhar via

Tutorial: Criar um diretório de pessoas (pré-visualização)

Um diretório de pessoas fornece uma abordagem estruturada para armazenar dados faciais para tarefas de reconhecimento. Ele permite que você adicione rostos individuais, procure rostos visualmente semelhantes e crie perfis de pessoas. Pode associar rostos a estes perfis e fazer corresponder novas imagens de rostos a indivíduos conhecidos. Esta configuração suporta correspondência facial flexível e reconhecimento de identidade em imagens e vídeos.

Diagrama ilustrando os processos de inscrição e pesquisa em um diretório de pessoas.

Recomendação de armazenamento de dados

Para acesso seguro e escalável, recomendamos armazenar todas as imagens de rosto no Armazenamento de Blobs do Azure. Ao fazer chamadas de API, certifique-se de que as URLs de rosto façam referência a essas imagens armazenadas no Armazenamento de Blobs.

Inscrição

A inscrição envolve as seguintes etapas:

  1. Criar um diretório de pessoas vazio
  2. Adicionar pessoas
  3. Adicionar rostos e associar a uma pessoa

Criar um diretório de pessoas vazio

Para criar um novo diretório de pessoas, envie uma solicitação para o endpoint da API. Este diretório serve como o contêiner para armazenar rostos e pessoas associadas.

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: Um identificador exclusivo definido pelo usuário para o diretório dentro do recurso.
  • description: (Opcional) Uma breve descrição da finalidade do diretório.
  • tags: (Opcional) Pares chave-valor para ajudar a organizar e gerenciar o diretório.

A API cria o diretório e retorna uma resposta de confirmação.

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
}

Adicionar pessoas

Para reconhecer ou gerenciar indivíduos, você precisa criar um perfil de pessoa. Uma vez criado, você pode associar rostos a essa pessoa.

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

{
  "tags": {
    "name": "Alice",
    "employeeId": "E12345"
  }
}
  • personDirectoryId: O identificador exclusivo do diretório criado na Etapa 1.
  • tags: Pares chave-valor para descrever a pessoa, como seu nome ou idade.

A API retorna um personId que identifica exclusivamente a pessoa criada.

200 OK

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

Adicionar rostos e associar a uma pessoa

Você pode adicionar um rosto ao diretório e, opcionalmente, associá-lo a uma pessoa existente. A API suporta URLs de imagem e dados de imagem codificados em 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: O identificador exclusivo do diretório de pessoas criado na Etapa 1.
  • faceSource: Especifica a imagem do rosto.
    • url: O caminho do arquivo da imagem armazenada no Armazenamento de Blob do Azure.
    • data: Dados de imagem codificados em Base64 como alternativa opcional ao url.
    • imageReferenceId: (Opcional) Um identificador definido pelo usuário para a imagem. Esse identificador pode ser útil para rastrear a origem da imagem ou para mapeá-la para outros dados.
    • targetBoundingBox: (Opcional) Localização aproximada do rosto na imagem. Se omitido, a API deteta e utiliza o maior rosto.
  • qualityThreshold: (Opcional) Filtra a qualidade facial (low, medium ou high). O padrão é medium, o que significa que apenas rostos de qualidade média ou alta são armazenados. Rostos de qualidade inferior são rejeitados.
  • personId: (Opcional) O personId de uma pessoa existente para associar o rosto com.

A API retorna um faceId que identifica exclusivamente o rosto criado com o boundingBox detetado no rosto.

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

Usar o diretório de pessoas

Depois de criar seu diretório de pessoas e adicionar imagens de rosto com associações de pessoas opcionais, você pode executar duas tarefas principais:

  1. Identificar uma pessoa: faça a correspondência entre uma imagem de rosto e as pessoas inscritas no diretório e determine a identidade mais provável.
  2. Encontre rostos semelhantes: pesquise rostos visualmente semelhantes em todas as entradas de rostos armazenadas no diretório.

Esses recursos permitem reconhecimento facial robusto e correspondência de similaridade para várias aplicações.

Diagrama ilustrando os processos de pesquisa em um diretório de pessoas.

Identificar uma pessoa

Identifique as correspondências de pessoas mais prováveis comparando a face de entrada com as pessoas inscritas no diretório.

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: A URL da imagem facial de entrada armazenada no Armazenamento de Blobs do Azure.
  • faceSource.targetBoundingBox: (Opcional) A caixa delimitadora aproximada do rosto na imagem. Se omitido, a API deteta o maior rosto.
  • maxPersonCandidates: (Opcional) O número máximo de pessoas candidatas a regressar. A predefinição é 1.

A API retorna a caixa delimitadora detetada do rosto junto com os candidatos de primeira pessoa.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "personCandidates": [
    {
      "personId": "{personId1}",
      "tags": {
        "name": "Alice",
        "employeeId": "E12345"
      },
      "confidence": 0.92
    }
  ]
}
  • detectedFace.boundingBox: A caixa delimitadora da face detetada na imagem de entrada.
  • personCandidates: Uma lista de possíveis correspondências, cada uma com um personId, associado tags, e uma confidence pontuação indicando a probabilidade de uma correspondência.

Encontrar rostos semelhantes

Encontre rostos visualmente semelhantes de todas as entradas de rosto armazenadas no diretório.

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: A URL da imagem facial de entrada armazenada no Armazenamento de Blobs do Azure.
  • faceSource.targetBoundingBox: (Opcional) A caixa delimitadora aproximada do rosto na imagem. Se omitido, a API deteta o maior rosto.
  • maxSimilarFaces: (Opcional) O número máximo de faces semelhantes a serem retornadas. O padrão é 1000, com um limite máximo de 1000.

A API retorna a detetada caixa delimitadora do rosto e os rostos mais semelhantes do diretório.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "similarFaces": [
    {
      "faceId": "{faceId}",
      "boundingBox": { ... },
      "confidence": 0.92,
      "imageReferenceId": "face.jpg"
    }
  ]
}
  • detectedFace.boundingBox: A caixa delimitadora da face detetada na imagem de entrada.
  • similarFaces: Uma lista de rostos semelhantes, cada um com uma pontuação de faceId, boundingBox, confidence e um imageReferenceId indicando a imagem de origem.

Próximo passo

Explore como identificar indivíduos em conteúdos de vídeo usando as soluções de vídeo Azure Content Understanding in Foundry Tools (pré-visualização).

  • Last updated on