0.4.11
Поиск по документации… ⌘K
06 · Руководство пользователя

06. Модели и провайдеры

AstraCode работает с разными большими языковыми моделями (LLM) через провайдеров — это endpoint'ы (URL), куда AstraCode шлёт запросы. Один провайдер обычно даёт несколько моделей. Этот документ — как выбрать, добавить, переключиться.

Что такое модель и провайдер

  • Модель — конкретный «мозг», например gpt-5 или claude-sonnet-4-6 или llama-3.3-70b. Каждая модель имеет свои сильные стороны (быстрее / умнее / дешевле / большой контекст).
  • Провайдер — кто хостит модель и предоставляет API: OpenAI, Anthropic, локальный server, on-prem gateway.

Один провайдер = один API endpoint = свой API-ключ.

Команда /model

В TUI:

text
/model

Откроется трёхколонный picker:

text
┌─ Provider ────────┬─ Status ─────┬─ Models ──────────────┐
│ OpenAI            │ Online       │ gpt-5                 │
│                   │              │ gpt-5-mini            │
│                   │              │ gpt-4o                │
│                   │              │ o3-mini               │
│ Anthropic         │ Online       │ claude-sonnet-4-6     │
│                   │              │ claude-opus-4-8       │
│                   │              │ claude-haiku-4-5      │
│ Local AstraCode   │ Needs key    │ —                     │
│                   │              │                       │
│ + Add provider                                            │
└────────────────────────────────────────────────────────────┘
↑↓ navigate · Enter activate · r refresh · d delete · Esc cancel
  • Стрелки — навигация.
  • Enter — активировать выделенную модель.
  • r — обновить каталог моделей у провайдера.
  • d — удалить провайдера (и его API-ключ).
  • Esc — отмена.

Добавить нового провайдера

В picker'е стрелкой вниз доходите до + Add provider и Enter. Откроется форма из трёх шагов:

Шаг 1: Display name

Любое человекочитаемое имя — My Local LLM, Company GPT, Personal OpenAI. Только для UI, не должно быть уникальным.

Шаг 2: Base URL

Корневой URL API. Обязательно /v1-совместимый с OpenAI (Chat Completions). Примеры:

Провайдер Base URL
OpenAI https://api.openai.com/v1
Anthropic https://api.anthropic.com/v1
vLLM local http://localhost:8000/v1
Ollama http://localhost:11434/v1
Together AI https://api.together.xyz/v1
Groq https://api.groq.com/openai/v1
Локальный AstraCode-gateway http://172.16.20.83:8000/v1

URL валидируется при сохранении.

Chat Completions bridge (0.4.11+): если ваш провайдер отвечает в Chat Completions формате, но AstraCode внутри ходит в Responses API, в-процесс прокси responses-api-proxy --mode chat-completions сам транслирует запросы и ответы. Включается через конфиг провайдера; пользователь видит просто работающую модель. Это покрывает большинство кастомных OpenAI-совместимых endpoint'ов (vLLM, LiteLLM, Ollama).

Шаг 3: API key

Bearer-токен. Шифруется и хранится в ~/.astracode/secrets/local.age. Видим только вам.

Если провайдеру не нужен ключ (например, локальный llama.cpp) — введите любую строку, например dummy.

После добавления

Провайдер появится в picker'е. Выберите модель, Enter — активирована для последующих turn'ов.

Сменить модель / провайдера на лету

Просто /model → выбрать другую → Enter. Текущая сессия продолжится с новой модели; что было до — остаётся в истории.

Выбор сохраняется автоматически в [ui_state] файла ~/.astracode/config.toml. При следующем запуске AstraCode возьмёт ту же модель.

Удалить провайдера

В picker'е выделите провайдера, d. Удалится из конфига и сотрётся его API-ключ из secrets.

⚠️ Безвозвратно. Для провайдеров «выключения» нет — только удалить и добавить заново.

Редактирование провайдера

Прямо в UI — нельзя. Нужно: 1. d — удалить. 2. + Add provider — добавить с правильными данными.

Какую модель выбрать

Никакого «лучшего» ответа — зависит от задач, бюджета, доступности. Ориентиры:

Задача Рекомендация
Сложный рефакторинг, дизайн архитектуры Claude Sonnet 4.6 / GPT-5 / Opus 4.8
Быстрые правки, ответы на вопросы Claude Haiku 4.5 / GPT-5-mini
Code review Sonnet 4.6 (хороший баланс)
Reasoning-задачи (математика, доказательства) GPT-5 с reasoning_effort = high
Локально (без интернета, конфиденциально) Llama 3.3 70B / Qwen 3 / DeepSeek

Цена и скорость варьируются: смотрите на сайтах провайдеров.

Конфигурация в config.toml

Когда хотите менять много или скриптом — редактируйте ~/.astracode/config.toml напрямую:

toml
default_provider = "openai"
model = "gpt-5"
model_context_window = 200000
model_auto_compact_token_limit = 180000
model_reasoning_effort = "medium"   # none | low | medium | high

# Провайдер для /review (отдельно от основной модели)
review_model = "claude-sonnet-4-6"

[[providers]]
id = "openai"
display_name = "OpenAI"
base_url = "https://api.openai.com/v1"

[[providers]]
id = "anthropic"
display_name = "Anthropic"
base_url = "https://api.anthropic.com/v1"

[[providers]]
id = "company-llm"
display_name = "Company LLM Gateway"
base_url = "https://llm.company.internal/v1"

Изменения применяются при следующем запуске. Чтобы перезагрузить «на горячую» — /new.

Параметры модели

model_context_window

Размер контекста модели в токенах (например, 200000 для GPT-5, 200000 для Claude 4). AstraCode использует это, чтобы предупреждать о приближении к лимиту.

model_auto_compact_token_limit

Когда токены превысят этот порог, AstraCode сам предложит /compact. По умолчанию ~90% от model_context_window.

model_reasoning_effort

Для моделей с extended thinking (o1, o3, GPT-5 reasoning, Claude extended thinking): - none — без размышлений. - low — короткие. - medium — стандарт. - high — длинные (дольше, дороже, но точнее).

review_model

Отдельная модель для команды /review. Хорошая практика — взять более дешёвую/быструю чем основная.

personality

Если провайдер поддерживает custom personality / system prompt — задайте имя из ~/.astracode/personalities/ (если есть).

On-prem / self-hosted

Подробно — 02-installation.md. Кратко:

toml
[[providers]]
id = "company-llm"
display_name = "Company LLM"
base_url = "https://llm.company.internal/v1"
default_provider = "company-llm"

Если у gateway self-signed CA:

bash
export ASTRACODE_CA_CERTIFICATE=/etc/ssl/certs/company-ca.pem
astracode

API-ключи: где живут и безопасны ли

  • Все ключи зашифрованы библиотекой age (passphrase-режим); passphrase хранится в OS keyring.
  • Файл — ~/.astracode/secrets/local.age.
  • Без вашего OS-логина расшифровать нельзя.
  • В config.toml ключи никогда не пишутся — только идентификаторы провайдеров.

Подробнее — 13-safety.md.

Сколько денег я трачу

/status показывает текущий расход токенов в сессии. По провайдерам: - OpenAI — https://platform.openai.com/usage. - Anthropic — https://console.anthropic.com/dashboard.

Стоимость за 1k токенов меняется — смотрите в дашбордах. Грубо: - Haiku / mini-модели: $0.0001-0.001 за 1k токенов. - Sonnet / 4o: $0.003-0.015 за 1k токенов. - Opus / GPT-5: $0.015-0.075 за 1k токенов.

Длинная сессия с большим контекстом и многими tool-вызовами легко съест $1-5. Для тех, кто работает много — стоит выбирать дешёвые модели на рутину и дорогие на сложное.

Несколько профилей с разными провайдерами

Если хотите разные конфиги для рабочих и личных задач:

bash
# Рабочие — корпоративный gateway
ASTRACODE_HOME=~/.astracode-work astracode

# Личные — OpenAI
ASTRACODE_HOME=~/.astracode-personal astracode

Каждая директория — полностью изолирована: свои секреты, свои сессии, свой конфиг.

Прокси

Если выход в интернет через прокси:

toml
# ~/.astracode/config.toml
[network]
http_proxy = "http://proxy.company.com:3128"
https_proxy = "http://proxy.company.com:3128"
no_proxy = "localhost,127.0.0.1,*.internal"

Или через env: HTTP_PROXY, HTTPS_PROXY, NO_PROXY.

Если что-то не работает

См. 15-troubleshooting.md. Типовые:

  • Could not find suitable model provider — провайдер не настроен. /model → добавить.
  • 401 Unauthorized — API-ключ протух или неверный. /model → удалить и добавить заново.
  • Rate limit exceeded — провайдер ограничивает запросы. Подождать или сменить тариф.
  • Failed to decrypt secrets file — keyring разъехался с файлом. rm ~/.astracode/secrets/local.age (потеряете ключи) и заново.
ESC