Провайдеры и модели

SOBA работает с любым OpenAI-совместимым API. Этот гайд объясняет, как работать со встроенными провайдерами, выбирать модели, добавлять кастомные и диагностировать проблемы.

Ключевое изменение в v0.6.x: Модели больше не хранятся в жёстко закодированных списках — они обнаруживаются динамически через GET /v1/models. Это значит, что новые модели (DeepSeek-V3, Kimi K2, Qwen3 и т.д.) доступны сразу, без обновления SOBA.

1. Архитектура

Система провайдеров в SOBA использует registry (реестр), который объединяет:

• Встроенные провайдеры: 5 провайдеров с известными base URL и transport-профилями
• Кастомные провайдеры: любые OpenAI-совместимые API, добавленные пользователем
• Динамический discovery моделей: список моделей запрашивается у API провайдера при запуске (и кэшируется)

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

2. Встроенные провайдеры

SOBA v0.6.x поставляется с 5 встроенными провайдерами. Официальный OpenAI provider использует нативный Responses API, остальные — специализированные OpenAI-compatible transports.

2.1. Динамический discovery моделей

При запуске SOBA делает GET {baseUrl}/models для активного провайдера. Полученный список моделей кэшируется в памяти до перезапуска. При автоматическом выборе SOBA пропускает модели, которые явно объявляют нетекстовый output, а в остальном сохраняет порядок провайдера. Возможности не выводятся из слов chat, code или имени вендора в ID модели.

Discovery также читает лимиты контекста/вывода и структурированные reasoning capabilities, если provider их публикует. Приоритет effective limits: явные значения модели пользователя → runtime limit → лимит активного route → общий лимит модели → поддерживаемый профиль точной модели → консервативный fallback. Лимит router route может сузить более широкое context window модели. Fallback-значения помечаются как предполагаемые (~), а при выборе такой модели SOBA показывает предупреждение.

Кэш живёт только в памяти текущего процесса. Чтобы заново запросить каталог моделей, перезапустите SOBA или откройте селектор модели в TUI через F2 или /model.

3. Выбор модели

3.1. Просмотр доступных моделей

# В консоли
soba provider list

Вывод показывает всех провайдеров и их текущие модели, сгруппированные по провайдеру. Активная модель помечена звёздочкой.

3.2. Выбор модели

В TUI модель переключается через селектор F2 или /model. Селектор показывает провайдеры в левой колонке, а модели выбранного провайдера — в правой. Поиск фильтрует и провайдеры, и названия/ID моделей; в строках моделей показываются context window, max output, streaming и thinking бейджи, если эти данные известны. Ctrl+M остаётся best-effort legacy alias, но многие терминалы кодируют его как Enter.

Используйте ↑ / ↓ для перемещения по моделям, ← / → или Tab / Shift+Tab для смены провайдера и Enter для выбора. Открытие селектора обновляет discovery встроенных провайдеров, поэтому это самый быстрый способ подтянуть новые модели во время уже запущенной TUI-сессии.

Для одного запуска можно передать модель через top-level CLI-флаг или env:

# Через CLI на один запуск
soba --model deepseek-v4-flash "Проверь проект"

# Через env
export SOBA_MODEL="anthropic/claude-sonnet-4.6"

Команда soba provider use <id> переключает активного провайдера на его default model. Для кастомных провайдеров default model задаётся при добавлении (--default-model) или берётся из первого --model.

3.3. Управление reasoning

SOBA хранит provider-neutral запрошенную policy и вычисляет effective policy для активной модели. Нажмите F4, чтобы циклически переключать только те controls, которые реально объявляет модель, или используйте /reasoning для точного effort, toggle либо token budget. В sidebar показывается effective mode; при несовместимом выборе он отображает effective ← requested и сообщает причину fallback.

provider default означает, что reasoning-поле вообще не отправляется. SOBA не заменяет неподдерживаемый уровень ближайшим. Если live capabilities устарели и provider отклонил reasoning-параметр, запрос один раз повторяется без reasoning-полей, а fallback фиксируется.

3.4. Рекомендации по моделям

Это не вечный рейтинг, а рабочая шпаргалка на 21 июня 2026 года. Перед большой задачей всё равно загляните в soba provider list: провайдеры часто меняют алиасы, цены и лимиты.

4. Кастомные провайдеры

Любой OpenAI-совместимый API можно добавить как кастомного провайдера.

4.1. Добавление провайдера

# Ollama (локальный, без API-ключа)
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-совместимых моделей особые настройки не нужны. Если модели требуется другой wire-формат, задайте его в JSON для --from-file; SOBA никогда не включает такое поведение по имени провайдера или модели:

{
  "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"]
  }]
}

Поддерживаются adaptive_thinking, reasoning_split, reasoning_details_input, prefer_max_completion_tokens и single_system_message. Legacy boolean supportsThinking читается ещё один compatibility-релиз, но не описывает уровни и бюджеты; для новых definitions используйте структурированное поле reasoning. Dynamic 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 — его сериализацию. Неизвестный endpoint не получает reasoning-поля без подтверждённого профиля.

metadataProfile управляет только разбором model catalogue metadata. auto подходит большинству custom endpoints и использует endpoint probes для поддержанных локальных серверов; vllm, ollama, lmstudio и llamacpp выбирают их документированные metadata shapes. none отключает интерпретацию provider metadata. Это не связано с reasoning transport.

Используйте single_system_message для chat templates, которые принимают не более одного системного сообщения. На границе OpenAI wire-формата SOBA объединяет основные инструкции, инструкции активных skills, context capsules и compaction summaries в одно системное сообщение с индексом 0. Относительный порядок несистемных сообщений сохраняется. Флаг задаётся для каждой модели отдельно, поэтому модели одного endpoint могут иметь разные настройки совместимости.

4.4. Управление кастомными провайдерами

# Посмотреть определение провайдера
soba provider show ollama

# Сделать провайдера активным
soba provider use ollama

# Удалить кастомный провайдер
soba provider remove ollama

Команды update нет: чтобы изменить URL или список моделей, удалите кастомного провайдера и добавьте его заново.

4.5. Хранение

Кастомные провайдеры сохраняются в registry.customProviders внутри ~/.soba/config.json:

{
  "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

# Список провайдеров и моделей
soba provider list

# Выбрать активного провайдера (использует его default model)
soba provider use deepseek

# Добавить кастомный провайдер
soba provider add <id> --base-url <url> --model <spec> [--api-key-env <VAR>] [--name <name>]

# Удалить кастомный провайдер
soba provider remove <id>

# Показать определение провайдера
soba provider show <id>

Slash-команды в TUI

Управление провайдерами и моделями производится через CLI-команды soba provider (см. выше) или через флаг --model при запуске.

6. Аутентификация

6.1. Способы передачи API-ключа

Приоритет:

1. Сохранённый ключ провайдера в registry.providers.<providerId>.apiKey (создаётся first-time wizard для встроенных провайдеров)
2. Переменная окружения провайдера: DEEPSEEK_API_KEY, MOONSHOT_API_KEY, DASHSCOPE_API_KEY, OPENROUTER_API_KEY
3. Legacy flat-настройки SOBA_API_KEY / apiKey используются старым fallback-путём конфигурации; для registry-провайдеров предпочтительны provider-specific env-переменные или сохранённый ключ

6.2. Для кастомных провайдеров

При использовании --api-key-env MY_VAR SOBA будет читать ключ из process.env.MY_VAR. Если не указан --api-key-env, кастомный провайдер считается keyless — это удобно для локальных OpenAI-compatible серверов.

7. Диагностика

7.1. Проверка соединения

# Прямой запрос к API для проверки
curl -H "Authorization: Bearer $DEEPSEEK_API_KEY" https://api.deepseek.com/models

# Проверка через SOBA: вывести провайдеров и активную модель
soba provider list

7.2. Распространённые проблемы

7.3. Проверка кэша моделей

SOBA кэширует модели в памяти текущего процесса. При добавлении новой модели провайдером перезапустите SOBA или откройте селектор F2 / /model, чтобы заново выполнить discovery.

7.4. Смена провайдера при проблемах

Если один провайдер недоступен, легко переключиться на другой:

soba provider use openrouter
soba --model meta-llama/llama-3.3-70b-instruct "Продолжи задачу"