Files

Anton 99cd8ae727 docs: add full project documentation

- Architecture: overview, 7 ADR, tech stack
- Principles: code-style, git-workflow, security
- API contracts: auth, profile, tests, admin endpoints
- Database schema: tables, relationships, indexes
- LLM strategy: prompts, fallback, validation, Qwen 2.5 14B
- Onboarding: setup, Docker, .env template
- Progress: roadmap, changelog
- Agents: context, backend instructions

Made-with: Cursor

2026-03-04 12:07:17 +03:00

2.0 KiB

Raw Permalink Blame History

ADR-005: Абстракция LLM через LlmService

Статус

Принято

Контекст

Приложение использует LLM для генерации вопросов, проверки ответов и рекомендаций. Нужна возможность менять провайдера без изменения бизнес-логики.

Решение

Весь доступ к LLM только через LlmService. Конфигурация провайдера — через переменные окружения:

LLM_BASE_URL=http://localhost:11434/v1    # Ollama (runtime для backend)
LLM_MODEL=qwen2.5:14b
LLM_API_KEY=                               # пустой для локального
LLM_TIMEOUT_MS=15000
LLM_MAX_RETRIES=1

Стратегия провайдеров

Dev/test — локальный LLM (Ollama, LM Studio, vLLM) с OpenAI-совместимым API
Production — облачный API (OpenAI, Anthropic и др.)
Переключение — замена переменных в .env, код приложения не меняется

Интерфейс LlmService

generateQuestions(stack, level, count, type) → structured JSON
verifyAnswer(question, userAnswer) → boolean + explanation
getHint(question) → string
getRecommendations(weakTopics) → string[]

Fallback

Если LLM недоступен или таймаут — берём вопросы из question_bank (предварительно наполненного через тот же LLM и провалидированного вручную).

Последствия

Бизнес-код не зависит от конкретного провайдера
Замена LLM — изменение одного .env файла
Нужен минимальный банк вопросов для fallback до запуска
Все ответы LLM валидируются по JSON-схеме перед использованием

2.0 KiB Raw Permalink Blame History Unescape Escape