Las páginas sin traducir se abren en inglés y se indican como inglés.
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Enseñar con Loom
Loom puede servir como entorno de laboratorio para un curso sobre agentes de IA, recuperación de información, bases de datos o ingeniería de software. Cada estudiante ejecuta su propio stack de un solo usuario, en un portátil con Docker o en un codespace de GitHub sin nada instalado en su máquina. Cada laboratorio enlaza la página que hace el trabajo.
Configuración
| Los estudiantes tienen | Empiecen con |
|---|---|
| Una cuenta de GitHub y un navegador | Pruébalo en GitHub Codespaces |
| Docker en su propia máquina | Inicio rápido: vía rápida |
Un codespace consume la cuota de Codespaces del estudiante mientras se ejecuta y mientras se conserva su disco, y
GitHub elimina, junto con sus datos, el que se deja sin usar durante su período de retención
(facturación,
eliminación automática).
Los hostRequirements del dev container fijan la máquina más pequeña en la que se ejecuta
(.devcontainer/devcontainer.json).
La instalación estándar no necesita ninguna clave de API: genera los embeddings con un modelo local incluido, por lo que la búsqueda funciona
sin conexión, y ningún veredicto de escritura llama a un LLM. La extracción, los resúmenes y las respuestas generadas
(memory.ask, knowledge.synthesize) necesitan un LLM real
(modelos y claves de API); los ejercicios siguientes usan
solo escrituras, lecturas y búsqueda.
El Lab 1, y la vía del SDK en el Lab 2, necesitan el SDK de Python en un entorno virtual, en una
terminal del portátil o del codespace. En Debian o Ubuntu, incluidos un codespace y WSL,
ejecuta sudo apt-get update && sudo apt-get install -y python3-venv antes de los
comandos siguientes. El SDK necesita Python 3.11 o posterior; python3 --version indica cuál está
instalado. Un estudiante sin Python 3.11 o posterior puede usar el codespace, donde este paso
instala un Python lo bastante reciente.
python3 -m venv .venv && . .venv/bin/activate && pip install clickhouse-loom
Los comandos docker compose de los labs se ejecutan en esa misma terminal, actúan sobre los contenedores de la pila
y nombran su directorio de instalación como <dir>: ~/.loom en un portátil y
/workspaces/.loom en un codespace.
Entrega los laboratorios como una tarea
El starter del curso es un repositorio para cada
estudiante: el código de los Labs 1 y 2 y la consulta del Lab 4, con sus huecos marcados con TODO, una
página de respuestas para los ejercicios escritos, un dev container que instala la última versión
en un codespace con el SDK de Python y Claude Code, y un workflow de calificación. Cópialo en un
repositorio nuevo bajo tu cuenta o la organización de tu escuela, y marca ese
repositorio como plantilla (necesita curl, tar, git y la
GitHub CLI, con la sesión iniciada):
mkdir loom-labs && cd loom-labs
curl -fsSL https://github.com/ClickHouse/loom/archive/refs/heads/main.tar.gz \
| tar -xz --strip-components=3 loom-main/examples/course-starter
git init -b main && git add . && git commit -m "Loom labs"
gh repo create <owner>/loom-labs --public --source . --push
gh repo edit <owner>/loom-labs --template
El push ejecuta el workflow de calificación una vez, antes de que el repositorio sea una plantilla, y esa ejecución
falla por diseño: la línea de cada comprobación nombra la parte del starter que aún falta por escribir. La
copia es el starter de main, probado contra main, mientras que cada ejecución instala la última
versión, así que un fallo por cualquier otro motivo significa que ambos difieren: copia el starter de nuevo
después de la siguiente versión. Los push posteriores a la plantilla no se califican.
Después, cada estudiante trabaja en un repositorio creado a partir de esa plantilla, con Use this template en su página o con la herramienta que uses para repartir tus tareas, y lo abre en un codespace o lo clona en un portátil. Un estudiante necesita acceso de lectura a la plantilla para usarla: una pública no contiene respuestas, y una privada sirve para los miembros de su organización o los colaboradores que añadas.
python grading/grade.py ejecuta el código del laboratorio contra el stack en ejecución del estudiante y comprueba
lo que escribió y devolvió, no cómo llegó ahí, así que revisa también el código. El workflow Grade
ejecuta las mismas comprobaciones en cada push, contra un stack nuevo en un runner de GitHub Actions, y
escribe la tabla de comprobaciones en el resumen de la ejecución; la ejecución falla mientras alguna comprobación falle. Cada
comprobación falla con el starter sin modificar y no necesita clave de API. El Lab 3 y la página de respuestas se
califican a mano: sus ejercicios piden explicaciones.
Una ejecución de calificación tarda unos dos minutos, la mayoría arrancando el stack. En un repositorio privado esos minutos cuentan contra la cuota de Actions de la cuenta u organización propietaria (facturación de Actions); los codespaces cuestan lo que indica Configuración.
Laboratorio 1: un agente que recuerda
Construye un agente pequeño con el SDK de Python: una identidad, hechos que guarda y vuelve a leer, una sesión y una ejecución. Sigue Tu primer agente.
Ejercicios:
- Busca con
memory.searchalgo que ningún hecho guardado responda, y explica elabstain_codeque incluye la respuesta (buscar y preguntar). - Guarda un hecho y luego un valor cercano pero distinto bajo otra clave, y lee el veredicto de la escritura (cómo se juzga una escritura).
- Revisa un hecho y lee sus versiones con
memory.history(historial y procedencia).
Lab 2: búsqueda de documentos con citas
Ingiere algunos documentos con loom demo, que en el stack estándar (LLM falso) imprime
los primeros resultados de knowledge.search para una pregunta en lugar de una respuesta (hacer una pregunta sobre un
documento). La
ruta de --file está dentro del contenedor, que guarda esta documentación en /app/docs/. Copia primero
un archivo tuyo (aquí notes.md del directorio actual), con un nombre que
lo identifique, ya que loom demo nombra el documento por su ruta: un segundo archivo copiado
a la misma ruta reemplaza al primero como su siguiente revisión.
docker compose --project-directory <dir> exec loom loom demo --file /app/docs/getting-started/quickstart.md --question "How do I get a token?"
docker compose --project-directory <dir> exec -T loom sh -c 'cat > /tmp/notes.md' < ./notes.md
docker compose --project-directory <dir> exec loom loom demo --file /tmp/notes.md --question "<a question the file answers>"
Después busca en los documentos del espacio de nombres con knowledge.search por HTTP (sin cabecera
Authorization en el stack de un solo usuario) o con el SDK
(documentos de conocimiento). El método knowledge.ingest_file del SDK
publica un archivo local sin copiarlo al contenedor; el starter del curso en
labs/lab2.py lo usa.
Ejercicios:
- Para diez preguntas, etiqueta el documento y el pasaje que responde a cada una, y mide
recall@k en
knowledge.search(evalúa tu carga de trabajo). - Añade preguntas que los documentos no responden.
knowledge.searchsigue devolviendo resultados para ellas, así que compara lasimilaritymás alta entre los resultados (1 menos la distancia coseno) en preguntas con respuesta y sin respuesta, y elige un umbral que las separe. Elscorede un resultado es un ranking fusionado en el modo híbrido por defecto y no las separa.
Laboratorio 3: un índice de código
Indexa un repositorio en el stack
(indexar un repositorio).
Luego pregunta dónde se define un símbolo, quién lo llama y qué afecta un cambio en él (qué
responde el índice de código) por HTTP,
con POST /v1/code.<op>. El stack de un solo usuario no rellena las llamadas code.*, por lo que cada
cuerpo indica "org": "dev" y el "namespace" del repositorio (code-myrepo en la
entrada del quickstart).
Un agente de código puede hacer las mismas preguntas una vez conectado (conectar un agente de código). Se ejecuta con el modelo de su propio proveedor, por lo que necesita un inicio de sesión o una clave de API allí; el stack no proporciona ninguna.
Ejercicios:
- Elige cinco funciones y compara
code.callerscon lo que encuentragrep; explica cada diferencia (cómo leer una respuesta). -
En un clon del repositorio indexado, cambia una función y envía el diff a
code.impactcomodiff(cómo lo usa un agente). El comando necesitajq(sudo apt-get install -y jqen Debian o Ubuntu):git diff | jq -Rs '{org: "dev", namespace: "code-myrepo", diff: .}' \ | curl -s -X POST http://localhost:7777/v1/code.impact -H 'Content-Type: application/json' -d @-
Laboratorio 4: la memoria como base de datos
Loom guarda sus datos como filas en tablas de ClickHouse, y un usuario de ClickHouse de solo lectura lee un espacio de nombres a través de sus vistas (superficie SQL). Crea uno para el espacio de nombres del stack, local (el primer comando imprime su contraseña) y luego consulta con ese usuario:
docker compose --project-directory <dir> exec loom loom sql-access grant --user student1 --org dev --namespaces local
docker compose --project-directory <dir> exec clickhouse clickhouse-client --user student1 --password <password>
Ejercicios:
- Escribe una consulta sobre
loom.sql_v1_memoriesque cuente los hechos que cada agente creó en la última hora (segúncreated_at, que una revisión conserva). - Compara el resultado de un
memory.searchcon una consulta SQL sobre las mismas filas y explica qué aporta el ranking.
Qué laboratorios corresponden a cada curso
| Curso | Laboratorios | Leer a continuación |
|---|---|---|
| Agentes de IA | 1, 2, 3 | Integrar Loom en un agente, memoria |
| Recuperación de información | 1, 2 | Buscar y preguntar, evaluar Loom |
| Bases de datos | 1, 4 | Autoridad de almacenamiento, superficie SQL |
| Ingeniería de software | 3 | Índice de código, historial de PR |