Dela upp och vektorisera innehåll med Azure Content Understanding-kompetensen

I den här artikeln får du lära dig hur du använder Azure Content Understanding för att:

Kompetensen Azure Content Understanding returnerar en eller flera delar för varje dokument. Varje segment innehåller Markdown-formaterat innehåll, platsmetadata (sidnummer och avgränsande polygoner) och valfria referenser till extraherade bilder. När du anger chunkingProperties.method till semanticföljer segment stycke- och rubrikgränser i stället för intervall med fasta tecken. När du anger modelName och modelDeployment anropar färdigheten en distribution för chattkomplettering i Azure OpenAI för att generera beskrivningar av inbäddade bilder. Kompetensen sammanfogar sedan dessa beskrivningar med segmentets innehåll.

I den här artikeln används exempel-pdf:er för sjukförsäkringsplaner som illustrationer. Du kan köra samma pipeline mot alla datakällor som stöds och som exponerar filer i ett format som Content Understanding stöder.

Förutsättningar

• En Azure AI-sökning tjänst i alla regioner som stöds . Själva söktjänsten är inte regionbegränsad för det här scenariot.

• En Microsoft Foundry-resurs i en region som stöds av färdigheten Azure Content Understanding. Bildbeskrivning och uppdelning i segment bearbetas i Foundry-resursens region.

• En Microsoft Foundry-resurs kopplad till kompetensuppsättningen för fakturering. Den Azure Content Understanding-färdigheten debiteras enligt prissättningen Azure Content Understanding.

• (Valfritt) En Azure OpenAI-distribution av en modell för chattens slutförande (till exempel gpt-4.1) i samma Foundry-resurs som används för att generera bildbeskrivningar. Krävs endast om du vill ha AI-baserade bildbeskrivningar.

• En Azure OpenAI-distribution av en inbäddningsmodell (till exempel text-embedding-3-small), som används av Azure OpenAI-inbäddningsfärdighet för att vektorisera segment.

• En Azure Blob Storage container med de filer som du vill indexeras. Den här artikeln använder en blob-datakälla med indexerarinställningen allowSkillsetToReadFileData (som används för att skicka filinnehåll till Content Understanding-färdigheten).

Overview

Artikeln skapar en en-till-många-indexeringspipeline. Varje källdokument skapar flera sökdokument (ett per segment):

1. Indexeraren läser varje fil från Azure Blob Storage och skickar det binära innehållet till skillsetet via /document/file_data.

2. Färdigheten Azure Content Understanding använder semantisk uppdelning (förhandsversion) för att skapa text_sections. När modelName och modelDeployment anges skapas även AI-genererade beskrivningar (förhandsversion) av inbäddade bilder och infogar dem i varje segments Markdown.

3. Azure OpenAI-inbäddningsfärdigheten körs en gång per segment och skapar en vektor för segmentinnehållet.

4. En indexprojektion skriver ett sökdokument per segment till målindexet, mappar innehåll, sidmetadata, bildreferenser och vektor till fält.

5. (Valfritt) Ett knowledge store projekt normalized_images till Azure Blob Storage så att klientappar kan hämta de extraherade bilderna via URL.

Förbereda datafiler

Kunskapen Azure Content Understanding bearbetar det binära innehållet i varje dokument, så källfilerna måste vara i ett format som kunskapen stöder. Den aktuella listan finns i innehållstolkningstjänstens gränser. Vanliga format som stöds är PDF, DOCX, XLSX, PPTX och många bildformat.

Ladda upp dina filer till den datakälla som stöds. Du kan använda Azure-portalen, REST-API:er eller en Azure SDKs för att skapa datakällan.

Följande minimala begäran skapar den datakälla som används under den här genomgången.

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

Skapa ett index för en-till-många-indexering

Varje sökdokument motsvarar ett segment som skapats av content understanding-färdigheten. Indexet behöver:

• Ett nyckelfält (chunk_id).
• Ett överordnat fält som identifierar vilket källdokument segmentet kom från (parent_id).
• Fält som lagrar segmentinnehåll, sidmetadata och bildreferenser.
• Ett vektorfält för segmentbäddning.

Följande indexdefinition matchar den kompetensuppsättning som du skapar i nästa avsnitt.

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

Definiera en kompetensuppsättning för semantisk segmentering (förhandsversion) och vektorisering

När målindexet är på plats definierar du den kompetensuppsättning som producerar de segment, vektorer och projektionsmappningar som matar det.

Kompetensuppsättningen har två kompetenser:

• Kunskapen Azure Content Understanding segmentar varje dokument. Att ställa in chunkingProperties.method till semantic gör att kompetensen respekterar stycke- och rubrikgränser. Om du anger modelName och modelDeployment aktiveras AI-genererade bildbeskrivningar (förhandsversion), som kompetensen infogar direkt i segmentinnehållet före vektorisering. En lista över modeller för chattkomplettering som stöds och annan parameterinformation finns i Kunskapsparametrar.

• Azure OpenAI-inbäddningsfärdigheten genererar en vektor för varje segments innehåll.

Kompetensuppsättningen använder indexProjections för att mappa varje segment till ett separat sökdokument. Mer information finns i Definiera en indexprojektion.

Innan du skickar begäran ersätter du <subdomain> med din Azure OpenAI-underdomän, <Azure OpenAI api key> med inbäddningsresursnyckeln och <Foundry resource key> med nyckeln för foundry-resursen som är kopplad till kunskapsuppsättningen.

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

Fullständig parameterreferens, värden som stöds och valideringsregler för content understanding-färdigheten finns i Azure content understanding skill.

Konfigurera och köra indexeraren

Skapa och kör en indexerare som läser från datakällan, anropar kompetensuppsättningen och projicerar segment till indexet. Ställ in allowSkillsetToReadFileData på true så att färdigheten Innehållsförståelse tar emot filinnehållet, och ställ in parsingMode på default.

Du behöver inte outputFieldMappings i det här scenariot. Blocket indexProjections i kompetensuppsättningen mappar redan varje segment till målindexfälten.

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

När indexeraren körs använder content understanding-färdigheten semantisk segmentering (förhandsversion), genererar eventuellt AI-baserade bildbeskrivningar (förhandsversion) och skriver ett sökdokument per segment till indexet.

Kontrollera indexerarens status

Innan du frågar bekräftar du att indexeraren har körts klart:

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

Kontrollera att lastResult.status är success. Om den är transientFailure med itemsProcessed högre än 0är körningen delvis lyckad och du kan fortfarande köra frågor mot de ifyllda segmenten. Mer information finns i Övervaka indexerarens status.

Verifiera resultat

Fråga indexet för att kontrollera att segmenten innehåller det förväntade innehållet och att vektorsökningen fungerar som förväntat. Använd Sökutforskaren eller något verktyg som skickar HTTP-begäranden.

Följande begäran kör en hybridfråga (nyckelordssökning på chunk och en vektorfråga mot text_vector) för att bekräfta att både den segmenterade texten och inbäddningarna är ifyllda.

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

Ett lyckat svar ser ut ungefär så här (trimmat för korthet):

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

Svaret innehåller:

• chunk: Markdown-innehållet i varje segment. När du konfigurerar modelName och modelDeploymentvisas AI-genererade bildbeskrivningar (förhandsversion) infogade i Markdown.
• page_number_from och page_number_to: Sidintervallet som skapade segmentet.
• image_path: Sökvägen till bilden som extraherats med segmentet eller, när ett segment sträcker sig över flera bilder, en semikolonavgränsad lista över sökvägar. Den exakta formen beror på om en kunskapslagerfilprojektion har konfigurerats. Utan en filprojektion är sökvägen det korta formulär som visas i exemplet (figures/3). Med en filprojektion är sökvägen den relativa sökvägen till bilden i kunskapsarkivet. Information om hur du gör dessa avbildningar tillgängliga för klientappar finns i (Valfritt) Project bilder för hämtning.

(Valfritt) Projektbilder för hämtning

Värdena image_path som lagras i indexet är pekare i färdighetens berikningsträd, inte direkt hämtningsbara URL:er. Om du vill hämta bilder projicerar du normalized_images till Azure Blob Storage med hjälp av ett kunskapslager och skapar sedan en blob-URL för varje segment.

Det här steget är valfritt. Lägg bara till den om klientappen behöver visa eller ladda ned de extraherade bilderna.

Lägg till följande egenskap i nyttolasten för kompetensuppsättningen från föregående avsnitt. Begäran om kompetensprofil använder api-version=2026-08-01-preview.

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

När indexeraren har körts motsvarar varje blob i containern extracted-images ett normalized_images element. Blob-URL:en har formuläret https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, där <imagePath> matchar värdet som lagras i fältet image_path .

Det fullständiga schemat, inklusive ytterligare projektionstyper (tables och objects) och autentiseringsalternativ, finns i Knowledge store "projections" i Azure AI-sökning.

Rensa resurser

När du är klar tar du bort indexeraren, kompetensuppsättningen och indexet för att undvika avgifter för Content Understanding och Azure OpenAI. Källfilerna i Azure Blob Storage och själva Foundry-resursen finns kvar tills du tar bort dem.

Troubleshooting

Om indexeraren misslyckas eller returnerar oväntade resultat kontrollerar du följande vanliga orsaker.

Validering av kompetensuppsättning ger felkoden 400

Färdigheten returnerar ett 400 Skill validation failed fel när parameterkombinationer är i konflikt. Vanliga orsaker:

• modelName anges utan modelDeployment, eller vice versa. Båda måste anges samtidigt.
• method är semantic (förhandsversion) och overlapLength är större än 0. Ange overlapLength till 0 eller utelämna det.
• method och unit är inte ett par som stöds. Använd fixedSize med characters eller semantic med tokens.

Auktoriseringen misslyckas mot Foundry-resursen

Om färdigheten returnerar 401 eller 403 när du anropar Foundry-resursen kontrollerar du att:

• cognitiveServices-blocket i kompetensuppsättningen pekar på rätt Foundry-resurs.
• Den identitet som används av söktjänsten har den roll som krävs för Foundry-resursen. För konfigurationer med hanterad identitet, se Bifoga en fakturerbar resurs till en kompetensuppsättning i Azure AI-sökning.

text_sections är tom

Om indexerade dokument inte har några segment kontrollerar du att:

• Filformatet stöds. Listan finns i Filformat som stöds.
• Foundry-resursen finns i en region som stöds.
• Lösenordsskyddade PDF-filer låss upp innan indexering.

Bildbeskrivningar (förhandsversion) saknas

Om segmenten inte innehåller infogade bildbeskrivningar, kontrollera att:

• Både modelName och modelDeployment är angivna i kompetensuppsättningen.
• Chat completion-modellen i modelName är distribuerad i samma Foundry-resurs som kompetensuppsättningen refererar till.
• Driftsättningen har tillräcklig TPM- eller RPM-kvot för din dokumentvolym.

Indexeraren överskrider tidsgränsen för stora dokument

Content Understanding framtvingar en tidsgräns för bearbetning per dokument. Om stora PDF-filer misslyckas:

• Dela upp källdokumentet i mindre filer innan du indexerar.
• Minska batchSize till 1 så att varje dokument bearbetas separat.

Fullständiga datagränser för Azure Content Understanding-kunskaper finns i Datagränser.

Relaterat innehåll

• Azure Content Understanding-färdighet
• Azure OpenAI-inbäddningsfärdighet
• Multimodal-sökning i Azure AI-sökning
• Definiera en indexprojektion för överordnad-underordnad indexering
• Dela upp stora dokument för RAG och vektorsökning