REST を使用してAzure AI 検索で統合ベクター化を設定する

この記事では、スキルセットを使用して、サポートされているデータソースのコンテンツをチャンクおよびベクター化する方法について説明します。スキルセットは、チャンク処理を目的としてテキスト分割スキルまたはドキュメントレイアウトスキルを呼び出し、チャンクベクター化のためにサポートされている埋め込みモデルに結び付けられた埋め込みスキルを利用します。また、チャンクされたベクター化されたコンテンツをベクターインデックスに格納する方法についても説明します。

この記事では、REST を使用したのエンドツーエンドのワークフローについて説明します。ポータルベースの手順については、「Quickstart: Azure ポータルでテキストと画像をベクター化する」を参照>。

[前提条件]

アクティブなサブスクリプションを持つAzure アカウント。無料でアカウントを作成できます。
Azure AI 検索サービス。 Basic レベル以上をお勧めします。
サポートされているデータソース。
サポートされている埋め込みモデル。
クイックスタートの完了: キーなしで接続し、システム割り当てマネージド ID を構成します。データプレーン操作にはキーベースの認証を使用できますが、この記事では、より安全なロールとマネージド ID を前提としています。
Visual Studio Code REST クライアント拡張機能。

サポートされているデータソース

統合ベクター化は、サポートされているすべてのデータソースで機能します。ただし、この記事では、次の表で説明する、最もよく使用されるデータソースに焦点を当てています。

データソース	説明
Azure Blob Storage	このデータソースは、BLOB とテーブルで動作します。標準パフォーマンス (汎用 v2) アカウントを使用する必要があります。アクセス層は、ホット、クール、またはコールドにすることができます。
Azure Data Lake Storage (ADLS) Gen2	これは、階層型名前空間が有効になっているAzure Storage アカウントです。 Data Lake Storageがあることを確認するには、Overview ページの Properties タブを確認します。 &Azure ポータルの Azure Data Lake Storage アカウントのスクリーンショット。
Microsoft OneLake	このデータソースは、OneLake ファイルとショートカットに接続します。

サポートされている埋め込みモデル

統合ベクター化には、次のいずれかの埋め込みモデルを使用します。デプロイの手順については、後のセクションで説明します。

プロバイダー	サポートされているモデル
Azure OpenAI リソース^{1, 2}	text-embedding-ada-002 text-embedding-3-small text-embedding-3-large
Microsoft Foundry リソース3	テキストと画像の場合: Azure Vision multimodal⁴

¹ Azure OpenAI リソースのエンドポイントには、など、https://my-unique-name.openai.azure.comが必要です。 Azure ポータルでリソースを作成した場合、このサブドメインはリソースのセットアップ中に自動的に生成されました。

² Azure Microsoft Foundry ポータルで作成された (埋め込みモデルにアクセスできる) OpenAI リソースはサポートされていません。 Azure ポータルで Azure OpenAI リソースを作成する必要があります。

³ 課金目的で、Microsoft Foundry リソースを Azure AI 検索スキルセットにアタッチする必要があります。キーレス接続 (プレビュー) を使用してスキルセットを作成しない限り、両方のリソースが同じリージョンに存在する必要があります。

⁴ Azure Vision マルチモーダル埋め込みモデルは、select リージョンで使用できます。

ロールベースのアクセス

ロールの割り当てでMicrosoft Entra IDを使用することも、フルアクセス接続文字列を使用してキーベースの認証を使用することもできます。他のリソースへのAzure AI 検索接続の場合は、ロールの割り当てをお勧めします。

統合ベクター化のロールベースのアクセスを構成するには:

検索サービスで、ロールを有効にして、システム割り当てマネージド ID を構成します。
データソースプラットフォームと埋め込みモデルプロバイダーで、検索サービスがデータとモデルにアクセスできるようにするロールの割り当てを作成します。「データを準備する」と「埋め込みモデルを準備する」を参照してください。

注

無料の検索サービスでは、Azure AI 検索へのロールベースの接続がサポートされます。ただし、Azure Storageまたは Azure Vision への送信接続ではマネージド ID はサポートされていません。このサポート不足では、無料の検索サービスとその他のAzure リソース間の接続にキーベースの認証を使用する必要があります。

より安全な接続を実現するために、Basic レベル以上を使用します。その後、ロールを有効にし、承認されたアクセス用にマネージド ID を構成できます。

Azure AI 検索の接続情報を取得する

このセクションでは、Azure AI 検索サービスのエンドポイントとMicrosoft Entra トークンを取得します。 REST 要求で接続を確立するには、両方の値が必要です。

ヒント

次の手順では、概念実証テストにロールベースのアクセスを使用していることを前提としています。アプリ開発に統合ベクトル化を使用する場合は、 ID を使用してアプリを Azure AI 検索に接続するを参照してください。

Azure ポータルにサインインし、Azure AI 検索サービスを選択します。
検索エンドポイントを取得するには、[ 概要 ] ページで URL をコピーします。検索エンドポイントの例が。
Microsoft Entra トークンを取得するには、ローカルシステムで次のコマンドを実行します。この手順では、「クイックスタート: キーなしで接続する」を完了する必要があります。
```
az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv
```

データの準備

このセクションでは、サポートされているデータソースにファイルをアップロードし、ロールを割り当て、接続情報を取得することで、統合ベクター化のためにデータを準備します。

Azure Blob Storage
ADLS Gen2
OneLake

Azure ポータルにサインインし、Azure Storage アカウントを選択します。
左側のウィンドウで、[ データストレージContainers] を選択します。
コンテナーを作成するか、既存のコンテナーを選択して、コンテナーにファイルをアップロードします。
ロールを割り当てるには、次の手順を実行します。
1. 左側のウィンドウで、Access Control (IAM) を選択します。
2. [追加][ロール割り当ての追加] の順に選択します。
3. [ジョブ関数のロール] で、[ストレージ BLOB データ閲覧者] を選択し、[次へ] を選択します。
4. [ メンバー] で [ マネージド ID] を選択し、[ メンバーの選択] を選択します。
5. サブスクリプションと検索サービスのマネージド ID を選択します。
接続文字列を取得するには:
1. 左側のウィンドウで、セキュリティ + ネットワークAccess キーを選択します。
2. いずれかの接続文字列をコピーします。これは、後で Set 変数で指定します。
(省略可能)コンテナー内の削除を検索インデックスの削除と同期します。削除検出用にインデクサーを構成するには:
1. ストレージアカウントで論理的な削除を有効にします。ネイティブの論理的な削除を使用している場合、次の手順は必要ありません。
2. インデクサーがスキャンできるカスタムメタデータを追加して、削除対象としてマークされている BLOB を決定します。カスタムプロパティにわかりやすい名前を付けます。たとえば、プロパティに "IsDeleted" という名前を付け、false に設定できます。コンテナー内のすべての BLOB に対してこの手順を繰り返します。 BLOB を削除する場合は、プロパティを true に変更します。詳細については、「Azure Storageを参照してください。

埋め込みモデルを準備する

このセクションでは、ロールの割り当て、エンドポイントの取得、サポートされている埋め込みモデルのデプロイを使用して、Azure AI リソースを統合ベクター化用に準備します。

Azure OpenAI
Azure Vision

Azure AI 検索では、text-embedding-ada-002、text-embedding-3-small、および text-embedding-3-large がサポートされています。内部的には、Azure AI 検索は Azure OpenAI Embedding スキルを呼び出して、Azure OpenAI に接続します。

Azure ポータルにサインインし、Azure OpenAI リソースを選択します。
ロールを割り当てるには、次の手順を実行します。
1. 左側のウィンドウで、[ アクセス制御 (IAM)] を選択します。
2. [追加][ロール割り当ての追加] の順に選択します。
3. [ジョブ関数ロール] で、[Cognitive Services OpenAI ユーザー] を選択し、[次へ] を選択します。
4. [ メンバー] で [ マネージド ID] を選択し、[ メンバーの選択] を選択します。
5. サブスクリプションと検索サービスのマネージド ID を選択します。
エンドポイントを取得するには:
1. 左側のウィンドウで、リソース管理キーとエンドポイントを選択します。
2. Azure OpenAI リソースのエンドポイントをコピーします。この URL は、後で「変数の設定」で指定します。
埋め込みモデルをデプロイするには:
1. Foundry ポータルにサインインし、Azure OpenAI リソースを選択します。
2. サポートされている埋め込みモデルをデプロイします。
3. デプロイ名とモデル名をコピーします。この名前は、後で「変数の設定」で指定します。デプロイ名は選択したカスタム名で、モデル名はデプロイしたモデル ( など) です。

変数の設定

このセクションでは、Azure AI 検索サービス、サポートされているデータソース、およびサポートされる埋め込みモデルの接続情報を指定します。

Visual Studio Codeで、次のプレースホルダーを .rest または .http ファイルに貼り付けます。
```
@baseUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@token = PUT-YOUR-MICROSOFT-ENTRA-TOKEN-HERE
```
@baseUrl を検索エンドポイントに置き換え、@token を Azure AI 検索の接続情報を取得して得た Microsoft Entra トークンに置き換えます。

データソースに応じて、次の変数を追加します。

データソース	変数	この情報を入力してください
Azure Blob Storage	および	接続文字列と、データの準備で作成したコンテナーの名前。
ADLS Gen2	および	接続文字列と、データの準備で作成したコンテナーの名前。
OneLake	および	「データの準備」で取得したワークスペース ID とレイクハウス ID。

埋め込みモデルプロバイダーに応じて、次の変数を追加します。

埋め込みモデルプロバイダー	変数	この情報を入力してください
Azure OpenAI	、、	「埋め込みモデルの準備」で取得したエンドポイント、デプロイ名、およびモデル名。
Azure ビジョン	`@AiFoundryEndpoint`	「埋め込みモデルの準備」で取得したエンドポイント。

変数を確認するには、次の要求を送信します。
```
### List existing indexes by name
GET {{baseUrl}}/indexes?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}
```
隣接するウィンドウに応答が表示されます。既存のインデックスがある場合、そのインデックスが一覧表示されます。そうしないと、一覧は空です。 HTTP コードが場合は、続行する準備が整います。

データへの接続

このセクションでは、インデクサーベースのインデックス作成でサポートされているデータソースに接続します。 Azure AI 検索のindexerには、種類、資格情報、コンテナーを指定するデータソースが必要です。

インデックス作成中に接続情報を提供するデータソースを定義するには、データソースの作成を使用します。

### Create a data source
POST {{baseUrl}}/datasources?api-version=2025-09-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
  }

をデータソース (または) に設定します。
データソースを作成するには、[ 要求の送信] を選択します。
OneLake を使用している場合は、をに設定し、をに設定します。

スキルセットを作成する

このセクションでは、組み込みのスキルを呼び出してコンテンツをチャンクし、埋め込みスキルを呼び出してチャンクのベクター表現を作成するスキルセットを作成します。スキルセットは、後のセクションでインデックス作成中に実行されます。

組み込みのスキルを呼び出してコンテンツをチャンクする

コンテンツをチャンクに分割すると、埋め込みモデルの要件を満たし、切り捨てによるデータ損失を防ぐことができます。チャンク処理の詳細については、ベクター検索ソリューション向けの大規模ドキュメントのチャンク化を参照してください。

組み込みのデータチャンクの場合、Azure AI 検索は Text Split スキルおよび Document Layout スキルを提供します。テキスト分割スキルはテキストを特定の長さの文またはページに分割し、ドキュメントレイアウトスキルは段落の境界に基づいてコンテンツを分割します。

スキルセットの作成を使用してスキルセットを定義します。

### Create a skillset
POST {{baseUrl}}/skillsets?api-version=2025-09-01  HTTP/1.1
  Content-Type: application/json
  Authorization: Bearer {{token}}

  {
    "name": "my-skillset",
    "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"
        }
       ]
     }
    ]

注

ドキュメントレイアウトスキルはパブリックプレビュー段階です。このスキルを呼び出す場合は、などのプレビュー API を使用します。

埋め込みスキルを呼び出してチャンクをベクター化する

チャンクされたコンテンツをベクトル化するためには、サポートされている埋め込みモデルを示す埋め込みスキルがスキルセットに必要です。

skills 配列の組み込みチャンクスキルの後、Azure OpenAI Embedding スキルまたは Azure 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 Vision マルチモーダル埋め込みスキルはパブリックプレビュー段階です。このスキルを呼び出す場合は、最新のプレビュー API を使用します。

Azure OpenAI Embedding スキルを使用している場合は、dimensions を埋め込みモデルによって生成された埋め込みの数に設定します。

Azure Vision マルチモーダル埋め込みスキルを使用している場合は、skillsをアタッチします。この添付ファイルは課金目的です。

    "skills": [ ... ],
    "cognitiveServices": {
      "@odata.type": "#Microsoft.Azure.Search.AIServicesByIdentity",
      "subdomainUrl": "{{AiFoundryEndpoint}}"
     }

スキルセットを作成するには、[ 要求の送信] を選択します。

ベクトルインデックスを作成する

このセクションでは、vector インデックスを作成して、Azure AI 検索サービスに物理データ構造を設定します。ベクターインデックスのスキーマには、次のものが必要です。

名前
キーフィールド (文字列)
1 つ以上のベクターフィールド
ベクター構成

ベクターフィールドには、チャンクされたデータの数値表現が格納されます。検索可能で取得可能である必要がありますが、フィルター可能、ファセット可能、または並べ替え可能にすることはできません。また、アナライザー、ノーマライザー、またはシノニムマップの割り当てを持つことはできません。

次の手順のサンプルインデックスには、ベクターフィールドに加えて、人間が判読できるコンテンツの非ベクトルフィールドが含まれています。ベクター化するコンテンツに相当するプレーンテキストを含めるのが一般的です。詳細については、「ベクトルインデックスを作成する」を参照してください。

インデックスの作成を使用して、ベクターインデックスのスキーマを定義します。

### Create a vector index
POST {{baseUrl}}/indexes?api-version=2025-09-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",
        }
      ]
    }

はベクターフィールドのインデックス作成とクエリに使用されるアルゴリズムを指定しますが、はアルゴリズム構成をベクターフィールドに割り当てることができるプロファイルにリンクします。

埋め込みモデルに応じて、を更新します。距離メトリックの有効な値は、、、、およびです。

配列にフィールドを追加します。ドキュメント識別のキーフィールド、人間が判読できるコンテンツの非ベクトルフィールド、埋め込み用のベクターフィールドを含めます。

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

埋め込みスキルに応じて、各ベクターフィールドのを次の値に設定します。

埋め込みスキル入力する値

Azure OpenAI 埋め込みモデルによって生成された埋め込みの数。

Azure ビジョン 1024

埋め込みスキル	入力する値
Azure OpenAI	埋め込みモデルによって生成された埋め込みの数。
Azure ビジョン	`1024`

インデックスにベクターライザーを追加する

このセクションでは、インデックスでベクター化を定義することで、クエリ時にベクター化を有効にします。 vectorizer は、データのインデックスを作成する埋め込みモデルを使用して、検索文字列または画像をベクター検索用のベクターにデコードします。

の後に、Azure OpenAI vectorizer または 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": "{{AiFoundryEndpoint}}",
            "modelVersion": "2023-04-15"
          }
        }
      ]

注

Azure Vision ベクターライザーはパブリックプレビュー段階です。このベクターライザーを呼び出す場合は、などのプレビュー API を使用します。

でベクターライザーを指定します。

      "profiles": [
        {
          "name": "vector-profile-hnsw",
          "algorithm": "hnsw-algorithm",
          "vectorizer": "my-openai-vectorizer"
        }
      ]

ベクターインデックスを作成するには、[ 要求の送信] を選択します。

インデクサーの作成

このセクションでは、データの取得からスキルセットの実行、インデックス作成まで、ベクター化パイプライン全体を駆動するインデクサーを作成します。スケジュールに従ってインデクサーを実行して、スロットリングにより見逃された変更やドキュメントを処理することをお勧めします。

インデクサーの作成を使用して、ベクター化パイプラインを実行するインデクサーを定義します。

### Create an indexer
POST {{baseUrl}}/indexers?api-version=2025-09-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=2025-09-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 Vision ベクターライザーはパブリックプレビュー段階です。以前にこのベクターライザーを呼び出した場合は、などのプレビュー API を使用します。

統合ベクター化を呼び出すクエリの場合、をに設定し、テキスト文字列を指定する必要があります。この文字列は、ベクターフィールドに割り当てられたベクターライザーに渡されます。詳細については、「統合ベクター化を使用したクエリ」を参照してください。
ベクタークエリを実行するには、[ 要求の送信] を選択します。

フィードバック

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

Last updated on 2026-03-05