企业官网建设流程全解析

Agent Platform 微调 Hugging Face 数据集参考指南：加载、选列与列映射实践

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

导读

在 Agent Platform 模型微调（Model Tuning）流程中，训练数据是最关键的输入之一。本指南以 hf_datasets.md 为骨架，系统讲解如何从 Hugging Face 加载数据集、确认数据集与 split、进行源列到微调目标格式（prompt/completion或messages）的映射，并结合本仓库的prepare_dataset.py、tune_open_model.py、calculate_cost.py等脚本，给出从数据集发现、清洗转换到 JSONL 上传 GCS 的完整实战路径。读完本文，你将掌握面向不同任务（数学推理、指令跟随、多语言、编程、工具调用）挑选数据集、正确映射列并顺利提交微调任务的完整能力。

一、为什么微调前要先分析 Hugging Face 数据集

Agent Platform 微调服务要求训练数据为JSONL 格式并存放于 Google Cloud Storage（GCS），而 Hugging Face 上绝大多数数据集都以原始列结构（如problem、solution、answer）存在，无法直接用于微调。因此，在使用某个数据集之前，必须：

1. 理解数据集结构：明确数据集包含哪些列、每个 split 的样本量、内容是否贴合用户的任务；
2. 确认 split 与样本：向用户展示可用的 splits 并让其确认，同时预览若干样本；
3. 完成列映射：将源列映射到微调入口所需的目标格式——prompt（用户消息）与completion（助手回复），或messages格式。

该流程与 SKILL.md 中 "Phase 1.0 Dataset Discovery & Confirmation" 的要求一一对应：Agent 在准备数据集前必须向用户展示可用列、推荐列映射并取得确认，未确认前不得进行数据准备或上传。数据准备的详细格式规范见 Data Preparation Guide。

二、数据集加载与分片操作

2.1 加载整个数据集

使用 Hugging Face 的datasets库，一条命令即可拉取完整数据集：

from datasets import load_dataset dataset = load_dataset("username/dataset_name")

2.2 加载指定 split

如需指定某个 split（如default、train、test），传入split参数：

from datasets import load_dataset dataset = load_dataset("username/dataset_name", split="split_name")

2.3 大数据集的分片子集策略

对于体量很大的数据集（例如HuggingFaceTB/smoltalk2这类覆盖极广的数据集），建议：

• 优先使用 Hugging Face 页面中已定义好的 splits（如default）；
• 或主动为用户划分数据子集，只保留任务所需的部分；
• 在继续之前，务必让用户看到数据集的部分示例，避免盲目全量处理。

从本仓库的 prepare_dataset.py 源码可以看到，转换脚本内部也是通过datasets.load_dataset("csv"/"json"/"parquet", data_files=..., split="train")加载本地文件，再用dataset.filter()过滤空值、dataset.map()重排字段、train_test_split(seed=42, test_size=validation_split)划分验证集，最后以to_json(..., lines=True)写出 JSONL。也就是说，Hugging Face 数据集最终也要落成本地 CSV/JSON/Parquet 或 JSONL 后，才能被微调脚本消费。

三、强制确认流程：split 确认与列选择

[!IMPORTANT]关键：先确认，再继续。在执行数据集准备或上传之前，必须先完成以下两步并获得用户确认：

1. 数据集与 Split 确认：向用户展示数据集及其可用的 splits，请其确认使用哪个；同时展示少量样本供预览。
2. 列选择（Column Selection）：微调入口要求将源列映射到目标格式（prompt/completion或messages）。你必须：
   • 列出所选 split 中所有可用列；
   • 推荐哪些列应映射为prompt（或 user 消息）、哪些映射为completion（或 assistant 响应），必要时提供多个合理选项；
   • 请用户确认列映射，或由其指定要使用的列。

该确认机制在源码层面同样得到强化：prepare_dataset.py 在转换前会校验--prompt_col与--completion_col是否真实存在于数据集中，若列名错误会打印可用列列表并直接退出（sys.exit(1)）。因此列名必须来自真实数据，不能臆造。

四、数据集清单与任务选型

下文各数据集按任务类型分组，每个数据集都附有类型说明与使用提示。提示并非唯一用法，而是基于数据集本身特征给出的建议；同时应仔细阅读提示中关于数据内容的重要信息，因为它们可能与用户需求直接相关。

4.1 通用与推理类任务

数学推理（Mathematical Reasoning）

数学推理类任务在模型选型上可参考 models.md 的指引：Qwen 系列最擅长代码生成与复杂数学任务，因此qwen/qwen3@qwen3-8b、qwen/qwen3-14b等模型是这类数据集的理想搭配；模型资源名必须以{publisher}/{model_id}@{version_id}格式原样复制，例如qwen/qwen3-14b对应资源名qwen/qwen3@qwen3-14b。

指令跟随（Instruction Following）

多语言支持（Multilingual Support）

从 models.md 的选型指引可知，Gemma 系列针对聊天交互、创意写作与多语言任务做了优化，因此多语言数据集的推荐模型可优先考虑 Gemma 家族（如google/gemma3@gemma-3-4b-it）。

4.2 专业与技术类任务

编程与代码（Programming & Coding）

工具使用与集成（Tool Use & Integration）

编程与深度推理类任务按 models.md 的复杂度启发式应选择 8B-70B 规模模型，工具使用等复杂多轮任务则建议 27B-70B 模型，例如meta/llama3-3@llama-3.3-70b-instruct或qwen/qwen3@qwen3-32b。

五、从 Hugging Face 数据集到可微调 JSONL 的完整链路

5.1 转换：CSV/JSON/Parquet → JSONL

选定数据集与列映射后，使用 prepare_dataset.py 将数据转换为微调所需格式：

python3 scripts/prepare_dataset.py \ --input my_data.csv \ --output tuning_dataset.jsonl \ --format messages \ --prompt_col problem \ --completion_col solution \ --validation_split 0.1

参数说明（与脚本argparse定义一一对应，见 prepare_dataset.py）：

两种目标格式的结构（详见 data_prep.md）：

Conversational（messages）格式——推荐用于聊天类模型：

{ "messages": [ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "What is the capital of France?"}, {"role": "assistant", "content": "The capital of France is Paris."} ] }

Instruction（prompt/completion）格式——适合基座模型或简单补全任务：

{ "prompt": "Summarize the following text: [TEXT]", "completion": "[SUMMARY]" }

源码中 _format_row 正是把prompt_col/completion_col两列组装为上述两种结构：messages模式生成user/assistant两条消息，prompt模式直接输出prompt/completion键值对。

5.2 数据清洗的源码级实现

转换过程中脚本会自动执行以下清洗（见 prepare_dataset.py）：

• 删除 prompt 或 completion 为空的记录；
• 删除值为"nan"或"none"的记录（大小写不敏感、去除首尾空白后比较）；
• 清洗前后会打印丢弃行数，便于追踪数据质量。

5.3 验证 split 的字节上限约束

微调服务对验证集有严格限制：验证文件不得超过训练文件大小（按字节计）的 25%，且不超过 5000 行。由于上限按字节而非行数衡量，80/20 划分恰好压线，只要留出的验证行略长于平均就会超限（实测超限区间为 25.03%-26.45%），因此 data_prep.md 与脚本明确要求使用--validation_split 0.1，此时验证文件约占训练文件的 11%。

prepare_dataset.py 中的validation_ratio_error()会在上传前实测两个输出文件的字节数并提前拦截，让超限问题在提交微调任务之前就被发现，避免任务被服务端拒绝造成浪费。

5.4 上传到 GCS

格式验证通过后，将 JSONL 上传到用户确认的 GCS bucket（建议使用带时间戳的唯一目录，避免不同运行相互覆盖）：

ARTIFACTS="gs://YOUR_BUCKET/tuning_agent_job_<datetime>/dataset.jsonl" gcloud storage cp dataset.jsonl "$ARTIFACTS"

注意：绝不臆造 bucket 名称，也绝不在未经确认的情况下创建 bucket。若用户未指定 bucket，必须停下询问；新建 bucket 建议使用多区域位置US（若数据必须留在欧洲则用EU），因为开放模型默认在global位置微调，服务可能落在任意具备 GPU 容量的区域。

5.5 基于数据集规模的微调参数建议

选定数据集后，可依据 tuning_guide.md 的数据集规模启发式调整超参数：

各模型的基线超参数（tuning mode、learning rate、epochs、adapter size）与--base_model资源名详见 models.md。注意：FULL模式更新全部参数，需要更多 GPU 显存与更大数据集；PEFT_ADAPTER只训练少量 adapter 权重，更快、更省显存且小数据集下不易过拟合。

5.6 成本估算

提交任务前，可先用 calculate_cost.py 估算开放模型微调成本：

python3 scripts/calculate_cost.py \ --input tuning_dataset.jsonl \ --model "qwen/qwen3@qwen3-8b" \ --tuning_mode Full \ --epochs 3

--model接受显示名（如Qwen 3 8B）或与--base_model相同的资源名（如qwen/qwen3@qwen3-8b），脚本内部通过_build_aliases()建立别名映射后统一解析（见 calculate_cost.py）。成本估算公式为：

预估成本 = 数据集字符数 × tokens_per_character × epochs ÷ 1,000,000 × cost_per_1m_tokens

其中tokens_per_character是按微调模式实测的经验比率（PEFT 与 Full 使用不同训练容器，同一数据集在不同模式下的计费 token 数不同），cost_per_1m_tokens对应公开的 Model Tuning 价格表。需要注意的是，qwen/qwen3-5@qwen3.5-9b等条目已收录于目录但尚无公开定价，脚本会明确报错说明。估算结果仅为预估值，实际账单可能不同。

5.7 提交微调任务

开放模型微调任务通过 tune_open_model.py 提交：

python3 scripts/tune_open_model.py \ --project YOUR_PROJECT \ --location global \ --base_model qwen/qwen3@qwen3-8b \ --train_dataset gs://YOUR_BUCKET/tuning_agent_job_<datetime>/dataset.jsonl \ --output_uri gs://YOUR_BUCKET/tuning_agent_job_<datetime>/output \ --epochs 3 \ --learning_rate 5e-5 \ --tuning_mode Full

提交前注意：

• --base_model必须使用{publisher}/{model_id}@{version_id}资源名（可从 models.md 基线超参表 "Resource name" 列原样复制），@{version_id}后缀必不可少——省略后缀是最常见的INVALID_ARGUMENT: Invalid open source publisher model resource name报错原因；
• --output_uri对开放模型是必填的。虽然 Python SDK 将其声明为Optional[str] = None，但后端会以INVALID_ARGUMENT: The output_uri field is required for this model.拒绝缺省任务，脚本中也将其设为required=True（见 tune_open_model.py）；
• 提交前建议先运行scripts/list_models.py --project YOUR_PROJECT --filter gemini从输出中挑选真实的模型 ID，不要臆造 ID 或版本号；
• 任务提交与后续部署均属 Tier M 变更操作，必须先向用户展示完整命令字符串并取得确认。

六、结语

Hugging Face 数据集是 Agent Platform 微调流程中最常见的训练数据来源，但其原始列结构无法直接被微调服务消费。本指南基于 hf_datasets.md 梳理了从数据集加载、split 确认、列映射到 JSONL 转换、GCS 上传、成本估算与任务提交的完整链路，并给出了数学推理、指令跟随、多语言、编程、工具调用五类任务的精选数据集清单。读者可继续结合 Data Preparation Guide、Models Catalog 与 Tuning Guide，以及仓库中的prepare_dataset.py、calculate_cost.py、tune_open_model.py、list_models.py、monitor_tuning_job.py脚本，完成一次从数据到微调模型的端到端实践。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills