Vectoriseur d’API web personnalisée

Le vectoriseur d’API web personnalisé vous permet de configurer des requêtes de recherche pour appeler un point de terminaison d’API web qui génère des incorporations au moment de la requête. La structure de charge utile JSON requise pour le point de terminaison est décrite plus loin dans cet article. Vos données sont traitées dans la géographie où votre modèle est déployé.

Bien que les vectoriseurs soient utilisés au moment de la requête, vous les spécifiez dans les définitions d’index et les référencez sur les champs vectoriels via un profil vectoriel. Pour plus d’informations, consultez Configurer un vectoriseur dans un index de recherche.

Le vectoriseur d’API web personnalisé est appelé WebApiVectorizer dans l’API REST. Utilisez la dernière version stable de Indexes - Créer (API REST) ou un package sdk Azure qui fournit la fonctionnalité.

Paramètres du vectoriseur

Les paramètres sont sensibles à la casse.

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": "<your-header-value>"
            },
            "timeout": "PT60S",
            "authResourceId": null,
            "authIdentity": null
        }
    }
]

Mettre à jour les valeurs d’en-tête après GET

Lorsque vous récupérez une définition d’index avec GET ou répertoriez les index avec LIST, le service retourne <redacted> pour chaque valeur httpHeaders dans un vectoriseur d’API web personnalisé. Par exemple:

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

Pour réutiliser la valeur stockée api-key, mettez à jour le même vectoriseur existant avec le même name, kind et point de terminaison. Soumettez à nouveau l’espace réservé retourné pour le nom d’en-tête correspondant :

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

Pour le même vectoriseur et point de terminaison existant, vous pouvez combiner <unchanged> ou <redacted> pour les valeurs d’en-tête conservées avec des valeurs de remplacement réelles. Les valeurs explicites sont prioritaires sur les variables de substitution. Fournissez une valeur réelle pour chaque en-tête ajouté ou renommé, car un espace réservé nécessite une source existante non ambiguë. Pour connaître les modifications apportées aux requêtes URI, consultez la rédaction des URI et les mises à jour préservant les identifiants.

Si vous modifiez l’endpoint, fournissez l’URI réelle et les secrets d’en-tête dans la même mise à jour. Le service ne réutilise pas les secrets stockés pour un autre point de terminaison :

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

Si les informations d’identification ne sont pas disponibles et que vous devez modifier le point de terminaison, le faire pivoter ou régénérer les informations d’identification sur le point de terminaison externe. Envoyez ensuite les nouvelles valeurs uri et les valeurs d’en-tête ensemble.

La valeur <redacted> est une sentinelle de service, et non un justificatif d’authentification. Il ne peut pas créer de vectoriseur ni récupérer ou réutiliser une valeur d’en-tête stockée pour un autre vectoriseur.

Masquage des URI et mises à jour préservant les informations d’identification

Ce comportement de requête d’URI s’applique à toutes les versions de l’API.

Lorsque vous récupérez un index avec GET ou répertoriez les index avec LIST, Recherche Azure AI masque les valeurs sensibles de requête d’URI d’API web personnalisée, y compris sig et code, ainsi que les valeurs d’en-tête HTTP. Ces valeurs masquées protègent les signatures SAS, les clés de fonction et les informations d’identification d’en-tête.

Pour conserver les secrets stockés, mettez à jour la même ressource et le même point de terminaison existants déjà. Envoyez les espaces réservés retournés <unchanged> ou <redacted> dans la demande PUT de gestion. Ce PUT met à jour la définition d’index ; il n’est pas l’invocation du point de terminaison contrôlée par le/la httpMethod du vectoriseur. Vous pouvez également définir l’ensemble uri sur <unchanged> afin de conserver l’URI stocké.

Les valeurs secrètes ne sont pas transmises à un autre point de terminaison ou copiées dans une nouvelle ressource. La modification d’un point de terminaison, le clonage d’une définition expurgée ou la repointation d’une ressource nécessite des secrets explicites.

Si le service ne peut pas identifier une source existante non ambiguë pour un espace réservé, le PUT échoue avec 400 Bad Request et demande la valeur secrète réelle. Un espace réservé non résolu ou persistant n’est pas un identifiant utilisable. La restauration des secrets est atomique : une restauration ayant échoué n’applique pas partiellement les modifications d’URI ou d’en-tête.

Vous pouvez fournir un URI de remplacement ou des secrets d’en-tête à tout moment. Les valeurs explicites sont prioritaires sur les placeholders.

Les mises à jour des requêtes URI suivent les règles suivantes :

• Pour un paramètre de fonction code Azure, vous pouvez mettre à jour d’autres paramètres de requête non secrets tout en conservant la clé de fonction stockée pour le même point de terminaison.
• Pour un paramètre SAS sig, la signature est liée à la configuration de requête non secrète environnante. Si l’étendue, les autorisations, l’expiration, la ressource, la version, l’ordre, la casse ou l’encodage changent, fournissez une nouvelle signature. Même le texte de requête réorganisé ou réencodé sémantiquement nécessite une nouvelle signature.

Les noms des paramètres de requête secrets sont reconnus sans tenir compte de la casse et lorsqu’ils sont encodés en pourcentage. Le service conserve votre représentation URI au lieu de la normaliser. Les paramètres secrets répétés sont mis en correspondance par occurrence. Si leur modèle d’occurrence ne s’aligne plus avec l’URI stocké, fournissez des valeurs réelles.

Les flux de travail GET-then-PUT existants utilisant <redacted> ou <unchanged> restent pris en charge. Pour obtenir des exemples d’en-tête, consultez Mettre à jour les valeurs d’en-tête après GET.

Pour connaître les compétences personnalisées, consultez le masquage de l’URI de la compétence d’API web personnalisée et les mises à jour préservant les informations d’identification.

Structure de charge utile JSON

La structure de charge utile JSON requise pour un point de terminaison utilisé avec le vectoriseur d’API web personnalisée est identique à la structure utilisée par la compétence API web personnalisée. Pour plus d’informations, consultez la documentation relative aux compétences.

Gardez à l’esprit les considérations suivantes lors de l’implémentation d’un point de terminaison d’API web pour le vectoriseur d’API web personnalisé :

• 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.

• Le vectoriseur ignore les erreurs ou avertissements retournés par le point de terminaison. Ces erreurs et avertissements ne sont pas disponibles pour le 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

• Vectorisation intégrée
• Comment configurer un vectoriseur dans un index de recherche
• Compétence API web personnalisée