Agent ArenaClickHouse Workshops

00 环境准备

模块 00 的讲师笔记，时间安排、讲解脚本、常见故障和重置步骤。

学员课程 00 环境准备 的讲师配套材料。

课前：准备一个共享的学员密钥（公平用量）

对于公开的、讲师带领的场次，不要把你个人的 OpenRouter 密钥或一个无上限的密钥交给满屋子陌生人。OpenRouter 提供 Management (provisioning) API，可以 用程序化方式创建带硬性额度上限的专用密钥，这样课程成本 就有边界，也更公平。

1. 创建一个 Management key（一次性）。 OpenRouter → Settings → Management API Keys （openrouter.ai/settings/management-keys） → Create New Key。这个密钥可以创建、查看、删除其他密钥，并在你的 账户上花钱，请把它当作管理员凭据对待。

export OPENROUTER_PROVISIONING_KEY=sk-or-v1-<management-key>   # instructor only — never share

2. 用硬性上限开出共享的学员密钥。 仓库里带了一个脚本 （scripts/provision_workshop_keys.py）， 它会调用 POST https://openrouter.ai/api/v1/keys：

# one shared key the whole room uses, capped at $20 total (reset daily at 00:00 UTC):
python -m scripts.provision_workshop_keys --name "Agent Arena $(date +%F)" --limit 20 --daily

创建响应会只打印一次密钥字符串，复制它并作为学员的 OPENROUTER_API_KEY 交给他们。之后只能取回它的 hash（用于查看或 删除）。更喜欢直接用 curl？同样的调用：

curl -s https://openrouter.ai/api/v1/keys \
  -H "Authorization: Bearer $OPENROUTER_PROVISIONING_KEY" \
  -H "content-type: application/json" \
  -d '{"name":"Agent Arena 实训","limit":20}'

大班更公平的做法。 一个共享密钥意味着单个学员有可能把整个 预算烧光。对于 20 人以上，改为每位学员铸造一个带上限的密钥，各自独立受限：

python -m scripts.provision_workshop_keys --name "Agent Arena $(date +%F)" --limit 2 --count 30

这会创建 30 个密钥，每个上限 $2。每位学员发一个。

3. 观察并清理。 课中查看花费，结束后删除密钥：

python -m scripts.provision_workshop_keys --list
python -m scripts.provision_workshop_keys --delete <keyHash>

Management key 可以在你的账户上花钱并创建/删除密钥。只把它放在 讲师自己的 .env 里，绝不要出现在学员讲义、幻灯片或共享仓库中。学员 拿到的永远只是开出来的学员密钥（一个普通的、带上限的 sk-or-v1-…）。

规模估算：参赛阵容都是便宜的 flash-lite 档，网格只有 6 × 3 = 18 个配置，所以 $20 的共享上限足以从容覆盖满屋子人把 Arena 跑几遍，这个上限 是防止失控循环的护栏，而不是紧巴巴的预算。

时间安排

在账号已存在的情况下总共约 25–30 分钟；如果还要注册账号，请留更多时间。

  • 5 分钟：如果学员前一天没有完成准备，请现场创建三个账号（OpenRouter、Langfuse Cloud、ClickHouse Cloud）。
  • 5 分钟：克隆仓库、创建 virtualenv 并安装依赖。
  • 5 分钟：填写 .env。
  • 5 分钟：运行 source .env && scripts/arena.sh up，确认仪表板能够在 http://localhost:5174 打开。

课前请打开 OpenRouter → Settings → Privacy → Data Policies → Zero Data Retention，把 Non-frontier 关掉（灰色/关闭），然后用学员密钥测一下 Qwen。Qwen 会路由到阿里巴巴的非 ZDR 端点，所以开启 non-frontier ZDR 会产生 No endpoints available matching your guardrail restrictions and data policy， 即使已经允许了阿里巴巴、并且每个密钥/工作区的 guardrail 都很宽松。这是一个 账户级设置，无法通过 Management API 或某个请求参数放宽。这个设置只用于 本课程使用的合成负载；面对真实数据时，请记住你所在 组织的数据处理要求。

讲解脚本

  • 开场就把三个账号一起点出来，OpenRouter、ClickHouse Cloud、Langfuse Cloud，并明确说 Langfuse 就是其中之一，出现在第一个模块里， 在还没选任何模型之前。这正是重点：Langfuse 不是 在模块 04 才补上的生产附件，它是下一个模块里组织竞赛的 工具。
  • 指着架构图，点明那一条共享的代码路径：agents/ 同时被 eval/harness.py（benchmark）和 serving/api.py（生产）使用，所以 今天衡量的任何东西都不会与模块 04 上线的东西有偏离。
  • 在 scripts/arena.sh up 运行时讲解它到底做了什么：创建 arena 数据库、创建 arena_ro 只读用户、直接在 ClickHouse 里生成合成电商数据、 构建 v_* 视图，并启动 dashboard API + web UI。
  • 提前打好预期：本模块结束时 Leaderboard 标签页会是空的， 这是对的，不是 bug，而且它是通往模块 01 的悬念。

常见故障

  • OPENROUTER_API_KEY 还是占位的 sk-or-...：harness 会在模块 01 第一次调用模型时以 401 失败，而不是在 setup 阶段。让 学员现在就再确认一遍 .env 里是真实密钥，免得以后调试代价高。
  • ARENA_RO_PASSWORD 留空：scripts/arena.sh up 仍会创建 arena_ro 用户，但密码为空，而 agent 的只读客户端可能会 拒绝它，具体取决于 ClickHouse Cloud 服务的密码策略。让学员填 任意非空值。
  • ClickHouse Cloud 服务还在开通中：刚创建的服务可能需要 一两分钟才接受连接；跑得太早，scripts/arena.sh up 会以 连接错误快速失败。等一会儿重跑即可。
  • 运行脚本前没有 source .env：source .env && scripts/arena.sh up 写成一行是有原因的；在一个新 shell 里单独运行 scripts/arena.sh up 会因为缺少 CLICKHOUSE_CLOUD_* 环境变量而失败。
  • 5174（或 8000）端口已被占用：上一次运行留下的进程。 在重跑 up 之前用 scripts/arena.sh stop 清掉本地服务。

重置步骤

  • 从零重新初始化：source .env && scripts/arena.sh up，它是幂等的， 且不使用 Aurora、ClickPipes 或 ClickStack；它会重建 arena 数据库、 arena_ro 用户、合成数据和 v_* 视图，然后重启 dashboard API 和 web UI。benchmark 结果仍留在 Langfuse 里。
  • 如果只是本地服务卡住了（ClickHouse 没问题），scripts/arena.sh stop 后接 scripts/arena.sh serve 比完整跑一遍 up 更快。
  • 任何时候都可以用 scripts/arena.sh status 检查状态，它会报告 dashboard API 和 web UI 是否在运行，并打印每个 v_* 视图的行数。
  • 如果某位学员的 .env 里还是占位值，没有捷径，拿到 真实的密钥/凭据，然后重跑 scripts/arena.sh up。

讲师配套材料

面向主持人的时间安排、讲解脚本、常见故障和重置步骤。

01 选出基座模型

模块 01 的讲师笔记，时间安排、讲解脚本、常见故障和重置步骤。

本页内容

课前：准备一个共享的学员密钥（公平用量）时间安排讲解脚本常见故障重置步骤
ZH