Техническая документация

ModelComparator сравнивает LLM в рамках проекта, где каждый сценарий хранит собственные критерии, веса и оценки. Итогом является рейтинг моделей, объяснение вклада критериев, анализ чувствительности, общая сводка по всем сценариям и PDF-экспорт финального документа.

• Проект фиксирует цель сравнения и общий набор моделей.
• Сценарий представляет отдельный промпт или задачу; критерии не наследуются автоматически.
• Критерий имеет группу, описание и вес; все критерии сценария участвуют в расчёте.
• Оценка задаётся по шкале 1..5 для пары модель × критерий.

• webapp.py — FastAPI-приложение, роуты форм, JSON API, GitHub Models, PDF-экспорт.
• core.py — SQLite-слой, CRUD-хелперы, формулы рейтинга, вкладов, gap-анализа и текстовой сводки.
• templates/index.html — основной интерфейс, модалки, пресеты, вкладки, общая сводка.
• static/app.js — бесшовная навигация, модалки подтверждения, графики Chart.js, random-fill оценок.
• static/styles.css — тёмная дизайн-система, AI-состояния, таблицы, полноэкранный мастер.

Сервер остаётся источником истины: после любого изменения он пересчитывает контекст через load_context(). Клиент делает UX бесшовным: формы с data-smooth-form отправляются через fetch, после чего DOM заменяется свежим серверным HTML без полной перезагрузки окна.

• projects(id, name, scenario, created_at) — проект и его описание.
• scenarios(id, project_id, name, description, created_at) — сценарии/промпты в порядке создания.
• models(id, project_id, name, description) — модели внутри проекта.
• saved_models(id, name, description, created_at) — библиотека моделей “в памяти”.
• criteria(id, project_id, scenario_id, group_name, name, description, weight, enabled) — критерии конкретного сценария.
• scores(id, model_id, criterion_id, score) — уникальная оценка для пары модель × критерий.
• criteria_presets(id, name, description, data, created_at) — пользовательские пресеты критериев и весов в JSON.
• comparator_ai_reports(project_id, scenario_id, summary, report, model, ...) — сохранённые AI-сводки; scenario_id = NULL используется для общей сводки.

Удаление сценария вручную удаляет его критерии, оценки и сценарные AI-отчёты. Удаление модели удаляет её оценки. SQLite foreign keys описаны в схеме, но практические каскады выполняются явными запросами, чтобы поведение оставалось прозрачным.

Для модели m, критерия i, веса w_i и оценки s_{m,i}:

S_m = Σ(w_i × s_{m,i})
S_max = 5 × Σ(w_i)
K_m = S_m / S_max

• K = 1 означает максимум по всем критериям при текущих весах.
• Пропущенная оценка не добавляет вклад, но считается в колонке пропусков.
• Сортировка рейтинга идёт по K по убыванию.

w'_i = w_i / Σ(w_j)

Нормировка сохраняет относительную важность критериев, но приводит сумму весов к 1. Это удобно для сравнимости сценариев.

Contribution_{m,i} = w_i × s_{m,i}
Gap_i = w_i × (s_{leader,i} - s_{runner,i})

• Вклад показывает, какие критерии реально двигают модель вверх.
• Gap показывает, на каких критериях лидер отрывается от ближайшего конкурента.
• Чувствительность пересчитывает K через JSON API при изменении весов ползунками.

Так как в проекте пока нет эталонных датасетов и токеновых логитов моделей, метрики считаются как proxy-показатели на основе экспертных оценок 1..5. Это полезно для сравнительной панели, но не заменяет полноценный benchmark.

• Accuracy — средняя оценка модели по всем критериям, делённая на 5.
• Precision — среднее по критериям группы “Точность”; если таких нет, берётся общий average.
• Recall — среднее по остальным группам; если таких нет, берётся общий average.
• F1 = 2PR / (P + R) — гармоническое среднее precision и recall.
• BLEU, ROUGE-L, BERTScore — сглаженные proxy от общего average.
• Perplexity — обратный proxy: чем выше средняя оценка, тем ниже показатель.

Для настоящих BLEU/ROUGE/BERTScore нужны эталонные ответы, а для perplexity нужны вероятности токенов. Текущая логика сохраняет интерфейс и математику сравнения LLM, но оставляет место для будущей автооценки на мощностях сервиса.

Новый сценарий создаётся без критериев. Пользователь добавляет критерии вручную, применяет базовый пресет или сохраняет собственный набор в criteria_presets.

Форма оценок проходит по всем полям score_{criterion_id}_{model_id}. Пустое поле удаляет оценку, число 1..5 создаёт или обновляет строку через ON CONFLICT(model_id, criterion_id).

/report.pdf собирает финальную сводку, рейтинг, критерии, LLM-метрики, матрицу оценок, сильные/слабые стороны и график K. Для кириллицы регистрируется системный TTF-шрифт, затем отдаётся бинарный application/pdf.

AI-отчёт вынесен в общую сводку по всем сценариям. В payload передаются проект, сценарии, критерии по сценариям, оценки, рейтинг, LLM-метрики и формулы расчёта. Модель должна вернуть строгий JSON с summary и report.

• GITHUB_TOKEN — токен GitHub Models, в UI не отображается.
• GITHUB_MODEL — модель для ComparatorAI; по умолчанию используется значение из webapp.py.

Статус токена: настроен.

Текущая модель: meta/Meta-Llama-3.1-8B-Instruct

• GET / — основной интерфейс.
• GET /guide — техническая документация.
• GET /report.pdf?project_id=…&scenario_id=… — PDF-экспорт.

• POST /project/create|update|duplicate|delete
• POST /scenario/create|update|delete
• POST /criteria/add|update|delete|normalize
• POST /criteria/preset/apply, POST /criteria/preset/save

• POST /model/add|delete|save|add_from_saved|delete_saved
• POST /scores/save, POST /scores/import
• POST /sensitivity/api — realtime-пересчёт рейтинга.
• POST /ai/report/global — общая сводка ComparatorAI.