Создание плагина провайдера моделей

Плагины провайдеров моделей объявляют бэкенд инференса — OpenAI-совместимую конечную точку, сервер Anthropic Messages, Responses API в стиле Codex или нативный интерфейс Bedrock, — через который VibeOS может маршрутизировать вызовы AIAgent. Каждый встроенный провайдер (OpenRouter, Anthropic, GMI, DeepSeek, Nvidia и другие) поставляется как один из таких плагинов. Сторонние разработчики могут добавить свой собственный, просто поместив каталог в $VIBEOS_HOME/plugins/model-providers/ без каких-либо изменений в репозитории.

подсказка

Плагины провайдеров моделей — это третий вид провайдерских плагинов. Другие — это Плагины провайдеров памяти (межсессионные знания) и Плагины контекстных движков (стратегии сжатия контекста). Все три следуют одному и тому же шаблону: «помести каталог, объяви профиль, никаких правок в репозитории».

Как работает обнаружение

providers/__init__.py._discover_providers() выполняется лениво при первом вызове get_provider_profile() или list_providers(). Порядок обнаружения:

Встроенные плагины — <repo>/plugins/model-providers/<name>/ — поставляются с VibeOS
Пользовательские плагины — $VIBEOS_HOME/plugins/model-providers/<name>/ — поместите любой каталог; перезапуск для последующих сессий не требуется
Устаревшие однофайловые — <repo>/providers/<name>.py — обратная совместимость для внешних редактируемых установок

Пользовательские плагины переопределяют встроенные плагины с тем же именем, поскольку register_provider() работает по принципу «последний записавший побеждает». Поместите каталог $VIBEOS_HOME/plugins/model-providers/gmi/, чтобы заменить встроенный профиль GMI, не трогая репозиторий.

Структура каталога

plugins/model-providers/my-provider/
├── __init__.py       # Вызывает register_provider(profile) на уровне модуля
├── plugin.yaml       # kind: model-provider + метаданные (опционально, но рекомендуется)
└── README.md         # Инструкции по настройке (опционально)

Единственный обязательный файл — __init__.py. plugin.yaml используется командой vibeos plugins для интроспекции и общим PluginManager для маршрутизации плагина к соответствующему загрузчику; без него общий загрузчик прибегает к эвристике на основе исходного текста.

Минимальный пример — простой провайдер с API-ключом

# plugins/model-providers/acme-inference/__init__.py
from providers import register_provider
from providers.base import ProviderProfile

acme = ProviderProfile(
    name="acme-inference",
    aliases=("acme",),
    display_name="Acme Inference",
    description="Acme — OpenAI-совместимый прямой API",
    signup_url="https://acme.example.com/keys",
    env_vars=("ACME_API_KEY", "ACME_BASE_URL"),
    base_url="https://api.acme.example.com/v1",
    auth_type="api_key",
    default_aux_model="acme-small-fast",
    fallback_models=(
        "acme-large-v3",
        "acme-medium-v3",
        "acme-small-fast",
    ),
)

register_provider(acme)

# plugins/model-providers/acme-inference/plugin.yaml
name: acme-inference
kind: model-provider
version: 1.0.0
description: Acme Inference — OpenAI-совместимый прямой API
author: Ваше Имя

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

Интеграция	Где	Что получает
Разрешение учетных данных	`vibeos_cli/auth.py`	`PROVIDER_REGISTRY["acme-inference"]` заполняется из профиля
Флаг CLI `--provider`	`vibeos_cli/main.py`	Принимает `acme-inference`
Выбор `vibeos model`	`vibeos_cli/models.py`	Появляется в `CANONICAL_PROVIDERS`, список моделей загружается из `{base_url}/models`
`vibeos doctor`	`vibeos_cli/doctor.py`	Проверка работоспособности для `ACME_API_KEY` + пробный запрос к `{base_url}/models`
`vibeos setup`	`vibeos_cli/config.py`	`ACME_API_KEY` появляется в `OPTIONAL_ENV_VARS` и в мастере настройки
Обратное сопоставление URL	`agent/model_metadata.py`	Имя хоста → имя провайдера для автоопределения
Вспомогательная модель	`agent/auxiliary_client.py`	Использует `default_aux_model` для сжатия / суммаризации
Разрешение во время выполнения	`vibeos_cli/runtime_provider.py`	Возвращает правильные `base_url`, `api_key`, `api_mode`
Транспорт	`agent/transports/chat_completions.py`	Путь профиля генерирует kwargs через `prepare_messages` / `build_extra_body` / `build_api_kwargs_extras`

Поля ProviderProfile

Полное определение в providers/base.py. Наиболее полезные:

Поле	Тип	Назначение
`name`	str	Канонический идентификатор — соответствует `model.provider` в `config.yaml` и флагу `--provider`
`aliases`	`tuple[str, ...]`	Альтернативные имена, разрешаемые `get_provider_profile()` (например, `grok` → `xai`)
`api_mode`	str	`chat_completions` \| `codex_responses` \| `anthropic_messages` \| `bedrock_converse`
`display_name`	str	Человекочитаемая метка, отображаемая в выборе `vibeos model`
`description`	str	Подзаголовок в выборе
`signup_url`	str	Показывается при первой настройке («получить API-ключ здесь»)
`env_vars`	`tuple[str, ...]`	Переменные окружения для API-ключа в порядке приоритета; последняя запись `*_BASE_URL` используется как пользовательское переопределение базового URL
`base_url`	str	Конечная точка инференса по умолчанию
`models_url`	str	Явный URL каталога моделей (по умолчанию `{base_url}/models`)
`auth_type`	str	`api_key` \| `oauth_device_code` \| `oauth_external` \| `copilot` \| `aws_sdk` \| `external_process`
`fallback_models`	`tuple[str, ...]`	Подобранный список, показываемый, когда загрузка живого каталога не удалась
`default_headers`	`dict[str, str]`	Отправляется с каждым запросом (например, `Editor-Version` от Copilot)
`fixed_temperature`	Any	`None` = использовать значение вызывающего; sentinel `OMIT_TEMPERATURE` = не отправлять temperature вообще (Kimi)
`default_max_tokens`	`int \| None`	Ограничение max_tokens на уровне провайдера (Nvidia: 16384)
`default_aux_model`	str	Дешёвая модель для вспомогательных задач (сжатие, зрение, суммаризация)

Переопределяемые хуки

Создайте подкласс ProviderProfile для нетривиальных особенностей:

from typing import Any
from providers.base import ProviderProfile

class AcmeProfile(ProviderProfile):
    def prepare_messages(self, messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
        """Специфичная для провайдера предобработка сообщений. Выполняется после
        санитизации codex, перед заменой роли developer. По умолчанию: сквозная передача."""
        # Пример: Qwen нормализует текстовое содержимое в массив частей
        # и внедряет cache_control; Kimi переписывает JSON вызовов инструментов
        return messages

    def build_extra_body(self, *, session_id=None, **context) -> dict:
        """Специфичные для провайдера поля extra_body, объединяемые с вызовом API.
        Контекст включает: session_id, provider_preferences, model, base_url,
        reasoning_config. По умолчанию: пустой словарь."""
        # Пример: блок provider-preferences OpenRouter,
        # трансляция thinking_config Gemini.
        return {}

    def build_api_kwargs_extras(self, *, reasoning_config=None, **context):
        """Возвращает (extra_body_additions, top_level_kwargs). Нужно, когда некоторые
        поля идут на верхний уровень (reasoning_effort у Kimi, verbosity у OpenRouter для
        адаптивных моделей Anthropic), а некоторые — в extra_body (словарь reasoning
        у OpenRouter). По умолчанию: ({}, {})."""
        return {}, {}

    def fetch_models(self, *, api_key=None, timeout=8.0) -> list[str] | None:
        """Загрузка живого каталога. По умолчанию обращается к {models_url или base_url}/models
        с Bearer-аутентификацией. Переопределите для: кастомной аутентификации (Anthropic),
        отсутствия REST-эндпоинта (Bedrock → None) или публичных/неаутентифицированных
        каталогов (OpenRouter)."""
        return super().fetch_models(api_key=api_key, timeout=timeout)

Примеры использования хуков

Посмотрите на эти встроенные плагины для идиом:

Плагин	Почему стоит посмотреть
`plugins/model-providers/openrouter/`	Агрегатор с предпочтениями провайдеров, публичный каталог моделей
`plugins/model-providers/gemini/`	Трансляция `thinking_config` (нативные и OpenAI-совместимые вложенные формы)
`plugins/model-providers/kimi-coding/`	`OMIT_TEMPERATURE`, `extra_body.thinking`, `reasoning_effort` на верхнем уровне
`plugins/model-providers/qwen-oauth/`	Нормализация сообщений, внедрение `cache_control`, VL высокое разрешение
`plugins/model-providers/nous/`	Теги атрибуции, «опустить reasoning, когда отключено»
`plugins/model-providers/custom/`	Особенности Ollama: `num_ctx` + `think: false`
`plugins/model-providers/bedrock/`	`api_mode="bedrock_converse"`, `fetch_models` возвращает None (нет REST-эндпоинта)

Пользовательские переопределения — замена встроенного без правки репозитория

Допустим, вы хотите направить gmi на ваш частный staging-эндпоинт для тестирования. Создайте ~/.vibeos/plugins/model-providers/gmi/__init__.py:

from providers import register_provider
from providers.base import ProviderProfile

register_provider(ProviderProfile(
    name="gmi",
    aliases=("gmi-cloud", "gmicloud"),
    env_vars=("GMI_API_KEY",),
    base_url="https://gmi-staging.internal.example.com/v1",
    auth_type="api_key",
    default_aux_model="google/gemini-3.1-flash-lite-preview",
))

В следующей сессии get_provider_profile("gmi").base_url вернёт staging URL. Никаких патчей репозитория, никакой пересборки. Поскольку пользовательские плагины обнаруживаются после встроенных, вызов register_provider() пользователя побеждает.

Выбор api_mode

Распознаются четыре значения. VibeOS выбирает одно на основе:

Явного переопределения пользователем (config.yaml model.api_mode, если задано)
Диспетчеризации по модели OpenCode (opencode_model_api_mode для Zen и Go)
Автоопределения URL — суффикс /anthropic → anthropic_messages, api.openai.com → codex_responses, api.x.ai → codex_responses, /coding на доменах Kimi → chat_completions
api_mode профиля как запасной вариант, когда определение по URL ничего не находит
По умолчанию chat_completions

Установите profile.api_mode в соответствии с тем, что по умолчанию поставляет ваш провайдер — это действует как подсказка. Пользовательские переопределения URL всё равно имеют приоритет.

Типы аутентификации

`auth_type`	Значение	Кто использует
`api_key`	Одна переменная окружения содержит статический API-ключ	Большинство провайдеров
`oauth_device_code`	Поток OAuth с кодом устройства	—
`oauth_external`	Пользователь входит в систему в другом месте, токены попадают в `auth.json`	Anthropic OAuth, MiniMax OAuth, Qwen Portal, Nous Portal
`copilot`	Цикл обновления токена GitHub Copilot	Только плагин `copilot`
`aws_sdk`	Цепочка учётных данных AWS SDK (роль IAM, профиль, окружение)	Только плагин `bedrock`
`external_process`	Аутентификация обрабатывается дочерним процессом, который запускает агент	Только плагин `copilot-acp`

auth_type определяет, какие пути кода обрабатывают вашего провайдера как «простого провайдера с API-ключом» — если это не api_key, PluginManager всё равно записывает манифест, но автоматизация на уровне CLI VibeOS (проверки doctor, флаг --provider, делегирование мастеру настройки) может его пропустить.

Время обнаружения

Обнаружение провайдеров ленивое — запускается при первом вызове get_provider_profile() или list_providers() в процессе. На практике это происходит рано при запуске (загрузка модуля auth.py расширяет PROVIDER_REGISTRY с нетерпением). Если вам нужно проверить, загрузился ли ваш плагин, выполните:

vibeos doctor

— успешный профиль с auth_type="api_key" появится в разделе «Подключение провайдеров» с пробным запросом к /models.

Для программной проверки:

from providers import list_providers
for p in list_providers():
    print(p.name, p.base_url, p.api_mode)

Тестирование вашего плагина

Укажите VIBEOS_HOME на временный каталог, чтобы не загрязнять вашу реальную конфигурацию:

export VIBEOS_HOME=/tmp/vibeos-plugin-test
mkdir -p $VIBEOS_HOME/plugins/model-providers/my-provider
cat > $VIBEOS_HOME/plugins/model-providers/my-provider/__init__.py <<'EOF'
from providers import register_provider
from providers.base import ProviderProfile
register_provider(ProviderProfile(
    name="my-provider",
    env_vars=("MY_API_KEY",),
    base_url="https://api.my-provider.example.com/v1",
    auth_type="api_key",
))
EOF

export MY_API_KEY=your-test-key
vibeos -z "hello" --provider my-provider -m some-model

Интеграция с общим PluginManager

Общий PluginManager (то, с чем работает vibeos plugins) видит плагины провайдеров моделей, но не импортирует их — providers/__init__.py управляет их жизненным циклом. Менеджер записывает манифест для интроспекции и категоризирует по kind: model-provider. Когда вы помещаете немаркированный пользовательский плагин в $VIBEOS_HOME/plugins/, который вызывает register_provider с ProviderProfile, менеджер автоматически приводит его к kind: model-provider с помощью эвристики на основе исходного текста — поэтому плагин всё равно маршрутизируется правильно, даже без plugin.yaml.

Распространение через pip

Как и любой плагин VibeOS, провайдеры моделей могут распространяться как pip-пакет. Добавьте точку входа в ваш pyproject.toml:

[project.entry-points."vibeos_agent.plugins"]
acme-inference = "acme_vibeos_plugin:register"

…где acme_vibeos_plugin:register — это функция, которая вызывает register_provider(profile). Общий PluginManager подхватывает плагины точек входа во время discover_and_load(). Для pip-плагинов с kind: model-provider вам всё равно нужно объявить вид в манифесте (или положиться на эвристику исходного текста).

См. Создание плагина VibeOS для полной настройки точек входа.

Связанные страницы

Среда выполнения провайдера — приоритет разрешения + где каждый слой читает профиль
Добавление провайдеров — сквозной контрольный список для новых бэкендов инференса (охватывает как быстрый путь плагина, так и полную интеграцию CLI/аутентификации)
Плагины провайдеров памяти
Плагины контекстных движков
Создание плагина VibeOS — общее руководство по созданию плагинов

Как работает обнаружение​

Структура каталога​

Минимальный пример — простой провайдер с API-ключом​

Поля ProviderProfile​

Переопределяемые хуки​

Примеры использования хуков​

Пользовательские переопределения — замена встроенного без правки репозитория​

Выбор api_mode​

Типы аутентификации​

Время обнаружения​

Тестирование вашего плагина​

Интеграция с общим PluginManager​

Распространение через pip​

Связанные страницы​