Partage via

Vectoriseur d’API web personnalisée

  • Article

Important

Cette fonctionnalité est en préversion publique sous les conditions d’utilisation supplémentaires. L’API REST 2023-10-01-Preview et les API REST de préversion ultérieures prennent en charge cette fonctionnalité.

Le vectoriseur d’API web personnalisée vous permet de configurer vos requêtes de recherche pour appeler un point de terminaison d’API web, afin de générer des incorporations au moment de la requête. La structure de la charge utile JSON requise pour être implémentée dans le point de terminaison fourni est décrite plus loin dans ce document. Vos données sont traitées dans la zone géographique où votre modèle est déployé.

Paramètres du vectoriseur

Les paramètres respectent la casse.

Nom du paramètre Description
uri URI de l’API web à laquelle la charge utile JSON est envoyée. Seul le schéma d’URI https est autorisé.
httpMethod Méthode à utiliser pour envoyer la charge utile. Les méthodes autorisées sont PUT ou POST
httpHeaders Collection de paires clé-valeur où les clés représentent les noms d’en-tête et les valeurs représentent les valeurs d’en-tête envoyées à votre API web avec la charge utile. Les en-têtes suivants sont interdits dans cette collection : Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade, Via.
authResourceId (Facultatif) Chaîne qui, si elle est définie, indique que ce vectoriseur doit utiliser une identité managée sur la connexion à la fonction ou à l’application qui héberge le code. Cette propriété prend un ID d’application (client) ou l’inscription de l’application dans Microsoft Entra ID, dans un format pris en charge : api://<appId>. Cette valeur est utilisée pour étendre le jeton d’authentification récupéré par l’indexeur et est envoyée avec la requête d’API web personnalisée à la fonction ou à l’application. La définition de cette propriété nécessite que votre service de recherche soit configuré pour une identité managée et que votre application de fonction Azure soit configurée pour une connexion Microsoft Entra.
authIdentity (Facultatif) Une identité managée par l’utilisateur utilisée par le service de recherche pour la connexion à la fonction ou à l’application qui héberge le code. Vous pouvez utiliser une identité managée par le système ou l’utilisateur. Pour utiliser une identité managée par le système, laissez authIdentity vide.
timeout (Facultatif) Si spécifié, indique le délai d’expiration pour le client http qui effectue l’appel d’API. Il doit être formaté en tant que valeur « dayTimeDuration » XSD (un sous-ensemble limité d'une valeur de durée ISO 8601 ). Par exemple, PT60S pour 60 secondes. S’il n’est pas défini, une valeur par défaut de 30 secondes est choisie. Le délai d’expiration peut être défini sur 230 secondes maximum et 1 seconde minimum.

Types de requêtes vectorielles pris en charge

Le vectoriseur d’API web personnalisée prend en charge les requêtes vectorielles text, imageUrl et imageBinary.

Exemple de définition

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

Structure de charge utile JSON

La structure de charge utile JSON requise pour un point de terminaison lors de son utilisation avec le vectoriseur d’API web personnalisée est la même que celle de la compétence d’API web personnalisée, qui est abordée plus en détail dans la documentation de la compétence.

Il convient de prendre en compte les autres considérations suivantes lors de l’implémentation d’un point de terminaison d’API web à utiliser avec le vectoriseur d’API web personnalisée.

  • Le vectoriseur envoie un seul enregistrement à la fois dans le tableau values lors de l’envoi d’une requête au point de terminaison.

  • Le vectoriseur transmet les données à vectoriser dans une clé spécifique dans l’objet JSON data dans la charge utile de la requête. Cette clé est text, imageUrl ou imageBinary, selon le type de requête vectorielle demandée.

  • Le vectoriseur s’attend à ce que l’incorporation obtenue se trouve sous la clé vector dans l’objet JSON data dans la charge utile de réponse.

  • Les erreurs ou avertissements retournés par le point de terminaison sont ignorés par le vectoriseur et ne peuvent pas être obtenu à des fins de débogage au moment de la requête.

  • Si une requête vectorielle imageBinary a été demandée, la charge utile de la requête envoyée au point de terminaison est la suivante :

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

Voir aussi