Azure OpenAI Embedded skill

La habilidad Azure OpenAI Embedding se conecta con un modelo de incrustación desplegado en tu proyecto Azure OpenAI en Foundry Models o Microsoft Foundry para generar incrustaciones durante la indexación. Tus datos se procesan en la geometría donde se despliega tu modelo.

El asistente Importar datos en el portal de Azure utiliza la habilidad Azure OpenAI Embedding para vectorizar contenido. Puedes ejecutar el asistente y revisar el conjunto de habilidades generadas para ver cómo el asistente construye la habilidad para incrustar modelos.

Prerequisites

• Un recurso Azure OpenAI en Foundry Models o Foundry.

  • Tu recurso Azure OpenAI debe tener un subdominio personalizado, como https://<resource-name>.openai.azure.com. Puedes encontrar este endpoint en la página Keys and Endpoint en el portal de Azure y usarlo para la propiedad resourceUri en esta habilidad.

  • El recurso principal de tu proyecto Foundry proporciona acceso a múltiples endpoints, incluyendo https://<resource-name>.openai.azure.com, https://<resource-name>.services.ai.azure.com, y https://<resource-name>.cognitiveservices.azure.com. Puedes encontrar estos endpoints en la página Keys and Endpoint del portal de Azure y usar cualquiera de ellos para la propiedad resourceUri en esta habilidad.

• Un modelo de incrustación de Azure OpenAI desplegado en tu recurso o proyecto. Para modelos compatibles, consulta la sección de parámetros de habilidad .

@odata.type

Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill

Límites de datos

El tamaño máximo de una entrada de texto debe ser de 8.000 tokens. Si la entrada supera el máximo permitido, el modelo lanza un error de solicitud inválido. Para más información, consulte el concepto clave tokens en la documentación de Azure OpenAI. Considera usar la habilidad División de Texto si necesitas fragmentar datos.

Parámetros de aptitud

Los parámetros son sensibles a mayúsculas y mayúsculas.

Dimensiones soportadas por modelName

Las dimensiones soportadas para una habilidad de embebido Azure OpenAI dependen del modelName que esté configurado.

Entradas de habilidades

Resultados de habilidades

Definición de ejemplo

Consideremos un registro que tiene los siguientes campos:

{
    "content": "Microsoft released Windows 10."
}

Entonces tu definición de habilidad podría ser así:

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://my-demo-openai-eastus.openai.azure.com/",
  "deploymentId": "my-text-embedding-ada-002-model",
  "modelName": "text-embedding-ada-002",
  "dimensions": 1536,
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

Salida de ejemplo

Para el texto de entrada dado, se produce una salida de incrustación vectorizada.

{
  "embedding": [
        0.018990106880664825,
        -0.0073809814639389515,
        .... 
        0.021276434883475304,
      ]
}

La salida reside en la memoria. Para enviar esta salida a un campo en el índice de búsqueda, debes definir un outputFieldMapping que mapea la salida de incrustación vectorizada (que es un array) a un campo vectorial. Suponiendo que la salida de la habilidad reside en el nodo de incrustación del documento, y content_vector es el campo en el índice de búsqueda, el outputFieldMapping en el indexador debería verse así:

  "outputFieldMappings": [
    {
      "sourceFieldName": "/document/embedding/*",
      "targetFieldName": "content_vector"
    }
  ]

procedimientos recomendados

A continuación, se presentan algunas buenas prácticas que debes tener en cuenta al utilizar esta habilidad:

• Si alcanza el límite de TPM de OpenAI (Tokens por minuto) de Azure, tenga en cuenta el límite de quota limita el aviso para que pueda solucionarlo en consecuencia. Consulte la documentación Azure supervisión de OpenAI para obtener más información sobre el rendimiento de la instancia de OpenAI de Azure.

• El despliegue del modelo de embeddings de OpenAI Azure que utilices para esta habilidad debería estar idealmente separado del despliegue usado en otros casos de uso, incluyendo el vectorizador consulta. Esto ayuda a cada implementación a adaptarse a su caso de uso específico, lo que conduce a optimizar el rendimiento e identificar el tráfico desde el indexador y las llamadas de inserción de índices fácilmente.

• La instancia de OpenAI de Azure debe estar en la misma región o al menos cerca geográficamente de la región donde se hospeda el servicio de búsqueda de IA. Esto reduce la latencia y mejora la velocidad de transferencia de datos entre los servicios.

• Para evitar experimentar códigos de error 429 a menudo, considere la posibilidad de implementar el equilibrio de carga a través de API Management mediante la implementación de una puerta de enlace delante de varias implementaciones de modelos de inserción de OpenAI Azure.

• Si tiene un límite de Azure TPM de OpenAI (Tokens por minuto) mayor que el predeterminado, tal y como se publicó en quotas y límites, abra un caso de support con el equipo de Búsqueda de Azure AI, por lo que esto se puede ajustar en consecuencia. Esto ayuda a que el proceso de indexación no se ralentice innecesariamente mediante el límite de TPM predeterminado documentado, si tiene límites más altos.

• Para ejemplos y ejemplos de código que funcionan usando esta habilidad, consulta los siguientes enlaces:

  • Vectorización integrada (Python)
  • Vectorización integrada (C#)
  • Vectorización integrada (Java)

Errores y advertencias

Consideraciones de seguridad para la autenticación de identidad administrada

Cuando la aptitud de inserción de OpenAI de Azure usa la autenticación de identidad administrada, Búsqueda de Azure AI obtiene un token de acceso Microsoft Entra para la audiencia de Herramientas de Foundry (https://cognitiveservices.azure.com) e incluyelo en las solicitudes enviadas al punto de conexión especificado por resourceUri. La autenticación de identidad administrada se aplica cuando authIdentity se establece, o cuando ambos apiKey y authIdentity están vacíos y el servicio usa la identidad asignada por el sistema.

Se espera que el punto de conexión al resourceUri que hace referencia sea su propio recurso Azure OpenAI o Foundry Tools. Los dominios soportados son:

• openai.azure.com
• cognitiveservices.azure.com
• services.ai.azure.com

También se admiten puntos de conexión de Azure API Management (*.azure-api.netAPIM). Dado que un nombre de host de APIM no se puede comprobar solo con su nombre, Búsqueda de Azure AI valida estos puntos de conexión con una comprobación de conectividad activa en el momento de la configuración en lugar de mediante la coincidencia de dominios. Es responsable de configurar y mantener la relación entre el punto de conexión de APIM y el recurso de OpenAI o Foundry Tools de Azure detrás de él.

Un token de identidad administrada emitido para la audiencia de Foundry Tools es válido en cualquier recurso de Foundry Tools o Azure recurso de OpenAI en el que se autoriza la identidad. Enviarlo a un punto de conexión que no es de confianza podría exponer el token.

Procedimientos de seguridad recomendados

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

• Establezca resourceUri solo en los puntos de conexión que posee y confíe. Prefiere los dominios de Foundry Tools enumerados anteriormente. Si usa un punto de conexión de APIM, confirme que frente a su propio recurso antes de habilitar la identidad administrada. Un nombre de host de aspecto de confianza no es prueba de propiedad.
• Aplique el principio de privilegios mínimos a la identidad administrada usada por el servicio de búsqueda. La Azure aptitud de inserción de OpenAI solo requiere el rol de usuario openAI de Cognitive Services en el recurso de destino. Evite conceder roles más amplios.
• Use el perímetro de seguridad de red (NSP) y los puntos de conexión privados o la integración de red virtual para restringir los puntos de conexión a los que puede llegar el servicio de búsqueda y los orígenes desde los que el recurso de destino acepta solicitudes.
• Si usa un punto de conexión de APIM, asegúrese de que la puerta de enlace valida las solicitudes entrantes y las reenvía solo al back-end previsto. También debe revisar periódicamente sus directivas de acceso.
• Se prefiere la identidad administrada a través de apiKey. Si usa apiKey, almacene y gire de forma segura y no lo inserte en el control de código fuente. El servicio rechaza las configuraciones que establecen y apiKeyauthIdentity.
• Revise periódicamente las definiciones del conjunto de aptitudes, las asignaciones de roles de identidad administrada y las configuraciones de APIM para confirmar que resourceUri los valores, los controles de acceso y los permisos de identidad siguen siendo actuales y adecuados. Revise los cambios de configuración a través de los procesos establecidos de administración de cambios y revisión de seguridad.
• Supervise Azure registros de inicio de sesión de OpenAI y Foundry Tools, eventos de autenticación y registros de acceso para actividades inesperadas o no autorizadas.
• Quite las aptitudes, los puntos de conexión, las asignaciones de roles y las claves de API que ya no son necesarias.

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

Los usuarios que pueden crear, modificar o ejecutar conjuntos de aptitudes controlan tanto el punto de conexión de destino (resourceUri) como la configuración de autenticación usada por la aptitud. Dado que la aptitud envía un token de identidad administrada para la audiencia de Foundry Tools a ese punto de conexión, restrinja estos permisos a los administradores de confianza y siga los procesos estándar de administración de cambios y revisión de seguridad al configurar aptitudes habilitadas para identidad administrada.

Consulte también

• Aptitudes integradas
• Cómo definir un conjunto de habilidades
• Cómo definir las correspondencias de campos de salida