Provider 与模型

SOBA 可以使用任何 OpenAI-compatible API。本页说明如何使用内置 providers、切换模型、添加自定义 providers，以及排查常见连接问题。

v0.6.x 的重要变化： 模型不再保存在硬编码列表里。SOBA 会通过 GET /v1/models 动态发现模型，所以 provider 新增模型后，通常不需要等待 SOBA 发版。

1. 架构

SOBA 使用 provider registry。它包含：

• 内置 providers：5 个带已知 base URL 和 transport profile 的 provider
• 自定义 providers：用户添加的任意 OpenAI-compatible API
• 动态模型发现：从 provider API 拉取模型列表，并缓存在内存中

┌──────────────────────────────────────────┐
│              Registry                    │
│                                          │
│  ┌────────────────┐  ┌────────────────┐ │
│  │ Built-in       │  │ Custom         │ │
│  │ Providers (5)  │  │ Providers (∞)  │ │
│  └────────────────┘  └────────────────┘ │
│                                          │
│  ┌────────────────────────────────────┐  │
│  │ Dynamic Model Discovery             │  │
│  │ GET /v1/models → in-memory cache    │  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

2. 内置 providers

SOBA v0.6.x 提供 5 个内置 providers。官方 OpenAI provider 使用原生 Responses API；其余 provider 使用各自的 OpenAI-compatible transport。

2.1. 动态发现

启动时，SOBA 会对 active provider 调用 GET {baseUrl}/models。结果缓存在当前进程内。自动选择默认模型时，SOBA 会跳过明确声明非文本输出的模型，其余情况保持 provider 返回的顺序。它不会根据模型 ID 中的 chat、code 或 vendor 名称推断能力。

如果 provider 提供相关信息，discovery 还会读取 context/output limits 和结构化 reasoning capabilities。Effective limits 的优先级是：用户显式模型值 → runtime limit → active route limit → model-wide limit → 维护的精确模型 profile → 保守 fallback。Router route limit 可以缩小模型的全局 context window。Fallback 值会用 ~ 标为推定值，选择这类模型时也会显示警告。

缓存只存在于内存中。要刷新它，请重启 SOBA，或在 TUI 里用 F2 或 /model 打开模型选择器。

3. 选择模型

3.1. 查看可用模型

soba provider list

输出会按 provider 分组展示 providers 和模型。当前 active model 会带星号。

3.2. 选择模型

在 TUI 中可以用 F2 或 /model 切换模型。选择器左侧显示 providers，右侧显示当前高亮 provider 的模型。搜索会同时过滤 provider 名称、模型名称和模型 ID；模型行会在可用时显示 context window、max output、streaming 和 thinking 标签。Ctrl+M 仍作为 best-effort 旧别名保留，但很多终端会把它编码成 Enter。

用 ↑ / ↓ 在模型间移动，用 ← / → 或 Tab / Shift+Tab 切换 provider，用 Enter 选择高亮模型。打开选择器也会刷新内置 providers 的 discovery，所以在 TUI session 运行中获取新发布模型时，这是最快的方式。

单次运行可以通过 CLI 或 env 传入模型：

# 单次 CLI 运行
soba --model deepseek-v4-flash "Check the project"

# 环境变量
export SOBA_MODEL="anthropic/claude-sonnet-4.6"

soba provider use <id> 会把 active provider 切到它的 default model。自定义 providers 可以用 --default-model 设置默认模型；未设置时使用第一个 --model。

3.3. Reasoning 控制

SOBA 保存 provider-neutral 的 requested policy，并为 active model 计算 effective policy。按 F4 只会循环模型实际声明支持的 controls；也可以使用 /reasoning 精确设置 effort、toggle 或 token budget。Sidebar 显示 effective mode；如果选择不兼容，会显示 effective ← requested 并报告 fallback 原因。

provider default 表示请求中不发送任何 reasoning field。SOBA 不会把不支持的 level 静默替换成最接近的 level。如果 live capabilities 已过期且 provider 拒绝 reasoning 参数，SOBA 只会在移除 reasoning fields 后安全重试一次，并记录 fallback。

3.4. 实用模型选择

这不是永久排行榜，只是截至 2026 年 6 月 21 日的实用参考。跑大任务前建议先看 soba provider list：模型别名、价格和限制都变得很快。

4. 自定义 providers

任何 OpenAI-compatible API 都可以添加成自定义 provider。

4.1. 添加 provider

# Ollama，本地且不需要 key
soba provider add ollama \
  --base-url http://localhost:11434/v1 \
  --model llama3.1="Llama 3.1",8192,2048

# 本地模型建议从较小限制开始：
# 8192 = contextWindow，2048 = maxOutput。
# 128000,8192 可能会明显压到笔记本内存。

# Groq
soba provider add groq \
  --base-url https://api.groq.com/openai/v1 \
  --api-key-env GROQ_API_KEY \
  --model llama-3.3-70b-versatile="Llama 3.3 70B",128000,8192

# Together AI
soba provider add together \
  --base-url https://api.together.xyz/v1 \
  --api-key-env TOGETHER_API_KEY \
  --model meta-llama/Llama-3.3-70B-Instruct-Turbo="Llama 3.3 70B",128000,8192

# 任意 self-hosted OpenAI-compatible API
soba provider add my-api \
  --base-url https://my-llm.company.com/v1 \
  --api-key-env MY_LLM_KEY \
  --model company-code-model="Company Code Model",128000,8192

4.2. soba provider add 参数

4.3. 模型兼容性元数据

大多数 OpenAI-compatible 模型不需要特殊设置。如果模型需要不同的 wire format，请在传给 --from-file 的 JSON 中显式声明；SOBA 不会根据 provider 或模型名称自动启用这些行为：

{
  "id": "my-api",
  "name": "My API",
  "baseUrl": "https://my-llm.company.com/v1",
  "apiKeyEnv": "MY_LLM_KEY",
  "adapter": "openai",
  "metadataProfile": "generic_openai",
  "reasoningTransport": "openai_chat",
  "defaultModel": "company-model",
  "models": [{
    "id": "company-model",
    "name": "Company Model",
    "contextWindow": 128000,
    "maxOutput": 8192,
    "supportsStreaming": true,
    "reasoning": {
      "control": "effort",
      "supportedEfforts": ["low", "medium", "high"]
    },
    "compatibility": ["single_system_message"]
  }]
}

支持的 compatibility features 是 adaptive_thinking、reasoning_split、reasoning_details_input、prefer_max_completion_tokens 和 single_system_message。Legacy boolean supportsThinking 会再读取一个 compatibility release，但它无法描述 level 或 budget；新的 definitions 应使用结构化 reasoning。动态 discovery 也会读取 upstream 的 soba_compatibility 或 compatibility 列表，并忽略未知值。

Reasoning control 可以是 none、effort、budget、toggle 或 fixed。Transport 也必须显式声明为 openai_chat、openai_responses、openrouter、deepseek、kimi、minimax、qwen、ollama 或 none。Capability declaration 决定用户可以选择什么，transport 决定如何序列化。除非 profile 已确认，未知 endpoint 不会收到 reasoning fields。

metadataProfile 只控制 model catalogue metadata 的解释方式。auto 适用于大多数 custom endpoints，并会对受支持的本地服务器执行 endpoint probes；vllm、ollama、lmstudio 和 llamacpp 使用各自文档化的 metadata shape。none 会关闭 provider metadata 解释。这与 reasoning transport 相互独立。

对于最多只接受一条 system message 的 chat template，请使用 single_system_message。在 OpenAI wire-format 边界，SOBA 会把 core instructions、已启用 skill 的 instructions、context capsules 和 compaction summaries 合并为位于索引 0 的一条 system message。非 system messages 的相对顺序保持不变。该 feature 按模型配置，因此同一 endpoint 暴露的不同模型可以使用不同的兼容性设置。

4.4. 管理自定义 providers

# 查看 provider 定义
soba provider show ollama

# 设为 active provider
soba provider use ollama

# 删除自定义 provider
soba provider remove ollama

目前没有 update 命令。要修改 URL 或模型列表，请先删除自定义 provider，再重新添加。

4.5. 存储位置

自定义 providers 保存在 ~/.soba/config.json 的 registry.customProviders 中：

{
  "registry": {
    "activeProvider": "deepseek",
    "activeModelId": "deepseek-v4-flash",
    "customProviders": [
      {
        "id": "ollama",
        "name": "Ollama (Local)",
        "baseUrl": "http://localhost:11434/v1",
        "apiKeyEnv": "OLLAMA_API_KEY",
        "adapter": "openai"
      }
    ]
  }
}

5. CLI 管理

完整的 soba provider 命令：

# 帮助
soba provider help

# 列出 providers 和模型
soba provider list

# 选择 active provider 以及它的 default model
soba provider use deepseek

# 添加自定义 provider
soba provider add <id> --base-url <url> --model <spec> [--api-key-env <VAR>] [--name <name>]

# 删除自定义 provider
soba provider remove <id>

# 查看 provider 定义
soba provider show <id>

Provider 和模型管理目前主要通过 CLI 命令和 TUI 模型选择器完成。

6. 认证

6.1. API key 来源

优先级：

1. 已保存的 provider key：registry.providers.<providerId>.apiKey，通常由首次启动 wizard 为内置 providers 创建
2. Provider-specific 环境变量：DEEPSEEK_API_KEY、MOONSHOT_API_KEY、DASHSCOPE_API_KEY、OPENROUTER_API_KEY
3. Legacy flat config：SOBA_API_KEY 或 apiKey，作为 fallback 保留

对于 registry providers，更推荐 provider-specific env vars 或已保存的 provider key。

6.2. 自定义 providers

使用 --api-key-env MY_VAR 时，SOBA 会从 process.env.MY_VAR 读取 key。如果省略 --api-key-env，provider 会被认为不需要 key，这对本地 OpenAI-compatible server 很方便。

7. 诊断

7.1. 检查连接

# 直接检查 API
curl -H "Authorization: Bearer $DEEPSEEK_API_KEY" https://api.deepseek.com/models

# 通过 SOBA 检查
soba provider list

7.2. 常见问题

7.3. 刷新模型缓存

模型缓存在当前进程内。如果 provider 新增了模型，请重启 SOBA，或打开 F2 / /model 选择器重新 discovery。

7.4. 遇到问题时切换 provider

soba provider use openrouter
soba --model meta-llama/llama-3.3-70b-instruct "Continue the task"