Esercitazione: Creare una rubrica per persone ("anteprima")

Una directory delle persone offre un approccio strutturato all'archiviazione dei dati dei visi per le attività di riconoscimento. Consente di aggiungere singoli visi, cercare visi visivamente simili e creare profili di persona. È possibile associare i visi a questi profili e associare nuove immagini del viso a persone note. Questa configurazione supporta sia il riconoscimento flessibile dei volti che il riconoscimento delle identità tra immagini e video.

Raccomandazione per l'archiviazione dei dati

Per l'accesso sicuro e scalabile, archiviare le immagini del viso in Archiviazione BLOB di Azure. Quando si effettuano chiamate API, assicurarsi che gli URL delle immagini dei volti facciano riferimento a tali immagini archiviate.

Iscrizione

La registrazione prevede i passaggi seguenti:

1. Crea una rubrica vuota
2. Aggiungere persone
3. Aggiungere volti e associarli a una persona

Creare una rubrica vuota

Per creare un nuovo elenco di persone, inviare una richiesta all'API endpoint. Questa directory funge da contenitore per l'archiviazione dei visi e delle persone associate.

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: identificatore univoco definito dall'utente per la directory all'interno della risorsa.
• description: (Facoltativo) Breve descrizione dello scopo della directory.
• tags: (Facoltativo) Coppie chiave-valore per organizzare e gestire la directory.

L'API crea la directory e restituisce una risposta di conferma.

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
}

Aggiungere persone

Per riconoscere o gestire le persone, è necessario creare un profilo di persona. Dopo la creazione, è possibile associare i visi a questa persona.

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

{
  "tags": {
    "name": "Alice",
    "employeeId": "E12345"
  }
}

• personDirectoryId: identificatore univoco della directory creata nel passaggio 1.
• tags: coppie chiave-valore per descrivere la persona, ad esempio il nome o l'età.

L'API restituisce un oggetto personId che identifica in modo univoco la persona creata.

200 OK

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

Aggiungi volti e associa a una persona

È possibile aggiungere un viso alla directory e, facoltativamente, associarlo a una persona esistente. L'API supporta sia gli URL delle immagini che i dati dell'immagine con codifica 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: identificatore univoco della directory person creata nel passaggio 1.
• faceSource: specifica l'immagine del viso.
  • url: percorso del file dell'immagine archiviato in Archiviazione BLOB di Azure.
  • data: dati immagine con codifica Base64 come alternativa facoltativa a url.
  • imageReferenceId: (Facoltativo) Identificatore definito dall'utente per l'immagine. Questo identificatore può essere utile per tenere traccia dell'origine dell'immagine o per eseguire il mapping ad altri dati.
  • targetBoundingBox: (Facoltativo) Posizione approssimativa del viso nell'immagine. Se omesso, l'API rileva e usa il viso più grande.
• qualityThreshold: (Facoltativo) Filtra la qualità del viso (low, mediumo high). Il valore predefinito è medium, ovvero vengono archiviati solo i visi di media o alta qualità. I volti di qualità inferiore vengono rifiutati.
• personId: (Facoltativo) Il personId di una persona esistente con cui associare il volto.

L'API restituisce un oggetto faceId che identifica in modo univoco il viso creato con il viso rilevato boundingBox .

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

Utilizzare la rubrica dei contatti

Dopo aver creato la directory della persona e aver aggiunto immagini del viso con associazioni di persone facoltative, è possibile eseguire due attività principali:

1. Identificare una persona: associare un'immagine del viso a persone registrate nella directory e determinare l'identità più probabile.
2. Trovare visi simili: cercare visi visivamente simili in tutte le voci del viso archiviate nella directory.

Queste funzionalità consentono un solido riconoscimento facciale e una corrispondenza di somiglianza per varie applicazioni.

Identificare una persona

Identificare gli abbinamenti della persona più probabile confrontando il volto fornito con le persone registrate nella directory.

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 dell'immagine del viso di input archiviata in Archiviazione BLOB di Azure.
• faceSource.targetBoundingBox: (Facoltativo) Il riquadro di delimitazione approssimativo del viso nell'immagine. Se omesso, l'API rileva il viso più grande.
• maxPersonCandidates: (Facoltativo) Il numero massimo di candidati persona da restituire. Il valore predefinito è 1.

L'API restituisce il rettangolo delimitatore del viso rilevato insieme ai migliori candidati.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "personCandidates": [
    {
      "personId": "{personId1}",
      "tags": {
        "name": "Alice",
        "employeeId": "E12345"
      },
      "confidence": 0.92
    }
  ]
}

• detectedFace.boundingBox: riquadro delimitatore del viso rilevato nell'immagine di input.
• personCandidates: elenco di potenziali corrispondenze, ognuna con un personIdoggetto , associato tagse un confidence punteggio che indica la probabilità di una corrispondenza.

Trovare visi simili

Trova facce simili tra tutte le voci facciali archiviate nella directory.

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 dell'immagine del viso di input archiviata in Archiviazione BLOB di Azure.
• faceSource.targetBoundingBox: (Facoltativo) La rappresentazione approssimativa dell'area del viso nell'immagine. Se omesso, l'API rileva il viso più grande.
• maxSimilarFaces: (Facoltativo) Numero massimo di visi simili da restituire. Il valore predefinito è 1000, con un limite massimo di 1000.

L'API fornisce il riquadro di delimitazione rilevato del volto insieme ai volti più simili della directory.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "similarFaces": [
    {
      "faceId": "{faceId}",
      "boundingBox": { ... },
      "confidence": 0.92,
      "imageReferenceId": "face.jpg"
    }
  ]
}

• detectedFace.boundingBox: Il riquadro delimitatore del viso rilevato nell'immagine di input.
• similarFaces: un elenco di visi simili, ognuno con un punteggio faceId, boundingBox, confidence e un imageReferenceId che indica l'immagine di origine.

Passaggio successivo

Esplora come identificare gli individui nel contenuto video usando Azure Comprensione dei contenuti nelle soluzioni video di Foundry Tools (anteprima).