Udostępnij przez

Samouczek: tworzenie katalogu osób (wersja zapoznawcza)

Katalog osób zapewnia ustrukturyzowane podejście do przechowywania danych twarzy na potrzeby zadań rozpoznawania. Umożliwia dodawanie pojedynczych twarzy, wyszukiwanie wizualnie podobnych twarzy i tworzenie profilów osób. Możesz skojarzyć twarze z tymi profilami i dopasować nowe obrazy twarzy do znanych osób. Ta konfiguracja obsługuje zarówno elastyczne dopasowywanie twarzy, jak i rozpoznawanie tożsamości w obrazach i filmach.

Diagram ilustrujący procesy rejestracji i wyszukiwania w katalogu osób.

Zalecenie dotyczące magazynu danych

W celu zapewnienia bezpiecznego i skalowalnego dostępu zalecamy przechowywanie wszystkich obrazów twarzy w usłudze Azure Blob Storage. Podczas wykonywania wywołań interfejsu API upewnij się, że adresy URL twarzy odwołują się do tych przechowywanych obrazów w usłudze Blob Storage.

Rejestrowanie

Rejestracja obejmuje następujące kroki:

  1. Tworzenie pustego katalogu osób
  2. Dodawanie osób
  3. Dodawanie twarzy i kojarzenie z osobą

Tworzenie pustego katalogu osób

Aby utworzyć nowy katalog osób, wyślij PUT żądanie do punktu końcowego interfejsu API. Ten katalog służy jako kontener do przechowywania twarzy i skojarzonych osób.

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: unikatowy, zdefiniowany przez użytkownika identyfikator katalogu w ramach zasobu.
  • description: (Opcjonalnie) Krótki opis przeznaczenia katalogu.
  • tags: (Opcjonalnie) Pary klucz-wartość ułatwiające organizowanie katalogu i zarządzanie nim.

Interfejs API tworzy katalog i zwraca odpowiedź potwierdzającą.

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
}

Dodawanie osób

Aby rozpoznawać osoby lub zarządzać nimi, musisz utworzyć profil osoby. Po utworzeniu możesz skojarzyć twarze z tą osobą.

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

{
  "tags": {
    "name": "Alice",
    "employeeId": "E12345"
  }
}
  • personDirectoryId: unikatowy identyfikator katalogu utworzonego w kroku 1.
  • tags: Pary klucz-wartość do opisania osoby, jak na przykład jej imię lub wiek.

Interfejs API zwraca personId, który jednoznacznie identyfikuje utworzoną osobę.

200 OK

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

Dodawanie twarzy i kojarzenie z osobą

Możesz dodać twarz do katalogu i opcjonalnie skojarzyć ją z istniejącą osobą. Interfejs API obsługuje zarówno adresy URL obrazów, jak i dane obrazu zakodowane w formacie 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: unikatowy identyfikator katalogu osób utworzonego w kroku 1.
  • faceSource: określa obraz twarzy.
    • url: ścieżka pliku obrazu przechowywanego w usłudze Azure Blob Storage.
    • data: Dane obrazu zakodowane w formacie Base64 jako opcjonalna alternatywa do url.
    • imageReferenceId: (Opcjonalnie) Identyfikator zdefiniowany przez użytkownika dla obrazu. Ten identyfikator może być przydatny do śledzenia źródła obrazu lub mapowania go na inne dane.
    • targetBoundingBox: (Opcjonalnie) Przybliżona lokalizacja twarzy na obrazie. W przypadku pominięcia tego elementu, interfejs API wykrywa i korzysta z największej twarzy.
  • qualityThreshold: (Opcjonalnie) Filtruje jakość twarzy (low, medium, lub high). Wartość domyślna to medium, co oznacza, że przechowywane są tylko średnie lub wysokiej jakości twarze. Twarze niższej jakości są odrzucane.
  • personId: (Opcjonalnie) personId istniejącej osoby, z którą chcesz skojarzyć twarz.

Interfejs API zwraca element faceId , który jednoznacznie identyfikuje utworzoną twarz z wykrytą boundingBox twarzą.

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

Korzystanie z katalogu osób

Po utworzeniu katalogu osób i dodaniu obrazów twarzy z opcjonalnymi skojarzeniami osób można wykonać dwa kluczowe zadania:

  1. Zidentyfikuj osobę: dopasuj obraz twarzy do zarejestrowanych osób w katalogu i określ najbardziej prawdopodobną tożsamość.
  2. Znajdź podobne twarze: wyszukaj wizualnie podobne twarze we wszystkich przechowywanych wpisach twarzy w katalogu.

Te możliwości umożliwiają niezawodne rozpoznawanie twarzy i dopasowywanie podobieństw dla różnych aplikacji.

Diagram ilustrujący procesy wyszukiwania w katalogu osób.

Identyfikowanie osoby

Zidentyfikuj najbardziej prawdopodobne dopasowania osób, porównując wzorzec twarzy z zarejestrowanymi osobami w rejestrze.

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: adres URL wejściowego obrazu twarzy przechowywanego w usłudze Azure Blob Storage.
  • faceSource.targetBoundingBox: (Opcjonalnie) Przybliżone pole ograniczenia twarzy na obrazie. W przypadku pominięcia interfejs API wykryje największą twarz.
  • maxPersonCandidates: (Opcjonalnie) Maksymalna liczba kandydatów do zwrócenia. Wartość domyślna to 1.

Interfejs API zwraca wykryte pole ograniczenia twarzy wraz z kandydatami najwyższej osoby.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "personCandidates": [
    {
      "personId": "{personId1}",
      "tags": {
        "name": "Alice",
        "employeeId": "E12345"
      },
      "confidence": 0.92
    }
  ]
}
  • detectedFace.boundingBox: Obramowanie wykrytej twarzy na obrazie wejściowym.
  • personCandidates: lista potencjalnych dopasowań, każda z personId, skojarzonym tags oraz wynikiem confidence wskazującym prawdopodobieństwo dopasowania.

Wyszukiwanie podobnych twarzy

Znajdź wizualnie podobne twarze ze wszystkich przechowywanych wpisów dotyczących twarzy w katalogu.

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: adres URL wejściowego obrazu twarzy przechowywanego w usłudze Azure Blob Storage.
  • faceSource.targetBoundingBox: (Opcjonalnie) Przybliżone pole ograniczenia twarzy na obrazie. W przypadku pominięcia interfejs API wykryje największą twarz.
  • maxSimilarFaces: Maksymalna liczba zwracanych podobnych twarzy (opcjonalnie). Wartość domyślna to 1000 z maksymalnym limitem wynoszącym 1000.

Interfejs API zwraca wykryte pole ograniczenia twarzy wraz z najbardziej podobnymi twarzami z katalogu.

{
  "detectedFace": {
    "boundingBox": { ... }
  },
  "similarFaces": [
    {
      "faceId": "{faceId}",
      "boundingBox": { ... },
      "confidence": 0.92,
      "imageReferenceId": "face.jpg"
    }
  ]
}
  • detectedFace.boundingBox: Obramowanie wykrytej twarzy na obrazie wejściowym.
  • similarFaces: Lista podobnych twarzy, z których każda ma faceId, boundingBox, confidence wynik oraz imageReferenceId wskazujący obraz źródłowy.

Następny krok

Dowiedz się, jak identyfikować osoby w zawartości wideo przy użyciu usługi Azure Content Understanding w rozwiązaniach wideo narzędzi Foundry Tools (wersja zapoznawcza).

  • Last updated on