Segmenter et vectoriser du contenu avec la compétence Azure Content Understanding

Dans cet article, vous allez apprendre à utiliser la compétence Azure Content Understanding pour :

La compétence Azure Content Understanding retourne un ou plusieurs blocs par document. Chaque bloc contient du contenu au format Markdown, des métadonnées d’emplacement (numéros de page et polygones englobants) et des références facultatives aux images extraites. Lorsque vous définissez chunkingProperties.method sur semantic, les segments suivent les limites des paragraphes et des titres au lieu de plages de caractères fixes. Lorsque vous définissez modelName et modelDeployment, la compétence utilise un déploiement de complétion de conversation Azure OpenAI pour générer des descriptions d’images incorporées. La compétence intègre ensuite ces descriptions au contenu du fragment.

Cet article utilise les PDF d’exemple du régime d’assurance maladie à titre d’illustration. Vous pouvez exécuter le même pipeline sur n’importe quelle source de données prise en charge qui expose les fichiers dans un format pris en charge par Content Understanding.

Prerequisites

• Un service Recherche Azure AI dans n’importe quelle région prise en charge. Le service de recherche lui-même n’est pas limité par région pour ce scénario.

• Ressource Microsoft Foundry dans une region prise en charge par la compétence Azure Content Understanding. La description de l’image et la segmentation sont traitées dans la région de la ressource Foundry.

• Ressource Microsoft Foundry associée à l’ensemble de compétences pour la facturation. La compétence Azure Content Understanding est facturée selon la tarification d’Azure Content Understanding.

• (Facultatif) Déploiement Azure OpenAI d’un modèle d’achèvement de conversation (par exemple, gpt-4.1) dans la même ressource Foundry utilisée pour générer des descriptions d’images. Obligatoire uniquement si vous souhaitez des descriptions d’images basées sur l’IA.

• Déploiement Azure OpenAI d’un modèle d’incorporation (tel que text-embedding-3-small), utilisé par la compétence Azure OpenAI Embedding pour vectoriser les segments.

• Conteneur Stockage Blob Azure avec les fichiers à indexer. Cet article utilise une source de données blob avec le paramètre de l’indexeur allowSkillsetToReadFileData (utilisé pour transmettre le contenu du fichier à la compétence Content Understanding).

Overview

L’article construit un pipeline d’indexation de type un-à-plusieurs. Chaque document source produit plusieurs documents de recherche (un par segment) :

1. L’indexeur lit chaque fichier dans Stockage Blob Azure et transmet le contenu binaire au jeu de compétences via /document/file_data.

2. La compétence Azure Content Understanding utilise la segmentation sémantique (préversion) pour produire text_sections. Lorsque modelName et modelDeployment sont définis, cela génère également des descriptions des images incorporées par l’IA (aperçu) et les intègre directement dans le Markdown de chaque bloc.

3. La compétence Azure OpenAI Embedding s’exécute une fois par segment et génère un vecteur pour le contenu du segment.

4. Une projection d’indexation crée un document de recherche par segment dans l’index cible, en associant le contenu, les métadonnées de page, les références d’image et le vecteur à des champs.

5. (Facultatif) Une base de connaissances projette normalized_images dans Stockage Blob Azure afin que les applications clientes puissent récupérer les images extraites à l’aide d’une URL.

Préparer des fichiers de données

La compétence Azure Content Understanding traite le contenu binaire de chaque document. Les fichiers sources doivent donc être dans un format pris en charge par la compétence. Pour obtenir la liste actuelle, consultez les limites du service Content Understanding. Les formats pris en charge courants incluent PDF, DOCX, XLSX, PPTX et de nombreux formats d’image.

Chargez vos fichiers dans la source de données prise en charge. Vous pouvez utiliser le portail Azure, les API REST ou un Kit de développement logiciel (SDK) Azure pour créer la source de données.

La requête minimale suivante crée la source de données utilisée tout au long de cette procédure pas à pas.

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"
  }
}

Créer un index pour l’indexation un-à-plusieurs

Chaque document de recherche correspond à un bloc produit par la compétence Content Understanding. L’index a besoin des éléments suivants :

• Un champ clé (chunk_id).
• Champ parent qui identifie le document source du bloc (parent_id).
• Champs qui stockent le contenu de bloc, les métadonnées de page et les références d’image.
• Champ vectoriel pour l’incorporation de segments.

La définition d’index suivante correspond à l’ensemble de compétences que vous créez dans la section suivante.

{
  "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"
      }
    ]
  }
}

Définir un ensemble de compétences pour la segmentation sémantique (préversion) et la vectorisation

Une fois l’index cible en place, définissez le jeu de compétences qui produit les fragments, les vecteurs et les mappages de projection qui l’alimentent.

Le jeu de compétences comprend deux compétences :

• La compétence Azure Content Understanding segmente chaque document. Définir chunkingProperties.method sur semantic permet à la compétence de respecter les limites des paragraphes et des titres. Le fait de définir modelName et modelDeployment active les descriptions d’images générées par l’IA (préversion), que la compétence intègre directement au contenu du segment avant la vectorisation. Pour obtenir la liste des modèles d’achèvement de conversation pris en charge et d’autres détails de paramètres, consultez paramètres de compétence.

• La compétence d’incorporation Azure OpenAI génère un vecteur pour le contenu de chaque segment.

Le jeu de compétences utilise indexProjections pour associer chaque fragment à un document de recherche distinct. Pour plus d’informations, consultez Définir une projection d’index.

Avant d’envoyer la requête, remplacez <subdomain> par votre sous-domaine OpenAI Azure, <Azure OpenAI api key> par la clé de ressource d’incorporation et <Foundry resource key> par la clé de la ressource Foundry attachée à l’ensemble de compétences.

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"
    }
  }
}

Pour obtenir la référence complète des paramètres, les valeurs prises en charge et les règles de validation pour la compétence Content Understanding, consultez Azure compétence Content Understanding.

Configurer et exécuter l’indexeur

Créez et exécutez un indexeur qui lit à partir de votre source de données, appelle l’ensemble de compétences et projette les segments dans l’index. Définissez allowSkillsetToReadFileData sur true afin que la compétence Content Understanding reçoive le contenu du fichier, et définissez parsingMode sur default.

Vous n’avez pas besoin outputFieldMappings dans ce scénario. Le bloc indexProjections dans l’ensemble de compétences associe déjà chaque fragment aux champs de l’index cible.

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": []
}

Lorsque l’indexeur s’exécute, la compétence Content Understanding utilise la segmentation sémantique (préversion), génère éventuellement des descriptions d’images basées sur l’IA (préversion) et écrit un document de recherche par bloc dans l’index.

Vérifier l’état de l’indexeur

Avant d’interroger, vérifiez que l’exécution de l’indexeur s’est terminée :

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

Vérifiez que lastResult.status est success. Si la valeur est transientFailure avec itemsProcessed supérieur à 0, l’exécution est un succès partiel, et vous pouvez toujours interroger les blocs renseignés. Pour plus d’informations, consultez Surveiller l’état de l’indexeur.

Vérifier les résultats

Interrogez l’index pour vérifier que les blocs contiennent le contenu attendu et que la recherche vectorielle fonctionne comme prévu. Utilisez l’Explorateur de recherche ou tout outil qui envoie des requêtes HTTP.

La requête suivante exécute une requête hybride (recherche de mots clés sur chunk et requête vectorielle sur text_vector) pour confirmer que le texte segmenté et les incorporations sont remplis.

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"
}

Une réponse correcte se présente comme suit (abrégée par souci de concision) :

{
  "@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 réponse inclut :

• chunk: contenu Markdown de chaque bloc. Lorsque vous configurez modelDeployment et modelName, des descriptions d’images générées par l’IA (version préliminaire) s’affichent directement dans le Markdown.
• page_number_from et page_number_to: Plage de pages qui a produit le bloc.
• image_path: chemin d’accès à l’image extraite avec le bloc ou, lorsqu’un bloc s’étend sur plusieurs images, une liste de chemins séparés par des points-virgules. La forme exacte dépend de la configuration d’une projection de fichier de la base de connaissances. Sans projection de fichier, le chemin d’accès est le formulaire court indiqué dans l’exemple (figures/3). Dans le cas d’une projection de fichier, le chemin d’accès est le chemin relatif de l’image dans la base de connaissances. Pour mettre ces images à la disposition des applications clientes, consultez (Facultatif) Images du projet en vue de leur récupération.

(Facultatif) Images du projet pour la recherche

Les valeurs image_path stockées dans l’index sont des pointeurs vers l’arborescence d’enrichissement de la compétence, et non des URL directement récupérables. Pour récupérer des images, projetez normalized_images dans Stockage Blob Azure à l’aide d’un magasin de connaissances, puis générez une URL de blob pour chaque bloc.

Cette étape est facultative. Ajoutez-le uniquement si votre application cliente doit afficher ou télécharger les images extraites.

Ajoutez la propriété suivante à la charge utile de l’ensemble de compétences de la section précédente. La requête de l’ensemble de compétences utilise api-version=2026-08-01-preview.

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

Une fois l’indexeur exécuté, chaque objet blob du extracted-images conteneur correspond à un normalized_images élément. L’URL blob a la forme https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, où <imagePath> correspond à la valeur stockée dans le champ image_path.

Pour le schéma complet, y compris des types de projection supplémentaires (tables et objects) et des options d’authentification, consultez StoreKnowledge « projections » dans Recherche Azure AI.

Nettoyer les ressources

Lorsque vous avez terminé, supprimez l’indexeur, l’ensemble de compétences et l’index afin de ne plus engendrer de frais liés à Content Understanding et à Azure OpenAI. Les fichiers sources dans Stockage Blob Azure et la ressource Foundry elle-même restent jusqu’à ce que vous les supprimiez.

Résolution des problèmes

Si l’indexeur échoue ou retourne des résultats inattendus, vérifiez les causes courantes suivantes.

La validation du jeu de compétences échoue avec une erreur 400

La compétence retourne une 400 Skill validation failed erreur lorsque les combinaisons de paramètres sont en conflit. Causes courantes :

• modelName est défini sans modelDeployment, ou inversement. Les deux doivent être définis ensemble.
• method est semantic (préversion) et overlapLength est supérieur à 0. Définissez overlapLength sur 0 ou omettez-le.
• method et unit ne sont pas une paire prise en charge. Utiliser fixedSize avec characters ou semantic avec tokens.

L’autorisation échoue lors de l’accès à la ressource Foundry

Si la compétence renvoie un code 401 ou 403 lors de l’appel à la ressource Foundry, vérifiez que :

• Le bloc cognitiveServices dans le jeu de compétences fait référence à la ressource Foundry appropriée.
• L’identité utilisée par le service de recherche a le rôle requis sur la ressource Foundry. Pour les configurations d’identité managée, consultez Attacher une ressource facturable à un ensemble de compétences dans Recherche Azure AI.

text_sections est vide

Si les documents indexés n’ont pas de blocs, vérifiez que :

• Le format de fichier est pris en charge. Pour obtenir la liste, consultez les formats de fichier pris en charge.
• La ressource Foundry se trouve dans une région prise en charge.
• Les fichiers PDF protégés par mot de passe sont déverrouillés avant l’indexation.

Les descriptions d’image (aperçu) sont absentes

Si les blocs n’incluent pas de descriptions d’images inline, vérifiez que :

• Les paramètres modelName et modelDeployment sont tous deux définis dans l'ensemble de compétences.
• Le modèle de complétion de conversation dans modelName est déployé dans la même ressource Foundry référencée par l'ensemble de compétences.
• Le déploiement dispose d’un quota TPM ou RPM suffisant pour votre volume de documents.

L’indexeur expire sur les documents volumineux

Content Understanding applique un délai d’expiration de traitement par document. Si les fichiers PDF volumineux échouent :

• Fractionnez le document source en fichiers plus petits avant l’indexation.
• Réduisez batchSize à 1 afin que chaque document soit traité indépendamment.

Pour connaître les limites de données complètes de la compétence Azure Content Understanding, consultez les limites de Data.

Contenu connexe

• Compétence Azure Content Understanding
• Compétence d'intégration Azure OpenAI
• Recherche multimodale dans Recherche Azure AI
• Définir une projection d’index pour l’indexation parent-enfant
• Fractionner des documents volumineux pour le RAG et la recherche vectorielle