ZeBrains Gate — документация

Вся документация системы: LLM-гейтвея и панели управления к нему. Раньше она жила в двух README, которые росли до пределов читаемости; здесь она разложена по темам, и каждая страница отвечает на один вопрос.

Код — в двух других репозиториях:

С чего начать¶

Разворачиваете первый раз — Установка и запуск, потом Провайдеры и Пользователи и ключи. Разбираетесь, почему счёт такой — Цены и Логи.

Страницы¶

Как это устроено

• Архитектура — два решения, на которых стоит система, и кто чем владеет.
• Форматы и операции — какие входящие API приняты, какие операции у какого провайдера работают.
• Адресация моделей — provider/model, таблица маршрутов, регистр, что попадает в журнал.
• Схема и миграции — схема как контракт между двумя сервисами, порядок выката, форматы секретов.

Настройки

• Установка и запуск — Docker Compose, бой, без Docker.
• Переменные окружения — справочник по всем переменным и файлу конфигурации гейта.
• Провайдеры — типы, адреса, ключи, особенности диалектов, нагрузка и повторы.
• Пользователи и ключи — учётные записи, роли, наценка, лимиты, самообслуживание.
• Вход через каталог — LDAP и Active Directory.
• Цены — ставки за токены, ступени по контексту, окна по часам, цена за минуту аудио, валюта отображения.
• Логи — что записывается, как читается, что не записывается.

Работа с кодом

• Разработка и тесты — локальный стенд, тесты, тесты с базой.
• Границы версии — что намеренно не сделано и почему.

Смотреть в браузере¶

Страницы читаются как есть — в редакторе и на GitLab. Для чтения браузером тут же лежит образ: Markdown превращается в статический HTML на сборке, отдаёт nginx.

docker compose up -d --build     # http://localhost:8082

Порт меняется переменной WIKI_PORT. Ни JavaScript, ни внешних шрифтов, ни обращений к CDN — страница открывается в закрытой сети.

Собрать без Docker, чтобы посмотреть правку сразу:

pip install markdown==3.7
python tools/render.py ./site
python -m http.server -d site 8082

Оформление — tools/wiki.css, рендерер — tools/render.py. Боковое меню рендерер читает из этого файла: порядок и группировка здесь и есть источник навигации, второй список рассинхронизировался бы при первой же новой странице. Страница, не перечисленная выше, попадёт в сборку, но о ней будет предупреждение — найти её иначе будет нечем.

Соглашение этой документации¶

Страницы объясняют не только «как», но и «почему»: там, где решение неочевидно или обошлось дорого, написана причина. Если причина исчезла — решение можно менять; если написано «иначе счёт будет неверным», трогать без замены проверки нельзя.