Configuration · руководство по настройке

Настройка .env для трёх AI CLI. Настраивать нужно немного: выберите одного LLM-провайдера (OpenAI / GLM / DeepSeek / Kimi / Qwen / Doubao), а если хочется подкасты — добавьте TTS (пока только GLM-TTS). Всё работает по OpenAI-совместимому протоколу, смена провайдера — это три переменные.

TL;DR

cp .env.example .env
# 编辑 .env，至少配三项：
# LLM_BASE_URL=https://open.bigmodel.cn/api/paas/v4   (или любой провайдер ниже)
# LLM_API_KEY=your-key
# LLM_MODEL=glm-4.6                                   (или соответствующее имя model)

Комментарий в блоке выше — из файла-примера, оставлен как есть; суть: отредактируйте .env и заполните как минимум три указанные переменные.

После настройки проверьте запуск командой node apps/quiz-app/scripts/teach-generate.mjs --theme dev-intro.

Выбор LLM-провайдера

Все провайдеры подключаются по OpenAI-совместимому протоколу — код переключается через параметр baseURL npm-пакета openai.

Провайдер	baseURL	Рекомендуемая model	Особенности
Zhipu GLM (рекомендуется)	`https://open.bigmodel.cn/api/paas/v4`	`glm-4.6`	хорош для китайского, дёшев и стабилен, TTS на том же ключе
DeepSeek	`https://api.deepseek.com/v1`	`deepseek-chat`	самый дешёвый в Китае, силён в коде
Moonshot Kimi	`https://api.moonshot.cn/v1`	`moonshot-v1-32k`	длинный контекст
Alibaba Qwen	`https://dashscope.aliyuncs.com/compatible-mode/v1`	`qwen-plus`	экосистема Alibaba
ByteDance Doubao	`https://ark.cn-beijing.volces.com/api/v3`	`doubao-pro-32k`	экосистема ByteDance

Провайдер	baseURL	Рекомендуемая model
OpenAI	`https://api.openai.com/v1`	`gpt-4o-mini` (цена/качество) / `gpt-4o` (качество)

Claude / Gemini и прочие не-OpenAI протоколы

Нативно пока не поддерживаются. Подключайтесь через OpenAI-совместимый прокси:

LiteLLM Proxy: открытый код, самостоятельное развёртывание, унифицирует протоколы 100+ провайдеров
OpenRouter: SaaS, единый интерфейс, оплата по потреблению

Позже могут появиться нативные адаптеры Anthropic / Google.

Сервер выгрузки ошибок (SERVER, опционально)

grill-wrong.mjs выгружает ошибки из /api/progress бэкенда quiz-app и по умолчанию стучится в локальный http://localhost:8787. Если нужно направить локальный CLI на ваш развёрнутый в сети сервер, поменяйте здесь:

SERVER=https://your-server.example.com node apps/quiz-app/scripts/grill-wrong.mjs --theme your-theme

Остальные CLI (teach / podcast) ничего не тянут по сети и эту переменную не используют.

Язык вывода (STUDY_LANG, опционально)

Язык генерируемого контента трёх AI CLI; поддерживается zh (по умолчанию) / en / es / ru:

STUDY_LANG=en   # задаётся в .env, или разово при запуске: STUDY_LANG=es node ...

Аргумент командной строки --lang имеет приоритет над этой переменной окружения. Она влияет только на генерируемое содержимое курса/разбора/подкаста и фиксированные строки HTML; логи CLI остаются на китайском. Мультиязычность TTS у podcast зависит от провайдера (сначала проверьте с --no-tts). Подробности — в разделе «Язык вывода» руководства ai-cli-guide.ru.md.

Настройка TTS-провайдера (нужна только podcast-generate)

Сейчас поддерживается только GLM-TTS (Zhipu). Позже добавим OpenAI TTS / ElevenLabs.

Конфигурация

TTS_PROVIDER=glm-tts              # значение по умолчанию, можно опустить
GLM_TTS_API_KEY=your-glm-key      # если ваш LLM уже GLM, ключ LLM_API_KEY подхватится автоматически
TTS_MALE_VOICE=male                # опционально, по умолчанию male
TTS_FEMALE_VOICE=female            # опционально, по умолчанию female

Варианты голосов

Поддерживаемые GLM-TTS значения voice (подробности — в официальной документации):

Значение voice	Стиль
`male` / `female`	универсальные мужской/женский голоса (значения CLI по умолчанию, рекомендуются для старта)
`彤彤` / `小陈` / `锤锤` / `jam` / `kazi` / `douji` / `luodo`	конкретные имена голосов

Разным голосам могут требоваться разные права аккаунта — сначала добейтесь успешного теста с male/female, потом пробуйте конкретные голоса.

Не хотите настраивать TTS?

Запустите podcast-generate с --no-tts: получатся только сценарий диалога и транскрипт, а аудио синтезируйте позже другим инструментом (NotebookLM, онлайн-TTS и т. п.).

Полный шаблон .env

См. .env.example. Скопируйте и заполните значения:

cp .env.example .env

Как загружается конфигурация

При старте CLI scripts/lib/llm.mjs автоматически подхватывает .env из двух мест: корень репозитория (ai-study-kit/.env) и apps/quiz-app/.env. Первое имеет приоритет.
Если не хватает любого обязательного поля, CLI ясно печатает, чего не хватает и как настроить, после чего делает exit(1) — на полпути посреди работы оно не падает.
API-ключи никогда не попадают в git (.env уже исключён в .gitignore).

Проверка конфигурации

Проверить настройку LLM:

node -e "
import('./apps/quiz-app/scripts/lib/llm.mjs').then(async (m) => {
  const r = await m.chat([{ role: 'user', content: '回复\"OK\"两个字' }]);
  console.log('LLM response:', r);
});
"

Ожидаемый вывод — что-то вроде LLM response: OK. Если падает ошибка, прочитайте сообщение — обычно ключ недействителен или baseURL написан неверно.

Проверка TTS:

node -e "
import('./apps/quiz-app/scripts/lib/tts.mjs').then(async (m) => {
  const r = await m.synthesize({ text: '测试', gender: 'female' });
  console.log('TTS bytes:', r.audio.length);
});
"

Ожидаемый вывод — TTS bytes: <число> (от десятков до сотен тысяч).

Частые ошибки конфигурации

Сообщение об ошибке	Причина	Решение
`LLM 配置不完整`	в `.env` не хватает полей	проверьте, что заполнены `LLM_BASE_URL` / `LLM_API_KEY` / `LLM_MODEL`
`401 Unauthorized`	API-ключ недействителен или истёк	сгенерируйте ключ заново
`404 Not Found`	неверно написан baseURL	сверьтесь с документацией провайдера: в конце baseURL должен быть `/v1` или `/v4`
`model not found`	неверное имя model	сверьтесь с документацией провайдера: доступные model зависят от прав аккаунта
`音色id不存在` (TTS)	значение voice неверное или не поддерживается	откатитесь на `male`/`female`
`connect ETIMEDOUT`	доступ к зарубежным сервисам вроде OpenAI из Китая	перейдите на китайского провайдера или настройте прокси

Замечания по безопасности

.env уже в .gitignore и никогда не попадает в git
Не вписывайте API-ключи в код или документацию
Если ключ случайно попал в коммит — немедленно отзовите его в консоли провайдера и сгенерируйте новый
При развёртывании на сервере используйте серверные переменные окружения или secret manager — не переносите файл .env