Vlastní vektorizátor webového rozhraní API

Vektorizátor Custom Web API umožňuje konfigurovat vyhledávací dotazy pro volání endpointu webového rozhraní API, který generuje embeddingy v době dotazu. Požadovaná struktura datové části JSON pro koncový bod je popsaná dále v tomto článku. Vaše data se zpracovávají v geografii kde je váš model nasazený.

I když se vektorizátory používají v době dotazu, zadáte je v definicích indexu a odkazujete na ně na vektorová pole prostřednictvím vektorového profilu. Další informace naleznete v tématu Konfigurace vektorizátoru v indexu vyhledávání.

Vlastní vektorizátor webového rozhraní API se volá WebApiVectorizer v rozhraní REST API. Použijte nejnovější stabilní verzi Indexes – Create (REST API) nebo balíček sady AZURE SDK, který tuto funkci poskytuje.

Parametry vektorizátoru

Parametry jsou citlivé na velikost písmen.

Podporované typy vektorových dotazů

Vektorizátor vlastního webového rozhraní API podporuje text, imageUrl a imageBinary vektorové dotazy.

Ukázková definice

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

Aktualizujte hodnoty hlaviček po příkazu GET

Když načtete definici indexu pomocí GET nebo vypíšete indexy pomocí LIST, služba vrátí <redacted> pro každou hodnotu httpHeaders ve vektorizátoru vlastního webového rozhraní API. Příklady:

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

Chcete-li znovu použít uloženou api-key hodnotu, aktualizujte stejný existující vektorizátor se stejným nameparametrem , kinda koncovým bodem. Znovu odešlete vrácený zástupný text pro odpovídající název záhlaví:

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

Pro stejný existující vektorizátor a koncový bod můžete kombinovat <redacted> nebo <unchanged> pro zachované hodnoty záhlaví se skutečnými náhradními hodnotami. Explicitní hodnoty mají přednost před zástupnými symboly. Zadejte skutečnou hodnotu pro každé přidané nebo přejmenované záhlaví, protože zástupný symbol vyžaduje jednoznačný existující zdroj. Informace o změnách dotazů URI najdete v tématu Odstranění citlivých údajů z URI a aktualizace zachovávající přihlašovací údaje.

Pokud změníte koncový bod, zadejte ve stejné aktualizaci skutečný identifikátor URI a tajné údaje v hlavičkách. Služba opakovaně nepoužívá uložené tajné údaje pro jiný koncový bod:

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

Pokud jsou přihlašovací údaje nedostupné a musíte změnit koncový bod, obměňte je nebo je znovu vygenerujte na externím koncovém bodu. Pak společně odešlete novou hodnotu uri a hodnoty záhlaví.

Hodnota <redacted> je sentinel služby, nikoli přihlašovací údaj. Nemůže vytvořit vektorizátor ani načíst nebo znovu použít hodnotu hlavičky uloženou pro jiný vektorizátor.

Maskování URI a aktualizace se zachováním přihlašovacích údajů

Toto chování dotazu URI platí pro všechny verze rozhraní API.

Když pomocí GET načtete index nebo pomocí LIST vypíšete indexy, Azure AI Vyhledávač rediguje citlivé hodnoty parametrů dotazu URI vlastního webového rozhraní API, včetně sig a code, a hodnoty hlaviček HTTP. Tyto skryté hodnoty chrání signatury SAS, klíče funkcí a přihlašovací údaje v hlavičkách.

Pokud chcete zachovat uložené tajné údaje, aktualizujte stejný existující prostředek a koncový bod. Odešlete vrácené <redacted> nebo <unchanged> zástupné symboly v požadavku PUT pro správu. Tato operace PUT aktualizuje definici indexu; nejedná se o vyvolání koncového bodu řízené vektorizátorem httpMethod. Můžete také nastavit celé <unchanged> na uri, aby se zachoval uložený identifikátor URI.

Tajné hodnoty se nepřenášejí do jiného koncového bodu ani nekopírují do nového prostředku. Změna endpointu, klonování anonymizované definice nebo jiné přesměrování prostředku vyžaduje explicitně zadané tajné údaje.

Pokud služba nemůže identifikovat jeden jednoznačný existující zdroj pro zástupný symbol, PUT selže s 400 Bad Request a požádá o skutečnou hodnotu tajného údaje. Nevyřešený nebo ponechaný zástupný symbol není použitelný přihlašovací údaj. Obnovení tajného údaje je atomické: neúspěšné obnovení částečně neprovede změny identifikátoru URI ani hlavičky.

Kdykoli můžete zadat náhradní identifikátor URI nebo tajné klíče záhlaví. Explicitní hodnoty mají přednost před zástupnými symboly.

Aktualizace dotazů URI se řídí těmito pravidly:

• U parametru funkce code Azure můžete aktualizovat další parametry dotazu, které nejsou tajné, a přitom zachovat uložený klíč funkce pro stejný koncový bod.
• U parametru SAS sig je podpis vázán na okolní konfiguraci dotazu, která není tajná. Pokud se změní rozsah, oprávnění, vypršení platnosti, prostředek, verze, pořadí, použití velkých a malých písmen nebo kódování, vytvořte nový podpis. Dokonce i sémanticky ekvivalentní přeuspořádaný nebo překódovaný text dotazu vyžaduje novou signaturu.

Názvy parametrů tajného dotazu jsou rozpoznávány bez ohledu na velikost písmen i když jsou procentuálně kódovány. Služba zachovává reprezentaci identifikátoru URI místo jeho normalizace. Opakované tajné parametry se shodují podle výskytu. Pokud jejich vzor výskytu už není v souladu s uloženým identifikátorem URI, zadejte skutečné hodnoty.

Existující pracovní postupy GET-then-PUT používající <redacted> nebo <unchanged> zůstávají podporované. Příklady hlaviček najdete v tématu Aktualizace hodnot hlaviček po příkazu GET.

Vlastní dovednosti najdete v tématu Skrytí identifikátoru URI dovedností vlastního webového rozhraní API a aktualizace pro zachování přihlašovacích údajů.

Struktura datové části JSON

Požadovaná struktura datové části JSON pro koncový bod použitý s vektorizátorem vlastního webového rozhraní API je stejná jako struktura používaná dovedností vlastního webového rozhraní API. Další informace najdete v dokumentaci ke dovednostem.

Při implementaci koncového bodu webového rozhraní API pro vektorizátor vlastního webového rozhraní API mějte na paměti následující skutečnosti:

• Vektorizátor odesílá v poli values pouze jeden záznam najednou při požadavku na koncový bod.

• Vektorizátor předává data, která se mají vektorizovat v určitém klíči objektu data JSON v datové části požadavku. Tento klíč je text, imageUrlnebo imageBinary, v závislosti na typu vektorového dotazu byl požadován.

• Vektorizátor očekává, že výsledné vkládání bude pod vector klíčem v objektu data JSON v datové části odpovědi.

• Vektorizátor ignoruje všechny chyby nebo upozornění vrácené koncovým bodem. Tyto chyby a upozornění nejsou k dispozici pro ladění v době dotazu.

• Pokud byl požadován vektorový imageBinary dotaz, datová část požadavku odeslaná do koncového bodu je následující:

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

Viz také

• Integrovaná vektorizace
• Postup konfigurace vektorizátoru v indexu vyhledávání
• Vlastní dovednosti webového rozhraní API