Compartir vía

Aptitud API web personalizada en una canalización de enriquecimiento de Azure AI Search

  • Artículo

La aptitud API web personalizada permite extender el enriquecimiento con IA al llamar a un punto de conexión de la API web que proporciona operaciones personalizadas. De manera similar a las aptitudes integradas, una aptitud API web personalizada tiene entradas y salidas. En función de las entradas, la API web recibe una carga de JSON cuando se ejecuta el indexador y genera una carga de JSON como respuesta, junto con un código de estado correcto. Se espera que la respuesta tenga las salidas especificadas por la aptitud personalizada. Cualquier otra respuesta se considera un error y no se realiza ningún enriquecimiento. La estructura de la carga JSON se describe con mayor detalle más adelante en este documento.

La API web personalizada también se usa en la implementación de la característica Azure OpenAI en los datos. Si Azure OpenAI está configurado para el acceso basado en roles y recibe llamadas 403 Forbidden al crear el índice de vectores, compruebe que Azure AI Search tenga una identidad asignada por el sistema y se ejecute como un servicio de confianza en Azure OpenAI.

Nota:

El indizador realizará dos reintentos para ciertos códigos de estado HTTP estándar devueltos desde la API web. Estos códigos de estado HTTP son:

  • 502 Bad Gateway
  • 503 Service Unavailable
  • 429 Too Many Requests

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parámetros de la aptitud

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.
authResourceId (Opcional) Una cadena que, si se establece, indica que esta aptitud debe usar una identidad administrada por el sistema en la conexión a la función o aplicación que hospeda el código. Esta propiedad toma un identificador de aplicación (cliente) o el registro de la aplicación en Microsoft Entra ID, en cualquiera de estos formatos: api://<appId>, <appId>/.default, api://<appId>/.default. Este valor se usará para el ámbito del token de autenticación que recupera el indizador y se envía junto con la solicitud de la API de aptitud 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. Para usar este parámetro, llame a la API con api-version=2023-10-01-Preview.
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.
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.
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.
batchSize (Opcional) Indica cuántos "registros de datos" (consulte la estructura de la carga de JSON que se muestra más adelante) se enviarán por llamada API. Si no se establece, se elige un valor predeterminado de 1000. Se recomienda usar este parámetro para lograr un equilibrio adecuado entre el rendimiento de la indexación y la carga en la API.
degreeOfParallelism (Opcional) Cuando se especifica, indica el número de llamadas que realiza el indizador en paralelo al punto de conexión que ha proporcionado. Puede disminuir este valor si el punto de conexión no tiene presión o aumentarlo si el punto de conexión puede controlar la carga. Si no se establece, se usa un valor predeterminado de 5. degreeOfParallelism se puede establecer en un máximo de 10 y un mínimo de 1.

Entradas de la aptitud

No hay entradas predefinidas para esta aptitud. Las entradas son cualquier campo existente, o cualquier nodo del árbol de enriquecimiento que quiera pasar a la aptitud personalizada.

Salidas de la aptitud

No hay salidas predefinidas para esta aptitud. Asegúrese de definir una asignación de campos de salida en el indexador si la salida de la aptitud se debe enviar a un campo en el índice de búsqueda.

Definición de ejemplo

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "batchSize": 4,
  "context": "/document",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    },
    {
      "name": "language",
      "source": "/document/languageCode"
    },
    {
      "name": "phraseList",
      "source": "/document/keyphrases"
    }
  ],
  "outputs": [
    {
      "name": "hitPositions"
    }
  ]
}

Estructura de JSON de entrada de ejemplo

Esta estructura JSON representa la carga que se enviará a la API web. Siempre siga estas restricciones:

  • La entidad de nivel superior se llama values y es una matriz de objetos. El número de dichos objetos será como máximo el batchSize.

  • Cada objeto de la matriz values tiene:

    • Una propiedad recordId que será una cadena única usada para identificar ese registro.

    • Una propiedad data que será un objeto JSON. Los campos de la propiedad data corresponden a los "nombres" especificados en la sección inputs de la definición de aptitud. El valor de esos campos proviene del source de esos campos (que podrían ser de un campo del documento o posiblemente de otra aptitud).

{
    "values": [
      {
        "recordId": "0",
        "data":
           {
             "text": "Este es un contrato en Inglés",
             "language": "es",
             "phraseList": ["Este", "Inglés"]
           }
      },
      {
        "recordId": "1",
        "data":
           {
             "text": "Hello world",
             "language": "en",
             "phraseList": ["Hi"]
           }
      },
      {
        "recordId": "2",
        "data":
           {
             "text": "Hello world, Hi world",
             "language": "en",
             "phraseList": ["world"]
           }
      },
      {
        "recordId": "3",
        "data":
           {
             "text": "Test",
             "language": "es",
             "phraseList": []
           }
      }
    ]
}

Estructura JSON de salida de ejemplo

La "salida" corresponde a la respuesta devuelta desde la API web. La API web solo debe devolver una carga de JSON (que se comprueba al mirar el encabezado de la respuesta Content-Type) y debe cumplir con estas restricciones:

  • Debe haber una entidad de nivel superior llamada values, que debe ser una matriz de objetos.

  • El número de objetos en la matriz debe ser el mismo número de objetos enviados a la API web.

  • Cada objeto debe tener:

    • Una propiedad recordId.

    • Una propiedad data, que es un objeto donde los campos son enriquecimientos que coinciden con los "nombres" en output y cuyos valores se consideran el enriquecimiento.

    • Una propiedad errors, una matriz que muestra todos los errores detectados que se agregarán al historial de ejecuciones del indizador. Esta propiedad es obligatoria, pero puede tener un valor null.

    • Una propiedad warnings, una matriz que muestra todas las advertencias detectadas que se agregarán al historial de ejecuciones del indizador. Esta propiedad es obligatoria, pero puede tener un valor null.

  • El orden de los objetos en values en la solicitud o respuesta no es importante. Sin embargo, recordId se usa para correlación, por lo que se descartará cualquier registro de la respuesta que contenga un recordId que no haya sido parte de la solicitud original a la API web.

{
    "values": [
        {
            "recordId": "3",
            "data": {
            },
            "errors": [
              {
                "message" : "'phraseList' should not be null or empty"
              }
            ],
            "warnings": null
        },
        {
            "recordId": "2",
            "data": {
                "hitPositions": [6, 16]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "0",
            "data": {
                "hitPositions": [0, 23]
            },
            "errors": null,
            "warnings": null
        },
        {
            "recordId": "1",
            "data": {
                "hitPositions": []
            },
            "errors": null,
            "warnings": [
              {
                "message": "No occurrences of 'Hi' were found in the input text"
              }
            ]
        },
    ]
}

Casos de error

Además de una API web no disponible o del envío de códigos de estado no correcto, los siguientes se consideran como casos con errores:

  • Si la API web devuelve un código de estado correcto, pero la respuesta indica que no es application/json, entonces la respuesta se considera como no válida y no se realizará ningún enriquecimiento.

  • Si hay registros no válidos (por ejemplo, falta recordId o está duplicado) en la matriz values de respuesta, no se realizará ningún enriquecimiento para los registros no válidos. Es importante cumplir el contrato de aptitudes de API web al desarrollar aptitudes personalizadas. Puede hacer referencia a este ejemplo proporcionado en el repositorio de Power Skill que sigue el contrato esperado.

En los casos en que la API web no está disponible o devuelve un error HTTP, se agregará un error descriptivo con todos los detalles disponibles sobre el error HTTP al historial de ejecución del indizador.

Consulte también