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

[アーティクル]
11/05/2024

このクイックスタートでは、Azure AI 検索のインデックス付きコンテンツに対する会話形式の検索エクスペリエンスのために、基本的および複雑なクエリを大規模言語モデル (LLM) に送信する方法について説明します。 Azure portal を使ってリソースをセットアップした後、Python コードを実行して API を呼び出します。

前提条件

Azure サブスクリプション。無料で作成できます。
Azure AI 検索 (セマンティックランカーを有効にできるように Basic レベル以上)。リージョンは Azure OpenAI に使用されているのと同じである必要があります。
gpt-4o、gpt-4o-mini、または同等の LLM がデプロイされた Azure OpenAI リソース (Azure AI 検索と同じリージョン内)。
Python 拡張機能と Jupyter パッケージを持つ Visual Studio Code。詳細については、「Visual Studio Code での Python」を参照してください。

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

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

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

アクセスを構成する

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

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

Azure AI 検索は、ローカルシステムからクエリ要求を受信します。そのタスクの検索インデックスデータ閲覧者のロールの割り当てを自分自身に割り当てます。ホテルのサンプルインデックスも作成して読み込む場合は、Search Service 共同作成者と検索インデックスデータ共同作成者のロールも追加します。

Azure OpenAI は、ローカルシステムから (クエリ) "お勧めのホテルをいくつか教えてください" を受信し、さらに検索サービスから検索結果 (ソース) を受信します。 Cognitive Services OpenAI ユーザー ロールに自分自身と検索サービスを割り当てます。

Azure portal にサインインします。
システム割り当てマネージド ID を使用するように Azure AI 検索を構成して、ロールの割り当てを行えるようにします。
1. Azure portal で、ご利用の検索サービスを探します。
2. 左側のメニューで、[設定]>[ID] を選択します。
3. [システム割り当て済み] タブで、状態を [オン] に設定します。
ロールベースのアクセス用に Azure AI 検索を構成します。
1. Azure portal で Azure AI 検索サービスを見つけます。
2. 左側のメニューで、[設定]>[キー] を選択して、[ロールベースのアクセス制御] または [両方] のいずれかを選択します。
ロールを割り当てます。
1. 左側のメニューで、[アクセス制御 (IAM)] を選択します。
2. Azure AI 検索で、検索インデックスを作成、読み込み、クエリするためのアクセス許可があることを確認します。
  - 検索インデックスデータ閲覧者
  - 検索インデックスデータ共同作成者
  - Search Service Contributor
3. Azure OpenAI で、[アクセス制御 (IAM)] を選択して、Azure OpenAI で自分自身と検索サービス ID のアクセス許可を割り当てます。このクイックスタートのコードは、ローカルで実行されます。 Azure OpenAI への要求は、お使いのシステムから送信されます。また、検索エンジンからの検索結果は Azure OpenAI に渡されます。このような理由から、ユーザーと検索サービスの両方に Azure OpenAI に対するアクセス許可が必要です。
  - Cognitive Services OpenAI ユーザー

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

インデックスを作成する

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

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

"semantic" を検索して、インデックス内のセクションでセマンティック構成を検索します。空の "semantic": {} 行を次のセマンティック構成に置き換えます。この例では "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 と 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 LLM.
 query="Can you recommend a few hotels with complimentary breakfast?"

 # Set up the search results and the chat thread.
 # Retrieve the selected fields from the search index related to the question.
 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])

 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 からのものであり、いくつかのホテルのおすすめ候補で構成されています。出力は、たとえば、次のようになります。

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 構成を確認し、ロールベースのアクセスが有効になっていることを確認してください。

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

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

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

また、クエリパラメーターステップで 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 を LLM に渡す場合は、クエリでこれらのフィールドを指定できます。次の例では、要求に複合型を追加しています。書式設定命令に 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 AI 検索からのグラウンディングデータを使用した生成検索 (RAG)

前提条件

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

アクセスを構成する

インデックスを作成する

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

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

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

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

クリーンアップ

関連項目

フィードバック

その他のリソース

次の方法で共有

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

前提条件

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

アクセスを構成する

インデックスを作成する

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

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

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

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

クリーンアップ

関連項目

フィードバック

その他のリソース

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

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

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

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