使用AgentToolDecisions-180K前必须知道的5个局限与常见坑位

AgentToolDecisions-180K 是一个面向 AI Agent 工具调用（tool-calling）场景的决策数据集：180,000 行带类型标注的决策样本，回答"该不该调工具、调哪个工具、参数齐不齐"这 6 类小问题，适合训练毫秒级响应的小模型工具路由（tool router）。但在动手训练前，有 5 个局限和坑位值得你先读完——尤其是克隆仓库后拿到的根本不是数据文件这一点，几乎每个新手都会踩到。

一、先花 1 分钟搞清楚：这个数据集长什么样

维度	内容
总行数	180,000（train / validation / test = 171,056 / 2,713 / 6,231）
决策组	101,786 个（同一 agent 状态下可派生多行决策）
任务族	6 类：动作类型、工具选择、参数完整性、工具或文本、响应偏好、When2Call
格式	扁平 Parquet，35 列，兼容 datasets、DuckDB、Polars、pandas
数据文件	11 个 parquet：train-00000-of-00009.parquet 等 9 个训练分片 + validation-00000-of-00001.parquet + test-00000-of-00001.parquet
真实数据总量	约 153.7 MB

完整说明见 README.md。核心卖点只有一个：无泄漏的划分——没有任何决策组或上游源行跨 split 出现。

二、坑位 1：克隆仓库后，parquet 文件只有 132 字节 ⚠️

这是最典型的新手坑。直接 git clone 仓库后，你会看到所有 *.parquet 文件都只有 132 字节左右，内容是：

version https://git-lfs.github.com/spec/v1
oid sha256:2625602f488d22b5e16cf078b14143a846f0e03a9595ff3e155033cbaf4720f3
size 8655362

这不是损坏——它们是 Git LFS 指针文件。因为仓库的 .gitattributes 对 *.parquet 配置了 filter=lfs，普通克隆只拉取指针，不拉取真实数据。

典型症状：用 pyarrow 打开时报错 Parquet magic bytes not found in footer. Either the file is corrupted or this is not a parquet file.

两种正确做法：

• ✅ 推荐：不碰仓库文件，直接用 datasets 库加载：

from datasets import load_dataset

ds = load_dataset("MaziyarPanahi/AgentToolDecisions-180K")

• ✅ 若坚持本地克隆，克隆后必须执行 git lfs pull 把真实数据拉下来（约 153.7 MB），再验证文件体积是否正常。

💡 判断是否踩坑的捷径：ls -la *.parquet，看到 100 多字节的"文件"，就是 LFS 指针，数据还没下载。

三、坑位 2：6 种决策任务混在一张表里，"整表训练"会串题

180,000 行不是一个分类任务，而是 6 个任务族的混合：

task_family	模型要回答的问题	行数
agent_next_action_type	下一步应该做什么类型的动作？	79,238
tool_selection	下一步该调哪个可用工具？	37,233
tool_argument_completeness	参数是否包含了 schema 要求的必填项？	37,233
tool_or_text_action	下一步是调工具还是直接文本回复？	14,349
tool_response_preference	哪个响应更好地使用/拒绝了工具？	8,295
when_to_call_tool	When2Call 风格：到底该不该调工具？	3,652

不同任务的问题、候选答案（criteria）甚至答案类型都不同。把全表拼在一起喂给一个分类头，等于让模型同时学 6 道题。README 官方给的用法是先按 task_family 过滤，例如只取 tool_selection 训练工具路由器。

避坑原则：训练、评估都按 task_family 分组进行，不要跨任务混算准确率。

四、坑位 3：gold_label 可能是 None，真实答案藏在 gold_score 里

数据集有两种答案类型（primitive 列）：

• choice：从 criteria_json 的候选里选一个标签，共 142,767 行，答案在 gold_label；
• noul：一个 0–1 之间的有界分数，共 37,233 行（全部是 tool_argument_completeness 任务），答案在 gold_score，此时 gold_label 为 None。

典型症状：训练脚本里直接 dataset["gold_label"] 做标签索引，跑到完整性任务行时抛出 TypeError 或产生一堆 None 标签。

正确姿势：写一行判断再取答案——

answer = row["gold_label"] if row["gold_label"] is not None else row["gold_score"]

同时注意 state_json、state_preview、criteria_json、request_json、gold_json 都是规范化 JSON 字符串（为了保持 Parquet schema 稳定），使用前要 json.loads，不是现成的 dict。

五、坑位 4：标签是程序化/自动化生成的，噪声与歧义无法避免

这是 README 明确声明的第一条 Limitation：所有标签来自上游数据（程序化或自动化），不含任何专有模型输出。各标签来源的行数分布：

label_source	行数	含义
programmatic_next_message	79,238	由下一条消息程序化推导
programmatic_schema_check	37,233	按 schema 检查参数完整性
programmatic_tool_call	37,233	由真实工具调用推导
programmatic_message_format	14,349	由消息格式推导
automated_preference_gold	8,295	自动化偏好标注
automated_verified_mcq_gold	3,652	自动化验证的多选题

实际影响：

• 评估时务必保留 label_source 和 task_family 字段分维度看指标，整体准确率会掩盖特定来源的噪声；
• 上游 agent 片段的工具 schema 和领域各不相同，分布并不均匀；
• request_json 是归一化后的 typed 请求格式，不是上游原始 schema——如果你要复现原始 Nemotron-SFT-Agentic-v2 / When2Call 的格式，这里拿不到；
• 数据集不含任何 Jev、TypeSafe 等专有模型的预测/概率/延迟列，想对比基线模型，需要自己用 request_json（可直接发送的 "model": "jev-1.13.0" 请求）跑一遍。

另外注意：test split 只有 6,231 行，validation 2,713 行，做统计显著性结论时样本量有限。

六、坑位 5：上游许可是"混合"的，再分发前必须逐行核对 ⚠️

数据集卡片的 license 字段是 other，许可名写着 mixed-upstream-terms-see-source-cards——直白说：许可条款混合，请以上游数据集卡片为准。

• 数据来自 nvidia/Nemotron-SFT-Agentic-v2（153,704 行）与 nvidia/When2Call（26,296 行）的固定 revision；
• When2Call 标注为 CC BY 4.0；Nemotron 卡片在其各组件上分别列出 CC BY 4.0、Apache 2.0、MIT；
• 每一行都保留了 source_license、source_revision、source_url、source_dataset 等溯源列。

避坑原则：

• 内部训练/评估一般没问题；但如果要再分发、做衍生数据集或商用产品，请先按 source_dataset 分组核对每行的 source_license，并遵守上游数据集卡片的条款与署名要求；
• 不要把这个数据集当临床/医疗数据用——它明确定位为通用 agent 决策数据集，且不含任何临床内容。

七、其他高频小坑速查 📋

坑	说明
行 ≠ 决策组	180,000 行来自 101,786 个决策组，一个 agent 状态会派生多行不同任务，按组采样时注意去重
字段分三类	模型输入看 question_text + state_json + criteria_json；答案看 gold_label/gold_score；溯源看 source_* 列，别混淆
没有附带模型权重	这是数据不是 checkpoint，README 提到的 ModernBERT 复现配方在另一个仓库，需要自行准备训练环境
镜像仓库只读	本仓库 README.md 与数据文件均不应被修改，parquet 文件请只读使用

八、避坑总结：使用前的 5 分钟检查清单 ✅

1. 确认数据真实落地：文件体积是否为 MB 级？load_dataset 是否成功读出了 180,000 行？
2. 按 task_family 过滤：只训练你需要的任务族，不要整表混训。
3. 处理 None 标签：取答案前判断 gold_label is not None，否则回退到 gold_score。
4. 分来源看指标：评估结果按 label_source × task_family 拆分，警惕自动化标签噪声。
5. 核对许可：再分发前逐行检查 source_license，遵守 When2Call（CC BY 4.0）与 Nemotron 的上游条款。

把这 5 步走完，你就可以放心地用这 18 万行"typed decisions"训练你的工具路由模型了——毫秒级响应的决策层，正是让 agent 又快又省的关键一环。