Habilidad de Prompt GenAI

La habilidad GenAI (IA Generativa) ejecuta una solicitud chat completion contra un gran modelo de lenguaje (LLM) desplegado en Azure OpenAI en Foundry Models o Microsoft Foundry. Utiliza esta habilidad para crear nueva información que pueda indexarse y almacenarse como contenido buscable.

Aquí tienes algunos ejemplos de cómo la habilidad de prompt de GenAI puede ayudarte a crear contenido:

• Verbalizar imágenes
• Resume los largos pasajes de texto
• Simplificar contenido complejo
• Realiza cualquier otra tarea que puedas expresar en un prompt

La habilidad GenAI Prompt está generalmente disponible en la API REST del servicio de búsqueda 2026-04-01 API y en SDK de Azure que se dirigen a esta versión. Esta habilidad soporta texto, imagen y contenido multimodal, como imágenes con imágenes y texto extraído de archivos PDF.

Modelos compatibles

• Puede usar cualquier modelo de inferencia de finalización de chat implementado en Foundry, como modelos GPT, DeepSeek-R#, Llama-4-Maverick y Cohere-command-r. Para los modelos GPT específicamente, solo se soportan los endpoints de la API de completación de chats. Los endpoints que usan la API de Azure OpenAI Responses (que contiene /openai/responses en el URI) no son compatibles actualmente.

• Para la verbalización de imágenes, el modelo que usas para analizar la imagen determina qué formatos de imagen se soportan.

• Para los modelos GPT-5, el temperature parámetro no está soportado de la misma manera que en modelos anteriores. Si está definido, debe establecerse en 1.0, ya que otros valores provocarán errores.

• La facturación se basa en el precio del modelo que uses.

Prerequisites

• Un recurso Azure OpenAI en Foundry Models o Foundry.

• Un modelo soportado desplegado en tu recurso o proyecto.

  • Para Azure OpenAI, copia el endpoint con el dominio openai.azure.com desde la página Keys y Endpoint en el portal Azure. Usa este endpoint como parámetro Uri en esta habilidad.

  • Para Foundry, copia el URI objetivo para el despliegue desde la página de Modelos en el portal de Foundry. Usa este endpoint como parámetro Uri en esta habilidad.

• La autenticación puede basarse en claves con una clave API de tu recurso OpenAI de Foundry o Azure. Sin embargo, recomendamos el acceso basado en roles usando una identidad gestionada por servicio de búsqueda asignada a un rol.

  • En Azure OpenAI, asigna Cognitive Services OpenAI User a la identidad gestionada.

  • En Foundry, asigne Foundry User a la identidad administrada.

    Importante

    Recientemente se cambió el nombre de los roles RBAC de Foundry. Foundry User, Foundry Owner, Foundry Account Owner y Foundry Project Manager se denominaron anteriormente Azure usuario de IA, propietario de Azure ai, propietario de Azure cuenta de IA y Azure AI Project Manager. Es posible que siga viendo los nombres anteriores en algunos lugares mientras se implementa el cambio de nombre. El cambio de nombre no modifica los identificadores de rol y los permisos principales.

@odata.type

#Microsoft.Skills.Custom.ChatCompletionSkill

Límites de datos

Parámetros de aptitud

* Debe usarse exactamente una de apiKey, authIdentity, o la identidad asignada por el sistema del servicio.

commonModelParameters Predeterminados

Entradas de habilidades

Resultados de habilidades

Definiciones de ejemplo

Resumen de solo texto

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Summarizer",
  "description": "Summarizes document content.",
  "context": "/document",
  "inputs": [
    { "name": "text", "source": "/document/content" },
    { "name": "systemMessage", "source": "='You are a concise AI assistant.'" },
    { "name": "userMessage", "source": "='Summarize the following text:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "commonModelParameters": { "temperature": 0.3 }
}

Descripción de texto + imagen

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "Image Describer",
  "context": "/document/normalized_images/*",
  "inputs": [
    { "name": "image", "source": "/document/normalized_images/*/data" },
    { "name": "imageDetail", "source": "=high" },
    { "name": "systemMessage", "source": "='You are a useful AI assistant.'" },
    { "name": "userMessage", "source": "='Describe this image:'" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "authIdentity": "11111111-2222-3333-4444-555555555555",
  "responseFormat": { "type": "text" }
}

Buscador numérico estructurado de hechos

{
  "@odata.type": "#Microsoft.Skills.Custom.ChatCompletionSkill",
  "name": "NumericalFactFinder",
  "context": "/document",
  "inputs": [
    { "name": "systemMessage", "source": "='You are an AI assistant that helps people find information.'" },
    { "name": "userMessage", "source": "='Find all the numerical data and put it in the specified fact format.'"}, 
    { "name": "text", "source": "/document/content" }
  ],
  "outputs": [ { "name": "response" } ],
  "uri": "https://demo.openai.azure.com/openai/deployments/gpt-4o/chat/completions",
  "apiKey": "<api-key>",
  "responseFormat": {
    "type": "json_schema",
    "jsonSchemaProperties": {
      "name": "NumericalFactObj",
      "strict": true,
      "schema": {
        "type": "object",
        "properties": "{\"facts\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"number\":{\"type\":\"number\"},\"fact\":{\"type\":\"string\"}},\"required\":[\"number\",\"fact\"]}}}",
        "required": [ "facts" ],
        "additionalProperties": false
      }
    }
  }
}

Salida de muestra (truncada)

{
  "response": {
    "facts": [
      { "number": 32.0, "fact": "Jordan scored 32 points per game in 1986-87." },
      { "number": 6.0,  "fact": "He won 6 NBA championships." }
    ]
  },
  "usageInformation": {
    "usage": {
      "completion_tokens": 203,
      "prompt_tokens": 248,
      "total_tokens": 451
    }
  }
}

procedimientos recomendados

• Agrupa documentos largos con la habilidad División de Texto para mantenerlos dentro de la ventana de contexto del modelo.
• Para indexación de alto volumen, dedica un despliegue de modelo separado a esta habilidad para que las cuotas de tokens para cargas de trabajo RAG en tiempo de consulta permanezcan intactas.
• Para minimizar la latencia, coloca el modelo y tu servicio Búsqueda de Azure AI en la misma región de Azure.
• Úsalo responseFormat.json_schema con GPT-4o para una extracción estructurada fiable y un mapeo más fácil a campos de índice.
• Monitoriza el uso de tokens y envía solicitudes de aumento de cuota si el indexador satura tus límites de Tokens por Minuto (TPM).

Errores y advertencias

Consideraciones de seguridad para la autenticación de identidad administrada

Cuando la aptitud Preguntar de GenAI usa la autenticación de identidad administrada, Búsqueda de Azure AI obtiene un token de acceso de Microsoft Entra para la audiencia de Foundry Tools (https://cognitiveservices.azure.com) e incluye en las solicitudes enviadas al punto de conexión especificado por uri. 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 uri que hace referencia sea su propio recurso Azure OpenAI o Foundry. Los dominios soportados son:

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

también se admiten los puntos de conexión de Azure API Management (*.azure-api.netAPIM) y dominios personalizados que tienen delante estos recursos. Dado que un dominio personalizado o un nombre de host de APIM no se pueden comprobar solo desde 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. Usted es responsable de configurar y mantener la relación entre el punto de conexión y el Azure recurso OpenAI o Foundry detrás de él.

Procedimientos de seguridad recomendados

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

• Establezca uri 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 o de dominio personalizado, 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:
  • En Azure OpenAI, asigne solo el usuario openAI de Cognitive Services.
  • En Foundry, asigne solo el usuario foundry. 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 o de dominio personalizado, 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 apiM y las configuraciones de dominio personalizado para confirmar que uri 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, Foundry Tools y Foundry, 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 (uri) 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

• Búsqueda de Azure AI indexadores integrados
• Vectorización integrada
• Cómo definir un conjunto de habilidades
• Cómo generar completaciones de chat con Azure inferencia de modelos de IA (Foundry)
• Salidas estructuradas en Azure OpenAI