Rozdělení obsahu na části a jeho vektorizace pomocí dovednosti Azure Content Understanding

V tomto článku se naučíte používat dovednosti Azure Content Understanding k:

Dovednost Azure Content Understanding vrátí jeden nebo více bloků dat na jeden dokument. Každý blok dat obsahuje obsah ve formátu Markdown, metadata umístění (čísla stránek a ohraničující mnohoúhelníky) a volitelné odkazy na extrahované obrázky. Když nastavíte chunkingProperties.method na semantic, segmenty se řídí hranicemi odstavců a nadpisů namísto úseků o pevně daném počtu znaků. Když nastavíte modelName a modelDeployment, dovednost použije nasazení služby Azure OpenAI pro dokončování chatů k vygenerování popisů vložených obrázků. Dovednost pak tyto popisy sloučí do obsahu bloku dat.

Tento článek pro ilustraci používá ukázkové soubory PDF zdravotního plánu. Stejný kanál můžete spustit na jakémkoli podporovaném zdroji dat , který zveřejňuje soubory ve formátu, který služba Content Understanding podporuje.

Předpoklady

• Služba Azure AI Vyhledávač v libovolném podporovaném regionu. Samotná vyhledávací služba není pro tento scénář omezena oblastí.

• Prostředek Microsoft Foundry v oblasti podporované dovedností Azure Content Understanding. Popis obrázků a rozdělování na bloky se zpracovávají v regionu prostředku Foundry.

• Prostředek Microsoft Foundry připojený k sadě dovedností pro fakturaci. Dovednost Azure Content Understanding je zpoplatněna podle ceny služby Azure Content Understanding.

• (Volitelné) Nasazení modelu dokončování chatu Azure OpenAI (například gpt-4.1) ve stejném prostředku Foundry, který se používá k vygenerování popisů obrázků. Vyžaduje se pouze v případě, že chcete popisy obrázků založené na umělé inteligenci.

• Nasazení Azure OpenAI modelu vkládání (například text-embedding-3-small) používaného dovedností Azure Dovednosti vkládání OpenAI k vektorizaci bloků dat.

• Kontejner Azure Blob Storage se soubory, které chcete indexovat. Tento článek používá zdroj dat Blob s nastavením indexeru allowSkillsetToReadFileData (slouží k předání obsahu souboru do dovednosti Content Understanding).

Overview

Článek vytváří indexační kanál typu jedna ku mnoha. Každý zdrojový dokument vytvoří více vyhledávacích dokumentů (jeden na blok):

1. Indexer přečte každý soubor z Azure Blob Storage a předá binární obsah sadě dovedností prostřednictvím /document/file_data.

2. Dovednost Azure Content Understanding využívá sémantické členění (verze Preview) k vytváření text_sections. Když modelName a modelDeployment jsou nastavené, vytvoří také popisy vygenerované umělou inteligencí (Preview) vložených obrázků a vloží je do Markdownu jednotlivých bloků dat.

3. Dovednost Azure OpenAI Embedding se spustí jednou za blok dat a vytvoří vektor pro obsah bloku dat.

4. Projekce indexu zapíše do cílového indexu jeden vyhledávací dokument pro každý blok, přičemž obsah, metadata stránky, odkazy na obrázky a vektor mapuje na pole.

5. (Volitelné) úložiště znalostí promítá normalized_images do Azure Blob Storage, aby klientské aplikace mohly načítat extrahované obrázky pomocí adresy URL.

Příprava datových souborů

Dovednosti Azure Content Understanding zpracovávají binární obsah každého dokumentu, takže zdrojové soubory musí být ve formátu, který dovednost podporuje. Aktuální seznam najdete v omezeních služby Content Understanding. Mezi běžné podporované formáty patří PDF, DOCX, XLSX, PPTX a mnoho formátů obrázků.

Nahrajte soubory do podporovaného zdroje dat. Pomocí portálu Azure, rozhraní REST API nebo Azure SDK můžete vytvořit zdroj dat.

Následující minimální požadavek vytvoří zdroj dat použitý v tomto názorném postupu.

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

Vytvořit index pro indexaci typu jeden-ku-mnohým

Každý hledaný dokument odpovídá jednomu bloku vytvořenému dovedností Content Understanding. Index potřebuje:

• Pole pro klíč (chunk_id).
• Nadřazené pole, které identifikuje zdrojový dokument, ze kterého pochází blok dat (parent_id).
• Pole, která ukládají obsah bloku dat, metadata stránek a odkazy na obrázky.
• Vektorové pole pro vložení bloku dat.

Následující definice indexu odpovídá sadě dovedností, kterou vytvoříte v další části.

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

Definovat sadu dovedností pro sémantické dělení na bloky (Preview) a vektorizaci

Jakmile je cílový index vytvořen, definujte sadu dovedností, která vytváří segmenty, vektory a mapování projekcí, které jej naplňují.

Soubor dovedností obsahuje dvě dovednosti:

• Dovednost Azure Content Understanding rozdělí každý dokument na bloky. Nastavení chunkingProperties.method na semantic způsobí, že dovednost bude respektovat hranice odstavců a nadpisů. Nastavení modelName a modelDeployment umožňuje popisy obrázků generované umělou inteligencí (Preview), které dovednost před vektorizací vloží přímo do obsahu chunku. Seznam podporovaných modelů dokončování chatu a dalších podrobností o parametrech najdete v tématu Parametry dovedností.

• Dovednost Azure OpenAI Embedding generuje vektor pro obsah jednotlivých bloků dat.

Sada dovedností používá indexProjections k mapování jednotlivých bloků dat na samostatný vyhledávací dokument. Další informace naleznete v tématu Definování projekce indexu.

Před odesláním požadavku nahraďte <subdomain> subdoménou Azure OpenAI, <Azure OpenAI api key> klíčem k prostředku pro embeddingy a <Foundry resource key> klíčem k prostředku Foundry připojenému k sadě dovedností.

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

Úplnou referenci parametrů, podporované hodnoty a pravidla ověřování pro dovednost Content Understanding najdete v tématu dovednost Azure Content Understanding.

Konfigurace a spuštění indexeru

Vytvořte a spusťte indexer, který čte z vašeho zdroje dat, volá sadu dovedností a promítá bloky do indexu. Nastavte allowSkillsetToReadFileData na true, aby dovednost Content Understanding přijímala obsah souboru, a nastavte parsingMode na default.

V tomto scénáři nepotřebujete outputFieldMappings . Blok indexProjections v sadě dovedností už mapuje jednotlivé bloky dat na pole cílového indexu.

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

Při spuštění indexeru používá dovednost Content Understanding sémantické bloky dat (Preview), volitelně vygeneruje popisy obrázků založené na umělé inteligenci (Preview) a zapíše jeden hledaný dokument na jeden blok dat do indexu.

Kontrola stavu indexeru

Před dotazem ověřte, že se spuštění indexeru dokončilo:

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

Ověřte, že lastResult.status je success. Pokud je to transientFailure s itemsProcessed vyšším než 0, je běh částečně úspěšný a stále můžete zadávat dotazy na naplněné bloky dat. Další informace naleznete v tématu Monitorování stavu indexeru.

Ověření výsledků

Dotazem na index ověřte, že bloky dat obsahují očekávaný obsah a že vektorové vyhledávání funguje podle očekávání. Použijte Průzkumníka služby Search nebo jakýkoli nástroj, který odesílá požadavky HTTP.

Následující požadavek spustí hybridní dotaz (vyhledávání podle klíčových slov nad chunk a vektorový dotaz nad text_vector), aby se potvrdilo, že text rozdělený na bloky i embeddingy jsou naplněné.

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

Úspěšná odpověď vypadá podobně jako následující (zkrácená kvůli stručnosti):

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

Odpověď zahrnuje:

• chunk: Obsah Markdownu jednotlivých bloků dat. Když nakonfigurujete modelName a modelDeployment, popisy obrázků vygenerované AI (ve verzi Preview) se zobrazí přímo v textu Markdownu.
• page_number_from a page_number_to: Rozsah stránek, z něhož byl blok vytvořen.
• image_path: Cesta k obrázku extrahovanému s blokem dat nebo, pokud blok dat přesahuje více obrázků, seznam cest oddělený středníkem. Přesný tvar závisí na tom, jestli je nakonfigurovaná projekce souboru úložiště znalostí. Bez projekce souborů je cesta v krátké formě zobrazené v příkladu (figures/3). Při projekci souboru je cesta relativní cestou obrázku v úložišti znalostí. Chcete-li tyto obrazy zpřístupnit klientským aplikacím, přečtěte si část (Volitelné) Obrazy projektu pro získání.

(Volitelné) Obrázky projektu pro vyhledávání

Hodnoty image_path uložené v indexu jsou ukazatele do stromu obohacení dovednosti, nikoli přímo získatelné adresy URL. Chcete-li získat obrázky, promítněte normalized_images do Azure Blob Storage pomocí úložiště znalostí a potom pro každý blok dat vytvořte adresu URL objektu blob.

Tento krok je volitelný. Přidejte ho jenom v případě, že klientská aplikace potřebuje zobrazit nebo stáhnout extrahované obrázky.

Do datové části sady dovedností z předchozí části přidejte následující vlastnost. Žádost o sadu dovedností používá api-version=2026-08-01-preview.

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

Po spuštění indexeru každý objekt blob v kontejneru extracted-images odpovídá jednomu normalized_images prvku. Adresa URL objektu blob má formulář https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, kde <imagePath> odpovídá hodnotě image_path uložené v poli.

Úplné schéma včetně dalších typů projekce (tables a objects) a možností ověřování identity najdete v článku Knowledge store „projekce“ v Azure AI Vyhledávač.

Vyčistěte zdroje

Až budete hotovi, odstraňte indexer, sadu dovedností a index, aby se vám dál neúčtovaly poplatky za Content Understanding a Azure OpenAI. Zdrojové soubory v Azure Blob Storage a samotný prostředek Foundry zůstanou, dokud je neodstraníte.

Řešení problémů

Pokud indexer selže nebo vrátí neočekávané výsledky, zkontrolujte následující běžné příčiny.

Ověření sady dovedností selže s chybou 400

Dovednost vrátí chybu 400 Skill validation failed, když jsou kombinace parametrů v konfliktu. Běžné příčiny:

• modelName je nastavena bez modelDeploymentnebo naopak. Oba musí být nastavené společně.
• method je semantic (Preview) a overlapLength je větší než 0. Nastavte overlapLength na 0, nebo ho vynechejte.
• method a unit nejsou podporovaným párem. Použít fixedSize s characters nebo semantic s tokens.

Autorizace vůči prostředku Foundry selže

Pokud dovednost při volání zdroje Foundry vrátí hodnotu 401 nebo 403, ověřte, že:

• Blok cognitiveServices v sadě dovedností odkazuje na správný zdroj Foundry.
• Identita používaná vyhledávací službou má u prostředku Foundry požadovanou roli. Konfigurace spravované identity najdete v článku Připojte zpoplatněný prostředek k sadě dovedností v Azure AI Vyhledávač.

text_sections je prázdný.

Pokud indexované dokumenty neobsahují žádné bloky dat, ověřte, že:

• Podporuje se formát souboru. Seznam naleznete v části Podporované formáty souborů.
• Prostředek Foundry je v podporované oblasti.
• Před indexováním se soubory PDF chráněné heslem odemknou.

Chybí popisy obrázků (Preview)

Pokud bloky dat neobsahují vložené popisy obrázků, ověřte, že:

• Obě modelName a modelDeployment jsou nastavené v sadě dovedností.
• Model pro dokončování chatu v modelName je nasazený ve stejném prostředku služby Foundry, na který odkazuje sada dovedností.
• Nasazení má dostatečnou kvótu TPM nebo RPM pro váš objem dokumentů.

U velkých dokumentů vyprší časový limit indexeru.

Funkce Content Understanding vynucuje časový limit zpracování jednotlivých dokumentů. Pokud velké soubory PDF selžou:

• Před indexováním rozdělte zdrojový dokument na menší soubory.
• Snižte batchSize na 1, aby byl každý dokument zpracováván samostatně.

Úplné informace o datových limitech dovednosti Azure Content Understanding najdete v tématu Data limits.

Související obsah

• Dovednost pro porozumění obsahu Azure
• Dovednosti vkládání v Azure OpenAI
• Vícemodální vyhledávání v Azure AI Vyhledávač
• Definujte projekci indexu pro indexování nadřazený-podřízený
• Rozdělení velkých dokumentů na části pro RAG a vektorové vyhledávání