Aangepaste web-API-vectorisator

Note

Azure AI Zoeken is beschikbaar via de Azure-portal, REST API's en Azure-SDK's. Het vormt ook een basis voor Foundry IQ, de beheerde kennislaag die bedrijfsinhoud transformeert in herbruikbare, machtigingsbewuste knowledge bases voor agents in de Microsoft Foundry-portal.

Met de Aangepaste web-API-vectorizer kunt u zoekquery's configureren om een web-API-eindpunt aan te roepen waarmee insluitingen worden gegenereerd tijdens de query. De vereiste JSON-nettoladingstructuur voor het eindpunt wordt verderop in dit artikel beschreven. Uw gegevens worden verwerkt in de geography waar uw model wordt geïmplementeerd.

Hoewel vectorizers tijdens query's worden gebruikt, geeft u deze op in indexdefinities en verwijst u ernaar op vectorvelden via een vectorprofiel. Zie Een vectorizer configureren in een zoekindex voor meer informatie.

De aangepaste web-API vectorizer wordt aangeroepen WebApiVectorizer in de REST API. Gebruik de nieuwste stabiele versie van Indexes - Create (REST API) of een Azure SDK-pakket dat de functie biedt.

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. Wanneer u de index met GET ophaalt, retourneert de service de waarde van de queryparameter `?code=` als `?code=<redacted>` om te voorkomen dat functiesleutels zichtbaar worden. Als u de vectorizer wilt bijwerken zonder de opgeslagen URI te wijzigen, stelt u deze in `uri` op `<unchanged>`.
`httpMethod`	De methode waarmee de payload wordt verzonden. Toegestane methoden zijn `PUT` of `POST`.
`httpHeaders`	Een verzameling sleutel-waardeparen waarin sleutels headernamen en waarden zijn, worden verzonden naar uw web-API. De volgende kopteksten zijn verboden: , , , , , `Accept`, `Accept-Charset`, `Accept-EncodingContent-Length`, `Content-Type`en `Cookie`. `HostTEUpgradeVia` GET retourneert de sentinel-waarde `<redacted>` voor elke headerwaarde. Zie Header-waarden bijwerken na GET voor updatevereisten.
`authResourceId`	(Optioneel) Een tekenreeks die, indien ingesteld, aangeeft dat deze vectorizer een beheerde identiteit gebruikt voor de verbinding met de functie of app die als host fungeert voor de code. Deze eigenschap accepteert een applicatie-id of app-registratie in Microsoft Entra ID in een van deze indelingen: `api://<appId>`, `<appId>/.default`, `api://<appId>/.default`. Met deze waarde wordt het authenticatietoken bepaald dat wordt opgehaald door de querypijplijn en verzonden met het aangepaste web-API-verzoek naar de functie of app. Als u deze eigenschap instelt, moet dat uw zoekservice is geconfigureerd voor beheerde identiteit en moet uw Azure functie-app geconfigureerd zijn voor aanmelding bij Microsoft Entra.
`authIdentity`	(Optioneel) Een door de gebruiker beheerde identiteit die door de search service 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 of door de gebruiker beheerde identiteit gebruiken. Als u een door het systeem beheerde identiteit wilt gebruiken, laat u `authIdentity` leeg.
`timeout`	(Optioneel) De time-out 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 ). Betekent bijvoorbeeld `PT60S` 60 seconden. Als deze niet is ingesteld, is de standaardwaarde 30 seconden. De time-out kan tussen 1 en 230 seconden duren.

Ondersteunde vectorquerytypen

De Custom Web API vectorizer ondersteunt text, imageUrl en imageBinary vectorqueries.

Voorbeelddefinitie

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

Headerwaarden bijwerken na GET

Wanneer u een indexdefinitie ophaalt, retourneert de service de sentinel <redacted> voor elke httpHeaders waarde in een aangepaste web-API-vectorizer. Voorbeeld:

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

Als u de opgeslagen api-key waarde opnieuw wilt gebruiken, werkt u dezelfde bestaande vectorizer bij met hetzelfde name en kindlaat u de uri waarde ongewijzigd en verzendt u de sentinel opnieuw voor de overeenkomende headernaam:

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

Met een ongewijzigde waarde kunt u combineren uri voor bewaarde <redacted>headerwaarden met werkelijke vervangingswaarden voor andere bestaande headers. Geef een werkelijke waarde op voor elke toegevoegde of hernoemde header, omdat de sentinel alleen van toepassing is op een bestaande header met dezelfde naam op dezelfde vectorizer.

Als u de uriwaarde wijzigt, geeft u werkelijke waarden op voor elke httpHeaders vermelding in dezelfde update. De service hergebruikt opgeslagen waarden niet voor een ander uri:

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

Als de referenties niet beschikbaar zijn en u de urireferenties moet wijzigen, roteren of opnieuw genereren op het externe eindpunt. Verzend vervolgens de nieuwe uri waarden en koptekstwaarden samen.

De <redacted> waarde is een service-sentinel, geen referentie. Het kan geen vectorizer maken of een headerwaarde ophalen of opnieuw gebruiken die is opgeslagen voor een andere vectorizer.

JSON-nettoladingstructuur

De vereiste JSON-nettoladingstructuur voor een eindpunt dat wordt gebruikt met de Custom Web API vectorizer is dezelfde als de structuur die wordt gebruikt door de vaardigheid Custom Web API. Zie de documentatie voor vaardigheden voor meer informatie.

Houd rekening met de volgende overwegingen bij het implementeren van een web-API-eindpunt voor de Custom 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 die moeten worden gevectoriseerd door in een specifieke sleutel in het data JSON-object in de aanvraagpayload. Deze sleutel is text, imageUrlof imageBinary, afhankelijk van welk type vectorquery is aangevraagd.
De vectorizer verwacht dat de resulterende embedding onder de vector sleutel in het data JSON-object in de antwoordpayload staat.
De vectorizer negeert eventuele fouten of waarschuwingen die door het eindpunt worden geretourneerd. Deze fouten en waarschuwingen zijn niet beschikbaar voor foutopsporing in querytijd.

Als er een imageBinary vectorquery is aangevraagd, wordt de aanvraaginhoud die naar het eindpunt wordt verzonden, als volgt:

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

Zie ook

Feedback

Is deze pagina nuttig?

Last updated on 2026-08-13