Delen via

Aangepaste web-API-vectorizer

  • Artikel

Met de aangepaste web-API-vectorizer kunt u uw zoekquery's configureren om aan te roepen bij een web-API-eindpunt voor het genereren van insluitingen op het moment van query's. De structuur van de JSON-nettolading die in het opgegeven eindpunt moet worden geïmplementeerd, wordt verderop in dit document beschreven. Uw gegevens worden verwerkt in de geografische locatie waar uw model wordt geïmplementeerd.

Vectorizers worden gebruikt tijdens het uitvoeren van query's, maar opgegeven in indexdefinities en waarnaar wordt verwezen op vectorvelden via een vectorprofiel. De aangepaste web-API-vectorizer wordt aangeroepen WebApiVectorizer in de API.

Vectorizer-parameters

Parameters zijn hoofdlettergevoelig.

Parameternaam Beschrijving
uri De URI van de web-API waarnaar de JSON-nettolading wordt verzonden. Alleen het https-URI-schema is toegestaan.
httpMethod De methode die moet worden gebruikt tijdens het verzenden van de nettolading. Toegestane methoden zijn PUT of POST
httpHeaders Een verzameling sleutel-waardeparen waarbij de sleutels headernamen en -waarden vertegenwoordigen headerwaarden die samen met de nettolading naar uw web-API worden verzonden. De volgende headers mogen niet in deze verzameling voorkomen: Accept, , Accept-Charset, Accept-Encoding, Content-Length, Content-TypeCookie, , Host, , TE, , Upgrade, . Via
authResourceId (Optioneel) Een tekenreeks die, indien ingesteld, aangeeft dat deze vectorizer een beheerde identiteit moet gebruiken voor de verbinding met de functie of app die als host fungeert voor de code. Deze eigenschap gebruikt een toepassings-id (client) of app-registratie in Microsoft Entra ID, in een van deze indelingen: api://<appId>, <appId>/.default, api://<appId>/.default. Deze waarde wordt gebruikt om het verificatietoken te bepalen dat is opgehaald door de indexeerfunctie en wordt samen met de aangepaste web-API-aanvraag naar de functie of app verzonden. Als u deze eigenschap instelt, moet uw zoekservice zijn geconfigureerd voor beheerde identiteit en is uw Azure-functie-app geconfigureerd voor een Microsoft Entra-aanmelding.
authIdentity (Optioneel) Een door de gebruiker beheerde identiteit die door de zoekservice wordt gebruikt om verbinding te maken met de functie of app die als host fungeert voor de code. U kunt een door het systeem beheerde identiteit of een door de gebruiker beheerde identiteit gebruiken. Als u een door het systeem beheerde identiteit wilt gebruiken, laat u authIdentity leeg.
timeout (Optioneel) Wanneer dit is opgegeven, geeft u de time-out aan voor de HTTP-client die de API-aanroep maakt. Deze moet worden opgemaakt als een XSD-waarde 'dayTimeDuration' (een beperkte subset van een ISO 8601-duurwaarde ). Bijvoorbeeld PT60S gedurende 60 seconden. Als dit niet is ingesteld, wordt een standaardwaarde van 30 seconden gekozen. De time-out kan worden ingesteld op maximaal 230 seconden en minimaal 1 seconde.

Ondersteunde vectorquerytypen

De Custom Web API vectorizer ondersteunt text, imageUrlen imageBinary vectorquery's.

Voorbeelddefinitie

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

JSON-nettoladingstructuur

De vereiste JSON-nettoladingstructuur die wordt verwacht voor een eindpunt wanneer deze wordt gebruikt met de aangepaste web-API vectorizer, is hetzelfde als die van de aangepaste web-API-vaardigheid, die in meer detail wordt besproken in de documentatie voor de vaardigheid.

Er zijn de volgende andere overwegingen die u moet maken bij het implementeren van een web-API-eindpunt voor gebruik met de aangepaste web-API-vectorizer.

  • De vectorizer verzendt slechts één record tegelijk in de matrix bij het values indienen van een aanvraag naar het eindpunt.

  • De vectorizer geeft de gegevens door die moeten worden gevectoriseerd in een specifieke sleutel in het data JSON-object in de nettolading van de aanvraag. Deze sleutel is text, imageUrlof imageBinary, afhankelijk van welk type vectorquery is aangevraagd.

  • De vectorizer verwacht dat de resulterende insluiting onder de vector sleutel in het data JSON-object in de nettolading van het antwoord staat.

  • Eventuele fouten of waarschuwingen die door het eindpunt worden geretourneerd, worden genegeerd door de vectorizer en kunnen niet worden verkregen voor foutopsporingsdoeleinden tijdens de query.

  • Als er een imageBinary vectorquery is aangevraagd, is de nettolading van de aanvraag die naar het eindpunt is verzonden het volgende:

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

Zie ook