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

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

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

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

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

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

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

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

SOBA v0.4.0 поставляется с 4 встроенными провайдерами. Все они используют OpenAI-совместимый адаптер.

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

При запуске SOBA делает GET {baseUrl}/models для активного провайдера. Полученный список моделей кэшируется в памяти до перезапуска. Автоматически выбирается наиболее подходящая модель по умолчанию (предпочтение отдаётся код-ориентированным моделям).

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

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

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

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

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

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

В TUI модель переключается через селектор Ctrl+M. Для одного запуска можно передать модель через 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. Рекомендации по моделям

Это не вечный рейтинг, а рабочая шпаргалка на 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. Управление кастомными провайдерами

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

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

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

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

4.4. Хранение

Кастомные провайдеры сохраняются в 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 или откройте селектор Ctrl+M, чтобы заново выполнить discovery.

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

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

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