Fragmentar y vectorizar contenido con la aptitud Azure Content Understanding

En este artículo, aprenderá a usar la aptitud Azure Content Understanding para:

La aptitud Azure Content Understanding devuelve uno o varios fragmentos por documento. Cada fragmento contiene contenido con formato Markdown, metadatos de ubicación (números de página y polígonos delimitador) y referencias opcionales a imágenes extraídas. Cuando configuras chunkingProperties.method como semantic, los fragmentos siguen los límites de los párrafos y los encabezados en lugar de segmentos de caracteres fijos. Al establecer modelName y modelDeployment, la aptitud llama a una implementación de finalización de chat de Azure OpenAI para generar descripciones de imágenes insertadas. Luego, la habilidad integra esas descripciones en el contenido del fragmento.

En este artículo se utilizan los PDF de muestra del plan de salud a modo de ilustración. Puede ejecutar la misma canalización con cualquier origen de datos compatible que ofrezca archivos en un formato que admita Content Understanding.

Prerrequisitos

• Un servicio de Búsqueda de Azure AI en cualquier región admitida. El propio servicio de búsqueda no está restringido por regiones para este escenario.

• Un recurso de Microsoft Foundry en una región compatible con la habilidad de Azure Content Understanding. La descripción de la imagen y la fragmentación se procesan en la región del recurso de Foundry.

• Un recurso de Microsoft Foundry asociado al conjunto de aptitudes para facturación. La habilidad Azure Content Understanding se factura según los precios de Azure Content Understanding.

• (Opcional) Una implementación de Azure OpenAI de un modelo de finalización de chat (como gpt-4.1) en el mismo recurso de Foundry, que se utiliza para generar descripciones de imágenes. Solo es necesario si desea descripciones de imágenes basadas en IA.

• Una implementación de Azure OpenAI de un modelo de inserción vectorial (como text-embedding-3-small), que utiliza la Azure OpenAI Embedding skill para vectorizar fragmentos.

• Un contenedor Azure Blob Storage con los archivos que desea indexar. En este artículo se usa un origen de datos de blobs con la configuración del indexador allowSkillsetToReadFileData (que se usa para pasar el contenido del archivo a la aptitud Content Understanding).

Overview

En el artículo se compila una canalización de indexación de uno a varios. Cada documento de origen genera varios documentos de búsqueda (uno por fragmento):

1. El indexador lee cada archivo de Azure Blob Storage y pasa el contenido binario al conjunto de aptitudes a través de /document/file_data.

2. La habilidad Azure Content Understanding utiliza la fragmentación semántica (versión preliminar) para generar text_sections. Cuando se configuran modelName y modelDeployment, también genera descripciones de imágenes incrustadas creadas por IA (versión preliminar) y las inserta en el Markdown de cada fragmento.

3. La aptitud de inserción de Azure OpenAI se ejecuta una vez por fragmento y genera un vector para el contenido del fragmento.

4. Una proyección de índice escribe un documento de búsqueda por fragmento en el índice de destino, asignando contenido, metadatos de página, referencias de imagen y el vector a campos.

5. (Opcional) Un almacén de conocimiento exporta normalized_images a Azure Blob Storage para que las aplicaciones clientes puedan recuperar las imágenes extraídas mediante una dirección URL.

Preparación de los archivos de datos

La aptitud Azure Content Understanding procesa el contenido binario de cada documento, por lo que los archivos de origen deben tener un formato compatible con la aptitud. Para obtener la lista actual, consulte los límites del servicio Content Understanding. Entre los formatos admitidos comunes se incluyen PDF, DOCX, XLSX, PPTX y muchos formatos de imagen.

Cargue sus archivos al origen de datos admitido. Puede usar el portal de Azure, las API REST o un SDK de Azure para crear el origen de datos.

La siguiente solicitud mínima crea el origen de datos usado en este tutorial.

POST {endpoint}/datasources?api-version=2026-08-01-preview

{
  "name": "my_blob_datasource",
  "type": "azureblob",
  "credentials": {
    "connectionString": "<your-blob-connection-string>"
  },
  "container": {
    "name": "my-container"
  }
}

Crea un índice para indexación de uno a muchos

Cada documento de búsqueda corresponde a un fragmento generado por la aptitud Content Understanding. El índice necesita:

• Un campo de clave (chunk_id).
• Campo primario que identifica el documento de origen del que procede el fragmento (parent_id).
• Campos que almacenan el contenido del fragmento, los metadatos de página y las referencias de imagen.
• Campo vectorial para la inserción de fragmentos.

La siguiente definición de índice coincide con el conjunto de aptitudes que se crea en la sección siguiente.

{
  "name": "my_content_understanding_index",
  "fields": [
    {
      "name": "chunk_id",
      "type": "Edm.String",
      "key": true,
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false,
      "analyzer": "keyword"
    },
    {
      "name": "parent_id",
      "type": "Edm.String",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "title",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "chunk",
      "type": "Edm.String",
      "searchable": true,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "page_number_from",
      "type": "Edm.Int32",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false
    },
    {
      "name": "page_number_to",
      "type": "Edm.Int32",
      "searchable": false,
      "filterable": true,
      "retrievable": true,
      "stored": true,
      "sortable": true,
      "facetable": false
    },
    {
      "name": "image_path",
      "type": "Edm.String",
      "searchable": false,
      "filterable": false,
      "retrievable": true,
      "stored": true,
      "sortable": false,
      "facetable": false
    },
    {
      "name": "text_vector",
      "type": "Collection(Edm.Single)",
      "searchable": true,
      "retrievable": true,
      "stored": false,
      "dimensions": 1536,
      "vectorSearchProfile": "profile"
    }
  ],
  "vectorSearch": {
    "profiles": [
      {
        "name": "profile",
        "algorithm": "algorithm"
      }
    ],
    "algorithms": [
      {
        "name": "algorithm",
        "kind": "hnsw"
      }
    ]
  }
}

Definición de un conjunto de aptitudes para la fragmentación semántica (versión preliminar) y la vectorización

Con el índice de destino ya creado, defina el conjunto de aptitudes que produce los fragmentos, vectores y asignaciones de proyección para alimentarlo.

El conjunto de habilidades tiene dos habilidades:

• La habilidad Azure Content Understanding fragmenta cada documento. Configurar chunkingProperties.method en semantic hace que la habilidad respete los límites de los párrafos y los encabezados. Establecer modelName y modelDeployment habilita las descripciones de imágenes generadas por IA (versión preliminar), que la habilidad incorpora en el contenido del fragmento antes de la vectorización. Para obtener la lista de modelos de finalización de chat admitidos y otros detalles de parámetros, consulte Parámetros de aptitud.

• La aptitud Inserción de Azure OpenAI genera un vector para el contenido de cada fragmento.

El conjunto de aptitudes usa indexProjections para asignar cada fragmento a un documento de búsqueda distinto. Para obtener más información, consulte Definición de una proyección de índice.

Antes de enviar la solicitud, reemplace <subdomain> por el subdominio OpenAI de Azure, <Azure OpenAI api key> por la clave embedding-resource y <Foundry resource key> por la clave del recurso Foundry asociado al conjunto de aptitudes.

POST {endpoint}/skillsets?api-version=2026-08-01-preview

{
  "name": "my_content_understanding_skillset",
  "description": "Semantic chunking, image descriptions, and vectorization with the Azure Content Understanding skill",
  "skills": [
    {
      "@odata.type": "#Microsoft.Skills.Util.ContentUnderstandingSkill",
      "name": "my_content_understanding_skill",
      "context": "/document",
      "modelName": "gpt-4.1",
      "modelDeployment": "my-gpt-4-1-deployment",
      "chunkingProperties": {
        "method": "semantic",
        "unit": "tokens",
        "maximumLength": 500
      },
      "extractionOptions": ["images", "locationMetadata"],
      "inputs": [
        {
          "name": "file_data",
          "source": "/document/file_data"
        }
      ],
      "outputs": [
        {
          "name": "text_sections",
          "targetName": "text_sections"
        },
        {
          "name": "normalized_images",
          "targetName": "normalized_images"
        }
      ]
    },
    {
      "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
      "name": "my_azure_openai_embedding_skill",
      "context": "/document/text_sections/*",
      "inputs": [
        {
          "name": "text",
          "source": "/document/text_sections/*/content"
        }
      ],
      "outputs": [
        {
          "name": "embedding",
          "targetName": "text_vector"
        }
      ],
      "resourceUri": "https://<subdomain>.openai.azure.com",
      "deploymentId": "text-embedding-3-small",
      "modelName": "text-embedding-3-small",
      "apiKey": "<Azure OpenAI api key>"
    }
  ],
  "cognitiveServices": {
    "@odata.type": "#Microsoft.Azure.Search.CognitiveServicesByKey",
    "key": "<Foundry resource key>"
  },
  "indexProjections": {
    "selectors": [
      {
        "targetIndexName": "my_content_understanding_index",
        "parentKeyFieldName": "parent_id",
        "sourceContext": "/document/text_sections/*",
        "mappings": [
          {
            "name": "chunk",
            "source": "/document/text_sections/*/content"
          },
          {
            "name": "text_vector",
            "source": "/document/text_sections/*/text_vector"
          },
          {
            "name": "page_number_from",
            "source": "/document/text_sections/*/locationMetadata/pageNumberFrom"
          },
          {
            "name": "page_number_to",
            "source": "/document/text_sections/*/locationMetadata/pageNumberTo"
          },
          {
            "name": "image_path",
            "source": "/document/text_sections/*/imagePath"
          },
          {
            "name": "title",
            "source": "/document/metadata_storage_name"
          }
        ]
      }
    ],
    "parameters": {
      "projectionMode": "skipIndexingParentDocuments"
    }
  }
}

Para obtener la referencia completa de los parámetros, los valores admitidos y las reglas de validación de la habilidad Content Understanding, consulte habilidad Azure Content Understanding.

Configuración y ejecución del indexador

Cree y ejecute un indexador que lea en el origen de datos, llame al conjunto de aptitudes y proyecte fragmentos al índice. Establezca allowSkillsetToReadFileData en true para que la aptitud de Comprensión de contenido reciba el contenido del archivo, y establezca parsingMode en default.

No es necesario outputFieldMappings en este escenario. El bloque indexProjections del conjunto de aptitudes ya asigna cada fragmento a los campos del índice de destino.

POST {endpoint}/indexers?api-version=2026-08-01-preview

{
  "name": "my_content_understanding_indexer",
  "dataSourceName": "my_blob_datasource",
  "targetIndexName": "my_content_understanding_index",
  "skillsetName": "my_content_understanding_skillset",
  "parameters": {
    "batchSize": 1,
    "configuration": {
      "dataToExtract": "contentAndMetadata",
      "parsingMode": "default",
      "allowSkillsetToReadFileData": true
    }
  },
  "fieldMappings": [],
  "outputFieldMappings": []
}

Cuando se ejecuta el indexador, la aptitud Content Understanding usa la fragmentación semántica (versión preliminar), genera opcionalmente descripciones de imágenes basadas en IA (versión preliminar) y escribe un documento de búsqueda por fragmento en el índice.

Comprobación del estado del indexador

Antes de consultarlo, confirme que la ejecución del indexador ha finalizado:

GET {endpoint}/indexers/my_content_understanding_indexer/status?api-version=2026-08-01-preview

Compruebe que lastResult.status es success. Si es transientFailure con itemsProcessed más alto que 0, la ejecución es un éxito parcial y puede seguir consultando los fragmentos rellenados. Para obtener más información, consulte Supervisión del estado del indexador.

Comprobación de los resultados

Consulte el índice para comprobar que los fragmentos contienen el contenido esperado y que la búsqueda de vectores funciona según lo previsto. Use el Explorador de búsqueda o cualquier herramienta que envíe solicitudes HTTP.

La siguiente solicitud ejecuta una consulta híbrida (búsqueda de palabras clave en chunk y una consulta vectorial en text_vector) para confirmar que se rellenan tanto el texto fragmentado como las incrustaciones.

POST /indexes/my_content_understanding_index/docs/search?api-version=2026-08-01-preview
{
  "search": "copay for in-network providers",
  "count": true,
  "searchMode": "all",
  "vectorQueries": [
    {
      "kind": "text",
      "text": "copay for in-network providers",
      "fields": "text_vector"
    }
  ],
  "select": "chunk, title, page_number_from, page_number_to, image_path"
}

Una respuesta correcta es similar a la siguiente (recortada para mayor brevedad):

{
  "@odata.count": 2,
  "value": [
    {
      "@search.score": 0.0317,
      "chunk": "## Cost sharing\n\nFor in-network providers, the copay is $20 per visit...\n\n![Chart: Copay comparison across plans](figures/3)",
      "title": "Northwind_Standard_Benefits_Details.pdf",
      "page_number_from": 4,
      "page_number_to": 4,
      "image_path": "figures/3"
    },
    {
      "@search.score": 0.0289,
      "chunk": "### Out-of-network providers\n\nWhen you visit a provider that isn't in the Northwind network, the copay is $40 per visit...",
      "title": "Northwind_Standard_Benefits_Details.pdf",
      "page_number_from": 5,
      "page_number_to": 6,
      "image_path": null
    }
  ]
}

La respuesta incluye:

• chunk: el contenido de Markdown de cada fragmento. Al configurar modelName y modelDeployment, las descripciones de imágenes generadas por IA (versión preliminar) aparecen en línea dentro de Markdown.
• page_number_from y page_number_to: el intervalo de páginas que generó el fragmento.
• image_path: ruta de acceso a la imagen extraída con el fragmento o, cuando un fragmento abarca varias imágenes, una lista separada por punto y coma de rutas de acceso. La forma exacta depende de si se configura una proyección de archivos del almacén de conocimiento. Sin una proyección de archivos, la ruta es la forma abreviada que se muestra en el ejemplo (figures/3). Con una proyección de archivos, la ruta es la ruta relativa de la imagen en el almacén de conocimiento. Para que estas imágenes estén disponibles para las aplicaciones cliente, consulte (Opcional) Proyectar imágenes para su recuperación.

(Opcional) imágenes de Project para la recuperación

Los valores image_path almacenados en el índice son punteros al árbol de enriquecimiento de la aptitud, no a direcciones URL recuperables directamente. Para recuperar imágenes, proyecte normalized_images en Azure Blob Storage usando un almacén de conocimiento y, a continuación, derive una URL de blob para cada fragmento.

Este paso es opcional. Agréguelo solo si la aplicación cliente necesita mostrar o descargar las imágenes extraídas.

Agregue la siguiente propiedad a la carga del conjunto de aptitudes de la sección anterior. La solicitud del conjunto de aptitudes usa api-version=2026-08-01-preview.

"knowledgeStore": {
  "storageConnectionString": "<your-azure-storage-connection-string>",
  "projections": [
    {
      "files": [
        {
          "storageContainer": "extracted-images",
          "source": "/document/normalized_images/*"
        }
      ],
      "tables": [],
      "objects": []
    }
  ]
}

Una vez que se ejecuta el indexador, cada blob del extracted-images contenedor corresponde a un normalized_images elemento. La dirección URL del blob tiene el formulario https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, donde <imagePath> coincide con el valor almacenado en el image_path campo .

Para obtener el esquema completo, incluidos los tipos de proyección adicionales (tables y objects) y las opciones de autenticación, consulte Proyecciones de Knowledge Store en Búsqueda de Azure AI.

Limpieza de recursos

Cuando haya terminado, elimine el indexador, el conjunto de aptitudes y el índice para dejar de incurrir en los cargos de Content Understanding y Azure OpenAI. Los archivos de origen de Azure Blob Storage y el propio recurso Foundry permanecen hasta que los elimine.

Solución de problemas

Si el indexador produce un error o devuelve resultados inesperados, compruebe las siguientes causas comunes.

La validación del conjunto de aptitudes devuelve un error 400

La aptitud devuelve un 400 Skill validation failed error cuando entran en conflicto las combinaciones de parámetros. Causas comunes:

• modelName se establece sin modelDeployment, o viceversa. Ambos deben configurarse al mismo tiempo.
• method es overlapLength (versión preliminar) y semantic es mayor que 0. Establezca overlapLength en 0 o omítalo.
• method y unit no son un par admitido. Usa fixedSize con characters o semantic con tokens.

Error de autorización en el recurso Foundry

Si la habilidad devuelve un error 401 o 403 al llamar al recurso de Foundry, compruebe que:

• El bloque cognitiveServices del conjunto de aptitudes apunta al recurso correcto de Foundry.
• La identidad usada por el servicio de búsqueda tiene el rol necesario en el recurso Foundry. Para las configuraciones de identidad administrada, consulte Adjuntar un recurso facturable a un conjunto de aptitudes en Búsqueda de Azure AI.

text_sections está vacío

Si los documentos indexados no tienen fragmentos, compruebe que:

• Se admite el formato de archivo. Para obtener la lista, consulte Formatos de archivo admitidos.
• El recurso Foundry está en una región compatible.
• Los archivos PDF protegidos con contraseña se desbloquean antes de la indexación.

Faltan descripciones de imágenes (versión preliminar)

Si los fragmentos no incluyen descripciones integradas de imágenes, compruebe que:

• Tanto modelName como modelDeployment están establecidos en el conjunto de aptitudes.
• El modelo de finalización de chat en modelName se implementa en el mismo recurso de Foundry al que hace referencia el conjunto de aptitudes.
• La implementación tiene suficiente cuota de TPM o RPM para el volumen del documento.

Se agota el tiempo de espera del indexador con documentos grandes

Content Understanding aplica un tiempo de espera para el procesamiento de cada documento. Si se produce un error en archivos PDF grandes:

• Divida el documento de origen en archivos más pequeños antes de la indexación.
• Reduzca batchSize a 1 para que cada documento se procese de forma independiente.

Para conocer los límites de datos completos de la habilidad Azure Content Understanding, consulte Límites de datos.

Contenido relacionado

• Habilidad de Comprensión de Contenidos de Azure
• Aptitud de inserción de Azure OpenAI
• Búsqueda multimodal en Búsqueda de Azure AI
• Definir una proyección de un índice para la indexación de padre-hijo
• Dividir documentos grandes para RAG y búsqueda vectorial