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

Use la aptitud Custom Web API para ampliar el enriquecimiento con IA mediante una llamada a un punto de conexión de API web que proporcione operaciones personalizadas. Al igual que las aptitudes integradas, una aptitud de API web personalizada tiene entradas y salidas. En función de las entradas, la API web recibe una carga JSON cuando se ejecuta el indexador y devuelve una carga JSON como respuesta, junto con un código de estado correcto. La respuesta debe incluir 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 más adelante en este documento.

La aptitud Api web personalizada también se usa en la implementación de la Azure openAI en la característica Datos. Si Azure OpenAI está configurado para el acceso basado en roles y recibe 403 Forbidden errores al crear el índice de vectores, compruebe que Búsqueda de Azure AI tiene una identidad asignada por el sistema y se ejecuta como un servicio de confianza en Azure OpenAI.

@odata.type

Microsoft.Skills.Custom.WebApiSkill

Parámetros de aptitud

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

Descripción del authResourceId valor

Cuando una aptitud de API web personalizada usa la autenticación de identidad administrada, Búsqueda de Azure AI obtiene un token de acceso Microsoft Entra y lo envía al punto de conexión de aptitud personalizado. La authResourceId propiedad especifica el identificador de recurso, también conocido como URI de audiencia o identificador de aplicación, para el que se solicita el token. El valor debe coincidir con lo que espera la aplicación de destino durante la validación del token. De lo contrario, se produce un error de autenticación con una 401 Unauthorized respuesta.

El authResourceId valor identifica la aplicación que hospeda la aptitud personalizada. No es la dirección URL del servicio de búsqueda ni del indexador.

En la tabla siguiente se muestran los formatos comunes:

La propiedad acepta formatos con y sin el .default sufijo de ámbito. Use api://<appId> para que coincida directamente con el URI del identificador de aplicación. Si incluye un .default sufijo, como api://<appId>/.default, la notificación del token de aud acceso contiene el URI de identificador de aplicación base sin el sufijo.

Para conocer los pasos para configurar Microsoft Entra autenticación para una función de Azure y establecer authResourceId, consulte Uso de una identidad administrada del servicio de búsqueda para conectarse a una aplicación de función de Azure.

Ejemplo: función Azure protegida por Microsoft Entra ID

En este ejemplo, Búsqueda de Azure AI adquiere un token de acceso para la audiencia especificada por authResourceId e incluye el token al invocar el punto de conexión de aptitud personalizado.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso-function.azurewebsites.net/api/enrich",
  "authResourceId": "api://contoso-customskill"
}

Entradas de habilidades

Esta aptitud no tiene entradas predefinidas. Las entradas son cualquier campo existente, o cualquier nodo del árbol de enriquecimiento que quiera pasar a la aptitud personalizada.

Resultados de habilidades

Esta aptitud no tiene salidas predefinidas. 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"
    }
  ]
}

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "uri": "https://contoso.example.org/api?code=<redacted>",
  "httpMethod": "POST",
  "name": "myCustomSkill",
  "httpHeaders": {
    "Authorization": "<redacted>",
    "Ocp-Apim-Subscription-Key": "<redacted>"
  }
}

{
  "uri": "<unchanged>",
  "httpHeaders": {
    "Authorization": "<unchanged>",
    "Ocp-Apim-Subscription-Key": "<unchanged>"
  }
}

Estructura de JSON de entrada de ejemplo

Esta estructura JSON representa la carga que se envía 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 estos objetos es como máximo .batchSize

• Cada objeto de la matriz values tiene:

  • Propiedad recordId que es una cadena única que se usa para identificar ese registro.

  • Propiedad data que es 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. Los valores de esos campos proceden de source esos campos (que podrían ser de un campo del documento o potencialmente 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 que la API web no está disponible o envía códigos de estado no correctos, tenga en cuenta los siguientes casos como errores:

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

• Si la matriz de respuesta values contiene registros no válidos (por ejemplo, que faltan o están duplicados recordId), los registros no válidos no se enriquecen. Al desarrollar aptitudes personalizadas, siga el contrato de aptitudes de api web. Puede hacer referencia a este ejemplo proporcionado en el repositorio de Power Skill que sigue el contrato esperado.

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

Consideraciones de seguridad para la autenticación de identidad administrada

Al usar la autenticación de identidad administrada con una aptitud de API web personalizada, Búsqueda de Azure AI obtiene un token de acceso de Microsoft Entra para la aplicación identificada por authResourceId e incluye ese token en las solicitudes enviadas al punto de conexión especificado por uri. El punto de conexión al que uri hace referencia suele ser la función Azure, Azure App Service, punto de conexión de Azure API Management u otra aplicación protegida por Microsoft Entra. Es responsable de configurar y mantener la relación entre el punto de conexión y la aplicación identificada por authResourceId.

Independientemente del método de autenticación, las entradas de aptitud personalizadas pueden contener valores de documentos o valores proporcionados por el cliente derivados de esos documentos. Trate todas las entradas de aptitud personalizadas como que no son de confianza. Búsqueda de Azure AI reenvía las entradas configuradas en el conjunto de aptitudes al punto de conexión sin interpretar, validar ni restringir su contenido para la implementación personalizada.

Valide y restrinja los valores derivados de documentos en la aptitud personalizada antes de usarlos en solicitudes salientes u otras operaciones sensibles a la seguridad. Use la validación de entrada, las listas de permitidos de destino, la validación de direcciones URL y el nombre de host, las restricciones de protocolo y el acceso a la red con privilegios mínimos que solo permiten los destinos y los puertos que requiere la aptitud. Para obtener más información, consulte Estrategias de arquitectura para redes y conectividad.

Procedimientos de seguridad recomendados

Para ayudar a mantener una implementación segura, siga estos procedimientos:

• Configure la uri propiedad para que apunte solo a los puntos de conexión de confianza destinados a recibir solicitudes de Búsqueda de Azure AI.
• Configure authResourceId para identificar la aplicación Microsoft Entra que se espera que reciba y valide el token de acceso.
• Asegúrese de que la aplicación que recibe solicitudes valida las notificaciones de token estándar, incluido el público (aud), el emisor (), el inquilino (isstid) y los roles o permisos de aplicación necesarios, antes de procesar las solicitudes.
• Aplique el principio de privilegios mínimos al conceder permisos a la identidad administrada Búsqueda de Azure AI.
• Revise periódicamente las definiciones de aptitudes de api web personalizadas, los registros de aplicaciones Microsoft Entra y las asignaciones de roles de aplicación y los permisos concedidos a Búsqueda de Azure AI identidades administradas. Revise los cambios de configuración a través de los procesos establecidos de administración de cambios y revisión de seguridad.
• Revise periódicamente las configuraciones de punto de conexión para Azure Functions, App Services, API y puertas de enlace de API.
• Supervise los registros de inicio de sesión de la aplicación, los eventos de autenticación y los registros de acceso de API para actividades inesperadas o no autorizadas.
• Quite los puntos de conexión, los permisos, los registros de aplicaciones y las asignaciones de roles que ya no son necesarios.

Restricción del acceso a la configuración del conjunto de aptitudes

Los usuarios que pueden crear, modificar o ejecutar conjuntos de aptitudes pueden controlar tanto el punto de conexión de destino como la configuración de autenticación que usa una aptitud de API web personalizada. Restrinja estos permisos a los administradores de confianza y siga los procesos estándar de revisión de seguridad y administración de cambios al configurar aptitudes personalizadas habilitadas para la identidad administrada.

Consulte también

• Define a skillset (Definición de un conjunto de aptitudes)
• Incorporación de una aptitud personalizada a una canalización de enriquecimiento con IA
• Ejemplo: crear una aptitud personalizada para el enriquecimiento con IA
• Repositorio de Power Skill