Inhalte mit dem Azure-Skill für Content Understanding in Blöcke aufteilen und vektorisieren

In diesem Artikel erfahren Sie, wie Sie die Azure Fähigkeit zum Inhaltsverständnis verwenden können:

Die Azure Fähigkeit zum Verständnis von Inhalten gibt einen oder mehrere Blöcke pro Dokument zurück. Jeder Block enthält Markdown-formatierten Inhalt, Positionsmetadaten (Seitenzahlen und umgebende Polygone) und optionale Verweise auf extrahierte Bilder. Wenn Sie chunkingProperties.method auf semantic festlegen, folgen Blöcke den Absatz- und Überschriftengrenzen anstelle fester Zeichenbereiche. Wenn Sie modelName und modelDeployment festlegen, ruft der Skill eine Azure OpenAI-Bereitstellung für Chatvervollständigung auf, um Beschreibungen eingebetteter Bilder zu generieren. Die Fähigkeit führt dann diese Beschreibungen in den Abschnittsinhalt zusammen.

In diesem Artikel werden zur Veranschaulichung die Beispiel-PDFs für Gesundheitspläne verwendet. Sie können dieselbe Pipeline für jede unterstützte Datenquelle ausführen, die Dateien in einem Format verfügbar macht , das das Inhaltsverständnis unterstützt.

Voraussetzungen

• Ein Azure KI-Suche-Dienst in einer beliebigen unterstützten Region. Der Suchdienst selbst ist für dieses Szenario nicht regionseinschränkt.

• Eine Microsoft Foundry-Ressource in einer region, die von der Azure Fähigkeit zum Verständnis von Inhalten unterstützt wird. Bildbeschreibung und Segmentierung werden in der Region der Foundry-Ressource verarbeitet.

• Eine Microsoft Foundry-Ressource, die dem Skillset zugeordnet ist, zur Abrechnung. Der Azure Content Understanding-Skill wird gemäß der Preise für Azure Content Understanding abgerechnet.

• (Optional) Eine Azure OpenAI-Bereitstellung eines Chatabschlussmodells (z. B. gpt-4.1) in derselben Foundry-Ressource, die zum Generieren von Bildbeschreibungen verwendet wird. Nur erforderlich, wenn Sie die KI-basierten Bildbeschreibungen verwenden möchten.

• Eine Azure OpenAI-Bereitstellung eines Einbettungsmodells (z. B. text-embedding-3-small), das von der Azure OpenAI Embedding Skill zum Vektorisieren von Blöcken verwendet wird.

• Ein Azure Blob Storage-Container mit den Dateien, die Sie indizieren möchten. In diesem Artikel wird eine Blob-Datenquelle mit der allowSkillsetToReadFileData Indexer-Einstellung verwendet (mit der Dateiinhalte an den Content-Understanding-Skill übergeben werden).

Overview

Der Artikel baut eine One-to-many-Indexierungspipeline auf. Jedes Quelldokument erzeugt mehrere Suchdokumente (eins pro Block):

1. Der Indexer liest jede Datei aus Azure Blob Storage und übergibt den binären Inhalt über /document/file_data an das Skillset.

2. Die Azure Content Understanding Skill verwendet die semantische Segmentierung (Vorschau), um text_sections zu erzeugen. Wenn modelName und modelDeployment festgelegt sind, werden außerdem KI-generierte Beschreibungen (Vorschau) eingebetteter Bilder erzeugt und direkt in das Markdown jedes Abschnitts eingefügt.

3. Die Azure OpenAI Embedding Skill wird einmal pro Block ausgeführt und erzeugt einen Vektor für den Blockinhalt.

4. Eine Indexprojektion schreibt ein Suchdokument pro Chunk in den Zielindex und ordnet Inhalt, Seitenmetadaten, Bildverweise und den Vektor Feldern zu.

5. (Optional) Ein Wissensspeicher schreibt normalized_images in Azure Blob Storage, damit Client-Apps die extrahierten Bilder über die URL abrufen können.

Aufbereiten von Datendateien

Die Azure Fähigkeit zum Verständnis von Inhalten verarbeitet den binären Inhalt jedes Dokuments, sodass Quelldateien in einem Format vorliegen müssen, das von der Fähigkeit unterstützt wird. Die aktuelle Liste finden Sie unter den Grenzwerten für den Inhaltsverständnisdienst. Zu den gängigen unterstützten Formaten gehören PDF, DOCX, XLSX, PPTX und viele Bildformate.

Laden Sie Ihre Dateien in die unterstützte Datenquelle hoch. Sie können das Azure Portal, REST-APIs oder eine Azure SDK verwenden, um die Datenquelle zu create the data source.

Die folgende minimale Anforderung erstellt die datenquelle, die in dieser exemplarischen Vorgehensweise verwendet wird.

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

Erstellen eines Indexes für die 1:n-Indizierung

Jedes Suchdokument entspricht einem Teil, der von der Fähigkeit zum Inhaltsverständnis erzeugt wird. Der Index benötigt:

• Ein Schlüsselfeld (chunk_id).
• Ein übergeordnetes Feld, das angibt, aus welchem Quelldokument der Block stammt (parent_id).
• Felder, die den Abschnittsinhalt, Seitenmetadaten und Bildverweise speichern.
• Ein Vektorfeld für das Einbetten des Abschnitts.

Die folgende Indexdefinition entspricht dem Skillset, das Sie im nächsten Abschnitt erstellen.

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

Definieren eines Skillsets für semantische Segmentierung (Vorschau) und Vektorisierung

Sobald der Zielindex eingerichtet wurde, definieren Sie das Skillset, das die Segmente, Vektoren und Projektionszuordnungen erzeugt, die in ihn eingespeist werden.

Das Skillset verfügt über zwei Fähigkeiten:

• Die Azure-Skill für Inhaltsverständnis unterteilt jedes Dokument in Abschnitte. Das Festlegen von chunkingProperties.method auf semantic bewirkt, dass die Funktion Absatz- und Überschriftengrenzen berücksichtigt. Das Festlegen von modelName und modelDeployment aktiviert KI-generierte Bildbeschreibungen (Vorschau), die der Skill vor der Vektorisierung direkt in den Chunkinhalt einfügt. Eine Liste der unterstützten Chatabschlussmodelle und weitere Parameterdetails finden Sie unter Skill-Parameter.

• Die Azure OpenAI Embedding Skill generiert einen Vektor für den Inhalt der einzelnen Blöcke.

Das Skillset verwendet indexProjections , um jeden Abschnitt einem separaten Suchdokument zuzuordnen. Weitere Informationen finden Sie unter Definieren einer Indexprojektion.

Ersetzen Sie vor dem Senden der Anforderung <subdomain> durch Ihre Azure OpenAI-Unterdomäne, <Azure OpenAI api key> durch den Einbettungsressourcenschlüssel und <Foundry resource key> durch den Schlüssel für die dem Skillset zugeordnete Foundry-Ressource.

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

Die vollständige Parameterreferenz, unterstützte Werte und Validierungsregeln für die Fähigkeit zum Inhaltsverständnis finden Sie unter Azure Content Understanding Skill.

Konfigurieren und Ausführen des Indexers

Erstellen und führen Sie einen Indexer aus, der aus Ihrer Datenquelle liest, das Skillset aufruft und Blöcke in den Index projiziert. Legen Sie allowSkillsetToReadFileData auf true fest, damit die Content Understanding-Funktion den Dateiinhalt erhält, und legen Sie parsingMode auf default fest.

In diesem Szenario benötigen Sie outputFieldMappings nicht. Der indexProjections-Block im Skillset ordnet bereits jeden Chunk den Zielindexfeldern zu.

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

Wenn der Indexer ausgeführt wird, verwendet die Inhaltsverständnisfähigkeit semantische Blöcke (Vorschau), generiert optional KI-basierte Bildbeschreibungen (Vorschau) und schreibt ein Suchdokument pro Block in den Index.

Indexerstatus überprüfen

Bevor Sie eine Abfrage ausführen, vergewissern Sie sich, dass die Ausführung des Indexers abgeschlossen ist:

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

Vergewissern Sie sich, dass lastResult.statussuccess ist. Wenn es sich um transientFailure mit itemsProcessed höher als 0 handelt, ist der Durchlauf teilweise erfolgreich, und Sie können die befüllten Chunks weiterhin abfragen. Weitere Informationen finden Sie unter Überwachen des Indexerstatus.

Überprüfen der Ergebnisse

Fragen Sie den Index ab, um zu überprüfen, ob die Blöcke den erwarteten Inhalt enthalten und dass die Vektorsuche wie erwartet funktioniert. Verwenden Sie den Such-Explorer oder ein beliebiges Tool, das HTTP-Anforderungen sendet.

Die folgende Anfrage führt eine Hybridabfrage aus (eine Stichwortsuche für chunk und eine Vektorabfrage für text_vector), um zu überprüfen, dass sowohl der segmentierte Text als auch die Einbettungsvektoren gefüllt sind.

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

Eine erfolgreiche Antwort sieht in etwa so aus (der Kürze halber gekürzt):

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

Die Antwort umfasst:

• chunk: Der Markdown-Inhalt der einzelnen Blöcke. Wenn Sie modelName und modelDeployment konfigurieren, werden KI-generierte Bildbeschreibungen (Vorschau) direkt im Markdown angezeigt.
• page_number_from und page_number_to: Der Seitenbereich, der das Segment erzeugt hat.
• image_path: Der Pfad zum Bild, das mit dem Block extrahiert wurde, oder, wenn ein Block mehrere Bilder umfasst, eine durch Semikolons getrennte Liste von Pfaden. Die genaue Form hängt davon ab, ob eine Wissensspeicherdateiprojektion konfiguriert ist. Ohne Dateiprojektion ist der Pfad das kurze Formular im Beispiel (figures/3). Bei einer Dateiprojektion ist der Pfad der relative Pfad des Bilds im Wissensspeicher. Informationen dazu, wie Sie diese Bilder für Client-Apps verfügbar machen, finden Sie unter (Optional) Projektbilder zum Abrufen.

(Optional) Projektbilder für den Abruf

Die im Index gespeicherten image_path-Werte sind Zeiger auf den Anreicherungsbaum der Fertigkeit und keine direkt abrufbaren URLs. Um Bilder abzurufen, projizieren Sie normalized_images mithilfe eines Wissensspeichers in Azure Blob Storage, und leiten Sie dann neben jedem Chunk eine Blob-URL ab.

Dieser Schritt ist optional. Fügen Sie sie nur hinzu, wenn Ihre Client-App die extrahierten Bilder anzeigen oder herunterladen muss.

Fügen Sie der Nutzlast des Skillsets aus dem vorherigen Abschnitt die folgende Eigenschaft hinzu. Die Skillset-Anforderung verwendet api-version=2026-08-01-preview.

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

Nachdem der Indexer ausgeführt wurde, entspricht jeder Blob im extracted-images Container einem normalized_images Element. Die Blob-URL hat die Form https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, wobei <imagePath> dem im Feld image_path gespeicherten Wert entspricht.

Das vollständige Schema, einschließlich zusätzlicher Projektionstypen (tables und objects) und Authentifizierungsoptionen finden Sie unter Knowledge store "projections" in Azure KI-Suche.

Bereinigen von Ressourcen

Wenn Sie fertig sind, löschen Sie den Indexer, das Skillset und den Index, damit keine Gebühren für Content Understanding und Azure OpenAI mehr anfallen. Quelldateien in Azure Blob Storage und die Foundry-Ressource selbst bleiben, bis Sie sie löschen.

Problembehandlung

Wenn der Indexer fehlschlägt oder unerwartete Ergebnisse zurückgibt, überprüfen Sie die folgenden allgemeinen Ursachen.

Skillset-Validierung schlägt mit 400 fehl

Die Fähigkeit gibt einen 400 Skill validation failed Fehler zurück, wenn Parameterkombinationen in Konflikt geraten. Häufige Ursachen:

• modelName wird ohne modelDeployment festgelegt, oder umgekehrt. Beide müssen zusammen festgelegt werden.
• method ist semantic (Vorschau) und overlapLength größer als 0. Setzen Sie overlapLength auf 0 oder lassen Sie es weg.
• method und unit sind kein unterstütztes Paar. Verwenden Sie fixedSize mit characters oder semantic mit tokens.

Die Autorisierung schlägt gegen die Foundry-Ressource fehl.

Wenn die Fähigkeit beim Aufrufen der Foundry-Ressource 401 oder 403 zurückgibt, überprüfen Sie Folgendes:

• Der cognitiveServices Block im Skillset verweist auf die richtige Foundry-Ressource.
• Die vom Suchdienst verwendete Identität hat die erforderliche Rolle auf der Foundry-Ressource. Informationen zu Einrichtungen mit verwalteten Identitäten finden Sie unter Anfügen einer abrechenbaren Ressource an ein Skillset in Azure KI-Suche.

text_sections ist leer

Wenn indizierte Dokumente keine Blöcke aufweisen, stellen Sie folgendes sicher:

• Das Dateiformat wird unterstützt. Die Liste finden Sie unter "Unterstützte Dateiformate".
• Die Foundry-Ressource befindet sich in einer unterstützten Region.
• Kennwortgeschützte PDF-Dateien werden vor der Indizierung entsperrt.

Bildbeschreibungen (Vorschau) fehlen

Wenn Blöcke keine Inlinebildbeschreibungen enthalten, stellen Sie folgendes sicher:

• Sowohl modelName als auch modelDeployment sind im Skillset festgelegt.
• Das Modell zur Chatvervollständigung in modelName wird in derselben Foundry-Ressource bereitgestellt, auf die im Skillset verwiesen wird.
• Die Bereitstellung verfügt über ein ausreichendes TPM- oder RPM-Kontingent für Ihr Dokumentaufkommen.

Zeitüberschreitung des Indexers bei großen Dokumenten

Content Understanding legt ein Verarbeitungstimeout pro Dokument fest. Wenn große PDF-Dateien fehlschlagen:

• Teilen Sie das Quelldokument vor der Indizierung in kleinere Dateien auf.
• Reduzieren Sie batchSize auf 1, damit jedes Dokument unabhängig verarbeitet wird.

Die vollständigen Datenbeschränkungen der Azure Fähigkeiten für das Inhaltsverständnis finden Sie unter Data limits.

Verwandte Inhalte

• Azure Fähigkeit zum Verständnis von Inhalten
• Azure OpenAI Embedding Skill
• Multimodale Suche in Azure KI-Suche
• Definieren einer Indexprojektion für die Parent-Child-Indizierung
• Große Dokumente für RAG und Vektorsuche segmentieren