Esercitazione: Creare una directory delle 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 dei volti facciano riferimento a quelle immagini archiviate.

Iscrizione

La registrazione prevede i passaggi seguenti:

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

Creare una rubrica persone vuota

Per creare una nuova directory person, inviare una PUT richiesta all'endpoint API. Questa directory funge da contenitore per la memorizzazione dei volti e delle persone correlate.

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"
  }
}

Aggiungere volti e associarli 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) L'personId di una persona esistente a cui associare il viso.

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
  }
}

Usare la directory person

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 un confronto di somiglianza per varie applicazioni.

Identificare una persona

Identificare le corrispondenze più probabili delle persone confrontando il volto fornito con le persone iscritte 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) Rilevamento approssimativo del viso nell'immagine. Se omesso, l'API rileva il viso più grande.
• maxPersonCandidates: (Facoltativo) Numero massimo di candidati persone da restituire. Il valore predefinito è 1.

L'API restituisce il rettangolo di selezione rilevato del viso insieme ai candidati principali.

{
  "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: un elenco di potenziali corrispondenze, ognuna con un personId, un oggetto associato tags e un confidence punteggio che indica la probabilità di una corrispondenza.

Trovare visi simili

Trova volti visivamente simili tra tutte le voci di volti 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) Il riquadro di delimitazione approssimativo del viso nell'immagine. Nel caso in cui venga omesso, l'API rileva il volto più grande.
• maxSimilarFaces: (Facoltativo) Numero massimo di visi simili da restituire. Il valore predefinito è 1000, con un limite massimo di 1000.

L'API restituisce la casella delimitatrice rilevata del volto insieme ai volti più simili dell'archivio.

{
  "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 volti simili, ognuno con un faceId punteggio, boundingBoxconfidence e un imageReferenceId che indica l'immagine di origine.

Passaggio successivo

Esplora come identificare gli individui nel contenuto video usando Azure Content Understanding nelle soluzioni video di Foundry Tools (anteprima).