Face Recognition Operations - Find Similar From Large Face List

Usługa:

Azure AI Services

Wersja interfejsu API:

v1.2-preview.1

Podane faceId twarzy zapytania, aby wyszukać podobne twarze z listy dużych twarzy. Element "largeFaceListId" jest tworzony przez tworzenie dużej listy twarzy.
W zależności od danych wejściowych zwrócona lista podobnych twarzy zawiera identyfikatory faceId lub utrwalone IdentyfikatoryFaceId sklasyfikowane według podobieństwa.

Funkcja Znajdź podobne ma dwa tryby robocze: "matchPerson" i "matchFace". "matchPerson" jest trybem domyślnym, który próbuje znaleźć twarze tej samej osoby, jak to możliwe przy użyciu wewnętrznych progów tej samej osoby. Warto znaleźć inne zdjęcia znanej osoby. Należy pamiętać, że pusta lista zostanie zwrócona, jeśli żadne twarze nie przejdą do progów wewnętrznych. Tryb "matchFace" ignoruje progi osób tej samej osoby i mimo to zwraca podobne twarze, nawet podobieństwo jest niskie. Może być używany w przypadkach, takich jak wyszukiwanie twarzy wyglądające na celebrytów.

Element "recognitionModel" skojarzony z identyfikatorem faceId zapytania powinien być taki sam jak element "recognitionModel" używany przez docelową listę dużych twarzy.

POST {endpoint}/face/{apiVersion}/findsimilars

Parametry identyfikatora URI

Nazwa	W	Wymagane	Typ	Opis
apiVersion	path	True	string	Wersja interfejsu API
endpoint	path	True	string uri	Obsługiwane punkty końcowe usług Cognitive Services (protokół i nazwa hosta, na przykład: https://{nazwa-zasobu}.cognitiveservices.azure.com).

Treść żądania

Nazwa	Wymagane	Typ	Opis
faceId	True	string	faceId twarzy zapytania. Użytkownik musi najpierw wywołać metodę "Detect", aby uzyskać prawidłowy identyfikator faceId. Pamiętaj, że ten identyfikator faceId nie jest utrwalone i wygaśnie 24 godziny po wywołaniu wykrywania.
largeFaceListId	True	string	Istniejąca określona przez użytkownika unikatowa lista dużych twarzy utworzona w obszarze "Tworzenie dużej listy twarzy". Duża lista twarzy zawiera zestaw utrwałych identyfikatorówFaceId, które są utrwalane i nigdy nie wygasają.
maxNumOfCandidatesReturned		integer	Liczba zwróconych pierwszych podobnych twarzy. Prawidłowy zakres to [1, 1000]. Wartość domyślna to 20.
mode		FindSimilarMatchMode	Podobny tryb wyszukiwania twarzy. Może to być "matchPerson" lub "matchFace". Wartość domyślna to "matchPerson".

Odpowiedzi

Nazwa	Typ	Opis
200 OK	FindSimilarResult[]	Pomyślne wywołanie zwraca tablicę najbardziej podobnych twarzy reprezentowanych w faceId, jeśli parametr wejściowy to faceId lub utrwaloneFaceId, jeśli parametr wejściowy to faceListId lub largeFaceListId.
Other Status Codes	FaceErrorResponse	Nieoczekiwana odpowiedź na błąd. Nagłówki x-ms-error-code: string

Zabezpieczenia

Ocp-Apim-Subscription-Key

Klucz tajny subskrypcji rozpoznawania twarzy w usłudze Azure AI.

Typ: apiKey
W: header

AADToken

Przepływ OAuth2 usługi Azure Active Directory

Typ: oauth2
Flow: accessCode
Adres URL autoryzacji: https://api.example.com/oauth2/authorize
Adres URL tokenu: https://api.example.com/oauth2/token

Zakresy

Nazwa	Opis
https://cognitiveservices.azure.com/.default

Przykłady

Find Similar from LargeFaceList

Przykładowe żądanie

HTTP

POST {endpoint}/face/v1.2-preview.1/findsimilars

{
  "faceId": "c5c24a82-6845-4031-9d5d-978df9175426",
  "maxNumOfCandidatesReturned": 3,
  "mode": "matchPerson",
  "largeFaceListId": "your_large_face_list_id"
}

Przykładowa odpowiedź

Kod stanu:

200

[
  {
    "confidence": 0.8,
    "faceId": "015839fb-fbd9-4f79-ace9-7675fc2f1dd9"
  }
]

Definicje

Nazwa	Opis
FaceError	Obiekt błędu. Aby uzyskać szczegółowe informacje na temat kodów błędów i komunikatów zwracanych przez usługę rozpoznawania twarzy, zapoznaj się z następującym linkiem: https://aka.ms/face-error-codes-and-messages.
FaceErrorResponse	Odpowiedź zawierająca szczegóły błędu.
FindSimilarResult	Treść odpowiedzi w celu znalezienia podobnej operacji twarzy.

FaceError

Obiekt błędu. Aby uzyskać szczegółowe informacje na temat kodów błędów i komunikatów zwracanych przez usługę rozpoznawania twarzy, zapoznaj się z następującym linkiem: https://aka.ms/face-error-codes-and-messages.

Nazwa	Typ	Opis
code	string	Jeden z zdefiniowanych przez serwer zestaw kodów błędów.
message	string	Czytelna dla człowieka reprezentacja błędu.

FaceErrorResponse

Odpowiedź zawierająca szczegóły błędu.

Nazwa	Typ	Opis
error	FaceError	Obiekt błędu.

FindSimilarResult

Treść odpowiedzi w celu znalezienia podobnej operacji twarzy.

Nazwa	Typ	Opis
confidence	number	Wartość zaufania kandydata. Im większa pewność siebie, tym bardziej podobna. Zakres między [0,1].
faceId	string	faceId twarzy kandydata w przypadku znalezienia przez faceIds. FaceId jest tworzony przez funkcję "Detect" i wygaśnie 24 godziny po wywołaniu wykrywania.
persistedFaceId	string	persistedFaceId twarzy kandydata w przypadku znalezienia według faceListId lub largeFaceListId. persistedFaceId na liście twarzy/dużej liście twarzy jest utrwalone i nie wygaśnie.