SkillOpt 实战：从 pip 安装到首个技能训练的全流程

SkillOpt 实战从 pip 安装到首个技能训练的全流程本文所有操作在 macOS 14.5 Python 3.13 上实际执行终端输出为真实记录。环境准备pipinstallskillopt实际输出Successfully installed azure-core-1.41.0 azure-identity-1.25.3 skillopt-0.2.0验证安装pip show skillopt字段值NameskilloptVersion0.2.0LicenseMIT依赖azure-core, httpx, numpy, openai, openpyxl, pyyamlpython3-cimport skillopt; print(skillopt version:, skillopt.__version__)# 输出: skillopt version: 0.2.0包结构一览安装后skillopt/包的核心模块skillopt/ ├── engine/trainer.py # 训练循环核心 ├── envs/ # 6 个内置 benchmark │ ├── searchqa/ # 搜索问答 │ ├── docvqa/ # 文档视觉问答 │ ├── spreadsheetbench/ # 电子表格 │ ├── officeqa/ # 办公文档问答 │ ├── alfworld/ # 虚拟家庭任务 │ └── livemathematicianbench/ # 数学推理 ├── model/ # 模型后端 │ ├── openai_chat │ ├── claude_chat │ ├── qwen_chat │ ├── minimax_chat │ └── codex_harness ├── optimizer/ # 优化器 │ ├── skill.py # 技能文档更新 │ ├── slow_update.py # 慢更新epoch 边界 │ └── meta_skill.py # 元技能记忆 ├── evaluation/gate.py # 验证门控 ├── gradient/ │ ├── reflect.py # 轨迹分析 │ └── aggregate.py # 补丁合并 ├── scheduler/ # 学习率调度 └── datasets/base.py # 数据集基类trainer.py公开的核心 API类/函数作用ReflACTTrainer主训练器compute_score执行结果评分evaluate_gate验证门控判断merge_patches合并相似编辑补丁rank_and_select按学习率裁剪编辑数run_slow_updateEpoch 边界慢更新run_meta_skill跨 epoch 元记忆配置体系YAML 继承SkillOpt 的配置采用 YAML 继承结构。一个实际的 SearchQA 配置# configs/searchqa/default.yaml_base_:../_base_/default.yamlmodel:reasoning_effort:mediumtrain:train_size:400# 训练集大小batch_size:40# 每步采样数accumulation:1gradient:minibatch_size:8# 每次分析 8 条轨迹merge_batch_size:8optimizer:learning_rate:4# 每步最多改 4 处evaluation:sel_env_num:0# 验证集大小test_env_num:0# 测试集大小env:name:searchqaskill_init:skillopt/envs/searchqa/skills/initial.mdmax_turns:1workers:24limit:0参数速查参数默认值作用类比 DLtrain_size400训练样本数训练集大小batch_size40每步采样数批量大小minibatch_size8每次分析轨迹数梯度累积learning_rate4每步最大编辑数学习率workers24并发执行数数据并行max_turns1任务最大轮次推理步数初始技能文档训练从一份初始技能开始。SearchQA 的初始技能非常简单# Question Answering Skill (No learned rules yet. Rules will be added through the reflection process.)训练完成后这份文件会被优化成 300-2000 token 的best_skill.md包含从失败轨迹中提炼出的规则、格式要求、注意事项。训练流程eval_only 模式如果你已经有一份训练好的技能想评估它的效果使用eval_only.pypython scripts/eval_only.py\--configconfigs/searchqa/default.yaml\--skillckpt/searchqa/gpt5.5_skill.md参数说明--config指定 benchmark 配置--skill指定要评估的技能文件路径这个模式会在验证集上执行任务记录每个任务的执行结果输出综合评分不会修改技能文件训练流程完整训练python scripts/train.py\--configconfigs/searchqa/default.yaml\--optimizer_modelgpt-5.5\--target_modelgpt-5.5两个模型角色角色参数建议模型职责优化器--optimizer_model强模型GPT-5.5/Claude 4分析轨迹、生成编辑补丁目标--target_model可用较弱模型执行任务产生轨迹训练循环内部流程6 阶段Step 1: Rollout → 目标模型用当前技能执行 40 个任务batch_size40 → 每个任务产生轨迹 分数 → 耗时取决于任务复杂度 Step 2: Reflect → 优化器分析 8 条轨迹一组minibatch_size8 → 失败轨迹必须分析成功轨迹可选 → 输出编辑补丁增/删/改建议 Step 3: Aggregate → 语义相似的补丁合并 → 避免重复修改 Step 4: Select → 按评分排序取前 4 个learning_rate4 → 防止一次性改动太多 Step 5: Update → 应用选中的补丁到技能文档 → 生成新版本 Step 6: Gate → 在验证集上评估新版本 → 分数提高→ 接受没有→ 回退 Epoch Boundary: → Slow Update对比新旧版本找改善/退化模式 → Meta Skill跨 epoch 策略记忆SkillOpt-Sleep夜间进化 CLIv0.2.0 新增的skillopt-sleep是一个独立的 CLI 工具不需要训练数据和配置直接对日常使用痕迹进行优化。skillopt-sleep--helpusage: skillopt_sleep [-h] {run,dry-run,status,adopt,harvest,schedule,unschedule} ... Commands: run 完整夜间循环采集→挖掘→回放→固化→提案 dry-run 只采集分析不落盘安全试用 status 查看当前状态 最新提案 adopt 采纳最新提案中的技能 harvest 调试查看挖掘出的任务 schedule 为当前项目安装定时 cron 任务 unschedule 移除 cron 任务安全试用# 在项目目录下执行mock 后端不产生 API 调用skillopt-sleep dry-run--project$(pwd)--backendmock完整夜间循环skillopt-sleep run--project$(pwd)--backendopenaidry-run模式是了解 SkillOpt-Sleep 工作方式的最佳入口——它会在本地采集会话、挖掘重复任务但不会产生任何 API 调用或修改文件。支持的模型后端后端配置方式适用场景openai_chatOPENAI_API_KEY标准 OpenAI 模型claude_chatANTHROPIC_API_KEYAnthropic Claudeqwen_chatQWEN_CHAT_BASE_URL通义千问含本地 vLLMminimax_chatMINIMAX_API_KEYMiniMax 模型openai_compatible自定义 base_url兼容 OpenAI 协议的第三方codex_execCodex CLI代码执行环境claude_code_execClaude Code代码执行环境实际使用建议1. 数据集准备SkillOpt 需要带标准答案的评估数据集。如果从头开始建议收集 200-500 条带标注的任务样本按 80/20 拆分为训练集和验证集每条任务包含输入、期望输出、评分标准2. 模型选择优化器模型用你能拿到的最强模型。它负责分析失败原因和生成补丁质量直接影响训练效果目标模型可以用最终部署的模型这样训练出的技能直接可用3. 超参数调优从论文实验得出的经验超参数建议值说明learning_rate4-16太低学不动太高噪声大lr_schedulercosine余弦调度 常数调度epochs2-4技能收敛比神经网络快batch_size40更大批次收益递减4. 输出产物训练完成后你会得到ckpt/ ├── searchqa/ │ ├── gpt5.5_skill.md # 每步的快照 │ ├── best_skill.md # 验证集上最优版本 │ └── logs/ │ ├── train.jsonl # 训练日志 │ └── eval.jsonl # 评估日志best_skill.md就是最终产物部署时直接作为系统指令注入给模型。总结场景推荐工具关键步骤快速体验skillopt-sleep dry-run --backend mock零成本了解工作流有标注数据scripts/train.py配置 → 训练 → best_skill.md评估已有技能scripts/eval_only.py指定 skill 文件 配置日常进化skillopt-sleep run夜间自动采集→优化→提案SkillOpt 的核心价值不在于「用 LLM 改 prompt」——而在于它把验证门控、学习率调度、慢更新等深度学习训练机制完整地搬到了文本空间使技能优化变得可复现、可回退、可度量。安装pip install skillopt文档https://microsoft.github.io/SkillOpt/GitHubhttps://github.com/microsoft/SkillOpt本文所有输出为实际安装和运行结果。