RD-Agent FT-Agent 实战指南：用 LLM 智能体自动完成基准驱动的模型微调闭环-育师

RD-Agent FT-Agent 实战指南：用 LLM 智能体自动完成基准驱动的模型微调闭环

【免费下载链接】RD-AgentResearch and development (R&D) is crucial for the enhancement of industrial productivity, especially in the AI era, where the core aspects of R&D are mainly focused on data and models. We are committed to automating these high-value generic R&D processes through R&D-Agent, which lets AI drive>项目地址: https://gitcode.com/GitHub_Trending/rd/RD-Agent

本篇指南基于仓库中的 FT-Agent 场景文档，系统讲解如何在 RD-Agent 中运行「自动 LLM 微调」流程：从基准任务定义、原始数据集准备，到生成 LLaMA-Factory 训练配置、fail-fast 校验、OpenCompass 评估反馈的完整闭环。读完后你可以独立配置.env、跑通单次/批量微调任务，并理解其背后各组件（场景初始化、基准适配器、校验器、反馈生成）的源码级实现。

一、FT-Agent 是什么：基准驱动的微调闭环

FT-Agent 是 RD-Agent 中的 LLM 微调场景实现（研究导向），对应 ICML 2026 论文 FT-Dojo 的实验载体。它自动化的核心循环包含 5 个环节：

检查目标基准与可用原始数据集（inspect benchmark and raw datasets）；

生成数据处理代码和 LLaMA-Factory 训练配置（generate>git clone https://github.com/microsoft/RD-Agent cd RD-Agent make dev

四、最小`.env`配置

在仓库根目录创建.env，模型名与 API 设置按你的服务商调整。以下为官方文档给出的最小可用配置（完整保留）：

# LLM backend BACKEND=rdagent.oai.backend.LiteLLMAPIBackend CHAT_MODEL=gpt-4o CHAT_TEMPERATURE=1 CHAT_STREAM=True OPENAI_API_KEY=<your_api_key> # OPENAI_API_BASE=<your_api_base_if_needed> # Embedding model used by RD-Agent infrastructure EMBEDDING_MODEL=text-embedding-3-small # Fine-tuning workspace. Keep this stable to reuse downloaded models/datasets. FT_FILE_PATH=/absolute/path/to/finetune_files # Runtime environment: docker is the default path; conda is available for local setups. FT_Coder_CoSTEER_env_type=docker # Target task. You may also pass these through CLI arguments. FT_TARGET_BENCHMARK=aime25 FT_BENCHMARK_DESCRIPTION="AIME 2025 math competition problems. Each answer is an integer from 0 to 999. Expected Output Format: put the final answer within \\boxed{}, for example \\boxed{42}." # Target model and>rdagent llm_finetune \ --benchmark aime25 \ --benchmark-description "AIME 2025 math competition problems. Each answer is an integer from 0 to 999. Expected Output Format: put the final answer within \\boxed{}, for example \\boxed{42}." \ --base-model Qwen/Qwen2.5-7B-Instruct \ --loop-n 3 \ --timeout 12h

5.2 等价的直接 Python 入口

dotenv run -- python rdagent/app/finetune/llm/loop.py \ --benchmark aime25 \ --benchmark-description "AIME 2025 math competition problems. Each answer is an integer from 0 to 999. Expected Output Format: put the final answer within \\boxed{}, for example \\boxed{42}." \ --base-model Qwen/Qwen2.5-7B-Instruct \ --loop-n 3 \ --timeout 12h

5.3 参数说明

参数	含义
`--base-model`	待微调的 HuggingFace 模型 ID；除非已设置`FT_BASE_MODEL`，否则必填
`--benchmark`	目标基准 key，如`aime25`、`chemcotbench_mol_edit`
`--benchmark-description`	自然语言的任务与输出格式描述；除非已在`.env`中设置，否则必填
`--dataset`	数据集准备完成后供智能体选择的数据集名
`--upper-data-size-limit`	单个实验使用的训练样本上限
`--loop-n`	RD-Agent 循环的最大轮数
`--timeout`	整体墙钟预算，如`12h`

从 loop.py 的 main 函数可以看到几条硬约束：user_target_scenario目前尚未支持（传入会被断言拒绝），必须通过benchmark+benchmark_description指定目标；--base-model实际也必填（自动选模型的逻辑尚未实现，代码中保留了 TODO 断言）。若提供--path（形如$LOG_PATH/__session__/1/0_propose），还可以从断点恢复循环状态，--checkout控制是否清理该会话之后的日志。

5.4 运行时会发生什么（源码视角）

场景初始化LLMFinetuneScen（scen/scenario.py）是一个信息密度很高的阶段：

校验并创建FT_FILE_PATH，执行prepare_all()准备全部已注册数据集；若指定了base_model，还会确保模型资产存在；
通过LLaMAFactory_manager拉取 LLaMA-Factory 的方法与参数元信息，作为编码器的「知识源」；
生成dataset_info.json——数据集信息的单一事实来源，包含 LLaMA-Factory 兼容字段（file_name、formatting、columns）、自动统计、截断样本与 AI 生成的描述；
采集本机 GPU 运行时信息并生成显存估算报告（MemoryEstimator），供规划提示词引用；
运行基线评估：用目标模型在未微调状态下分别对基准的验证集与测试集打分。源码中注释明确：Agent 只可见验证集分数（baseline_benchmark_score），测试集分数（baseline_benchmark_score_test）仅供前端展示。验证/测试切分由get_benchmark_ranges()动态生成——小数据集（<200 样本）50/50 切分，大数据集各取 100 个样本，且保证两段不重叠（见 benchmark.py）。

六、批量运行（Job Runner）

多基准/多模型并行运行使用本目录的 job 辅助脚本：

cp rdagent/app/finetune/llm/job/tasks.json.example rdagent/app/finetune/llm/job/tasks.json cp .env rdagent/app/finetune/llm/job/.env bash rdagent/app/finetune/llm/job/run_ft_job.sh rdagent/app/finetune/llm/job/tasks.json

任务定义来自 tasks.json.example，结构如下：

{ "tasks": [ { "model": "Qwen/Qwen2.5-7B-Instruct", "benchmark": "aime25", "gpus": "0,1", "timeout": "12h" }, { "model": "Qwen/Qwen2.5-7B-Instruct", "benchmark": "chemcotbench_mol_edit", "gpus": "2,3", "timeout": "12h" }, { "model": "Qwen/Qwen2.5-7B-Instruct", "benchmark": "tablebench_visualization", "gpus": "4,5", "timeout": "12h", "benchmark_description": "Table Visualization - generate executable Python code to create the requested chart from tabular data. Expected Output Format: return Python code in a ```python code block using matplotlib or pandas." } ] }

任务字段说明（来自 job/README.md）：

字段	必填	默认值	说明
`model`	是	-	HuggingFace 模型 ID
`benchmark`	是	-	基准 key，如`aime25`、`chemcotbench_mol_edit`
`gpus`	否	`"0"`	写入`CUDA_VISIBLE_DEVICES`的值
`timeout`	否	`"12h"`	传给 FT-Agent 循环的墙钟预算
`port`	否	-	可选本地 API 端口；为该任务写入`OPENAI_API_BASE=http://localhost:<port>`
`benchmark_description`	否	取自`scenarios.json`	任务与输出格式描述

当任务条目未提供benchmark_description时，job runner 会从 job/scenarios.json 中按基准名查表补齐；两者都缺失时脚本直接报错退出。

从 run_ft_job.sh 的实现可以看到其工作机制：

依赖jq、tmux、conda（RD-Agent 的 conda 环境默认名为rdagent，可用CONDA_ENV_NAME覆盖）；
每个任务开一个 tmux 窗口（会话名rdagent），日志统一写入log/<job_id>/<task>.log，任务工作区位于git_ignore_folder/RD-Agent_workspace/<job_id>/<task>/；
第一个任务会等待场景初始化产物$FT_FILE_PATH/datasets/dataset_info.json出现后才放行其余任务，后续任务之间以 60 秒错峰启动；
运行模式由job/.env中的FT_Coder_CoSTEER_env_type决定：docker模式跳过 conda 环境就绪检查；conda模式则等待llm_finetune与opencompass两个环境初始化完毕。

七、fail-fast 校验：训练前的两道关卡

文档强调「完整训练前先做 fail-fast 校验」，其实现是 unified_validator.py 中的LLMConfigValidator，采用两/三步验证策略：

参数过滤（parameter filtering）：对照 LLaMA-Factory 实际支持的参数集合，剔除生成配置中的不支持项；
系统参数注入：注入受系统管理的参数（如overwrite_cache、save_only_model、output_dir=./output、per_device_eval_batch_size=1防评估 OOM），这些参数不进入对齐检查；
微批测试（micro-batch testing）：在小规模数据集上做运行时验证——由于微批测试本身覆盖了完整性校验，源码注释说明无需单独的完整性检查步骤。

此外，README Notes 指出：生成的训练数据必须使用 Alpaca 风格的instruction、input、output字段，校验器会在完整训练前检查这一点。对应超时配置为micro_batch_timeout（默认 30 分钟）与debug_data_processing_timeout（默认 20 分钟，用于编码阶段的 debug 数据处理）。

八、评估与反馈迭代

评估环节由 benchmark.py 的run_benchmark实现，要点包括：

在 Docker（或 conda）环境中渲染 OpenCompass 配置模板并执行opencompass <config> --work-dir <dir>；
通过adapter_config.json/adapter_model.*文件自动检测 LoRA 适配器；必要时（例如 vLLM 对含modules_to_save的 LoRA 支持受限）自动执行 LoRA 合并后再评估；
推理参数从configs/models.yaml按「精确匹配 → 最长前缀匹配 → default」三级合并，tensor_parallel_size: auto会向下取到最接近的 2 的幂；
评估结果除汇总准确率外，还会抽取至多 10 条错误样本（extract_error_samples）供智能体反馈分析；
已有同目录时间戳结果时直接复用（skip re-running），避免重复评估。

反馈生成由FTExperiment2Feedback（dev/feedback.py）完成：成功时基于基准分数、训练 loss 曲线（超 60 点时自动采样首尾各 30 点以控制 token 膨胀）与 SOTA/基线对比生成下一轮假设；失败时切换到错误分析提示词，并优先采用 runner 评估器产出的结构化分析（execution / return_checking / code 三段）而非裸错误字符串。文档 Notes 中「评估用验证集反馈驱动智能体迭代，测试集保留用于最终报告/前端展示」的设计，与上述源码注释完全一致。

九、日志与 UI 观察

运行产生的 RD-Agent trace 写入配置的日志目录。两种查看方式：

# FT 专用 Streamlit UI streamlit run rdagent/app/finetune/llm/ui/app.py # 通用 RD-Agent 日志 UI rdagent ui --port 19899 --log-dir <your_log_folder>

批量运行时，在 Streamlit UI 中选择生成的 job 文件夹作为日志源即可；也可以tmux attach -t rdagent或tail -f log/<job_id>/*.log实时监控。

十、实用注意事项汇总

首次运行预期缓慢：可能需要下载模型、数据集、LLaMA-Factory 资产与 OpenCompass 资产；
Docker 模式会把FT_FILE_PATH下的模型与数据集挂载进训练/评估环境；
训练数据格式必须是 Alpaca 风格三字段（instruction/input/output），否则会被校验器拦截；
验证/测试隔离：智能体迭代只看验证集反馈，测试集分数仅在最终报告与前端展示，避免评估泄漏；
成本控制：FT_API_MAX_WORKERS（默认 8）、FT_UPPER_DATA_SIZE_LIMIT（默认 2000）、--loop-n、--timeout以及benchmark_limit（快速调试时可限制评估样本数）是主要预算控制旋钮。

参考文件：场景文档 README、入口 loop.py、配置 conf.py、循环 scenarios/finetune/loop.py、场景 scen/scenario.py、评估 benchmark/benchmark.py、批量任务脚本 job/run_ft_job.sh。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

RD-Agent FT-Agent 实战指南：用 LLM 智能体自动完成基准驱动的模型微调闭环