この記事では、スキルセットを使用して、 サポートされているデータ ソースのコンテンツをチャンクおよびベクター化する方法について説明します。 スキルセットは、チャンク処理を目的としてテキスト分割スキルまたはドキュメント レイアウト スキルを呼び出し、チャンク ベクター化のためにサポートされている埋め込みモデルに結び付けられた埋め込みスキルを利用します。 また、チャンクされたベクター化されたコンテンツを ベクター インデックスに格納する方法についても説明します。
この記事では、REST を使用のエンドツーエンドのワークフローについて説明します。 ポータルベースの手順については、「 クイック スタート: Azure portal でテキストとイメージをベクター化する」を参照してください。
[前提条件]
アクティブなサブスクリプションを持つ Azure アカウント。 無料でアカウントを作成できます。
Azure AI Search サービス。 Basic レベル以上をお勧めします。
クイック スタートの完了: キーなしで接続し、システム割り当てマネージド ID を構成します。 データ プレーン操作にはキーベースの認証を使用できますが、この記事では 、より安全なロールとマネージド ID を前提としています。
サポートされているデータ ソース
統合ベクター化は 、サポートされているすべてのデータ ソースで機能します。 ただし、この記事では、次の表で説明する、最もよく使用されるデータ ソースに焦点を当てています。
| サポートされているデータ ソース | 説明 |
|---|---|
| Azure Blob Storage | このデータ ソースは、BLOB とテーブルで動作します。 標準パフォーマンス (汎用 v2) アカウントを使用する必要があります。 アクセス層は、ホット、クール、またはコールドにすることができます。 |
| Azure Data Lake Storage (ADLS) Gen2 | これは、階層型名前空間が有効になっている Azure Storage アカウントです。 Data Lake Storage があることを確認するには、[概要] ページの [プロパティ] タブを確認します。
|
サポートされている埋め込みモデル
統合ベクター化の場合は、Azure AI プラットフォームで次のいずれかの埋め込みモデルを使用する必要があります。 デプロイの手順については、 後のセクションで説明します。
| プロバイダー | サポートされているモデル |
|---|---|
| Azure AI Foundry Models の Azure OpenAI1、2 | text-embedding-ada-002 text-embedding-3-small テキスト埋め込み3ラージ |
| Azure AI サービスのマルチサービス リソース3 | テキストと画像の場合: Azure AI Vision マルチモーダル4 |
1 Azure OpenAI リソースのエンドポイントには、が必要です。 Azure portal でリソースを作成した場合、このサブドメインはリソースのセットアップ中に自動的に生成されました。
Azure AI Foundry ポータルで作成された 2 つの Azure OpenAI リソース (埋め込みモデルにアクセス可能) はサポートされていません。 Azure Portal で作成された Azure OpenAI リソースのみが 、Azure OpenAI Embedding スキルと互換性があります。
3 課金目的で、 Azure AI マルチサービス リソースを Azure AI Search サービスのスキルセットにアタッチする必要があります。 キーレス接続 (プレビュー) を使用してスキルセットを作成しない限り、両方のリソースが同じリージョンに存在する必要があります。
4 Azure AI Vision マルチモーダル 埋め込みモデルは、 一部のリージョンで利用できます。
ロールベースのアクセス
ロールの割り当てと共に Microsoft Entra ID を使用するか、フル アクセス接続文字列でキーベースの認証を使用できます。 他のリソースへの Azure AI Search 接続の場合は、ロールの割り当てを推奨します。
統合ベクター化のロールベースのアクセスを構成するには:
検索サービスで、 ロールを有効に して、 システム割り当てマネージド ID を構成します。
データ ソース プラットフォームと埋め込みモデル プロバイダーで、検索サービスがデータとモデルにアクセスできるようにするロールの割り当てを作成します。 「データを準備する」と「埋め込みモデルを準備する」を参照してください。
注
無料の検索サービスでは、Azure AI Search へのロールベースの接続がサポートされます。 ただし、Azure Storage または Azure AI Vision への送信接続ではマネージド ID はサポートされていません。 このサポート不足には、無料の検索サービスと他の Azure リソース間の接続に対するキーベースの認証が必要です。
より安全な接続を実現するために、Basic レベル以上を使用します。 その後、ロールを有効にし、承認されたアクセス用にマネージド ID を構成できます。
Azure AI Search の接続情報を取得する
このセクションでは、Azure AI Search サービスのエンドポイントと Microsoft Entra トークンを取得します。 REST 要求で接続を確立するには、両方の値が必要です。
ヒント
次の手順では、概念実証テストに ロールベースのアクセス を使用していることを前提としています。 アプリ開発に統合ベクター化を使用する場合は、「 ID を使用してアプリを Azure AI Search に接続する」を参照してください。
Azure portal にサインインし、Azure AI Search サービスを選択します。
検索エンドポイントを取得するには、[ 概要 ] ページで URL をコピーします。 検索エンドポイントの例が
https://my-service.search.windows.net。Microsoft Entra トークンを取得するには、ローカル システムで次のコマンドを実行します。 この手順では、「 クイック スタート: キーなしで接続する」を完了する必要があります。
az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
データを準備する
このセクションでは、サポートされているデータ ソースにファイルをアップロードし、ロールを割り当て、接続情報を取得することで、統合ベクター化のために データを準備します。
Azure portal にサインインし、Azure Storage アカウントを選択します。
左側のウィンドウで、[ データ ストレージ>Containers] を選択します。
コンテナーを作成するか、既存のコンテナーを選択して、コンテナーにファイルをアップロードします。
ロールを割り当てるには、次の手順を実行します。
左側のウィンドウで、[ アクセス制御 (IAM)] を選択します。
[追加>][ロール割り当ての追加] の順に選択します。
[ジョブ関数のロール] で、[ストレージ BLOB データ閲覧者] を選択し、[次へ] を選択します。
[ メンバー] で [ マネージド ID] を選択し、[ メンバーの選択] を選択します。
サブスクリプションと検索サービスのマネージド ID を選択します。
接続文字列を取得するには:
左側のウィンドウで、 セキュリティ + ネットワーク>Access キーを選択します。
いずれかの接続文字列をコピーします。この接続文字列は、後で 「変数の設定」で指定します。
(省略可能)コンテナー内の削除を検索インデックスの削除と同期します。 削除検出用にインデクサーを構成するには:
ストレージ アカウントで論理的な削除を有効にします。 ネイティブの論理的な削除を使用している場合、次の手順は必要ありません。
インデクサーがスキャンできるカスタム メタデータを追加して、削除対象としてマークされている BLOB を決定します。 カスタム プロパティにわかりやすい名前を付けます。 たとえば、プロパティに "IsDeleted" という名前を付け、false に設定できます。 コンテナー内のすべての BLOB に対してこの手順を繰り返します。 BLOB を削除する場合は、プロパティを true に変更します。 詳細については、「 Azure Storage からインデックスを作成するときの変更と削除の検出」を参照してください。
埋め込みモデルを準備する
このセクションでは、ロールを割り当て、エンドポイントを取得し、 サポートされている埋め込みモデルをデプロイすることで、統合ベクター化のために Azure AI リソースを準備します。
Azure AI Search では、text-embedding-ada-002、text-embedding-3-small、text-embedding-3-large がサポートされています。 内部的には、Azure AI Search は Azure OpenAI Embedding スキルを 呼び出して Azure OpenAI に接続します。
Azure portal にサインインし、Azure OpenAI リソースを選択します。
ロールを割り当てるには、次の手順を実行します。
左側のウィンドウで、[ アクセス制御 (IAM)] を選択します。
[追加>][ロール割り当ての追加] の順に選択します。
[ジョブ関数ロール] で、[Cognitive Services OpenAI ユーザー] を選択し、[次へ] を選択します。
[ メンバー] で [ マネージド ID] を選択し、[ メンバーの選択] を選択します。
サブスクリプションと検索サービスのマネージド ID を選択します。
エンドポイントを取得するには:
左側のウィンドウで、 リソース管理>キーとエンドポイントを選択します。
Azure OpenAI リソースのエンドポイントをコピーします。 この URL は、後で 「変数の設定」で指定します。
埋め込みモデルをデプロイするには:
Azure AI Foundry ポータルにサインインし、Azure OpenAI リソースを選択します。
左側のウィンドウで、[ モデル カタログ] を選択します。
デプロイ名とモデル名をコピーします。この名前は、後で 「変数の設定」で指定します。 デプロイ名は選択したカスタム名で、モデル名はデプロイしたモデル (
text-embedding-ada-002など) です。
変数の設定
このセクションでは、Azure AI Search サービス、サポートされているデータ ソース、サポートされている埋め込みモデルの接続情報を指定します。
Visual Studio Code で、次のプレースホルダーを
.restまたは.httpファイルに貼り付けます。@baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE @token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE@baseUrlを検索エンドポイントに置き換え、@tokenを「Azure AI Search の接続情報を取得する」で取得した Microsoft Entra トークンに置き換えます。データ ソースに応じて、次の変数を追加します。
データ ソース 変数 この情報を入力してください Azure Blob Storage (アジュール・ブロブ・ストレージ) @storageConnectionStringと@blobContainer接続文字列と、「 データの準備」で作成したコンテナーの名前。 ADLS Gen2 @storageConnectionStringと@blobContainer接続文字列と、「 データの準備」で作成したコンテナーの名前。 埋め込みモデル プロバイダーに応じて、次の変数を追加します。
埋め込みモデル プロバイダー 変数 この情報を入力してください Azure OpenAI @aoaiEndpoint、@aoaiDeploymentName、@aoaiModelName「 埋め込みモデルの準備」で取得したエンドポイント、デプロイ名、およびモデル名。 Azure AI Vision @aiMultiServiceEndpoint「埋め込みモデルの準備」で取得したエンドポイント。 変数を確認するには、次の要求を送信します。
### List existing indexes by name GET {{baseUrl}}/indexes?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}}隣接するウィンドウに応答が表示されます。 既存のインデックスがある場合、そのインデックスが一覧表示されます。 そうしないと、一覧は空です。 HTTP コードが
200 OK場合は、続行する準備が整います。
データへの接続
このセクションでは、インデクサーベースのインデックス作成で サポートされているデータ ソース に接続します。 Azure AI Search の インデクサー には、種類、資格情報、コンテナーを指定するデータ ソースが必要です。
インデックス作成中に接続情報を提供するデータ ソースを定義するには、データ ソースの 作成 を使用します。
### Create a data source POST {{baseUrl}}/datasources?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "name": "my-data-source", "type": "azureblob", "subtype": null, "credentials": { "connectionString": "{{storageConnectionString}}" }, "container": { "name": "{{blobContainer}}", "query": null }, "dataChangeDetectionPolicy": null, "dataDeletionDetectionPolicy": null }typeをデータ ソース (azureblobまたはadlsgen2) に設定します。データ ソースを作成するには、[ 要求の送信] を選択します。
スキルセットを作成する
このセクションでは、組み込みのスキルを呼び出してコンテンツをチャンクし、埋め込みスキルを呼び出してチャンクのベクター表現を作成するスキル セット を作成します。 スキルセットは、 後のセクションでインデックス作成中に実行されます。
組み込みのスキルを呼び出してコンテンツをチャンクする
コンテンツをチャンクに分割すると、埋め込みモデルの要件を満たし、切り捨てによるデータ損失を防ぐことができます。 チャンク処理の詳細については、ベクター検索ソリューション向けの大規模ドキュメントのチャンク化を参照してください。
組み込みのデータ チャンクの場合、Azure AI Search には テキスト分割スキル と ドキュメント レイアウト スキルが用意されています。 テキスト分割スキルはテキストを特定の長さの文またはページに分割し、ドキュメント レイアウト スキルは段落の境界に基づいてコンテンツを分割します。
スキルセットの作成を使用してスキルセットを定義します。
### Create a skillset POST {{baseUrl}}/skillsets?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "name": "my-skillset", "skills": [] }skills配列で、テキスト分割スキルまたはドキュメント レイアウト スキルを呼び出します。 次のいずれかの定義を貼り付けることができます。"skills": [ { "@odata.type": "#Microsoft.Skills.Text.SplitSkill", "name": "my-text-split-skill", "textSplitMode": "pages", "maximumPageLength": 2000, "pageOverlapLength": 500, "maximumPagesToTake": 0, "unit": "characters", "defaultLanguageCode": "en", "inputs": [ { "name": "text", "source": "/document/text", "inputs": [] } ], "outputs": [ { "name": "textItems" } ] }, { "@odata.type": "#Microsoft.Skills.Util.DocumentIntelligenceLayoutSkill", "name": "my-document-layout-skill", "context": "/document", "outputMode": "oneToMany", "markdownHeaderDepth": "h3", "inputs": [ { "name": "file_data", "source": "/document/file_data" } ], "outputs": [ { "name": "markdown_document" } ] } ]注
ドキュメント レイアウト スキルはパブリック プレビュー段階です。 このスキルを呼び出す場合は、
2025-03-01-previewなどのプレビュー API を使用します。
埋め込みスキルを呼び出してチャンクをベクター化する
チャンクされたコンテンツをベクトル化するためには、サポートされている埋め込みモデルを示す埋め込みスキルがスキルセットに必要です。
skills配列の組み込みのチャンク スキルの後に、Azure OpenAI Embedding スキルまたは Azure AI Vision スキルを呼び出します。 次のいずれかの定義を貼り付けることができます。{ "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill", "resourceUri": "{{aoaiEndpoint}}", "deploymentId": "{{aoaiDeploymentName}}", "modelName": "{{aoaiModelName}}", "dimensions": 1536, "inputs": [ { "name": "text", "source": "/document/text" } ], "outputs": [ { "name": "embedding" } ] }, { "@odata.type": "#Microsoft.Skills.Vision.VectorizeSkill", "context": "/document", "modelVersion": "2023-04-15", "inputs": [ { "name": "url", "source": "/document/metadata_storage_path" }, { "name": "queryString", "source": "/document/metadata_storage_sas_token" } ], "outputs": [ { "name": "vector" } ] }注
Azure AI Vision スキルはパブリック プレビュー段階です。 このスキルを呼び出す場合は、
2025-03-01-previewなどのプレビュー API を使用します。Azure OpenAI Embedding スキルを使用している場合は、
dimensionsを埋め込みモデルによって生成された埋め込みの数に設定します。Azure AI Vision スキルを使用している場合は、配列の後に
skills。 この添付ファイルは課金目的です。"skills": [ ... ], "cognitiveServices": { "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity", "subdomainUrl": "{{aiMultiServiceEndpoint}}" }スキルセットを作成するには、[ 要求の送信] を選択します。
ベクトル インデックスを作成する
このセクションでは、 ベクター インデックスを作成して、Azure AI Search サービスに物理データ構造を設定します。 ベクター インデックスのスキーマには、次のものが必要です。
- 名前
- キー フィールド (文字列)
- 1 つ以上のベクター フィールド
- ベクター構成
ベクター フィールドには、チャンクされたデータの数値表現が格納されます。 検索可能で取得可能である必要がありますが、フィルター可能、ファセット可能、または並べ替え可能にすることはできません。 また、アナライザー、ノーマライザー、またはシノニム マップの割り当てを持つことはできません。
次の手順のサンプル インデックスには、ベクター フィールドに加えて、人間が判読できるコンテンツの非ベクトル フィールドが含まれています。 ベクター化するコンテンツに相当するプレーンテキストを含めるのが一般的です。 詳細については、「ベクトル インデックスを作成する」を参照してください。
インデックスの作成を使用して、ベクター インデックスのスキーマを定義します。
### Create a vector index POST {{baseUrl}}/indexes?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "name": "my-vector-index", "fields": [], "vectorSearch": [] }-
"vectorSearch": { "algorithms": [ { "name": "hnsw-algorithm", "kind": "hnsw", "hnswParameters": { "m": 4, "efConstruction": 400, "efSearch": 100, "metric": "cosine" } } ], "profiles": [ { "name": "vector-profile-hnsw", "algorithm": "hnsw-algorithm", } ] }vectorSearch.algorithmsはベクター フィールドのインデックス作成とクエリに使用されるアルゴリズムを指定しますが、vectorSearch.profilesはアルゴリズム構成をベクター フィールドに割り当てることができるプロファイルにリンクします。 埋め込みモデルに応じて、
vectorSearch.algorithms.metricを更新します。 距離メトリックの有効な値 は、cosine、dotproduct、euclidean、およびhammingです。fields配列にフィールドを追加します。 ドキュメント識別のキー フィールド、人間が判読できるコンテンツの非ベクトル フィールド、埋め込み用のベクター フィールドを含めます。"fields": [ { "name": "id", "type": "Edm.String", "key": true, "filterable": true }, { "name": "title", "type": "Edm.String", "searchable": true, "filterable": true, "sortable": true, "retrievable": true }, { "name": "titleVector", "type": "Collection(Edm.Single)", "searchable": true, "retrievable": false, "stored": true, "dimensions": 1536, "vectorSearchProfile": "vector-profile-hnsw" }, { "name": "content", "type": "Edm.String", "searchable": true, "retrievable": true }, { "name": "contentVector", "type": "Collection(Edm.Single)", "searchable": true, "retrievable": false, "stored": false, "dimensions": 1536, "vectorSearchProfile": "vector-profile-hnsw" } ]埋め込みスキルに応じて、各ベクター フィールドの
dimensionsを次の値に設定します。埋め込みスキル この値を入力します Azure OpenAI 埋め込みモデルによって生成された埋め込みの数。 Azure AI Vision 1024
インデックスにベクターライザーを追加する
このセクションでは、インデックスでベクター 化を定義 することで、クエリ時にベクター化を有効にします。 vectorizer は、データのインデックスを作成する埋め込みモデルを使用して、検索文字列または画像をベクター検索用のベクターにデコードします。
後に、Azure OpenAI ベクターライザーまたは
vectorSearch.profilesを追加します。 次のいずれかの定義を貼り付けることができます。"profiles": [ ... ], "vectorizers": [ { "name": "my-openai-vectorizer", "kind": "azureOpenAI", "azureOpenAIParameters": { "resourceUri": "{{aoaiEndpoint}}", "deploymentId": "{{aoaiDeploymentName}}", "modelName": "{{aoaiModelName}}" } }, { "name": "my-ai-services-vision-vectorizer", "kind": "aiServicesVision", "aiServicesVisionParameters": { "resourceUri": "{{aiMultiServiceEndpoint}}", "modelVersion": "2023-04-15" } } ]注
Azure AI Vision ベクターライザーはパブリック プレビュー段階です。 このベクターライザーを呼び出す場合は、
2025-03-01-previewなどのプレビュー API を使用します。vectorSearch.profilesでベクターライザーを指定します。"profiles": [ { "name": "vector-profile-hnsw", "algorithm": "hnsw-algorithm", "vectorizer": "my-openai-vectorizer" } ]ベクター インデックスを作成するには、[ 要求の送信] を選択します。
インデクサーの作成
このセクションでは、データの取得からスキルセットの実行、インデックス作成まで、ベクター化パイプライン全体を駆動する インデクサー を作成します。 スケジュール に従ってインデクサーを実行して、 スロットリングにより見逃された変更やドキュメントを処理することをお勧めします。
インデクサーの作成を使用して、ベクター化パイプラインを実行するインデクサーを定義します。
### Create an indexer POST {{baseUrl}}/indexers?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "name": "my-indexer", "dataSourceName": "my-data-source", "targetIndexName": "my-vector-index", "skillsetName": "my-skillset", "schedule": { "interval": "PT2H" }, "parameters": { "batchSize": null, "maxFailedItems": null, "maxFailedItemsPerBatch": null } }インデクサーを作成するには、[ 要求の送信] を選択します。
ベクター クエリを実行してインデックス作成を確認する
このセクションでは、 ベクター クエリを作成して、コンテンツのインデックスが正常に作成されたことを確認します。 前のセクションでベクター化を構成したため、検索エンジンはプレーン テキストまたは画像をクエリ実行用のベクターにデコードできます。
ドキュメント - 検索ポストを使用して、クエリ時にベクター化されるクエリを定義します。
### Run a vector query POST {{baseUrl}}/indexes('my-vector-index')/docs/search.post.search?api-version=2024-07-01 HTTP/1.1 Content-Type: application/json Authorization: Bearer {{token}} { "count": true, "select": "title, content", "vectorQueries": [ { "kind": "text", "text": "a sample text string for integrated vectorization", "fields": "titleVector, contentVector", "k": "3" } ] }注
Azure AI Vision ベクターライザーはパブリック プレビュー段階です。 以前にこのベクターライザーを呼び出した場合は、
2025-03-01-previewなどのプレビュー API を使用します。統合ベクター化を呼び出すクエリの場合、
kindをtextに設定し、textテキスト文字列を指定する必要があります。 この文字列は、ベクター フィールドに割り当てられたベクターライザーに渡されます。 詳細については、「 統合ベクター化を使用したクエリ」を参照してください。ベクター クエリを実行するには、[ 要求の送信] を選択します。