빠른 시작: Azure AI 검색의 그라운딩 데이터가 있는 생성형 검색(RAG)

아티클
10/31/2024

이 빠른 시작에서는 Azure AI Search에서 인덱싱된 콘텐츠를 통해 대화형 검색 환경을 위해 LLM(대규모 언어 모델)에 기본 및 복잡한 쿼리를 보내는 방법을 보여 줍니다. Azure Portal을 사용하여 리소스를 설정한 다음 Python 코드를 실행하여 API를 호출합니다.

필수 구성 요소

Azure 구독 체험 계정 만들기
의미 순위매기기를 사용하도록 설정할 수 있도록 Azure AI 검색 기본 계층 이상. 지역은 Azure OpenAI에 사용되는 지역과 동일해야 합니다.
Azure AI Search와 동일한 지역에 배포 또는 동등한 LLM을 배포gpt-4ogpt-4o-mini하는 Azure OpenAI 리소스입니다.
Python 확장 및 Jupyter 패키지가 있는 Visual Studio Code. 자세한 내용은 Visual Studio Code의 Python을 참조하세요.

파일 다운로드

GitHub에서 Jupyter Notebook을 다운로드하여 이 빠른 시작에서 요청을 보냅니다. 자세한 내용은 GitHub에서 파일 다운로드를 참조하세요.

이 문서의 지침을 사용하여 로컬 시스템에서 새 파일을 시작하고 수동으로 요청을 만들 수도 있습니다.

액세스 구성

검색 엔드포인트에 대한 요청은 인증 및 권한 부여를 받아야 합니다. 이 작업에 API 키 또는 역할을 사용할 수 있습니다. 키는 시작하기가 더 쉽지만 역할이 더 안전합니다. 이 빠른 시작에서는 역할을 가정합니다.

두 개의 클라이언트를 설정하므로 두 리소스 모두에 대한 권한이 필요합니다.

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 서비스 기여자
3. Azure OpenAI에서 액세스 제어(IAM)를 선택하여 자신과 검색 서비스에 Azure OpenAI에 대한 ID 권한을 할당합니다. 이 빠른 시작의 코드는 로컬로 실행됩니다. Azure OpenAI에 대한 요청은 시스템에서 시작됩니다. 또한 검색 엔진의 검색 결과가 Azure OpenAI에 전달됩니다. 이러한 이유로 자신과 검색 서비스 모두에 Azure OpenAI에 대한 권한이 필요합니다.
  - Cognitive Services OpenAI 사용자

사용 권한이 적용되는 데 몇 분 정도 걸릴 수 있습니다.

인덱스 만들기

몇 분 안에 만들 수 있고 모든 검색 서비스 계층에서 실행되는 hotels-sample-index를 권장합니다. 이 인덱스는 기본 제공 샘플 데이터를 사용하여 생성됩니다.

Azure Portal에서 검색 서비스를 찾습니다.
개요 홈페이지에서 데이터 가져오기를 선택하여 마법사를 시작합니다.
데이터에 연결 페이지의 드롭다운 목록에서 샘플을 선택합니다.
hotels-sample을 선택합니다.
나머지 페이지에서 다음을 선택하고 기본값을 적용합니다.
인덱스가 만들어지면 왼쪽 메뉴에서 Search 관리>인덱스를 선택하여 인덱스를 엽니다.
JSON 편집을 선택합니다.

"의미론적"을 검색하여 의미론적 구성에 대한 인덱스의 섹션을 찾습니다. 비어 있는 "semantic": {} 줄을 다음과 같은 의미론적 구성으로 바꿉니다. 이 예제에서는 이 빠른 시작을 실행하는 데 중요한 "defaultConfiguration"을 지정합니다.

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

변경 내용을 저장합니다.

검색 탐색기에서 다음 쿼리를 실행하여 인덱스를 테스트합니다. 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

사용할 수 없음 오류 메시지가 표시되면 Azure AI 검색 구성을 확인하여 역할 기반 액세스가 사용하도록 설정되어 있는지 확인합니다.

권한 부여 실패 오류 메시지가 표시되면 몇 분 정도 기다렸다가 다시 시도하세요. 역할 할당이 작동하려면 몇 분 정도 걸릴 수 있습니다.

그렇지 않은 경우 더 실험하려면 쿼리를 변경하고 마지막 단계를 다시 실행하여 모델이 기초 데이터를 사용하여 작동하는 방식을 더 잘 이해합니다.

프롬프트를 수정하여 출력의 톤이나 구조를 변경할 수도 있습니다.

쿼리 매개 변수 단계에서 use_semantic_reranker=False를 설정하여 의미론적 순위 지정 없이 쿼리를 시도할 수도 있습니다. 의미론적 순위 지정은 쿼리 결과의 관련성과 LLM이 유용한 정보를 반환하는 기능을 눈에 띄게 개선할 수 있습니다. 실험을 통해 콘텐츠에 변화를 가져올지 여부를 결정할 수 있습니다.

복잡한 RAG 쿼리 보내기

Azure AI Search는 중첩된 JSON 구조에 대한 복합 형식 을 지원합니다. hotels-sample-index에서 , Address , Address.StateProvinceAddress.PostalCode및 Address.Country로 구성된 복합 형식의 Address.StreetAddressAddress.City예입니다. 인덱스는 각 호텔에 대한 복잡한 컬렉션 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 Portal에서 리소스를 찾고 관리할 수 있습니다.

참고 항목

튜토리얼: Azure AI에서 RAG 솔루션을 빌드하는 방법 검색

다음을 통해 공유