次の方法で共有

クイックスタートガイド: セマンティックランク付け

このクイック スタートでは、.NET 用の Azure AI 検索 クライアント ライブラリを使用して、既存の検索インデックスに semantic ranking を追加し、インデックスにクエリを実行します。

セマンティック ランク付けは、コンピューターの読解力を使用して検索結果を再スコア付けし、最も意味的に関連性の高い一致を一覧の先頭に昇格させるクエリ側の機能です。 再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。 セマンティック ランク付けは、情報テキストまたは説明テキストに最も効果的です。

ヒント

すぐにget startedしたいですか? GitHubにsource コードをダウンロードします。

前提条件

アクセスを構成する

開始する前に、Azure AI 検索でコンテンツと操作をaccessするアクセス許可があることを確認してください。 このクイック スタートでは、認証にMicrosoft Entra IDを使用し、承認にロールベースのaccessを使用します。 ロールを割り当てるには、Owner または User Access Administrator である必要があります。 ロールの使用が困難な場合は、代わりにキー ベースの認証を使用してください。

推奨されるロールベースのaccessを構成するには:

  1. 検索サービスのロールベースアクセスを有効にすることができます。

  2. ユーザー アカウントに次のロールを割り当てます 。

    • Search Service 貢献者

    • 検索インデックス データ閲覧者

注

インデックスを作成して読み込む他のクイック スタートとは異なり、このクイック スタートでは、データが既に含まれている既存のインデックスを想定しているため、 検索インデックス データ共同作成者 ロールは必要ありません。

エンドポイントを取得する

各 Azure AI Search serviceには endpoint があります。これは、サービスを識別してネットワークaccessを提供する一意の URL です。 後のセクションでは、プログラムでsearch serviceに接続するために、このエンドポイントを指定します。

エンドポイントを取得するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[ 概要] を選択します。

  3. エンドポイントを書き留めておくと、https://my-service.search.windows.NET のようになります。

インデックスから始める

このクイック スタートでは、セマンティック構成を含むように既存のインデックスを変更します。 Azure portal ウィザードを使用して数分で作成できる hotels-sample インデックスをお勧めします。

別のインデックスを使用するには、サンプル コード全体で、インデックス名、セマンティック構成のフィールド名、クエリ ステートメントのフィールド名を置き換えます。 インデックスには、 と として属性付けされた説明テキスト フィールドが含まれている必要があります。

セマンティック ランク付け前に hotels-sample インデックスを確認してクエリを実行するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[検索の管理] [インデックス] を選択します。

  3. [hotels-sample] を選択してください。

  4. [ セマンティック構成 ] を選択して、既存の構成を表示します。 ウィザードの作成フロー中にセマンティック ランク付けを有効にした場合は、既定の構成が必要です。

    Azure ポータルにおける既定のセマンティック構成のスクリーンショット

  5. 検索エクスプローラーを選択し、表示JSON ビューを選択します。

  6. 次の JSON をクエリ エディターに貼り付けます。

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. [検索] を選んでクエリを実行します。

    応答は、次の例のようになります。 これは、BM25 によってランク付けされたフルテキスト クエリであるため、クエリの全体的な意味ではなく、個々のクエリ用語と言語バリアントで結果が一致します。 たとえば、 は に一致し、 と はフレーズとしてではなく、個別に一致します。

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    ヒント

    このクエリは、セマンティック ランク付けが適用される前の応答の外観を示します。 セマンティック構成を構成したら、 と を追加して、セマンティック ランク付けによって同じクエリのランクが異なる方法を確認します。

環境をセットアップする

  1. Git を使用してサンプル リポジトリを複製します。

    git clone https://github.com/Azure-Samples/azure-search-dotnet-samples

  2. クイック スタート フォルダーに移動し、Visual Studio Code で開きます。

    cd azure-search-dotnet-samples/quickstart-semantic-ranking
code .

  3. で、のプレースホルダー値を Get エンドポイントで取得した URL に置き換えます。

  4. に対して前の手順を繰り返します。

  5. Microsoft Entra IDによるキーレス認証の場合は、Azure アカウントにサインインします。 複数のサブスクリプションがある場合は、Azure AI Search serviceを含むサブスクリプションを選択します。

    az login

コードの実行

  1. 最初のprojectを実行して、セマンティック構成でインデックスを更新します。

    dotnet run --project BuildIndex

  2. 2 番目のprojectを実行してインデックスに対してクエリを実行します。 クエリ間 で Enter キー を押して、単純なクエリからセマンティック クエリへのキャプションと回答の進行状況を確認します。

    dotnet run --project QueryIndex

アウトプット

最初のprojectでは、セマンティック構成で hotels-sample インデックスが更新されます。 出力には、セマンティック構成の確認が含まれます。

Here's a list of all indexes on the search service. You should see hotels-sample:
hotels-sample

Added new semantic configuration 'semantic-config' to the index definition.
Index updated successfully.
Here is the revised index definition:
{
  "Name": "hotels-sample",
  ... // Trimmed for brevity
  "SemanticSearch": {
    "DefaultConfigurationName": "semantic-config",
    "Configurations": [
      {
        "Name": "hotels-sample-semantic-configuration",
        ... // Trimmed for brevity
      },
      {
        "Name": "semantic-config",
        "PrioritizedFields": {
          "TitleField": {
            "FieldName": "HotelName"
          },
          "ContentFields": [
            {
              "FieldName": "Description"
            }
          ],
          "KeywordsFields": [
            {
              "FieldName": "Tags"
            }
          ]
        },
        "RankingOrder": {}
      }
    ]
  }
}

2 番目のprojectでは、4 つのクエリが実行されます。 出力には、関連性スコア、キャプション、回答を含む検索結果が含まれます。

Query 1: Simple query using the search string 'walking distance to live music'.
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
----------------------------------------
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 2: Semantic query (no captions, no answers) for 'walking distance to live music'.
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
HotelId: 2
HotelName: Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.
@search.score: 5.004435
@search.rerankerScore: 2.271434783935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 3: Semantic query with captions.
Caption: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
HotelId: 24
HotelName: Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.
@search.score: 4.555706
@search.rerankerScore: 2.613231658935547
----------------------------------------
... // Trimmed for brevity
Press Enter to continue to the next query...


Query 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.
Extractive Answers:
  Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
----------------------------------------
... // Trimmed for brevity

コードを理解する

注

このセクションのコード スニペットは、読みやすくするために変更されている可能性があります。 完全な作業例については、ソース コードを参照してください。

コードを実行したので、主な手順を分解しましょう。

  1. 構成と認証
  2. セマンティック構成でインデックスを更新する
  3. インデックスのクエリを実行する

構成と認証

どちらのプロジェクトも同じ構成パターンを共有します。 ファイルは、検索エンドポイントを定義し、キーレス認証にを使用します。

var endpoint = new Uri("PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE");
var credential = new DefaultAzureCredential();
var indexClient = new SearchIndexClient(endpoint, credential);

重要なポイント:

  • DefaultAzureCredential では、Microsoft Entra IDを使用したキーレス認証が提供されます。 az login からのAzure CLI資格情報など、複数の資格情報の種類を連結します。
  • は、インデックス スキーマの更新など、インデックス レベルの操作を管理します。
  • は、インデックスのクエリなどのドキュメント レベルの操作を処理します。

セマンティック構成でインデックスを更新する

の次のコードは、セマンティック構成を既存のインデックスに追加します。 この操作では、検索ドキュメントは削除されません。構成が追加された後もインデックスは引き続き動作します。

static void AddSemanticConfiguration(
    SearchIndex index,
    string semanticConfigName)
{
    if (index.SemanticSearch == null)
    {
        index.SemanticSearch = new SemanticSearch();
    }
    var configs = index.SemanticSearch.Configurations;
    if (!configs.Any(c => c.Name == semanticConfigName))
    {
        var prioritizedFields =
            new SemanticPrioritizedFields
        {
            TitleField = new SemanticField("HotelName"),
            ContentFields =
            {
                new SemanticField("Description")
            },
            KeywordsFields =
            {
                new SemanticField("Tags")
            }
        };

        configs.Add(
            new SemanticConfiguration(
                semanticConfigName,
                prioritizedFields
            )
        );
    }
    index.SemanticSearch.DefaultConfigurationName =
        semanticConfigName;
}

重要なポイント:

  • セマンティック構成では、セマンティック ランク付けに使用されるフィールドを指定します。
  • セマンティック構成は、再構築せずに既存のインデックスに追加できます。
  • は、ドキュメントタイトルを表すフィールドを設定します。
  • は、メイン コンテンツを含むフィールドを設定します。
  • は、キーワードまたはタグを含むフィールドを設定します。

インデックスのクエリを実行する

QueryIndex projectは 4 つのクエリを順番に実行し、単純なキーワード検索からキャプションと回答を含むセマンティック ランク付けに進みます。

単純なクエリ

最初のクエリは、セマンティック ランク付けを使用しない単純なキーワード検索です。 このクエリは、セマンティック再ランク付けと比較せずに結果を比較するためのベースラインとして機能します。

await RunQuery(client, searchText, new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Simple,
    IncludeTotalCount = true,
    Select = { "HotelId", "HotelName", "Description" }
});

重要なポイント:

  • このシステムでは、既定の BM25 ランク付けアルゴリズムが使用されます。
  • 結果はキーワードの関連性 () によってのみランク付けされます。

セマンティック クエリ (キャプションなし、回答なし)

次のクエリでは、キャプションや回答のないセマンティック ランク付けが追加されます。 次のコードは、セマンティック ランク付けを呼び出すための最小要件を示しています。

var semanticOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config"
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(client, searchText, semanticOptions);

重要なポイント:

  • を使用すると、クエリのセマンティック ランク付けが可能になります。
  • は、使用するセマンティック構成を指定します。
  • はセマンティックの関連性を示します (高い方が良い)。
  • 用語クエリの最初の結果は、セマンティック ランク付けモデルを使用して再スコア付けされます。 このデータセットとクエリの場合、セマンティック ランク付けの効果は、下位ランクの結果でより顕著になります。

キャプションを含むセマンティック クエリ

次のコードでは、キャプションを追加して各結果から最も関連性の高い箇所を抽出し、重要な用語と語句にヒット強調表示を適用します。

var captionsOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryCaption =
            new QueryCaption(QueryCaptionType.Extractive)
        {
            HighlightEnabled = true
        }
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
captionsOptions.HighlightFields.Add("Description");
await RunQuery(
    client, searchText, captionsOptions, showCaptions: true
);

重要なポイント:

  • コンテンツフィールドから抽出されたキャプションを有効にします。
  • キャプションは最も関連性の高い箇所を表示し、重要な用語に<em>タグを追加します。

回答を含むセマンティック クエリ

最後のクエリでは、セマンティック回答が追加されます。 セマンティック回答はクエリが質問として表現される場合に最適であるため、このクエリでは別の検索文字列 () が使用されます。 答えは、チャット完了モデルから構成された応答ではなく、インデックスから抽出された逐語的な一節です。

回答を返すには、クエリとインデックス付きコンテンツを厳密に揃える必要があります。 信頼度しきい値を満たす候補がない場合、応答には回答は含まれません。 この例では、構文を確認できるように、結果を生成するために既知の質問を使用します。 回答がシナリオに役立たない場合は、コードから を省略します。 構成された回答については、 RAG パターン または エージェント検索を検討してください。

var answersOptions = new SearchOptions
{
    Size = 5,
    QueryType = SearchQueryType.Semantic,
    SemanticSearch = new SemanticSearchOptions
    {
        SemanticConfigurationName = "semantic-config",
        QueryAnswer =
            new QueryAnswer(QueryAnswerType.Extractive)
    },
    IncludeTotalCount = true,
    Select =
    {
        "HotelId", "HotelName", "Description"
    }
};
await RunQuery(
    client, searchText2, answersOptions, showAnswers: true
);

重要なポイント:

  • では、質問に似たクエリに対する抽出的な回答が可能になります。
  • 回答は、生成されたテキストではなく、インデックスから抽出された逐語的なコンテンツです。

このクイック スタートでは、Java 用の Azure AI 検索 クライアント ライブラリを使用して、既存の検索インデックスに semantic ranking を追加し、インデックスにクエリを実行します。

セマンティック ランク付けは、コンピューターの読解力を使用して検索結果を再スコア付けし、最も意味的に関連性の高い一致を一覧の先頭に昇格させるクエリ側の機能です。 再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。 セマンティック ランク付けは、情報テキストまたは説明テキストに最も効果的です。

ヒント

すぐにget startedしたいですか? GitHubにsource コードをダウンロードします。

前提条件

アクセスを構成する

開始する前に、Azure AI 検索でコンテンツと操作をaccessするアクセス許可があることを確認してください。 このクイック スタートでは、認証にMicrosoft Entra IDを使用し、承認にロールベースのaccessを使用します。 ロールを割り当てるには、Owner または User Access Administrator である必要があります。 ロールの使用が困難な場合は、代わりにキー ベースの認証を使用してください。

推奨されるロールベースのaccessを構成するには:

  1. 検索サービスのロールベースアクセスを有効にすることができます。

  2. ユーザー アカウントに次のロールを割り当てます 。

    • Search Service 貢献者

    • 検索インデックス データ閲覧者

注

インデックスを作成して読み込む他のクイック スタートとは異なり、このクイック スタートでは、データが既に含まれている既存のインデックスを想定しているため、 検索インデックス データ共同作成者 ロールは必要ありません。

エンドポイントを取得する

各 Azure AI Search serviceには endpoint があります。これは、サービスを識別してネットワークaccessを提供する一意の URL です。 後のセクションでは、プログラムでsearch serviceに接続するために、このエンドポイントを指定します。

エンドポイントを取得するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[ 概要] を選択します。

  3. エンドポイントを書き留めておくと、https://my-service.search.windows.NET のようになります。

インデックスから始める

このクイック スタートでは、セマンティック構成を含むように既存のインデックスを変更します。 Azure portal ウィザードを使用して数分で作成できる hotels-sample インデックスをお勧めします。

別のインデックスを使用するには、サンプル コード全体で、インデックス名、セマンティック構成のフィールド名、クエリ ステートメントのフィールド名を置き換えます。 インデックスには、 と として属性付けされた説明テキスト フィールドが含まれている必要があります。

セマンティック ランク付け前に hotels-sample インデックスを確認してクエリを実行するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[検索の管理] [インデックス] を選択します。

  3. [hotels-sample] を選択してください。

  4. [ セマンティック構成 ] を選択して、既存の構成を表示します。 ウィザードの作成フロー中にセマンティック ランク付けを有効にした場合は、既定の構成が必要です。

    Azure ポータルにおける既定のセマンティック構成のスクリーンショット

  5. 検索エクスプローラーを選択し、表示JSON ビューを選択します。

  6. 次の JSON をクエリ エディターに貼り付けます。

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. [検索] を選んでクエリを実行します。

    応答は、次の例のようになります。 これは、BM25 によってランク付けされたフルテキスト クエリであるため、クエリの全体的な意味ではなく、個々のクエリ用語と言語バリアントで結果が一致します。 たとえば、 は に一致し、 と はフレーズとしてではなく、個別に一致します。

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    ヒント

    このクエリは、セマンティック ランク付けが適用される前の応答の外観を示します。 セマンティック構成を構成したら、 と を追加して、セマンティック ランク付けによって同じクエリのランクが異なる方法を確認します。

環境をセットアップする

  1. Git を使用してサンプル リポジトリを複製します。

    git clone https://github.com/Azure-Samples/azure-search-java-samples

  2. クイック スタート フォルダーに移動し、Visual Studio Code で開きます。

    cd azure-search-java-samples/quickstart-semantic-ranking
code .

  3. src/main/resources/application.properties で、Azure.search.endpoint のプレースホルダー値を、Get エンドポイントで取得した URL に置き換えます。

  4. projectをコンパイルして、Azure-search-documents などの依存関係を解決します。

    mvn compile

    ビルドが完了したら、出力にエラーが表示されていないことを確認します。

  5. Microsoft Entra IDによるキーレス認証の場合は、Azure アカウントにサインインします。 複数のサブスクリプションがある場合は、Azure AI Search serviceを含むサブスクリプションを選択します。

    az login

コードの実行

  1. 既存のインデックス設定を取得します。

    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.GetIndexSettings"

  2. セマンティック構成でインデックスを更新します。

    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.UpdateIndexSettings"

  3. セマンティック クエリを実行します。

    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQuery"

  4. キャプションを使用してセマンティック クエリを実行します。

    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticQueryWithCaptions"

  5. 回答を含むセマンティック クエリを実行します。

    mvn compile exec:java "-Dexec.mainClass=com.azure.search.quickstart.SemanticAnswer"

アウトプット

の出力は、インデックスの名前、フィールド、およびセマンティック構成です。 新しい構成を追加する前に、インデックスには既定の構成のみが含まれます。

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic search configurations: 1
Configuration name: hotels-sample-semantic-configuration

の出力には、コードが追加されたものを含め、インデックス上のすべてのセマンティック構成が一覧表示され、その後に成功メッセージが表示されます。

// Trimmed for brevity
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

の出力は、セマンティック ランク付けリランカー スコアによって並べ替えられた一致するすべてのドキュメントを返します。

Search result #1:
  Re-ranker Score: 2.61
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.27
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.99
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

この出力によって、検索フィールドとともに、ヒットがハイライト表示されたキャプション要素が追加されます。 キャプションは、結果の中で最も関連性の高い一節です。 インデックスに大きなテキストが含まれている場合、キャプションは最も興味深い文を抽出するのに役立ちます。

Search result #1:
  Re-ranker Score: 2.61
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.27
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

の出力には、質問に最も一致する結果の 1 つから取得されたセマンティック回答と、キャプション付きの検索結果が含まれます。

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.98

Search Results:

Search result #1:
Re-ranker Score: 2.12
Hotel: Stay-Kay City Hotel
Description: This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.

Search result #2:
Re-ranker Score: 2.07
Hotel: Double Sanctuary Resort
Description: 5 star Luxury Hotel - Biggest Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
Caption: <em>5 star Luxury Hotel </em>-<em> Biggest </em>Rooms in the city. #1 Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.
// Trimmed for brevity

コードを理解する

注

このセクションのコード スニペットは、読みやすくするために変更されている可能性があります。 完全な作業例については、ソース コードを参照してください。

コードを実行したので、主な手順を分解しましょう。

  1. 構成と認証
  2. セマンティック構成でインデックスを更新する
  3. インデックスのクエリを実行する

構成と認証

クラスはプロパティを読み込み、キーレス認証のための設定を作成します。

import com.azure.identity.DefaultAzureCredential;
import com.azure.identity.DefaultAzureCredentialBuilder;

import java.io.IOException;
import java.io.InputStream;
import java.util.Properties;

public class SearchConfig {
    private static final Properties properties =
        new Properties();

    static {
        try (InputStream input = SearchConfig.class
            .getClassLoader()
            .getResourceAsStream(
                "application.properties")) {
            properties.load(input);
        } catch (IOException e) {
            throw new RuntimeException(
                "Failed to load application.properties",
                e);
        }
    }

    public static final String SEARCH_ENDPOINT =
        properties.getProperty(
            "azure.search.endpoint");
    public static final String INDEX_NAME =
        properties.getProperty(
            "azure.search.index.name");
    public static final String SEMANTIC_CONFIG_NAME =
        properties.getProperty(
            "semantic.configuration.name");

    public static final DefaultAzureCredential
        CREDENTIAL = new DefaultAzureCredentialBuilder()
            .build();
}

重要なポイント:

  • DefaultAzureCredential では、Microsoft Entra IDを使用したキーレス認証が提供されます。 az login からのAzure CLI資格情報など、複数の資格情報の種類を連結します。
  • プロパティは、クラスパスの ファイルから読み込まれます。
  • 静的フィールド (SEARCH_ENDPOINT、INDEX_NAME、SEMANTIC_CONFIG_NAME、CREDENTIAL) は、project内のすべてのクラスで共有されます。

セマンティック構成でインデックスを更新する

クラスは、既存の インデックスにセマンティック構成を追加します。 この操作では、検索ドキュメントは削除されません。構成が追加された後もインデックスは引き続き動作します。

import com.azure.search.documents.indexes
    .SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models
    .SearchIndex;
import com.azure.search.documents.indexes.models
    .SemanticConfiguration;
import com.azure.search.documents.indexes.models
    .SemanticField;
import com.azure.search.documents.indexes.models
    .SemanticPrioritizedFields;
import com.azure.search.documents.indexes.models
    .SemanticSearch;

import java.util.ArrayList;
import java.util.List;

var indexClient = new SearchIndexClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

SearchIndex existingIndex =
    indexClient.getIndex(SearchConfig.INDEX_NAME);

var prioritizedFields =
    new SemanticPrioritizedFields()
        .setTitleField(
            new SemanticField("HotelName"))
        .setKeywordsFields(
            List.of(new SemanticField("Tags")))
        .setContentFields(
            List.of(
                new SemanticField("Description")));

var newSemanticConfiguration =
    new SemanticConfiguration(
        SearchConfig.SEMANTIC_CONFIG_NAME,
        prioritizedFields);

SemanticSearch semanticSearch =
    existingIndex.getSemanticSearch();
if (semanticSearch == null) {
    semanticSearch = new SemanticSearch();
    existingIndex.setSemanticSearch(semanticSearch);
}

List<SemanticConfiguration> configurations =
    semanticSearch.getConfigurations();
if (configurations == null) {
    configurations = new ArrayList<>();
    semanticSearch.setConfigurations(configurations);
}

configurations.add(newSemanticConfiguration);

indexClient.createOrUpdateIndex(existingIndex);

重要なポイント:

  • は、セマンティック ランカーが評価するフィールドを定義します。 は、ドキュメントタイトルを設定 メインコンテンツを設定し、 キーワードまたはタグフィールドを設定します。
  • は、名前と優先順位付けされたフィールドを組み合わせて、クエリ時に使用するセマンティック構成を識別します。
  • createOrUpdateIndex は、インデックスを再構築したりドキュメントを削除したりせずに、更新されたスキーマをsearch serviceにプッシュします。

インデックスのクエリを実行する

次の 3 つのクラスは、インデックスを順番に照会し、基本的なセマンティック検索からキャプションと回答を含むセマンティックランク付けに進みます。

セマンティック クエリ (キャプションなし、回答なし)

最初のクエリでは、キャプションや回答のないセマンティック ランク付けが追加されます。 クラスは、セマンティック ランク付けを呼び出すための最小要件を示しています。

import com.azure.search.documents
    .SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryType;
import com.azure.search.documents.models.SearchOptions;
import com.azure.search.documents.models.SearchResult;
import com.azure.search.documents.models
    .SemanticSearchOptions;
import com.azure.search.documents.util
    .SearchPagedIterable;

var searchClient = new SearchClientBuilder()
    .endpoint(SearchConfig.SEARCH_ENDPOINT)
    .indexName(SearchConfig.INDEX_NAME)
    .credential(SearchConfig.CREDENTIAL)
    .buildClient();

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME))
    .setSelect("HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    var document = result.getDocument(
        SearchDocument.class);
    double rerankerScore = result
        .getSemanticSearch().getRerankerScore();

    System.out.printf("Re-ranker Score: %.2f%n",
        rerankerScore);
    System.out.printf("HotelName: %s%n",
        document.get("HotelName"));
    System.out.printf("Description: %s%n%n",
        document.get("Description"));
}

重要なポイント:

  • を使用すると、クエリのセマンティック ランク付けが可能になります。
  • は、使用するセマンティック構成を指定します。
  • は、再ランク付けされた結果に対して反復可能な機能を提供します。 各 には、リランカー スコアの アクセサーが含まれています。

キャプションを含むセマンティック クエリ

クラスは、各結果から最も関連性の高い箇所を抽出するキャプションを追加し、重要な用語とフレーズにヒット強調表示を適用します。

import com.azure.search.documents.models
    .QueryCaption;
import com.azure.search.documents.models
    .QueryCaptionResult;
import com.azure.search.documents.models
    .QueryCaptionType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE)
                    .setHighlightEnabled(true)))
    .setSelect(
        "HotelId", "HotelName", "Description");

SearchPagedIterable results = searchClient.search(
    "walking distance to live music",
    searchOptions, null);

for (SearchResult result : results) {
    List<QueryCaptionResult> captions =
        result.getSemanticSearch()
            .getQueryCaptions();
    if (captions != null && !captions.isEmpty()) {
        QueryCaptionResult caption = captions.get(0);
        if (caption.getHighlights() != null) {
            System.out.printf(
                "Caption: %s%n",
                caption.getHighlights());
        }
    }
}

重要なポイント:

  • コンテンツフィールドから抽出されたキャプションを有効にします。
  • 重要な用語にはキャプション内でタグが追加されます。
  • 各セマンティック検索アクセサーは、それぞれに関連する情報を提供します。

回答を含むセマンティック クエリ

クラスはセマンティック回答を追加します。 セマンティック回答は、クエリが質問として表現される場合に最適であるため、このクラスは質問を検索テキストとして使用します。 答えは、チャット完了モデルから構成された応答ではなく、インデックスから抽出された逐語的な一節です。

回答を返すには、クエリとインデックス付きコンテンツを厳密に揃える必要があります。 信頼度しきい値を満たす候補がない場合、応答には回答は含まれません。 この例では、構文を確認できるように、結果を生成するために既知の質問を使用します。 回答がシナリオに役立たない場合は、コードから を省略します。 構成された回答については、 RAG パターン または エージェント検索を検討してください。

import com.azure.search.documents.models
    .QueryAnswer;
import com.azure.search.documents.models
    .QueryAnswerResult;
import com.azure.search.documents.models
    .QueryAnswerType;

var searchOptions = new SearchOptions()
    .setQueryType(QueryType.SEMANTIC)
    .setSemanticSearchOptions(
        new SemanticSearchOptions()
            .setSemanticConfigurationName(
                SearchConfig.SEMANTIC_CONFIG_NAME)
            .setQueryCaption(
                new QueryCaption(
                    QueryCaptionType.EXTRACTIVE))
            .setQueryAnswer(
                new QueryAnswer(
                    QueryAnswerType.EXTRACTIVE)))
    .setSelect(
        "HotelName", "Description", "Category");

SearchPagedIterable results = searchClient.search(
    "What's a good hotel for people who like to read",
    searchOptions, null);

List<QueryAnswerResult> semanticAnswers =
    results.getSemanticResults().getQueryAnswers();

for (QueryAnswerResult answer :
    semanticAnswers != null ? semanticAnswers
        : List.<QueryAnswerResult>of()) {
    if (answer.getHighlights() != null) {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getHighlights());
    } else {
        System.out.printf(
            "Semantic Answer: %s%n",
            answer.getText());
    }
    System.out.printf(
        "Semantic Answer Score: %.2f%n",
        answer.getScore());
}

重要なポイント:

  • では、質問に似たクエリに対する抽出的な回答が可能になります。
  • 回答は、生成されたテキストではなく、インデックスから抽出された逐語的なコンテンツです。
  • は、検索結果とは別に回答オブジェクトを取得します。

このクイック スタートでは、JavaScript 用の Azure AI 検索 クライアント ライブラリを使用して、既存の検索インデックスに semantic ranking を追加し、インデックスにクエリを実行します。

セマンティック ランク付けは、コンピューターの読解力を使用して検索結果を再スコア付けし、最も意味的に関連性の高い一致を一覧の先頭に昇格させるクエリ側の機能です。 再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。 セマンティック ランク付けは、情報テキストまたは説明テキストに最も効果的です。

ヒント

すぐにget startedしたいですか? GitHubにsource コードをダウンロードします。

前提条件

アクセスを構成する

開始する前に、Azure AI 検索でコンテンツと操作をaccessするアクセス許可があることを確認してください。 このクイック スタートでは、認証にMicrosoft Entra IDを使用し、承認にロールベースのaccessを使用します。 ロールを割り当てるには、Owner または User Access Administrator である必要があります。 ロールの使用が困難な場合は、代わりにキー ベースの認証を使用してください。

推奨されるロールベースのaccessを構成するには:

  1. 検索サービスのロールベースアクセスを有効にすることができます。

  2. ユーザー アカウントに次のロールを割り当てます 。

    • Search Service 貢献者

    • 検索インデックス データ閲覧者

注

インデックスを作成して読み込む他のクイック スタートとは異なり、このクイック スタートでは、データが既に含まれている既存のインデックスを想定しているため、 検索インデックス データ共同作成者 ロールは必要ありません。

エンドポイントを取得する

各 Azure AI Search serviceには endpoint があります。これは、サービスを識別してネットワークaccessを提供する一意の URL です。 後のセクションでは、プログラムでsearch serviceに接続するために、このエンドポイントを指定します。

エンドポイントを取得するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[ 概要] を選択します。

  3. エンドポイントを書き留めておくと、https://my-service.search.windows.NET のようになります。

インデックスから始める

このクイック スタートでは、セマンティック構成を含むように既存のインデックスを変更します。 Azure portal ウィザードを使用して数分で作成できる hotels-sample インデックスをお勧めします。

別のインデックスを使用するには、サンプル コード全体で、インデックス名、セマンティック構成のフィールド名、クエリ ステートメントのフィールド名を置き換えます。 インデックスには、 と として属性付けされた説明テキスト フィールドが含まれている必要があります。

セマンティック ランク付け前に hotels-sample インデックスを確認してクエリを実行するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[検索の管理] [インデックス] を選択します。

  3. [hotels-sample] を選択してください。

  4. [ セマンティック構成 ] を選択して、既存の構成を表示します。 ウィザードの作成フロー中にセマンティック ランク付けを有効にした場合は、既定の構成が必要です。

    Azure ポータルにおける既定のセマンティック構成のスクリーンショット

  5. 検索エクスプローラーを選択し、表示JSON ビューを選択します。

  6. 次の JSON をクエリ エディターに貼り付けます。

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. [検索] を選んでクエリを実行します。

    応答は、次の例のようになります。 これは、BM25 によってランク付けされたフルテキスト クエリであるため、クエリの全体的な意味ではなく、個々のクエリ用語と言語バリアントで結果が一致します。 たとえば、 は に一致し、 と はフレーズとしてではなく、個別に一致します。

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    ヒント

    このクエリは、セマンティック ランク付けが適用される前の応答の外観を示します。 セマンティック構成を構成したら、 と を追加して、セマンティック ランク付けによって同じクエリのランクが異なる方法を確認します。

環境をセットアップする

  1. Git を使用してサンプル リポジトリを複製します。

    git clone https://github.com/Azure-Samples/azure-search-javascript-samples

  2. クイック スタート フォルダーに移動し、Visual Studio Code で開きます。

    cd azure-search-javascript-samples/quickstart-semantic-ranking-js
code .

  3. で、のプレースホルダー値を Get エンドポイントで取得した URL に置き換えます。

  4. の名前を に変更します。

    mv sample.env .env

  5. 依存関係をインストールします。

    npm install

    インストールが完了すると、project ディレクトリに node_modules フォルダーが表示されます。

  6. Microsoft Entra IDによるキーレス認証の場合は、Azure アカウントにサインインします。 複数のサブスクリプションがある場合は、Azure AI Search serviceを含むサブスクリプションを選択します。

    az login

コードの実行

  1. 既存のインデックス設定を取得します。

    node -r dotenv/config src/getIndexSettings.js

  2. セマンティック構成でインデックスを更新します。

    node -r dotenv/config src/updateIndexSettings.js

  3. セマンティック クエリを実行します。

    node -r dotenv/config src/semanticQuery.js

  4. キャプションを使用してセマンティック クエリを実行します。

    node -r dotenv/config src/semanticQueryReturnCaptions.js

  5. 回答を含むセマンティック クエリを実行します。

    node -r dotenv/config src/semanticAnswer.js

アウトプット

スクリプトは、インデックスの名前、そのフィールド、および既存のセマンティック構成を返します。

Getting semantic ranking index settings...
Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
Field: Description_fr, Type: Edm.String, Searchable: true
Field: Category, Type: Edm.String, Searchable: true
Field: Tags, Type: Collection(Edm.String), Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

スクリプトは、コードが追加されたものを含め、インデックス上のすべてのセマンティック構成を返し、その後に成功メッセージが返されます。

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

スクリプトは、セマンティックランキングのリランカースコアで並べ替えられた、すべての一致するドキュメントを返します。

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

Search result #3:
  Re-ranker Score: 1.9861756563186646
  HotelId: 4
  HotelName: Sublime Palace Hotel
  Description: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience.
// Trimmed for brevity

スクリプトは、検索フィールドと共にヒットが強調表示されたキャプション要素を返します。 キャプションは、結果の中で最も関連性の高い一節です。 インデックスに大きなテキストが含まれている場合、キャプションは最も興味深い文を抽出するのに役立ちます。

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and then head over to<em> Benaroya Hall </em>to catch the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music.

  Caption text: The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live.
------------------------------------------------------------
// Trimmed for brevity

スクリプトは、質問に最も一致する結果の 1 つから取得されたセマンティック回答を返し、その後にキャプション付きの検索結果を返します。

Answers:

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
Caption: This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city in the heart of New York. A few minutes away is Times Square and the historic centre of the city, as well as other places of interest that make New York one of America's most attractive and cosmopolitan cities.
// Trimmed for brevity

コードを理解する

注

このセクションのコード スニペットは、読みやすくするために変更されている可能性があります。 完全な作業例については、ソース コードを参照してください。

コードを実行したので、主な手順を分解しましょう。

  1. 構成と認証
  2. セマンティック構成でインデックスを更新する
  3. インデックスのクエリを実行する

構成と認証

ファイルは環境変数を読み込み、認証用の設定を作成します。

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

重要なポイント:

  • DefaultAzureCredential では、Microsoft Entra IDを使用したキーレス認証が提供されます。 az login からのAzure CLI資格情報など、複数の資格情報の種類を連結します。
  • 環境変数は、を使用して ファイルから読み込まれます。

セマンティック構成でインデックスを更新する

ファイルは、既存の インデックスにセマンティック構成を追加します。 この操作では、検索ドキュメントは削除されません。構成が追加された後もインデックスは引き続き動作します。

import { SearchIndexClient }
    from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields = {
    titleField: { name: "HotelName" },
    keywordsFields: [{ name: "Tags" }],
    contentFields: [{ name: "Description" }]
};

const newSemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

重要なポイント:

  • セマンティック構成では、セマンティック ランク付けに使用されるフィールドを指定します。 はドキュメントタイトルを定義し、 はメインコンテンツを定義し、 はキーワードまたはタグフィールドを定義します。
  • 構成オブジェクトを作成し、既存のインデックスの 配列にプッシュします。
  • createOrUpdateIndex は、インデックスを再構築したりドキュメントを削除したりせずに、更新されたスキーマをsearch serviceにプッシュします。

インデックスのクエリを実行する

クエリ スクリプトは、基本的なセマンティック検索からキャプションと回答を含むセマンティックランク付けに進む 3 つのクエリを順番に実行します。

セマンティック クエリ (キャプションなし、回答なし)

次のコードは、セマンティック ランク付けを呼び出すための最小要件を示しています。

import { SearchClient }
    from "@azure/search-documents";
import {
    credential, searchEndpoint,
    indexName, semanticConfigurationName
} from "./config.js";

const searchClient = new SearchClient(
    searchEndpoint, indexName, credential
);

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

重要なポイント:

  • を使用すると、クエリのセマンティック ランク付けが可能になります。
  • は、使用するセマンティック構成を指定します。
  • 結果内の「 」は意味的な関連性を示し、数値が高いほど関連性が高いです。

キャプションを含むセマンティック クエリ

次のコードでは、キャプションを追加して各結果から最も関連性の高い箇所を抽出し、重要な用語と語句にヒット強調表示を適用します。

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

重要なポイント:

  • コンテンツフィールドから抽出されたキャプションを有効にします。
  • キャプションは最も関連性の高い箇所を見つけ出し、重要な用語に<em>タグを追加します。

回答を含むセマンティック クエリ

最後のクエリでは、セマンティック回答が追加されます。 セマンティック回答は、クエリが質問として表現される場合に最適であるため、このクエリでは質問が検索テキストとして使用されます。 答えは、チャット完了モデルから構成された応答ではなく、インデックスから抽出された逐語的な一節です。

回答を返すには、クエリとインデックス付きコンテンツを厳密に揃える必要があります。 信頼度しきい値を満たす候補がない場合、応答には回答は含まれません。 この例では、構文を確認できるように、結果を生成するために既知の質問を使用します。 回答がシナリオに役立たない場合は、コードから を省略します。 構成された回答については、 RAG パターン または エージェント検索を検討してください。

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

重要なポイント:

  • では、質問に似たクエリに対する抽出的な回答が可能になります。
  • 回答は、生成されたテキストではなく、インデックスから抽出された逐語的なコンテンツです。
  • は、検索結果とは別に回答オブジェクトを取得します。

このクイック スタートでは、Python 用の Azure AI 検索 クライアント ライブラリ を使用して、既存の検索インデックスに semantic ranking を追加し、インデックスのクエリを実行します。

セマンティック ランク付けは、コンピューターの読解力を使用して検索結果を再スコア付けし、最も意味的に関連性の高い一致を一覧の先頭に昇格させるクエリ側の機能です。 再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。 セマンティック ランク付けは、情報テキストまたは説明テキストに最も効果的です。

ヒント

すぐにget startedしたいですか? GitHubにsource コードをダウンロードします。

前提条件

アクセスを構成する

開始する前に、Azure AI 検索でコンテンツと操作をaccessするアクセス許可があることを確認してください。 このクイック スタートでは、認証にMicrosoft Entra IDを使用し、承認にロールベースのaccessを使用します。 ロールを割り当てるには、Owner または User Access Administrator である必要があります。 ロールの使用が困難な場合は、代わりにキー ベースの認証を使用してください。

推奨されるロールベースのaccessを構成するには:

  1. 検索サービスのロールベースアクセスを有効にすることができます。

  2. ユーザー アカウントに次のロールを割り当てます 。

    • Search Service 貢献者

    • 検索インデックス データ閲覧者

注

インデックスを作成して読み込む他のクイック スタートとは異なり、このクイック スタートでは、データが既に含まれている既存のインデックスを想定しているため、 検索インデックス データ共同作成者 ロールは必要ありません。

エンドポイントを取得する

各 Azure AI Search serviceには endpoint があります。これは、サービスを識別してネットワークaccessを提供する一意の URL です。 後のセクションでは、プログラムでsearch serviceに接続するために、このエンドポイントを指定します。

エンドポイントを取得するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[ 概要] を選択します。

  3. エンドポイントを書き留めておくと、https://my-service.search.windows.NET のようになります。

インデックスから始める

このクイック スタートでは、セマンティック構成を含むように既存のインデックスを変更します。 Azure portal ウィザードを使用して数分で作成できる hotels-sample インデックスをお勧めします。

別のインデックスを使用するには、サンプル コード全体で、インデックス名、セマンティック構成のフィールド名、クエリ ステートメントのフィールド名を置き換えます。 インデックスには、 と として属性付けされた説明テキスト フィールドが含まれている必要があります。

セマンティック ランク付け前に hotels-sample インデックスを確認してクエリを実行するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[検索の管理] [インデックス] を選択します。

  3. [hotels-sample] を選択してください。

  4. [ セマンティック構成 ] を選択して、既存の構成を表示します。 ウィザードの作成フロー中にセマンティック ランク付けを有効にした場合は、既定の構成が必要です。

    Azure ポータルにおける既定のセマンティック構成のスクリーンショット

  5. 検索エクスプローラーを選択し、表示JSON ビューを選択します。

  6. 次の JSON をクエリ エディターに貼り付けます。

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. [検索] を選んでクエリを実行します。

    応答は、次の例のようになります。 これは、BM25 によってランク付けされたフルテキスト クエリであるため、クエリの全体的な意味ではなく、個々のクエリ用語と言語バリアントで結果が一致します。 たとえば、 は に一致し、 と はフレーズとしてではなく、個別に一致します。

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    ヒント

    このクエリは、セマンティック ランク付けが適用される前の応答の外観を示します。 セマンティック構成を構成したら、 と を追加して、セマンティック ランク付けによって同じクエリのランクが異なる方法を確認します。

環境をセットアップする

  1. Git を使用してサンプル リポジトリを複製します。

    git clone https://github.com/Azure-Samples/azure-search-python-samples

  2. クイック スタート フォルダーに移動し、Visual Studio Code で開きます。

    cd azure-search-python-samples/Quickstart-Semantic-Ranking
code .

  3. で、のプレースホルダー値を Get エンドポイントで取得した URL に置き換えます。

  4. の名前を に変更します。

    mv sample.env .env

  5. を開きます。

  6. Ctrl + Shift + P キーを押し、[Notebook: Select Notebook Kernel]\(ノートブック カーネルの選択\) を選択し、画面の指示に従って仮想環境を作成します。 依存関係用にrequirements.txtを選択します。

    完了すると、project ディレクトリに .venv フォルダーが表示されます。

  7. Microsoft Entra IDによるキーレス認証の場合は、Azure アカウントにサインインします。 複数のサブスクリプションがある場合は、Azure AI Search serviceを含むサブスクリプションを選択します。

    az login

コードの実行

  1. セルを実行して、必要なパッケージをインストールし、環境変数を読み込みます。

  2. 残りのセルを順番に実行してセマンティック構成を追加し、インデックスにクエリを実行します。

アウトプット

セルの出力は、インデックスの名前、そのフィールド、および既存のセマンティック構成です。

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: True
Field: HotelName, Type: Edm.String, Searchable: True
Field: Description, Type: Edm.String, Searchable: True
Field: Description_fr, Type: Edm.String, Searchable: True
Field: Category, Type: Edm.String, Searchable: True
Field: Tags, Type: Collection(Edm.String), Searchable: True
// Trimmed for brevity
Semantic config: hotels-sample-semantic-configuration
Title field: HotelName

セルの出力には、コードが追加されたものを含め、インデックス上のすべてのセマンティック構成が一覧表示され、その後に成功メッセージが表示されます。

Semantic configurations:
----------------------------------------
  Configuration: hotels-sample-semantic-configuration
    Title field: HotelName
    Keywords fields: Category
    Content fields: Description

  Configuration: semantic-config
    Title field: HotelName
    Keywords fields: Tags
    Content fields: Description

✅ Semantic configuration successfully added!

セルの出力は、BM25 スコアで並べ替えられた一致するすべてのドキュメントを返します。 このベースライン クエリでは、セマンティック ランク付けは使用されません。

5.360838
4
Sublime Palace Hotel
Description: Sublime Cliff Hotel is located in the heart of the
historic center of Sublime in an extremely vibrant and lively area
within short walking distance to the sites and landmarks of the city
and is surrounded by the extraordinary beauty of churches, buildings,
shops and monuments. Sublime Cliff is part of a lovingly restored
19th century resort, updated for every modern convenience.
4.691083
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

セルの出力は、セマンティック リランカー スコアで並べ替えられた一致するすべてのドキュメントを返します。

2.613231658935547
24
Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to theaters, art galleries, restaurants and
shops. Visit Seattle Art Museum by day, and then head over to
Benaroya Hall to catch the evening's concert performance.
2.271434783935547
2
Old Century Hotel
Description: The hotel is situated in a nineteenth century plaza,
which has been expanded and renovated to the highest architectural
standards to create a modern, functional and first-class hotel in
which art and unique historical elements coexist with the most
modern comforts. The hotel also regularly hosts events like wine
tastings, beer dinners, and live music.
// Trimmed for brevity

セルの出力により、検索フィールドとともにヒットを強調するキャプション要素が追加されます。 キャプションは、結果の中で最も関連性の高い一節です。 インデックスに大きなテキストが含まれている場合、キャプションは最も興味深い文を抽出するのに役立ちます。

2.613231658935547
24
Uptown Chic Hotel
Description: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to theaters, art galleries, restaurants and
shops. Visit Seattle Art Museum by day, and then head over to
Benaroya Hall to catch the evening's concert performance.
Caption: Chic hotel near the city. High-rise hotel in downtown,
within walking distance to<em> theaters, </em>art galleries,
restaurants and shops. Visit<em> Seattle Art Museum </em>by day, and
then head over to<em> Benaroya Hall </em>to catch the evening's
concert performance.
// Trimmed for brevity

セルの出力には、質問に最も一致する結果の 1 つから取得されたセマンティック回答と、キャプション付きの検索結果が含まれます。

Semantic Answer: Nature is Home on the beach. Explore the shore by
day, and then come home to our shared living space to relax around a
stone fireplace, sip something warm, and explore the<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

コードを理解する

注

このセクションのコード スニペットは、読みやすくするために変更されている可能性があります。 完全な作業例については、ソース コードを参照してください。

コードを実行したので、主な手順を分解しましょう。

  1. 構成と認証
  2. セマンティック構成でインデックスを更新する
  3. インデックスのクエリを実行する

構成と認証

セルは環境変数を読み込み、認証用のオブジェクトを作成します。

from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential
from azure.identity import get_bearer_token_provider
import os

load_dotenv(override=True)

search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = os.getenv(
    "AZURE_SEARCH_INDEX", "hotels-sample"
)

重要なポイント:

  • DefaultAzureCredential では、Microsoft Entra IDを使用したキーレス認証が提供されます。 az login からのAzure CLI資格情報など、複数の資格情報の種類を連結します。
  • 環境変数は、を使用して ファイルから読み込まれます。

セマンティック構成でインデックスを更新する

セルは、既存の インデックスにセマンティック構成を追加します。 この操作では、検索ドキュメントは削除されません。構成が追加された後もインデックスは引き続き動作します。

from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

new_semantic_config = SemanticConfiguration(
    name="semantic-config",
    prioritized_fields=SemanticPrioritizedFields(
        title_field=SemanticField(field_name="HotelName"),
        keywords_fields=[
            SemanticField(field_name="Tags")
        ],
        content_fields=[
            SemanticField(field_name="Description")
        ]
    )
)

if existing_index.semantic_search is None:
    existing_index.semantic_search = SemanticSearch(
        configurations=[new_semantic_config]
    )
else:
    existing_index.semantic_search.configurations.append(
        new_semantic_config
    )

result = index_client.create_or_update_index(existing_index)

重要なポイント:

  • セマンティック構成では、セマンティック ランク付けに使用されるフィールドを指定します。 は、ドキュメントタイトルを設定 メインコンテンツを設定し、 キーワードまたはタグフィールドを設定します。
  • とそれに関連付けられている モデルを使用して構成を作成し、既存のインデックスに追加します。
  • create_or_update_index は、インデックスを再構築したりドキュメントを削除したりせずに、更新されたスキーマをsearch serviceにプッシュします。

インデックスのクエリを実行する

クエリ セルは、4 つのクエリを順番に実行します。ベースライン キーワード検索の後に、3 つのセマンティック ランク付けバリエーションが続き、機能が向上します。

用語クエリ (ベースライン)

セルは、BM25 スコアリングを使用してキーワード検索を実行します。 このベースライン クエリはセマンティック ランク付けを使用せず、比較ポイントとして機能します。

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='simple',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    include_total_count=True
)

重要なポイント:

  • は、BM25 スコアリングを使用したキーワード検索を指定します。
  • 結果の「 」は、BM25 関連性スコアを示します。

セマンティック クエリ (キャプションなし、回答なし)

[ ] セルには、セマンティック ランク付けを呼び出すための最小要件が表示されます。

from azure.search.documents import SearchClient

search_client = SearchClient(
    endpoint=search_endpoint,
    index_name=index_name,
    credential=credential
)

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelId,HotelName,Description',
    query_caption='extractive'
)

重要なポイント:

  • を使用すると、クエリのセマンティック ランク付けが可能になります。
  • は、使用するセマンティック構成を指定します。
  • 結果内の「 」は意味的な関連性を示し、数値が高いほど関連性が高いです。

キャプションを含むセマンティック クエリ

[ ] セルにはキャプションが追加され、各結果から最も関連性の高い箇所が抽出され、重要な用語と語句にヒット強調表示が適用されます。

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="walking distance to live music",
    select='HotelName,HotelId,Description',
    query_caption='extractive'
)

for result in results:
    captions = result["@search.captions"]
    if captions:
        caption = captions[0]
        if caption.highlights:
            print(f"Caption: {caption.highlights}\n")

重要なポイント:

  • コンテンツフィールドから抽出されたキャプションを有効にします。
  • キャプションは最も関連性の高い箇所を見つけ出し、重要な用語に<em>タグを追加します。

回答を含むセマンティック クエリ

[ ] セルにセマンティック回答が追加されます。 セマンティック回答は、クエリが質問として表現される場合に最適であるため、このクエリでは質問が検索テキストとして使用されます。 答えは、チャット完了モデルから構成された応答ではなく、インデックスから抽出された逐語的な一節です。

回答を返すには、クエリとインデックス付きコンテンツを厳密に揃える必要があります。 信頼度しきい値を満たす候補がない場合、応答には回答は含まれません。 この例では、構文を確認できるように、結果を生成するために既知の質問を使用します。 回答がシナリオに役立たない場合は、コードから を省略します。 構成された回答については、 RAG パターン または エージェント検索を検討してください。

results = search_client.search(
    query_type='semantic',
    semantic_configuration_name='semantic-config',
    search_text="what's a good hotel for people who "
                "like to read",
    select='HotelName,Description,Category',
    query_caption='extractive',
    query_answer="extractive",
)

semantic_answers = results.get_answers()
for answer in semantic_answers:
    if answer.highlights:
        print(f"Semantic Answer: {answer.highlights}")
    else:
        print(f"Semantic Answer: {answer.text}")
    print(f"Semantic Answer Score: {answer.score}\n")

重要なポイント:

  • では、質問に似たクエリに対する抽出的な回答が可能になります。
  • 回答は、生成されたテキストではなく、インデックスから抽出された逐語的なコンテンツです。
  • は、検索結果とは別に回答オブジェクトを取得します。

このクイック スタートでは、JavaScript 用の Azure AI 検索 クライアント ライブラリ (TypeScript と互換性があります) を使用して、semantic ranking を既存の検索インデックスに追加し、インデックスにクエリを実行します。

セマンティック ランク付けは、コンピューターの読解力を使用して検索結果を再スコア付けし、最も意味的に関連性の高い一致を一覧の先頭に昇格させるクエリ側の機能です。 再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。 セマンティック ランク付けは、情報テキストまたは説明テキストに最も効果的です。

ヒント

すぐにget startedしたいですか? GitHubにsource コードをダウンロードします。

前提条件

  • アクティブなサブスクリプションを持つAzure アカウント。 アカウントを無料で作成。

  • Azure AI Search サービスsemantic ranker が有効になっている。

  • およびとして属性付けされた説明テキスト フィールドを含むインデックス。 このクイック スタートでは、 hotels-sample インデックスを前提としています。

  • コンパイル済みコードを実行するには、20 LTS 以降をNode.js します。

  • TypeScript で TypeScript を JavaScript にコンパイルします。

  • Visual Studio Code。

  • Git を使ってサンプルリポジトリを複製します。

  • Microsoft Entra IDを使用したキーレス認証のAzure CLI。

アクセスを構成する

開始する前に、Azure AI 検索でコンテンツと操作をaccessするアクセス許可があることを確認してください。 このクイック スタートでは、認証にMicrosoft Entra IDを使用し、承認にロールベースのaccessを使用します。 ロールを割り当てるには、Owner または User Access Administrator である必要があります。 ロールの使用が困難な場合は、代わりにキー ベースの認証を使用してください。

推奨されるロールベースのaccessを構成するには:

  1. 検索サービスのロールベースアクセスを有効にすることができます。

  2. ユーザー アカウントに次のロールを割り当てます 。

    • Search Service 貢献者

    • 検索インデックス データ閲覧者

注

インデックスを作成して読み込む他のクイック スタートとは異なり、このクイック スタートでは、データが既に含まれている既存のインデックスを想定しているため、 検索インデックス データ共同作成者 ロールは必要ありません。

エンドポイントを取得する

各 Azure AI Search serviceには endpoint があります。これは、サービスを識別してネットワークaccessを提供する一意の URL です。 後のセクションでは、プログラムでsearch serviceに接続するために、このエンドポイントを指定します。

エンドポイントを取得するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[ 概要] を選択します。

  3. エンドポイントを書き留めておくと、https://my-service.search.windows.NET のようになります。

インデックスから始める

このクイック スタートでは、セマンティック構成を含むように既存のインデックスを変更します。 Azure portal ウィザードを使用して数分で作成できる hotels-sample インデックスをお勧めします。

別のインデックスを使用するには、サンプル コード全体で、インデックス名、セマンティック構成のフィールド名、クエリ ステートメントのフィールド名を置き換えます。 インデックスには、 と として属性付けされた説明テキスト フィールドが含まれている必要があります。

セマンティック ランク付け前に hotels-sample インデックスを確認してクエリを実行するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[検索の管理] [インデックス] を選択します。

  3. [hotels-sample] を選択してください。

  4. [ セマンティック構成 ] を選択して、既存の構成を表示します。 ウィザードの作成フロー中にセマンティック ランク付けを有効にした場合は、既定の構成が必要です。

    Azure ポータルにおける既定のセマンティック構成のスクリーンショット

  5. 検索エクスプローラーを選択し、表示JSON ビューを選択します。

  6. 次の JSON をクエリ エディターに貼り付けます。

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. [検索] を選んでクエリを実行します。

    応答は、次の例のようになります。 これは、BM25 によってランク付けされたフルテキスト クエリであるため、クエリの全体的な意味ではなく、個々のクエリ用語と言語バリアントで結果が一致します。 たとえば、 は に一致し、 と はフレーズとしてではなく、個別に一致します。

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    ヒント

    このクエリは、セマンティック ランク付けが適用される前の応答の外観を示します。 セマンティック構成を構成したら、 と を追加して、セマンティック ランク付けによって同じクエリのランクが異なる方法を確認します。

環境をセットアップする

  1. Git を使用してサンプル リポジトリを複製します。

    git clone https://github.com/Azure-Samples/azure-search-javascript-samples

  2. クイック スタート フォルダーに移動し、Visual Studio Code で開きます。

    cd azure-search-javascript-samples/quickstart-semantic-ranking-ts
code .

  3. で、のプレースホルダー値を Get エンドポイントで取得した URL に置き換えます。

  4. の名前を に変更します。

    mv sample.env .env

  5. 依存関係をインストールします。

    npm install

    インストールが完了すると、project ディレクトリに node_modules フォルダーが表示されます。

  6. TypeScript ファイルをビルドします。

    npm run build

  7. Microsoft Entra IDによるキーレス認証の場合は、Azure アカウントにサインインします。 複数のサブスクリプションがある場合は、Azure AI Search serviceを含むサブスクリプションを選択します。

    az login

コードの実行

  1. 既存のインデックス設定を取得します。

    node -r dotenv/config dist/getIndexSettings.js

  2. セマンティック構成でインデックスを更新します。

    node -r dotenv/config dist/updateIndexSettings.js

  3. セマンティック クエリを実行します。

    node -r dotenv/config dist/semanticQuery.js

  4. キャプションを使用してセマンティック クエリを実行します。

    node -r dotenv/config dist/semanticQueryReturnCaptions.js

  5. 回答を含むセマンティック クエリを実行します。

    node -r dotenv/config dist/semanticAnswer.js

    注

    これらのコマンドは、以前に TypeScript から JavaScript にトランスパイルした際に使用したため、フォルダー内のファイルを実行します。

アウトプット

スクリプトは、インデックス名、フィールド数、型と検索可能な状態を持つフィールドの詳細、および既存のセマンティック構成を返します。

Index name: hotels-sample
Number of fields: 23
Field: HotelId, Type: Edm.String, Searchable: true
Field: HotelName, Type: Edm.String, Searchable: true
Field: Description, Type: Edm.String, Searchable: true
// Trimmed for brevity
Semantic ranking configurations: 1
Configuration name: hotels-sample-semantic-configuration
Title field: undefined

スクリプトは、追加したセマンティック構成を含むすべてのセマンティック構成を返します。

Semantic configurations:
----------------------------------------
Configuration name: hotels-sample-semantic-configuration
Title field: undefined
Keywords fields:
Content fields: AzureSearch_DocumentKey
----------------------------------------
Configuration name: semantic-config
Title field: HotelName
Keywords fields: Tags
Content fields: Description
----------------------------------------
Semantic configuration updated successfully.

スクリプトは、リランカー スコアで並べ替えられた結果を返します。

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelId: 24
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown,
  within walking distance to theaters, art galleries, restaurants and
  shops. Visit Seattle Art Museum by day, and then head over to
  Benaroya Hall to catch the evening's concert performance.

Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelId: 2
  HotelName: Old Century Hotel
  Description: The hotel is situated in a nineteenth century plaza...
  // Trimmed for brevity

スクリプトは、ヒットを強調表示した抽出形式のキャプションを返します。 キャプションは、結果の中で最も関連性の高い一節です。

Search result #1:
  Re-ranker Score: 2.613231658935547
  HotelName: Uptown Chic Hotel
  Description: Chic hotel near the city. High-rise hotel in downtown,
  within walking distance to theaters, art galleries, restaurants and
  shops. Visit Seattle Art Museum by day, and then head over to
  Benaroya Hall to catch the evening's concert performance.

  Caption with highlights: Chic hotel near the city. High-rise hotel
  in downtown, within walking distance to<em> theaters, </em>art
  galleries, restaurants and shops. Visit<em> Seattle Art Museum
  </em>by day, and then head over to<em> Benaroya Hall </em>to catch
  the evening's concert performance.
------------------------------------------------------------
Search result #2:
  Re-ranker Score: 2.271434783935547
  HotelName: Old Century Hotel
  // Trimmed for brevity

スクリプトは、質問に最も一致する結果から取得されたセマンティック回答 (逐語的な内容) を返します。

Semantic answer result #1:
Semantic Answer: Nature is Home on the beach. Explore the shore by
day, and then come home to our shared living space to relax around
a stone fireplace, sip something warm, and explore the<em> library
</em>by night. Save up to 30 percent. Valid Now through the end of
the year. Restrictions and blackouts may apply.
Semantic Answer Score: 0.9829999804496765

Search Results:

Search result #1:
2.124817371368408
Stay-Kay City Hotel
This classic hotel is fully-refurbished and ideally located on the
main commercial artery of the city in the heart of New York...
Caption: This classic hotel is<em> fully-refurbished </em>and
ideally located on the main commercial artery of the city...
// Trimmed for brevity

コードを理解する

注

このセクションのコード スニペットは、読みやすくするために変更されている可能性があります。 完全な作業例については、ソース コードを参照してください。

コードを実行したので、主な手順を分解しましょう。

  1. 構成と認証
  2. セマンティック構成でインデックスを更新する
  3. インデックスのクエリを実行する

構成と認証

ファイルは環境変数を読み込み、認証用のを作成し、タイプ セーフ用の インターフェイスを定義します。

import { DefaultAzureCredential }
    from "@azure/identity";

export const searchEndpoint =
    process.env.AZURE_SEARCH_ENDPOINT
    || "PUT-YOUR-SEARCH-SERVICE-ENDPOINT-HERE";
export const indexName =
    process.env.AZURE_SEARCH_INDEX_NAME
    || "hotels-sample";
export const semanticConfigurationName =
    process.env.SEMANTIC_CONFIGURATION_NAME
    || "semantic-config";

export const credential = new DefaultAzureCredential();

export interface HotelDocument {
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
}

重要なポイント:

  • DefaultAzureCredential では、Microsoft Entra IDを使用したキーレス認証が提供されます。 az login からのAzure CLI資格情報など、複数の資格情報の種類を連結します。
  • HotelDocument インターフェースは、検索結果に対するコンパイル時の型チェックを提供し、ドキュメントフィールドへの型安全なアクセスを保証します。
  • 環境変数は、を使用して ファイルから読み込まれます。

セマンティック構成でインデックスを更新する

ファイルは、既存の インデックスにセマンティック構成を追加します。 この操作では、検索ドキュメントは削除されません。構成が追加された後もインデックスは引き続き動作します。 TypeScript 型の注釈により、構成が予想されるスキーマと一致することが保証されます。

import {
    SearchIndexClient,
    SemanticConfiguration,
    SemanticPrioritizedFields,
    SemanticField
} from "@azure/search-documents";
import {
    searchEndpoint, indexName,
    credential, semanticConfigurationName
} from "./config.js";

const indexClient = new SearchIndexClient(
    searchEndpoint, credential
);
const existingIndex =
    await indexClient.getIndex(indexName);

const fields: SemanticPrioritizedFields = {
    titleField: { name: "HotelName" },
    keywordsFields: [
        { name: "Tags" }
    ] as SemanticField[],
    contentFields: [
        { name: "Description" }
    ] as SemanticField[]
};

const newSemanticConfiguration:
    SemanticConfiguration = {
    name: semanticConfigurationName,
    prioritizedFields: fields
};

if (existingIndex.semanticSearch
    && existingIndex.semanticSearch.configurations) {
    existingIndex.semanticSearch.configurations
        .push(newSemanticConfiguration);
} else {
    existingIndex.semanticSearch = {
        configurations: [newSemanticConfiguration]
    };
}

await indexClient.createOrUpdateIndex(existingIndex);

重要なポイント:

  • 、、などの TypeScript 型は、構成構造のコンパイル時の検証を提供します。
  • は、ドキュメントタイトルを設定 メインコンテンツを設定し、 キーワードまたはタグフィールドを設定します。
  • createOrUpdateIndex は、インデックスを再構築したりドキュメントを削除したりせずに、更新されたスキーマをsearch serviceにプッシュします。

インデックスのクエリを実行する

クエリ スクリプトは、基本的なセマンティック検索からキャプションと回答を含むセマンティックランク付けに進む 3 つのクエリを順番に実行します。

セマンティック クエリ (キャプションなし、回答なし)

スクリプトは、タイプ セーフな結果でセマンティック ランク付けを呼び出すための最小要件を示しています。

import { SearchClient }
    from "@azure/search-documents";
import {
    HotelDocument, credential,
    searchEndpoint, indexName,
    semanticConfigurationName
} from "./config.js";

const searchClient =
    new SearchClient<HotelDocument>(
        searchEndpoint, indexName, credential
    );

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

重要なポイント:

  • SearchClient<HotelDocument> は、結果内のドキュメントフィールドに対してタイプセーフなアクセスを提供し、select および result.document におけるフィールド名のオートコンプリートを提供します。
  • を使用すると、クエリのセマンティック ランク付けが可能になります。
  • は、使用するセマンティック構成を指定します。

キャプションを含むセマンティック クエリ

スクリプトは、各結果から最も関連性の高い箇所を抽出するキャプションを追加し、重要な用語と語句にヒット強調表示を適用します。

const results = await searchClient.search(
    "walking distance to live music",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive",
                highlight: true
            }
        },
        select: [
            "HotelId", "HotelName", "Description"
        ]
    }
);

for await (const result of results.results) {
    const captions = result.captions;
    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(
                `Caption: ${caption.highlights}`
            );
        }
    }
}

重要なポイント:

  • コンテンツフィールドから抽出されたキャプションを有効にします。
  • キャプションは最も関連性の高い箇所を見つけ出し、重要な用語に<em>タグを追加します。

回答を含むセマンティック クエリ

スクリプトはセマンティック回答を追加します。 クエリが質問として表現されるとセマンティック回答が最適に機能するため、検索テキストとして質問が使用されます。 答えは、チャット完了モデルから構成された応答ではなく、インデックスから抽出された逐語的な一節です。

回答を返すには、クエリとインデックス付きコンテンツを厳密に揃える必要があります。 信頼度しきい値を満たす候補がない場合、応答には回答は含まれません。 この例では、構文を確認できるように、結果を生成するために既知の質問を使用します。 回答がシナリオに役立たない場合は、コードから を省略します。 構成された回答については、 RAG パターン または エージェント検索を検討してください。

const results = await searchClient.search(
    "What's a good hotel for people who "
    + "like to read",
    {
        queryType: "semantic",
        semanticSearchOptions: {
            configurationName:
                semanticConfigurationName,
            captions: {
                captionType: "extractive"
            },
            answers: {
                answerType: "extractive"
            }
        },
        select: [
            "HotelName", "Description", "Category"
        ]
    }
);

const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    if (answer.highlights) {
        console.log(
            `Semantic Answer: ${answer.highlights}`
        );
    } else {
        console.log(
            `Semantic Answer: ${answer.text}`
        );
    }
    console.log(
        `Semantic Answer Score: ${answer.score}`
    );
}

重要なポイント:

  • では、質問に似たクエリに対する抽出的な回答が可能になります。
  • 回答は、生成されたテキストではなく、インデックスから抽出された逐語的なコンテンツです。
  • は、検索結果とは別に回答オブジェクトを取得します。

このクイック スタートでは、Azure AI 検索 REST API を使用して、既存の検索インデックスに semantic ranking を追加し、インデックスのクエリを実行します。

セマンティック ランク付けは、コンピューターの読解力を使用して検索結果を再スコア付けし、最も意味的に関連性の高い一致を一覧の先頭に昇格させるクエリ側の機能です。 再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。 セマンティック ランク付けは、情報テキストまたは説明テキストに最も効果的です。

ヒント

すぐにget startedしたいですか? GitHubにsource コードをダウンロードします。

前提条件

アクセスを構成する

開始する前に、Azure AI 検索でコンテンツと操作をaccessするアクセス許可があることを確認してください。 このクイック スタートでは、認証にMicrosoft Entra IDを使用し、承認にロールベースのaccessを使用します。 ロールを割り当てるには、Owner または User Access Administrator である必要があります。 ロールの使用が困難な場合は、代わりにキー ベースの認証を使用してください。

推奨されるロールベースのaccessを構成するには:

  1. 検索サービスのロールベースアクセスを有効にすることができます。

  2. ユーザー アカウントに次のロールを割り当てます 。

    • Search Service 貢献者

    • 検索インデックス データ閲覧者

注

インデックスを作成して読み込む他のクイック スタートとは異なり、このクイック スタートでは、データが既に含まれている既存のインデックスを想定しているため、 検索インデックス データ共同作成者 ロールは必要ありません。

エンドポイントを取得する

各 Azure AI Search serviceには endpoint があります。これは、サービスを識別してネットワークaccessを提供する一意の URL です。 後のセクションでは、プログラムでsearch serviceに接続するために、このエンドポイントを指定します。

エンドポイントを取得するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[ 概要] を選択します。

  3. エンドポイントを書き留めておくと、https://my-service.search.windows.NET のようになります。

インデックスから始める

このクイック スタートでは、セマンティック構成を含むように既存のインデックスを変更します。 Azure portal ウィザードを使用して数分で作成できる hotels-sample インデックスをお勧めします。

別のインデックスを使用するには、サンプル コード全体で、インデックス名、セマンティック構成のフィールド名、クエリ ステートメントのフィールド名を置き換えます。 インデックスには、 と として属性付けされた説明テキスト フィールドが含まれている必要があります。

セマンティック ランク付け前に hotels-sample インデックスを確認してクエリを実行するには:

  1. Azure portal にサインインし、検索サービスを選択します。

  2. 左側のウィンドウで、[検索の管理] [インデックス] を選択します。

  3. [hotels-sample] を選択してください。

  4. [ セマンティック構成 ] を選択して、既存の構成を表示します。 ウィザードの作成フロー中にセマンティック ランク付けを有効にした場合は、既定の構成が必要です。

    Azure ポータルにおける既定のセマンティック構成のスクリーンショット

  5. 検索エクスプローラーを選択し、表示JSON ビューを選択します。

  6. 次の JSON をクエリ エディターに貼り付けます。

    {
  "search": "walking distance to live music",
  "select": "HotelId, HotelName, Description",
  "count": true
}

  7. [検索] を選んでクエリを実行します。

    応答は、次の例のようになります。 これは、BM25 によってランク付けされたフルテキスト クエリであるため、クエリの全体的な意味ではなく、個々のクエリ用語と言語バリアントで結果が一致します。 たとえば、 は に一致し、 と はフレーズとしてではなく、個別に一致します。

    "@odata.count": 30,
"value": [
  {
    "@search.score": 5.004435,
    "HotelId": "2",
    "HotelName": "Old Century Hotel",
    "Description": "The hotel is situated in a nineteenth century plaza, which has been expanded and renovated to the highest architectural standards to create a modern, functional and first-class hotel in which art and unique historical elements coexist with the most modern comforts. The hotel also regularly hosts events like wine tastings, beer dinners, and live music."
  },
  {
    "@search.score": 4.555706,
    "HotelId": "24",
    "HotelName": "Uptown Chic Hotel",
    "Description": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance."
  },
  {
    "@search.score": 3.5625167,
    "HotelId": "4",
    "HotelName": "Sublime Palace Hotel",
    "Description": "Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within short walking distance to the sites and landmarks of the city and is surrounded by the extraordinary beauty of churches, buildings, shops and monuments. Sublime Cliff is part of a lovingly restored 19th century resort, updated for every modern convenience."
  },
  ... // Trimmed for brevity
]

    ヒント

    このクエリは、セマンティック ランク付けが適用される前の応答の外観を示します。 セマンティック構成を構成したら、 と を追加して、セマンティック ランク付けによって同じクエリのランクが異なる方法を確認します。

環境をセットアップする

  1. Git を使用してサンプル リポジトリを複製します。

    git clone https://github.com/Azure-Samples/azure-search-rest-samples

  2. クイック スタート フォルダーに移動し、Visual Studio Code で開きます。

    cd azure-search-rest-samples/Quickstart-semantic-ranking
code .

  3. で、のプレースホルダー値を Get エンドポイントで取得した URL に置き換えます。

  4. に対して前の手順を繰り返します。

  5. Microsoft Entra IDによるキーレス認証の場合は、Azure アカウントにサインインします。 複数のサブスクリプションがある場合は、Azure AI Search serviceを含むサブスクリプションを選択します。

    az login

  6. Microsoft Entra IDを使用したキーレス認証の場合は、access トークンを生成します。

    az account get-access-token --scope https://search.azure.com/.default --query accessToken --output tsv

  7. 両方のファイルでプレースホルダーの値を、前の手順で取得したトークンに置き換えます。

コードの実行

  1. を開きます。

  2. 接続を確認するには、最初の GET 要求で [要求の 送信] を選択します。

    隣接するウィンドウに応答が表示されます。 既存のインデックスがある場合は、名前で一覧表示されます。 HTTP コードが 場合は、続行する準備が整います。

  3. 要求を送信して、セマンティック構成をインデックスに追加します。

    エラーが発生した場合、インデックス スキーマはサンプルとは異なります。 要求を送信し、応答 JSON をコピーし、ソース コードから JSON に セクションを追加し、PUT 要求本文をマージされたスキーマに置き換えます。

  4. に切り替えて、要求を順番に送信します。ベースライン比較のための単純なクエリ、ランク付け、キャプション、回答を含むセマンティック クエリです。

アウトプット

要求は、BM25 関連性でランク付けされた結果を返します。これは、 フィールドによって示されます。

{
  "@odata.count": 30,
  "value": [
    {
      "@search.score": 5.004435,
      "HotelId": "2",
      "HotelName": "Old Century Hotel",
      "Description": "The hotel is situated in a nineteenth century plaza..."
    },
    // Trimmed for brevity
  ]
}

要求によって項目が追加されます。 単純なクエリから順序が変わります。

{
  "@odata.count": 30,
  "@search.answers": [],
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel",
      "Description": "Chic hotel near the city. High-rise hotel in downtown..."
    },
    // Trimmed for brevity
  ]
}

抽出されたテキストと強調表示を追加するリクエストです。

{
  "value": [
    {
      "@search.score": 4.555706,
      "@search.rerankerScore": 2.613231658935547,
      "@search.captions": [
        {
          "text": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to theaters, art galleries, restaurants and shops...",
          "highlights": "Chic hotel near the city. High-rise hotel in downtown, within walking distance to<em> theaters, </em>art galleries, restaurants and shops..."
        }
      ],
      "HotelId": "24",
      "HotelName": "Uptown Chic Hotel"
    },
    // Trimmed for brevity
  ]
}

クエリが質問として表現されたとき、要求は抽出形式の回答を返します。

{
  "@odata.count": 46,
  "@search.answers": [
    {
      "key": "38",
      "text": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the library by night...",
      "highlights": "Nature is Home on the beach. Explore the shore by day, and then come home to our shared living space to relax around a stone fireplace, sip something warm, and explore the<em> library </em>by night...",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.060124,
      "@search.rerankerScore": 2.124817371368408,
      "@search.captions": [
        {
          "text": "This classic hotel is fully-refurbished and ideally located on the main commercial artery of the city...",
          "highlights": "This classic hotel is<em> fully-refurbished </em>and ideally located on the main commercial artery of the city..."
        }
      ],
      "HotelId": "1",
      "HotelName": "Stay-Kay City Hotel"
    },
    // Trimmed for brevity
  ]
}

コードを理解する

注

このセクションのコード スニペットは、読みやすくするために変更されている可能性があります。 完全な作業例については、ソース コードを参照してください。

コードを実行したので、主な手順を分解しましょう。

  1. 構成と認証
  2. セマンティック構成でインデックスを更新する
  3. インデックスのクエリを実行する

構成と認証

どちらの ファイルも、すべての要求で再利用するために、先頭に変数を定義します。

@searchUrl = PUT-YOUR-SEARCH-SERVICE-URL-HERE
@personalAccessToken = PUT-YOUR-PERSONAL-ACCESS-TOKEN-HERE
@api-version = 2025-09-01

重要なポイント:

  • @searchUrl は、search serviceのエンドポイントです。
  • @personalAccessToken は、Azure CLIから取得したMicrosoft Entra ID トークンです。 これにより、API キーがキーレス認証に置き換えられます。
  • 認証用のすべてのリクエストヘッダーに含まれています。

セマンティック構成でインデックスを更新する

の要求は、新しい セクションと共に完全なインデックス スキーマを送信します。 REST API には更新操作の完全なスキーマが必要であるため、セマンティック構成のみを送信することはできません。

重要な追加は、 セクションです。

"semantic": {
    "configurations": [
        {
            "name": "semantic-config",
            "rankingOrder":
                "BoostedRerankerScore",
            "prioritizedFields": {
                "titleField": {
                    "fieldName": "HotelName"
                },
                "prioritizedContentFields": [
                    {
                        "fieldName": "Description"
                    }
                ],
                "prioritizedKeywordsFields": [
                    {
                        "fieldName": "Tags"
                    }
                ]
            }
        }
    ]
}

重要なポイント:

  • は、セマンティック評価用のドキュメント タイトルを含むフィールドを識別します。
  • は、メイン コンテンツ フィールドを識別します。 セマンティック ランカーは、関連性をスコア付けするときに最初にこれらを評価します。
  • は、追加のコンテキストのキーワードまたはタグ フィールドを識別します。
  • BM25スコアとセマンティックリランカースコアが結合されます。
  • REST API には、PUT 操作用の完全なスキーマが必要です。 セクションのみが新しく、他のすべてのフィールドは変更されません。

インデックスのクエリを実行する

の要求は、単純なキーワード検索からキャプションと回答を含むセマンティック ランク付けに進みます。 すべてのクエリは、 Documents - Search Post (REST API) への POST 要求です。

単純なクエリ

要求は、セマンティック ランク付けを使用しない単純なキーワード検索です。 これは、セマンティック再ランク付けと比較せずに結果を比較するためのベースラインとして機能します。

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "simple"
}

重要なポイント:

  • このシステムでは、既定の BM25 ランク付けアルゴリズムが使用されます。
  • 結果はキーワードの関連性 () によってのみランク付けされます。

セマンティック クエリ (キャプションなし、回答なし)

要求によってセマンティック ランク付けが追加されます。 次の JSON は、セマンティック ランク付けを呼び出すための最小要件を示しています。

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config"
}

重要なポイント:

  • を使用すると、クエリのセマンティック ランク付けが可能になります。
  • は、使用するセマンティック構成を指定します。

キャプションを含むセマンティック クエリ

要求では、各結果から最も関連性の高い箇所を抽出するためのキャプションが追加され、重要な用語と語句にヒット強調表示が適用されます。

{
    "search":
        "walking distance to live music",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true"
}

重要なポイント:

  • では、重要な用語に関する タグを含む抽出キャプションが有効になります。
  • キャプションは、各結果の 配列に表示されます。

回答を含むセマンティック クエリ

要求によってセマンティック回答が追加されます。 クエリが質問として表現されるとセマンティック回答が最適に機能するため、検索テキストとして質問が使用されます。 答えは、チャット完了モデルから構成された応答ではなく、インデックスから抽出された逐語的な一節です。

回答を返すには、クエリとインデックス付きコンテンツを厳密に揃える必要があります。 信頼度しきい値を満たす候補がない場合、応答には回答は含まれません。 この例では、構文を確認できるように、結果を生成するために既知の質問を使用します。 回答がシナリオに役立たない場合は、要求から パラメーターを省略します。 構成された回答については、 RAG パターン または エージェント検索を検討してください。

{
    "search":
        "what's a good hotel for people who like to read",
    "select":
        "HotelId, HotelName, Description",
    "count": true,
    "queryType": "semantic",
    "semanticConfiguration": "semantic-config",
    "captions": "extractive|highlight-true",
    "answers": "extractive"
}

重要なポイント:

  • では、質問に似たクエリに対する抽出的な回答が可能になります。
  • 回答は、個々の結果とは別に、最上位 配列に表示されます。
  • 回答は、生成されたテキストではなく、インデックスから抽出された逐語的なコンテンツです。

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

自分のサブスクリプションで作業するときは、不要になったリソースを削除してprojectを完了することをお勧めします。 リソースを動作させたままだと、お金がかかることがあります。

Azure portalで、左側のウィンドウで [すべてのリソース] または [リソース グループ を選択して、リソースを検索および管理します。 リソースを個別に削除することも、リソース グループを削除してすべてのリソースを一度に削除することもできます。

関連コンテンツ

  • Last updated on