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

Способ подключения моделей зависит от сборки Астра ИИ [КОД]. Определить её можно по astracode --version:

Перед выбором модели

Этот раздел и два следующих («Выбрать основную модель», «Модели сабагентов») относятся к managed-сборке.

Нужна активная корпоративная сессия. Проверить её можно командой:

astracode login status

Если вход не выполнен:

astracode login

Подробнее — Доступ через AstraHub.

Выбрать основную модель

В TUI выполните:

/model

Откроется список моделей, разрешённых организацией для основного агента. Стрелки перемещают курсор, Enter активирует модель, Esc закрывает окно без изменения.

Выбор применяется к следующим ходам текущей сессии и сохраняется между запусками. История разговора при переключении модели остаётся.

Если организация изменила модельную политику, новый список применяется автоматически. Уже выполняющийся ход завершается с прежними настройками.

Модели сабагентов

Команда:

/submodel

показывает отдельный пул моделей для сабагентов. Он может отличаться от списка в /model: модель основного агента не обязательно доступна сабагентам и наоборот.

Роли сабагентов:

• worker — реализация и выполнение ограниченных задач;
• explorer — исследование кодовой базы;
• пользовательские роли, созданные через /subagent.

Назначения и ограничения определяются политикой AstraHub. Если роль не имеет отдельной модели, Астра ИИ [КОД] использует разрешённое наследование или модель по умолчанию из пула сабагентов.

Свои провайдеры и API-ключи

Раздел относится к сборкам, в версии которых нет суффикса -managed.

Провайдер — это адрес API (Base URL) и, если нужно, ключ доступа к нему. У одного провайдера обычно есть несколько моделей. Астра ИИ [КОД] обращается к провайдеру по протоколу Chat Completions (<Base URL>/chat/completions), а список моделей запрашивает по адресу <Base URL>/models. Поэтому подходят локальные серверы моделей, облачные API и корпоративные шлюзы с таким интерфейсом. Особенности передачи reasoning для таких провайдеров описаны в разделе «Reasoning effort» ниже.

Первый запуск

Если провайдеров ещё нет, после выбора доверенной директории появится экран «Настройте первого провайдера». В нём те же три поля, что и в форме добавления (см. ниже). Пока провайдер не настроен, чат недоступен.

Окно /model

Провайдер     Статус          Модели
DeepSeek      Доступен (2)    deepseek-chat
                              deepseek-reasoner
Локальный     Доступен (1)    qwen3-coder
Qwen          Нужен ключ      -
Dev-сервер    Недоступен      -

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

↑↓ навигация · Enter выбрать · r обновить · e изменить · d удалить · Esc отменить

Модель выбирается на её строке: стрелки перемещают курсор, Enter активирует пару «провайдер + модель». У провайдера не в статусе «Доступен» выбрать нечего — вместо моделей стоит прочерк.

Клавиши r, e и d относятся к провайдеру, на строке которого стоит курсор.

Выбор применяется сразу, без перезапуска, и запоминается между запусками: Астра ИИ [КОД] записывает его в раздел [ui_state] файла ~/.astracode/config.toml. История разговора при переключении остаётся.

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

Выберите строку «+ Добавить провайдера» и нажмите Enter. Откроется форма из трёх полей:

Tab и Shift+Tab переключают поля, Enter переходит к следующему полю, а на последнем сохраняет провайдера, Esc отменяет. Если название или Base URL пустые либо Base URL не является корректным URL, форма покажет ошибку и ничего не сохранит.

Примеры Base URL:

API-ключ хранится в зашифрованном хранилище ~/.astracode/secrets/local.age и не записывается в config.toml. При вводе символы скрыты.

После сохранения Астра ИИ [КОД] сообщает «Провайдер … добавлен; проверяю /v1/models…» и проверяет провайдера. Когда статус станет «Доступен», выберите модель.

Изменить, обновить и удалить провайдера

• e открывает форму с текущими названием и Base URL. Поле ключа пустое: если оставить его пустым, прежний ключ сохранится, а чтобы заменить ключ, введите новый. После сохранения провайдер проверяется заново.
• r повторяет проверку, например после того, как вы запустили локальный сервер.
• d удаляет запись и сохранённый ключ. Это необратимо. Роли сабагентов, которые ссылались на этого провайдера, возвращаются к модели основного агента. Если удалён активный провайдер, выбор модели сбрасывается и /model открывается снова.

Модели сабагентов в такой сборке

/submodel показывает тот же список с колонкой ролей. На выделенной модели:

• w назначает её роли worker;
• e назначает роли explorer;
• c назначает общую модель для ваших ролей, созданных через /subagent.

Назначенные роли отмечены у модели метками [w], [e], [c]. Роль без назначения использует модель основного агента. Назначения сохраняются в [ui_state.role_models]. Добавлять и удалять провайдеров в /submodel нельзя, только в /model.

Настройка через config.toml

Провайдеров можно описать и вручную в ~/.astracode/config.toml:

default_provider = "deepseek"

[[providers]]
id = "deepseek"
display_name = "DeepSeek"
base_url = "https://api.deepseek.com/v1"

[[providers]]
id = "local"
display_name = "Локальный сервер"
base_url = "http://localhost:8000/v1"

Что важно учесть:

• default_provider используется, если нет сохранённого выбора из /model.
• API-ключ в config.toml не пишется: его вводят только в форме добавления или изменения провайдера.
• Раздел [ui_state] Астра ИИ [КОД] ведёт автоматически, править его вручную не нужно.
• Правки вступают в силу при следующем запуске Астра ИИ [КОД]. Если запись некорректна (пустой или повторяющийся id, неверный base_url), конфигурация не загрузится, а сообщение укажет на запись.
• Старые разделы [model_providers] и [profiles] не поддерживаются: при их наличии конфигурация не загрузится. Перенесите записи в [[providers]].

Свои провайдеры вместе со входом в AstraHub

В некоторых сборках можно и войти в AstraHub (экспериментальная возможность, astracode login), и сохранить собственных провайдеров. После входа в /model появляется строка AstraHub с пометкой «Управляемый провайдер: модель можно выбирать; изменение/удаление запрещены». Ваши провайдеры остаются в списке. После /logout Астра ИИ [КОД] возвращает провайдера и модель, которые были выбраны до входа.

Посмотреть текущую модель

Выполните:

/status

Статус показывает активную модель, reasoning effort, использование контекста и текущие ограничения песочницы.

Модель также можно вывести в нижней строке через /statusline или в заголовке терминала через /title.

Reasoning effort

Reasoning effort определяет, сколько вычислений модель тратит на обдумывание ответа. В конфигурации допустимы шесть значений:

• none — без дополнительного reasoning;
• minimal — минимальный;
• low — короткий;
• medium — стандартный;
• high — более глубокий;
• xhigh — максимальный.

Какие из них модель действительно поддерживает, зависит от самой модели и её сервера. Астра ИИ [КОД] не проверяет и не подбирает значение автоматически, а отправляет то, что указано.

Как задать

В меню /model уровня нет: там выбираются только провайдер и модель. Значение задаётся в ~/.astracode/config.toml:

model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

Когда значение не доходит до модели

Астра ИИ [КОД] обращается к моделям по Responses API. Если провайдер понимает только Chat Completions, запрос идёт через встроенный мост, и мост не передаёт поле reasoning. В этом случае model_reasoning_effort отображается в статусе, но на работу модели не влияет. Если бэкенд принимает такой параметр в теле запроса, его можно передать через extra_body провайдера в config.toml:

[[providers]]
id = "local"
base_url = "http://localhost:8000/v1"
extra_body = { reasoning_effort = "high" }

Название параметра и допустимые значения определяет бэкенд.

Размер контекста и compact

/status показывает, сколько контекста занято в текущей сессии. Когда история становится большой:

/compact

Команда сжимает старую часть разговора, сохраняя рабочую сводку. Для несвязанной задачи лучше открыть новый тред через /new.

Автоматический порог можно настроить:

model_context_window = 200000
model_auto_compact_token_limit = 120000

Не задавайте размер контекста выше фактического лимита модели, опубликованного организацией.

Модель для ревью кода

/review использует review_model, если эта настройка задана и модель разрешена политикой AstraHub. Иначе используется активная модель.

review_model = "имя-модели-из-доступного-пула"

Если модель для ревью больше недоступна, удалите review_model из конфига и выберите актуальную модель через /model.

Типовые проблемы

«Требуется вход в AstraHub»

astracode login status
astracode login

Если сессия повреждена или относится к другому аккаунту:

astracode logout
astracode login

Нужной модели нет в /model

В managed-сборке список управляется организацией. Закройте и снова откройте список, а если модель по-прежнему отсутствует — обратитесь к администратору AstraHub.

Модель доступна в /model, но отсутствует в /submodel

Это ожидаемо: основной агент и сабагенты используют разные пулы.

429 Rate limit exceeded

Подождите и повторите запрос позже. Можно уменьшить model_reasoning_effort или выбрать другую доступную модель. Если ошибка повторяется, передайте администратору время ошибки и фрагмент лога без содержимого вашего кода.

Модель отвечает медленно

• снизьте reasoning effort;
• выполните /compact для длинной сессии;
• выберите другую модель из /model, если она доступна;
• проверьте корпоративную сеть или VPN.

После /logout работа остановилась

Для managed-сборки это штатно: без активной AstraHub-сессии запросы к моделям заблокированы. Выполните /login или astracode login.

Провайдер в статусе «Нужен ключ»

Сервер отклонил авторизацию. В /model выделите провайдера, нажмите e, введите актуальный ключ и сохраните.

Провайдер в статусе «Недоступен»

Причина показана под статусом. Проверьте, что сервер запущен, Base URL указан верно (обычно он оканчивается на /v1), а сеть или VPN доступны, затем нажмите r. Тот же статус появится, если сервер ответил, но не вернул ни одной модели для чата.