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

  • Artículo

Importante

Esta aptitud está en versión preliminar pública en los términos de uso complementarios. La API REST de versión preliminar admite 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 las 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. 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.

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