write-kaggle-benchmarks

编写 Kaggle 基准测试

关键词

Kaggle 基准测试、编写基准测试、基准测试任务、kbench、推送任务、运行任务。

官方资源

• SDK 源码与 API — https://github.com/Kaggle/kaggle-benchmarks
• SDK 自动生成的文档 — https://deepwiki.com/Kaggle/kaggle-benchmarks
• CLI 文档 — https://github.com/Kaggle/kaggle-cli/blob/main/docs/benchmarks.md

命令层级

kaggle benchmarks (alias: kaggle b)
├── auth              — Fetch Model Proxy credentials
├── init              — Fetch credentials + setup local dev environment
└── tasks (alias: t)  — Manage benchmark tasks
    ├── push          — Upload a task from a .py file
    ├── run           — Run a task against model(s)
    ├── list          — List your benchmark tasks
    ├── status        — Show task details and per-model run status
    ├── download      — Download completed run outputs (and optionally source notebooks)
    ├── log (logs)    — Show execution logs for run(s) (streams live for RUNNING runs)
    ├── publish       — Make a task public (publishes the backing notebook by default)
    ├── models        — List available benchmark models
    └── delete        — Delete a task (not yet supported by server)

设置

# Full setup: credentials + .env + example_task.py + kaggle_benchmarks_reference.md
kaggle b init -y

# Credentials only (refresh MODEL_PROXY_* in .env)
kaggle b auth -y

自定义路径：初始化时使用 --env-file <FILE> 和 --example-file <FILE>。

init 写入的环境变量：

• MODEL_PROXY_URL
• MODEL_PROXY_API_KEY
• MODEL_PROXY_EXPIRY_TIME
• LLM_DEFAULT
• LLM_DEFAULT_EVAL
• LLMS_AVAILABLE

核心工作流：初始化 → 编写 → 验证 → 推送 → 运行 → 查看状态 → 下载

节奏安排 — 每个阶段都要确认

不要串联执行完整流程。 将以下每个编号步骤视为检查点：

1. 说明当前步骤准备执行的操作（一句话，并写明打算运行的确切命令）。
2. 等待用户同意后再执行——包括看似“显而易见”的 init 或 list 等步骤。
3. 步骤完成后，展示相关输出，然后停止。不要自动进入下一步。
4. 询问用户希望如何继续：进入文档所述的下一步、更改参数，还是改走其他分支。

如果用户明确要求“完整流程”或“全部执行”，可以串联执行，但要提前概述计划执行的步骤，并请求用户一次性确认整个流程，而不是悄然跳过逐步确认。

0. 初始化（每个环境执行一次，凭据过期时重新运行）

init 会获取 Model Proxy 凭据、写入 .env，并在其旁边生成 example_task.py 和 kaggle_benchmarks_reference.md。所有后续步骤 都依赖它写入的 MODEL_PROXY_* 变量，因此要先运行它，再执行其他操作； 如果 python task.py 或 kaggle b t run 因认证错误而失败，也要重新运行 该命令（API 密钥的有效期较短）。

kaggle b init -y                      # first-time setup
kaggle b auth -y                      # creds-only refresh (no scaffolding)

1. 编写任务文件

任务文件必须：

• 导入 kaggle_benchmarks as kbench
• 至少定义一个使用 @kbench.task(...) 装饰的函数
• 对任务函数调用 .run(kbench.llm)（或 .evaluate(...)）——参见注意事项
• 使用 # %% 单元格标记（jupytext 百分比格式）

最简示例：

# %%
import kaggle_benchmarks as kbench

# %%
@kbench.task(name="my-test-task")
def my_test_task(llm):
    response = llm.prompt("What is 2 + 2?")
    kbench.assertions.assert_in("4", response, expectation="Should contain 4")

my_test_task.run(kbench.llm)

LLM 解析优先级（从高到低）：

1. 代码中显式指定模型：task.run(llm=kbench.llms["gemini-3.5-flash"])
2. 代码中指定默认值：task.run(llm=kbench.llm)（解析为 LLM_DEFAULT）
3. .env 中的环境变量（LLM_DEFAULT、LLMS_AVAILABLE、MODEL_PROXY_*）

2. 本地验证

推送前，端到端运行任务。这可以及时发现静默无操作问题和提示词错误，避免推送 → 运行 → 等待 → 下载的往返流程白费时间。

kaggle b init -y                     # ensure .env is current
python task.py                       # run the task directly
ls -1 *.run.json                     # confirm a run file was produced

如果 python task.py 正常退出且生成了 *.run.json，就可以安全地推送任务。如果验证失败，请先修复并重新运行，然后再进入第 3 步。

3. 推送

kaggle b t push my-task -f task.py --wait
kaggle b t push my-task -f task.py -d owner/dataset1 -d owner/dataset2   # attach datasets

--wait [TIMEOUT] 会阻塞，直到服务端创建完成（不带参数时将无限等待）。--poll-interval <SECONDS> 用于限制轮询间隔（默认 60s；轮询从 5s 开始，并根据情况逐步调整）。每个数据集都要重复指定一次 -d/--kaggle-dataset（不要用空格分隔；参见注意事项）。

4. 运行

# Interactive picker
kaggle b t run my-task

# Specific model
kaggle b t run my-task -m gemini-3.5-flash

# Multiple models (repeat -m, do NOT space-separate)
kaggle b t run my-task -m gemini-3.5-flash -m claude-haiku-4-5

# Wait for completion
kaggle b t run my-task -m gemini-3.5-flash --wait

列出可用模型：kaggle b t models。

5. 查看状态

kaggle b t status my-task
kaggle b t status my-task -m gemini-3.5-flash

打印任务元数据（slug、版本、状态、创建时间戳、公开标记、任务 URL）和按模型列出的运行表。运行出错时，会在 Errors: 部分显示最终异常行。

6. 下载

kaggle b t download my-task                       # all terminal runs
kaggle b t download my-task -o ./results          # custom directory
kaggle b t download my-task -m gemini-3.5-flash
kaggle b t download my-task -s                    # also fetch source notebooks
kaggle b t download my-task -f                    # force re-download (overwrite)

输出目录结构：<output>/<task>/<version>/<model>/<run_id>/.... 除非传入 --force/-f，否则会跳过已下载的运行结果。使用 --include-source/-s 时，每个运行目录除了常规输出外，还会包含 __notebook__.ipynb 和 __notebook_source__.ipynb（有助于调试内核会话）。

7. 日志

kaggle b t log my-task                            # logs for every run of the task
kaggle b t log my-task -m gemini-3.5-flash # filter to one model
kaggle b t log my-task -m model-a -m model-b      # multiple models, sequential

RUNNING 状态的运行会通过 SSE 实时流式输出；COMPLETED／ERRORED 状态的运行会一次性打印已保存的日志；QUEUED 状态的运行会打印 (No logs available — server returned 404) 并继续。

8. 发布

kaggle b t publish my-task                              # publish task + backing notebook (default)
kaggle b t publish my-task --no-publish-backing-notebook  # publish task only, keep notebook private

默认会同时发布任务及其依赖的笔记本。如果任务已经公开，该命令不会对任务本身进行任何操作，但仍会发布笔记本，除非传入 --no-publish-backing-notebook。

快速操作示例

提醒：以下是参考片段，不是要自动串联执行的命令。按照上文“执行节奏”部分的说明，除非用户明确要求串联执行，否则每次只运行一个，并在每次运行之间征求用户确认。

# Push → run → download (run one command at a time, confirm between)
kaggle b t push my-task -f task.py --wait
kaggle b t run my-task -m gemini-3.5-flash --wait
kaggle b t download my-task -o ./results

# List tasks, filtered
kaggle b t list --name-regex "^math" --status errored

# Debug an errored run: pull logs first, then download source notebook
kaggle b t log my-task -m gemini-3.5-flash
kaggle b t download my-task -m gemini-3.5-flash -s -f

注意事项

其中大多数是 Agent 无法自行检测到的静默失败；生成任何任务文件或 CLI 调用之前，请先查看。

• 没有 .run() 调用 → 静默无操作。即使文件中没有 .run()，推送也会成功（推送验证只会检查是否有 @task 装饰器）。随后任务会在服务端执行，但不会生成 .run.json，因此不会记录任何内容。每个任务函数都必须以 task_fn.run(kbench.llm)（或 .evaluate(...)）结尾。
• MODEL_PROXY_API_KEY 有效期较短。如果运行 python task.py 时出现身份验证错误，请重新运行 kaggle b auth -y（或 kaggle b init -y）以刷新。
• init／auth 会追加到环境文件中。通过 dotenv 加载，因此采用后者优先的规则，重新运行是安全的，但文件中的重复条目会随着时间不断累积。
• 任务 slug 必须与 @task 装饰器匹配。如果 <SLUG> 与文件中某个 @kbench.task(name=...) 的名称（或函数名）转换为 slug 后的结果不匹配，kaggle b t push <SLUG> -f file.py 就会失败。名称会经过规范化：My Task → my-task，my_task → my-task。
• 使用不带前缀的规范模型 slug（例如 gemini-3.5-flash、claude-haiku-4-5）。CLI 会自动规范化输入，去掉任何提供方前缀（google/、anthropic/），并将 @ 替换为 -，因此 google/gemini-3.5-flash、anthropic/claude-haiku-4-5@20251001 和 claude-haiku-4-5-6@default 都能正常使用；但表格、错误日志和下载目录始终会显示规范形式（例如 claude-haiku-4-5-20251001）。请始终使用不带前缀的 slug，以保持命令、输出和路径一致。
• 重新推送时未指定 -d 会解除先前关联的数据集。如果任务的旧版本关联了 Kaggle 数据集，而重新推送时没有重复指定 -d 标志，命令会向 stderr 打印黄色警告，并静默解除这些数据集的关联。每次推送时都要重复完整的 -d 列表。
• 为已有笔记本补充源笔记本时，需同时使用 -f -s。如果最初下载时没有指定 -s，后续运行 download -s 会跳过缓存的运行，并打印提示。请使用 -f -s 重新运行，以覆盖缓存的运行并获取其源笔记本。
• log 按顺序输出，不会交错。多个运行处于活动状态时，CLI 会持续等待第一个运行的流，直到其结束后才处理下一个。这可以防止日志交错，但意味着一次只能等待一个运行。
• delete 尚未在服务端实现。该命令虽然存在，但目前会打印 Delete is not supported by the server yet.
• 多值标志需重复指定，不可用空格分隔。对于多值标志（-m、-d／--kaggle-dataset），每个值都要指定一次标志：-m a -m b，而不是 -m a b。不支持用空格分隔的形式，使用后会报错。
• CLI 仅适用于任务，不适用于基准测试。基准测试 是精心整理的任务集合。CLI 可以创建、推送和运行单个任务，但创建或管理基准测试（集合）必须在 Kaggle 网页 UI 中完成。

超越基础用法的 SDK 功能

以下是 任务编写技能 中更具拓展性的 kaggle_benchmarks 用法。当最简示例无法满足需求时，可以使用这些模式；完整的代码示例请参阅上游技能文档。

任务定义规则

• @kbench.benchmark 是 @kbench.task 的完全等价别名。选择更顺口的那个即可。
• 如果任务会返回值，必须添加返回类型注解。 def score(llm) -> float: — 如果没有 -> float / -> bool / -> dict 等注解，运行对象的 .result 类型就会出错。
• 子任务设置 store_task=False。 如果在另一个任务内部调用 @kbench.task（例如数据集评估中的逐行评分器），请在内部任务上设置 store_task=False，以避免将其作为顶层运行持久化。

运行对象

在执行 run = task_fn.run(...) 后：

• run.passed — bool，如果结果和每条断言都通过，则为 True。
• run.result — 返回值（类型由任务的返回类型注解决定）。
• run.assertion_results — list[AssertionResult]，包含记录的每条断言。

llm.prompt() 上的推理和温度设置

response = llm.prompt("Solve: 127 * 53?", reasoning="high")   # "low" | "medium" | "high"
traces   = kbench.last_reasoning_traces()                     # str | None — may be None if disabled/unsupported
response = llm.prompt("Write a creative story.", temperature=0.7)   # default 0

使用 last_reasoning_traces() 前，始终检查其返回值是否为 null。

多模态输入

from kaggle_benchmarks.content_types import images, videos, audios

# Images: from_url / from_path / from_base64
img = images.from_url("https://example.com/cat.jpg")     # llm.prompt auto-downloads + base64-encodes
img = images.from_path("local/chart.png")                # read + base64 immediately
img = images.from_base64(b64_str, format="png")          # default format="jpeg"

# Videos: YouTube URLs only (no local files, no non-YouTube URLs); select Gemini models only
video = videos.from_url("https://www.youtube.com/watch?v=...")

# Audio
audio = audios.from_path("speech.mp3")

response = llm.prompt("Describe this", image=img)

• llm.prompt(...) 会自动将图片 URL 下载为 base64（适用于不支持 URL 的模型）。user.send(...) 会原样传递 URL——可用它测试原生 URL 获取功能，但不支持此功能的模型会报错。
• 视频输入仅支持 YouTube，且仅限特定 Gemini 模型；本地文件或非 YouTube URL 会报错。

分支与隔离聊天历史

• chats.fork("name") — 将当前历史记录复制到临时分支；退出时不会更改原始聊天。
• contexts.enter(chat=...) — 以底层方式切换活动聊天，从而完全隔离 Agent 的历史记录。仅在 ChatRoom 不适用时使用（例如，各 Agent 必须彼此不可见的场景）。

多 Agent：ChatRoom + Participant（模式 I.5）

对于辩论 / 隐藏角色 / 谈判流程，优先使用 kbench.ChatRoom，而不是手动编写 contexts.enter() 连接逻辑。每个参与者都会看到经过视角投影的对话记录；同一个 kbench.llm 可以为多个参与者提供支持。

room = kbench.ChatRoom(system_prompt="A structured 2-turn debate.")
pro  = room.add_participant(llm, name="Pro", system_prompt="Argue FOR.")
con  = room.add_participant(llm, name="Con", system_prompt="Argue AGAINST.")
pro.reply()
con.reply()

完整操作指南请参阅 kaggle-benchmarks 仓库中的 docs/chatroom/rooms_walkthrough.md。

自定义断言

• @assertion_handler() — 将函数装饰为自定义断言处理器（返回或引发 AssertionResult）。使用 @assertion_handler(raises_assertion_error=True) 可在不匹配时明确报错。
• kbench.assertions.assert_tool_was_invoked(fn) — 验证模型是否在提示词期间实际调用了已注册的工具。