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. Permite-lhe adicionar rostos individuais, procurar rostos visualmente semelhantes e criar perfis de pessoa. Pode associar rostos a esses perfis e associar novas imagens faciais a pessoas conhecidas. Esta configuração suporta tanto a correspondência flexível de rostos como o reconhecimento de identidade entre imagens e vídeos.

Recomendação de armazenamento de dados

Para acesso seguro e escalável, armazene imagens de rostos no Armazenamento de Blobs do Azure. Ao realizar chamadas de API, certifique-se de que as URLs faciais fazem referência a essas imagens armazenadas.

Matrícula

A inscrição envolve os seguintes passos:

1. Criar um diretório de pessoas vazio
2. Adicionar pessoas
3. Adicione rostos e associe-os a uma pessoa

Criar um diretório de pessoas vazio

Para criar um novo diretório de pessoas, envie um PUT pedido para o endpoint da API. Este diretório serve como recipiente 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 único, definido pelo utilizador, para o diretório dentro do recurso.
• description: (Opcional) Uma breve descrição do propósito do diretório.
• tags: (Opcional) Pares chave-valor para ajudar a organizar e gerir o diretório.

A API cria o diretório e devolve 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 gerir pessoas, precisa de criar um perfil. Uma vez criada, 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 único do diretório criado no Passo 1.
• tags: Pares de chave-valor para descrever a pessoa, como o nome ou a idade.

A API devolve um personId que identifica unicamente a pessoa criada.

200 OK

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

Adiciona rostos e associa-te a uma pessoa

Podes adicionar uma cara ao diretório e, opcionalmente, associá-la a uma pessoa já existente. A API suporta tanto URLs de imagem como 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 único do diretório de pessoas criado no Passo 1.
• faceSource: Especifica a imagem do rosto.
  • url: O caminho do ficheiro da imagem armazenada em Armazenamento de Blobs do Azure.
  • data: Dados de imagem codificados em base64 como alternativa opcional a url.
  • imageReferenceId: (Opcional) Um identificador definido pelo utilizador para a imagem. Este identificador pode ser útil para rastrear a origem da imagem ou para a mapear para outros dados.
  • targetBoundingBox: (Opcional) Localização aproximada do rosto na imagem. Se for omitido, a API deteta e utiliza a maior face.
• qualityThreshold: (Opcional) Filtra a qualidade da face (low, medium, ou high). O padrão é medium, ou seja, apenas as faces de média ou alta qualidade são armazenadas. Faces de qualidade inferior são rejeitadas.
• personId: (Opcional) A personId de uma pessoa já existente para associar o rosto.

A API devolve um faceId que identifica de forma única a face criada com a detetada boundingBox da face.

{
  "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 o seu diretório de pessoas e adicionar imagens faciais com associações opcionais de pessoas, pode realizar duas tarefas principais:

1. Identifique uma pessoa: Compare uma imagem facial com as pessoas inscritas no diretório e determine a identidade mais provável.
2. Encontre rostos semelhantes: Procure rostos visualmente semelhantes em todas as entradas de rostos armazenadas no diretório.

Estas capacidades permitem um reconhecimento facial robusto e a correspondência de similaridade para várias aplicações.

Identificar uma pessoa

Identifique as correspondências mais prováveis comparando a face de entrada com as pessoas registadas 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: O URL da imagem da face de entrada armazenada no Armazenamento de Blobs do Azure.
• faceSource.targetBoundingBox: (Opcional) A caixa delimitadora aproximada da face na imagem. Se for omitido o parâmetro, a API detecta a maior face.
• maxPersonCandidates: (Opcional) O número máximo de candidatos a retornar. O padrão é 1.

A API devolve a caixa delimitadora detectada do rosto juntamente com os principais candidatos.

{
  "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 potenciais correspondências, cada uma com um personId, associado tags, e uma pontuação confidence que indica a probabilidade de correspondência.

Encontre rostos semelhantes

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

A API devolve a caixa delimitadora do rosto detectado, assim como as faces 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 faces semelhantes, cada uma com uma pontuação 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 o Azure Content Understanding nas soluções de vídeo (pré-visualização) da Foundry Tools.