クイックスタート: セマンティックランキング - Azure AI Search

このクイックスタートでは、セマンティックランク付けを既存のインデックスに追加する方法について説明します。 hotels-sample-index または独自のものを使用できます。

Azure AI 検索のセマンティックランク付けは、Microsoft の機械読解を使用して検索結果を再スコアリングして、セマンティック関連性が最も高い一致を一覧の最上位に昇格させる、クエリ側の機能です。コンテンツとクエリによっては、セマンティックランク付けによって、開発者の労力を最小限に抑えながら検索の関連性を大幅に向上させることができます。

再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。セマンティックランク付けは、情報的または説明的なテキストに最も効果的です。

このクイックスタートでは、次の方法について説明します。

検索インデックスにセマンティック構成を追加する
セマンティックパラメーターをクエリに追加する

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
セマンティックランカーが有効になっている、Basic レベル以上の Azure AI Search サービス。
説明的または詳細なテキストフィールドを持つ新規または既存のインデックス。インデックスで取得可能と見なされます。このクイックスタートでは、 hotels-sample-index を前提としています。

アクセスを構成する

ロールの割り当てで API キーまたは Microsoft Entra ID を使用して、Azure AI Search サービスに接続できます。キーの方が簡単に使い始めることができますが、安全性が高いのはロールの方です。

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

Azure portal にサインインし、検索サービスを選択します。
次に、左側のペインで [設定]>[キー] を選択します。
[API アクセス制御] で、[両方] を選択します。

このオプションでは、キーベース認証とキーレス認証の両方が有効になります。ロールを割り当てた後、この手順に戻り、[ ロールベースのアクセス制御] を選択できます。
左側のウィンドウで、[ アクセス制御 (IAM)] を選択します。
[追加>][ロール割り当ての追加] の順に選択します。
ユーザーアカウントに次のロールを割り当てます。
- Search Service サービス貢献者
- 検索インデックスデータ共同作成者

詳細については、「ロールを使用して Azure AI 検索に接続する」を参照してください。

インデックスから始める

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

Azure portal にサインインし、ご利用の検索サービスを探します。
[検索の管理>Indexes] で、hotels-sample-index を開きます。インデックスにセマンティック構成がないことを確認します。

インデックスが操作可能であることを確認するには、クエリを実行します。 検索エクスプローラーで、セマンティックランク付けが適用される前に応答を表示できるように、この検索文字列 "walking distance to live music" を入力します。

応答は、フルテキスト検索の既定の BM25 L1 ランカーによってスコア付けされた次の例のようになります。読みやすくするために、この例では "HotelName" "HotelId" フィールドと "Description" フィールドのみを選択します。

このクエリはキーワード検索です。結果には、クエリ用語 (ウォーキング、距離、ライブ、音楽) または言語バリアント (ウォーク、リビング) に関する逐語的一致が含まれます。

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime ___location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

後で、セマンティックランク付けが構成された後に、応答がどのように変化するかを確認するために、このクエリをもう一度試すことができます。

ヒント

セマンティック構成は、Azure portal で追加できます。ただし、セマンティック構成をプログラムで追加する方法については、このクイックスタートの手順に進んでください。

クライアントを設定する

このクイックスタートでは、IDE と Azure.Search.Documents クライアントライブラリを使用して、セマンティックランク付けを既存の検索インデックスに追加します。

このクイックスタートでは、Visual Studio をお勧めします。

ヒント

ソースコードをダウンロードして完成したプロジェクトから開始することも、以下の手順に従って独自のアプリケーションを作成することもできます。

ライブラリのインストール

Visual Studio を起動し、 quickstart-semantic-search.sln を開くか、コンソールアプリケーションテンプレートを使用して新しいプロジェクトを作成します。
[ツール]>[NuGet パッケージマネージャー] で、[ソリューションの NuGet パッケージの管理] を選択します。
[参照] を選択します。
Azure.Search.Documents パッケージを検索し、最新の安定バージョンを選択します。
Azure.Identity パッケージを検索し、最新の安定バージョンを選択します。
[インストール] を選択して、プロジェクトとソリューションにアセンブリを追加します。

Azure portal にサインインした場合は、Azure にサインインします。不明な場合は、Azure CLI または Azure PowerShell を使用してログインします。 az login または az connect。複数のテナントとサブスクリプションがある場合、接続方法については、「クイックスタート: キーなしで接続する」を参照してください。

インデックスを更新する

このセクションでは、セマンティック構成を含むように検索インデックスを更新します。このコードは、検索サービスからインデックス定義を取得し、セマンティック構成を追加します。

Visual Studio で BuildIndex プロジェクトを開きます。プログラムは次のコードで構成されます。

このコードでは、SearchIndexClient を使用して検索サービスのインデックスを更新します。

class BuildIndex
{
    static async Task Main(string[] args)
    {
        string searchServiceName = "PUT-YOUR-SEARCH-SERVICE-NAME-HERE";
        string indexName = "hotels-sample-index";
        string endpoint = $"https://{searchServiceName}.search.windows.net";
        var credential = new Azure.Identity.DefaultAzureCredential();

        await ListIndexesAsync(endpoint, credential);
        await UpdateIndexAsync(endpoint, credential, indexName);
    }

    // Print a list of all indexes on the search service
    // You should see hotels-sample-index in the list
    static async Task ListIndexesAsync(string endpoint, Azure.Core.TokenCredential credential)
    {
        try
        {
            var indexClient = new Azure.Search.Documents.Indexes.SearchIndexClient(
                new Uri(endpoint),
                credential
            );

            var indexes = indexClient.GetIndexesAsync();

            Console.WriteLine("Here's a list of all indexes on the search service. You should see hotels-sample-index:");
            await foreach (var index in indexes)
            {
                Console.WriteLine(index.Name);
            }
            Console.WriteLine(); // Add an empty line for readability
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error listing indexes: {ex.Message}");
        }
    }

    static async Task UpdateIndexAsync(string endpoint, Azure.Core.TokenCredential credential, string indexName)
    {
        try
        {
            var indexClient = new Azure.Search.Documents.Indexes.SearchIndexClient(
                new Uri(endpoint),
                credential
            );

            // Get the existing definition of hotels-sample-index
            var indexResponse = await indexClient.GetIndexAsync(indexName);
            var index = indexResponse.Value;

            // Add a semantic configuration
            const string semanticConfigName = "semantic-config";
            AddSemanticConfiguration(index, semanticConfigName);

            // Update the index with the new information
            var updatedIndex = await indexClient.CreateOrUpdateIndexAsync(index);
            Console.WriteLine("Index updated successfully.");

            // Print the updated index definition as JSON
            var refreshedIndexResponse = await indexClient.GetIndexAsync(indexName);
            var refreshedIndex = refreshedIndexResponse.Value;
            var jsonOptions = new JsonSerializerOptions { WriteIndented = true };
            string indexJson = JsonSerializer.Serialize(refreshedIndex, jsonOptions);
            Console.WriteLine($"Here is the revised index definition:\n{indexJson}");
        }
        catch (Exception ex)
        {
            Console.WriteLine($"Error updating index: {ex.Message}");
        }
    }

    // This is the semantic configuration definition
    static void AddSemanticConfiguration(SearchIndex index, string semanticConfigName)
    {
        if (index.SemanticSearch == null)
        {
            index.SemanticSearch = new SemanticSearch();
        }
        var configs = index.SemanticSearch.Configurations;
        if (configs == null)
        {
            throw new InvalidOperationException("SemanticSearch.Configurations is null and cannot be assigned. Your service must be Basic tier or higher.");
        }
        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
                )
            );
            Console.WriteLine($"Added new semantic configuration '{semanticConfigName}' to the index definition.");
        }
        else
        {
            Console.WriteLine($"Semantic configuration '{semanticConfigName}' already exists in the index definition.");
        }
        index.SemanticSearch.DefaultConfigurationName = semanticConfigName;
    }
}

検索サービスの URL を有効なエンドポイントに置き換えます。
プログラムを実行します。
出力は Console.WriteLine からコンソールウィンドウに記録されます。新しいセマンティック構成が含まれるインデックススキーマの JSON を含め、各ステップのメッセージが表示されます。

セマンティッククエリを実行する

このセクションでは、プログラムは複数のセマンティッククエリを順番に実行します。

Visual Studio で QueryIndex プロジェクトを開きます。プログラムは次のコードで構成されます。

このコードでは、インデックスにクエリを送信するために SearchClient を使用します。

class SemanticQuery
{
    static async Task Main(string[] args)
    {
        string searchServiceName = "PUT-YOUR-SEARCH-SERVICE-NAME-HERE";
        string indexName = "hotels-sample-index";
        string endpoint = $"https://{searchServiceName}.search.windows.net";
        var credential = new Azure.Identity.DefaultAzureCredential();

        var client = new SearchClient(new Uri(endpoint), indexName, credential);

        // Query 1: Simple query
        string searchText = "walking distance to live music";
        Console.WriteLine("\nQuery 1: Simple query using the search string 'walking distance to live music'.");
        await RunQuery(client, searchText, new SearchOptions
        {
            Size = 5,
            QueryType = SearchQueryType.Simple,
            IncludeTotalCount = true,
            Select = { "HotelId", "HotelName", "Description" }
        });
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 2: Semantic query (no captions, no answers)
        Console.WriteLine("\nQuery 2: Semantic query (no captions, no answers) for 'walking distance to live music'.");
        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);
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 3: Semantic query with captions
        Console.WriteLine("\nQuery 3: Semantic query with captions.");
        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" }
        };
        // Add the field(s) you want captions for to the QueryCaption.Fields collection
        captionsOptions.HighlightFields.Add("Description");
        await RunQuery(client, searchText, captionsOptions, showCaptions: true);
        Console.WriteLine("Press Enter to continue to the next query...");
        Console.ReadLine();

        // Query 4: Semantic query with answers
        // This query uses different search text designed for an answers scenario
        string searchText2 = "what's a good hotel for people who like to read";
        searchText = searchText2; // Update searchText for the next query
        Console.WriteLine("\nQuery 4: Semantic query with a verbatim answer from the Description field for 'what's a good hotel for people who like to read'.");
        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);

        static async Task RunQuery(
        SearchClient client,
        string searchText,
        SearchOptions options,
        bool showCaptions = false,
        bool showAnswers = false)
        {
            try
            {
                var response = await client.SearchAsync<SearchDocument>(searchText, options);

                if (showAnswers && response.Value.SemanticSearch?.Answers != null)
                {
                    Console.WriteLine("Extractive Answers:");
                    foreach (var answer in response.Value.SemanticSearch.Answers)
                    {
                        Console.WriteLine($"  {answer.Highlights}");
                    }
                    Console.WriteLine(new string('-', 40));
                }

                await foreach (var result in response.Value.GetResultsAsync())
                {
                    var doc = result.Document;
                    // Print captions first if available
                    if (showCaptions && result.SemanticSearch?.Captions != null)
                    {
                        foreach (var caption in result.SemanticSearch.Captions)
                        {
                            Console.WriteLine($"Caption: {caption.Highlights}");
                        }
                    }
                    Console.WriteLine($"HotelId: {doc.GetString("HotelId")}");
                    Console.WriteLine($"HotelName: {doc.GetString("HotelName")}");
                    Console.WriteLine($"Description: {doc.GetString("Description")}");
                    Console.WriteLine($"@search.score: {result.Score}");

                    // Print @search.rerankerScore if available
                    if (result.SemanticSearch != null && result.SemanticSearch.RerankerScore.HasValue)
                    {
                        Console.WriteLine($"@search.rerankerScore: {result.SemanticSearch.RerankerScore.Value}");
                    }
                    Console.WriteLine(new string('-', 40));
                }
            }
            catch (Exception ex)
            {
                Console.WriteLine($"Error querying index: {ex.Message}");
            }
        }
    }
}

検索サービスの URL を有効なエンドポイントに置き換えます。
プログラムを実行します。
出力は Console.WriteLine からコンソールウィンドウに記録されます。各クエリの検索結果が表示されます。

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

この出力はセマンティッククエリからの出力であり、キャプションや回答はありません。クエリ文字列は"ライブ音楽までの距離" です。

ここで、用語クエリの最初の結果は、セマンティックランク付けモデルを使用して再スコア付けされます。この特定のデータセットとクエリの場合、最初のいくつかの結果は同様の位置にあります。セマンティックランク付けの効果は、結果の残りの部分でより顕著になります。

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: 5.074317
@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.5153193
@search.rerankerScore: 2.271434783935547
----------------------------------------
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.
@search.score: 4.8959594
@search.rerankerScore: 1.9861756563186646
----------------------------------------
HotelId: 39
HotelName: White Mountain Lodge & Suites
Description: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.
@search.score: 0.7334347
@search.rerankerScore: 1.9615401029586792
----------------------------------------
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.5502293
@search.rerankerScore: 1.9085469245910645
----------------------------------------
Press Enter to continue to the next query...

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

こちらがヒットを強調してキャプションを追加するクエリの結果です。

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: 5.074317
@search.rerankerScore: 2.613231658935547
----------------------------------------
Caption:
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.5153193
@search.rerankerScore: 2.271434783935547
----------------------------------------
Caption: Sublime Cliff Hotel is located in the heart of the historic center of Sublime in an extremely vibrant and lively area within<em> short walking distance </em>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,.
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.
@search.score: 4.8959594
@search.rerankerScore: 1.9861756563186646
----------------------------------------
Caption: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend<em> evening entertainment </em>on the patio features special<em> guest musicians </em>or.
HotelId: 39
HotelName: White Mountain Lodge & Suites
Description: Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings.
@search.score: 0.7334347
@search.rerankerScore: 1.9615401029586792
----------------------------------------
Caption: Book now and Save up to 30%. Central ___location. <em>Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood.</em> Brand new rooms. Impeccable service.
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.5502293
@search.rerankerScore: 1.9085469245910645
----------------------------------------
Press Enter to continue to the next query...

セマンティック回答の出力

最後のクエリはセマンティック回答を返します。次の例のクエリ文字列に注目してください:「読書好きのための良いホテルはどこですか」。

セマンティックランカーは、質問の特性を持つクエリ文字列に対する回答を生成できます。生成された回答はコンテンツから逐語的に抽出されるため、チャット完了モデルに期待するような構成済みのコンテンツは含まれません。セマンティック回答がシナリオに役立たない場合は、コードから semantic_answers を省略できます。

セマンティック回答を生成するには、質問と回答を密接に調整する必要があり、モデルは質問に明確に回答するコンテンツを見つける必要があります。候補の回答が信頼度のしきい値を満たしていない場合、モデルは回答を返しません。この例ではデモ用に、質問が応答を取得するように設計されているため、構文を確認できます。

回答は、インデックスから取得された 逐語的なコンテンツ であり、ユーザーが表示すると予想される語句が見つからない可能性があることを思い出してください。チャット完了モデルによって生成された 構成済みの回答 を取得するには、 RAG パターンまたはエージェント検索の使用を検討します。

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.
----------------------------------------
HotelId: 1
HotelName: 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.
@search.score: 2.0361428
@search.rerankerScore: 2.124817371368408
----------------------------------------
HotelId: 16
HotelName: 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.
@search.score: 3.759768
@search.rerankerScore: 2.0705394744873047
----------------------------------------
HotelId: 38
HotelName: Lakeside B & B
Description: 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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
@search.score: 0.7308748
@search.rerankerScore: 2.041472911834717
----------------------------------------
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: 3.391012
@search.rerankerScore: 2.0231292247772217
----------------------------------------
HotelId: 15
HotelName: By the Market Hotel
Description: Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service.
@search.score: 1.3198771
@search.rerankerScore: 2.021622657775879
----------------------------------------

このクイックスタートでは、セマンティックランク付けを既存のインデックスに追加する方法について説明します。 hotels-sample-index または独自のものを使用できます。

Azure AI 検索のセマンティックランク付けは、Microsoft の機械読解を使用して検索結果を再スコアリングして、セマンティック関連性が最も高い一致を一覧の最上位に昇格させる、クエリ側の機能です。コンテンツとクエリによっては、セマンティックランク付けによって、開発者の労力を最小限に抑えながら検索の関連性を大幅に向上させることができます。

再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。セマンティックランク付けは、情報的または説明的なテキストに最も効果的です。

このクイックスタートでは、次の方法について説明します。

検索インデックスにセマンティック構成を追加する
セマンティックパラメーターをクエリに追加する

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
セマンティックランカーが有効になっている、Basic レベル以上の Azure AI Search サービス。
説明的または詳細なテキストフィールドを持つ新規または既存のインデックス。インデックスで取得可能と見なされます。このクイックスタートでは、 hotels-sample-index を前提としています。

アクセスを構成する

ロールの割り当てで API キーまたは Microsoft Entra ID を使用して、Azure AI Search サービスに接続できます。キーの方が簡単に使い始めることができますが、安全性が高いのはロールの方です。

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

Azure portal にサインインし、検索サービスを選択します。
次に、左側のペインで [設定]>[キー] を選択します。
[API アクセス制御] で、[両方] を選択します。

このオプションでは、キーベース認証とキーレス認証の両方が有効になります。ロールを割り当てた後、この手順に戻り、[ ロールベースのアクセス制御] を選択できます。
左側のウィンドウで、[ アクセス制御 (IAM)] を選択します。
[追加>][ロール割り当ての追加] の順に選択します。
ユーザーアカウントに次のロールを割り当てます。
- Search Service サービス貢献者
- 検索インデックスデータ共同作成者

詳細については、「ロールを使用して Azure AI 検索に接続する」を参照してください。

インデックスから始める

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

Azure portal にサインインし、ご利用の検索サービスを探します。
[検索の管理>Indexes] で、hotels-sample-index を開きます。インデックスにセマンティック構成がないことを確認します。

インデックスが操作可能であることを確認するには、クエリを実行します。 検索エクスプローラーで、セマンティックランク付けが適用される前に応答を表示できるように、この検索文字列 "walking distance to live music" を入力します。

応答は、フルテキスト検索の既定の BM25 L1 ランカーによってスコア付けされた次の例のようになります。読みやすくするために、この例では "HotelName" "HotelId" フィールドと "Description" フィールドのみを選択します。

このクエリはキーワード検索です。結果には、クエリ用語 (ウォーキング、距離、ライブ、音楽) または言語バリアント (ウォーク、リビング) に関する逐語的一致が含まれます。

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime ___location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

後で、セマンティックランク付けが構成された後に、応答がどのように変化するかを確認するために、このクエリをもう一度試すことができます。

ヒント

セマンティック構成は、Azure portal で追加できます。ただし、セマンティック構成をプログラムで追加する方法については、このクイックスタートの手順に進んでください。

クライアントを設定する

このクイックスタートでは、IDE と @azure/search-documents クライアントライブラリを使用して、既存の検索インデックスにセマンティックランク付けを追加します。

このクイックスタートでは、お使いのコンピューターに次のものが用意されていることを前提としています。

このクイックスタート用の Visual Studio Code。
サンプルを実行するための Node.js(LTS)。

ヒント

ソースコードをダウンロードして完成したプロジェクトから開始することも、以下の手順に従って独自のアプリケーションを作成することもできます。

ローカル開発環境を設定する

新しいディレクトリで Visual Studio Code を開始します。

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

プロジェクトディレクトリに ESM モジュール用の新しいパッケージを作成します。
```
npm init -y
npm pkg set type=module
```
azure-search-documents などのパッケージをインストールします。
```
npm install @azure/identity @azure/search-documents dotenv
```
.env を作成し、検索サービスエンドポイントを指定します。エンドポイントは、検索サービスの [概要 ] ページの Azure portal から取得できます。
```
AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
SEMANTIC_CONFIGURATION_NAME=semantic-config
```
プロジェクトディレクトリに src ディレクトリを作成します。
```
mkdir src
```

Azure portal にサインインした場合は、Azure にサインインします。不明な場合は、Azure CLI または Azure PowerShell を使用してログインします。 az login または az connect。複数のテナントとサブスクリプションがある場合、接続方法については、「クイックスタート: キーなしで接続する」を参照してください。

共通の認証ファイルを作成する

./src ファイルを読み取り、環境変数と認証情報を保持するために、config.ts に .env というファイルを作成します。次のコードをコピーし、変更しないでください。このファイルは、このクイックスタート内の他のすべてのファイルで使用されます。

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

// Configuration - use environment variables
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-index";
export const semanticConfigurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";

// Create credential
export const credential = new DefaultAzureCredential();

console.log(`Using Azure Search endpoint: ${searchEndpoint}`);
console.log(`Using index name: ${indexName}\n\n`);

インデックススキーマを取得する

このセクションでは、検索サービスの既存の hotels-sample-index インデックスの設定を取得します。

./src に getIndexSettings.js という名前のファイルを作成し、次のコードをコピーします。

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

const indexClient = new SearchIndexClient(searchEndpoint, credential);

console.log('Getting semantic search index settings...');

// Get the existing schema
const index = await indexClient.getIndex(indexName);

console.log(`Index name: ${index.name}`);
console.log(`Number of fields: ${index.fields.length}`);

for(const field of index.fields) {
    console.log(`Field: ${field.name}, Type: ${field.type}, Searchable: ${field.searchable}`);
}

if(index.semanticSearch && index.semanticSearch.configurations) {
    console.log(`Semantic search configurations: ${index.semanticSearch.configurations.length}`);
    for(const config of index.semanticSearch.configurations) {
        console.log(`Configuration name: ${config.name}`);
        console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
    }
} else {
    console.log("No semantic configuration exists for this index.");
}

コードを実行します。

node -r dotenv/config src/getIndexSettings.js

出力は、インデックスの名前、フィールドの一覧、セマンティック構成が存在するかどうかを示すステートメントです。このクイックスタートでは、メッセージは「No semantic configuration exists for this index」と表示されるはずです。

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

検索サービス上の既存の ./src インデックスにセマンティック構成を追加するために、updateIndexSettings.js に hotels-sample-index という名前のファイルを作成し、次のコードをコピーします。この操作では検索ドキュメントは削除されません。構成が追加された後も、インデックスは引き続き動作します。

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

try {

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

    // Add the new semantic configuration to the existing index
    if (existingIndex.semanticSearch && existingIndex.semanticSearch.configurations) {
        existingIndex.semanticSearch.configurations.push(newSemanticConfiguration);
    } else {
        const configExists = existingIndex.semanticSearch?.configurations?.some(
            config => config.name === semanticConfigurationName
        );
        if (!configExists) {
            existingIndex.semanticSearch = {
                configurations: [newSemanticConfiguration]
            };
        }
    }

    await indexClient.createOrUpdateIndex(existingIndex);

    const updatedIndex = await indexClient.getIndex(indexName);

    console.log(`Semantic configurations:`);
    console.log("-".repeat(40));

    if (updatedIndex.semanticSearch && updatedIndex.semanticSearch.configurations) {
        for (const config of updatedIndex.semanticSearch.configurations) {
            console.log(`Configuration name: ${config.name}`);
            console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
            console.log(`Keywords fields: ${config.prioritizedFields.keywordsFields?.map(f => f.name).join(", ")}`);
            console.log(`Content fields: ${config.prioritizedFields.contentFields?.map(f => f.name).join(", ")}`);
            console.log("-".repeat(40));
        }
    } else {
        console.log("No semantic configurations found.");
    }

    console.log("Semantic configuration updated successfully.");
} catch (error) {
    console.error("Error updating semantic configuration:", error);
}

コードを実行します。

node -r dotenv/config src/updateIndexSettings.js

出力は、先ほど追加したセマンティック構成「Semantic configuration updated successfully.」です。

セマンティッククエリを実行する

hotels-sample-index インデックスにセマンティック構成が設定されると、セマンティックパラメーターを含むクエリを実行できるようになります。

インデックスのセマンティッククエリを作成するために、./src に semanticQuery.js という名前のファイルを作成し、次のコードをコピーします。これは、セマンティックランク付けを呼び出すための最小要件です。

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

let rowNumber = 1;
for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const score = result.score;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelId: ${doc.HotelId}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);
}

コードを実行します。

node -r dotenv/config src/semanticQuery.js

出力は、 rerankerScoreDisplayで並べ替えられた 13 個のドキュメントで構成されている必要があります。

キャプションを返す

必要に応じて、キャプションを追加してテキストの一部を抽出し、重要な用語や語句にヒット強調表示を適用できます。このクエリでは、キャプションが追加されます。

クエリにキャプションを追加するために、./src に semanticQueryReturnCaptions.js という名前のファイルを作成し、次のコードをコピーします。

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

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

console.log(`Using semantic configuration: ${semanticConfigurationName}`);
console.log("Search query: walking distance to live music");

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

console.log(`Found ${results.count} results with semantic search\n`);
let rowNumber = 1;

for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);

    // Caption handling with better debugging
    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];

        if (caption.highlights) {
            console.log(`  Caption with highlights: ${caption.highlights}`);
        } else if (caption.text) {
            console.log(`  Caption text: ${caption.text}`);
        } else {
            console.log(`  Caption exists but has no text or highlights content`);
        }
    } else {
        console.log("  No captions found for this result");
    }
    console.log("-".repeat(60));
}

コードを実行します。

node -r dotenv/config src/semanticQueryReturnCaptions.js

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

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.

セマンティック回答を返す

この最後のクエリでは、セマンティック回答を返します。

セマンティックランカーは、質問の特性を持つクエリ文字列に対する回答を生成できます。生成された回答はコンテンツから逐語的に抽出されるため、チャット完了モデルに期待するような構成済みのコンテンツは含まれません。セマンティック回答がシナリオに役立たない場合は、コードから semantic_answers を省略できます。

セマンティック回答を生成するには、質問と回答を密接に調整する必要があり、モデルは質問に明確に回答するコンテンツを見つける必要があります。候補の回答が信頼度のしきい値を満たしていない場合、モデルは回答を返しません。この例ではデモ用に、質問が応答を取得するように設計されているため、構文を確認できます。

セマンティックな回答を取得するために、./src に semanticAnswer.js という名前のファイルを作成し、次のコードをコピーします。

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("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"]
});

console.log(`Answers:\n\n`);
let rowNumber = 1; 

// Extract semantic answers from the search results
const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    console.log(`Semantic answer result #${rowNumber++}:`);
    if (answer.highlights) {
        console.log(`Semantic Answer: ${answer.highlights}`);
    } else {
        console.log(`Semantic Answer: ${answer.text}`);
    }
    console.log(`Semantic Answer Score: ${answer.score}\n\n`);
}

console.log(`Search Results:\n\n`);
rowNumber = 1;

// Iterate through the search results
for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`${rerankerScoreDisplay}`);
    console.log(`${doc.HotelName}`);
    console.log(`${doc.Description || 'N/A'}`);

    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(`Caption: ${caption.highlights}\n`);
        } else {
            console.log(`Caption: ${caption.text}\n`);
        }
    }
}

コードを実行します。

node -r dotenv/config src/semanticAnswer.js

出力は次の例のようになります。質問に対する最良の答えは、いずれかの結果から取得されます。

回答は、インデックスから取得された 逐語的なコンテンツ であり、ユーザーが表示すると予想される語句が見つからない可能性があることを思い出してください。チャット完了モデルによって生成された 構成済みの回答 を取得するには、 RAG パターンまたはエージェント検索の使用を検討します。
```
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 library 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
```

このクイックスタートでは、セマンティックランク付けを既存のインデックスに追加する方法について説明します。 hotels-sample-index または独自のものを使用できます。

Azure AI 検索のセマンティックランク付けは、Microsoft の機械読解を使用して検索結果を再スコアリングして、セマンティック関連性が最も高い一致を一覧の最上位に昇格させる、クエリ側の機能です。コンテンツとクエリによっては、セマンティックランク付けによって、開発者の労力を最小限に抑えながら検索の関連性を大幅に向上させることができます。

再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。セマンティックランク付けは、情報的または説明的なテキストに最も効果的です。

このクイックスタートでは、次の方法について説明します。

検索インデックスにセマンティック構成を追加する
セマンティックパラメーターをクエリに追加する

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
セマンティックランカーが有効になっている、Basic レベル以上の Azure AI Search サービス。
説明的または詳細なテキストフィールドを持つ新規または既存のインデックス。インデックスで取得可能と見なされます。このクイックスタートでは、 hotels-sample-index を前提としています。

アクセスを構成する

ロールの割り当てで API キーまたは Microsoft Entra ID を使用して、Azure AI Search サービスに接続できます。キーの方が簡単に使い始めることができますが、安全性が高いのはロールの方です。

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

Azure portal にサインインし、検索サービスを選択します。
次に、左側のペインで [設定]>[キー] を選択します。
[API アクセス制御] で、[両方] を選択します。

このオプションでは、キーベース認証とキーレス認証の両方が有効になります。ロールを割り当てた後、この手順に戻り、[ ロールベースのアクセス制御] を選択できます。
左側のウィンドウで、[ アクセス制御 (IAM)] を選択します。
[追加>][ロール割り当ての追加] の順に選択します。
ユーザーアカウントに次のロールを割り当てます。
- Search Service サービス貢献者
- 検索インデックスデータ共同作成者

詳細については、「ロールを使用して Azure AI 検索に接続する」を参照してください。

インデックスから始める

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

Azure portal にサインインし、ご利用の検索サービスを探します。
[検索の管理>Indexes] で、hotels-sample-index を開きます。インデックスにセマンティック構成がないことを確認します。

インデックスが操作可能であることを確認するには、クエリを実行します。 検索エクスプローラーで、セマンティックランク付けが適用される前に応答を表示できるように、この検索文字列 "walking distance to live music" を入力します。

応答は、フルテキスト検索の既定の BM25 L1 ランカーによってスコア付けされた次の例のようになります。読みやすくするために、この例では "HotelName" "HotelId" フィールドと "Description" フィールドのみを選択します。

このクエリはキーワード検索です。結果には、クエリ用語 (ウォーキング、距離、ライブ、音楽) または言語バリアント (ウォーク、リビング) に関する逐語的一致が含まれます。

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime ___location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

後で、セマンティックランク付けが構成された後に、応答がどのように変化するかを確認するために、このクエリをもう一度試すことができます。

ヒント

セマンティック構成は、Azure portal で追加できます。ただし、セマンティック構成をプログラムで追加する方法については、このクイックスタートの手順に進んでください。

クライアントを設定する

このクイックスタートでは、IDE と Azure AI Search Java SDK クライアントライブラリを使用して、既存の検索インデックスにセマンティックランク付けを追加します。

このクイックスタートでは、お使いのコンピューターに次のものが用意されていることを前提としています。

Java 拡張機能を備えた Visual Studio Code または IntelliJ IDEA
Java 21 (LTS)。
Maven。

ローカル開発環境を設定する

新しい Maven プロジェクトディレクトリを作成します。

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

必要な依存関係を持つ pom.xml ファイルを作成します。

<project xmlns="http://maven.apache.org/POM/4.0.0"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
         http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelVersion>4.0.0</modelVersion>

    <groupId>com.azure.search</groupId>
    <artifactId>semantic-ranking-quickstart</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>21</maven.compiler.source>
        <maven.compiler.target>21</maven.compiler.target>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-search-documents</artifactId>
            <version>11.7.8</version>
        </dependency>
        <dependency>
            <groupId>com.azure</groupId>
            <artifactId>azure-identity</artifactId>
            <version>1.17.0</version>
        </dependency>
    </dependencies>
</project>

プロジェクトをコンパイルして依存関係を解決します。
```
mvn compile
```

ソースディレクトリ構造を作成します。

mkdir -p src/main/java/com/azure/search/quickstart
mkdir -p src/main/resources

src/main/resources/application.properties を作成し、検索サービスエンドポイントを指定します。エンドポイントは、検索サービスの [概要 ] ページの Azure portal から取得できます。
```
azure.search.endpoint=YOUR-SEARCH-SERVICE-ENDPOINT
azure.search.index.name=hotels-sample-index
semantic.configuration.name=semantic-config
```

Azure portal にサインインした場合は、Azure にサインインします。不明な場合は、Azure CLI を使用してログインしてください: az login。複数のテナントとサブスクリプションがある場合、接続方法については、「クイックスタート: キーなしで接続する」を参照してください。

共通の構成クラスを作成する

src/main/java/com/azure/search/quickstart に SearchConfig.java という名前のファイルを作成し、プロパティファイルを読み取って構成値と認証情報を保持します。

package com.azure.search.quickstart;

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();

    static {
        System.out.println("Using Azure Search endpoint: " + SEARCH_ENDPOINT);
        System.out.println("Using index name: " + INDEX_NAME + "\n");
    }
}

インデックススキーマを取得する

このセクションでは、検索サービスの既存の hotels-sample-index インデックスの設定を取得します。

src/main/java/com/azure/search/quickstart に GetIndexSettings.java という名前のファイルを作成します。

package com.azure.search.quickstart;

import com.azure.search.documents.indexes.SearchIndexClientBuilder;
import com.azure.search.documents.indexes.models.SearchField;
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.SemanticSearch;

public class GetIndexSettings {
    public static void main(String[] args) {
        var indexClient = new SearchIndexClientBuilder()
            .endpoint(SearchConfig.SEARCH_ENDPOINT)
            .credential(SearchConfig.CREDENTIAL)
            .buildClient();

        System.out.println("Getting semantic search index settings...");

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

        System.out.println("Index name: " + index.getName());
        System.out.println("Number of fields: " + index.getFields().size());

        for (SearchField field : index.getFields()) {
            System.out.printf("Field: %s, Type: %s, Searchable: %s%n",
                field.getName(), field.getType(), field.isSearchable());
        }

        SemanticSearch semanticSearch = index.getSemanticSearch();
        if (semanticSearch != null &&
            semanticSearch.getConfigurations() != null) {
            System.out.println("Semantic search configurations: " +
                semanticSearch.getConfigurations().size());
            for (SemanticConfiguration config :
                semanticSearch.getConfigurations()) {
                System.out.println("Configuration name: " + config.getName());
                SemanticField titleField = config.getPrioritizedFields().getTitleField();
                if (titleField != null) {
                    System.out.println("Title field: " +
                        titleField.getFieldName());
                }
            }
        } else {
            System.out.println(
                "No semantic configuration exists for this index.");
        }

        System.exit(0);
    }
}

コードをコンパイルして実行します。

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

出力は、インデックスの名前、フィールドの一覧、セマンティック構成が存在するかどうかを示すステートメントです。このクイックスタートでは、メッセージは「No semantic configuration exists for this index」と表示されるはずです。

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

検索サービス上の既存の src/main/java/com/azure/search/quickstart インデックスにセマンティック構成を追加するために、UpdateIndexSettings.java に hotels-sample-index という名前のファイルを作成します。

package com.azure.search.quickstart;

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;

public class UpdateIndexSettings {
    public static void main(String[] args) {
        try {
            var indexClient = new SearchIndexClientBuilder()
                .endpoint(SearchConfig.SEARCH_ENDPOINT)
                .credential(SearchConfig.CREDENTIAL)
                .buildClient();

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

            // Create prioritized fields for semantic configuration
            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);

            // Add the semantic configuration to the index
            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);
            }

            // Check if configuration already exists
            boolean configExists = configurations.stream()
                .anyMatch(config -> SearchConfig.SEMANTIC_CONFIG_NAME
                    .equals(config.getName()));

            if (!configExists) {
                configurations.add(newSemanticConfiguration);
            }

            indexClient.createOrUpdateIndex(existingIndex);

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

            System.out.println("Semantic configurations:");
            System.out.println("-".repeat(40));

            SemanticSearch updatedSemanticSearch =
                updatedIndex.getSemanticSearch();
            if (updatedSemanticSearch != null &&
                updatedSemanticSearch.getConfigurations() != null) {
                for (SemanticConfiguration config :
                    updatedSemanticSearch.getConfigurations()) {
                    System.out.println("Configuration name: " + config.getName());

                    SemanticPrioritizedFields fields =
                        config.getPrioritizedFields();
                    if (fields.getTitleField() != null) {
                        System.out.println("Title field: " +
                            fields.getTitleField().getFieldName());
                    }
                    if (fields.getKeywordsFields() != null) {
                        List<String> keywords = fields.getKeywordsFields().stream()
                            .map(SemanticField::getFieldName)
                            .toList();
                        System.out.println("Keywords fields: " +
                            String.join(", ", keywords));
                    }
                    if (fields.getContentFields() != null) {
                        List<String> content = fields.getContentFields().stream()
                            .map(SemanticField::getFieldName)
                            .toList();
                        System.out.println("Content fields: " +
                            String.join(", ", content));
                    }
                    System.out.println("-".repeat(40));
                }
            } else {
                System.out.println("No semantic configurations found.");
            }

            System.out.println("Semantic configuration updated successfully.");

            System.exit(0);
        } catch (Exception e) {
            System.err.println("Error updating semantic configuration: " +
                e.getMessage());
        }
    }
}

コードを実行します。

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

出力は、先ほど追加したセマンティック構成「Semantic configuration updated successfully.」です。

セマンティッククエリを実行する

hotels-sample-index インデックスにセマンティック構成が設定されると、セマンティックパラメーターを含むクエリを実行できるようになります。

インデックスのセマンティッククエリを作成するために、src/main/java/com/azure/search/quickstart に SemanticQuery.java という名前のファイルを作成します。

package com.azure.search.quickstart;

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;

public class SemanticQuery {
    public static void main(String[] args) {
        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);

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

            System.out.printf("Search result #%d:%n", rowNumber++);
            System.out.printf("  Re-ranker Score: %.2f%n", rerankerScore);
            System.out.printf("  HotelId: %s%n", document.get("HotelId"));
            System.out.printf("  HotelName: %s%n", document.get("HotelName"));
            System.out.printf("  Description: %s%n%n",
                document.get("Description") != null ?
                    document.get("Description") : "N/A");
        }

        System.exit(0);
    }
}

コードを実行します。

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

出力は、リランカースコア順に並べ替えられた 13 個のドキュメントで構成されている必要があります。

キャプションを返す

必要に応じて、キャプションを追加してテキストの一部を抽出し、重要な用語や語句にヒット強調表示を適用できます。

src/main/java/com/azure/search/quickstart に SemanticQueryWithCaptions.java という名前のファイルを作成します。

package com.azure.search.quickstart;

import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryCaption;
import com.azure.search.documents.models.QueryCaptionResult;
import com.azure.search.documents.models.QueryCaptionType;
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;
import java.util.List;

public class SemanticQueryWithCaptions {
    public static void main(String[] args) {
        var searchClient = new SearchClientBuilder()
            .endpoint(SearchConfig.SEARCH_ENDPOINT)
            .indexName(SearchConfig.INDEX_NAME)
            .credential(SearchConfig.CREDENTIAL)
            .buildClient();

        System.out.println("Using semantic configuration: " +
            SearchConfig.SEMANTIC_CONFIG_NAME);
        System.out.println("Search query: walking distance to live music");

        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);

        System.out.printf("Found results with semantic search%n%n");
        int rowNumber = 1;

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

            System.out.printf("Search result #%d:%n", rowNumber++);
            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") != null ?
                    document.get("Description") : "N/A");

            // Handle captions
            List<QueryCaptionResult> captions =
                result.getSemanticSearch().getQueryCaptions();
            if (captions != null && !captions.isEmpty()) {
                QueryCaptionResult caption = captions.get(0);

                if (caption.getHighlights() != null &&
                    !caption.getHighlights().trim().isEmpty()) {
                    System.out.printf("  Caption with highlights: %s%n",
                        caption.getHighlights());
                } else if (caption.getText() != null &&
                    !caption.getText().trim().isEmpty()) {
                    System.out.printf("  Caption text: %s%n",
                        caption.getText());
                } else {
                    System.out.println(
                        "  Caption exists but has no text or highlights content");
                }
            } else {
                System.out.println("  No captions found for this result");
            }
            System.out.println("-".repeat(60));
        }

        System.exit(0);
    }
}

コードを実行します。

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

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

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.

セマンティック回答を返す

この最後のクエリでは、セマンティック回答を返します。

セマンティックランカーは、質問の特性を持つクエリ文字列に対する回答を生成できます。生成された回答はコンテンツから逐語的に抽出されるため、チャット完了モデルに期待するような構成済みのコンテンツは含まれません。

セマンティック回答を生成するには、質問と回答を密接に調整する必要があり、モデルは質問に明確に回答するコンテンツを見つける必要があります。候補の回答が信頼度のしきい値を満たしていない場合、モデルは回答を返しません。この例ではデモ用に、質問が応答を取得するように設計されているため、構文を確認できます。

src/main/java/com/azure/search/quickstart に SemanticAnswer.java という名前のファイルを作成します。

package com.azure.search.quickstart;

import com.azure.search.documents.SearchClientBuilder;
import com.azure.search.documents.SearchDocument;
import com.azure.search.documents.models.QueryAnswer;
import com.azure.search.documents.models.QueryAnswerResult;
import com.azure.search.documents.models.QueryAnswerType;
import com.azure.search.documents.models.QueryCaption;
import com.azure.search.documents.models.QueryCaptionResult;
import com.azure.search.documents.models.QueryCaptionType;
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;

import java.util.List;

public class SemanticAnswer {
    public static void main(String[] args) {
        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)
                .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);

        System.out.println("Answers:\n");

        // Extract semantic answers
        List<QueryAnswerResult> semanticAnswers =
            results.getSemanticResults().getQueryAnswers();
        int answerNumber = 1;

        if (semanticAnswers != null) {
            for (QueryAnswerResult answer : semanticAnswers) {
                System.out.printf("Semantic answer result #%d:%n",
                    answerNumber++);

                if (answer.getHighlights() != null &&
                    !answer.getHighlights().trim().isEmpty()) {
                    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%n",
                    answer.getScore());
            }
        }

        System.out.println("Search Results:\n");
        int rowNumber = 1;

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

            System.out.printf("Search result #%d:%n", rowNumber++);
            System.out.printf("Re-ranker Score: %.2f%n", rerankerScore);
            System.out.printf("Hotel: %s%n", document.get("HotelName"));
            System.out.printf("Description: %s%n",
                document.get("Description") != null ?
                    document.get("Description") : "N/A");

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

        System.exit(0);
    }
}

コードを実行します。

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

出力は次の例のようになります。質問に対する最良の答えは、いずれかの結果から取得されます。

回答は、インデックスから取得された 逐語的なコンテンツ であり、ユーザーが表示すると予想される語句が見つからない可能性があることを思い出してください。チャット完了モデルによって生成された 構成済みの回答 を取得するには、 RAG パターンまたはエージェント検索の使用を検討します。
```
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 library 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
```

このクイックスタートでは、セマンティックランク付けを既存のインデックスに追加する方法について説明します。 hotels-sample-index または独自のものを使用できます。

Azure AI 検索のセマンティックランク付けは、Microsoft の機械読解を使用して検索結果を再スコアリングして、セマンティック関連性が最も高い一致を一覧の最上位に昇格させる、クエリ側の機能です。コンテンツとクエリによっては、セマンティックランク付けによって、開発者の労力を最小限に抑えながら検索の関連性を大幅に向上させることができます。

再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。セマンティックランク付けは、情報的または説明的なテキストに最も効果的です。

このクイックスタートでは、次の方法について説明します。

検索インデックスにセマンティック構成を追加する
セマンティックパラメーターをクエリに追加する

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
セマンティックランカーが有効になっている、Basic レベル以上の Azure AI Search サービス。
説明的または詳細なテキストフィールドを持つ新規または既存のインデックス。インデックスで取得可能と見なされます。このクイックスタートでは、 hotels-sample-index を前提としています。

アクセスを構成する

ロールの割り当てで API キーまたは Microsoft Entra ID を使用して、Azure AI Search サービスに接続できます。キーの方が簡単に使い始めることができますが、安全性が高いのはロールの方です。

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

Azure portal にサインインし、検索サービスを選択します。
次に、左側のペインで [設定]>[キー] を選択します。
[API アクセス制御] で、[両方] を選択します。

このオプションでは、キーベース認証とキーレス認証の両方が有効になります。ロールを割り当てた後、この手順に戻り、[ ロールベースのアクセス制御] を選択できます。
左側のウィンドウで、[ アクセス制御 (IAM)] を選択します。
[追加>][ロール割り当ての追加] の順に選択します。
ユーザーアカウントに次のロールを割り当てます。
- Search Service サービス貢献者
- 検索インデックスデータ共同作成者

詳細については、「ロールを使用して Azure AI 検索に接続する」を参照してください。

インデックスから始める

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

Azure portal にサインインし、ご利用の検索サービスを探します。
[検索の管理>Indexes] で、hotels-sample-index を開きます。インデックスにセマンティック構成がないことを確認します。

インデックスが操作可能であることを確認するには、クエリを実行します。 検索エクスプローラーで、セマンティックランク付けが適用される前に応答を表示できるように、この検索文字列 "walking distance to live music" を入力します。

応答は、フルテキスト検索の既定の BM25 L1 ランカーによってスコア付けされた次の例のようになります。読みやすくするために、この例では "HotelName" "HotelId" フィールドと "Description" フィールドのみを選択します。

このクエリはキーワード検索です。結果には、クエリ用語 (ウォーキング、距離、ライブ、音楽) または言語バリアント (ウォーク、リビング) に関する逐語的一致が含まれます。

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime ___location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

後で、セマンティックランク付けが構成された後に、応答がどのように変化するかを確認するために、このクエリをもう一度試すことができます。

ヒント

セマンティック構成は、Azure portal で追加できます。ただし、セマンティック構成をプログラムで追加する方法については、このクイックスタートの手順に進んでください。

クライアントを設定する

このクイックスタートでは、Jupyter Notebook と Azure SDK for Python の azure-search-documents ライブラリを使用して、セマンティックランク付けについて学習します。

このクイックスタートでは、Python 3.10 以降と Python 拡張機能を使用した Visual Studio Code をお勧めします。

ヒント

完成したノートブックをダウンロードして完成したプロジェクトから開始するか、次の手順に従って独自のノートブックを作成できます。

このクイックスタートでは仮想環境をお勧めします。

Visual Studio Code を起動します。
semantic-search-quickstart.ipynb ファイルを開くか、新しいノートブックを作成します。
Ctrl + Shift + P キーを使用してコマンドパレットを開きます。
Python: 環境の作成を検索します。
Venv. を選択
Python インタープリターを選択します。 3.10 以降を選択します。

短時間で設定されます。問題が発生した場合は、VS Code での Python 環境に関する記事を参照してください。

パッケージのインストールと環境変数の設定

azure-search-documents などのパッケージをインストールします。
```
! pip install -r requirements.txt --quiet
```
sample.envの名前を.envに変更し、検索サービスエンドポイントを指定します。エンドポイントは、検索サービスの [概要 ] ページの Azure portal から取得できます。
```
AZURE_SEARCH_ENDPOINT=https://your-search-service.search.windows.net
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
```

Azure portal にサインインした場合は、Azure にサインインします。不明な場合は、Azure CLI または Azure PowerShell を使用してログインします。 az login または az connect。複数のテナントとサブスクリプションがある場合、接続方法については、「クイックスタート: キーなしで接続する」を参照してください。

インデックスを更新する

このセクションでは、セマンティック構成を含むように検索インデックスを更新します。このコードは、検索サービスからインデックス定義を取得し、セマンティック構成を追加します。

Visual Studio Code で semantic-search-quickstart.ipynb ファイルを開くか、新しいファイルを作成します。

ソリューションで使用される変数を指定します。

# Provide variables
from dotenv import load_dotenv
from azure.identity import DefaultAzureCredential, get_bearer_token_provider
import os

load_dotenv(override=True) # Take environment variables from .env.

# The following variables from your .env file are used in this notebook
search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
token_provider = get_bearer_token_provider(credential, "https://search.azure.com/.default")
index_name = os.getenv("AZURE_SEARCH_INDEX", "hotels-sample-index")

SearchIndexClient を作成し、既存の hotels-sample-index を取得します。

from azure.search.documents.indexes import SearchIndexClient
from azure.identity import DefaultAzureCredential
import os

# Initialize the client (similar to what you already have)
search_endpoint = os.environ["AZURE_SEARCH_ENDPOINT"]
credential = DefaultAzureCredential()
index_name = "hotels-sample-index"  # or use your existing index_name variable

# Create the SearchIndexClient
index_client = SearchIndexClient(endpoint=search_endpoint, credential=credential)

try:
    # Get the existing index schema
    index = index_client.get_index(index_name)

    print(f"Index name: {index.name}")
    print(f"Number of fields: {len(index.fields)}")

    # Print field details
    for field in index.fields:
        print(f"Field: {field.name}, Type: {field.type}, Searchable: {field.searchable}")

    # Access semantic configuration if it exists
    if index.semantic_search and index.semantic_search.configurations:
        for config in index.semantic_search.configurations:
            print(f"Semantic config: {config.name}")
            if config.prioritized_fields.title_field:
                print(f"Title field: {config.prioritized_fields.title_field.field_name}")
    else:
        print("No semantic configuration exists for this index")

except Exception as ex:
    print(f"Error retrieving index: {ex}")

コードを実行します。
出力は、インデックスの名前、フィールドの一覧、セマンティック構成が存在するかどうかを示すステートメントです。このクイックスタートの目的上、"このインデックスのセマンティック構成は存在しません" というメッセージが表示されます。

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

# Add semantic configuration to hotels-sample-index and display updated index details
from azure.search.documents.indexes.models import (
    SemanticConfiguration,
    SemanticField,
    SemanticPrioritizedFields,
    SemanticSearch
)

try:
    # Get the existing index
    existing_index = index_client.get_index(index_name)

    # Create a new semantic configuration
    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")]
        )
    )

    # Add semantic configuration to the index
    if existing_index.semantic_search is None:
        existing_index.semantic_search = SemanticSearch(configurations=[new_semantic_config])
    else:
        # Check if configuration already exists
        config_exists = any(config.name == "semantic-config" 
                          for config in existing_index.semantic_search.configurations)
        if not config_exists:
            existing_index.semantic_search.configurations.append(new_semantic_config)

    # Update the index
    result = index_client.create_or_update_index(existing_index)

    # Get the updated index and display detailed information
    updated_index = index_client.get_index(index_name)

    print("Semantic configurations:")
    print("-" * 40)
    if updated_index.semantic_search and updated_index.semantic_search.configurations:
        for config in updated_index.semantic_search.configurations:
            print(f"  Configuration: {config.name}")
            if config.prioritized_fields.title_field:
                print(f"    Title field: {config.prioritized_fields.title_field.field_name}")
            if config.prioritized_fields.keywords_fields:
                keywords = [kf.field_name for kf in config.prioritized_fields.keywords_fields]
                print(f"    Keywords fields: {', '.join(keywords)}")
            if config.prioritized_fields.content_fields:
                content = [cf.field_name for cf in config.prioritized_fields.content_fields]
                print(f"    Content fields: {', '.join(content)}")
            print()
    else:
        print("  No semantic configurations found")

    print("✅ Semantic configuration successfully added!")

except Exception as ex:
    print(f"❌ Error adding semantic configuration: {ex}")

コードを実行します。
出力は、先ほど追加したセマンティック構成です。

セマンティッククエリを実行する

インデックスにセマンティック構成が設定されたら、セマンティックパラメーターを含むクエリを実行できます。

SearchClient と、セマンティッククエリの種類とセマンティック構成を含むクエリ要求を作成します。これは、セマンティックランク付けを呼び出すための最小要件です。

# Set up the search client
search_client = SearchClient(endpoint=search_endpoint,
                      index_name=index_name,
                      credential=credential)

# Runs a semantic query (runs a BM25-ranked query, rescoring and promoting the most semantically relevant matches to the top)
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')

for result in results:
    print(result["@search.reranker_score"])
    print(result["HotelId"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

コードを実行します。
出力は、 "@search.reranker_score"で並べ替えられた 13 個のドキュメントで構成されている必要があります。

キャプションを返す

必要に応じて、キャプションを追加してテキストの一部を抽出し、重要な用語や語句にヒット強調表示を適用できます。このクエリでは、キャプションが追加されます。

クエリに captions を追加します。

# Runs a semantic query that returns captions
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:
    print(result["@search.reranker_score"])
    print(result["HotelId"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

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

コードを実行します。

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

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.

セマンティック回答を返す

この最後のクエリでは、セマンティック回答を返します。

セマンティックランカーは、質問の特性を持つクエリ文字列に対する回答を生成できます。生成された回答はコンテンツから逐語的に抽出されるため、チャット完了モデルに期待するような構成済みのコンテンツは含まれません。セマンティック回答がシナリオに役立たない場合は、コードから semantic_answers を省略できます。

セマンティック回答を生成するには、質問と回答を密接に調整する必要があり、モデルは質問に明確に回答するコンテンツを見つける必要があります。候補の回答が信頼度のしきい値を満たしていない場合、モデルは回答を返しません。この例ではデモ用に、質問が応答を取得するように設計されているため、構文を確認できます。

クエリに answers を追加します。

# Run a semantic query that returns semantic answers  
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")

for result in results:
    print(result["@search.reranker_score"])
    print(result["HotelName"])
    print(f"Description: {result['Description']}")

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

コードを実行します。

出力は次の例のようになります。質問に対する最良の答えは、いずれかの結果から取得されます。

回答は、インデックスから取得された 逐語的なコンテンツ であり、ユーザーが表示すると予想される語句が見つからない可能性があることを思い出してください。チャット完了モデルによって生成された 構成済みの回答 を取得するには、 RAG パターンまたはエージェント検索の使用を検討します。

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

2.124817371368408
1
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.

2.0705394744873047
16
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.

2.041472911834717
38
Lakeside B & B
Description: 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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.
Caption: 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.

2.084540843963623
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<em> city. #1 </em>Hotel in the area listed by Traveler magazine. Free WiFi, Flexible check in/out, Fitness Center & espresso in room.

...

このクイックスタートでは、セマンティックランク付けを既存のインデックスに追加する方法について説明します。 hotels-sample-index または独自のものを使用できます。

Azure AI 検索のセマンティックランク付けは、Microsoft の機械読解を使用して検索結果を再スコアリングして、セマンティック関連性が最も高い一致を一覧の最上位に昇格させる、クエリ側の機能です。コンテンツとクエリによっては、セマンティックランク付けによって、開発者の労力を最小限に抑えながら検索の関連性を大幅に向上させることができます。

再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。セマンティックランク付けは、情報的または説明的なテキストに最も効果的です。

このクイックスタートでは、次の方法について説明します。

検索インデックスにセマンティック構成を追加する
セマンティックパラメーターをクエリに追加する

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
セマンティックランカーが有効になっている、Basic レベル以上の Azure AI Search サービス。
説明的または詳細なテキストフィールドを持つ新規または既存のインデックス。インデックスで取得可能と見なされます。このクイックスタートでは、 hotels-sample-index を前提としています。

アクセスを構成する

ロールの割り当てで API キーまたは Microsoft Entra ID を使用して、Azure AI Search サービスに接続できます。キーの方が簡単に使い始めることができますが、安全性が高いのはロールの方です。

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

Azure portal にサインインし、検索サービスを選択します。
次に、左側のペインで [設定]>[キー] を選択します。
[API アクセス制御] で、[両方] を選択します。

このオプションでは、キーベース認証とキーレス認証の両方が有効になります。ロールを割り当てた後、この手順に戻り、[ ロールベースのアクセス制御] を選択できます。
左側のウィンドウで、[ アクセス制御 (IAM)] を選択します。
[追加>][ロール割り当ての追加] の順に選択します。
ユーザーアカウントに次のロールを割り当てます。
- Search Service サービス貢献者
- 検索インデックスデータ共同作成者

詳細については、「ロールを使用して Azure AI 検索に接続する」を参照してください。

インデックスから始める

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

Azure portal にサインインし、ご利用の検索サービスを探します。
[検索の管理>Indexes] で、hotels-sample-index を開きます。インデックスにセマンティック構成がないことを確認します。

インデックスが操作可能であることを確認するには、クエリを実行します。 検索エクスプローラーで、セマンティックランク付けが適用される前に応答を表示できるように、この検索文字列 "walking distance to live music" を入力します。

応答は、フルテキスト検索の既定の BM25 L1 ランカーによってスコア付けされた次の例のようになります。読みやすくするために、この例では "HotelName" "HotelId" フィールドと "Description" フィールドのみを選択します。

このクエリはキーワード検索です。結果には、クエリ用語 (ウォーキング、距離、ライブ、音楽) または言語バリアント (ウォーク、リビング) に関する逐語的一致が含まれます。

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime ___location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

後で、セマンティックランク付けが構成された後に、応答がどのように変化するかを確認するために、このクエリをもう一度試すことができます。

ヒント

セマンティック構成は、Azure portal で追加できます。ただし、セマンティック構成をプログラムで追加する方法については、このクイックスタートの手順に進んでください。

クライアントを設定する

このクイックスタートでは、REST クライアントと Azure AI Search REST API を使用してセマンティックランカーを構成して使用します。

このクイックスタートでは、VISUAL Studio Code と REST クライアント拡張機能をお勧めします。

ヒント

ソースコードをダウンロードして完成したプロジェクトから開始することも、以下の手順に従って独自のアプリケーションを作成することもできます。

Visual Studio Code を起動し、 semantic-search-index-update.rest ファイルを開くか、新しいファイルを作成します。
上部で、検索サービス、承認、およびインデックス名の環境変数を設定します。
- @searchURLの場合は、Azure portal にサインインし、検索サービスの [概要] ページから URL をコピーします。
- @personalAccessTokenについては、「キーを使用せずに接続する」の手順に従って、個人用アクセストークンを取得します。

接続をテストするには、最初の要求を送信します。

### List existing indexes by name (verify the connection)
 GET  {{searchUrl}}/indexes?api-version=2025-08-01-preview&$select=name  HTTP/1.1
 Authorization: Bearer {{personalAccessToken}}

[ 送信済み要求] を選択します。
この GET 要求の出力は、既存のインデックスの一覧を返します。 HTTP 200 Success 状態コードとインデックスの一覧 (このクイックスタートで使用される hotels-sample-index を含む) を取得する必要があります。

インデックスを更新する

REST API を使用してインデックスを更新するには、スキーマ全体に加えて、行う変更を指定する必要があります。この要求では、hotels-sample-index スキーマとセマンティック構成が提供されます。変更は、次の JSON で構成されます。

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

インデックス名、操作、および完全な JSON スキーマを指定する POST 要求を作成します。スキーマのすべての必須要素が存在する必要があります。この要求には、hotels-sample-index の完全なスキーマとセマンティック構成が含まれます。

POST  {{searchUrl}}/indexes?api-version=2025-08-01-preview  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

{
   "name": "hotels-sample-index",
   "fields": [
       { "name": "HotelId", "type": "Edm.String", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "key": true },
       { "name": "HotelName", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
       { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
       { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
       { "name": "Category", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
       { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
       { "name": "ParkingIncluded", "type": "Edm.Boolean", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
       { "name": "LastRenovationDate", "type": "Edm.DateTimeOffset", "searchable": false, "filterable": false, "retrievable": true, "stored": true, "sortable": true, "facetable": false },
       { "name": "Rating", "type": "Edm.Double", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": true, "facetable": true },
       { "name": "Address", "type": "Edm.ComplexType", "fields": [
          { "name": "StreetAddress", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
          { "name": "City", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "StateProvince", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "PostalCode", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "Country", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" }]},
       { "name": "Location", "type": "Edm.GeographyPoint", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": true, "facetable": false },
       { "name": "Rooms", "type": "Collection(Edm.ComplexType)", "fields": [
          { "name": "Description", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "en.microsoft" },
          { "name": "Description_fr", "type": "Edm.String", "searchable": true, "filterable": false, "retrievable": true, "stored": true, "sortable": false, "facetable": false, "analyzer": "fr.microsoft" },
          { "name": "Type", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "BaseRate", "type": "Edm.Double", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "BedOptions", "type": "Edm.String", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" },
          { "name": "SleepsCount", "type": "Edm.Int64", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "SmokingAllowed", "type": "Edm.Boolean", "searchable": false, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true },
          { "name": "Tags", "type": "Collection(Edm.String)", "searchable": true, "filterable": true, "retrievable": true, "stored": true, "sortable": false, "facetable": true, "analyzer": "en.microsoft" }]},
       { "name": "id", "type": "Edm.String", "searchable": false, "filterable": false, "retrievable": false, "stored": true, "sortable": false, "facetable": false },
       { "name": "rid", "type": "Edm.String", "searchable": false, "filterable": false, "retrievable": false, "stored": true, "sortable": false, "facetable": false }],
  "scoringProfiles": [],
  "suggesters": [],
  "analyzers": [],
  "normalizers": [],
  "tokenizers": [],
  "tokenFilters": [],
  "charFilters": [],
  "similarity": {
    "@odata.type": "#Microsoft.Azure.Search.BM25Similarity"
  },
  "semantic": {
    "configurations": [
      {
        "name": "semantic-config",
        "flightingOptIn": false,
        "rankingOrder": "BoostedRerankerScore",
        "prioritizedFields": {
          "titleField": {
            "fieldName": "HotelName"
          },
          "prioritizedContentFields": [
            {
              "fieldName": "Description"
            }
          ],
          "prioritizedKeywordsFields": [
            {
              "fieldName": "Tags"
            }
          ]
        }
      }
    ]
  }
}

[ 送信済み要求] を選択します。
この POST 要求の出力は、HTTP 200 成功ステータスメッセージです。

セマンティッククエリを実行する

必要なセマンティックパラメーターには、 query_type と semantic_configuration_nameが含まれます。最小パラメーターを使用した基本的なセマンティッククエリの例を次に示します。

semantic-search-query.rest ファイルを開くか、新しいファイルを作成します。
ファイルの先頭で、検索サービス、承認、およびインデックス名の環境変数を設定します。
- @searchURLの場合は、Azure portal にサインインし、検索サービスの [概要] ページから URL をコピーします。
- @personalAccessTokenについては、「キーを使用せずに接続する」の手順に従って、個人用アクセストークンを取得します。

hotels-sample-index を返す GET 要求との接続をテストします。

GET  {{searchUrl}}/indexes/hotels-sample-index?api-version=2025-08-01-preview  HTTP/1.1
Authorization: Bearer {{personalAccessToken}}

セマンティッククエリの種類と構成名を含むクエリを送信します。

 POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-08-01-preview  HTTP/1.1
 Content-Type: application/json
 Authorization: Bearer {{personalAccessToken}}

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

出力は JSON 検索結果で構成されます。 13 軒のホテルがクエリと一致します。この例には、上位 7 つが含まれています。

{
   "@odata.count": 13,
   "@search.answers": [],
   "value": [
     {
       "@search.score": 5.074317,
       "@search.rerankerScore": 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.score": 5.5153193,
       "@search.rerankerScore": 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.score": 4.8959594,
       "@search.rerankerScore": 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."
     },
     {
       "@search.score": 0.7334347,
       "@search.rerankerScore": 1.9615401029586792,
       "HotelId": "39",
       "HotelName": "White Mountain Lodge & Suites",
       "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
     },
     {
       "@search.score": 1.5502293,
       "@search.rerankerScore": 1.9085469245910645,
       "HotelId": "15",
       "HotelName": "By the Market Hotel",
       "Description": "Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
     },
     {
       "@search.score": 1.7595702,
       "@search.rerankerScore": 1.90234375,
       "HotelId": "49",
       "HotelName": "Swirling Currents Hotel",
       "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
     },
     {
       "@search.score": 2.0364518,
       "@search.rerankerScore": 1.9012802839279175,
       "HotelId": "31",
       "HotelName": "Country Residence Hotel",
       "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
     }
   ]
 }

キャプションを返す

必要に応じて、キャプションを追加してテキストの一部を抽出し、重要な用語や語句にヒット強調表示を適用できます。このクエリでは、ヒット強調表示を含むキャプションが追加されます。

captions パラメーターを追加し、要求を送信します。

POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-08-01-preview  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

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

出力は同じ結果で構成され、 "@search.captions"が追加されます。 1 つのドキュメントの JSON を次に示します。各マッチには、検索スコア、プレーンテキスト形式とハイライト形式のキャプション、および選択フィールドが含まれます。

{
   "@search.score": 5.074317,
   "@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. Visit Seattle Art Museum by day, and then head over to Benaroya Hall to catch the evening's concert performance.",
       "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."
     }
   ],
   "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."
}

セマンティック回答を返す

この最後のクエリでは、セマンティック回答を返します。

セマンティックランカーは、質問の特性を持つクエリ文字列に対する回答を生成できます。生成された回答はコンテンツから逐語的に抽出されるため、チャット完了モデルに期待するような構成済みのコンテンツは含まれません。セマンティック回答がシナリオに役立たない場合は、コードから semantic_answers を省略できます。

セマンティック回答を生成するには、質問と回答を密接に調整する必要があり、モデルは質問に明確に回答するコンテンツを見つける必要があります。候補の回答が信頼度のしきい値を満たしていない場合、モデルは回答を返しません。この例ではデモ用に、質問が応答を取得するように設計されているため、構文を確認できます。

質問をする検索文字列を使用して要求を作成します。

POST {{searchUrl}}/indexes/hotels-sample-index/docs/search?api-version=2025-08-01-preview  HTTP/1.1
Content-Type: application/json
Authorization: Bearer {{personalAccessToken}}

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

出力は、新しいクエリの 41 件の結果で構成され、読みたいユーザー向けのホテルに関するクエリの質問に対する "@search.answers" が含まれます。

回答は、インデックスから取得された 逐語的なコンテンツ であり、ユーザーが表示すると予想される語句が見つからない可能性があることを思い出してください。チャット完了モデルによって生成された 構成済みの回答 を取得するには、 RAG パターンまたはエージェント検索の使用を検討します。

この例では、回答は質問に強く適合すると見なされます。

{
  "@odata.count": 41,
  "@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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply.",
      "score": 0.9829999804496765
    }
  ],
  "value": [
    {
      "@search.score": 2.0361428,
      "@search.rerankerScore": 2.124817371368408,
      "HotelId": "1",
      "HotelName": "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."
    },
    {
      "@search.score": 3.759768,
      "@search.rerankerScore": 2.0705394744873047,
      "HotelId": "16",
      "HotelName": "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."
    },
    {
      "@search.score": 0.7308748,
      "@search.rerankerScore": 2.041472911834717,
      "HotelId": "38",
      "HotelName": "Lakeside B & B",
      "Description": "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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
    },
    {
      "@search.score": 3.391012,
      "@search.rerankerScore": 2.0231292247772217,
      "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": 1.3198771,
      "@search.rerankerScore": 2.021622657775879,
      "HotelId": "15",
      "HotelName": "By the Market Hotel",
      "Description": "Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
    },
    {
      "@search.score": 1.3983066,
      "@search.rerankerScore": 2.005582809448242,
      "HotelId": "5",
      "HotelName": "Red Tide Hotel",
      "Description": "On entering this charming hotel in Scarlet Harbor, you'll notice an uncommon blend of antiques, original artwork, and contemporary comforts that give this hotel its signature look. Each suite is furnished to accentuate the views and unique characteristics of the building's classic architecture. No two suites are alike. However, all guests are welcome in the mezzanine plaza, the surrounding gardens, and the northside terrace for evening refreshments."
    },
    {
      "@search.score": 1.4815493,
      "@search.rerankerScore": 1.9739465713500977,
      "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."
    }
  ]
}

このクイックスタートでは、セマンティックランク付けを既存のインデックスに追加する方法について説明します。 hotels-sample-index または独自のものを使用できます。

Azure AI 検索のセマンティックランク付けは、Microsoft の機械読解を使用して検索結果を再スコアリングして、セマンティック関連性が最も高い一致を一覧の最上位に昇格させる、クエリ側の機能です。コンテンツとクエリによっては、セマンティックランク付けによって、開発者の労力を最小限に抑えながら検索の関連性を大幅に向上させることができます。

再構築を必要とせず、セマンティック構成を既存のインデックスに追加できます。セマンティックランク付けは、情報的または説明的なテキストに最も効果的です。

このクイックスタートでは、次の方法について説明します。

検索インデックスにセマンティック構成を追加する
セマンティックパラメーターをクエリに追加する

前提条件

アクティブなサブスクリプションが含まれる Azure アカウント。無料でアカウントを作成できます。
セマンティックランカーが有効になっている、Basic レベル以上の Azure AI Search サービス。
説明的または詳細なテキストフィールドを持つ新規または既存のインデックス。インデックスで取得可能と見なされます。このクイックスタートでは、 hotels-sample-index を前提としています。

アクセスを構成する

ロールの割り当てで API キーまたは Microsoft Entra ID を使用して、Azure AI Search サービスに接続できます。キーの方が簡単に使い始めることができますが、安全性が高いのはロールの方です。

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

Azure portal にサインインし、検索サービスを選択します。
次に、左側のペインで [設定]>[キー] を選択します。
[API アクセス制御] で、[両方] を選択します。

このオプションでは、キーベース認証とキーレス認証の両方が有効になります。ロールを割り当てた後、この手順に戻り、[ ロールベースのアクセス制御] を選択できます。
左側のウィンドウで、[ アクセス制御 (IAM)] を選択します。
[追加>][ロール割り当ての追加] の順に選択します。
ユーザーアカウントに次のロールを割り当てます。
- Search Service サービス貢献者
- 検索インデックスデータ共同作成者

詳細については、「ロールを使用して Azure AI 検索に接続する」を参照してください。

インデックスから始める

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

Azure portal にサインインし、ご利用の検索サービスを探します。
[検索の管理>Indexes] で、hotels-sample-index を開きます。インデックスにセマンティック構成がないことを確認します。

インデックスが操作可能であることを確認するには、クエリを実行します。 検索エクスプローラーで、セマンティックランク付けが適用される前に応答を表示できるように、この検索文字列 "walking distance to live music" を入力します。

応答は、フルテキスト検索の既定の BM25 L1 ランカーによってスコア付けされた次の例のようになります。読みやすくするために、この例では "HotelName" "HotelId" フィールドと "Description" フィールドのみを選択します。

このクエリはキーワード検索です。結果には、クエリ用語 (ウォーキング、距離、ライブ、音楽) または言語バリアント (ウォーク、リビング) に関する逐語的一致が含まれます。

"@odata.count": 13,
"value": [
  {
    "@search.score": 5.5153193,
    "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.074317,
    "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.8959594,
    "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."
  },
  {
    "@search.score": 2.5966604,
    "HotelId": "35",
    "HotelName": "Bellevue Suites",
    "Description": "Comfortable city living in the very center of downtown Bellevue. Newly reimagined, this hotel features apartment-style suites with sleeping, living and work spaces. Located across the street from the Light Rail to downtown. Free shuttle to the airport."
  },
  {
    "@search.score": 2.566386,
    "HotelId": "47",
    "HotelName": "Country Comfort Inn",
    "Description": "Situated conveniently at the north end of the village, the inn is just a short walk from the lake, offering reasonable rates and all the comforts home inlcuding living room suites and functional kitchens. Pets are welcome."
  },
  {
    "@search.score": 2.2405157,
    "HotelId": "9",
    "HotelName": "Smile Up Hotel",
    "Description": "Experience the fresh, modern downtown. Enjoy updated rooms, bold style & prime ___location. Don't miss our weekend live music series featuring who's new/next on the scene."
  },
  {
    "@search.score": 2.1737604,
    "HotelId": "8",
    "HotelName": "Foot Happy Suites",
    "Description": "Downtown in the heart of the business district. Close to everything. Leave your car behind and walk to the park, shopping, and restaurants. Or grab one of our bikes and take your explorations a little further."
  },
  {
    "@search.score": 2.0364518,
    "HotelId": "31",
    "HotelName": "Country Residence Hotel",
    "Description": "All of the suites feature full-sized kitchens stocked with cookware, separate living and sleeping areas and sofa beds. Some of the larger rooms have fireplaces and patios or balconies. Experience real country hospitality in the heart of bustling Nashville. The most vibrant music scene in the world is just outside your front door."
  },
  {
    "@search.score": 1.7595702,
    "HotelId": "49",
    "HotelName": "Swirling Currents Hotel",
    "Description": "Spacious rooms, glamorous suites and residences, rooftop pool, walking access to shopping, dining, entertainment and the city center. Each room comes equipped with a microwave, a coffee maker and a minifridge. In-room entertainment includes complimentary W-Fi and flat-screen TVs. "
  },
  {
    "@search.score": 1.5502293,
    "HotelId": "15",
    "HotelName": "By the Market Hotel",
    "Description": "Book now and Save up to 30%. Central ___location. Walking distance from the Empire State Building & Times Square, in the Chelsea neighborhood. Brand new rooms. Impeccable service."
  },
  {
    "@search.score": 1.3302404,
    "HotelId": "42",
    "HotelName": "Rock Bottom Resort & Campground",
    "Description": "Rock Bottom is nestled on 20 unspoiled acres on a private cove of Rock Bottom Lake. We feature both lodging and campground accommodations to suit just about every taste. Even though we are out of the traffic of the city, getting there is only a short drive away."
  },
  {
    "@search.score": 0.9050383,
    "HotelId": "38",
    "HotelName": "Lakeside B & B",
    "Description": "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. Save up to 30 percent. Valid Now through the end of the year. Restrictions and blackouts may apply."
  },
  {
    "@search.score": 0.7334347,
    "HotelId": "39",
    "HotelName": "White Mountain Lodge & Suites",
    "Description": "Live amongst the trees in the heart of the forest. Hike along our extensive trail system. Visit the Natural Hot Springs, or enjoy our signature hot stone massage in the Cathedral of Firs. Relax in the meditation gardens, or join new friends around the communal firepit. Weekend evening entertainment on the patio features special guest musicians or poetry readings."
  }
]

後で、セマンティックランク付けが構成された後に、応答がどのように変化するかを確認するために、このクエリをもう一度試すことができます。

ヒント

セマンティック構成は、Azure portal で追加できます。ただし、セマンティック構成をプログラムで追加する方法については、このクイックスタートの手順に進んでください。

クライアントを設定する

このクイックスタートでは、IDE と @azure/search-documents クライアントライブラリを使用して、既存の検索インデックスにセマンティックランク付けを追加します。

このクイックスタートでは、お使いのコンピューターに次のものが用意されていることを前提としています。

このクイックスタート用の Visual Studio Code。
サンプルを実行するための Node.js(LTS)。
サンプルコードの作成に使用する TypeScript。

ヒント

ソースコードをダウンロードして完成したプロジェクトから開始することも、以下の手順に従って独自のアプリケーションを作成することもできます。

ローカル開発環境を設定する

新しいディレクトリで Visual Studio Code を開始します。

mkdir semantic-ranking-quickstart && cd semantic-ranking-quickstart
code .

プロジェクトディレクトリに ESM モジュール用の新しいパッケージを作成します。
```
npm init -y
npm pkg set type=module
```
azure-search-documents 含む開発パッケージをインストールします。
```
npm install @azure/identity @azure/search-documents dotenv
```
開発依存関係パッケージをインストールします。
```
npm install dotenv @types/node --save-dev
```

ESM モジュールを有効にしてモジュールの解決を設定するために、プロジェクトディレクトリに tsconfig.json ファイルを作成します。

 {
   "compilerOptions": {
     "target": "es2022",
     "module": "esnext",
     "moduleResolution": "bundler",
     "rootDir": "./src",
     "outDir": "./dist/",
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "strict": true,
     "skipLibCheck": true,
     "declaration": true,
     "sourceMap": true,
     "resolveJsonModule": true,
     "moduleDetection": "force",
     "allowSyntheticDefaultImports": true,
     "verbatimModuleSyntax": false
   },
   "include": [
     "src/**/*.ts"
   ],
   "exclude": [
     "node_modules/**/*",
     "**/*.spec.ts"
   ]
 }

package.json を更新して、TypeScript ファイルをビルドするスクリプトを追加します。 scripts セクションに次の行を追加します。
```
"build": "tsc"
```
.env を作成し、検索サービスエンドポイントを指定します。エンドポイントは、検索サービスの [概要 ] ページの Azure portal から取得できます。
```
AZURE_SEARCH_ENDPOINT=YOUR-SEARCH-SERVICE-ENDPOINT
AZURE_SEARCH_INDEX_NAME=hotels-sample-index
SEMANTIC_CONFIGURATION_NAME=semantic-config
```
プロジェクトディレクトリに src ディレクトリを作成します。
```
mkdir src
```

Azure portal にサインインした場合は、Azure にサインインします。不明な場合は、Azure CLI または Azure PowerShell を使用してログインします。 az login または az connect。複数のテナントとサブスクリプションがある場合、接続方法については、「クイックスタート: キーなしで接続する」を参照してください。

共通の認証ファイルを作成する

./src ファイルを読み取り、環境変数と認証情報を保持するために、config.ts に .env というファイルを作成します。次のコードをコピーし、変更しないでください。このファイルは、このクイックスタート内の他のすべてのファイルで使用されます。

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

// Configuration - use environment variables
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-index";
export const semanticConfigurationName = process.env.SEMANTIC_CONFIGURATION_NAME || "semantic-config";

// Create credential
export const credential = new DefaultAzureCredential();

console.log(`Using Azure Search endpoint: ${searchEndpoint}`);
console.log(`Using index name: ${indexName}\n\n`);

// Hotel document interface
export interface HotelDocument {
    "@search.action"?: string;
    HotelId: string;
    HotelName: string;
    Description: string;
    Category: string;
    Tags: string[];
    ParkingIncluded: string;
    LastRenovationDate: string;
    Rating: number;
    Address: {
        StreetAddress: string;
        City: string;
        StateProvince: string;
        PostalCode: string;
        Country: string;
    };
}

インデックススキーマを取得する

このセクションでは、検索サービスの既存の hotels-sample-index インデックスの設定を取得します。

./src に getIndexSettings.ts という名前のファイルを作成し、次のコードをコピーします。

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

const indexClient = new SearchIndexClient(searchEndpoint, credential);

console.log('Updating semantic search index...');

// Get the existing schema
const index = await indexClient.getIndex(indexName);

console.log(`Index name: ${index.name}`);
console.log(`Number of fields: ${index.fields.length}`);

for(const field of index.fields) {

    // @ts-ignore
    console.log(`Field: ${field.name}, Type: ${field.type}, Searchable: ${field.searchable}`);
}

if(index.semanticSearch && index.semanticSearch.configurations) {
    console.log(`Semantic search configurations: ${index.semanticSearch.configurations.length}`);
    for(const config of index.semanticSearch.configurations) {
        console.log(`Configuration name: ${config.name}`);
        console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
    }
} else {
    console.log("No semantic configuration exists for this index.");
}

コードを実行します。

npm run build && node -r dotenv/config dist/getIndexSettings.js

出力は、インデックスの名前、フィールドの一覧、セマンティック構成が存在するかどうかを示すステートメントです。このクイックスタートでは、メッセージは「No semantic configuration exists for this index」と表示されるはずです。

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

検索サービス上の既存の ./src インデックスにセマンティック構成を追加するために、updateIndexSettings.ts に hotels-sample-index という名前のファイルを作成し、次のコードをコピーします。この操作では検索ドキュメントは削除されません。構成が追加された後も、インデックスは引き続き動作します。

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

try {

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

    // Add the new semantic configuration to the existing index
    if (existingIndex.semanticSearch && existingIndex.semanticSearch.configurations) {
        existingIndex.semanticSearch.configurations.push(newSemanticConfiguration);
    } else {
        const configExists = existingIndex.semanticSearch?.configurations?.some(
            config => config.name === semanticConfigurationName
        );
        if (!configExists) {
            existingIndex.semanticSearch = {
                configurations: [newSemanticConfiguration]
            };
        }
    }

    await indexClient.createOrUpdateIndex(existingIndex);

    const updatedIndex = await indexClient.getIndex(indexName);

    console.log(`Semantic configurations:`);
    console.log("-".repeat(40));

    if (updatedIndex.semanticSearch && updatedIndex.semanticSearch.configurations) {
        for (const config of updatedIndex.semanticSearch.configurations) {
            console.log(`Configuration name: ${config.name}`);
            console.log(`Title field: ${config.prioritizedFields.titleField?.name}`);
            console.log(`Keywords fields: ${config.prioritizedFields.keywordsFields?.map(f => f.name).join(", ")}`);
            console.log(`Content fields: ${config.prioritizedFields.contentFields?.map(f => f.name).join(", ")}`);
            console.log("-".repeat(40));
        }
    } else {
        console.log("No semantic configurations found.");
    }

    console.log("Semantic configuration updated successfully.");
} catch (error) {
    console.error("Error updating semantic configuration:", error);
}

コードを実行します。

npm run build && node -r dotenv/config dist/updateIndexSettings.js

出力は、先ほど追加したセマンティック構成「Semantic configuration updated successfully.」です。

セマンティッククエリを実行する

hotels-sample-index インデックスにセマンティック構成が設定されると、セマンティックパラメーターを含むクエリを実行できるようになります。

インデックスのセマンティッククエリを作成するために、./src に semanticQuery.ts という名前のファイルを作成し、次のコードをコピーします。これは、セマンティックランク付けを呼び出すための最小要件です。

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

let rowNumber = 1;
for await (const result of results.results) {

    // Log each result
    const doc = result.document;
    const score = result.score;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelId: ${doc.HotelId}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);
}

コードを実行します。

npm run build && node -r dotenv/config dist/semanticQuery.js

出力は、 rerankerScoreDisplayで並べ替えられた 13 個のドキュメントで構成されている必要があります。

キャプションを返す

必要に応じて、キャプションを追加してテキストの一部を抽出し、重要な用語や語句にヒット強調表示を適用できます。このクエリでは、キャプションが追加されます。

クエリにキャプションを追加するために、./src に semanticQueryReturnCaptions.ts という名前のファイルを作成し、次のコードをコピーします。

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

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

// Debug info
console.log(`Using semantic configuration: ${semanticConfigurationName}`);
console.log("Search query: walking distance to live music");

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

console.log(`Found ${results.count} results with semantic search\n`);
let rowNumber = 1;

for await (const result of results.results) {
    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;

    console.log(`Search result #${rowNumber++}:`);
    console.log(`  Re-ranker Score: ${rerankerScoreDisplay}`);
    console.log(`  HotelName: ${doc.HotelName}`);
    console.log(`  Description: ${doc.Description || 'N/A'}\n`);

    // Caption handling with better debugging
    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];

        if (caption.highlights) {
            console.log(`  Caption with highlights: ${caption.highlights}`);
        } else if (caption.text) {
            console.log(`  Caption text: ${caption.text}`);
        } else {
            console.log(`  Caption exists but has no text or highlights content`);
        }
    } else {
        console.log("  No captions found for this result");
    }
    console.log("-".repeat(60));
}

コードを実行します。

npm run build && node -r dotenv/config dist/semanticQueryReturnCaptions.js

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

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.

セマンティック回答を返す

この最後のクエリでは、セマンティック回答を返します。

セマンティックランカーは、質問の特性を持つクエリ文字列に対する回答を生成できます。生成された回答はコンテンツから逐語的に抽出されるため、チャット完了モデルに期待するような構成済みのコンテンツは含まれません。セマンティック回答がシナリオに役立たない場合は、コードから semantic_answers を省略できます。

セマンティック回答を生成するには、質問と回答を密接に調整する必要があり、モデルは質問に明確に回答するコンテンツを見つける必要があります。候補の回答が信頼度のしきい値を満たしていない場合、モデルは回答を返しません。この例ではデモ用に、質問が応答を取得するように設計されているため、構文を確認できます。

セマンティックな回答を取得するために、./src に semanticAnswer.ts という名前のファイルを作成し、次のコードをコピーします。

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("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"]
});

console.log(`Answers:\n\n`);
let rowNumber = 1; 

// Extract semantic answers from the search results
const semanticAnswers = results.answers;
for (const answer of semanticAnswers || []) {
    console.log(`Semantic answer result #${rowNumber++}:`);
    if (answer.highlights) {
        console.log(`Semantic Answer: ${answer.highlights}`);
    } else {
        console.log(`Semantic Answer: ${answer.text}`);
    }
    console.log(`Semantic Answer Score: ${answer.score}\n\n`);
}

console.log(`Search Results:\n\n`);
rowNumber = 1;

// Iterate through the search results
for await (const result of results.results) {


    // Log each result
    const doc = result.document;
    const rerankerScoreDisplay = result.rerankerScore;
    console.log(`Search result #${rowNumber++}:`);
    console.log(`${rerankerScoreDisplay}`);
    console.log(`${doc.HotelName}`);
    console.log(`${doc.Description || 'N/A'}`);

    const captions = result.captions;

    if (captions && captions.length > 0) {
        const caption = captions[0];
        if (caption.highlights) {
            console.log(`Caption: ${caption.highlights}\n`);
        } else {
            console.log(`Caption: ${caption.text}\n`);
        }
    }
}

コードを実行します。

npm run build && node -r dotenv/config dist/semanticAnswer.js

出力は次の例のようになります。質問に対する最良の答えは、いずれかの結果から取得されます。

回答は、インデックスから取得された 逐語的なコンテンツ であり、ユーザーが表示すると予想される語句が見つからない可能性があることを思い出してください。チャット完了モデルによって生成された 構成済みの回答 を取得するには、 RAG パターンまたはエージェント検索の使用を検討します。
```
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 library 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
```

次の方法で共有

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

前提条件

アクセスを構成する

インデックスから始める

クライアントを設定する

ライブラリのインストール

Azure にサインインする

インデックスを更新する

セマンティック クエリを実行する

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

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

セマンティック回答の出力

前提条件

アクセスを構成する

インデックスから始める

クライアントを設定する

ローカル開発環境を設定する

Azure にサインインする

共通の認証ファイルを作成する

インデックス スキーマを取得する

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

セマンティック クエリを実行する

キャプションを返す

セマンティック回答を返す

前提条件

アクセスを構成する

インデックスから始める

クライアントを設定する

ローカル開発環境を設定する

Azure にサインインする

共通の構成クラスを作成する

インデックス スキーマを取得する

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

セマンティック クエリを実行する

キャプションを返す

セマンティック回答を返す

前提条件

アクセスを構成する

インデックスから始める

クライアントを設定する

パッケージのインストールと環境変数の設定

Azure にサインインする

インデックスを更新する

セマンティック クエリを実行する

キャプションを返す

セマンティック回答を返す

前提条件

アクセスを構成する

インデックスから始める

クライアントを設定する

インデックスを更新する

セマンティック クエリを実行する

キャプションを返す

セマンティック回答を返す

前提条件

アクセスを構成する

インデックスから始める

クライアントを設定する

ローカル開発環境を設定する

Azure にサインインする

共通の認証ファイルを作成する

インデックス スキーマを取得する

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

セマンティック クエリを実行する

キャプションを返す

セマンティック回答を返す

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

関連コンテンツ

フィードバック

その他のリソース

セマンティッククエリを実行する

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

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

インデックススキーマを取得する

セマンティッククエリを実行する

インデックススキーマを取得する

セマンティッククエリを実行する

セマンティッククエリを実行する

セマンティッククエリを実行する

インデックススキーマを取得する

セマンティッククエリを実行する