Aptitud de AML en una canalización de enriquecimiento de Search de Azure AI

Artículo
12/18/2024

Importante

La compatibilidad con las conexiones del indexador al catálogo de modelos de Azure AI Foundry se encuentra en versión preliminar pública en términos de uso complementarios. Las API REST en versión preliminar admiten esta aptitud.

La aptitud AML permite ampliar el enriquecimiento con inteligencia artificial con un modelo personalizado de Azure Machine Learning (AML) o un modelo de inserción base implementado en Azure AI Foundry. Una vez entrenado e implementado un modelo AML, una aptitud de AML la integra en un conjunto de aptitudes.

Uso de aptitudes de AML

Al igual que otras aptitudes integradas, una aptitud de AML personalizada tiene entradas y salidas. Las entradas se envían a un punto de conexión en línea de AML implementado como un objeto JSON. La salida del punto de conexión debe ser una carga JSON en la respuesta, junto con un código de estado correcto. Los datos se procesan en la ubicación geográfica en la que se implementa el modelo. Se espera que la respuesta proporcione las salidas especificadas por la definición de aptitud de AML . Cualquier otra respuesta se considera un error y no se realiza ningún enriquecimiento.

Nota:

El indizador realizará dos reintentos para determinados códigos de estado HTTP estándar devueltos desde el punto de conexión en línea de AML. Estos códigos de estado HTTP son:

503 Service Unavailable
429 Too Many Requests

Se puede llamar a la aptitud AML con la versión de API estable 2024-07-01 o el SDK de Azure equivalente, o la versión de API 2024-05-01-preview para las conexiones al catálogo de modelos en el portal de Azure AI Foundry.

Aptitud AML para modelos en Azure AI Foundry

A partir de la API REST 2024-05-01-preview y en Azure Portal (que también tiene como destino 2024-05-01-preview), Azure AI Search proporciona el vectorizador de catálogo de modelos de Azure AI Foundry para las conexiones en tiempo de consulta al catálogo de modelos en el portal de Azure AI Foundry. Si desea usar ese vectorizador para consultas, una aptitud de AML es el homólogo de indexación para generar incrustaciones mediante un modelo en el catálogo de modelos de Azure AI Foundry.

Durante la indexación, la aptitud AML puede conectarse al catálogo de modelos para generar vectores para el índice. En el momento de la consulta, las consultas pueden usar un vectorizador para conectarse al mismo modelo para vectorizar cadenas de texto para una consulta vectorial. En este flujo de trabajo, la aptitud AML y el vectorizador de catálogo de modelos deben usarse juntos para que use el mismo modelo de inserción para la indexación y las consultas. Consulte Uso de modelos de inserción desde el catálogo de modelos de Azure AI Foundry para más información y para obtener una lista de los modelos de inserción admitidos.

Se recomienda usar el Asistente para importar y vectorizar datos para generar un conjunto de aptitudes que incluya una aptitud AML para la inserción de modelos implementados en Azure AI Foundry. El asistente genera una definición de aptitud de AML para entradas, salidas y asignaciones, lo que proporciona una manera fácil de probar un modelo antes de escribir cualquier código.

Requisitos previos

Un área de trabajo de AML para un modelo personalizado que cree o un proyecto en Azure AI Foundry si se implementa un modelo de inserción desde el catálogo.
Puntos de conexión en línea (en tiempo real) en esta área de trabajo para un modelo personalizado o el punto de conexión del modelo para insertar modelos implementados desde el catálogo.

@odata.type

Microsoft.Skills.Custom.AmlSkill

Parámetros de la aptitud

Los parámetros distinguen mayúsculas de minúsculas. Los parámetros que decida usar dependen de la autenticación que requiera el punto de conexión en línea de AML, si hay alguna

Nombre de parámetro	Descripción
`uri`	(Necesario para la autenticación con clave) El URI de puntuación del punto de conexión en línea de AML al que se envía la carga útil de JSON. Solo se permite el esquema de URI https. Para insertar modelos en el catálogo de modelos de Azure AI Foundry, este es el URI de destino.
`key`	(Obligatorio para la autenticación de claves) La clave para el punto de conexión en línea de AML o la
`resourceId`	(Necesario para la autenticación de tokens). El identificador de recursos de Azure Resource Manager del punto de conexión en línea de AML. Debe tener este formato: `subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{workspace-name}/onlineendpoints/{endpoint_name}`.
`region`	(Opcional para la autenticación de tokens). La región en la que se implementa el punto de conexión en línea de AML.
`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.
`degreeOfParallelism`	(Opcional) Cuando se especifica, indica el número de llamadas que realiza el indexador en paralelo al punto de conexión que ha proporcionado. Puede reducir este valor si el punto de conexión produce un error demasiado alto en una carga de solicitud. Puede generarlo si el punto de conexión puede aceptar más solicitudes y desea aumentar el rendimiento del indizador. 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.

Autenticación

Los puntos de conexión en línea de AML proporcionan dos opciones de autenticación:

Autenticación basada en claves. Se proporciona una clave estática para autenticar las solicitudes de puntuación de las aptitudes de AML. Establezca los uri parámetros y key para esta conexión.
Autenticación basada en tokens, donde el punto de conexión en línea de AML se implementa mediante la autenticación basada en tokens. La identidad administrada de Azure AI servicio Search debe estar habilitada y tener una asignación de roles en el área de trabajo. A continuación, la aptitud de AML usa la identidad administrada del servicio para autenticarse en el punto de conexión en línea de AML, sin que se necesiten claves estáticas. La identidad del servicio de búsqueda debe ser propietario o colaborador. Establezca el resourceId parámetro y, si el servicio de búsqueda está en una región diferente del área de trabajo de AML, establezca el region parámetro .

Entradas de la aptitud

Las entradas de aptitud son un nodo del documento enriquecido que se crea durante el descifrado de documentos. Por ejemplo, podría ser el documento raíz, una imagen normalizada o el contenido de un blob. No hay entradas predefinidas para esta aptitud. Para las entradas, debe especificar uno o varios nodos que se rellenan en el momento de la ejecución de la aptitud AML.

Salidas de la aptitud

Las salidas de aptitud son nuevos nodos de un documento enriquecido creado por la aptitud. No hay salidas predefinidas para esta aptitud. En el caso de las salidas, debe proporcionar nodos que se pueden rellenar a partir de la respuesta JSON de la aptitud de AML.

Definición de ejemplo

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A custom model that detects the language in a document.",
    "uri": "https://language-model.models.contoso.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "text",
        "source": "/document/content"
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Estructura de JSON de entrada de ejemplo

Esta estructura JSON representa la carga que se envía al punto de conexión en línea de AML. Los campos de nivel superior de la estructura corresponden a los "nombres" especificados en la sección inputs de la definición de la 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)

{
  "text": "Este es un contrato en Inglés"
}

Estructura JSON de salida de ejemplo

La salida corresponde a la respuesta devuelta desde el punto de conexión en línea de AML. El punto de conexión en línea de AML solo debe devolver una carga JSON (comprobada mediante el examen del encabezado de respuesta de Content-Type) y debe ser un objeto en el que los campos son enriquecimientos que coinciden con los "nombres" de la output y cuyo valor se considere el enriquecimiento.

{
    "detected_language_code": "es"
}

Definición de ejemplo de formas insertadas

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://language-model.models.contoso.com/score",
    "context": "/document",
    "inputs": [
      {
        "name": "shapedText",
        "sourceContext": "/document",
        "inputs": [
            {
              "name": "content",
              "source": "/document/content"
            }
        ]
      }
    ],
    "outputs": [
      {
        "name": "detected_language_code"
      }
    ]
  }

Estructura JSON de entrada de formas insertadas

{
  "shapedText": { "content": "Este es un contrato en Inglés" }
}

Estructura JSON de salida de ejemplo de formas insertadas

{
    "detected_language_code": "es"
}

Casos de error

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

El punto de conexión en línea de AML devuelve un código de estado correcto, pero la respuesta indica que no application/jsones , la respuesta se considera no válida y no se realiza ningún enriquecimiento.
El punto de conexión en línea de AML devuelve JSON no válido.

En los casos en los que el punto de conexión en línea de AML no está disponible o devuelve un error HTTP, se agrega un error descriptivo con los detalles disponibles sobre el error HTTP al historial de ejecución del indexador.

Compartir vía