Início rápido: RAG (pesquisa generativa) com dados de fundamentação da Pesquisa de IA do Azure

Artigo
11/01/2024

Este início rápido mostra como enviar consultas básicas e complexas para um Grande Modelo de Linguagem (LLM) para uma experiência de pesquisa por conversação sobre seu conteúdo indexado na Pesquisa de IA do Azure. Use o portal do Azure para configurar os recursos e, em seguida, execute o código do Python para chamar as APIs.

Pré-requisitos

Uma assinatura do Azure. Crie um gratuitamente.
Pesquisa de IA do Azure, camada Básica ou superior para que você possa habilitar o classificador semântico. A região deve ser a mesma usada para o OpenAI do Azure.
O recurso OpenAI do Azure com uma implantação de gpt-4o, gpt-4o-mini, ou LLM equivalente, na mesma região da Pesquisa de IA do Azure.
Visual Studio Code com a extensão do Python e o pacote do Jupyter. Para mais informações, Python no Visual Studio Code.

Fazer download do arquivo

No GitHub, baixe um notebook do Jupyter para enviar as solicitações nesse início rápido. Para obter mais informações, consulte Baixando arquivos do GitHub.

Você também pode iniciar um novo arquivo em seu sistema local e criar solicitações manualmente usando as instruções nesse artigo.

Configurar o acesso

As solicitações para o ponto de extremidade de pesquisa precisam ser autenticadas e autorizadas. Você pode usar funções ou chaves de API para essa tarefa. É mais fácil usar as chaves para começar, mas as funções são mais seguras. Este início rápido assume funções.

Você está configurando dois clientes, portanto, precisa de permissões em ambos os recursos.

A Pesquisa de IA do Azure está recebendo a solicitação de consulta do sistema local. Atribua a si mesmo a função de Leitor de Dados de Índice de Pesquisa para essa tarefa. Se você também estiver criando e carregando o índice de exemplo de hotel, adicione também as funções de Contribuidor de Serviço de Pesquisa e Contribuidor de Dados de Índice de Pesquisa.

O Serviço OpenAI do Azure está recebendo a (consulta) "Você pode recomendar alguns hotéis" do seu sistema local, além de receber os resultados da pesquisa (origem) do serviço de pesquisa. Atribua a si mesmo e ao serviço de pesquisa a função de Usuário dos Serviços Cognitivos do OpenAI.

Entre no portal do Azure.
Configure a Pesquisa de IA do Azure para usar uma identidade gerenciada atribuída pelo sistema para que você possa atribuir funções a ela:
1. No portal do Azure, encontre seu serviço de pesquisa.
2. No menu à esquerda, selecione Configurações>Identidade.
3. Na guia Atribuído pelo sistema, alterne o status para Ativado.
Configurar a Pesquisa de IA do Azure para acesso baseado em função:
1. No portal do Azure, localize o serviço de Pesquisa de IA do Azure.
2. No menu à esquerda, selecione Configurações>Chaves e selecione Controle de acesso baseado em função ou Ambos.
Atribuir funções:
1. No menu à esquerda, selecione Controle de acesso (IAM).
2. Na Pesquisa de IA do Azure, verifique se você tem permissões para criar, carregar e consultar um índice de pesquisa:
  - Colaborador de dados de índice de pesquisa
  - Colaborador do Serviço de Pesquisa
3. No OpenAI do Azure, selecione Controle de acesso (IAM) para atribuir a si mesmo e as permissões de identidade do serviço de pesquisa no OpenAI do Azure. O código deste início rápido é executado localmente. As solicitações para o OpenAI do Azure são originadas do seu sistema. Além disso, os resultados da pesquisa do mecanismo de pesquisa são passados para o OpenAI do Azure. Por esses motivos, você e o serviço de pesquisa precisam de permissões no OpenAI do Azure.
  - Usuário do OpenAI de Serviços Cognitivos

Pode demorar vários minutos para que as alterações entrem em vigor.

Crie um índice

Recomendamos o hotels-sample-index, que pode ser criado em minutos e é executado em qualquer camada de serviço de pesquisa. Esse índice é criado usando dados de exemplo internos.

No portal do Azure, encontre seu serviço de pesquisa.
Na página inicial Visão geral, selecione Importar dados para iniciar o assistente.
Na página Conectar aos seus dados, selecione Exemplos na lista suspensa.
Escolha o hotels-sample.
Selecione Avançar nas páginas restantes, aceitando os valores padrão.
Depois que o índice for criado, selecione Gerenciamento de Pesquisa>Índices no menu à esquerda para abrir o índice.
Selecione Editar JSON.

Pesquise por "semântica" para localizar a seção no índice para uma configuração semântica. Substitua a linha vazia "semantic": {} pela configuração semântica a seguir. Este exemplo especifica um "defaultConfiguration", que é importante para a execução deste início rápido.

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

Salve suas alterações.

Execute a seguinte consulta no Gerenciador de Pesquisa para testar o seu índice: complimentary breakfast.

A saída deve ser semelhante ao exemplo a seguir. Os resultados retornados diretamente do mecanismo de pesquisa consistem em campos e seus valores verbais, juntamente com metadados como uma pontuação de pesquisa e uma classificação semântica e legenda se você usar o classificador semântico. Usamos uma instrução select para retornar apenas os campos HotelName, Descrição e Rótulos.

{
"@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"
      ]
   },
   . . .
]}

Obter pontos de extremidade de serviço

Nas seções restantes, você configurará chamadas de API para o OpenAI do Azure e para a Pesquisa de IA do Azure. Obtenha os pontos de extremidade de serviço para que você possa fornecê-los como variáveis em seu código.

Entre no portal do Azure.
Encontre o seu serviço de pesquisa.
Na página inicial Visão Geral, copie a URL. Um ponto de extremidade de exemplo pode parecer com https://example.search.windows.net.
Localize o serviço OpenAI do Azure.
Na página inicial Visão geral, selecione o link para exibir os pontos de extremidade. Copie a URL. Um ponto de extremidade de exemplo pode parecer com https://example.openai.azure.com/.

Configurar o thread de chat e a consulta

Esta seção usa o Visual Studio Code e o Python para chamar as APIs de conclusão de chat no OpenAI do Azure.

Inicie o Visual Studio Code e abra o arquivo .ipynb ou crie um novo arquivo Python.

Instale os seguintes pacotes do 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

Defina as variáveis a seguir, substituindo espaços reservados pelos pontos de extremidade coletados na etapa anterior.

 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"

Configure clientes, o prompt, a consulta e a resposta.

Ao usar a nuvem Azure Government, modifique o ponto de extremidade da API no provedor de token para "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)

A saída é do Azure OpenAI e consiste em recomendações para vários hotéis. Aqui está um exemplo de como a saída pode ser:

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

Se você receber uma mensagem de erro Proibido, verifique a configuração da Pesquisa de IA do Azure para verificar se o acesso baseado em função está habilitado.

Se você receber uma mensagem de erro de Falha na autorização, aguarde alguns minutos e tente novamente. Pode levar vários minutos para que as atribuições de função se tornem operacionais.

Caso contrário, para experimentar mais, altere a consulta e execute novamente a última etapa para entender melhor como o modelo funciona com os dados de fundamentação.

Você também pode modificar o prompt para alterar o tom ou a estrutura da saída.

Você também pode tentar a consulta sem classificação semântica definindo use_semantic_reranker=False na etapa de parâmetros de consulta. A classificação semântica pode melhorar a relevância dos resultados da consulta e a capacidade da LLM de retornar informações úteis. A experimentação pode ajudar você a decidir se isso faz diferença para o conteúdo.

Enviar uma consulta RAG complexa

A Pesquisa de IA do Azure dá suporte a tipos complexos para estruturas JSON aninhadas. No índice de amostra de hotéis, Address é um exemplo de um tipo complexo, consistindo em Address.StreetAddress, Address.City, Address.StateProvince, Address.PostalCode e Address.Country. O índice também tem uma coleção complexa de Rooms para cada hotel.

Se o seu índice tiver tipos complexos, sua consulta poderá fornecer esses campos se você primeiro converter a saída dos resultados da pesquisa para JSON e, em seguida, passar o JSON para o LLM. O exemplo a seguir adiciona tipos complexos à solicitação. As instruções de formatação incluem uma especificação 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)

A saída é do OpenAI do Azure e adiciona conteúdo de tipos complexos.

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.

Solução de problemas

Para depurar erros de autenticação, insira o código a seguir antes da etapa que chama o mecanismo de pesquisa e o 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)

Execute novamente o script de consulta. Agora você deve obter instruções INFO e DEBUG na saída que fornecem mais detalhes sobre o problema.

Se você vir mensagens de saída relacionadas a falhas de aquisição de token e ManagedIdentityCredential, pode ser que você tenha vários locatários e sua entrada no Azure esteja usando um locatário que não tenha seu serviço de pesquisa. Para obter sua ID de locatário, pesquise “propriedades de locatário” no portal do Azure. ou execute az login tenant list.

Assim que você tiver a sua ID de locatário, execute az login --tenant <YOUR-TENANT-ID> em um prompt de comando e execute novamente o script.

Limpar

Quando você está trabalhando em sua própria assinatura, é uma boa ideia identificar, no final de um projeto, se você ainda precisa dos recursos criados. Recursos deixados em execução podem custar dinheiro. É possível excluir os recursos individualmente ou excluir o grupo de recursos para excluir todo o conjunto de recursos.

Você pode encontrar e gerenciar recursos no portal do Azure usando o link Todos os recursos ou Grupos de recursos no painel de navegação à esquerda.

Confira também

Tutorial: Como criar uma solução de RAG na Pesquisa de IA do Azure

Compartilhar via