Notas prácticas: Crea una aplicación RAG sencilla en Google Colab con LlamaIndex

Esta guía reconstruye el proceso desde las materias primas hasta un sistema funcional para: crear una aplicación RAG sencilla en Google Colab con LlamaIndex y un modelo de lenguaje de código abierto. Se enfoca en pasos operativos claros, verificaciones explícitas y código que se puede incorporar directamente a un repositorio sin necesidad de adivinar la intención. En la etapa de visión general, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras posteriores.

1. Instale las bibliotecas necesarias

Al trabajar en la etapa 1 “Instalar los componentes necesarios”, anote primero el contrato: los datos de entrada requeridos, la señal de éxito y qué ocurre en caso de un fallo parcial. Esa lista de verificación ayuda a mantener honestas las futuras modificaciones del código. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe indicar una única responsabilidad y no un proceso complicado. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de problemas.

!pip install -q llama-index llama-index-readers-web html2text llama-index-llms-groq llama-index-embeddings-huggingface

2. Importar los paquetes necesarios

Al trabajar en la etapa 2 “Importar los elementos requeridos”, anote primero el contrato: las entradas necesarias, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación ayuda a mantener honestos los cambios posteriores en el código. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina comprobaciones de éxito y evite completaciones parciales silenciosas. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de problemas.

from llama_index.core import VectorStoreIndex, Settings
from llama_index.readers.web
import SimpleWebPageReader
from llama_index.llms.groq import Groq
from llama_index.embeddings.huggingface import HuggingFaceEmbedding
from google.colab import userdata

3. Configurar la clave API de Groq

Al trabajar en la etapa 3 de “Configurar Groq”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Registre los tiempos de ejecución y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando se pasa de entornos de demostración a entornos compartidos. Almacene en caché las instrucciones del sistema estables y los esquemas de las herramientas. Reenviar un preámbulo idéntico es una causa común de consumo excesivo de recursos. Al trabajar en la etapa 3 de “Configurar Groq”, anote primero el contrato: las entradas requeridas, la señal de éxito y qué ocurre en caso de fallo parcial. Esa lista de verificación garantiza que los cambios posteriores en el código sean transparentes. Documente tanto la ruta óptima como la ruta de recuperación. Las reintentos, los controles humanos y el manejo de mensajes no entregados forman parte del producto, no son mejoras adicionales realizadas posteriormente.

# Groq API Key
os.environ["GROQ_API_KEY"] = userdata.get("GROQ_APIKEY")

4. Configurar el modelo LLM y de incrustación

La etapa 4 de configuración del LLM funciona mejor cuando se trata como una superficie medible. Capture una transcripción exitosa, un caso de fallo y la nota de reversión antes de ampliar el alcance. Prefiera unidades pequeñas y verificables en lugar de scripts extensos. Cuando un paso falla, el fallo debe apuntar a una sola responsabilidad y no a un proceso complicado. Establezca un límite de tokens por turno y por sesión. Las herramientas agenciales amplían el contexto de forma excesiva; los límites estrictos evitan que las demostraciones se conviertan en facturas inesperadas.

# Set up the open-source LLM and embedding model
Settings.llm = Groq( model="openai/gpt-oss-120b", temperature=0.1 )
Settings.embed_model = HuggingFaceEmbedding(model_name="BAAI/bge-small-en-v1.5" )

5. Cargar una página web

La etapa 5 de carga en la plataforma web funciona mejor cuando se trata como una superficie medible. Capture un registro exitoso, un caso de fallo y la nota de reversión antes de ampliar el alcance. Considere esta etapa como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace cualquier completación parcial silenciosa. Asigne un presupuesto de tokens por turno y por sesión; las herramientas autónomas amplían el contexto de forma excesiva, por lo que los límites máximos evitan que las demostraciones se conviertan en facturas inesperadas.

# Passing a URL which we want to load to our vector store
url = "https://mlds.analyticsindiamag.com/"

# Using SimpleWebPageReader to load the URL content
# html_to_text=True converts HTML into plain text
d1 = SimpleWebPageReader( html_to_text=True ).load_data([url])

6. Crear el índice vectorial

La etapa 6 de “Crear el vector” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Registre los tiempos y el costo de tokens o consultas junto con los resultados funcionales. Tener visibilidad del costo desde el principio evita facturas inesperadas cuando el proceso pasa de la demostración a entornos compartidos. Asigne un presupuesto de tokens por turno y por sesión. Las herramientas agenciales amplían el contexto de forma intensiva; los límites estrictos impiden que las demostraciones se conviertan en facturas inesperadas. La etapa 6 de “Crear el vector” funciona mejor cuando se trata como una superficie medible. Capture un registro ideal, un caso de fallo y la nota de reversión antes de ampliar el alcance. Documente tanto el camino óptimo como el camino de recuperación. Las reintentos, los controles humanos y el manejo de correos no entregados forman parte del producto, no son ajustes realizados posteriormente.

# Create a searchable index from the loaded document
index = VectorStoreIndex.from_documents(d1)

7. Crear el motor de consultas

Para la etapa 7 de Crear la consulta, defina las entradas, el responsable del paso y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar el paso a partir de un punto de control conocido sin tener que adivinar el estado oculto. Prefiera unidades pequeñas y verificables sobre scripts extensos. Cuando un paso falla, el error debe indicar una única responsabilidad y no un proceso complicado. Prefiera salidas estructuradas con validación de esquema sobre texto libre cuando el paso siguiente sea código o una llamada a una herramienta.

# Creating query engine
query_engine = index.as_query_engine()

8. Hacer una pregunta

En la fase 8 “Haz una pregunta”, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto. Considere esta fase como un contrato entre las entradas y los resultados validados. Asigne nombres a los artefactos, defina verificaciones de éxito y rechace las completaciones parciales silenciosas. Prefiera resultados estructurados con validación de esquema sobre textos en formato libre cuando el siguiente paso sea escribir código o realizar una llamada a una herramienta.

# Running a query against the loaded URL data
r1 = query_engine.query("What is MLDS?")
print(r1)

El flujo completo de RAG

En la fase “El flujo completo de RAG”, defina las entradas, el responsable de la tarea y los criterios de finalización antes de modificar el código. Los operadores deben poder volver a ejecutar la tarea a partir de un punto de control conocido sin tener que adivinar el estado oculto.

Web Page
   ↓
SimpleWebPageReader
   ↓
Extract Text
   ↓
Hugging Face Embeddings
   ↓
VectorStoreIndex
   ↓
User Question
   ↓
Relevant Context
   ↓
Groq LLM
   ↓
Answer

¿Qué sigue?

Lista de verificación operativa