En este CodeLab, aprenderás a crear un Agente de búsqueda de hoteles utilizando Cadena LangChain, Servicios de inteligencia artificial de Couchbasey Catálogo de agentes. También incorporaremos Arize Phoenix para la observabilidad y la evaluación, con el fin de garantizar que nuestro agente funcione de manera confiable.
Este tutorial te lleva desde cero hasta crear un agente totalmente funcional que puede buscar hoteles, filtrar por servicios y responder consultas en lenguaje natural utilizando datos del mundo real.
Nota: Puede encontrar el cuaderno completo de Google CodeLab para este CodeLab. aquí.
¿Qué son los servicios de inteligencia artificial de Couchbase?
La creación de aplicaciones de IA a menudo implica combinar múltiples servicios: una base de datos vectorial para la memoria, un proveedor de inferencia para LLM (como OpenAI o Anthropic) y una infraestructura independiente para integrar modelos.
Servicios de inteligencia artificial de Couchbase Optimiza este proceso al proporcionar una plataforma unificada en la que conviven sus datos operativos, la búsqueda vectorial y los modelos de inteligencia artificial. Ofrece:
- API de inferencia y embeddings de LLM: Acceda a modelos LLM populares (como Llama 3) y modelos de incrustación directamente en Couchbase Capella, sin claves API externas, sin infraestructura adicional y sin salida de datos. Los datos de su aplicación permanecen dentro de Capella. Las consultas, los vectores y la inferencia de modelos se realizan donde se encuentran los datos. Esto permite experiencias de IA seguras y de baja latencia, al tiempo que se cumplen los requisitos de privacidad y cumplimiento normativo. De ahí el valor clave: datos e IA juntos, sin enviar información confidencial fuera de su sistema.
- Plataforma unificada: Base de datos + Vectorización + Búsqueda + Modelo
- Búsqueda vectorial integrada: Realice búsquedas semánticas directamente en sus datos JSON con una latencia de milisegundos.
¿Por qué es necesario?
A medida que pasamos de los chatbots simples a flujos de trabajo de agentes, donde los modelos de IA utilizan herramientas de forma autónoma, la latencia y la complejidad de la configuración se convierten en cuellos de botella. Al ubicar sus datos y servicios de IA en el mismo lugar, se reduce la sobrecarga operativa y la latencia. Además, herramientas como la Catálogo de agentes Ayuda con la gestión de cientos de indicaciones y herramientas para agentes y proporciona un registro integrado para tus agentes.
Requisitos previos
Antes de empezar, asegúrate de que tienes:
- A Couchbase Capella cuenta.
- Python 3.10+ instalado.
- Conocimientos básicos de Python y cuadernos Jupyter.
Crear un clúster en Couchbase Capella
- Inicie sesión en Couchbase Capella.
- Cree un nuevo clúster o utilice uno existente. Tenga en cuenta que el clúster debe ejecutar la última versión de Couchbase Server 8.0 con los servicios de datos, consultas, índices y eventos.
- Cree un cubo.
- Cree un ámbito y una colección para sus datos.
Paso 1: Instalar dependencias
Comenzaremos instalando los paquetes necesarios. Esto incluye el couchbase-infraestructura ayudante para la configuración, el agentec CLI para el catálogo y los paquetes de integración LangChain.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 |
%pip install -q \ "pydantic>=2.0.0,<3.0.0" \ "python-dotenv>=1.0.0,<2.0.0" \ "pandas>=2.0.0,<3.0.0" \ "nest-asyncio>=1.6.0,<2.0.0" \ "langchain-couchbase>=0.2.4,<0.5.0" \ "langchain-openai>=0.3.11,<0.4.0" \ "arize-phoenix>=11.37.0,<12.0.0" \ "openinference-instrumentation-langchain>=0.1.29,<0.2.0" \ "couchbase-infrastructure" # Install Agent Catalog %pip install agentc==1.0.0 |
Paso 2: Infraestructura como código
En lugar de hacer clic manualmente en la interfaz de usuario, utilizamos el couchbase-infraestructura paquete para aprovisionar mediante programación nuestro entorno Capella. Esto garantiza una configuración reproducible.
Nos comprometemos a:
- Cree un proyecto y un grupo.
- Implementar un modelo de incrustación (
nvidia/llama-3.2-nv-embedqa-1b-v2) y un máster en Derecho (meta/llama3-8b-instrucción). - Cargar el
viaje-muestraconjunto de datos.
Couchbase AI Services proporciona puntos finales compatibles con OpenAI que utilizan los agentes.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 |
import os from getpass import getpass from couchbase_infrastructure import CapellaConfig, CapellaClient from couchbase_infrastructure.resources import ( create_project, create_developer_pro_cluster, add_allowed_cidr, load_sample_data, create_database_user, deploy_ai_model, create_ai_api_key, ) # 1. Collect Credentials management_api_key = getpass("Enter your MANAGEMENT_API_KEY: ") organization_id = input("Enter your ORGANIZATION_ID: ") config = CapellaConfig( management_api_key=management_api_key, organization_id=organization_id, project_name="agent-app", cluster_name="agent-app-cluster", db_username="agent_app_user", sample_bucket="travel-sample", # Using Couchbase AI Services for models embedding_model_name="nvidia/llama-3.2-nv-embedqa-1b-v2", llm_model_name="meta/llama3-8b-instruct", ) # 2. Provision Cluster client = CapellaClient(config) org_id = client.get_organization_id() project_id = create_project(client, org_id, config.project_name) cluster_id = create_developer_pro_cluster(client, org_id, project_id, config.cluster_name, config) # 3. Network & Data Setup add_allowed_cidr(client, org_id, project_id, cluster_id, "0.0.0.0/0") # Allow all IPs for tutorial load_sample_data(client, org_id, project_id, cluster_id, config.sample_bucket) db_password = create_database_user(client, org_id, project_id, cluster_id, config.db_username, config.sample_bucket) # 4. Deploy AI Models print("Deploying AI Models...") deploy_ai_model(client, org_id, config.embedding_model_name, "agent-hub-embedding-model", "embedding", config) deploy_ai_model(client, org_id, config.llm_model_name, "agent-hub-llm-model", "llm", config) # 5. Generate API Keys api_key = create_ai_api_key(client, org_id, config.ai_model_region) |
Asegúrese de seguir los pasos para configurar el certificado raíz de seguridad. Las conexiones seguras a Couchbase Capella requieren un certificado raíz para la verificación TLS. Puede encontrarlo en el ## 📜 Configuración del certificado raíz sección del cuaderno de Google Colab.
Paso 3: Integración del catálogo de agentes
En Catálogo de agentes es una potente herramienta para gestionar el ciclo de vida de las capacidades de su agente. En lugar de codificar de forma rígida las indicaciones y las definiciones de herramientas en sus archivos Python, puede gestionarlas como activos versionados. Puede centralizar y reutilizar sus herramientas en todos sus equipos de desarrollo. También puede examinar y supervisar las respuestas de los agentes con Agent Tracer.
Inicializar y descargar recursos
Primero, inicializamos el catálogo y descargamos nuestras indicaciones y herramientas predefinidas.
|
1 2 3 4 5 6 7 8 |
!git init !agentc init # Download example tools and prompts !mkdir -p prompts tools !wget -O prompts/hotel_search_assistant.yaml https://raw.githubusercontent.com/couchbase-examples/agent-catalog-quickstart/refs/heads/main/notebooks/hotel_search_agent_langchain/prompts/hotel_search_assistant.yaml !wget -O tools/search_vector_database.py https://raw.githubusercontent.com/couchbase-examples/agent-catalog-quickstart/refs/heads/main/notebooks/hotel_search_agent_langchain/tools/search_vector_database.py !wget -O agentcatalog_index.json https://raw.githubusercontent.com/couchbase-examples/agent-catalog-quickstart/refs/heads/main/notebooks/hotel_search_agent_langchain/agentcatalog_index.json |
Indexar y publicar
Utilizamos agentec para indexar nuestros archivos locales y publicarlos en Couchbase. Esto almacena los metadatos en su base de datos, lo que permite que el agente los busque y los encuentre en tiempo de ejecución.
|
1 2 3 4 5 |
# Create local index of tools and prompts !agentc index . # Upload to Couchbase !agentc publish |
Paso 4: Preparación del almacén de vectores
Para que nuestro agente pueda buscar hoteles semánticamente (por ejemplo, “lugar acogedor cerca de la playa”), necesitamos generar incrustaciones vectoriales para nuestros datos de hoteles.
Definimos un asistente para dar formato a los datos de nuestro hotel en una representación de texto enriquecido, dando prioridad a la ubicación y las comodidades.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 |
from langchain_couchbase.vectorstores import CouchbaseVectorStore def load_hotel_data_to_couchbase(cluster, bucket_name, scope_name, collection_name, embeddings, index_name): # Check if data exists # ... (omitted for brevity) ... # Generate rich text for each hotel # e.g., "Le Clos Fleuri in Giverny, France. Amenities: Free breakfast: Yes..." hotel_texts = get_hotel_texts() # Initialize Vector Store connected to Capella vector_store = CouchbaseVectorStore( cluster=cluster, bucket_name=bucket_name, scope_name=scope_name, collection_name=collection_name, embedding=embeddings, index_name=index_name, ) # Batch upload texts vector_store.add_texts(texts=hotel_texts) print(f"Successfully loaded {len(hotel_texts)} hotel embeddings") |
Paso 5: Creación del agente LangChain
Utilizamos el Catálogo de agentes para obtener nuestras definiciones de herramientas y mensajes de forma dinámica. El código sigue siendo genérico, mientras que sus capacidades (herramientas) y personalidad (mensajes) se gestionan por separado. También crearemos nuestro ReAct agentes.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 |
import agentc from langchain.agents import AgentExecutor, create_react_agent from langchain_core.prompts import PromptTemplate from langchain_core.tools import Tool def create_langchain_agent(self, catalog, span): # 1. Setup AI Services using Capella endpoints embeddings, llm = setup_ai_services(framework="langchain") # 2. Discover Tools from Catalog # The catalog.find() method searches your published catalog tool_search = catalog.find("tool", name="search_vector_database") tools = [ Tool( name=tool_search.meta.name, description=tool_search.meta.description, func=tool_search.func, # The actual python function ), ] # 3. Discover Prompt from Catalog hotel_prompt = catalog.find("prompt", name="hotel_search_assistant") # 4. Construct the Prompt Template custom_prompt = PromptTemplate( template=hotel_prompt.content.strip(), input_variables=["input", "agent_scratchpad"], partial_variables={ "tools": "\n".join([f"{tool.name}: {tool.description}" for tool in tools]), "tool_names": ", ".join([tool.name for tool in tools]), }, ) # 5. Create the ReAct Agent agent = create_react_agent(llm, tools, custom_prompt) agent_executor = AgentExecutor( agent=agent, tools=tools, verbose=True, handle_parsing_errors=True, # Auto-correct formatting errors max_iterations=5, return_intermediate_steps=True, ) return agent_executor |
Paso 6: Ejecutar el agente
Una vez inicializado el agente, podemos realizar consultas complejas. El agente:
- Reciba la entrada del usuario.
- Decide que necesita utilizar el
buscar_base_de_datos_vectorialherramienta. - Realiza la búsqueda en Capella.
- Sintetizar los resultados en una respuesta en lenguaje natural.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 |
# Initialize Agent Catalog catalog = agentc.catalog.Catalog() span = catalog.Span(name="Hotel Support Agent", blacklist=set()) # Create the agent agent_executor = couchbase_client.create_langchain_agent(catalog, span) # Run a query query = "Find hotels in Giverny with free breakfast" response = agent_executor.invoke({"input": query}) print(f"User: {query}") print(f"Agent: {response['output']}") |
Ejemplo de resultado:
Agente: Encontré un hotel en Giverny que ofrece desayuno gratis llamado Le Clos Fleuri. Se encuentra en el número 5 de la rue de la Dîme, 27620 Giverny. Ofrece conexión a internet y estacionamiento gratuitos.
Nota: En Capella Model Services, los resultados del modelo pueden ser en caché (tanto caché semántica como estándar). El mecanismo de almacenamiento en caché mejora la eficiencia y la velocidad del RAG, especialmente cuando se trata de consultas repetidas o similares. Cuando se procesa una consulta por primera vez, el LLM genera una respuesta y luego la almacena en Couchbase. Cuando más tarde se reciben consultas similares, se devuelven las respuestas almacenadas en caché. La duración del almacenamiento en caché se puede configurar en los servicios del modelo Capella.
Agregar caché semántico
El almacenamiento en caché resulta especialmente útil en situaciones en las que los usuarios pueden enviar consultas similares varias veces o en las que se solicitan con frecuencia determinados datos. Al almacenarlos en una caché, podemos reducir considerablemente el tiempo que se tarda en responder a estas consultas, mejorando así la experiencia del usuario.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 |
## Semantic Caching Demonstration # This section demonstrates how to enable and use Semantic Caching with Capella Model Services. # Semantic caching stores responses for queries and reuses them for semantically similar future queries, significantly reducing latency and cost. # 1. Setup LLM with Semantic Caching enabled # We pass the "X-cb-cache": "semantic" header to enable the feature print(" Setting up LLM with Semantic Caching enabled...") llm_with_cache = ChatOpenAI( model=os.environ["CAPELLA_API_LLM_MODEL"], base_url=os.environ["CAPELLA_API_LLM_ENDPOINT"] + "/v1" if not os.environ["CAPELLA_API_LLM_ENDPOINT"].endswith("/v1") else os.environ["CAPELLA_API_LLM_ENDPOINT"], api_key=os.environ["CAPELLA_API_LLM_KEY"], temperature=0, # Deterministic for caching default_headers={"X-cb-cache": "semantic"} ) # 2. Define a query and a semantically similar variation query_1 = "What are the best hotels in Paris with a view of the Eiffel Tower?" query_2 = "Recommend some hotels in Paris where I can see the Eiffel Tower." print(f"\n Query 1: {query_1}") print(f" Query 2 (Semantically similar): {query_2}") # 3. First execution (Cache Miss) print("\n Executing Query 1 (First run - Cache MISS)...") start_time = time.time() response_1 = llm_with_cache.invoke(query_1) end_time = time.time() time_1 = end_time - start_time print(f" Time taken: {time_1:.4f} seconds") print(f" Response: {response_1.content[:100]}...") # 4. Second execution (Cache Hit) # The system should recognize query_2 is semantically similar to query_1 and return the cached response print("\n Executing Query 2 (Semantically similar - Cache HIT)...") start_time = time.time() response_2 = llm_with_cache.invoke(query_2) end_time = time.time() time_2 = end_time - start_time print(f" Time taken: {time_2:.4f} seconds") print(f" Response: {response_2.content[:100]}...") |
Paso 7: Observabilidad con Arize Phoenix
En producción, es necesario saber por qué un agente ha dado una respuesta concreta. Utilizamos Arize Phoenix para rastrear el “proceso de pensamiento” del agente (la cadena ReAct).
También podemos realizar evaluaciones para verificar si alucinaciones o relevancia.
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
import phoenix as px from phoenix.evals import llm_classify, LENIENT_QA_PROMPT_TEMPLATE # 1. Start Phoenix Server session = px.launch_app() # 2. Instrument LangChain from openinference.instrumentation.langchain import LangChainInstrumentor LangChainInstrumentor().instrument() # ... Run your agent queries ... # 3. Evaluate Results # We use an LLM-as-a-judge to grade our agent's responses hotel_qa_results = llm_classify( data=hotel_eval_df[["input", "output", "reference"]], model=evaluator_llm, template=LENIENT_QA_PROMPT_TEMPLATE, rails=["correct", "incorrect"], provide_explanation=True, ) |
Al inspeccionar la interfaz de usuario de Phoenix, puede visualizar la secuencia exacta de llamadas a herramientas y ver la latencia de cada paso de la cadena.
Conclusión
Hemos creado con éxito un potente agente de búsqueda de hoteles. Esta arquitectura aprovecha:
- Servicios de inteligencia artificial de Couchbase: Para una capa de datos e inteligencia artificial unificada y de baja latencia.
- Catálogo de agentes: Para una gestión organizada y versionada de las herramientas y las indicaciones de los agentes. El catálogo de agentes también proporciona seguimiento. Permite a los usuarios utilizar SQL++ con seguimientos, aprovechar el rendimiento de Couchbase y obtener información detallada sobre las indicaciones y las herramientas en la misma plataforma.
- LangChain: Para una orquestación flexible.
- Arize Phoenix: Por motivos de observabilidad.
Este enfoque se adapta bien a los equipos que desarrollan sistemas complejos con múltiples agentes, en los que la gestión de datos y el descubrimiento de herramientas son retos fundamentales.
