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-trainscripts.train:main运行技能优化训练循环skillopt-evalscripts.eval_only:main仅执行评估skillopt-sleepskillopt_sleep.__main__:mainSkillOpt-Sleep 部署伴侣工具需要特别说明的是wheel 包不包含以下内容这些文件需要源码检出才能获得仓库内置的 Benchmark 配置即 configs/ 目录数据物化脚本如 scripts/materialize_searchqa.pyAgent 集成外壳 / 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_compatibleSkillOpt-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 Benchmarkpython -m pip install -e .[alfworld]安装alfworld0.4.0与gymnasium0.29.0。仅在运行 ALFWorld 环境时需要相关代码位于 skillopt/envs/alfworld/。Claude agent SDK可选python -m pip install -e .[claude]该 extra 安装claude-agent-sdk0.1.0与json_repair0.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]安装vllm0.4.0与json_repair0.61.0用于通过 vLLM 本地服务 Qwen 模型。SearchQA 数据物化python -m pip install -e .[searchqa]安装datasets2.18.0配合 scripts/materialize_searchqa.py 物化 SearchQA 数据划分。WebUI 仪表盘python -m pip install -e .[webui]安装gradio4.0.0用于运行 skillopt_webui/ 图形化界面。开发Developmentpython -m pip install -e .[dev]安装ruff0.4.0与pytest8.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运行命令前需将其导出到当前 shellset -a source .env set aset -a使后续导出的变量自动标记为 exportset a关闭该行为。Azure OpenAIopenai_chat后端使用 API Key 认证时最小配置如下AZURE_OPENAI_ENDPOINThttps://your-resource.openai.azure.com/ AZURE_OPENAI_API_VERSION2024-12-01-preview AZURE_OPENAI_API_KEYyour-key AZURE_OPENAI_AUTH_MODEapi_keyAZURE_OPENAI_AUTH_MODE支持三种取值见 .env.example认证模式说明api_key使用AZURE_OPENAI_API_KEYazure_cli使用 Azure CLI 凭据无需 API KeyAzure VM 上推荐managed_identity托管身份可选配AZURE_OPENAI_MANAGED_IDENTITY_CLIENT_IDClaude Code CLIclaude_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、插件与全局技能。Cursorcursor后端 /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_MODEopenai_compatible配合AZURE_OPENAI_ENDPOINT与AZURE_OPENAI_API_KEY使用——此时创建的是普通 OpenAI 客户端无 Azure 认证与 api-version见 .env.example。SkillOpt-Sleepskillopt-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 查看全部配置项新增 BenchmarkNew Benchmark 了解如何接入新环境。【免费下载链接】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），仅供参考