microsoft/SkillOpt · 上手攻略

仓库：microsoft/SkillOpt
链接：https://github.com/microsoft/SkillOpt
分类：agent / llm-infra
作者：Jay
更新：2026-07-09

是什么

SkillOpt 是微软研究院发布的文本空间优化器，用训练神经网络的方式为"冻结"的 LLM 智能体（即不修改模型权重）自动迭代优化自然语言技能文档（Markdown 格式的 best_skill.md），让 AI Agent 在执行特定任务时表现越来越好。

核心思路：把技能文档当作"可训练的权重"，配合专门的优化器模型（GPT-5.5 等）分析轨迹、打分、生成编辑补丁，再通过验证门控决定是否接受——整个流程和深度学习的"前向传播→反向梯度→优化器更新"完全对应。

论文：arXiv:2605.23904 文档：microsoft.github.io/SkillOpt PyPI：skillopt

解决什么问题

大多数 Agent 的技能靠人工编写、一次性 LLM 生成，或松散的自修订——这些方法没有稳定收敛保证，在反馈下容易退化或停滞。

SkillOpt 解决了三个核心问题：

技能优化缺乏系统化方法：技能文档没有标准训练流程，只能靠手工调。
反馈驱动的技能改进不稳定：无门控的自修订容易接受降低质量的编辑，导致技能退化。
技能跨模型/场景迁移差：手工技能难以复用，优化出来的技能在相似模型上效果也不传递。

实验结果（GPT-5.5 目标模型）： - 直接对话：无技能 → +23.5 分 - Codex CLI agentic loop：+24.8 分 - Claude Code CLI：+19.1 分

快速安装

方式 A：从 PyPI（推荐）

pip install skillopt

# 可选依赖
pip install skillopt[alfworld]    # ALFWorld benchmark
pip install skillopt[webui]        # Gradio 监控面板
pip install skillopt[claude]        # Claude 模型后端
pip install skillopt[qwen]          # 本地 Qwen 后端

方式 B：从源码

git clone https://github.com/microsoft/SkillOpt.git
cd SkillOpt
pip install -e .
# 可选
pip install -e ".[alfworld,webui,claude,qwen]"

验证安装

python -c "import skillopt; print('SkillOpt ready!')"

核心用法

1. 配置模型凭证

SkillOpt 统一使用环境变量，统一兼容 OpenAI 认证方式：

cp .env.example .env
# 编辑 .env 后
set -a; source .env; set +a

Azure OpenAI（默认）：

export AZURE_OPENAI_ENDPOINT="https://your-resource.openai.azure.com/"
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
export AZURE_OPENAI_API_KEY="your-key"

OpenAI 兼容端点：

export AZURE_OPENAI_ENDPOINT="https://api.openai.com/v1"
export AZURE_OPENAI_API_KEY="sk-..."
export AZURE_OPENAI_AUTH_MODE=openai_compatible

Anthropic Claude：

export ANTHROPIC_API_KEY="sk-ant-..."

本地 Qwen（vLLM）：

export QWEN_CHAT_BASE_URL="http://localhost:8000/v1"
export QWEN_CHAT_MODEL="Qwen/Qwen3.5-4B"

⚠️ 注意：SkillOpt 复用 AZURE_OPENAI_* 变量名来统一认证，即使对 OpenAI 兼容端点也是如此，没有独立的 OPENAI_API_KEY 变量。

2. 准备数据（以 SearchQA 为例）

SearchQA 约 6.5 GB，只需下载一次：

pip install datasets
python - <<'PY'
import json, os
from datasets import load_dataset

ds = load_dataset("lucadiliello/searchqa")
by_key = {r["key"]: r for split in ds.values() for r in split}

for split in ["train", "val", "test"]:
    ids = json.load(open(f"data/searchqa_id_split/{split}/items.json"))
    items = []
    for x in ids:
        r = by_key[x["id"]]
        items.append({"id": r["key"], "question": r["question"],
                      "context": r["context"], "answers": r["answers"]})
    os.makedirs(f"data/searchqa_split/{split}", exist_ok=True)
    json.dump(items, open(f"data/searchqa_split/{split}/items.json", "w"))
    print(split, len(items))
PY

其他 benchmark 参考 data/README.md 的数据源说明。

3. 开始训练

python scripts/train.py \
  --config configs/searchqa/default.yaml \
  --split_dir data/searchqa_split \
  --azure_openai_endpoint https://your-resource.openai.azure.com/ \
  --optimizer_model gpt-5.5 \
  --target_model gpt-5.5

常用参数：

参数	说明
`--config`	Benchmark 配置 YAML
`--split_dir`	数据切分目录
`--optimizer_model`	优化器模型（负责生成编辑）
`--target_model`	被优化目标模型
`--num_epochs`	训练轮数（默认 ~4）
`--batch_size`	Rollout 批大小
`--out_root`	输出目录
`--cfg-options k=v`	覆盖任意配置项

4. 仅评估（不训练）

python scripts/eval_only.py \
  --config configs/searchqa/default.yaml \
  --skill ckpt/searchqa/gpt5.5_skill.md \
  --split valid_unseen \
  --split_dir data/searchqa_split \
  --azure_openai_endpoint https://your-resource.openai.azure.com/

--split 取值：train（训练集）/ valid_seen（验证选择集）/ valid_unseen（测试集）

5. 监控面板（可选）

pip install -e ".[webui]"
python -m skillopt_webui.app --port 7860 --host 0.0.0.0 --share

6. 断点续训

SkillOpt 每步自动保存 runtime_state.json，重新运行相同命令即自动从上次位置继续。

输出结构

outputs/<run_name>/
 ├─ config.json          # 运行时配置
 ├─ history.json         # 每步训练历史
 ├─ runtime_state.json   # 断点续训状态
 ├─ best_skill.md       # ★ 最终最佳技能文档（部署用）
 ├─ skills/skill_vXXXX.md  # 每步快照
 ├─ steps/step_XXXX/    # 每步详细产物（补丁、评分等）
 ├─ slow_update/epoch_XX/  # 慢更新日志
 └─ meta_skill/epoch_XX/   # 元技能记忆

best_skill.md 就是部署用的技能文档，直接给目标模型加载即可。

典型适用场景

垂直领域 Agent 技能优化：如代码助手、客服机器人、数据分析助手，需要持续提升任务准确率。
多 Agent 协作时的技能迁移：优化好的 best_skill.md 可在不同模型间迁移（GPT-5.5 → GPT-5 → Claude 等），无需重新训练。
低成本提升模型表现：在不换模型、不重训练的情况下，通过优化提示词文档提升 +20 分以上。
技能库自动化构建：将组织的最佳实践写成初始 skill，让 SkillOpt 自动精炼成高质量可复用技能。
离线自我进化（v0.2.0 新增 SkillOpt-Sleep）：夜间自动回顾历史 session、重放常见任务、凝聚新技能，不需要在线模型调用。

坑与注意

数据需自行准备：benchmark 数据集不随仓库分发，必须按文档准备 train/val/test 切分 JSON 文件，否则训练无法启动。
凭证配置繁琐：统一用 AZURE_OPENAI_* 变量，对纯 OpenAI 用户容易混淆，注意设置 AZURE_OPENAI_AUTH_MODE=openai_compatible。
优化器模型要强：optimizer_model 建议 GPT-5.5 或同等水平，弱模型生成的编辑补丁质量低，优化效果差（论文中用 GPT-5.5 实验）。
ALFWorld 依赖特殊安装：pip install -e ".[alfworld]" 后还需运行 alfworld-download，且需要配置 $ALFWORLD_DATA 环境变量。
编辑频率并非越高越好：学习率过高（每步编辑数过多）会导致技能文档急剧退化，建议 moderate（文档建议 4-16 edits/step）。
v0.2.0 为最新版本：含 SkillOpt-Sleep 等新功能，但部分功能（如 cross-tool backends）仍为新引入，稳定性待观察。

与同类对比

方案	技能优化方式	门控机制	跨模型迁移	部署形式
SkillOpt	文本空间优化（自动迭代）	✅ 验证门控	✅ skill.md 可迁移	best_skill.md
手工 Prompt 工程	人工编写/修改	❌ 无	❌ 难迁移	prompt 模板
一次性 LLM 生成	一次生成，无迭代	❌ 无	❌ 难迁移	静态 prompt
ReAct / Self-Refine	自修订（无门控）	❌ 无稳定保证	❌ 差	模型内部
DSPy	程序化 prompt 优化	✅ 有（训练）	✅ 模块可迁移	程序模块

核心差异：SkillOpt 是目前唯一将完整深度学习训练循环（Rollout→Reflect→Aggregate→Select→Update→Gate）迁移到文本空间做技能优化的开源框架，且有严格的验证门控保证每次更新不低于现有水平。

一句话推荐结论

如果你想让 AI Agent 的任务表现随使用持续提升，而不是靠人工反复调 prompt，SkillOpt 是目前最系统化、有验证保障的开源选择——尤其是团队已有强优化器模型（如 GPT-5.5、Claude）时，投入产出比最高。