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

Artigo
01/10/2025

Este guia de início rápido mostra como enviar consultas para um modelo de conclusão de bate-papo 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

Visual Studio Code com a extensão Python e o pacote Jupyter. Para obter mais informações, consulte Python no Visual Studio Code.
Uma assinatura do Azure com permissões para atribuir funções. Crie um gratuitamente.
Azure OpenAI
- Escolha uma região que suporte o modelo de conclusão de chat que você deseja usar (gpt-4o, gpt-4o-mini ou modelo equivalente).
- Implante o modelo de conclusão de chat no Azure AI Foundry ou use outra abordagem.
Azure AI Search
- Mesma região que o Azure OpenAI.
- Recomenda-se o nível básico ou superior.
- Habilite a classificação semântica.
- Habilite o controle de acesso baseado em função (veja abaixo).

Para atender ao requisito da mesma região, comece analisando as regiões para o modelo de chat que você deseja usar. Depois de identificar uma região, confirme se o Azure AI Search está disponível na mesma região.

Certifique-se de saber o nome do modelo implantado e ter os pontos de extremidade para ambos os recursos do Azure à mão. Você fornecerá essas informações nas etapas a seguir.

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 se o índice de amostra de hotéis já existir. Se ele não existir, atribua a si mesmo as funções de Colaborador do Serviço de Pesquisa e de Colaborador de Dados do Índice de Pesquisa para que você possa criar e consultar o índice.

O Azure OpenAI está recebendo a consulta e os resultados da pesquisa do seu sistema local. Atribua a si mesmo a função de Usuário OpenAI dos Serviços Cognitivos no Azure OpenAI.

Inicie sessão no portal do Azure.
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, selecione estas funções para criar, carregar e consultar um índice de pesquisa e, em seguida, atribua-as à sua identidade de utilizador do Microsoft Entra ID:
  - Contribuidor de dados do índice de pesquisa
  - Colaborador do Serviço de Pesquisa
3. No Azure OpenAI, selecione Controle de acesso (IAM) para atribuir essa função a si mesmo 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

Um índice de pesquisa fornece dados de aterramento para o modelo de chat. 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.
Role até o final do índice, onde você pode encontrar espaços reservados para construções que podem ser adicionadas a um índice.
```
"analyzers": [],
"tokenizers": [],
"tokenFilters": [],
"charFilters": [],
"normalizers": [],
```

Em uma nova linha após "normalizadores", cole na 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/.

Criar um ambiente virtual

Nesta etapa, volte para o sistema local e o Visual Studio Code. Recomendamos que você crie um ambiente virtual para que possa instalar as dependências isoladamente.

No Visual Studio Code, abra a pasta que contém Quickstart-RAG.ipynb.
Pressione Ctrl-shift-P para abrir a paleta de comandos, procure por "Python: Create Environment" e selecione Venv para criar um ambiente virtual no espaço de trabalho atual.
Selecione Quickstart-RAG\requirements.txt para as dependências.

Leva vários minutos para criar o ambiente. Quando o ambiente estiver pronto, avance para o passo seguinte.

Você está usando a ID do Microsoft Entra e atribuições de função para a conexão. Certifique-se de que tem sessão iniciada no mesmo inquilino e subscrição que o Azure AI Search e o Azure OpenAI. Você pode usar a CLI do Azure na linha de comando para mostrar as propriedades atuais, alterar as propriedades e entrar. Para obter mais informações, consulte Conectar-se sem chaves.

Execute cada um dos seguintes comandos em sequência.

az account show

az account set --subscription <PUT YOUR SUBSCRIPTION ID HERE>

az login --tenant <PUT YOUR TENANT ID HERE>

Agora você deve estar conectado ao Azure a partir do seu dispositivo local.

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 chat model
 query="Can you recommend a few hotels with complimentary breakfast?"

 # Search results are created by the search client
 # Search results are composed of the top 5 results and the fields selected from the search index
 # Search results include the top 5 matches to your query
 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])

 # Send the search results and the query to the LLM to generate a response based on the prompt.
 response = openai_client.chat.completions.create(
     messages=[
         {
             "role": "user",
             "content": GROUNDED_PROMPT.format(query=query, sources=sources_formatted)
         }
     ],
     model=AZURE_DEPLOYMENT_MODEL
 )

 # Here is the response from the chat 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.

Se você receber uma mensagem de erro Recurso não encontrado , verifique os URIs do recurso e verifique se a versão da API no modelo de chat é válida.

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, sua 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 modelo de chat. 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

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

Pré-requisitos

Transferir ficheiro

Configurar o acesso

Criar um índice

Obter pontos de extremidade de serviço

Criar um ambiente virtual

Configurar a consulta e o thread de chat

Enviar uma consulta RAG complexa

Erros de resolução de problemas

Limpeza

Consulte também

Comentários

Recursos adicionais

Partilhar via

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

Pré-requisitos

Transferir ficheiro

Configurar o acesso

Criar um índice

Obter pontos de extremidade de serviço

Criar um ambiente virtual

Iniciar sessão no Azure

Configurar a consulta e o thread de chat

Enviar uma consulta RAG complexa

Erros de resolução de problemas

Limpeza

Consulte também

Comentários

Recursos adicionais