SkillOpt 完全指南：像训练神经网络一样训练 Agent 技能文档

SkillOpt 完全指南像训练神经网络一样训练 Agent 技能文档【免费下载链接】SkillOptSkillOpt is a text-space optimizer that trains reusable natural-language skills for frozen LLM agents through trajectory-driven edits, validation-gated updates, and deployable best_skill.md artifacts.项目地址: https://gitcode.com/gh_mirrors/sk/SkillOptSkillOpt 是一个开源的文本空间优化器text-space optimizer它把 Agent 的自然语言技能文档当作可训练状态通过轨迹驱动的编辑、验证门控更新最终产出可直接部署的best_skill.md工件。本指南以项目文档首页 docs/index.md 为核心骨架系统梳理其两大工作流、七阶段训练管线、深度学习类比、内置基准与模型后端并结合仓库源码与配置文件给出可直接复现的 SearchQA 实战流程。读完你将掌握 SkillOpt 的完整运行机制并能独立完成安装、配置、训练、评估与监控。两个互补的工作流SkillOpt 提供两套独立入口共享有界文本更新 验证的核心思想但拥有不同的配置与安全边界工作流包 / 命令用途研究引擎Research engineskillopt、skillopt-train、skillopt-eval在明确的基准划分train/validation/test split上训练和评估技能文档SkillOpt-Sleep预览skillopt_sleep、skillopt-sleep回顾受支持的编码 Agent 会话将提议的记忆/技能更新暂存staging供人工采纳使用真实会话数据之前建议先阅读 SkillOpt-Sleep 概览了解其数据边界harvest → mine → replay → consolidate背后有保留验证门控。工作原理七阶段训练管线SkillOpt 将技能文档视为冻结 Agent 的可训练状态优化器模型把带评分的 rollout 轨迹转化为对单个技能文档的有界增删改add/delete/replace编辑。在默认的论文式路径中候选编辑只有在严格提升保留验证集held-out validation分数时才会被接受。文本化的学习率预算、被拒编辑缓冲区rejected-edit buffer以及按 epoch 的慢更新/元技能机制共同保证了训练的稳定性且部署时零推理期模型调用。核心循环Rollout → Reflect → Aggregate → Select → Update → GateRollout前向传播目标模型使用当前技能文档作为提示执行任务产生轨迹与分数。Reflect反向传播/梯度优化器分析轨迹小批量产出结构化的编辑补丁edit patches。失败小批量始终进入分析成功轨迹默认也会被分析除非开启gradient.failure_only。独立小批量可依据gradient.analyst_workers并发执行。Aggregate梯度聚合对语义相似的编辑补丁做层级合并hierarchical merge避免冗余编辑。Select梯度裁剪按相关度对编辑排序optimizer.learning_rate限制每步最多应用的编辑数。Update参数更新 / SGD 步将选中的补丁应用到技能文档产生新版本。Gate验证在 selection split相当于验证集上评估新技能启用门控时只有分数严格高于当前技能才接受evaluation.use_gate: false时仍记录验证分数但强制接受每个候选。Epoch 边界还有两个纵向机制Slow Update动量式纵向对比从 epoch 2 开始比较上一 epoch 技能与当前技能在同一批样本上的表现分类为改进/回退/持续失败/稳定成功生成高层指导用于对抗跨 epoch 遗忘与Meta Skill跨 epoch 优化器策略记忆从 epoch 2 末尾开始累积压缩记忆并在后续 reflect/update 阶段作为额外上下文。源码层面的印证训练入口 scripts/train.py 通过懒注册维护_ENV_REGISTRY按env.name解析到各基准的EnvAdapter主训练循环实现在 skillopt/engine/trainer.py其中train()方法串起各阶段_normalise_patches、_build_longitudinal_pairs、_format_rejection_buffer等方法分别对应补丁规整、纵向对比对构造与被拒编辑缓冲区的组织。基准适配器如skillopt/envs/searchqa/、skillopt/envs/docvqa/、skillopt/envs/officeqa/继承自 skillopt/envs/base.py 的EnvAdapter只需实现build_train_env、build_eval_env、rollout、get_task_types四个抽象方法reflect()共享实现默认继承。深度学习类比超参数即训练配置SkillOpt 的核心洞见是优化自然语言提示与训练神经网络遵循同一结构。官方给出完整映射表深度学习SkillOpt说明模型权重技能文档Markdown被优化的对象前向传播Rollout目标模型用当前技能执行任务损失函数任务评估器给任务执行质量打分反向传播Reflect优化器分析失败 → 编辑补丁梯度编辑补丁对技能的提议修改梯度聚合补丁聚合合并相似编辑梯度裁剪编辑选择限制每步最大编辑数学习率learning_rate每步最多应用的编辑数学习率调度lr_schedulercosine / linear / constant / autonomousSGD 步技能更新将选中补丁应用到文档验证集Selection split门控在接受前检查改进动量Slow updateepoch 边界的纵向比较元学习Meta skill跨 epoch 优化器策略记忆批量大小batch_size每次 rollout 采样的任务数数据并行analyst_workers并行反思 worker 数检查点技能快照每个被接受步骤后保存实验经验法则来自项目文档 docs/guide/dl-analogy.md余弦调度优于常数调度中等学习率4–16优于过高/过低编辑太少学得慢、太多太吵慢更新能防止跨 epoch 灾难性遗忘元技能记忆改善反思。反之更大的 rollout 批量收益递减API 成本上升技能收敛快于神经网络2–4 个 epoch 通常足够。内置基准基准类型配置DocVQA文档问答configs/docvqa/ALFWorld具身智能configs/alfworld/OfficeQA企业问答configs/officeqa/SearchQA开放域问答configs/searchqa/LiveMathematicianBench数学推理configs/livemathematicianbench/SpreadsheetBench电子表格编辑configs/spreadsheetbench/每个基准都是skillopt/envs/name/下的一个包适配器 数据加载器 带评分的 rollout 辅助 YAML 配置 可选初始种子技能。注册采用懒加载见 scripts/train.py 的_register_builtins()缺失可选依赖时以try/except ImportError静默跳过不会破坏--help。扩展指南见 docs/guide/new-benchmark.md。模型后端优化器与目标角色分离优化器与目标角色分别配置。聊天类后端包括 Azure OpenAIopenai_chat、提供方中立的openai_compatible、Claude Code CLIclaude_chat、Qwen 与 MiniMaxCodex 与 Claude Code 的 exec 执行器codex_exec、claude_code_exec仅作为目标角色需要适配器支持。注意claude_chat实际启动claude -p并非直接的 Anthropic API 客户端。后端优化器目标openai_chat✓✓openai_compatible✓✓claude_chat✓✓qwen_chat✓✓minimax_chat✓✓copilot_chat✓✓codex_exec✓✓claude_code_exec—✓cursor_exec—✓copilot_exec—✓如果某个提供方实现了 OpenAI Chat Completions 协议应优先使用内置的openai_compatible后端文档见 docs/guide/new-backend.md而不是新写集成。认证与按角色覆盖详见 配置指南。快速上手完整跑通 SearchQA以下命令序列完整覆盖安装 → 配置凭据 → 数据物化 → 训练 → 评估# 克隆并安装研究版 checkout 及 SearchQA 数据扩展 git clone https://github.com/microsoft/SkillOpt.git cd SkillOpt python -m pip install -e .[searchqa] # 配置凭据在 .env 中选择一种认证方式 cp .env.example .env set -a; source .env; set a # 从仓库内置的 ID manifest 物化可运行的数据划分 python scripts/materialize_searchqa.py # 在 SearchQA 上训练输出到可预测的目录 python scripts/train.py \ --config configs/searchqa/default.yaml \ --out_root outputs/searchqa_quickstart # 评估最优技能 python scripts/eval_only.py \ --config configs/searchqa/default.yaml \ --skill outputs/searchqa_quickstart/best_skill.md \ --split valid_unseen要点说明仓库只内置 SearchQA 的稳定 ID manifest不包含完整可运行样本因此必须先安装[searchqa]扩展并运行物化脚本一次。物化器默认读取data/searchqa_id_split/把训练/验证/测试负载写到data/searchqa_split/两个路径都有命令行覆盖项见 docs/guide/first-experiment.md。训练入口 scripts/train.py 打印解析后的后端/数据配置、每步 rollout 与门控进度及输出目录任何 YAML 键都可通过--cfg-options覆盖例如optimizer.learning_rate16。显式--out_root会生成标准运行目录config.json、runtime_state.json、history.json、best_skill.md、skills/、steps/、slow_update/、meta_skill/。评估脚本 scripts/eval_only.py 会把eval_summary.json写入自己带时间戳的outputs/eval_.../目录不会覆盖训练产物。安装与凭据详见 安装指南Python ≥ 3.10.env不会自动加载需set -a; source .env; set a导出到当前 shell。配置深入核心超参数与默认值SkillOpt 加载结构化 YAML解析_base_继承并拍平后交给 trainer。默认值集中在 configs/base/default.yaml各基准配置覆盖之。以下是关键参数族完整参考见 docs/reference/config.md训练trainnum_epochs: 4epoch 数、batch_size: 40每步采样任务数、accumulation: 1每步累积轮数、seed: 42。梯度/反思gradientminibatch_size: 8反思小批量、merge_batch_size: 8补丁合并批量、analyst_workers: 16并行反思 worker、failure_only: false仅反思失败。优化器optimizerlearning_rate: 4每步最大编辑补丁数即编辑预算、min_learning_rate: 2衰减调度下限、lr_scheduler: cosineconstant/linear/cosine/autonomous、lr_control_mode: fixed、skill_update_mode: patchpatch/rewrite_from_suggestions/full_rewrite_minibatch、use_slow_update: trueepoch 边界纵向更新、slow_update_samples: 20、use_meta_skill: true跨 epoch 优化器记忆。可选的技能感知反思use_skill_aware_reflection默认关会把失败路由为 SKILL_DEFECT规则错误→常规门控正文编辑或 EXECUTION_LAPSE规则存在但未遵守→追加到受保护附录区逐级编辑永不触碰。评估evaluationuse_gate: true默认且论文式设置false记录验证但强制接受每个候选、gate_metric: hardhard/soft/mixed、gate_mixed_weight: 0.5、eval_test: true训练后跑测试评估。环境envname基准名、skill_init初始技能文档、split_mode: ratioratio从data_path确定性切分split_dir使用预切分目录、split_ratio如2:1:7、split_seed: 42、exec_timeout: 120单任务超时秒数、out_root。模型modelbackend: azure_openai向后兼容的高层运行标签、optimizer_backend/target_backend默认openai_chat、optimizer/target默认gpt-5.5训练/评估入口在后端初始化后应用这两个值覆盖同名环境变量因此选用 OpenAI-compatible 或 Qwen 后端时务必在 YAML 里显式设置两个角色的模型、reasoning_effort: medium、rewrite_max_completion_tokens: 64000。值得注意的兼容性细节Codex 的codex_bin/codex_cli_bin/codex_path是codex_exec_path的别名codex_sandbox/sandbox是codex_exec_sandbox的别名空白/null值让对应的CODEX_EXEC_*环境变量生效生效优先级为显式命令行/YAML 值 → 环境变量 → 内置安全默认。Qwen 的 thinking 模式是三态设置server_default默认不发送chat_template_kwargs端口最安全、enabled/disabled显式发送enable_thinking可复现的跑批建议显式 pin。训练进程可视化训练进程中可通过 epoch 检查点观察收敛趋势。下图展示 SpreadsheetBench、SearchQA、LiveMath 三个基准上训练 rollout、selection best 与 unseen test 分数随 epoch 的变化如需浏览器端监控可安装 WebUI 扩展并启动pip install -e .[webui]然后python -m skillopt_webui.app默认监听http://localhost:7860默认 host 为0.0.0.0本地使用建议--host 127.0.0.1详见 首次实验指南。延伸阅读训练循环详解各阶段细节与 epoch 边界机制深度学习 ↔ SkillOpt 类比表完整超参数映射与迁移规则配置参考全部参数的默认值与取值范围配置指南后端选择、CLI 覆盖与三套 OpenAI-compatible 路径安装指南可选依赖ALFWorld、Claude、Qwen、WebUI、dev与环境变量新增基准指南约 200 行代码接入自有基准SkillOpt-Sleep 概览夜间离线自进化引擎的预览工作流CLI 参考 与 API 参考命令与接口速查【免费下载链接】SkillOptSkillOpt is a text-space optimizer that trains reusable natural-language skills for frozen LLM agents through trajectory-driven edits, validation-gated updates, and deployable best_skill.md artifacts.项目地址: https://gitcode.com/gh_mirrors/sk/SkillOpt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考