Incorporación de una aptitud personalizada a una canalización de enriquecimiento de Azure AI Search

Una canalización de enriquecimiento con IA puede incluir aptitudes integradas y aptitudes personalizadas que cree y publique. El código personalizado se ejecuta fuera del servicio de búsqueda (por ejemplo, como una función de Azure), pero acepta entradas y envía salidas al conjunto de aptitudes igual que cualquier otra aptitud. Los datos se procesan en el geography donde se implementa el modelo.

Las aptitudes personalizadas pueden parecer complejas, pero pueden ser sencillas de implementar. Si tiene paquetes existentes que proporcionan modelos de clasificación o coincidencia de patrones, puede pasar contenido extraído de blobs a esos modelos para su procesamiento. Dado que el enriquecimiento con IA se basa en Azure, también debe hospedar el modelo en Azure. Entre las opciones de hospedaje comunes se incluyen Azure Functions o containers.

Si vas a crear una habilidad personalizada, en este artículo se describe la interfaz que se utiliza para integrar la habilidad en el pipeline. El requisito principal es la capacidad de aceptar entradas y emitir salidas de maneras que el conjunto de aptitudes puede consumir en su conjunto. Por tanto, este artículo se centra en los formatos de entrada y salida que necesita la canalización de enriquecimiento.

Ventajas de las aptitudes personalizadas

Crear una habilidad personalizada le otorga una forma de insertar transformaciones únicas en su contenido. Por ejemplo, puede crear modelos de clasificación personalizados para diferenciar contratos y documentos comerciales y financieros, o agregar una aptitud de reconocimiento de voz para profundizar en el contenido relevante de los archivos de audio. Para obtener un ejemplo paso a paso, consulte Ejemplo: crear una aptitud personalizada para el enriquecimiento con IA.

Establecer el punto de conexión y el intervalo de tiempo de espera

Especifique la interfaz de una habilidad personalizada mediante la habilidad de API web personalizada.

"@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
"description": "This skill has a 230-second timeout",
"uri": "https://[your custom skill uri goes here]",
"authResourceId": "[for managed identity connections, your app's client ID goes here]",
"timeout": "PT230S",

El URI es el punto de conexión HTTPS de la función o aplicación. Al establecer el URI, asegúrese de que sea seguro (HTTPS). Si hospeda el código en una aplicación de función de Azure, incluya una clave de API en el encabezado o como un parámetro URI en el URI para autorizar la solicitud.

Si su función o aplicación utiliza identidades administradas de Azure y roles de Azure para la autenticación y la autorización, la aptitud personalizada puede incluir un token de autenticación en la solicitud. En los puntos siguientes se describen los requisitos para este enfoque:

• El servicio de búsqueda, que envía la solicitud en nombre del indexador, debe configurarse para usar una identidad administrada (ya sea un sistema o asignado por el usuario) para que Microsoft Entra ID pueda autenticar al autor de la llamada.

• Debe configurar la función o la aplicación para Microsoft Entra ID.

• La definición de aptitud personalizada debe incluir una propiedad authResourceId. Esta propiedad toma un identificador de aplicación (cliente), en un formato compatible: api://<appId>.

Asegúrese de que uri apunta al punto de conexión de la aplicación identificado por authResourceId. Los valores no coincidentes pueden provocar errores de autenticación o solicitudes que se envían a un punto de conexión no deseado. Para obtener instrucciones de seguridad, procedimientos recomendados y pasos para comprobar la configuración, consulte Consideraciones de seguridad para la autenticación de identidad administrada.

De forma predeterminada, la conexión al punto de conexión agota el tiempo de espera si no se devuelve una respuesta dentro de una ventana de 30 segundos (PT30S). La canalización de indexación es sincrónica y la indexación genera un error de tiempo de espera si no se recibe una respuesta en ese período de tiempo. Puede aumentar el intervalo a un valor máximo de 230 segundos estableciendo el parámetro timeout (PT230S).

Si un punto de conexión protegido por restricciones de acceso IP no responde, establezca timeout temporalmente en un valor corto, como PT10S, para mostrar el error de tiempo de espera más rápido. Para una aplicación de función de Azure, administre las reglas IP de entrada en Configuración Restricciones>de acceso a>. Para las direcciones IP que se van a permitir, consulte Configuración de reglas de firewall de IP para permitir conexiones del indexador.

Formato de entradas de API web

La API web debe aceptar una matriz de registros para procesar. Dentro de cada registro, proporcione un contenedor de propiedades como entrada para la API web.

Supongamos que desea crear un enriquecidor básico que identifique la primera fecha mencionada en el texto del contrato. En este ejemplo, la aptitud personalizada acepta una única entrada, contractText. Esta habilidad también tiene una única salida, que es la fecha del contrato. Para que el enriquecedor resulte más interesante, devuelve contractDate en forma de tipo complejo multiparte.

La API web debe estar lista para recibir un lote de registros de entrada. Cada miembro de la values matriz representa la entrada de un registro determinado. Es necesario que cada registro tenga los siguientes elementos:

• Miembro recordId que es el identificador único de un registro determinado. Cuando su enriquecedor devuelva resultados, debe proporcionar este recordId para que el llamante pueda hacer coincidir los resultados de los registros con las entradas.

• Un miembro data, que es un conjunto de campos de entrada para cada registro.

La solicitud de API web resultante podría tener este aspecto:

{
    "values": [
      {
        "recordId": "a1",
        "data":
           {
             "contractText": 
                "This is a contract that was issued on November 3, 2023 and that involves... "
           }
      },
      {
        "recordId": "b5",
        "data":
           {
             "contractText": 
                "In the City of Seattle, WA on February 5, 2018 there was a decision made..."
           }
      },
      {
        "recordId": "c3",
        "data":
           {
             "contractText": null
           }
      }
    ]
}

En la práctica, tu código puede ser llamado con cientos o miles de registros, en lugar de solo los tres que se muestran aquí.

Dar formato a las salidas de la API web

El formato de salida es un conjunto de registros que contienen un recordId y un conjunto de propiedades. Este ejemplo concreto tiene solo una salida, pero puede devolver más de una propiedad. Como procedimiento recomendado, considere la posibilidad de devolver mensajes de error y advertencia si algún registro no se pudo procesar.

{
  "values": 
  [
      {
        "recordId": "b5",
        "data" : 
        {
            "contractDate":  { "day" : 5, "month": 2, "year" : 2018 }
        }
      },
      {
        "recordId": "a1",
        "data" : {
            "contractDate": { "day" : 3, "month": 11, "year" : 2023 }                    
        }
      },
      {
        "recordId": "c3",
        "data" : 
        {
        },
        "errors": [ { "message": "contractText field required "}   ],  
        "warnings": [ {"message": "Date not found" }  ]
      }
    ]
}

Adición de una aptitud personalizada a un conjunto de aptitudes

Al crear un enriquecidor de API web, puede definir encabezados y parámetros HTTP como parte de la solicitud. El siguiente fragmento de código muestra cómo se pueden incluir los parámetros de solicitud y los encabezados HTTP opcionales en la definición del conjunto de aptitudes. Establecer un encabezado HTTP es útil si necesita pasar valores de configuración al código.

{
    "skills": [
      {
        "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
        "name": "myCustomSkill",
        "description": "This skill calls an Azure function, which in turn calls TA sentiment",
        "uri": "https://indexer-e2e-webskill.azurewebsites.net/api/DateExtractor?language=en",
        "context": "/document",
        "httpHeaders": {
            "DateExtractor-Api-Key": "foo"
        },
        "inputs": [
          {
            "name": "contractText",
            "source": "/document/content"
          }
        ],
        "outputs": [
          {
            "name": "contractDate",
            "targetName": "date"
          }
        ]
      }
  ]
}

Vea este vídeo

Para ver una introducción en vídeo y una demostración, vea la siguiente demostración.

Pasos siguientes

En este artículo se han tratado los requisitos de la interfaz necesarios para integrar una aptitud personalizada en un conjunto de aptitudes. Para más información sobre las aptitudes personalizadas y la composición del conjunto de aptitudes, consulte los siguientes recursos:

• Power Skills: un repositorio de aptitudes personalizadas
• Ejemplo: crear una aptitud personalizada para el enriquecimiento con IA
• Definición de un conjunto de aptitudes
• Crear conjunto de habilidades (REST)
• Cómo mapear campos enriquecidos