Разбиение содержимого на фрагменты и его векторизация с помощью навыка Azure Content Understanding

Из этой статьи вы узнаете, как использовать навык Azure Распознавание содержимого:

Навык распознавания содержимого Azure возвращает один или несколько фрагментов на документ. Каждый фрагмент содержит содержимое в формате Markdown, метаданные расположения (номера страниц и ограничивающие многоугольники) и необязательные ссылки на извлеченные изображения. Если задано значение chunkingProperties.methodsemantic, блоки следуют границам абзаца и заголовка вместо диапазонов фиксированных символов. Когда вы задаете modelName и modelDeployment, навык вызывает развертывание Azure OpenAI для завершения чата, чтобы создавать описания встроенных изображений. Затем навык объединяет эти описания в содержимое блока.

В этой статье для иллюстрации используются образцы PDF-файлов планов медицинского страхования. Один и тот же конвейер можно запустить в любом поддерживаемом источнике данных , который предоставляет файлы в формате, поддерживаемом Content Understanding.

Необходимые условия

• Служба Поиск с использованием ИИ Azure в любом поддерживаемом регионе. Сама служба поиска не ограничена регионами для этого сценария.

• Ресурс Microsoft Foundry в регионе, поддерживаемом навыком Azure Content Understanding. Создание описания изображения и разбиение на фрагменты выполняется в регионе ресурса Foundry.

• Ресурс Microsoft Foundry присоединен к набору навыков для выставления счетов. Навык Azure Content Understanding оплачивается по тарифам Тарифы Azure Content Understanding.

• (Необязательно) Развертывание Azure OpenAI модели завершения чата (например, gpt-4.1) в том же ресурсе Foundry, используемом для создания описания изображений. Требуется только в том случае, если требуется описание изображений на основе ИИ.

• Развертывание модели эмбеддингов Azure OpenAI (например, text-embedding-3-small), используемое навыком эмбеддингов Azure OpenAI для векторизации фрагментов.

• Контейнер Хранилище BLOB-объектов Azure с файлами, которые требуется индексировать. В этой статье используется источник данных BLOB с параметром индексатора allowSkillsetToReadFileData (используемым для передачи содержимого файла навыку Content Understanding).

Overview

В статье описывается создание конвейера индексации по схеме «один ко многим». Каждый исходный документ создает несколько документов поиска (по одному на блок):

1. Индексатор считывает каждый файл из Хранилище BLOB-объектов Azure и передает двоичное содержимое набору навыков через /document/file_data.

2. Навык Azure Content Understanding использует семантическое разбиение на фрагменты (предварительная версия) для создания text_sections. Если заданы modelName и modelDeployment, также создаются ИИ-описания встроенных изображений (предварительная версия) и встраиваются непосредственно в Markdown каждого фрагмента.

3. Навык Azure OpenAI Embedding выполняется один раз для каждого фрагмента и формирует вектор для содержимого фрагмента.

4. Проекция индекса записывает в целевой индекс один поисковый документ для каждого фрагмента, сопоставляя содержимое, метаданные страницы, ссылки на изображения и вектор с полями.

5. (Необязательно) Хранилище знаний проецирует normalized_images в Хранилище BLOB-объектов Azure, чтобы клиентские приложения могли получать извлечённые изображения по URL-адресу.

Подготовьте файлы данных

Навык распознавания содержимого Azure обрабатывает двоичное содержимое каждого документа, поэтому исходные файлы должны быть в формате, который поддерживает навык. Сведения о текущем списке см. в ограничениях службы "Распознавание содержимого". Распространенные поддерживаемые форматы включают PDF, DOCX, XLSX, PPTX и многие форматы изображений.

Отправьте файлы в поддерживаемый источник данных. Портал Azure, REST API или Azure SDK можно использовать для создания источника данных.

Следующий минимальный запрос создает источник данных, используемый в этом пошаговом руководстве.

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

Создать индекс для метода индексирования "один ко многим"

Каждый документ поиска соответствует одному блоку, созданному навыком "Понимание содержимого". Требуется индекс:

• Ключевое поле (chunk_id).
• Родительское поле, определяющее исходный документ, из которого был получен блок (parent_id).
• Поля, которые хранят содержимое блока, метаданные страницы и ссылки на изображения.
• Поле вектора для внедрения блока.

Следующее определение индекса соответствует набору навыков, создаваемому в следующем разделе.

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

Определение набора навыков для семантического фрагментирования (предварительная версия) и векторизации

После создания целевого индекса определите набор навыков, который формирует фрагменты, векторы и сопоставления проекций для его заполнения.

Набор навыков включает два навыка:

• Навык Azure Content Understanding разбивает каждый документ на фрагменты. Установка значения chunkingProperties.method на semantic приводит к тому, что навык учитывает границы абзацев и заголовков. Настройка modelName и modelDeployment включает описания изображений, созданные ИИ (предварительная версия), которые навык встраивает непосредственно в содержимое фрагмента перед векторизацией. Список поддерживаемых моделей завершения чата и других параметров см. в разделе "Параметры навыка".

• Навык Azure OpenAI Embedding создает вектор для содержимого каждого фрагмента.

Набор навыков использует indexProjections для сопоставления каждого фрагмента с отдельным поисковым документом. Дополнительные сведения см. в разделе "Определение проекции индекса".

Перед отправкой запроса замените <subdomain> на поддомен Azure OpenAI, <Azure OpenAI api key> на ключ ресурса внедрения, а <Foundry resource key> на ключ ресурса Foundry, связанного с набором навыков.

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

Полный справочник по параметрам, поддерживаемым значениям и правилам проверки для навыка Content Understanding см. в разделе навык Azure Content Understanding.

Настройте и запустите индексатор

Создайте и запустите индексатор, который считывает данные из источника данных, вызывает набор навыков и помещает фрагменты в индекс. Задайте для allowSkillsetToReadFileData значение true, чтобы навык Content Understanding получал содержимое файла, и задайте для parsingMode значение default.

В этом сценарии вам не нужно outputFieldMappings . Блок indexProjections в наборе навыков уже сопоставляет каждый фрагмент с полями целевого индекса.

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

При запуске индексатора навык "Понимание содержимого" использует семантические блоки (предварительная версия), при необходимости создает описания изображений на основе ИИ (предварительная версия) и записывает один документ поиска на блок в индекс.

Проверка состояния индексатора

Перед запросом подтвердите завершение выполнения индексатора:

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

Убедитесь, что lastResult.status это success. Если это transientFailure при значении itemsProcessed выше 0, запуск считается частично успешным, и вы по-прежнему можете выполнять запросы к заполненным чанкам. Дополнительные сведения см. в разделе "Мониторинг состояния индексатора".

Проверка результатов

Запросите индекс, чтобы убедиться, что блоки содержат ожидаемое содержимое и что векторный поиск работает должным образом. Используйте обозреватель поиска или любое средство, которое отправляет HTTP-запросы.

Следующий запрос выполняет гибридный поиск (поиск по ключевым словам в chunk и векторный запрос к text_vector), чтобы убедиться, что и разбитый на фрагменты текст, и эмбеддинги заполнены.

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

Успешный ответ выглядит следующим образом (обрезанный для краткости):

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

Ответ включает:

• chunk: Содержимое каждого фрагмента в формате Markdown. При настройке modelName и modelDeployment описания изображений, созданные ИИ (предварительная версия), отображаются прямо в Markdown.
• page_number_from и page_number_to: диапазон страниц, создающий блок.
• image_path: Путь к изображению, извлечённому вместе с фрагментом, или, если фрагмент охватывает несколько изображений, список путей, разделённых точкой с запятой. Точная форма зависит от того, настроена ли проекция файла в хранилище знаний. Без проекции файла путь — это короткая форма, показанная в примере (figures/3). При файловой проекции путь — это относительный путь к изображению в хранилище знаний. Чтобы сделать эти изображения доступными для клиентских приложений, см. раздел (Необязательно) Изображения проекта для извлечения.

(Необязательно) Изображения проекта для извлечения

Значения image_path, хранящиеся в индексе, являются указателями на дерево обогащения навыка, а не URL-адресами, которые можно получить напрямую. Чтобы получить изображения, спроецируйте normalized_images в Хранилище BLOB-объектов Azure с помощью хранилища знаний, а затем сформируйте URL-адрес BLOB-объекта для каждого фрагмента.

Этот шаг необязательный. Добавьте его только в том случае, если клиентское приложение должно отобразить или скачать извлеченные изображения.

Добавьте следующее свойство в полезные данные набора навыков из предыдущего раздела. Запрос набора навыков использует api-version=2026-08-01-preview.

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

После выполнения индексатора каждый BLOB-объект в контейнере extracted-images соответствует одному элементу normalized_images. URL-адрес BLOB-объекта имеет вид https://<storage-account>.blob.core.windows.net/<container>/<imagePath>, где <imagePath> соответствует значению, хранящемуся в поле image_path.

Полное описание схемы, включая дополнительные типы проекций (tables и objects) и параметры аутентификации, см. в статье «Проекции» в хранилище знаний Поиск с использованием ИИ Azure.

Очистите ресурсы

По завершении удалите индексатор, набор навыков и индекс, чтобы прекратить начисление платы за Content Understanding и Azure OpenAI. Исходные файлы в Хранилище BLOB-объектов Azure и сам ресурс Foundry остаются до их удаления.

Troubleshooting

Если индексатор дает сбой или возвращает неожиданные результаты, проверьте следующие распространенные причины.

Проверка набора навыков завершается с ошибкой 400

Навык возвращает ошибку 400 Skill validation failed при конфликте сочетаний параметров. Распространенные причины:

• modelName задан без modelDeployment, или наоборот. Оба должны быть установлены вместе.
• method — semantic (предварительная версия), а overlapLength больше, чем 0. Установите overlapLength в значение 0 или не указывайте его.
• method и unit не являются поддерживаемой парой. Используйте fixedSize с characters или semantic с tokens.

Сбой авторизации в ресурсе Foundry

Если навык возвращает значение 401 или 403 при вызове ресурса Foundry, убедитесь, что:

• Блок cognitiveServices в наборе навыков указывает на правильный ресурс Foundry.
• Учетной записи, используемой службой поиска, назначена необходимая роль на ресурсе Foundry. Сведения о конфигурациях с управляемыми удостоверениями см. в разделе Подключение платного ресурса к набору навыков в Поиск с использованием ИИ Azure.

text_sections пусто

Если проиндексированные документы не содержат фрагментов, убедитесь, что:

• Формат файла поддерживается. Список см. в разделе "Поддерживаемые форматы файлов".
• Ресурс Foundry находится в поддерживаемом регионе.
• Перед индексированием разблокируются защищенные паролем PDF-файлы.

Отсутствуют описания изображений (предварительная версия)

Если фрагменты не включают встроенные описания изображений, убедитесь, что:

• И modelName, и modelDeployment заданы в наборе навыков.
• Модель завершения чата в modelName развернута в том же ресурсе Foundry, на который ссылается набор навыков.
• Для развертывания доступна достаточная квота TPM или RPM для вашего объема документов.

При обработке больших документов индексатор превышает время ожидания

Content Understanding применяет ограничение времени обработки для каждого документа. Если не удаётся обработать большие PDF-файлы:

• Разбиение исходного документа на небольшие файлы перед индексированием.
• Уменьшите значение с batchSize до 1, чтобы каждый документ обрабатывался независимо.

Полные ограничения данных навыка распознавания содержимого Azure см. в разделе Data limits.

Связанный контент

• Навык анализа содержимого Azure
• Навык внедрения Azure OpenAI
• Мультимодальный поиск в Поиск с использованием ИИ Azure
• Определение проекции индекса для индексирования родительского дочернего элемента
• Разбивайте большие документы на части для RAG и векторного поиска