Документация: подключение провайдеров и моделей

Всё подключается через админку: сначала добавляете ключ провайдера, затем добавляете модели. Ключи шифруются и хранятся в базе данных (не в .env).

Полная инструкция интеграции (один файл)

Для интеграции MarkBase и подключения любых сайтов через безопасный виджет (без x-project-key в браузере) используйте единый документ:

Открыть “Полная интеграция с AI Server”

Если вы только что “пересобрали проект”

После миграций в базе появятся базовые сущности (в т.ч. openrouter/auto и native-ai), а также тарифы.
Чтобы подтянуть все модели OpenRouter, добавьте ключ openrouter и нажмите кнопку Синхронизировать OpenRouter в Админка → Модели.
Если в чате нет моделей — это почти всегда значит: нет активного ключа провайдера или модели выключены.
Самый быстрый путь: откройте Админка → Мастер настройки и пройдите шаги (ключ → sync → включить модели → проверить чат).
Чтобы ассистент сразу отвечал на типовые вопросы: откройте Админка → База ответов и отредактируйте стартовые ответы/шаблоны под ваш проект. Эти ответы срабатывают раньше самообучения.

Интеграция с другими сайтами (через ключ проекта)

Ключ проекта (Project API key вида sk_live_...) передаётся в AI waygpt как заголовок x-project-key. Ключ никогда не должен попадать в браузер — он хранится только на сервере (Markbase/BFF).

Чтобы “привязать ключ к домену”, откройте Кабинет → API‑ключи → Настройки проекта и заполните список доменов. Тогда AI waygpt будет требовать заголовок X-Site-Domain и принимать запросы только из указанных доменов.

Для прод‑защиты можно включить HMAC‑подпись (там же в настройках проекта): AI waygpt начнёт требовать заголовки X-MB-Timestamp, X-MB-Nonce, X-MB-Signature. Секрет генерируется в кабинете и хранится только в секретах Markbase/BFF.

Пример запроса (server‑to‑server): x-project-key + X-Site-Domain + JSON body в /api/v1/waygpt/chat/completions.

Готовый “мастер” с примерами кода: Кабинет → Интеграция.

1) Добавить ключ провайдера

Откройте Админка → Модели и нажмите Настроить ключ.
Укажите:
- provider: строковый “slug” провайдера, например openai, openrouter, groq, ollama, anthropic, yandex.
- api key: ключ провайдера.
- auth header и prefix: как провайдер ожидает авторизацию (обычно Authorization + Bearer).

Быстрые пресеты (рекомендации)

provider	Тип интеграции	API Base (пример)	Auth (пример)
`openai`	OpenAI‑compatible	пусто (дефолт) или `https://api.openai.com/v1`	`Authorization: Bearer ...`
`openrouter`	OpenAI‑compatible	`https://openrouter.ai/api/v1`	`Authorization: Bearer ...`
`groq`	OpenAI‑compatible	`https://api.groq.com/openai/v1`	`Authorization: Bearer ...`
`ollama`	OpenAI‑compatible (локально)	`http://localhost:11434/v1` (или адрес сервиса)	обычно не требуется (но можно `Bearer`)
`anthropic`	Native adapter	пусто (дефолт)	`x-api-key: ...`
`yandex`	Native adapter	пусто (дефолт)	`Authorization: Api-Key ...`

OpenRouter: зачем он нужен и будет ли дороже?

OpenRouter — это агрегатор моделей: один API‑ключ и один OpenAI‑совместимый endpoint, через который вы получаете доступ к сотням моделей (вендоры, open‑source, разные семейства).

По цене: иногда через OpenRouter может быть чуть дороже, чем “напрямую” у конкретного провайдера (зависит от модели/маршрута). Зато вы экономите время и сложность интеграции.

Рекомендованная схема для продакшена: держать 1–2 “базовых” провайдера напрямую (например OpenAI/Gemini), а “длинный хвост” моделей подключать через OpenRouter.

Как проверить стоимость: откройте страницу Models и смотрите цену/контекст/возможности у конкретной модели: openrouter.ai/models.

Как подключить OpenRouter (пошагово)

Добавьте ключ:
Админка → Модели → Настроить ключ → provider: openrouter → auth: Authorization + Bearer.
Нажмите синхронизацию каталога:
Админка → Модели → Синхронизировать OpenRouter. Вы увидите, сколько моделей создано/обновлено.
(Опционально) Добавьте extra headers для рейтингов:
{ "HTTP-Referer": "https://your-site.example", "X-Title": "AI waygpt" }
Добавьте/включите модели:
После синхронизации вы можете просто включить нужные модели (переключатель “Включить/Выключить”). Если добавляете вручную: Админка → Модели → Добавить модель → provider: openrouter → API Base: https://openrouter.ai/api/v1 →model_identifier берите из openrouter.ai/models (обычно vendor/model).

2) Добавить модель

Откройте Админка → Модели и нажмите Добавить модель.
Укажите:
- ID: внутренний id (например gpt-4o-mini, deepseek-chat).
- Provider: должен совпадать с ключом провайдера (например openai / openrouter / groq).
- Model Identifier: то, что уходит на провайдера (часто совпадает с “официальным” именем модели). Для YandexGPT — это полный modelUri.
- API Base (опционально): базовый URL до .../v1 или .../api/v1 для OpenAI‑совместимых провайдеров.
- Task type: chat / image / video (влияет на то, в каких эндпоинтах модель доступна).

Важно: сейчас multimodal parts (контент вида [{type:text},{type:image_url}]) поддерживаются только для OpenAI‑compatible провайдеров.

3) Использование

В UI: откройте Чат и выберите модель. В API: используйте ваш project key и endpoint /api/v1/waygpt/chat/completions.

Как считается цена (важно для понимания “где править”): base_cost_usd * (1 + markup_percent) * plan_multiplier.base_cost берётся из полей модели base_cost_per_1k_input/output и фактических токенов запроса.markup_percent задаётся в Админка → Модели → Редактировать. plan_multiplier выбирается пользователем в Кабинет → Настройки (Тариф).

Полный “чек‑лист” с таблицами провайдеров/моделей: MODEL_CATALOG_RU.md в репозитории.