Compartir a través de

Vectorizador de la API de web personalizada

  • Artículo

Importante

Esta característica se encuentra en versión preliminar pública en los Términos de uso complementarios. La API REST 2023-10-01-Preview y las API REST de versión preliminar posteriores admiten esta característica.

El Vectorizador de la API de web personalizada permite configurar las consultas de búsqueda para llamar a un punto de conexión de API web para generar inserciones en el momento de la consulta. La estructura de la carga JSON necesaria para implementarse en el punto de conexión proporcionado se describe más adelante en este documento. Los datos se procesan en la ubicación geográfica donde se implementa el modelo.

Parámetros de vectorizador

Los parámetros distinguen mayúsculas de minúsculas.

Nombre de parámetro Descripción
uri El URI de la API web adonde se enviará la carga de JSON. Solo se permite el esquema de URI https.
httpMethod Método que se usará al enviar la carga. Los métodos permitidos son PUT o POST
httpHeaders Colección de pares clave-valor donde las claves representan los nombres de encabezados y los valores representan los valores de encabezados que se enviarán a la API web junto con la carga. Los encabezados siguientes no se permiten en esta colección: Accept, Accept-Charset, Accept-Encoding, Content-Length, Content-Type, Cookie, Host, TE, Upgrade y Via.
authResourceId (Opcional) Una cadena que, si se establece, indica que este vectorizador debe utilizar una identidad administrada en la conexión a la función o aplicación que hospeda el código. Esta propiedad toma un id. de aplicación (cliente) o el registro de la aplicación en Microsoft Entra ID, en un formato admitido: api://<appId>. Este valor se usa para definir el ámbito del token de autenticación recuperado por el indexador y se envía junto con la solicitud de API de web personalizada a la función o aplicación. El establecimiento de esta propiedad requiere que el servicio de búsqueda esté configurado para la identidad administrada y que la aplicación de funciones de Azure esté configurada para un inicio de sesión de Microsoft Entra.
authIdentity (Opcional) Una identidad administrada por el usuario que usa el servicio de búsqueda para conectarse a la función o aplicación que hospeda el código. Puede usar una identidad administrada por el usuario o por el sistema. Para usar una identidad administrada del sistema, deje authIdentity en blanco.
timeout (Opcional) Cuando se especifica, indica el tiempo de expiración del cliente http que hace la llamada API. Debe tener el formato de un valor "dayTimeDuration" XSD (subconjunto restringido de un valor de duración ISO 8601 ). Por ejemplo, PT60S para 60 segundos. Si no se establece, se elige el valor predeterminado de 30 segundos. El tiempo de expiración se puede establecer en un máximo de 230 segundos y un mínimo de 1.

Tipos de consulta vectorial admitidos

El vectorizador de API de web personalizada admite consultas vectoriales text, imageUrl y imageBinary.

Definición de ejemplo

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

Estructura de carga JSON

La estructura de carga útil JSON requerida que se espera para un punto de conexión cuando se utiliza con el vectorizador de la API web personalizada es la misma que la de la aptitud de la API web personalizada, que se describe con más detalle en la documentación de la aptitud.

Hay otras consideraciones que se deben tener en cuenta al implementar un punto de conexión de API web para usarlo con el vectorizador de API web personalizado.

  • El vectorizador envía sólo un registro a la vez en la matriz values cuando realiza una solicitud al punto de conexión.

  • El vectorizador pasa los datos que se van a vectorizar en una clave específica del objeto JSON data en la carga de la solicitud. Esa clave es text, imageUrl o imageBinary, dependiendo del tipo de consulta vectorial solicitada.

  • El vectorizador espera que la inserción resultante esté bajo la clave vector del objeto JSON data en la carga útil de respuesta.

  • Los errores o advertencias devueltos por el punto de conexión se omiten mediante el vectorizador y no se pueden obtener con fines de depuración en el momento de la consulta.

  • Si se ha solicitado una consulta vectorial imageBinary, la carga útil de la solicitud enviada al punto de conexión es la siguiente:

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

Consulte también