Compartilhar via

Tutorial: Criar um diretório de pessoa (versão prévia)

Um diretório de pessoas fornece uma abordagem estruturada para armazenar dados faciais para tarefas de reconhecimento. Ele permite que você adicione rostos individuais, pesquise rostos visualmente semelhantes e crie perfis de pessoa. Você pode associar rostos a esses perfis e corresponder novas imagens faciais a indivíduos conhecidos. Essa configuração dá suporte à correspondência facial flexível e ao reconhecimento de identidade entre imagens e vídeos.

Diagrama ilustrando os processos de registro e pesquisa em um diretório de pessoa.

Recomendação de armazenamento de dados

Para acesso seguro e escalonável, recomendamos armazenar todas as imagens faciais no Armazenamento de Blobs do Azure. Ao fazer chamadas à API, verifique se as URLs de detecção facial fazem referência a essas imagens armazenadas no Armazenamento de Blobs.

Registro

O registro envolve as seguintes etapas:

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

Criar um diretório de pessoa vazio

Para criar um novo diretório de pessoa, envie uma PUT solicitação para o ponto de extremidade da API. Esse 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. Depois de 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 dá suporte a 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 pessoa criado na Etapa 1.
  • faceSource: especifica a imagem facial.
    • url: o caminho do arquivo da imagem armazenada no Armazenamento de Blobs do Azure.
    • data: dados de imagem codificados em Base64 como alternativa opcional para url.
    • imageReferenceId: (Opcional) Um identificador definido pelo usuário para a imagem. Esse identificador pode ser útil para acompanhar a origem da imagem ou mapeá-la para outros dados.
    • targetBoundingBox: (Opcional) Localização aproximada do rosto na imagem. Se omitida, a API detectará e usará o maior rosto.
  • qualityThreshold: (Opcional) Filtra a qualidade da face (low, medium ou high). O padrão é medium, o que significa que apenas imagens faciais de qualidade média ou alta são armazenadas. Rostos de qualidade mais baixa são rejeitados.
  • personId: (Opcional) O personId de uma pessoa existente à qual associar o rosto.

A API retorna um faceId que identifica exclusivamente o rosto criado com o boundingBox detectado do rosto.

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

Use o diretório de pessoas

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

  1. Identificar uma pessoa: Comparar uma imagem de um rosto com as pessoas registradas no diretório e determinar qual é a identidade mais provável.
  2. Encontre rostos semelhantes: pesquise rostos visualmente semelhantes em todas as entradas de rosto armazenadas no diretório.

Esses recursos permitem o reconhecimento facial robusto e a correspondência de similaridade para vários aplicativos.

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

Identificar uma pessoa

Identifique as correspondências de pessoa mais prováveis comparando a face de entrada com as pessoas registradas 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 de rosto de entrada armazenada no Armazenamento de Blobs do Azure.
  • faceSource.targetBoundingBox: (Opcional) A caixa delimitadora aproximada do rosto na imagem. Se omitida, a API detectará o maior rosto.
  • maxPersonCandidates: (Opcional) O número máximo de candidatos a serem retornados. O padrão é UTF-1.

A API retorna a caixa delimitadora detectada do rosto junto com os principais candidatos a pessoa.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "personCandidates": [
    {
      "personId": "{personId1}",
      "tags": {
        "name": "Alice",
        "employeeId": "E12345"
      },
      "confidence": 0.92
    }
  ]
}
  • detectedFace.boundingBox: a caixa delimitadora do rosto detectado na imagem de entrada.
  • personCandidates: uma lista de possíveis correspondências, cada uma com uma personId, tags associada e uma pontuação confidence 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 de rosto de entrada armazenada no Armazenamento de Blobs do Azure.
  • faceSource.targetBoundingBox: (Opcional) A caixa delimitadora aproximada do rosto na imagem. Se omitida, a API detectará o maior rosto.
  • maxSimilarFaces: (Opcional) O número máximo de rostos semelhantes a serem retornados. O padrão é 1000, com um limite máximo de 1000.

A API retorna a caixa delimitadora detectada do rosto juntamente com os rostos mais semelhantes do diretório.

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

Próxima etapa

Explore como identificar indivíduos no conteúdo de vídeo usando as soluções de vídeo do Azure Content Understanding in Foundry Tools (versão prévia).

  • Last updated on