Guia de início rápido: pesquisa generativa (RAG) com dados de aterramento da Pesquisa de IA do Azure

Artigo
10/31/2024

Este guia de início rápido mostra como enviar consultas básicas e complexas para um LLM (Large Language Model) para uma experiência de pesquisa conversacional sobre seu conteúdo indexado no Azure AI Search. Use o portal do Azure para configurar os recursos e, em seguida, execute o código Python para chamar as APIs.

Pré-requisitos

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

Transferir ficheiro

Baixe um bloco de anotações Jupyter do GitHub para enviar as solicitações neste 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 neste artigo.

Configurar o acesso

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

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

O Azure AI Search está a receber o pedido de consulta do seu sistema local. Atribua a si mesmo a atribuição da função Leitor de Dados do Í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 Colaborador do Serviço de Pesquisa e Colaborador de Dados do Índice de Pesquisa .

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

Inicie sessão no portal do Azure.
Configure a Pesquisa de IA do Azure para usar uma identidade gerenciada atribuída ao sistema para que você possa atribuir a ela atribuições de função:
1. No portal do Azure, localize o seu serviço de pesquisa.
2. No menu à esquerda, selecione Identidade de configurações>.
3. Na guia Sistema atribuído, defina status como Ativado.
Configure o Azure AI Search para acesso baseado em função:
1. No portal do Azure, localize o seu serviço Azure AI Search.
2. No menu à esquerda, selecione Teclas de configurações>e, em seguida, selecione Controle de acesso baseado em função ou Ambos.
Atribuir funções:
1. No menu à esquerda, selecione Controle de acesso (IAM).
2. No Azure AI Search, certifique-se de que tem permissões para criar, carregar e consultar um índice de pesquisa:
  - Contribuidor de dados do índice de pesquisa
  - Colaborador do Serviço de Pesquisa
3. No Azure OpenAI, selecione Controle de acesso (IAM) para atribuir a si mesmo e às permissões de identidade do serviço de pesquisa no Azure OpenAI. O código para este início rápido é executado localmente. As solicitações para o Azure OpenAI são originadas do seu sistema. Além disso, os resultados da pesquisa do mecanismo de pesquisa são passados para o Azure OpenAI. Por esses motivos, você e o serviço de pesquisa precisam de permissões no Azure OpenAI.
  - Utilizador OpenAI dos Serviços Cognitivos

Pode levar vários minutos para que as permissões entrem em vigor.

Criar 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, localize o 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 Amostras na lista suspensa.
Escolha os hotéis-amostra.
Selecione Avançar nas páginas restantes, aceitando os valores padrão.
Depois que o índice for criado, selecione Índices de gerenciamento>de pesquisa no menu à esquerda para abri-lo.
Selecione Editar JSON.

Procure por "semântica" para encontrar a seção no índice para uma configuração semântica. Substitua a linha vazia "semantic": {} pela seguinte configuração semântica. 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 Search Explorer para testar seu índice: complimentary breakfast.

A saída deve ser semelhante ao exemplo a seguir. Os resultados que são retornados diretamente do mecanismo de pesquisa consistem em campos e seus valores literais, juntamente com metadados como uma pontuação de pesquisa e uma pontuação de classificação semântica e legenda se você usar o classificador semântico. Usamos uma instrução select para retornar apenas os campos HotelName, Description e 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"
      ]
   },
   . . .
]}

Obter pontos de extremidade de serviço

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

Inicie sessão no portal do Azure.
Encontre o seu serviço de pesquisa.
Na página inicial Visão geral , copie o URL. Um ponto final de exemplo poderá ser parecido com https://example.search.windows.net.
Encontre seu serviço Azure OpenAI.
Na página inicial Visão geral , selecione o link para exibir os pontos de extremidade. Copiar o URL. Um ponto final de exemplo poderá ser parecido com https://example.openai.azure.com/.

Configurar a consulta e o thread de chat

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

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

Instale os seguintes pacotes 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 os clientes, o prompt, a consulta e a resposta.

Para a nuvem do 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 parecer:

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 do Azure AI Search para garantir que o acesso baseado em função esteja habilitado.

Se receber uma mensagem de erro 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 aterramento.

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 notavelmente a relevância dos resultados da consulta e a capacidade do LLM de retornar informações úteis. A experimentação pode ajudá-lo a decidir se faz diferença para o seu conteúdo.

Enviar uma consulta RAG complexa

O Azure AI Search 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 coleção complexa de Rooms para cada hotel.

Se o índice tiver tipos complexos, a consulta poderá fornecer esses campos se você primeiro converter a saída dos resultados da pesquisa em 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 Azure OpenAI 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.

Erros de resoluçã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 ManagedIdentityCredential e falhas de aquisição de token, pode ser que você tenha vários locatários e sua entrada do Azure esteja usando um locatário que não tenha seu serviço de pesquisa. Para obter sua ID de locatário, pesquise "propriedades do locatário" no portal do Azure ou execute az login tenant list.

Depois de ter o ID do locatário, execute az login --tenant <YOUR-TENANT-ID> em um prompt de comando e execute novamente o script.

Limpeza

Ao trabalhar na sua própria subscrição, recomendamos que verifique, depois de concluir um projeto, se ainda vai precisar dos recursos que criou. Os recursos que deixar em execução podem custar dinheiro. Pode eliminar recursos individualmente ou eliminar o grupo de recursos para eliminar todo o conjunto de recursos.

Você pode localizar e gerenciar recursos no portal do Azure usando o link Todos os recursos ou Grupos de recursos no painel mais à esquerda.

Consulte também

Tutorial: Como criar uma solução RAG no Azure AI Search

Partilhar via