Niestandardowy wektoryzator interfejsu API sieci Web

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.

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 żądaniu GET

Gdy pobierasz definicję indeksu za pomocą GET lub wyświetlasz indeksy za pomocą LIST, usługa zwraca <redacted> dla każdej wartości httpHeaders w niestandardowym wektoryzatorze 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 tego samego nameelementu , kindi punktu końcowego. Prześlij ponownie zwrócony symbol zastępczy 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
    }
}

Dla tego samego istniejącego wektoryzatora i punktu końcowego można mieszać <redacted> lub <unchanged> dla zachowanych wartości nagłówka z rzeczywistymi wartościami zastępczymi. Jawne wartości mają pierwszeństwo przed symbolami zastępczymi. Podaj rzeczywistą wartość dla każdego dodanego nagłówka lub nagłówka o zmienionej nazwie, ponieważ symbol zastępczy wymaga jednoznacznego istniejącego źródła. Aby uzyskać informacje na temat zmian w zapytaniu URI, zobacz Redagowanie identyfikatorów URI i aktualizacje zachowujące poświadczenia.

Jeśli zmienisz endpoint, podaj rzeczywisty URI i sekrety nagłówka w tej samej aktualizacji. Usługa nie używa ponownie przechowywanych sekretów dla innego punktu końcowego:

{
    "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 dane uwierzytelniające są niedostępne i musisz zmienić punkt końcowy, przeprowadzić rotację lub ponownie je wygenerować w zewnętrznym punkcie końcowym. Następnie prześlij razem nowe wartości uri i nagłówka.

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

Maskowanie identyfikatorów URI i aktualizacje zachowujące dane logowania

To zachowanie parametru query w identyfikatorze URI dotyczy wszystkich wersji interfejsu API.

Gdy pobierasz indeks za pomocą GET lub wyświetlasz listę indeksów za pomocą LIST, usługa Wyszukiwanie AI platformy Azure ukrywa poufne wartości parametrów zapytania w identyfikatorze URI niestandardowego internetowego interfejsu API, w tym sig, code oraz wartości nagłówków HTTP. Te zanonimizowane wartości chronią sygnatury dostępu współdzielonego (SAS), klucze funkcji i poświadczenia nagłówka.

Aby zachować przechowywane sekrety, zaktualizuj ten sam istniejący zasób i punkt końcowy. Prześlij zwrócone <redacted> lub <unchanged> symbole zastępcze w żądaniu PUT do zarządzania. To żądanie PUT aktualizuje definicję indeksu; nie jest to wywołanie punktu końcowego kontrolowane przez element httpMethod wektoryzatora. Możesz również ustawić całe uri na <unchanged>, aby zachować przechowywany identyfikator URI.

Wartości sekretów nie są przenoszone do innego punktu końcowego ani kopiowane do nowego zasobu. Zmiana punktu końcowego, sklonowanie ocenzurowanej definicji lub ponowne wskazanie zasobu wymaga jawnych sekretów.

Jeśli usługa nie może zidentyfikować jednego jednoznacznego istniejącego źródła dla symbolu zastępczego, funkcja PUT zakończy się niepowodzeniem 400 Bad Request i zażąda rzeczywistej wartości sekretu. Nierozwiązane lub pozostawione symbole zastępcze nie są danymi uwierzytelniającymi do użycia. Przywracanie sekretów jest niepodzielne: jeśli przywracanie się nie powiedzie, nie powoduje częściowego zastosowania zmian identyfikatora URI ani nagłówka.

W dowolnym momencie możesz podać zastępczy identyfikator URI lub sekrety nagłówka. Jawne wartości mają pierwszeństwo przed symbolami zastępczymi.

Aktualizacje zapytań URI są zgodne z następującymi regułami:

• W przypadku parametru Azure Function code można zaktualizować inne parametry zapytania inne niż tajne, zachowując przechowywany klucz funkcji dla tego samego punktu końcowego.
• W przypadku parametru SAS sig sygnatura jest powiązana z otaczającą konfiguracją kwerendy bez wpisu tajnego. Jeśli zmieni się zakres, uprawnienia, wygaśnięcie, zasób, wersja, kolejność, wielkość liter lub kodowanie, podaj nowy podpis. Nawet semantycznie równoważny tekst zapytania o zmienionej kolejności lub ponownie zakodowany wymaga nowego podpisu.

Nazwy parametrów tajnego zapytania są rozpoznawane bez uwzględniania wielkości liter i również po zakodowaniu procentowym. Usługa zachowuje reprezentację identyfikatora URI zamiast go normalizować. Powtarzające się tajne parametry są dopasowywane według wystąpienia. Jeśli wzorzec ich wystąpienia nie jest już zgodny z przechowywanym identyfikatorem URI, podaj rzeczywiste wartości.

Istniejące przepływy pracy GET-then-PUT używające <redacted> lub <unchanged> pozostają obsługiwane. Aby zapoznać się z przykładami nagłówków, zobacz Aktualizowanie wartości nagłówka po metodzie GET.

W przypadku umiejętności niestandardowych zobacz Ukrywanie identyfikatora URI umiejętności niestandardowej usługi Web API i aktualizacje zachowujące poświadczenia.

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ż

• Wektoryzacja zintegrowana
• Jak skonfigurować wektoryzator w indeksie wyszukiwania
• Niestandardowa funkcja web API