AgentToolDecisions-180K进阶探索:DuckDB与Polars高速分析18万条决策数据的实战清单
AgentToolDecisions-180K进阶探索:DuckDB与Polars高速分析18万条决策数据的实战清单
AgentToolDecisions-180K 是一个包含 18 万条智能体工具决策记录的开源数据集,采用扁平化 Parquet 格式,可以直接被 DuckDB、Polars 等工具高速分析。本文面向新手整理了一份完整实战清单:从克隆数据到分片校验,用 DuckDB 和 Polars 快速摸清 180K 决策数据的分布、标签与质量。
数据集概览:18万条“决策账本”
AgentToolDecisions-180K 把 NVIDIA 的开源智能体数据转换成了 typed 决策格式——每条数据都是“一个问题 + 固定选项 + 唯一正确答案”。Agent 每一步背后都在做这些判断:该调工具还是回文本?调哪个工具?参数齐不齐?
核心指标一目了然(详见 README.md):
| 指标 | 数值 |
|---|---|
| 总行数 | 180,000 |
| Train / Validation / Test | 171,056 / 2,713 / 6,231 |
| 决策组(Decision groups) | 101,786 |
| 上游源行数 | 41,809 |
| 格式 | 扁平 Parquet,35 列 |
| 泄漏 | 无:决策组与源行均不跨 split |
数据覆盖六大决策任务族,是训练轻量级 tool router(工具路由器) 的理想语料:
| 任务族 | 模型要回答的问题 | 行数 |
|---|---|---|
agent_next_action_type |
助手下一步该执行什么类型的动作? | 79,238 |
tool_selection |
下一步该调用哪个可用工具? | 37,233 |
tool_argument_completeness |
工具调用是否包含所有必需参数? | 37,233 |
tool_or_text_action |
该调工具还是输出文本? | 14,349 |
tool_response_preference |
哪个回复更好地使用了工具? | 8,295 |
when_to_call_tool |
到底要不要调用工具? | 3,652 |
答案类型只有两种:choice(142,767 行,从候选项中选一个)和 noul(37,233 行,0–1 的有界分数)。
为什么选 DuckDB 与 Polars 高速分析
18 万行 × 35 列的扁平 Parquet,用传统“加载进 pandas 再遍历”的方式既慢又容易把内存撑爆。而 DuckDB 和 Polars 恰好是这类分析的最优解:
- DuckDB:进程内分析型数据库,直接对 Parquet 文件做 SQL 查询,零导入、零拷贝,扫 18 万行是毫秒级的事;
- Polars:基于 Arrow 的惰性(lazy)查询引擎,多核并行过滤与聚合,比 pandas 快一个数量级;
- 两者都能直接读文件路径,不需要先把 11 个分片拼成一个大文件。
数据集本身就是为此设计的——README 明确写着:flat Parquet, 35 columns, works with datasets, DuckDB, Polars and pandas。
准备工作:克隆数据与文件布局
由于 Parquet 大文件通过 Git LFS 存储(见 .gitattributes),克隆时确保本机安装了 git-lfs,否则只会拉下到 LFS 指针文件:
git clone https://gitcode.com/hf_mirrors/MaziyarPanahi/AgentToolDecisions-180K
cd AgentToolDecisions-180K
仓库文件布局非常简洁:
| 文件 | 用途 |
|---|---|
| train-00000-of-00009.parquet ~ train-00008-of-00009.parquet | 训练集,共 9 个分片 |
| validation-00000-of-00001.parquet | 验证集,2,713 行 |
| test-00000-of-00001.parquet | 测试集,6,231 行,无泄漏可放心评测 |
| README.md | 数据集卡片:字段说明、标签来源、审计结果 |
小贴士 📌 用 ls -lh 检查分片大小,如果每个文件只有一两百字节,说明 LFS 没有拉取,运行 git lfs pull 即可。
实战清单:6步摸清18万条决策数据
第1步:DuckDB 一行命令查看表结构
用通配符一次性挂上全部 9 个训练分片,不用写任何加载代码:
SELECT * FROM 'train-*.parquet' LIMIT 1;
DESCRIBE SELECT * FROM 'train-*.parquet';
关键字段分组(README “How to read a row” 一节):
- 标识:
row_id、group_id、output_split - 任务:
priority、task_family、primitive、question_key - 模型输入:
state_json、state_preview、question_text、criteria_json - 参考答案:
gold_label、gold_score、gold_json、label_source - 溯源:
source_dataset、source_row_id、source_license等
⚠️ 注意:嵌套载荷(state、request、criteria、gold)都是标准 JSON 字符串,不是真正的 JSON 列,查询时需要 DuckDB 的
json_extract_string或 Polars 的str.json_extract*解析。
第2步:按任务族统计分布,验证行数
SELECT task_family, count(*) AS rows
FROM 'train-*.parquet'
GROUP BY 1
ORDER BY 2 DESC;
结果应与上表 79,238 / 37,233 / 37,233 / 14,349 / 8,295 / 3,652 完全一致——这是最基础的完整性校验。
第3步:Polars 惰性加载与条件过滤
训练单个任务族(比如只练工具选择器)时,Polars 的 lazy 模式只扫需要的分片:
import polars as pl
df = pl.scan_parquet("train-*.parquet")
tool_sel = df.filter(pl.col("task_family") == "tool_selection")
# 输入:question_text + state_json;标签:gold_label
tool_sel.select("question_text", "state_json", "gold_label").collect().head()
惰性执行的优点是:先过滤后落地,内存里永远不会出现完整的 17 万行。
第4步:核对 label_source 与 task_family 的对应关系
标签全部来自上游的程序化或自动化流程,没有第三方模型输出。用一条聚合即可核对分布:
SELECT label_source, count(*) AS rows
FROM 'train-*.parquet'
GROUP BY 1 ORDER BY 2 DESC;
期望看到 6 种来源:programmatic_next_message(79,238)、programmatic_schema_check(37,233)、programmatic_tool_call(37,233)、programmatic_message_format(14,349)、automated_preference_gold(8,295)、automated_verified_mcq_gold(3,652),分别对应六大任务族——两者应严格一一对应,出现错配就是异常信号。
第5步:泄漏自检——确认 group_id 不跨 split
数据集宣称 split-safe(无泄漏)。自己动手验证一遍才安心:把三个 split 的 group_id 取交集,结果应为空:
-- train 与 test 之间不应共享任何决策组
SELECT t.group_id
FROM 'train-*.parquet' t
JOIN 'test-00000-of-00001.parquet' x USING (group_id)
LIMIT 1; -- 期望:0 行
同理可检查 source_row_id。这一步是评估可信度的前提:如果组泄漏,你在 test 上的准确率就是虚高的。
第6步:抽样检查 request_json,体验“即发即用”
每条数据的 request_json 都是可直接发送的 typed 请求("model": "jev-1.13.0",带 question、criteria 和 agent state)。抽几条看看结构:
df.select("request_json", "gold_label").slice(0, 3).unnest(
pl.col("request_json").str.json_normalize().alias("req")).collect()
这一步的价值:你可以用任何 typed 决策模型(或小模型路由器)跑完全相同的请求,直接和 gold_label 对比——即“Race Jev”玩法,无需额外造数据。
常见坑与避坑指南 🕳️
- LFS 指针文件:
head一下某个 parquet 若看到version https://git-lfs.github.com/spec/v1,就是没拉到大文件,执行git lfs pull。 - JSON 列是字符串:直接
WHERE request_json做布尔判断没有意义,记得先解析;DuckDB 支持json_extract_string(col, '$.field'),Polars 用str.json_extract系列。 gold_label与gold_score互斥:choice 类只有gold_label,noul 类只有gold_score,取值时注意判空(README 的 Quick start 里展示了row["gold_label"] if ... is not None else row["gold_score"]的写法)。- 标签可能有噪声:上游标签是程序化生成的,评测时务必保留
label_source和task_family,分族看指标,别只看总分。 - 许可注意:数据派生自
nvidia/Nemotron-SFT-Agentic-v2(CC BY 4.0 / Apache 2.0 / MIT 混合)与nvidia/When2Call(CC BY 4.0),每行都保留了source_license,二次分发前请查阅上游数据集卡片。
总结
AgentToolDecisions-180K 把“Agent 每一步的小决策”变成了 18 万条干净、带类型、可审计的训练数据。得益于扁平 Parquet 格式,DuckDB 一条 SQL 看分布、Polars 一行过滤练单任务,几分钟就能完成从数据体检到训练集切分的全流程。按上面 6 步清单走完,你手上就有一个无泄漏、可评测、即插即用的工具路由器训练集——毫秒级出决策,告别昂贵的整轮 LLM 调用 🚀