Inicio rápido: Búsqueda generativa (RAG) con datos de contextualización de Búsqueda de Azure AI

Artículo
11/02/2024

En este inicio rápido se muestra cómo enviar consultas básicas y complejas a un modelo de lenguaje grande (LLM) para una experiencia de búsqueda conversacional sobre el contenido indexado en Azure AI Search. Use Azure Portal para configurar los recursos y, a continuación, ejecute código de Python para llamar a las API.

Requisitos previos

Suscripción a Azure. cree una de forma gratuita.
Búsqueda de Azure AI, en el nivel Básico o superior para que pueda habilitar el clasificador semántico. La región debe ser la misma que se usa para Azure OpenAI.
Recurso de Azure OpenAI con una implementación de gpt-4o, gpt-4o-mini o LLM equivalente, en la misma región que Azure AI Search.
Visual Studio Code con la extensión de Python y el paquete Jupyter. Para obtener más información, consulte Python en Visual Studio Code.

Descarga de un archivo

Descargue un Jupyter Notebook de GitHub para enviar las solicitudes de este inicio rápido. Para obtener más información, consulte Descarga de archivos de GitHub.

También puede iniciar un nuevo archivo en el sistema local y crear solicitudes manualmente con las instrucciones de este artículo.

Configurar el acceso

Las solicitudes al punto de conexión de búsqueda deben autenticarse y autorizarse. Puede usar claves de API o roles para esta tarea. Las claves son más fáciles de empezar, pero los roles son más seguros. En este inicio rápido se asumen los roles.

Va a configurar dos clientes, por lo que necesita permisos en ambos recursos.

Búsqueda de Azure AI recibe la solicitud de consulta del sistema local. Asígnese a sí mismo la asignación de roles Lector de datos de índice de búsqueda para esa tarea. Si también va a crear y cargar el índice de muestra del hotel, agregue también los roles Colaborador del servicio de búsqueda y Colaborador de datos del índice de búsqueda.

Azure OpenAI recibe el mensaje "¿Puede recomendar algunos hoteles?" del sistema local, además de recibir los resultados de búsqueda (origen) del servicio de búsqueda. Asígnese a sí mismo y al servicio de búsqueda el rol Usuario de OpenAI de Cognitive Services.

Inicie sesión en Azure Portal.
Configure Búsqueda de Azure AI para usar una identidad administrada asignada por el sistema para que pueda asignarle asignaciones de roles:
1. Busque el servicio de búsqueda en Azure Portal.
2. En el menú de la izquierda, seleccione Configuración>Identidad.
3. En la pestaña Sistema asignado, establezca el estado en Activado.
Configuración de Búsqueda de Azure AI para el acceso basado en roles:
1. En Azure Portal, busque el servicio de Búsqueda de Azure AI.
2. En el menú de la izquierda, seleccione Configuración>Claves y, a continuación, seleccione Control de acceso basado en rol o Ambos.
Asignar roles:
1. En el menú izquierdo, seleccione Control de acceso (IAM).
2. En Búsqueda de Azure AI, asegúrese de que tiene permisos para crear, cargar y consultar un índice de búsqueda:
  - Lector de datos de índice de búsqueda
  - Colaborador de datos de índice de búsqueda
  - Colaborador del servicio Search
3. En Azure OpenAI, seleccione Control de acceso (IAM) para asignarse a sí mismo y al servicio de búsqueda permisos de identidad en Azure OpenAI. El código de este inicio rápido se ejecuta localmente. Las solicitudes a Azure OpenAI se originan en el sistema. Además, los resultados de búsqueda del motor de búsqueda se pasan a Azure OpenAI. Por estos motivos, tanto usted como el servicio de búsqueda necesitan permisos en Azure OpenAI.
  - Usuario de OpenAI de Cognitive Services

Los permisos pueden tardar varios minutos en aplicarse.

Creación de un índice

Se recomienda el índice hotels-sample-index, que se puede crear en minutos y se ejecuta en cualquier nivel de servicio de búsqueda. Este índice se crea mediante datos de ejemplo integrados.

Busque el servicio de búsqueda en Azure Portal.
En la página principal de Información general, seleccione Importar datos para iniciar el asistente.
En la página Conectar a los datos, seleccione Ejemplos en la lista desplegable.
Elija el hotels-sample.
Seleccione Siguiente en las páginas restantes y acepte los valores predeterminados.
Una vez creado el índice, seleccione Administración de búsqueda>Índices en el menú izquierdo para abrir el índice.
Seleccione Editar JSON.

Busque "semántica" para buscar la sección en el índice para obtener una configuración semántica. Sustituya la línea vacía "semantic": {} por la siguiente configuración semántica. En este ejemplo se especifica un "defaultConfiguration", que es importante para la ejecución de este inicio rápido.

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

Guarde los cambios mediante Guardar.

Ejecute la siguiente consulta en el Explorador de búsqueda para probar su índice: complimentary breakfast.

La salida debe ser similar al siguiente ejemplo. Los resultados que se devuelven directamente desde el motor de búsqueda constan de campos y sus valores literales, junto con metadatos como una puntuación de búsqueda y una puntuación de clasificación semántica y un título si usa el clasificador semántico. Usamos una instrucción select para devolver solo los campos HotelName, Description y 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"
      ]
   },
   . . .
]}

Obtener puntos de conexión de servicio

En las secciones restantes, configurará llamadas API a Azure OpenAI y Búsqueda de Azure AI. Obtenga los puntos de conexión de servicio para que pueda proporcionarlos como variables en el código.

Inicie sesión en Azure Portal.
Búsqueda del servicio de búsqueda.
En la página principal de Información general, copie la dirección URL. Un punto de conexión de ejemplo podría ser similar a https://example.search.windows.net.
Busque el Azure OpenAI Service.
En la página principal de Información general, seleccione el vínculo para ver los puntos de conexión. Copie la dirección URL. Un punto de conexión de ejemplo podría ser similar a https://example.openai.azure.com/.

Configuración de la consulta y el subproceso de chat

En esta sección se usa Visual Studio Code y Python para llamar a las API de finalización de chat en Azure OpenAI.

Inicie Visual Studio Code y abra el archivo .ipynb o cree un nuevo archivo de Python.

Instale los siguientes paquetes de 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

Establezca las siguientes variables, sustituyendo los marcadores de posición por los puntos de conexión recopilados en el paso 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, la indicación, la consulta y la respuesta.

Para la nube de Azure Government, modifique el punto de conexión de API en el proveedor de tokens a "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)

La salida procede de Azure OpenAI y consta de recomendaciones de varios hoteles. El ejemplo siguiente muestra el aspecto que podría tener la salida:

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

Si recibe un mensaje de error Prohibido, compruebe la configuración de Azure AI Search para asegurarse de que el acceso basado en roles esté habilitado.

Si recibe un mensaje de error de autorización, espere unos minutos e inténtelo de nuevo. Las asignaciones de roles pueden tardar varios minutos en estar operativas.

De lo contrario, para experimentar más, cambie la consulta y vuelva a ejecutar el último paso para comprender mejor cómo funciona el modelo con los datos de puesta a tierra.

También puede modificar la indicación para cambiar el tono o la estructura de la salida.

También puede probar la consulta sin clasificación semántica estableciendo use_semantic_reranker=False en el paso de parámetros de consulta. La clasificación semántica puede mejorar considerablemente la relevancia de los resultados de la consulta y la capacidad del LLM para devolver información útil. La experimentación puede ayudarle a decidir si supone una diferencia para su contenido.

Envío de una consulta RAG compleja

Azure AI Search admite tipos complejos para estructuras JSON anidadas. En el índice hotels-sample-index, Address es un ejemplo de un tipo complejo, que consta de Address.StreetAddress, Address.City, Address.StateProvince, Address.PostalCode, y Address.Country. El índice también cuenta con una colección compleja de Rooms para cada hotel.

Si el índice tiene tipos complejos, la consulta puede proporcionar esos campos si convierte primero la salida de los resultados de búsqueda en JSON y, a continuación, pasa el JSON al LLM. En el ejemplo siguiente se agregan tipos complejos a la solicitud. Las instrucciones de formato incluyen una especificación 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)

La salida procede de Azure OpenAI y agrega contenido de tipos complejos.

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.

Errores de solución de problemas

Para depurar errores de autenticación, inserte el código siguiente antes del paso que llama al motor de búsqueda y al 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)

Vuelva a ejecutar el script de consulta. Ahora debería obtener instrucciones INFO y DEBUG en la salida que proporcionan más detalles sobre el problema.

Si ve mensajes de salida relacionados con los errores de adquisición de tokens y ManagedIdentityCredential, puede ser que tenga varios inquilinos y que el inicio de sesión de Azure use un inquilino que no tenga el servicio de búsqueda. Para obtener el identificador de inquilino, busque "propiedades de inquilino" en Azure Portal o ejecute az login tenant list.

Una vez que tenga el id. de inquilino, ejecute az login --tenant <YOUR-TENANT-ID> en un símbolo del sistema y vuelva a ejecutar el script.

Limpieza

Cuando trabaje con su propia suscripción, es una buena idea al final de un proyecto identificar si todavía se necesitan los recursos que ha creado. Los recursos que se dejan en ejecución pueden costarle mucho dinero. Puede eliminar los recursos de forma individual o eliminar el grupo de recursos para eliminar todo el conjunto de recursos.

Puede encontrar y administrar recursos en el portal mediante el vínculo Todos los recursos o Grupos de recursos en el panel izquierdo.

Consulte también

Tutorial: Creación de una solución RAG en Búsqueda de Azure AI

Compartir a través de