Desarrollo de un asistente de documentación basado en RAG para APIs con LlamaIndex
Crea un asistente de documentación para APIs con LlamaIndex: carga documentos en formato Markdown, divídelos en fragmentos con SentenceSplitter, incrusta la información, guárdala en Chroma y realiza consultas con un RAG QueryEngine.
Fuentes: Building a RAG-Powered API Documentation Assistant with LlamaIndex (Part 1: Components)
Estás configurando una nueva API de pagos. Abres la documentación, presionas Ctrl+F, escribes “refund” y obtienes doce resultados distribuidos en cuatro páginas; la mitad de ellos son irrelevantes porque solo mencionan la palabra. Un cuarto de hora después has encontrado el endpoint, pero ya no recuerdas qué estabas haciendo.
Imagina ahora escribir “¿Cómo realizo un reembolso?” y obtener una respuesta clara directamente de la documentación. Ese es el objetivo: un pequeño asistente para una API de comercio electrónico ficticia llamada ShopSphere. No se basa en el conocimiento general del modelo de lenguaje ni inventa respuestas; busca en la documentación real de ShopSphere y responde a partir de ella. LlamaIndex se encarga del trabajo pesado, y cada paso se explica detalladamente, incluyendo los casos en que el framework parece magia.
El problema a resolver
Los modelos de lenguaje saben mucho sobre el mundo, pero nada sobre la referencia API de su empresa. Pegar cientos de páginas en cada solicitud sería lento, costoso y problemático. Un plan mejor es encontrar primero los pasajes relevantes y luego pedirle al modelo que responda a partir de ellos. Si alguien pregunta cómo crear un pedido, el sistema localiza la sección sobre creación de pedidos y ese texto va al modelo junto con la pregunta.
La técnica se denomina Generación Aumentada por Recuperación (RAG): primero recuperar información y luego generarla. Todo lo que sigue trata sobre cómo construir la parte de recuperación e, eventualmente, permitir que un agente elija qué información o herramienta utilizar.
Cuatro ideas en LlamaIndex
El framework organiza todo en torno a cuatro conceptos, y una vez que se entienden estos, deja de parecer un laberinto de nombres de clases. Una pequeña cocina de restaurante sirve como una comparación útil:
- Componentes son los ingredientes y aparatos: el horno, el refrigerador, la harina. Son capacidades en estado bruto.
- Herramientas son las recetas pegadas en los aparatos, redactadas de tal manera que un cocinero principiante pueda seguirlas sin hacer preguntas.
- Agentes son el chef, quien decide, paso a paso, qué receta utilizar y en qué secuencia, según lo que desee el cliente.
- Flujos de trabajo son las tarjetas de receta impresas, que se usan cuando no se desea improvisar y se necesita seguir una secuencia fija en cada ocasión.
El asistente se construye apilando estos cuatro elementos en ese orden.
Componentes: convertir documentos Markdown en una base de conocimientos buscable
Esta es la fase de preparación. Antes de que se realice cualquier razonamiento, cinco archivos de documentación (autenticación, productos, pedidos, errores y webhooks) deben estar en un formato que permita a la computadora buscar por su contenido, y no solo por palabras clave. Esto implica cinco pasos.
Paso 1: carga
from llama_index.core import SimpleDirectoryReader
def load_documents():
reader = SimpleDirectoryReader(input_dir="data", required_exts=[".md"])
documents = reader.load_data()
return documents
El lector abre cada archivo Markdown de la carpeta data/ y lo envuelve en un Document, que es la representación de LlamaIndex de un texto junto con información sobre su origen. La parte relativa al origen es más útil de lo que parece: el nombre original del archivo se conserva como metadato, por lo que cuando el asistente responde posteriormente, puede indicar que la información proviene de algo como 03-cart-orders.md sin necesidad de realizar un registro manual.
Paso 2: fragmentación
Un problema: 03-cart-orders.md abarca los carritos, el proceso de pago, los pedidos, las reembolsos y las cancelaciones todo en un solo archivo. Al tratarse como una única unidad buscable, podría responder a una pregunta sobre reembolsos incluyendo detalles de cancelaciones no relacionados. Por eso, cada documento se divide en partes más pequeñas a las que LlamaIndex denomina nodos, de forma similar a cuando se convierte un libro en una pila de tarjetas de índice, donde cada una recuerda al libro original.
from llama_index.core.node_parser import SentenceSplitter
splitter = SentenceSplitter(chunk_size=400, chunk_overlap=40)
Cortar de forma aleatoria cada 400 caracteres podría dividir una oración por la mitad o, peor aún, interrumpir una orden de formato. SentenceSplitter busca en su lugar los límites naturales de las oraciones. Una pequeña superposición de 40 caracteres también hace que la parte final de un fragmento aparezca al inicio del siguiente, lo que mantiene juntos los materiales relacionados, como un ejemplo de código y la oración que lo explica.
Paso 3: incrustación
La búsqueda por significado depende de este paso. Cada fragmento pasa por un modelo de incrustación, el cual convierte el texto en una larga lista de números conocida como vector. Los pasajes con significados similares terminan en vectores similares, incluso cuando las palabras utilizadas son completamente diferentes.
Un usuario podría preguntar: "¿Cómo recupero mi dinero?", mientras que los documentos tienen una sección titulada "Solicitar un reembolso". Las dos frases no comparten palabras importantes, pero expresan la misma idea. El modelo de incrustación capta esa relación, por lo que la búsqueda semántica puede mostrar la documentación sobre reembolsos.
from llama_index.embeddings.huggingface import HuggingFaceInferenceAPIEmbedding
embed_model = HuggingFaceEmbedding(
model_name="BAAI/bge-small-en-v1.5",
)
Paso 4: almacenamiento de los embeddings
Incrustar cada fragmento lleva tiempo y puede costar dinero debido a las llamadas a la API, y nadie quiere repetirlo en cada inicio de sesión. Por eso los vectores se almacenan en una base de datos vectorial que puede reutilizarse. En este caso se trata de Chroma, una base de datos local gratuita que facilita la persistencia y la búsqueda de embeddings.
import chromadb
from llama_index.vector_stores.chroma import ChromaVectorStore
db = chromadb.PersistentClient(path="./chroma_db")
chroma_collection = db.get_or_create_collection("shopsphere_api_docs")
vector_store = ChromaVectorStore(chroma_collection=chroma_collection)
LlamaIndex puede combinar los pasos 2 a 4 en un único proceso, el IngestionPipeline. Se definen las etapas una sola vez, y cada documento pasa por ellas automáticamente: se divide, se incrusta y luego se escribe en Chroma.
from llama_index.core.ingestion import IngestionPipeline
pipeline = IngestionPipeline(
transformations=[
SentenceSplitter(chunk_size=400, chunk_overlap=20),
embed_model
],
vector_store=vector_store,
)
Échelo a correr una vez y se creará un índice duradero y buscable en la carpeta chroma_db. Solo es necesario volver a crearlo cuando cambien los documentos.
Paso 5: consultas
Aquí es donde se ve el resultado. Los vectores almacenados están envueltos en un VectorStoreIndex, que se convierte en un QueryEngine, el objeto al que realmente se le hacen las preguntas:
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_vector_store(vector_store, embed_model=embed_model)
query_engine = index.as_query_engine(llm=llm, similarity_top_k=3)
query_engine.query("How do I create a new order?")
Cuando llega una pregunta ocurren tres cosas:
- La pregunta se convierte en un vector, utilizando el mismo modelo de embedding que para la ingesta. Esto es importante porque tanto la pregunta como los fragmentos deben encontrarse en el mismo espacio vectorial. Es como medir todo en una misma unidad, ya que mezclar pulgadas y centímetros hace que la comparación carezca de sentido.
- Se recuperan los fragmentos más similares del almacén de vectores. En este caso, se trata de los tres fragmentos cuyo significado está más cerca del de la pregunta.
- Dichos fragmentos se envían al LLM como contexto, y el modelo elabora su respuesta a partir de ellos en lugar de basarse únicamente en los datos de entrenamiento.
Ese es un pipeline RAG completo, y por sí solo ya es útil. Sin embargo, solo puede hacer una cosa: recuperar información y luego responder. No tiene forma de determinar si una pregunta específica requiere una búsqueda diferente. Eso necesita herramientas y un agente.
Ejecutarlo por uno mismo
Se puede clonar el proyecto terminado y ejecutarlo localmente. Configure un entorno virtual, instale los requisitos necesarios y pegue un token de Hugging Face en el archivo .env:
git clone https://github.com/H11199/API-Documentation-Agent.git
cd API-Documentation-Agent
python3 -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\Activate.ps1
pip install -r requirements.txt
cp .env.example .env # then paste your HF token in as HF_TOKEN=hf_...
python ingestion_pipeline.py # builds the index from the sample docs in data/
python app.py # chat with the assistant
Qué viene a continuación
Por el momento existe un motor de búsqueda funcional para la documentación, pero solo permite recuperar información y responder preguntas. La siguiente etapa proporciona herramientas al asistente y permite a un agente decidir cuáles utilizar. También revela una parte de los flujos de trabajo de LlamaIndex que al principio parece mágica: cómo un flujo de trabajo sabe qué paso debe ejecutarse a continuación.