跳到内容
ClickHouse Loom
Esc
↑↓导航↵打开⌘J预览
本页内容

用 Loom 教学

用 Loom 教学

本页由机器从英文原文翻译,内容以英文原文为准。 Machine-translated from the English page, which is authoritative.

Loom 可以作为 AI agent、信息检索、数据库或软件工程课程的实验环境。每位学生运行各自的单用户堆栈,可以在装有 Docker 的笔记本电脑上运行,也可以在 GitHub codespace 中运行,无需在本机安装任何软件。每个实验都链接到完成相应工作的页面。

环境准备

学生具备的条件 起步方式
GitHub 账号和浏览器 在 GitHub Codespaces 中试用
自己的机器上装有 Docker 快速入门:快速路径

Codespace 在运行期间以及保留其磁盘期间,都会占用学生的 Codespaces 配额;如果闲置超过保留期,GitHub 会将其连同数据一并删除(计费,自动删除)。开发容器的 hostRequirements 规定了它可运行的最小机器配置(.devcontainer/devcontainer.json)。

默认安装不需要 API 密钥:它使用内置的本地模型生成嵌入,因此搜索可以离线进行,并且没有任何写入判定会调用 LLM。提取、摘要和生成式回答(memory.ask、knowledge.synthesize)需要真正的 LLM(模型与 API 密钥);下面的练习只用到写入、读取和搜索。

实验 1 以及实验 2 中的 SDK 方式,需要在虚拟环境中安装 Python SDK,可在笔记本电脑的终端或 codespace 中进行。在 Debian 或 Ubuntu 上(包括 codespace 和 WSL),请先运行 sudo apt-get update && sudo apt-get install -y python3-venv,再执行下面的命令。SDK 需要 Python 3.11 或更高版本;运行 python3 --version 可查看已安装的版本。没有 Python 3.11 或更高版本的学生可以使用 codespace,这一步会在其中安装足够新的 Python。

python3 -m venv .venv && . .venv/bin/activate && pip install clickhouse-loom

实验中的 docker compose 命令在同一个终端中运行,作用于该技术栈的容器,并以 <dir> 表示其安装目录:在笔记本电脑上是 ~/.loom,在 codespace 中是 /workspaces/.loom。

将实验作为作业布置

课程入门项目是为每位学生准备的仓库,包含实验 1 和实验 2 的代码以及实验 4 的查询,其中的空缺处以 TODO 标出;此外还有用于书面练习的答案页、在 codespace 中安装最新版本并带有 Python SDK 和 Claude Code 的 dev container,以及评分工作流。将它复制到你的账户或学校组织下的新仓库中,并把该仓库设为模板(需要 curl、tar、git 和已登录的 GitHub CLI):

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

推送会在仓库成为模板之前运行一次评分工作流,这次运行按设计会失败:每项检查的输出行都会指出入门项目中仍待编写的部分。复制下来的是 main 上的入门项目,并针对 main 进行测试,而每次运行安装的都是最新版本,因此若因其他原因失败,说明两者存在差异:请在下一个版本发布后重新复制入门项目。之后对模板的推送不会被评分。

随后,每位学生在由该模板创建的仓库中工作,可以使用模板页面上的 Use this template,或使用你布置作业所用的工具,然后在 codespace 中打开,或克隆到笔记本电脑上。学生需要有模板的读取权限才能使用它:公开模板不含答案,私有模板则适用于其组织的成员或你添加的协作者。

python grading/grade.py 会针对学生正在运行的堆栈执行实验代码,检查其写入和返回的内容,而不是实现过程,因此也请阅读代码。Grade 工作流会在每次推送时运行同样的检查,使用 GitHub Actions runner 上全新的堆栈,并将检查结果表写入该次运行的摘要;只要有检查未通过,运行就会失败。每项检查在未改动的入门项目上都会失败,且不需要 API key。实验 3 和答案页由人工评分:它们的练习要求给出解释。

一次评分运行约需两分钟,大部分时间用于启动堆栈。在私有仓库中,这些分钟数计入拥有该仓库的账户或组织的 Actions 配额(Actions 计费);codespace 的费用见安装中的说明。

实验 1:会记忆的 agent

使用 Python SDK 构建一个小型 agent:包含一个身份、它保存并读回的事实、一个会话和一次运行。请按照你的第一个 agent进行操作。

练习:

  • 用 memory.search 搜索一个没有任何已保存事实能回答的问题,并解释回复中携带的 abstain_code(搜索与提问)。
  • 保存一个事实,再在另一个键下保存一个相近但不同的值,并查看写入判定结果(写入如何被判定)。
  • 修订一个事实,并用 memory.history 读取它的各个版本(历史与来源)。

Lab 2:带引用的文档搜索

用 loom demo 摄取几份文档。在默认的堆栈(fake LLM)上,它会针对问题打印 knowledge.search 的前几条命中结果,而不是给出答案(见就文档提问)。--file 路径位于容器内部,容器的 /app/docs/ 下存放着这些文档。先把你自己的文件复制进去(这里是当前目录下的 notes.md),并使用能标识该文件的名称,因为 loom demo 按路径给文档命名:复制到相同路径的第二个文件会替换第一个文件,成为它的下一个修订版本。

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>"

然后通过 HTTP(在单用户堆栈上不需要 Authorization 请求头)或 SDK,用 knowledge.search 搜索该命名空间的文档(见知识文档)。SDK 的 knowledge.ingest_file 可以直接发布本地文件,无需先复制到容器中;课程起始项目中的 labs/lab2.py 会用到它。

练习:

  • 针对十个问题,标注能回答每个问题的文档和段落,并在 knowledge.search 上度量 recall@k(见评估你的工作负载)。
  • 加入文档无法回答的问题。knowledge.search 仍然会为这些问题返回命中结果,因此请比较可回答问题和不可回答问题的命中结果中最高的 similarity(即 1 减去余弦距离),并选择一个能将二者区分开的截断值。在默认的混合模式下,命中结果的 score 是融合后的排名,无法区分它们。

实验 3:代码索引

在栈上为一个仓库建立索引 (为仓库建立索引)。 然后通过 HTTP,使用 POST /v1/code.<op>,询问某个符号定义在哪里、谁调用了它,以及对它的修改会影响哪些部分(代码索引能回答什么)。单用户栈不会自动补全 code.* 调用,因此每个请求体都要写明 "org": "dev" 以及仓库的 "namespace"(快速入门示例中为 code-myrepo)。

连接之后,coding agent 也可以提出同样的问题 (连接 coding agent)。它运行在其自身提供方的模型上,因此需要在那里登录或使用 API key;该栈不提供这些。

练习:

  • 选取五个函数,将 code.callers 的结果与 grep 的结果进行比较,并解释每一处差异(如何解读答案)。

  • 在已建立索引的仓库的克隆中修改一个函数,并将 diff 作为 diff 发送给 code.impact (agent 如何使用它)。该命令需要 jq(在 Debian 或 Ubuntu 上使用 sudo apt-get install -y jq 安装):

    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 @-

Lab 4:作为数据库的记忆

Loom 将数据以行的形式保存在 ClickHouse 表中,只读的 ClickHouse 用户通过视图读取某个命名空间(SQL 接口)。为该栈的命名空间 local 创建一个这样的用户(第一条命令会打印其密码),然后以该用户身份查询:

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>

练习:

  • 针对 loom.sql_v1_memories 编写一条查询,统计每个 agent 在最近一小时内创建的事实数量(按 created_at 统计,修订会保留该字段)。
  • 比较 memory.search 的结果与针对相同行的 SQL 查询结果,并解释排序带来了什么。

哪些实验适合哪门课程

课程 实验 接下来阅读
AI 智能体 1, 2, 3 将 Loom 集成到 agent 中,记忆
信息检索 1, 2 搜索与提问,评估 Loom
数据库 1, 4 存储权威,SQL 接口
软件工程 3 代码索引,PR 历史

这个页面有帮助吗?