SkillOpt 安装指南：PyPI、源码与多后端环境变量配置全解析-二趣网

SkillOpt 安装指南：PyPI、源码与多后端环境变量配置全解析

【免费下载链接】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

本文是 SkillOpt（面向冻结 LLM Agent 的自然语言技能文本优化器）的完整安装与初始化指南。文章以仓库 docs/guide/installation.md 为骨架，结合 pyproject.toml、.env.example 与后端解析源码，系统讲解 PyPI 与源码两种安装路径、各可选依赖（extras）的适用场景，以及 Azure OpenAI、Claude Code CLI、OpenAI 兼容端点等后端的认证配置。读完本文，你将能独立完成环境搭建、模型后端配置与安装验证，并具备运行首次训练实验的前提条件。

系统要求

安装 SkillOpt 之前，请确认环境满足以下条件：

Python ≥ 3.10。项目在 pyproject.toml 中通过requires-python = ">=3.10"声明，并在元数据中标注支持 Python 3.10 / 3.11 / 3.12。
至少一个已配置的模型后端，用于研究训练（skillopt-train）与评估（skillopt-eval）。后端可以是：
- 托管 API（如 Azure OpenAI、OpenAI 兼容网关、MiniMax）；
- 本地推理服务器（如通过 vLLM/SGLang 服务的 Qwen）；
- 已安装并完成认证的执行型 CLI（如 Claude Code CLI、Codex CLI、Cursor Agent、Copilot CLI、Pi coding-agent）。
SkillOpt-Sleep 的mock后端无需任何凭据。它由 skillopt_sleep/backend.py 中的MockBackend实现，完全确定性、不发起任何网络请求，适合在无 API Key 的情况下验证控制流与测试管线（详细机制见 docs/sleep/README.md）。

选择安装方式：PyPI 还是源码

SkillOpt 提供两种安装路径，二者面向不同的使用场景。

方式一：PyPI 安装（轻量使用）

python -m pip install skillopt skillopt-sleep --help

该命令会一并安装skillopt-train、skillopt-eval、skillopt-sleep三个命令行入口，其映射定义在 pyproject.toml 的[project.scripts]段：

命令	入口	用途
`skillopt-train`	`scripts.train:main`	运行技能优化训练循环
`skillopt-eval`	`scripts.eval_only:main`	仅执行评估
`skillopt-sleep`	`skillopt_sleep.__main__:main`	SkillOpt-Sleep 部署伴侣工具

需要特别说明的是，wheel 包不包含以下内容，这些文件需要源码检出才能获得：

仓库内置的 Benchmark 配置（即 configs/ 目录）；
数据物化脚本（如 scripts/materialize_searchqa.py）；
Agent 集成外壳 / MCP 服务器（即 plugins/ 目录下的 Claude Code、Cursor、Codex、Copilot、Devin 等插件）；
开发测试用例（tests/ 目录）。

方式二：源码安装（完整功能）

git clone https://gitcode.com/gh_mirrors/sk/SkillOpt.git cd SkillOpt python -m pip install -e .

源码检出适合以下场景：

论文复现：仓库携带全部内置 Benchmark 配置与数据物化脚本；
使用 main 分支新特性（见下文版本差异说明）；
为项目做贡献（开发流程见 CONTRIBUTING.md）。

PyPI 版本与`main`分支的差异（重要）

文档跟踪的是最新main分支，当前 PyPI 发布版本为0.2.0。以下能力在0.2.0发布之后才合入main，在下一个版本发布之前，只能通过源码安装获得：

通用研究后端openai_compatible；
SkillOpt-Sleep 的 handoff（交接）机制；
Sleep 对非 Azure 的 OpenAI 兼容端点的支持；
Sleep 的--preferences标志；
Cursor 的 source / backend / plugin 支持；
Pi 的 source / backend 支持；
多技能扇出（multi-skill fan-out）与人工复核子集采纳（reviewed subset adoption）。

如果你的场景依赖以上任一特性，请使用源码安装。

可选依赖（Extras）详解

SkillOpt 使用[project.optional-dependencies]（见 pyproject.toml）管理按需安装的依赖，按 Benchmark 或后端拆分为多个 extra。

ALFWorld（具身 Agent Benchmark）

python -m pip install -e ".[alfworld]"

安装alfworld>=0.4.0与gymnasium>=0.29.0。仅在运行 ALFWorld 环境时需要，相关代码位于 skillopt/envs/alfworld/。

Claude agent SDK（可选）

python -m pip install -e ".[claude]"

该 extra 安装claude-agent-sdk>=0.1.0与json_repair>=0.61.0（后者用于修复非 OpenAI 后端自由格式输出中的 JSON，见 requirements.txt 的注释说明）。

重要：此 extra不会安装claude可执行文件。研究用的claude_chat后端通过claude -p启动 Claude Code CLI（见 skillopt/model/backend_config.py 的说明），因此你需要单独安装并完成 Claude Code CLI 的认证。SDK extra 仅在需要选择 SDK 支撑的 Claude Code 执行路径时才使用。

Pi coding-agent CLI（可选）

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

仅在skillopt-sleep --backend pi时需要使用 Pi CLI 并完成认证。如果只是用--source pi从本地 Pi 转录中收割数据，则不需要安装 CLI 或配置提供商认证——默认情况下 source 读取~/.pi/agent/sessions目录，--pi-home可指定包含agent/sessions的父目录。

Qwen（本地模型）

python -m pip install -e ".[qwen]"

安装vllm>=0.4.0与json_repair>=0.61.0，用于通过 vLLM 本地服务 Qwen 模型。

SearchQA 数据物化

python -m pip install -e ".[searchqa]"

安装datasets>=2.18.0，配合 scripts/materialize_searchqa.py 物化 SearchQA 数据划分。

WebUI 仪表盘

python -m pip install -e ".[webui]"

安装gradio>=4.0.0，用于运行 skillopt_webui/ 图形化界面。

开发（Development）

python -m pip install -e ".[dev]"

安装ruff>=0.4.0与pytest>=8.0.0，用于代码检查与测试。

全量安装

python -m pip install -e ".[alfworld,claude,qwen,searchqa,webui,docs,dev]"

注意 pyproject.toml 中的allextra 只聚合了alfworld、gymnasium、claude-agent-sdk、json_repair，不包含 docs/dev/webui；需要文档站点、开发工具或 WebUI 时，请按上方的完整列表显式指定。

环境变量配置：模型后端认证

SkillOpt 将模型凭据通过环境变量注入，不会自动加载.env文件，需要手动导出到当前 shell。

复制并导出模板

从源码检出后，先复制模板，再只填写你将要使用的后端：

cp .env.example .env

模板文件 .env.example 内注释详尽，覆盖了全部后端。由于 SkillOpt 不自动加载.env，运行命令前需将其导出到当前 shell：

set -a source .env set +a

（set -a使后续导出的变量自动标记为 export，set +a关闭该行为。）

Azure OpenAI（`openai_chat`后端）

使用 API Key 认证时，最小配置如下：

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

AZURE_OPENAI_AUTH_MODE支持三种取值（见 .env.example）：

认证模式	说明
`api_key`	使用`AZURE_OPENAI_API_KEY`
`azure_cli`	使用 Azure CLI 凭据，无需 API Key（Azure VM 上推荐）
`managed_identity`	托管身份，可选配`AZURE_OPENAI_MANAGED_IDENTITY_CLIENT_ID`

Claude Code CLI（`claude_chat`后端）

研究用的claude_chat是Claude Code CLI 适配器，而非直接的 Anthropic API 客户端。它通过claude -p --output-format text调用 CLI。需要：

单独安装并认证claude可执行文件；
若可执行文件不在PATH中，设置CLAUDE_CLI_BIN指定完整路径；
ANTHROPIC_API_KEY是 CLI 可能消费的一种认证方式，SkillOpt 本身不直接调用 Anthropic API（配置表见 docs/guide/configuration.md）。

从源码实现看，skillopt/model/backend_config.py 中CLAUDE_CODE_EXEC_PATH默认值为claude，而claude_chat后端在未设置ANTHROPIC_API_KEY时以非--bare模式运行、设置后追加--bare标志，以隔离用户环境中的 hooks、插件与全局技能。

Cursor（`cursor`后端 /`cursor_exec`执行后端）

SkillOpt-Sleep 的cursor后端同样要求单独安装并认证cursor-agent；仅用--source cursor收割数据则不需要。可配置：

SKILLOPT_SLEEP_CURSOR_PATH：当可执行文件不在PATH时指定路径；
SKILLOPT_SLEEP_CURSOR_MODEL：覆盖其使用的模型。

研究侧的cursor_exec是 target-only 执行后端，相关配置（CURSOR_EXEC_PATH、CURSOR_EXEC_SANDBOX）在 skillopt/model/backend_config.py 中定义，sandbox 默认enabled。Cursor 插件安装与显式项目技能目标见 plugins/cursor/README.md。

OpenAI 兼容服务器的三条独立路径

OpenAI 兼容服务有三个互不混淆的入口，这是最容易踩坑的地方：

研究引擎通用openai_compatible后端：使用OPENAI_COMPATIBLE_BASE_URL、OPENAI_COMPATIBLE_API_KEY、OPENAI_COMPATIBLE_MODEL。适合 DeepSeek、Novita AI 等任意 Chat Completions 端点（示例见 .env.example）。
研究openai_chat的兼容模式：保留openai_chat后端，设AZURE_OPENAI_AUTH_MODE=openai_compatible，配合AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY使用——此时创建的是普通 OpenAI 客户端，无 Azure 认证与 api-version（见 .env.example）。
SkillOpt-Sleep：skillopt-sleep run --backend azure_openai复用与第 2 条相同的 Azure 系变量；Sleep不读取研究后端的角色专属变量（docs/guide/configuration.md 有完整对比）。

角色模型覆盖（optimizer / target）

在训练与评估入口（skillopt-train/skillopt-eval）中，YAML 配置里的model.optimizer与model.target会在后端初始化之后应用，并覆盖OPENAI_COMPATIBLE_MODEL、QWEN_CHAT_MODEL等模型名环境变量。因此选择这些后端时，务必在配置中显式设置两个角色模型。环境变量中还有OPTIMIZER_/TARGET_前缀的按角色覆盖形式（如OPTIMIZER_OPENAI_COMPATIBLE_MODEL），示例见 .env.example。相关后端实现细节可参考 docs/guide/configuration.md 的完整后端对照表。

最小化原则

你只需配置打算使用的后端。后端命名与角色覆盖的精确清单见 docs/guide/configuration.md；未使用的后端变量保持注释状态即可，避免无意义的凭据暴露。

验证安装

配置完成后，通过以下命令确认安装与命令入口均可用：

python -c "import skillopt; print('SkillOpt ready!')" skillopt-train --help skillopt-eval --help skillopt-sleep --help

如果只是验证 SkillOpt-Sleep 的流程而暂时没有模型凭据，可用--backend mock跑一个确定性实验（不产生任何 API 费用），相关提示见 docs/guide/local-env-smoke.md 与 docs/guideline.html。

下一步

安装与配置完成后，推荐按以下路径继续：

运行第一个实验：Run your first experiment 以 SearchQA 为例，演示从数据物化、配置、训练到评估的完整流程；
理解训练循环：Training Loop 讲解轨迹驱动编辑与验证门控的机制；
完整参数参考：Configuration Reference 查看全部配置项；
新增 Benchmark：New Benchmark 了解如何接入新环境。

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

企业官网建设流程全解析