Yif-Yang
165 lines
4.3 KiB
Markdown
165 lines
4.3 KiB
Markdown
# Installation
|
|
|
|
## Requirements
|
|
|
|
- Python ≥ 3.10
|
|
- For research training/evaluation, access to at least one configured model
|
|
backend (hosted API, local server, or an installed execution CLI)
|
|
- The SkillOpt-Sleep `mock` backend needs no credentials
|
|
|
|
## Choose an Install
|
|
|
|
### PyPI
|
|
|
|
Use PyPI for the Python packages and installed commands:
|
|
|
|
```bash
|
|
python -m pip install skillopt
|
|
skillopt-sleep --help
|
|
```
|
|
|
|
This installs `skillopt-train`, `skillopt-eval`, and `skillopt-sleep`. The wheel
|
|
does not include the repository's benchmark configs, data materializers,
|
|
agent-integration shells/MCP servers, or development tests; use a source
|
|
checkout for those files.
|
|
|
|
!!! important "PyPI versus `main`"
|
|
These docs track the latest `main`. The current PyPI release is `0.2.0`.
|
|
The generic research `openai_compatible` backend, SkillOpt-Sleep handoff,
|
|
Sleep support for non-Azure OpenAI-compatible endpoints, and the Sleep
|
|
`--preferences` flag landed after that release and require a source install
|
|
from `main` until the next release.
|
|
|
|
### Source checkout
|
|
|
|
```bash
|
|
git clone https://github.com/microsoft/SkillOpt.git
|
|
cd SkillOpt
|
|
python -m pip install -e .
|
|
```
|
|
|
|
Use the source checkout for paper reproduction, built-in benchmark configs,
|
|
and contributions.
|
|
|
|
## Optional Dependencies
|
|
|
|
Install extras for specific benchmarks or backends:
|
|
|
|
=== "ALFWorld"
|
|
|
|
```bash
|
|
python -m pip install -e ".[alfworld]"
|
|
```
|
|
|
|
=== "Claude agent SDK (optional)"
|
|
|
|
```bash
|
|
python -m pip install -e ".[claude]"
|
|
```
|
|
|
|
This extra does not install the `claude` executable. The research
|
|
`claude_chat` backend launches `claude -p`, so install and authenticate the
|
|
Claude Code CLI separately. The SDK extra is only needed when selecting an
|
|
SDK-backed Claude Code exec path.
|
|
|
|
=== "Qwen (Local)"
|
|
|
|
```bash
|
|
python -m pip install -e ".[qwen]"
|
|
```
|
|
|
|
=== "SearchQA data"
|
|
|
|
```bash
|
|
python -m pip install -e ".[searchqa]"
|
|
```
|
|
|
|
=== "WebUI"
|
|
|
|
```bash
|
|
python -m pip install -e ".[webui]"
|
|
```
|
|
|
|
=== "Development"
|
|
|
|
```bash
|
|
python -m pip install -e ".[dev]"
|
|
```
|
|
|
|
=== "All"
|
|
|
|
```bash
|
|
python -m pip install -e ".[alfworld,claude,qwen,searchqa,webui,docs,dev]"
|
|
```
|
|
|
|
## Environment Variables
|
|
|
|
From a source checkout, copy the template and fill in only the backend you
|
|
will use:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
SkillOpt does not automatically load `.env`; export it into the current shell
|
|
before running commands:
|
|
|
|
```bash
|
|
set -a
|
|
source .env
|
|
set +a
|
|
```
|
|
|
|
For Azure OpenAI with API-key authentication, the minimum settings are:
|
|
|
|
```ini
|
|
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
|
|
```
|
|
|
|
Use `AZURE_OPENAI_AUTH_MODE=azure_cli` for Azure CLI credentials, or
|
|
`managed_identity` with an optional
|
|
`AZURE_OPENAI_MANAGED_IDENTITY_CLIENT_ID`.
|
|
|
|
The research `claude_chat` backend is a Claude Code CLI adapter, not a direct
|
|
Anthropic API client. Install and authenticate `claude`, and set
|
|
`CLAUDE_CLI_BIN` only if the executable is not available as `claude` on
|
|
`PATH`. `ANTHROPIC_API_KEY` is one authentication option the CLI may consume.
|
|
|
|
OpenAI-compatible servers have three distinct entry points:
|
|
|
|
1. The research engine's generic `openai_compatible` backend uses
|
|
`OPENAI_COMPATIBLE_BASE_URL`, `OPENAI_COMPATIBLE_API_KEY`, and
|
|
`OPENAI_COMPATIBLE_MODEL`.
|
|
2. The research `openai_chat` backend can use
|
|
`AZURE_OPENAI_AUTH_MODE=openai_compatible` with
|
|
`AZURE_OPENAI_ENDPOINT` and `AZURE_OPENAI_API_KEY`.
|
|
3. SkillOpt-Sleep uses the same Azure-family variables as item 2 with
|
|
`skillopt-sleep run --backend azure_openai`.
|
|
|
|
For research train/eval commands, `model.optimizer` and `model.target` in the
|
|
YAML config are applied after backend initialization. They override model-name
|
|
environment variables such as `OPENAI_COMPATIBLE_MODEL` and
|
|
`QWEN_CHAT_MODEL`; set both role models explicitly when selecting those
|
|
backends.
|
|
|
|
!!! tip
|
|
You only need to configure the backend you plan to use. See
|
|
[Configuration](configuration.md#model-backends) for exact backend names
|
|
and role-specific overrides.
|
|
|
|
## Verify Installation
|
|
|
|
```bash
|
|
python -c "import skillopt; print('SkillOpt ready!')"
|
|
skillopt-train --help
|
|
skillopt-eval --help
|
|
skillopt-sleep --help
|
|
```
|
|
|
|
## Next Steps
|
|
|
|
→ [Run your first experiment](first-experiment.md)
|