Compartir vía

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

  • Artículo

Importante

La compatibilidad con conexiones de indexador al catálogo de modelos de Azure AI Studio 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 de IA con un modelo personalizado de Azure Machine Learning (AML). Una vez que un modelo de AML se ha entrenado e implementado, una aptitud de AML lo integra en el enriquecimiento con IA.

Como en el caso de otras aptitudes integradas, una aptitud de AML tiene entradas y salidas. Las entradas se envían a su punto de conexión en línea de AML implementado como un objeto JSON, que emite una carga útil JSON como respuesta junto con un código de estado de éxito. Los datos se procesan en la ubicación geográfica en la que se implementa el modelo. Se espera que la respuesta tenga las salidas especificadas por la aptitud de AML. Cualquier otra respuesta se considera un error y no se realiza ningún enriquecimiento.

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

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 introdujo el vectorizador de catálogo de modelos de Azure AI Studio para las conexiones de tiempo de consulta al catálogo de modelos en Azure AI Studio. Si desea usar ese vectorizador para consultas, la aptitud AML es el homólogo de indexación para generar incrustaciones mediante un modelo en el catálogo de modelos de Azure AI Studio.

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 Implementación de vectorización integrada mediante modelos de Azure AI Studio para más información sobre este flujo de trabajo.

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

Requisitos previos

@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.
key (Se requiere para la autenticación de clave) La clave del punto de conexión en línea de AML.
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. Debería estar en el formato subscriptions/{guid}/resourceGroups/{resource-group-name}/Microsoft.MachineLearningServices/workspaces/{nombre-área-trabajo}/onlineendpoints/{nombre-punto-de-conexión}.
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.

Qué parámetros de la aptitud se van a usar

Los parámetros de la aptitud de AML necesarios dependen de la autenticación que use el punto de conexión en línea de AML, si hay alguno. 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 aptitudes de AML.
    • Use los parámetros uri y key.
  • Autenticación basada en tokens El punto de conexión en línea de AML se implementa mediante la autenticación basada en tokens. La identidad administrada del servicio de Azure AI Search debe estar habilitada. 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 debe tener asignado el rol de propietario o colaborador.
    • Use el parámetro resourceId.
    • Si el servicio de búsqueda está en una región diferente del área de trabajo de AML, use el parámetro región para establecer la región en la que se implementó el punto de conexión en línea de AML

Entradas de la aptitud

No hay entradas "predefinidas" para esta aptitud. Puede elegir uno o más campos que ya estarían disponibles en el momento de la ejecución de esta aptitud como entradas y la carga de JSON enviada al punto de conexión en línea de AML tendrá distintos campos.

Salidas de la aptitud

No hay salidas "predefinidas" para esta aptitud. En función de la respuesta que devuelva el punto de conexión en línea de AML, agregue campos de salida para poder seleccionarlos desde la respuesta de JSON.

Definición de ejemplo

  {
    "@odata.type": "#Microsoft.Skills.Custom.AmlSkill",
    "description": "A sample model that detects the language of sentence",
    "uri": "https://contoso.count-things.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://contoso.count-things.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:

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

En los casos en que el punto de conexión en línea de AML 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