Azure Content Understanding スキルを使用してコンテンツをチャンクおよびベクター化する

Note

Azure AI 検索は、Azure ポータル、REST API、およびAzure SDKから使用できます。また、Foundry IQ は、エンタープライズコンテンツを、Microsoft Foundry ポータルのエージェントの再利用可能なアクセス許可に対応したナレッジベースに変換するマネージドナレッジレイヤーです。

Important

機能、またはマークされたプロパティ (プレビュー) は、サービスレベルアグリーメントの対象ではなく、運用環境のワークロードには推奨されず、一般公開される前に変更または制約される可能性があります。 Azure AI 検索プレビューの用語は、スタンドアロンでも一般公開されている機能の一部でも、すべてのプレビュー機能に適用されます。

Important

これらの機能は、他のMicrosoft サービスおよびサードパーティのサービスへの接続をサポートします。これらのサービスの利用は各サービスの利用規約に従うものとし、データが Azure コンプライアンス境界の外部で処理または保存されたり、Azure コンプライアンス境界内に流入したりする場合があります。

データが組織のコンプライアンスと地理的境界の外部に流れるかどうか、および関連する影響、および適切なアクセス許可、境界、承認がプロビジョニングされるかどうかを管理するのは、お客様の責任です。

特定のユースケースのコンテキストで構築したアプリケーションを慎重に確認およびテストし、すべての適切な決定とカスタマイズを行う責任があります。これには、メタプロンプト、コンテンツフィルター、その他の安全システムなどの独自の責任ある AI 軽減策の実装や、アプリケーションが適切な品質、信頼性、セキュリティ、信頼性の標準を満たしていることを確認する機能が含まれます。詳細については、「Azure AI 検索透過性に関するメモを参照してください。

この記事では、Azure Content Understanding スキルを使用して次の操作を行う方法について説明します。

ドキュメントからテキストと画像を抽出する
段落とセクションの境界を尊重するセマンティックコヒーレントチャンクを生成する (プレビュー)
グラフ、図、およびその他のインライン画像の AI の説明を生成する (プレビュー)
ベクター検索用の各チャンクを埋め込み、Azure AI 検索インデックスに投影する

Azure Content Understanding スキルは、各ドキュメントに対して 1 つ以上のチャンクを返します。各チャンクには、Markdown 形式のコンテンツ、場所のメタデータ (ページ番号と境界ポリゴン)、および抽出された画像への省略可能な参照が含まれます。 chunkingProperties.methodをsemanticに設定すると、チャンクは固定文字スパンではなく段落と見出しの境界に従います。 modelName と modelDeployment を設定すると、スキルは Azure OpenAI チャット完了デプロイを呼び出して、埋め込みイメージの説明を生成します。その後、スキルはそれらの説明をチャンクコンテンツにマージします。

この記事では、説明用にサンプルの医療保険プラン PDFを使用しています。 Content Understanding がサポートする形式でファイルを公開する、サポートされている任意のデータソースに対して同じパイプラインを実行できます。

Prerequisites

サポートされているリージョン内のAzure AI 検索サービス。このシナリオでは、検索サービス自体はリージョンに制約されません。
Azure Content Understanding スキルでサポートされる region のMicrosoft Foundry リソース。画像の説明とチャンク化は、Foundry リソースのリージョンで処理されます。
課金のためにスキルセットに関連付けられた Microsoft Foundry リソース。 Azure Content Understanding スキルは、Azure Content Understanding の価格で課金されます。
(省略可能)同じ Foundry リソース内のチャット完了モデル (gpt-4.1 など) の Azure OpenAI デプロイ。画像の説明を生成するために使用されます。 AI ベースの画像の説明が必要な場合にのみ必要です。
チャンクをベクトル化するために text-embedding-3-small が使用する埋め込みモデル（など）の Azure OpenAI のデプロイ。
インデックスを作成するファイルを含む Azure Blob Storage コンテナー。この記事では、(Content Understanding スキルにファイルコンテンツを渡すために使用される) allowSkillsetToReadFileData インデクサー設定で BLOB データソースを使用します。

Overview

この記事では、一対多のインデックス作成パイプラインを構築します。各ソースドキュメントは、複数の検索ドキュメント (チャンクごとに 1 つ) を生成します。

インデクサーは、Azure Blob Storageから各ファイルを読み取り、/document/file_data を介してバイナリコンテンツをスキルセットに渡します。
Azure Content Understanding スキルは、セマンティックチャンク化 (プレビュー) を使用し、text_sectionsを生成します。 modelNameとmodelDeploymentが設定されると、埋め込み画像の AI によって生成された説明 (プレビュー) も生成され、各チャンクの Markdown にインライン化されます。
Azure OpenAI Embedding スキルはチャンクごとに 1 回実行され、チャンクコンテンツのベクターが生成されます。
インデックスプロジェクションは、チャンクごとに 1 つの検索ドキュメントをターゲットインデックスに書き込み、コンテンツ、ページメタデータ、画像参照、およびベクターをフィールドにマッピングします。
（省略可能）ナレッジストアは、normalized_images を Azure Blob Storage に投影するため、クライアントアプリで URL を使用して抽出された画像を取得できます。

データファイルを準備する

Azure Content Understanding スキルは各ドキュメントのバイナリコンテンツを処理するため、ソースファイルはスキルがサポートする形式である必要があります。現在の一覧については、 Content Understanding サービスの制限を参照してください。一般的にサポートされる形式は、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"
  }
}

一対多インデックス作成用のインデックスを作成する

各検索ドキュメントは、Content Understanding スキルによって生成された 1 つのチャンクに対応します。インデックスには次のものが必要です。

キーフィールド (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"
      }
    ]
  }
}

セマンティックチャンク (プレビュー) とベクター化のスキルセットを定義する

ターゲットインデックスを配置し、それをフィードするチャンク、ベクター、プロジェクションマッピングを生成するスキルセットを定義します。

スキルセットには、次の 2 つのスキルがあります。

Azure Content Understanding スキルは各ドキュメントをチャンクします。 chunkingProperties.methodをsemanticに設定すると、スキルは段落と見出しの境界を考慮します。 modelNameとmodelDeploymentを設定すると、AI によって生成された画像の説明 (プレビュー) が有効になり、スキルはベクター化の前にチャンクコンテンツにインライン化されます。サポートされているチャット完了モデルとその他のパラメーターの詳細の一覧については、「スキルパラメーター」を参照してください。
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 スキルを参照してください。

Note

この記事では、API キーを使用して、例を簡潔に保ちます。運用環境では、マネージド ID を使用することをお勧めします。

Foundry リソースへのスキルセット: キーの代わりにマネージド ID を使用してスキルセットを Foundry リソースにバインドするには、「検索サービスを Azure AI サービスを参照してください。マネージド ID を使用する場合は、スキルセットのkey ブロックから cognitiveServices プロパティを省略します。
Azure OpenAI へのスキルセット:Azure OpenAI 埋め込みスキルでは、apiKey の代わりにマネージド ID がサポートされています。
Azure Blob Storage へのインデクサー: 接続文字列をマネージド ID 接続に置き換えます。マネージド ID を使用したデータソースへの接続の設定を参照してください。

エンドツーエンドの概要については、「ロールを使用してAzure AI 検索に接続するを参照してください。

インデクサーを構成して実行する

データソースから読み取り、スキルセットを呼び出し、チャンクをインデックスに投影するインデクサーを作成して実行します。 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": []
}

インデクサーを実行すると、Content Understanding スキルはセマンティックチャンク (プレビュー) を使用し、必要に応じて AI ベースの画像の説明 (プレビュー) を生成し、チャンクごとに 1 つの検索ドキュメントをインデックスに書き込みます。

インデクサーの状態を確認する

クエリを実行する前に、インデクサーの実行が完了したことを確認します。

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

lastResult.statusがsuccessされていることを確認します。 transientFailure が itemsProcessed を上回る 0 の場合、実行は部分的な成功となり、データが格納されたチャンクに対して引き続きクエリを実行できます。詳細については、「インデクサーの状態の監視」を参照してください。

結果を確認する

インデックスにクエリを実行して、チャンクに予想されるコンテンツが含まれていること、およびベクター検索が期待どおりに動作することを確認します。 Search Explorer または 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を構成すると、AI によって生成された画像の説明 (プレビュー) が Markdown 内にインラインで表示されます。
page_number_from page_number_to: チャンクを生成したページ範囲。
image_path: チャンクで抽出されたイメージへのパス、またはチャンクが複数のイメージにまたがる場合は、セミコロンで区切られたパスのリスト。正確な形状は、ナレッジストアファイルプロジェクションが構成されているかどうかによって異なります。ファイルプロジェクションがない場合、パスは例に示されている短い形式 (figures/3)。ファイルプロジェクションでは、パスはナレッジストア内のイメージの相対パスです。これらのイメージをクライアントアプリで使用できるようにするには、(省略可能) Projectイメージを参照して取得します。

（任意）取得用のプロジェクト画像

インデックスに格納されている image_path 値は、直接取得可能な URL ではなく、スキルのエンリッチメントツリーへのポインターです。画像を取得するには、ナレッジストアを使用して normalized_images を Azure Blob Storage に投影し、各チャンクに対応する Blob URL を生成します。

このステップはオプションです。クライアントアプリで抽出されたイメージを表示またはダウンロードする必要がある場合にのみ追加します。

前のセクションのスキルセットペイロードに次のプロパティを追加します。スキルセット要求では、 api-version=2026-08-01-previewが使用されます。

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

インデクサーの実行後、 extracted-images コンテナー内の各 BLOB は 1 つの normalized_images 要素に対応します。 BLOB URL にはフォーム https://<storage-account>.blob.core.windows.net/<container>/<imagePath>があり、 <imagePath> は image_path フィールドに格納されている値と一致します。

その他のプロジェクションの種類 (tables、objects) や認証オプションなど、完全なスキーマについては、「Knowledge store "projections" in Azure AI 検索を参照してください。

リソースをクリーンアップする

完了したら、Content Understanding と Azure OpenAI の料金が発生しないように、インデクサー、スキルセット、インデックスを削除してください。 Azure Blob Storage内のソースファイルと Foundry リソース自体は、削除するまで保持されます。

Troubleshooting

インデクサーが失敗した場合、または予期しない結果が返された場合は、次の一般的な原因を確認してください。

スキルセットの検証が 400 で失敗する

パラメーターの組み合わせが競合すると、スキルは 400 Skill validation failed エラーを返します。一般的な原因:

modelName は modelDeploymentなしで設定されます。またはその逆も同様です。両方を一緒に設定する必要があります。
method が semantic (プレビュー) であり、 overlapLength が 0より大きい。 overlapLengthを0に設定するか、省略します。
method と unit はサポートされているペアではありません。 fixedSizeでcharactersを使用するか、semanticでtokensを使用します。

Foundry リソースに対する承認が失敗する

Foundry リソースを呼び出すときにスキルが 401 または 403 を返す場合は、次のことを確認します。

スキルセットの cognitiveServices ブロックは、適切な Foundry リソースを指しています。
検索サービスで使用される ID には、Foundry リソースに必要なロールがあります。マネージド ID のセットアップについては、「 Azure AI 検索のスキルセットに課金対象リソースをアタッチする」を参照してください。

`text_sections` が空です

インデックスされたドキュメントにチャンクがない場合は、次のことを確認してください:

ファイル形式がサポートされています。一覧については、「サポートされているファイル形式」を参照してください。
Foundry リソースは、サポートされているリージョンにあります。
パスワードで保護された PDF は、インデックスを作成する前にロック解除されます。

画像の説明 (プレビュー) がありません

チャンクにインラインイメージの説明が含まれていない場合は、次のことを確認します。

modelNameとmodelDeploymentの両方がスキルセットに設定されます。
modelNameのチャット完了モデルは、スキルセットによって参照されているのと同じ Foundry リソースにデプロイされます。
デプロイには、お使いのドキュメント量に対して十分な TPM または RPM のクォータが確保されています。

インデクサーが大きなドキュメントでタイムアウトする

Content Understanding では、ドキュメントごとの処理タイムアウトが適用されます。大きな PDF が失敗した場合:

インデックスを作成する前に、ソースドキュメントをより小さなファイルに分割します。
各ドキュメントが個別に処理されるように、 batchSize を 1 に減らします。

Azure Content Understanding スキルの完全なデータ制限については、「Data の制限を参照してください。

フィードバック

このページはお役に立ちましたか?

Last updated on 2026-09-17