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

[アーティクル]
09/16/2024

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

前提条件

Azure サブスクリプション。無料で作成できます。
Azure AI 検索 (セマンティックランカーを有効にできるように Basic レベル以上)。リージョンは Azure OpenAI に使用されているのと同じである必要があります。
gpt-35-turbo、gpt-4、または同等のモデルがデプロイされた 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 エクスプローラーで次のクエリを実行します: hotels near the ocean with beach access and good views。

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

   "@search.score": 5.600783,
   "@search.rerankerScore": 2.4191176891326904,
   "@search.captions": [
     {
       "text": "Contoso Ocean Motel. Budget. pool\r\nair conditioning\r\nbar. Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Various shops and art entertainment are on the boardwalk, just steps away..",
       "highlights": "Contoso Ocean Motel. Budget.<em> pool\r\nair conditioning\r\nbar. O</em>ceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Various shops and art entertainment are on the boardwalk, just steps away."
     }
   ],
   "HotelId": "41",
   "HotelName": "Contoso Ocean Motel",
   "Description": "Oceanfront hotel overlooking the beach features rooms with a private balcony and 2 indoor and outdoor pools. Various shops and art entertainment are on the boardwalk, just steps away.",
   "Category": "Budget",
   "Tags": [
     "pool",
     "air conditioning",
     "bar"
   ],

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

残りのセクションでは、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.0b4 --quiet
! pip install azure-identity==1.16.0 --quiet
! pip install openai --quiet
! pip intall aiohttp --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-35-turbo"

次のコードを実行して、クエリパラメーターを設定します。このクエリは、セマンティックランク付けを使用したキーワード検索です。キーワード検索では、検索エンジンは最大 50 個の一致を返しますが、上位 5 個のみがモデルに提供されます。お使いの検索サービスでセマンティック rankersemantic-how-to-enable-disable.md を有効にできない場合は、値を false に設定します。
```
# Set query parameters for grounding the conversation on your search index
 search_type="text"
 use_semantic_reranker=True
 sources_to_include=5
```

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

# 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 near the ocean with beach access and good views"

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

Based on your criteria, we recommend the following hotels:

- Contoso Ocean Motel: located right on the beach and has private balconies with ocean views. They also have indoor and outdoor pools. It's located on the boardwalk near shops and art entertainment.
- Northwind Plaza & Suites: offers ocean views, free Wi-Fi, full kitchen, and a free breakfast buffet. Although not directly on the beach, this hotel has great views and is near the aquarium. They also have a pool.

Several other hotels have views and water features, but do not offer beach access or views of the ocean.

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

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

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

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

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

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

認証エラーをデバッグするには、検索エンジンと 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)

前提条件

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

アクセスを構成する

インデックスを作成する

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

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

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

クリーンアップ

関連項目

フィードバック

その他のリソース

次の方法で共有

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

前提条件

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

アクセスを構成する

インデックスを作成する

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

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

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

クリーンアップ

関連項目

フィードバック

その他のリソース

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

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

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

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