Fragmentowanie i wektoryzowanie zawartości za pomocą umiejętności Azure Content Understanding

Z tego artykułu dowiesz się, jak używać umiejętności Azure Content Understanding:

Funkcja Azure Content Understanding zwraca dla każdego dokumentu jeden lub więcej fragmentów. Każdy fragment zawiera zawartość w formacie Markdown, metadane lokalizacji (numery stron i wielokąty ograniczenia) oraz opcjonalne odwołania do wyodrębnionych obrazów. Gdy ustawisz chunkingProperties.method na semantic, fragmenty tekstu są wyznaczane zgodnie z granicami akapitów i nagłówków zamiast według zakresów o stałej liczbie znaków. Po ustawieniu modelName i modelDeployment umiejętność wywołuje wdrożenie funkcji uzupełniania czatu w usłudze Azure OpenAI w celu wygenerowania opisów osadzonych obrazów. Następnie umiejętność scala te opisy z zawartością fragmentu.

W tym artykule użyto plików PDF przykładowego planu kondycji na potrzeby ilustracji. Możesz uruchomić ten sam potok względem dowolnego obsługiwanego źródła danych, które udostępnia pliki w formacie obsługiwanym przez Content Understanding.

Wymagania wstępne

• Usługa Wyszukiwanie AI platformy Azure w dowolnym obsługiwanym regionie. Sama usługa wyszukiwania nie jest ograniczona w regionie w tym scenariuszu.

• Zasób Microsoft Foundry w regionie obsługiwanym przez umiejętność Azure Content Understanding. Opis obrazu i dzielenie na fragmenty są przetwarzane w regionie zasobu usługi Foundry.

• Zasób Microsoft Foundry dołączony do zestawu umiejętności na potrzeby rozliczeń. Umiejętność Azure Content Understanding jest rozliczana według cennika usługi Azure Content Understanding.

• (Opcjonalnie) Wdrożenie w usłudze Azure OpenAI modelu do uzupełniania czatu (na przykład gpt-4.1) w tym samym zasobie Foundry, używanego do generowania opisów obrazów. Wymagane tylko wtedy, gdy potrzebujesz opisów obrazów opartych na sztucznej inteligencji.

• Wdrożenie modelu osadzeń w usłudze Azure OpenAI (takiego jak text-embedding-3-small), używane przez umiejętność Azure OpenAI Embedding do wektoryzacji fragmentów.

• Kontener Azure Blob Storage z plikami, które chcesz indeksować. W tym artykule używa się źródła danych typu blob z ustawieniem indeksatora allowSkillsetToReadFileData (służącym do przekazywania zawartości pliku do umiejętności Content Understanding).

Overview

Artykuł przedstawia potok indeksowania typu jeden-do-wielu. Każdy dokument źródłowy tworzy wiele dokumentów wyszukiwania (jeden na fragment):

1. Indeksator odczytuje każdy plik z usługi Azure Blob Storage i przekazuje zawartość binarną do zestawu umiejętności za pośrednictwem /document/file_data.

2. Funkcja Azure Content Understanding używa podziału semantycznego (wersja zapoznawcza), aby utworzyć text_sections. Gdy ustawiono modelName i modelDeployment, tworzy również generowane przez SI opisy osadzonych obrazów (wersja zapoznawcza) i wstawia je bezpośrednio do kodu Markdown każdego fragmentu.

3. Umiejętność osadzania Azure OpenAI Embedding skill jest uruchamiana raz dla każdego fragmentu i tworzy wektor dla zawartości fragmentu.

4. Projekcja indeksu zapisuje jeden dokument wyszukiwania dla każdego fragmentu w indeksie docelowym, mapuje zawartość, metadane strony, odwołania do obrazów i wektor do pól.

5. (Opcjonalnie) magazyn wiedzy zapisuje normalized_images w usłudze Azure Blob Storage, aby aplikacje klienckie mogły pobierać wyodrębnione obrazy za pomocą adresu URL.

Przygotowywanie plików danych

Umiejętność Azure Content Understanding przetwarza zawartość binarną każdego dokumentu, dlatego pliki źródłowe muszą być w formacie, który obsługuje umiejętność. Aby uzyskać bieżącą listę, zobacz Limity usługi Content Understanding. Typowe obsługiwane formaty to PDF, DOCX, XLSX, PPTX i wiele formatów obrazów.

Przekaż pliki do obsługiwanego źródła danych. Możesz użyć portalu Azure, interfejsów API REST lub Azure SDK, aby utworzyć źródło danych.

Poniższe minimalne żądanie tworzy źródło danych używane w tym przewodniku.

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

Utwórz indeks dla indeksowania jeden do wielu

Każdy dokument wyszukiwania odpowiada jednemu fragmentowi utworzonemu przez umiejętności Content Understanding. Indeks wymaga:

• Pole klucza (chunk_id).
• Pole nadrzędne, które identyfikuje dokument źródłowy, z którego pochodzi fragment (parent_id).
• Pola przechowujące zawartość fragmentu, metadane strony i odwołania do obrazów.
• Pole wektorowe osadzania fragmentu.

Poniższa definicja indeksu jest zgodna z zestawem umiejętności utworzonym w następnej sekcji.

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

Definiowanie zestawu umiejętności do fragmentowania semantycznego (wersja zapoznawcza) i wektoryzacji

Po utworzeniu indeksu docelowego zdefiniuj zestaw umiejętności, który generuje fragmenty, wektory i mapowania projekcji zasilające ten indeks.

Zestaw umiejętności obejmuje dwie umiejętności:

• Umiejętność Azure Content Understanding fragmentuje każdy dokument. Ustawienie chunkingProperties.method na semantic powoduje, że umiejętność uwzględnia granice akapitów i nagłówków. Ustawienie modelName i modelDeployment włącza opisy obrazów generowane przez SI (wersja zapoznawcza), które umiejętność wstawia bezpośrednio do treści fragmentu przed wektoryzacją. Aby uzyskać listę obsługiwanych modeli uzupełniania czatu i innych szczegółów parametrów, zobacz Parametry umiejętności.

• Umiejętność osadzania Azure OpenAI generuje wektor dla zawartości każdego fragmentu.

Zestaw umiejętności używa indexProjections, aby przypisać każdy fragment do oddzielnego dokumentu wyszukiwania. Aby uzyskać więcej informacji, zobacz Definiowanie projekcji indeksu.

Przed wysłaniem żądania zastąp <subdomain> subdomeną usługi Azure OpenAI, <Azure OpenAI api key> kluczem zasobu osadzania, a <Foundry resource key> kluczem zasobu Foundry dołączonego do zestawu umiejętności.

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

Pełny opis parametrów, obsługiwane wartości i reguły walidacji dotyczące umiejętności Content Understanding można znaleźć w artykule Azure Content Understanding skill.

Konfigurowanie i uruchamianie indeksatora

Utwórz i uruchom indeksator, który odczytuje dane ze źródła danych, wywołuje zestaw umiejętności i mapuje fragmenty do indeksu. Ustaw allowSkillsetToReadFileData na true, aby umiejętność Content Understanding otrzymywała zawartość pliku, i ustaw parsingMode na default.

Nie potrzebujesz outputFieldMappings w tym scenariuszu. Blok indexProjections w zestawie umiejętności mapuje już każdy fragment do pól indeksu docelowego.

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

Gdy indeksator jest uruchamiany, umiejętność Content Understanding używa semantycznego dzielenia na fragmenty (wersja zapoznawcza), opcjonalnie generuje opisy obrazów oparte na sztucznej inteligencji (wersja zapoznawcza) i zapisuje w indeksie po jednym dokumencie wyszukiwania dla każdego fragmentu.

Sprawdzanie stanu indeksatora

Przed wykonaniem zapytania upewnij się, że uruchomienie indeksatora zostało zakończone:

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

Sprawdź, czy lastResult.status jest to success. Jeśli jest to transientFailure i itemsProcessed jest wyższe niż 0, uruchomienie kończy się częściowym powodzeniem i nadal możesz wysyłać zapytania do uzupełnionych fragmentów. Aby uzyskać więcej informacji, zobacz Monitorowanie stanu indeksatora.

Weryfikowanie wyników

Wykonaj zapytanie względem indeksu, aby sprawdzić, czy fragmenty zawierają oczekiwaną zawartość, a wyszukiwanie wektorów działa zgodnie z oczekiwaniami. Użyj Eksploratora wyszukiwania lub dowolnego narzędzia wysyłającego żądania HTTP.

Poniższe żądanie wykonuje zapytanie hybrydowe (wyszukiwanie słów kluczowych w chunk oraz zapytanie wektorowe względem text_vector), aby potwierdzić, że zarówno tekst podzielony na fragmenty, jak i osadzenia wektorowe zostały wypełnione.

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

Pomyślna odpowiedź wygląda podobnie jak poniżej (skrócona dla zwięzłości):

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

Odpowiedź obejmuje:

• chunk: zawartość języka Markdown każdego fragmentu. Podczas konfigurowania modelName i modelDeployment opisy obrazów generowane przez sztuczną inteligencję (wersja zapoznawcza) są wyświetlane bezpośrednio w treści Markdown.
• page_number_from i page_number_to: zakres stron, który wygenerował fragment.
• image_path: Ścieżka do obrazu wyodrębnionego wraz z fragmentem lub, gdy fragment obejmuje wiele obrazów, lista ścieżek rozdzielonych średnikami. Dokładny kształt zależy od tego, czy jest skonfigurowana projekcja plików magazynu wiedzy. Bez projekcji pliku ścieżka jest krótką postacią pokazaną w przykładzie (figures/3). W przypadku projekcji plików ścieżka to ścieżka względna obrazu w magazynie wiedzy. Aby udostępnić te obrazy aplikacjom klienckim, zobacz (Opcjonalnie) Obrazy projektu do pobrania.

(Opcjonalnie) Obrazy projektu do pobrania

Wartości image_path przechowywane w indeksie są wskaźnikami do drzewa wzbogacania skilla, a nie adresami URL, które można bezpośrednio pobrać. Aby pobrać obrazy, wyeksportuj normalized_images do usługi Azure Blob Storage za pomocą magazynu wiedzy, a następnie wyprowadź adres URL obiektu blob dla każdego fragmentu.

Ten krok jest opcjonalny. Dodaj go tylko wtedy, gdy aplikacja kliencka musi wyświetlać lub pobierać wyodrębnione obrazy.

Dodaj następującą właściwość do treści zestawu umiejętności z poprzedniej sekcji. Żądanie zestawu umiejętności używa elementu 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 uruchomieniu indeksatora każdy obiekt blob w kontenerze extracted-images odpowiada jednemu normalized_images elementowi. Adres URL obiektu blob ma postać https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, gdzie <imagePath> odpowiada wartości przechowywanej w polu image_path.

Pełny schemat, w tym dodatkowe typy projekcji (tables i objects) oraz opcje uwierzytelniania, można znaleźć w artykule „Projekcje” w magazynie wiedzy w usłudze Wyszukiwanie AI platformy Azure.

Uprzątnij zasoby

Po zakończeniu usuń indeksator, zestaw umiejętności i indeks, aby uniknąć dalszego naliczania opłat za usługę Content Understanding i usługę Azure OpenAI. Pliki źródłowe w Azure Blob Storage i sam zasób Foundry pozostają do momentu ich usunięcia.

Troubleshooting

Jeśli indeksator ulegnie awarii lub zwróci nieoczekiwane wyniki, sprawdź następujące typowe przyczyny.

Walidacja zestawu umiejętności kończy się błędem 400

Funkcja zwraca 400 Skill validation failed błąd, gdy kombinacje parametrów są ze sobą sprzeczne. Typowe przyczyny:

• modelName jest ustawiony bez modelDeployment, lub odwrotnie. Oba muszą być ustawione razem.
• method jest semantic (wersja zapoznawcza) i overlapLength jest większa niż 0. Ustaw overlapLength na 0 lub pomiń je.
• method i unit nie są obsługiwaną parą. Użyj fixedSize z characters lub semantic z tokens.

Autoryzacja nie powodzi się w przypadku zasobu Foundry

Jeśli przy wywoływaniu zasobu Foundry zwracany jest kod 401 lub 403, sprawdź, czy:

• Blok cognitiveServices w zestawie umiejętności wskazuje właściwy zasób Foundry.
• Tożsamość używana przez usługę wyszukiwania ma wymaganą rolę w zasobie Foundry. W przypadku konfiguracji z tożsamością zarządzaną zobacz artykuł Dołączanie zasobu rozliczanego do zestawu umiejętności w usłudze Wyszukiwanie AI platformy Azure.

text_sections jest pusta

Jeśli indeksowane dokumenty nie mają fragmentów, sprawdź, czy:

• Format pliku jest obsługiwany. Aby uzyskać listę, zobacz Obsługiwane formaty plików.
• Zasób Foundry znajduje się w obsługiwanym regionie.
• Chronione hasłem pliki PDF są odblokowywane przed indeksowaniem.

Brak opisów obrazów (wersja zapoznawcza)

Jeśli fragmenty nie zawierają wbudowanych opisów obrazów, sprawdź, czy:

• Zarówno modelName, jak i modelDeployment są ustawione w zestawie umiejętności.
• Model uzupełniania czatu w zasobie modelName jest wdrożony w tym samym zasobie Foundry, do którego odwołuje się zestaw umiejętności.
• Wdrożenie ma wystarczający limit TPM lub RPM dla wolumenu dokumentów.

Indeksator przekracza limit czasu w przypadku dużych dokumentów

Content Understanding wymusza limit czasu przetwarzania dla każdego dokumentu. Jeśli duże pliki PDF kończą się niepowodzeniem:

• Przed indeksowaniem podziel dokument źródłowy na mniejsze pliki.
• Zmniejsz batchSize do 1, aby każdy dokument był przetwarzany niezależnie.

Aby uzyskać pełne limity danych umiejętności Azure Content Understanding, zobacz Data limits.

Treści powiązane

• Umiejętność Azure Content Understanding
• Umiejętność osadzania Azure OpenAI
• Multimodalne wyszukiwanie w Wyszukiwanie AI platformy Azure
• Definiowanie projekcji indeksu dla indeksowania nadrzędno-podrzędnego
• Fragmentowanie dużych dokumentów na potrzeby wyszukiwania RAG i wyszukiwania wektorów