Mostrar imágenes incrustadas en documentos en recuperación de agentes (versión preliminar)

Utilice servicio de imágenes (versión preliminar) para mostrar imágenes incrustadas en documentos de origen (como diagramas, gráficos, infografías, formularios escaneados e imágenes de productos) durante la recuperación de agentes, para que su modelo de lenguaje grande (LLM) pueda razonar sobre el contexto visual junto con el texto al sintetizar una respuesta.

Cuando activas el servicio de imágenes, Búsqueda de Azure AI:

• En el momento de la indexación, extrae imágenes de documentos admitidos y las almacena en un almacén de recursos de blobs Azure proporcionado por el cliente.

• En el momento de la consulta, recupera esas imágenes durante la acción de recuperación, las codifica en base64 y las inserta como contenido multimodal en el prompt del LLM que genera la respuesta sintetizada.

En este artículo se muestra cómo habilitar el servicio de imágenes en una base de conocimiento, invalidarlo por solicitud, inspeccionar las estadísticas de servicio de imágenes y planear los requisitos del ciclo de vida de la cuenta de almacenamiento.

Soporte para el uso

Prerrequisitos

• Un servicio azure AI Search con una base de conocimiento que especifica un LLM. La base de conocimiento debe usar la síntesis de respuestas.

• Una fuente de conocimientos indexada basada en archivos configurada con un assetStore en su ingestionParameters. Tipos admitidos:

  • Fuente de conocimientos de blobs (Azure Blob Storage o Azure Data Lake Storage Gen2)
  • Origen de conocimiento indexado de OneLake
  • Origen de conocimiento indexado de SharePoint

  Para las fuentes de conocimiento de blobs que utilizan la extracción estándar, cumple los requisitos previos de la fuente de conocimiento de blobs.

• La fuente de conocimiento no debe configurar ingestionPermissionOptions.

• Documentos de origen que contienen imágenes extractables, como archivos PNG, archivos JPEG o ARCHIVOS PDF con imágenes incrustadas.

• Un recurso de Microsoft Foundry en una región compatible con Azure Content Understanding en Foundry Tools, con implementaciones de incrustación de Azure OpenAI y de modelos de chat multimodales. Utilice el punto de conexión del recurso con el formato https://<resource-name>.services.ai.azure.com.

• Permiso para crear o actualizar la base de conocimiento y el origen de conocimiento administrado. Configure la autenticación sin clave con los roles Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda asignados al usuario o a la identidad de automatización que realiza estas operaciones de administración (recomendado). Como alternativa, use una clave de API de administración.

• Permiso para invocar la acción "retrieve". Asigne el rol Lector de datos de índice de búsqueda a la identidad que envía solicitudes de recuperación (recomendadas) o use una clave de API de consulta.

• Para realizar llamadas salientes al LLM durante la síntesis de respuestas, el servicio de búsqueda debe tener una identidad administrada con permisos de Cognitive Services User en el recurso de Microsoft Foundry que aloja el LLM.

• Para el acceso al almacén de recursos, configure la identidad administrada del servicio de búsqueda, tal como se describe en Configuración del acceso al almacén de recursos y a la aplicación.

• La API de REST 2026-08-01-preview o un paquete de versión preliminar de SDK de Azure equivalente: .NET | Java | JavaScript | Python

Limitaciones y consideraciones

• El servicio de imágenes solo está disponible a través de la API retrieve en recuperación de agentes. Las consultas clásicas /docs/search no proporcionan imágenes insertadas en documentos para la síntesis de respuestas descendentes sin una solución o configuración personalizada.

• El servicio de imágenes solo funciona en el modo de salida de síntesis de respuestas. El modo de salida extractiveData omite la entrega de imágenes.

• El servicio de imágenes solo se aplica a fuentes de conocimientos indexados basadas en archivos que tienen configurado assetStore y fragmentos indexados con valores de image_path rellenados.

• En las bases de conocimiento mixtas, solo los tipos de fuentes de conocimiento admitidos (blob, OneLake indexado y SharePoint indexado) proporcionan imágenes incrustadas en los documentos para la síntesis posterior de respuestas. Otros tipos aún pueden contribuir a la fundamentación del texto.

• El servicio de imágenes no es compatible con las fuentes de conocimiento que utilizan ingestionPermissionOptions para incorporar permisos en el nivel de documento, incluidas las ACL, los ámbitos RBAC o las etiquetas de confidencialidad de Microsoft Purview. El almacén de recursos crea un almacén de conocimiento subyacente y los almacenes de conocimiento no admiten la herencia de permisos.

• El esquema de respuesta de recuperación no define campos para las rutas de imagen individuales del almacén de activos ni para los bytes de imagen enviados al modelo. La imageServing actividad notifica estadísticas agregadas de las imágenes recuperadas y enviadas al modelo.

• El acceso a imágenes se controla en el nivel de cuenta de almacenamiento, independientemente del acceso al contenido indexado. Cualquier identidad con acceso de lectura a la cuenta de almacenamiento de activos puede obtener sus imágenes.

• No almacene secretos (claves de cuenta, tokens, cadenas de conexión) en documentos de origen porque el contenido se puede devolver como datos de base.

• El servicio de imágenes puede aumentar la latencia en la síntesis de respuestas debido a la descarga de imágenes y al procesamiento de tokens multimodales. Ejecute consultas representativas con servicio de imágenes habilitados y deshabilitados y compare la latencia de respuesta con la actividad notificada imageServing .

• Content Understanding puede generar diferentes resultados de imagen para archivos PDF y DOCX. Si se requieren la extracción y la verbalización coherentes de imágenes insertadas, convierta documentos de origen en PDF o pruebe cada formato de origen con contenido representativo.

Cómo funciona el servicio de imágenes

El servicio de imágenes tiene dos fases:

• Indexación: Cuando se configura la extracción de contenido estándar y un almacén de activos en una fuente de conocimiento, la habilidad de Content Understanding generada divide el documento en fragmentos semánticos, conserva las tablas en formato Markdown y utiliza el LLM configurado para describir las figuras incrustadas. Las descripciones de las figuras pasan a formar parte del Markdown enriquecido que la habilidad de incrustación vectoriza. La habilidad también extrae imágenes a su almacén de activos de blobs y añade image_path referencias a fragmentos superpuestos.

  Al configurar un repositorio de recursos, el servicio de búsqueda también crea un almacén de conocimiento junto con la fuente de conocimiento para almacenar de forma persistente los artefactos de imagen extraídos. Puede inspeccionar y administrar este almacén de conocimiento como cualquier otro.

• Recuperación: Cuando la acción de recuperación se ejecuta con la función de imagen habilitada, el servicio de búsqueda captura las imágenes coincidentes del almacén de recursos, las codifica en base64 y las incluye como contenido bidireccional en el mensaje de síntesis de respuesta.

Configuración del acceso al almacén de recursos y a la aplicación

El servicio de imágenes abarca tres límites de confianza. Durante la indexación, el servicio de búsqueda escribe artefactos de imagen en el almacén de recursos. En el momento de la consulta, el servicio de búsqueda lee del almacén de recursos para recuperar imágenes. La aplicación también lee del almacén de recursos si necesita representar imágenes en una interfaz de usuario. Configure cada ruta de acceso para seguir el acceso con privilegios mínimos.

Acceso del servicio de búsqueda al almacén de recursos

• Use Microsoft Entra ID y una identidad administrada para el servicio de búsqueda. Asigne a la identidad el rol Colaborador de datos de Storage Blob en el ámbito de la cuenta de almacenamiento, ya que el indexador escribe artefactos de imagen y la acción de recuperación los lee. Cuando la fuente y los contenedores de activos comparten esa cuenta, el rol también proporciona acceso de lectura a los blobs de la fuente.

• No habilite el acceso público anónimo en el contenedor del almacén de recursos.

Acceso de la aplicación a las referencias de imagen

El índice generado almacena image_path referencias a imágenes en el almacén de recursos. El esquema de la respuesta de recuperación no define campos específicos para las rutas de las imágenes individuales del almacén de recursos ni para los bytes de imagen enviados al modelo. sourceData opcional son datos de referencia estructurados, y image_path no es obligatorio en ellos.

Para mostrar una imagen indizada en la aplicación:

1. Asigne a la identidad de su aplicación el rol Lector de datos de blobs de almacenamiento en el ámbito de la cuenta de almacenamiento de activos.

2. Asigne la identidad de la aplicación al rol Lector de datos de índice de búsqueda para que pueda consultar el índice generado.

3. Obtenga un image_path autorizado del índice generado mediante una consulta controlada por la aplicación o un punto final de servicio.

4. Compruebe que la referencia apunta a la cuenta de almacenamiento y al contenedor de activos esperados. Rechace las rutas no fiables antes de la búsqueda del blob.

5. Recupere el nombre del blob resultante del contenedor de activos utilizando la identidad de su aplicación.

Esta separación le permite controlar quién puede ver las imágenes de origen independientemente de quién puede llamar a la API de recuperación.

Configurar el almacén de recursos en una fuente de conocimientos

Configure assetStore en los ingestionParameters de un origen de conocimiento indizado compatible. El almacén de recursos es un contenedor de blobs que usted posee y en el que el servicio de búsqueda escribe los artefactos de imagen.

Para obtener instrucciones específicas de la fuente, consulte:

• Creación de un origen de conocimiento de blobs
• Crear un origen de conocimiento SharePoint indexado
• Creación de un origen de conocimiento de OneLake

Una fuente de conocimiento mínima de blobs con la publicación de imágenes habilitada tiene este aspecto:

PUT https://{service-name}.search.windows.net/knowledgesources/my-blob-ks?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "my-blob-ks",
  "kind": "azureBlob",
  "azureBlobParameters": {
    "connectionString": "ResourceId=<storage-resource-id>",
    "containerName": "source-documents",
    "ingestionParameters": {
      "assetStore": {
        "connectionString": "ResourceId=<storage-resource-id>",
        "containerName": "image-assets"
      },
      "chatCompletionModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
          "deploymentId": "gpt-4o",
          "modelName": "gpt-4o"
        }
      },
      "embeddingModel": {
        "kind": "azureOpenAI",
        "azureOpenAIParameters": {
          "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
          "deploymentId": "text-embedding-3-large",
          "modelName": "text-embedding-3-large"
        }
      },
      "contentExtractionMode": "standard",
      "aiServices": {
        "uri": "https://{foundry-resource}.services.ai.azure.com"
      }
    }
  }
}

Resultados de configuración

La combinación de assetStore, disableImageVerbalization y chatCompletionModel determina lo que almacena el indexador y lo que ve el modelo en el momento de la consulta:

• Almacén de recursos + verbalización (valor predeterminado):assetStore establecido, disableImageVerbalization queda como false, chatCompletionModel establecido. El indexador conserva las imágenes en el almacén de recursos y almacena descripciones de texto en el índice. La actividad de recuperación puede informar verbalizationUsed como true.

• Solo para el almacén de recursos:assetStore establecido, disableImageVerbalization establecido en true, chatCompletionModel no requerido. El indexador conserva las imágenes en el almacén de recursos, pero no genera descripciones de texto. La actividad de recuperación puede informar verbalizationUsed como false.

• Sin almacén de recursos, conjunto de modelos:assetStore no establecido, chatCompletionModel establecido. Solo descripciones de texto, sin artefactos de imagen. El servicio de imágenes no se aplica.

• Sin almacén de activos, sin modelo: Sin procesamiento de imágenes.

Comprobación de la configuración del almacén de recursos

Espere a que se complete la ingesta antes de continuar:

• Compruebe el estado del indexador en el portal de Azure o use Get Indexer Status (API REST).

• Compruebe si los fragmentos indexados tienen un campo rellenado image_path . Si image_path está vacío, compruebe el estado del indexador, la configuración del almacén de recursos del origen de conocimiento, el contenido del documento de origen y el contenido del contenedor de recursos.

• Inspeccione el contenedor del almacén de recursos. Debería ver blobs de imagen que el indexador escribió durante la ingesta.

Habilitar la publicación de imágenes en una base de conocimientos

Establezca enableImageServing en true en la referencia de la fuente de conocimientos de la definición de la base de conocimiento. Esta configuración se convierte en el valor predeterminado para cada solicitud de recuperación que tiene como destino el origen de conocimiento.

La definición de la base de conocimiento también especifica el LLM que se usa para la síntesis de respuestas en el momento de la consulta. Esta configuración es independiente de cualquier chatCompletionModel que establezca en los ingestionParameters de la fuente de conocimientos, que controla la verbalización de imágenes durante la indexación.

Si la base de conocimiento hace referencia a varias fuentes de conocimiento, establezca enableImageServing solo en los tipos de índice basados en archivos compatibles que tengan configurado assetStore. Los tipos no admitidos (como un índice de búsqueda, SharePoint remoto o la web) siguen contribuyendo a la fundamentación textual, pero no proporcionan imágenes integradas en los documentos para la generación posterior de respuestas.

PUT https://{service-name}.search.windows.net/knowledgebases/my-kb?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "name": "my-kb",
  "knowledgeSources": [
    {
      "name": "my-blob-ks",
      "enableImageServing": true
    }
  ],
  "outputMode": "answerSynthesis",
  "models": [
    {
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://{foundry-resource}.services.ai.azure.com",
        "deploymentId": "gpt-4o",
        "modelName": "gpt-4o"
      }
    }
  ]
}

Comprobar la habilitación del servicio de imágenes

Envíe una GET solicitud al punto de conexión de la base de conocimiento y compruebe que la referencia del origen de conocimiento incluye "enableImageServing": true.

Recuperar con servicio de imágenes

Llame a la acción de recuperación en la base de conocimiento. Para anular el valor predeterminado de la base de conocimiento para cada solicitud, establezca enableImageServing en la entrada correspondiente de knowledgeSourceParams.

POST https://{service-name}.search.windows.net/knowledgebases/my-kb/retrieve?api-version=2026-08-01-preview
Content-Type: application/json
Authorization: Bearer {{search-access-token}}

{
  "retrievalReasoningEffort": { "kind": "medium" },
  "outputMode": "answerSynthesis",
  "includeActivity": true,
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What's the wiring configuration shown in the installation guide?" }
      ]
    }
  ],
  "knowledgeSourceParams": [
    {
      "knowledgeSourceName": "my-blob-ks",
      "kind": "azureBlob",
      "enableImageServing": true
    }
  ]
}

¿Qué ocurre en el momento de la recuperación?

En el caso de las referencias de imagen asociadas al contenido coincidente, el servicio de búsqueda descarga las imágenes correspondientes del almacén de recursos, las codifica en base64 y las pasa como contenido bidireccional al modelo de síntesis de respuestas de bajada. Consulte las estadísticas agregadas sobre la entrega de imágenes en activity.imageServing. Para obtener la forma de respuesta exacta, consulte la documentación de referencia de Recuperación de conocimientos: recuperación (API REST).

Comprobar comportamiento de recuperación

Una respuesta de recuperación puede proporcionar estas señales de servicio de imágenes:

• Cuando includeActivity es true, la matriz imageServing informa de la actividad activity de una fuente de conocimiento cuando el servicio registra operaciones de suministro de imágenes.

• Un imagesSentToModel valor mayor que 0 significa que el servicio informa de que proporcionó imágenes al modelo de síntesis de respuestas de nivel inferior.

Reglas de precedencia

Cuando la definición de la base de conocimiento y la solicitud de recuperación especifican enableImageServing, el valor de la solicitud de recuperación tiene prioridad. La prioridad completa es:

1. El valor de knowledgeSourceParams[].enableImageServing en la solicitud de recuperación (si se ha establecido).
2. Valor de la referencia de origen de conocimiento coincidente en la definición de la base de conocimiento (si se establece).
3. false (valor predeterminado).

En la tabla siguiente se resumen las nueve combinaciones.

Inspeccionar estadísticas del servicio de imágenes

Cuando se ejecuta el servicio de imágenes, la respuesta de recuperación incluye una imageServing sección para cada origen de conocimiento dentro de la activity matriz. Use esta sección para comparar las imágenes recuperadas del almacén de recursos con las imágenes enviadas al modelo.

"activity": [
  {
    "type": "azureBlob",
    "knowledgeSourceName": "my-blob-ks",
    "imageServing": {
      "verbalizationUsed": true,
      "imagesRetrieved": 5,
      "imagesSentToModel": 4,
      "totalImageSizeBytes": 248361
    }
  }
]

El informe de campos:

• verbalizationUsed: La estadística de verbalización de imágenes comunicada por el servicio para la actividad de recuperación.

• imagesRetrieved: el número de imágenes recuperadas del almacén de recursos.

• imagesSentToModel: El número de imágenes enviadas al modelo posterior.

• totalImageSizeBytes: tamaño total, en bytes, de las imágenes enviadas al modelo.

Si imagesRetrieved es mayor que imagesSentToModel, no todas las imágenes recuperadas se enviaron al modelo.

Inspeccione verbalizationUsed e imagesSentToModel independientemente. Una respuesta puede indicar tanto verbalizationUsed como true, así como una o varias imágenes enviadas al modelo.

Probar servicio de imágenes de extremo a extremo

Use uno de los ejemplos siguientes para probar la configuración completa:

• Ejemplo de servicio de imágenes de C#
• ejemplo de servicio de imágenes de Python

Los ejemplos crean una fuente de conocimiento y una base de conocimiento de blobs, comparan las solicitudes de recuperación con el servicio de imágenes desactivado y activado, y analizan las estadísticas del servicio de imágenes. Además, utilizan una consulta independiente con índice de comodines para seleccionar un image_path y descargar ese activo. Los ejemplos seleccionan una referencia delimitada por punto y coma, quitan un prefijo de proyección, como 11.7: de una ruta de acceso relativa, o descodifican una ruta de acceso absoluta y quitan su segmento inicial de contenedor de recursos. Estas transformaciones son un comportamiento de ejemplo, no garantías de la API de recuperación. El recurso seleccionado no evidencia que la misma imagen contribuyó a una respuesta de recuperación determinada.

Una lista de comprobación de comparación A/B típica:

• Elija una pregunta que solo se pueda responder a partir de un diagrama, un gráfico o una imagen escaneada.

• Ejecute la solicitud de recuperación con enableImageServing: false y capture la respuesta.

• Ejecute la misma solicitud de recuperación con enableImageServing: true y compare las respuestas, la latencia y la actividad notificada.

• Trate las diferencias de respuesta como señales A/B de observación, no como prueba de que las imágenes causaron las diferencias. Un imagesSentToModel valor mayor que 0 significa que el servicio informa de que proporcionó imágenes al modelo.

Limpieza de recursos

Elimine la base de conocimiento antes de eliminar su origen de conocimiento. Al eliminar estos recursos Búsqueda de Azure AI no se eliminan documentos de origen ni blobs de imágenes proyectados en Azure Storage. Elimina esos blobs por separado solo cuando ningún canal de ingesta o recuperación retenido los necesite ya.

Solución de problemas

Utilice el bloque de actividad imageServing de Inspeccionar estadísticas del servicio de imágenes como primer diagnóstico. En la tabla siguiente se enumeran las comprobaciones de síntomas comunes sin asumir una única causa.

Contenido relacionado

• Consulta de una base de conocimiento
• Usar la síntesis de respuestas para las respuestas respaldadas por citas
• ¿Qué es un origen de conocimiento?
• Conceptos del almacén de conocimiento