クイックスタート: Azure AI 検索からのグラウンディングデータを使用した生成検索 (RAG)

[アーティクル]
01/13/2025

このクイックスタートでは、Azure AI 検索のインデックス付きコンテンツに対する会話型検索エクスペリエンスのために、チャット補完モデルにクエリを送信する方法について説明します。 Azure portal を使ってリソースをセットアップした後、Python コードを実行して API を呼び出します。

前提条件

Python 拡張機能と Jupyter パッケージを持つ Visual Studio Code。詳細については、「Visual Studio Code での Python」を参照してください。
ロールを割り当てるアクセス許可を持つ Azure サブスクリプション。無料で作成できます。
Azure OpenAI
- 使用するチャット補完モデル (gpt-4o、gpt-4o-mini、または同等のモデル) をサポートするリージョンを選択します。
- Azure AI Foundry でチャット補完モデルをデプロイするか、別の方法を使用します。
Azure AI Search
- Azure OpenAI と同じリージョン。
- Basic レベル以上が推奨されます。
- セマンティックランク付けを有効にします。
- ロールベースのアクセス制御を有効にします (以下を参照)。

同一リージョンの要件を満たすには、まず使用するチャットモデルのリージョンを確認します。リージョンを特定したら、Azure AI 検索が同じリージョンで使用できることを確認します。

デプロイされたモデルの名前を確認し、両方の Azure リソースのエンドポイントを手元に用意してください。この情報は、この後の手順で入力します。

ファイルをダウンロードする

GitHub から Jupyter ノートブックをダウンロードして、このクイックスタートの要求を送信します。詳細については、「GitHub からファイルをダウンロードする」を参照してください。

ローカルシステムで新しいファイルを開始し、この記事の手順を使用して手動で要求を作成することもできます。

アクセスを構成する

検索エンドポイントへの要求は、認証および承認する必要があります。このタスクには API キーまたはロールを使用できます。キーの方が簡単に使い始めることができますが、安全性が高いのはロールの方です。このクイックスタートでは、ロールを前提としています。

2 つのクライアントを設定するため、両方のリソースに対するアクセス許可が必要です。

Azure AI 検索は、ローカルシステムからクエリ要求を受信します。ホテルサンプルのインデックスが既に存在する場合は、検索インデックスデータ閲覧者ロールの割り当てを自分に割り当てます。存在しない場合は、Search Service 共同作成者と検索インデックスデータ共同作成者のロールを自分に割り当てて、インデックスを作成してクエリを実行できるようにします。

Azure OpenAI は、ローカルシステムからクエリと検索結果を受け取ります。 Azure OpenAI で Cognitive Services OpenAI ユーザー ロールを自分に割り当てます。

Azure portal にサインインします。
ロールベースのアクセス用に Azure AI 検索を構成します。
1. Azure portal で Azure AI 検索サービスを見つけます。
2. 左側のメニューで、[設定]>[キー] を選択して、[ロールベースのアクセス制御] または [両方] のいずれかを選択します。
ロールを割り当てます。
1. 左側のメニューで、[アクセス制御 (IAM)] を選択します。
2. Azure AI 検索で、検索インデックスを作成、読み込み、クエリを実行するために次のロールを選択し、それらを Microsoft Entra ID ユーザー ID に割り当てます。
  - 検索インデックスデータ共同作成者
  - Search Service Contributor
3. Azure OpenAI で、[アクセス制御 (IAM)] を選択して、このロールを Azure OpenAI で自分に割り当てます。
  - Cognitive Services OpenAI ユーザー

アクセス許可が有効になるまで数分かかる場合があります。

インデックスを作成する

検索インデックスは、チャットモデルの基となるデータを提供します。 hotels-sample-index をお勧めします。これは数分で作成でき、任意の検索サービスレベルで実行されます。このインデックスは、組み込みのサンプルデータを使って作成します。

Azure portal で、ご利用の検索サービスを探します。
[概要] ホームページで、[データのインポート] を選択して、ウィザードを開始します。
[データへの接続] ページで、ドロップダウンリストから [サンプル] を選択します。
[hotels-sample] を選択します。
[次へ] を選んで残りのページに進み、既定値をそのまま使用します。
インデックスが作成されたら、左側のメニューの [検索管理]>[インデックス] を選択して、インデックスを開きます。
[JSON の編集] を選択します。
インデックスの末尾までスクロールすると、インデックスに追加できる構成のプレースホルダーがあります。
```
"analyzers": [],
"tokenizers": [],
"tokenFilters": [],
"charFilters": [],
"normalizers": [],
```

"normalizers" の後の新しい行に、次のセマンティック構成を貼り付けます。この例では "defaultConfiguration" を指定します。これは、このクイックスタートの実行に重要です。

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

変更内容を保存します。

インデックスをテストするには、Search エクスプローラーで次のクエリを実行します: complimentary breakfast。

出力は次の例のように表示されます。検索エンジンから直接返される結果は、フィールドとその逐語的な値と、セマンティックランカーを使用する場合は、検索スコアやセマンティックランカースコア、キャプションなどのメタデータで構成されます。ここでは select ステートメントを使用して、HotelName、Description、Tags フィールドのみを返しています。

{
"@odata.count": 18,
"@search.answers": [],
"value": [
   {
      "@search.score": 2.2896252,
      "@search.rerankerScore": 2.506816864013672,
      "@search.captions": [
      {
         "text": "Head Wind Resort. Suite. coffee in lobby\r\nfree wifi\r\nview. The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a **complimentary continental breakfast** in the lobby, and free Wi-Fi throughout the hotel..",
         "highlights": ""
      }
      ],
      "HotelName": "Head Wind Resort",
      "Description": "The best of old town hospitality combined with views of the river and cool breezes off the prairie. Our penthouse suites offer views for miles and the rooftop plaza is open to all guests from sunset to 10 p.m. Enjoy a complimentary continental breakfast in the lobby, and free Wi-Fi throughout the hotel.",
      "Tags": [
      "coffee in lobby",
      "free wifi",
      "view"
      ]
   },
   {
      "@search.score": 2.2158256,
      "@search.rerankerScore": 2.288334846496582,
      "@search.captions": [
      {
         "text": "Swan Bird Lake Inn. Budget. continental breakfast\r\nfree wifi\r\n24-hour front desk service. We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins..",
         "highlights": ""
      }
      ],
      "HotelName": "Swan Bird Lake Inn",
      "Description": "We serve a continental-style breakfast each morning, featuring a variety of food and drinks. Our locally made, oh-so-soft, caramel cinnamon rolls are a favorite with our guests. Other breakfast items include coffee, orange juice, milk, cereal, instant oatmeal, bagels, and muffins.",
      "Tags": [
      "continental breakfast",
      "free wifi",
      "24-hour front desk service"
      ]
   },
   {
      "@search.score": 0.92481667,
      "@search.rerankerScore": 2.221315860748291,
      "@search.captions": [
      {
         "text": "White Mountain Lodge & Suites. Resort and Spa. continental breakfast\r\npool\r\nrestaurant. 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..",
         "highlights": ""
      }
      ],
      "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.",
      "Tags": [
      "continental breakfast",
      "pool",
      "restaurant"
      ]
   },
   . . .
]}

サービスエンドポイントを取得する

残りのセクションでは、Azure OpenAI と Azure AI 検索への API 呼び出しを設定します。サービスエンドポイントを取得して、コード内で変数として提供できるようにします。

Azure portal にサインインします。
使用する検索サービスを見つけます。
[概要] ホームページで、URL をコピーします。たとえば、エンドポイントは https://example.search.windows.net のようになります。
Azure OpenAI サービスを見つけます。
[概要] ホームページで、リンクを選択して、エンドポイントを表示します。 URL をコピーします。たとえば、エンドポイントは https://example.openai.azure.com/ のようになります。

仮想環境を作成する

この手順では、ローカルシステムと Visual Studio Code に戻ります。依存関係を分離してインストールできるように、仮想環境を作成することをお勧めします。

Visual Studio Code で、Quickstart-RAG.ipynb が含まれるフォルダーを開きます。
Ctrl-shift-P を押してコマンドパレットを開き、"Python: 環境の作成" を検索し、次に Venv を選択して現在のワークスペースに仮想環境を作成します。
依存関係には Quickstart-RAG\requirements.txt を選択します。

環境の作成には数分かかります。環境の準備ができたら、次の手順に進みます。

接続には Microsoft Entra ID とロールの割り当てを使用しています。 Azure AI 検索および Azure OpenAI と同じテナントおよびサブスクリプションにログインしていることを確認します。コマンドラインで Azure CLI を使用して、現在のプロパティの表示、プロパティの変更、サインインを行うことができます。詳細については、「キーを使用せずに接続する」を参照してください。

次の各コマンドを順番に実行します。

az account show

az account set --subscription <PUT YOUR SUBSCRIPTION ID HERE>

az login --tenant <PUT YOUR TENANT ID HERE>

これで、ローカルデバイスから Azure にログインできるようになりました。

クエリとチャットスレッドをセットアップする

このセクションでは、Visual Studio Code と Python を使用して、Azure OpenAI でチャット完了 API を呼び出します。

Visual Studio Code を起動し、.ipynb ファイルを開くか、新しい Python ファイルを作成します。

次の Python パッケージをインストールします。

! pip install azure-search-documents==11.6.0b5 --quiet
! pip install azure-identity==1.16.1 --quiet
! pip install openai --quiet
! pip install aiohttp --quiet
! pip install ipykernel --quiet

プレースホルダーを前の手順で収集したエンドポイントに置き換えて、次の変数を設定します。

 AZURE_SEARCH_SERVICE: str = "PUT YOUR SEARCH SERVICE ENDPOINT HERE"
 AZURE_OPENAI_ACCOUNT: str = "PUT YOUR AZURE OPENAI ENDPOINT HERE"
 AZURE_DEPLOYMENT_MODEL: str = "gpt-4o"

クライアント、プロンプト、クエリ、応答を設定します。

Azure Government クラウドの場合は、トークンプロバイダーの API エンドポイントを "https://cognitiveservices.azure.us/.default" に変更します。

# Set up the query for generating responses
 from azure.identity import DefaultAzureCredential
 from azure.identity import get_bearer_token_provider
 from azure.search.documents import SearchClient
 from openai import AzureOpenAI

 credential = DefaultAzureCredential()
 token_provider = get_bearer_token_provider(credential, "https://cognitiveservices.azure.com/.default")
 openai_client = AzureOpenAI(
     api_version="2024-06-01",
     azure_endpoint=AZURE_OPENAI_ACCOUNT,
     azure_ad_token_provider=token_provider
 )

 search_client = SearchClient(
     endpoint=AZURE_SEARCH_SERVICE,
     index_name="hotels-sample-index",
     credential=credential
 )

 # This prompt provides instructions to the model
 GROUNDED_PROMPT="""
 You are a friendly assistant that recommends hotels based on activities and amenities.
 Answer the query using only the sources provided below in a friendly and concise bulleted manner.
 Answer ONLY with the facts listed in the list of sources below.
 If there isn't enough information below, say you don't know.
 Do not generate answers that don't use the sources below.
 Query: {query}
 Sources:\n{sources}
 """

 # Query is the question being asked. It's sent to the search engine and the chat model
 query="Can you recommend a few hotels with complimentary breakfast?"

 # Search results are created by the search client
 # Search results are composed of the top 5 results and the fields selected from the search index
 # Search results include the top 5 matches to your query
 search_results = search_client.search(
     search_text=query,
     top=5,
     select="Description,HotelName,Tags"
 )
 sources_formatted = "\n".join([f'{document["HotelName"]}:{document["Description"]}:{document["Tags"]}' for document in search_results])

 # Send the search results and the query to the LLM to generate a response based on the prompt.
 response = openai_client.chat.completions.create(
     messages=[
         {
             "role": "user",
             "content": GROUNDED_PROMPT.format(query=query, sources=sources_formatted)
         }
     ],
     model=AZURE_DEPLOYMENT_MODEL
 )

 # Here is the response from the chat model.
 print(response.choices[0].message.content)

出力は Azure OpenAI からのものであり、いくつかのホテルのおすすめ候補で構成されています。出力は、たとえば、次のようになります。

Sure! Here are a few hotels that offer complimentary breakfast:

- **Head Wind Resort**
- Complimentary continental breakfast in the lobby
- Free Wi-Fi throughout the hotel

- **Double Sanctuary Resort**
- Continental breakfast included

- **White Mountain Lodge & Suites**
- Continental breakfast available

- **Swan Bird Lake Inn**
- Continental-style breakfast each morning with a variety of food and drinks 
 such as caramel cinnamon rolls, coffee, orange juice, milk, cereal, 
 instant oatmeal, bagels, and muffins

[Forbidden] エラーメッセージが表示された場合は、Azure AI Search 構成を確認し、ロールベースのアクセスが有効になっていることを確認してください。

[承認に失敗しました]エラーメッセージが表示された場合は、数分待ってからもう一度お試しください。ロールの割り当てが操作可能になるまでに数分かかる場合があります。

"リソースが見つかりません" エラーメッセージが表示された場合は、リソース URI を確認し、チャットモデルの API バージョンが有効であることを確認します。

それ以外の場合、さらに実験するには、クエリを変更し、最後の手順を再実行して、モデルがグラウンディングデータでどのように機能するかを理解します。

プロンプトを変更して、出力のトーンや構造を変更することもできます。

また、クエリパラメーターステップで use_semantic_reranker=False を設定して、セマンティックランク付けなしにクエリを試すこともできます。セマンティックランク付けを使用すると、クエリ結果の関連性と、LLM が有用な情報を返す能力を著しく向上させることができます。実験は、コンテンツに違いがあるかどうかを判断するのに役立ちます。

複雑な RAG クエリを送信する

Azure AI 検索は、入れ子になった JSON 構造用の複合型をサポートしています。 hotels-sample-index の Address は、Address.StreetAddress、Address.City、Address.StateProvince、Address.PostalCode、Address.Country で構成される複合型の例です。インデックスには、各ホテルの Rooms の複合コレクションもあります。

インデックスに複合型がある場合、最初に検索結果の出力を JSON に変換し、次にその JSON をチャットモデルに渡すと、クエリでそれらのフィールドを指定できます。次の例では、要求に複合型を追加しています。書式設定命令に JSON 仕様が含まれています。

import json

# Query is the question being asked. It's sent to the search engine and the LLM.
query="Can you recommend a few hotels that offer complimentary breakfast? 
Tell me their description, address, tags, and the rate for one room that sleeps 4 people."

# Set up the search results and the chat thread.
# Retrieve the selected fields from the search index related to the question.
selected_fields = ["HotelName","Description","Address","Rooms","Tags"]
search_results = search_client.search(
    search_text=query,
    top=5,
    select=selected_fields,
    query_type="semantic"
)
sources_filtered = [{field: result[field] for field in selected_fields} for result in search_results]
sources_formatted = "\n".join([json.dumps(source) for source in sources_filtered])

response = openai_client.chat.completions.create(
    messages=[
        {
            "role": "user",
            "content": GROUNDED_PROMPT.format(query=query, sources=sources_formatted)
        }
    ],
    model=AZURE_DEPLOYMENT_MODEL
)

print(response.choices[0].message.content)

出力は Azure OpenAI からのものであり、複合型のコンテンツを追加します。

Here are a few hotels that offer complimentary breakfast and have rooms that sleep 4 people:

1. **Head Wind Resort**
   - **Description:** The best of old town hospitality combined with views of the river and 
   cool breezes off the prairie. Enjoy a complimentary continental breakfast in the lobby, 
   and free Wi-Fi throughout the hotel.
   - **Address:** 7633 E 63rd Pl, Tulsa, OK 74133, USA
   - **Tags:** Coffee in lobby, free Wi-Fi, view
   - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99

2. **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. Offers continental breakfast.
   - **Address:** 2211 Elliott Ave, Seattle, WA 98121, USA
   - **Tags:** View, pool, restaurant, bar, continental breakfast
   - **Room for 4:** Suite, 2 Queen Beds (Amenities) - $254.99

3. **Swan Bird Lake Inn**
   - **Description:** Continental-style breakfast featuring a variety of food and drinks. 
   Locally made caramel cinnamon rolls are a favorite.
   - **Address:** 1 Memorial Dr, Cambridge, MA 02142, USA
   - **Tags:** Continental breakfast, free Wi-Fi, 24-hour front desk service
   - **Room for 4:** Budget Room, 2 Queen Beds (City View) - $85.99

4. **Gastronomic Landscape Hotel**
   - **Description:** Known for its culinary excellence under the management of William Dough, 
   offers continental breakfast.
   - **Address:** 3393 Peachtree Rd, Atlanta, GA 30326, USA
   - **Tags:** Restaurant, bar, continental breakfast
   - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $66.99
...
   - **Tags:** Pool, continental breakfast, free parking
   - **Room for 4:** Budget Room, 2 Queen Beds (Amenities) - $60.99

Enjoy your stay! Let me know if you need any more information.

トラブルシューティングエラー

認証エラーをデバッグするには、検索エンジンと LLM を呼び出す手順の前に次のコードを挿入します。

import sys
import logging # Set the logging level for all azure-storage-* libraries
logger = logging.getLogger('azure.identity') 
logger.setLevel(logging.DEBUG)

handler = logging.StreamHandler(stream=sys.stdout)
formatter = logging.Formatter('[%(levelname)s %(name)s] %(message)s')
handler.setFormatter(formatter)
logger.addHandler(handler)

クエリスクリプトを再実行してください。出力に INFO ステートメントと DEBUG ステートメントが表示され、問題の詳細が表示されるようになるはずです。

ManagedIdentityCredential とトークン取得エラーに関する出力メッセージが表示される場合は、複数のテナントがあり、Azure サインインに検索サービスがないテナントを使用している可能性があります。テナント ID を取得するには、Azure portal で "テナントプロパティ" を検索するか、az login tenant list を実行します。

テナント ID を取得したら、コマンドプロンプトで az login --tenant <YOUR-TENANT-ID> を実行し、スクリプトを再実行します。

クリーンアップ

独自のサブスクリプションを使用している場合は、プロジェクトの最後に、作成したリソースがまだ必要かどうかを確認してください。リソースを実行したままにすると、お金がかかる場合があります。リソースを個別に削除するか、リソースグループを削除してリソースのセット全体を削除することができます。

左端のペイン内にある [すべてのリソース] または [リソースグループ] リンクを使用して、Azure portal 内でリソースを検索および管理できます。

次の方法で共有

クイックスタート: Azure AI 検索からのグラウンディングデータを使用した生成検索 (RAG)

前提条件

ファイルをダウンロードする

アクセスを構成する

インデックスを作成する

サービスエンドポイントを取得する

仮想環境を作成する

クエリとチャットスレッドをセットアップする

複雑な RAG クエリを送信する

トラブルシューティングエラー

クリーンアップ

関連項目

フィードバック

その他のリソース

次の方法で共有

クイックスタート: Azure AI 検索からのグラウンディング データを使用した生成検索 (RAG)

前提条件

ファイルをダウンロードする

アクセスを構成する

インデックスを作成する

サービス エンドポイントを取得する

仮想環境を作成する

Azure へのサインイン

クエリとチャット スレッドをセットアップする

複雑な RAG クエリを送信する

トラブルシューティング エラー

クリーンアップ

関連項目

フィードバック

その他のリソース

クイックスタート: Azure AI 検索からのグラウンディングデータを使用した生成検索 (RAG)

サービスエンドポイントを取得する

クエリとチャットスレッドをセットアップする

トラブルシューティングエラー