Inhoud segmenteren en vectoriseren met de vaardigheid Azure Inhoudskennis

In dit artikel leert u hoe u de vaardigheid Azure Content Understanding gebruikt om:

De vaardigheid Azure Inhoudskennis retourneert een of meer segmenten per document. Elk segment bevat markdown-opgemaakte inhoud, locatiemetagegevens (paginanummers en begrenzingsveelhoeken) en optionele verwijzingen naar geëxtraheerde afbeeldingen. Wanneer u chunkingProperties.method instelt op semantic, volgen chunks de alinea- en kopgrenzen in plaats van segmenten met een vast aantal tekens. Wanneer u modelName en modelDeployment instelt, roept de vaardigheid een Azure OpenAI-implementatie voor chatvoltooiing aan om beschrijvingen van ingesloten afbeeldingen te genereren. De vaardigheid voegt deze beschrijvingen vervolgens samen in de segmentinhoud.

In dit artikel wordt gebruikgemaakt van de sample health plan PDF-bestanden ter illustratie. U kunt dezelfde pijplijn uitvoeren op elke ondersteunde gegevensbron die bestanden beschikbaar maakt in een indeling die Content Understanding ondersteunt.

Prerequisites

• Een Azure AI Zoeken-service in een ondersteunde regio. De zoekservice zelf is niet beperkt tot regio's voor dit scenario.

• Een Microsoft Foundry-resource in een regio die wordt ondersteund door de vaardigheid Azure Content Understanding. Beschrijving en segmentering van afbeeldingen worden verwerkt in de regio van de Foundry-resource.

• Een Microsoft Foundry-resource gekoppeld aan de vaardighedenset voor facturering. Voor de vaardigheid Azure Content Understanding worden kosten in rekening gebracht volgens de prijzen voor Azure Content Understanding.

• (Optioneel) Een Azure OpenAI-implementatie van een chatvoltooiingsmodel (zoals gpt-4.1) in dezelfde Foundry-resource, die wordt gebruikt voor het genereren van afbeeldingsbeschrijvingen. Alleen vereist als u beschrijvingen van ai-afbeeldingen wilt.

• Een Azure OpenAI-implementatie van een insluitmodel (zoals text-embedding-3-small), dat wordt gebruikt door de vaardigheid Azure OpenAI Embedding om segmenten te vectoriseren.

• Een Azure Blob Storage container met de bestanden die u wilt indexeren. In dit artikel wordt een blobgegevensbron gebruikt met de instelling voor de allowSkillsetToReadFileData indexeerfunctie (gebruikt om bestandsinhoud door te geven aan de vaardigheid Inhoudskennis).

Overview

In het artikel wordt een één-op-veel-indexeringspipeline beschreven. Elk brondocument produceert meerdere zoekdocumenten (één per segment):

1. De indexeerfunctie leest elk bestand uit Azure Blob Storage en geeft de binaire inhoud door aan de vaardighedenset via /document/file_data.

2. De Azure Content Understanding-vaardigheid gebruikt semantische opsplitsing (preview-versie) om text_sections te genereren. Wanneer modelName en modelDeployment zijn ingesteld, genereert het ook door AI gegenereerde beschrijvingen (preview) van ingebedde afbeeldingen en voegt het deze rechtstreeks toe aan de Markdown van elke chunk.

3. De vaardigheid Azure OpenAI Embedding wordt eenmaal per segment uitgevoerd en produceert een vector voor de segmentinhoud.

4. Een indexprojectie schrijft één zoekdocument per deel naar de doelindex en wijst inhoud, paginametagegevens, afbeeldingsverwijzingen en de vector toe aan velden.

5. (Optioneel) Een knowledge store projecteert normalized_images naar Azure Blob Storage, zodat clienttoepassingen de geëxtraheerde afbeeldingen via een URL kunnen ophalen.

Gegevensbestanden voorbereiden

De Azure Content Understanding-vaardigheid verwerkt de binaire inhoud van elk document, dus bronbestanden moeten een indeling hebben die door de vaardigheid wordt ondersteund. Zie de limieten van de Content Understanding-service voor de huidige lijst. Veelgebruikte ondersteunde indelingen zijn PDF, DOCX, XLSX, PPTX en veel afbeeldingsindelingen.

Upload uw bestanden naar de ondersteunde gegevensbron. U kunt de Azure-portal, REST API's of een Azure SDK gebruiken om de gegevensbron te maken.

Met de volgende minimale aanroep wordt de gegevensbron gemaakt waarvan in deze stapsgewijze handleiding gebruik wordt gemaakt.

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

Een index maken voor een-op-veel-indexering

Elk zoekdocument komt overeen met één segment dat wordt geproduceerd door de vaardigheid Content Understanding. De index heeft het volgende nodig:

• Een sleutelveld (chunk_id).
• Een bovenliggend veld waarmee wordt aangegeven uit welk brondocument het segment afkomstig is (parent_id).
• Velden die de segmentinhoud, metagegevens van pagina's en afbeeldingsverwijzingen opslaan.
• Een vectorveld voor de chunk-embedding.

De volgende indexdefinitie komt overeen met de vaardighedenset die u in de volgende sectie maakt.

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

Een vaardighedenset definiëren voor semantische segmentering (preview) en vectorisatie

Wanneer de doelindex gereed is, definieert u de skillset die de segmenten, vectoren en projectietoewijzingen produceert waarmee deze wordt gevuld.

De vaardighedenset heeft twee vaardigheden:

• De vaardigheid Azure Content Understanding segmenteert elk document. Door chunkingProperties.method in te stellen op semantic, zorgt u ervoor dat de vaardigheid de grenzen van alinea's en koppen respecteert. Door modelName en modelDeployment in te stellen, schakelt u door AI gegenereerde afbeeldingsbeschrijvingen (previewversie) in, die de vaardigheid vóór vectorisatie inline in de chunkinhoud opneemt. Zie Vaardigheidsparameters voor de lijst met ondersteunde modellen voor chatvoltooiing en andere parameterdetails.

• De vaardigheid Azure OpenAI Embedding genereert een vector voor de inhoud van elk segment.

De vaardighedenset gebruikt indexProjections om elk segment toe te wijzen aan een afzonderlijk zoekdocument. Zie Een indexprojectie definiëren voor meer informatie.

Voordat u de aanvraag verzendt, vervangt u <subdomain> door uw Azure OpenAI-subdomein, <Azure OpenAI api key> door de insluitingsresourcesleutel en <Foundry resource key> door de sleutel voor de Foundry-resource die is gekoppeld aan de vaardighedenset.

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

Zie Azure Content Understanding skill voor de volledige parameterreferentie, ondersteunde waarden en validatieregels voor de vaardigheid Content Understanding.

De indexeerfunctie configureren en uitvoeren

Maak en voer een indexeerfunctie uit die uit uw gegevensbron leest, de skillset aanroept en segmenten naar de index projecteert. Stel allowSkillsetToReadFileData in op true zodat de vaardigheid Content Understanding de bestandsinhoud ontvangt, en stel parsingMode in op default.

U hebt outputFieldMappings in dit scenario niet nodig. Het indexProjections blok in de vaardighedenset wijst elk segment al toe aan de doelindexvelden.

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

Wanneer de indexeerfunctie wordt uitgevoerd, gebruikt de vaardigheid Inhoudsbegrip semantische segmentering (preview), genereert optioneel op AI gebaseerde afbeeldingsbeschrijvingen (preview) en schrijft één zoekdocument per segment naar de index.

De status van de indexeerfunctie controleren

Controleer voordat u een query uitvoert of de uitvoering van de indexeerfunctie is voltooid:

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

Controleer of dat lastResult.status is success. Als het transientFailure is met itemsProcessed hoger dan 0, is de uitvoering gedeeltelijk geslaagd en kunt u nog steeds query’s uitvoeren op de gevulde segmenten. Zie De status van de indexeerfunctie controleren voor meer informatie.

Resultaten controleren

Voer een query uit op de index om te controleren of de segmenten de verwachte inhoud bevatten en dat vectorzoekopdrachten naar verwachting werken. Gebruik Search Explorer of een hulpprogramma waarmee HTTP-aanvragen worden verzonden.

Met de volgende aanroep wordt een hybride query uitgevoerd (zoeken op trefwoorden in chunk en een vectorquery op text_vector) om te bevestigen dat zowel de gesegmenteerde tekst als de embeddings zijn gevuld.

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

Een geslaagd antwoord ziet er ongeveer als volgt uit (afgekapt voor beknoptheid):

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

Het antwoord bevat:

• chunk: De Markdown-inhoud van elk segment. Wanneer u modelName en modelDeployment configureert, worden door AI gegenereerde afbeeldingsbeschrijvingen (preview) inline in de Markdown weergegeven.
• page_number_from en page_number_to: het paginabereik waaruit het tekstsegment afkomstig is.
• image_path: Het pad naar de afbeelding die is geëxtraheerd met het segment of, wanneer een segment meerdere afbeeldingen omvat, een door puntkomma's gescheiden lijst met paden. De exacte shape is afhankelijk van of een projectie van een knowledge store-bestand is geconfigureerd. Zonder een bestandsprojectie is het pad het korte formulier dat wordt weergegeven in het voorbeeld (figures/3). Bij een bestandsprojectie is het pad het relatieve pad van de afbeelding in de kennisopslag. Om deze images beschikbaar te maken voor client-apps, zie (Optioneel) Projectimages voor ophalen.

(Optioneel) Projectafbeeldingen om op te halen

De image_path waarden die in de index zijn opgeslagen, zijn aanwijzers in de verrijkingsstructuur van de vaardigheid, niet rechtstreeks ophaalbare URL's. Als u afbeeldingen wilt ophalen, schrijft u normalized_images met behulp van een kennisarchief weg naar Azure Blob Storage en genereert u vervolgens naast elk segment een blob-URL.

Deze stap is optioneel. Voeg deze alleen toe als de client-app de geëxtraheerde afbeeldingen moet weergeven of downloaden.

Voeg de volgende eigenschap toe aan de payload van de skillset in de vorige sectie. De aanvraag voor de vaardighedenset maakt gebruik van api-version=2026-08-01-preview.

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

Nadat de indexeerfunctie is uitgevoerd, komt elke blob in de extracted-images container overeen met één normalized_images element. De blob-URL heeft de vorm https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, waarbij <imagePath> overeenkomt met de waarde die is opgeslagen in het veld image_path.

Zie tables voor het volledige schema, inclusief aanvullende projectietypen (objects en ) en verificatieopties.

De hulpbronnen opschonen

Wanneer u klaar bent, verwijdert u de indexeerfunctie, vaardighedenset en index om te stoppen met het maken van kosten voor Content Understanding en Azure OpenAI. Bronbestanden in Azure Blob Storage en de Foundry-resource zelf blijven staan totdat u ze verwijdert.

Troubleshooting

Als de indexeerfunctie mislukt of onverwachte resultaten retourneert, controleert u de volgende veelvoorkomende oorzaken.

Validatie van de vaardighedenset mislukt met fout 400

De vaardigheid retourneert een 400 Skill validation failed fout wanneer parametercombinaties conflicteren. Veelvoorkomende oorzaken:

• modelName is ingesteld zonder modelDeployment, of omgekeerd. Beide moeten samen worden ingesteld.
• method is semantic (preview) en overlapLength is groter dan 0. Stel overlapLength deze in 0 of laat deze weg.
• method en unit zijn geen ondersteund paar. Gebruiken fixedSize met characters of semantic met tokens.

Autorisatie mislukt voor de Foundry-resource

Als de vaardigheid bij het aanroepen van de Foundry-resource de statuscode 401 of 403 retourneert, controleer of:

• Het cognitiveServices blok in de vaardighedenset verwijst naar de juiste Foundry-resource.
• De identiteit die door de zoekservice wordt gebruikt, heeft de vereiste rol voor de Foundry-resource. Zie Een factureerbare resource koppelen aan een vaardighedenset in Azure AI Zoeken voor installatie van beheerde identiteiten.

text_sections is leeg

Als geïndexeerde documenten geen segmenten hebben, controleert u of:

• De bestandsindeling wordt ondersteund. Zie Ondersteunde bestandsindelingen voor de lijst.
• De Foundry-resource bevindt zich in een ondersteunde regio.
• Pdf-bestanden die met een wachtwoord zijn beveiligd, worden ontgrendeld voordat ze worden geïndexeerd.

Afbeeldingsbeschrijvingen (preview) ontbreken

Als delen geen beschrijvingen van inline-afbeeldingen bevatten, controleer dan of:

• Zowel modelName als modelDeployment zijn ingesteld in de skillset.
• Het model voor chatvoltooiing in modelName is geïmplementeerd in dezelfde Foundry-resource waarnaar in de vaardighedenset wordt verwezen.
• De implementatie heeft voldoende TPM- of RPM-quotum voor uw documentvolume.

Er treedt een time-out op bij de indexeerfunctie op grote documenten

Content Understanding hanteert een verwerkingstime-out per document. Als grote PDF-bestanden mislukken:

• Splits het brondocument in kleinere bestanden voordat u indexeert.
• Verlaag batchSize naar 1 zodat elk document onafhankelijk wordt verwerkt.

Zie Data-limieten voor de volledige gegevenslimieten van de vaardigheid Azure Content Understanding.

Verwante inhoud

• Azure Content Understanding-vaardigheid
• Vaardigheid voor insluiten van Azure OpenAI
• Multimodal zoeken in Azure AI Zoeken
• Een indexprojectie definiëren voor ouder-kind indexering
• Segmenteer grote documenten voor RAG en vectorzoekopdrachten