Niestandardowy wektoryzator interfejsu API sieci Web

Note

Wyszukiwanie AI platformy Azure jest dostępna za pośrednictwem portalu Azure, interfejsów API REST i Azure SDKs. Jest także podstawą Foundry IQ — zarządzanej warstwy wiedzy, która przekształca treści przedsiębiorstwa w bazy wiedzy wielokrotnego użytku z uwzględnieniem uprawnień dla agentów w portalu Microsoft Foundry.

Wektoryfikator niestandardowego internetowego interfejsu API umożliwia skonfigurowanie zapytań wyszukiwania w celu wywołania internetowego punktu końcowego interfejsu API, który generuje osadzanie w czasie zapytania. Wymagana struktura ładunku JSON dla punktu końcowego została opisana w dalszej części tego artykułu. Dane są przetwarzane w regionie, w którym wdrożono model.

Mimo że wektoryzatory są używane w czasie wykonywania zapytania, należy określić je w definicjach indeksu i odwoływać się do nich w polach wektorów za pośrednictwem profilu wektorowego. Aby uzyskać więcej informacji, zobacz Konfigurowanie wektoryzatora w indeksie wyszukiwania.

Niestandardowy webowy wektorizer API jest wywoływany jako WebApiVectorizer w interfejsie REST API. Użyj najnowszej stabilnej wersji Indexes - Create (REST API) lub pakietu Azure SDK, który udostępnia tę funkcję.

Parametry wektoryzatora

Parametry są rozróżniane ze względu na wielkość liter.

Nazwa parametru	opis
`uri`	URI internetowego interfejsu API, do którego są wysyłane dane JSON. Dozwolony jest tylko schemat identyfikatora URI https. Po pobraniu indeksu za pomocą polecenia GET usługa zwraca wartość parametru zapytania `?code=` jako `?code=<redacted>`, aby zapobiec ujawnieniu kluczy funkcji. Aby zaktualizować wektoryzator bez zmiany przechowywanego identyfikatora URI, ustaw wartość `uri<unchanged>`.
`httpMethod`	Metoda używana do wysyłania ładunku. Dozwolone metody to `PUT` lub `POST`.
`httpHeaders`	Kolekcja par klucz-wartość, w których klucze są nazwami nagłówków i wartościami są wysyłane do internetowego interfejsu API. Następujące nagłówki są zabronione: `Accept`, , `Accept-Charset`, `Accept-EncodingContent-LengthContent-TypeCookieHostTEUpgrade`i .`Via` Funkcja GET zwraca wartość `<redacted>` sentinel dla każdej wartości nagłówka. Aby uzyskać informacje o wymaganiach dotyczących aktualizacji, zobacz Aktualizowanie wartości nagłówka po pobraniu.
`authResourceId`	(Opcjonalnie) Ciąg, który, jeśli ustawiono, wskazuje, że ten wektorizer używa tożsamości zarządzanej dla połączenia z funkcją lub aplikacją hostująca kod. Ta właściwość przyjmuje identyfikator aplikacji (ID klienta) lub rejestrację aplikacji w Microsoft Entra ID w jednym z następujących formatów: `api://<appId>`, `<appId>/.default`, `api://<appId>/.default`. Ta wartość określa zakres tokenu uwierzytelniania pobranego przez potok zapytania i wysyłany za pomocą niestandardowego żądania internetowego interfejsu API do funkcji lub aplikacji. Ustawienie tej właściwości wymaga, aby usługa wyszukiwania była skonfigurowana dla tożsamości zarządzanej, a aplikacja funkcji Azure była skonfigurowana dla logowania Microsoft Entra.
`authIdentity`	(Opcjonalnie) Tożsamość zarządzana przez użytkownika używana przez search service do łączenia się z funkcją lub aplikacją hostująca kod. Można użyć tożsamości zarządzanej przez system lub tożsamości zarządzanej przez użytkownika. Aby użyć tożsamości zarządzanej przez system, pozostaw `authIdentity` wartość pustą.
`timeout`	(Opcjonalnie) Limit czasu klienta HTTP wywołującego interfejs API. Musi być sformatowana jako wartość XSD `dayTimeDuration` (ograniczony podzestaw wartości czasu trwania ISO 8601 ). Na przykład `PT60S` oznacza 60 sekund. Jeśli nie zostanie ustawiona, wartość domyślna to 30 sekund. Czas wyczekiwania może wynosić od 1 do 230 sekund.

Obsługiwane typy zapytań wektorowych

Wektoryfikator niestandardowego internetowego interfejsu API obsługuje text, imageUrl, i imageBinary zapytania wektorów.

Przykładowa definicja

"vectorizers": [
    {
        "name": "my-custom-web-api-vectorizer",
        "kind": "customWebApi",
        "customWebApiParameters": {
            "uri": "https://contoso.embeddings.com",
            "httpMethod": "POST",
            "httpHeaders": {
                "api-key": "<your-header-value>"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        }
    }
]

Aktualizowanie wartości nagłówka po pobraniu

Po pobraniu definicji indeksu usługa zwraca sentinel <redacted> dla każdej httpHeaders wartości w wektory niestandardowego internetowego interfejsu API. Przykład:

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<redacted>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}

Aby ponownie użyć przechowywanej api-key wartości, zaktualizuj ten sam istniejący wektoryzator przy użyciu tej samej name wartości i kindpozostaw niezmienioną uri wartość i ponownie prześlij sentinel dla pasującej nazwy nagłówka:

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<redacted>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}

Bez zmian urimożna mieszać <redacted> wartości zachowanych nagłówków z rzeczywistymi wartościami zastępczymi dla innych istniejących nagłówków. Podaj rzeczywistą wartość dla każdego dodanego lub zmienionego nagłówka, ponieważ sentinel ma zastosowanie tylko do istniejącego nagłówka o tej samej nazwie w tym samym wektorze.

Jeśli zmienisz wartość uri, podaj rzeczywiste wartości dla każdego httpHeaders wpisu w tej samej aktualizacji. Usługa nie używa ponownie przechowywanych wartości dla innego urielementu :

{
    "name": "my-custom-web-api-vectorizer",
    "kind": "customWebApi",
    "customWebApiParameters": {
        "uri": "https://new.contoso.embeddings.com",
        "httpMethod": "POST",
        "httpHeaders": {
            "api-key": "<new-header-value>"
        },
        "timeout": "PT60S",
        "authResourceId": null,
        "authIdentity": null
    }
}

Jeśli poświadczenia są niedostępne i musisz zmienić urielement , obrócić lub ponownie wygenerować je w zewnętrznym punkcie końcowym. Następnie prześlij razem nowe wartości nagłówka i .uri

Wartość <redacted> jest usługą sentinel, a nie poświadczenie. Nie może utworzyć wektoryzatora ani pobrać ani ponownie użyć wartości nagłówka przechowywanej dla innego wektoryzatora.

Struktura ładunku JSON

Wymagana struktura ładunku JSON dla punktu końcowego używanego z wektoryzatorem Custom Web API jest taka sama jak struktura używana przez umiejętność Custom Web API. Aby uzyskać więcej informacji, zobacz dokumentację umiejętności.

Podczas wdrażania punktu końcowego interfejsu Web API dla niestandardowego wektoryzatora Web API należy pamiętać o następujących kwestiach:

Wektoryzator wysyła tylko jeden rekord w tablicy values jednocześnie podczas wysyłania żądania do punktu końcowego.
Wektoryzator przekazuje dane do wektoryzacji w kluczu data w określonym obiekcie JSON w ładunku żądania. Ten klucz to text, imageUrllub imageBinary, w zależności od żądanego typu zapytania wektorowego.
Wektoryzator oczekuje, że wynikowe osadzenie znajdzie się pod kluczem vector w obiekcie JSON data w danych odpowiedzi.
Wektoryzator ignoruje wszelkie błędy lub ostrzeżenia zwrócone przez punkt końcowy. Te błędy i ostrzeżenia nie są dostępne do debugowania w czasie wykonywania zapytań.

Jeśli zażądano zapytania wektorowego imageBinary , ładunek żądania wysłany do punktu końcowego jest następujący:

{
    "values": [
        {
            "recordId": "0",
            "data":
            {
                "imageBinary": {
                    "data": "<base 64 encoded image binary data>"
                }
            }
        }
    ]
}

Zobacz też

Opinia

Czy ta strona była pomocna?

Last updated on 2026-08-13