CEFR AI — Система тестирования уровня английского языка

Общая информация

CEFR AI — это веб-приложение для автоматизированного диагностического тестирования уровня владения английским языком по шкале CEFR (Common European Framework of Reference).

Система организует интерактивный процесс:

• Пользователь проходит серию структурированных заданий
• Ответы автоматически оцениваются с использованием LLM (OpenAI)
• Система отслеживает прогресс в памяти сессии
• Формируется итоговый отчет с определением уровня (A1–C2) и статистикой по навыкам
• Результаты сохраняются в JSON-логах

Архитектура и структура проекта

cefr_ai/
├── main.py                          # FastAPI приложение, основные маршруты
├── README.md                        # Документация
├── dockerfile                       # Docker-конфигурация
├── pyproject.toml                   # Конфигурация проекта
│
├── templates/                       # HTML-шаблоны для веб-интерфейса
│   ├── base.html                    # Базовый шаблон
│   ├── index.html                   # Страница входа
│   ├── quiz_form.html               # Форма теста
│   ├── free_text_form.html          # Форма для свободного ответа
│   ├── quiz_media.html              # Тест с медиа
│   └── finish.html                  # Страница результатов
│
├── static/                          # Статические ресурсы
│   └── audio/                       # Аудиофайлы для тестов
│
├── logs/                            # Логи результатов
│   └── [user_results].json          # JSON-отчеты сессий
│
├── exercises/                       # Основной модуль логики тестирования
│   ├── dependencies.py              # Инициализация сервисов
│   ├── requirements.txt             # Зависимости
│   │
│   ├── exercises_service/           # Ядро системы тестирования
│   │   ├── lesson_engine.py         # Главный двигатель сессий и прогресса
│   │   ├── schema_load_example.py   # Примеры загрузки схем
│   │   │
│   │   ├── models/                  # Pydantic модели данных
│   │   │   ├── repo_models.py       # Модели уроков и заданий
│   │   │   ├── grade_models.py      # Модели результатов оценивания
│   │   │   └── userforms_models.py  # Модели ответов пользователя
│   │   │
│   │   ├── repositories/            # Доступ к данным
│   │   │   ├── lessons_repo.py      # Репозиторий уроков
│   │   │   └── mock_data/           # Тестовые данные
│   │   │       ├── diagnostic_01.json
│   │   │       ├── valid_lesson.json
│   │   │       └── invalid_lesson.json
│   │   │
│   │   ├── grading/                 # Логика оценивания
│   │   │   └── grader.py            # Проверка заданий (готовые варианты или LLM)
│   │   │
│   │   └── tests/                   # unit тесты
│   │       └── test_engine.py
│   │
│   └── integration/                 # Интеграция с внешними сервисами
│       └── llm_adapter.py           # Адаптер для LLM
│
├── llm_gateway/                     # Модуль работы с LLM
│   ├── main.py                      # Отдельный сервер LLM Gateway
│   ├── routers.py                   # Маршруты для LLM
│   ├── requirements.txt             # Зависимости
│   │
│   ├── llm_service/                 # Основной сервис LLM
│   │   ├── llm_service.py           # Интерфейс LLM сервиса
│   │   ├── config_loader.py         # Загрузка конфигураций из YAML
│   │   ├── prompt_constructor.py    # Конструктор промптов
│   │   ├── token_count.py           # Подсчет токенов
│   │   │
│   │   ├── llm_config/              # Конфигурационные файлы
│   │   │   ├── llm_models.yaml      # Параметры моделей LLM
│   │   │   └── scenarios.yaml       # Сценарии использования
│   │   │
│   │   └── prompts/                 # Шаблоны промптов
│   │       ├── text_generator.yaml  
│   │       ├── text_questions_gen.yaml
│   │       ├── writing_evaluation.yaml
│   │       └── [другие сценарии]
│   │
│   ├── llm_providers/               # Реализации провайдеров
│   │   └── llm_openai.py            # OpenAI API
│   │
│   ├── models/                      # Pydantic модели
│   │   ├── api_pydantic.py          # API модели
│   │   └── llm_pydantic.py          # LLM модели
│   │
│   └── examples/                    # Примеры использования
│       ├── examples_llm_openai.py
│       ├── examples_prompt.py
│       └── examples_scenario.py
│
└── utils/                           # Утилиты
    └── file_utils.py                # Работа с файлами

Описание основных модулей

main.py — FastAPI приложение

Главная точка входа. Определяет маршруты и управляет потоком запросов:

• GET / — Страница входа (ввод имени пользователя)
• POST / — Начало теста (получение user_id)
• GET /start — Инициализация сессии
• GET /check-progress/{session_id} — Маршрутизатор (выбор следующего задания)
• GET /lessons/{lesson_id}/{task_id} — Рендеринг страницы задания
• POST /submit-answer/{session_id} — Прием ответа пользователя
• GET /finish/{session_id} — Вывод итоговых результатов
• GET /test-llm — Технический эндпоинт для проверки LLM

exercises/exercises_service/lesson_engine.py — LessonEngine

Центральный компонент логики тестирования:

• Управление сессиями в памяти (кэш)
• Отслеживание прогресса пользователя через индекс текущего задания
• Обработка ответов пользователя
• Вызов грейдера для оценивания
• Формирование финального отчета с уровнем CEFR

Ключевые методы:

• init_session()
  — создание новой сессии
• process_task_result()
  — обработка отправленного ответа
• get_next_step_info()
  — определение следующего задания
• get_task_content()
  — загрузка содержимого задания
• get_final_summary()
  — формирование итогового отчета

exercises/exercises_service/grading/grader.py — Grader

Модуль оценивания ответов:

• Получает ответ пользователя и модель задания
• Вызывает LLM для оценки в зависимости от типа задания
• Формирует структурированный результат оценивания
• Вычисляет итоговый балл и уровень CEFR

exercises/exercises_service/models/ — Модели данных

Pydantic модели для валидации и сериализации:

• repo_models.py —
  TaskModel
  ,
  LessonModel
  ,
  TaskId
  (структура уроков и заданий)
• grade_models.py —
  TaskAnswers
  ,
  GradingResult
  (результаты оценивания)
• userforms_models.py —
  UserAnswerModel
  (ответы пользователя)

exercises/exercises_service/repositories/lessons_repo.py — LessonRepository

Доступ к данным уроков:

• Загрузка уроков из JSON-файлов (mock_data)
• Валидация структуры уроков
• Предоставление информации о заданиях

llm_gateway/llm_service/ — LLM Service

Интеграция с языковыми моделями:

• llm_service.py — основной интерфейс для генерации и оценивания
• config_loader.py — загрузка конфигураций из YAML
• prompt_constructor.py — построение промптов из шаблонов
• token_count.py — подсчет использованных токенов

llm_gateway/llm_providers/llm_openai.py — OpenAI Provider

Конкретная реализация для работы с OpenAI API:

• Отправка запросов к модели GPT
• Парсинг ответов
• Обработка ошибок API

exercises/integration/llm_adapter.py — LLM Adapter

Адаптер для унификации работы с LLM: локально или по api (пока только локально)

templates/ — HTML-шаблоны

Jinja2 шаблоны для веб-интерфейса:

• Динамическое рендеринг форм в зависимости от типа задания
• Передача данных между клиентом и сервером

Поток выполнения

1. Пользователь входит на / и вводит имя
   ↓
2. POST / → RedirectResponse к /start?user_id=...
   ↓
3. GET /start → init_session → RedirectResponse к /check-progress/{session_id}
   ↓
4. GET /check-progress/{session_id} → get_next_step_info → RedirectResponse к /lessons/{lesson_id}/{task_id}
   ↓
5. GET /lessons/{lesson_id}/{task_id} → render_task (рендер HTML-формы)
   ↓
6. Пользователь заполняет форму и отправляет
   ↓
7. POST /submit-answer/{session_id} → process_task_result → Grader.evaluate → RedirectResponse к /check-progress
   ↓
8. Повтор шагов 4-7 до завершения всех заданий
   ↓
9. get_next_step_info возвращает status="finished"
   ↓
10. GET /finish/{session_id} → get_final_summary → render finish.html с результатами

Требования и установка

Зависимости

• Python 3.12
• FastAPI — веб-фреймворк
• Uvicorn — ASGI-сервер
• Pydantic — валидация данных
• python-dotenv — управление переменными окружения
• PyYAML — парсинг конфигураций
• OpenAI — API для работы с GPT

Установка

Приложение будет доступно по адресу: http://localhost:8000

Тестирование

Запуск модульных тестов

Проверка LLM интеграции

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

Переменные окружения (.env)

OPENAI_API_KEY=sk-...              # API ключ OpenAI
либо другие провайдеры, использующие формат openai

YAML конфигурации

• llm_gateway/llm_config/llm_models.yaml
  — параметры моделей
• llm_gateway/llm_config/scenarios.yaml
  — доступные сценарии

Выходные данные

Результаты сохраняются в

Лицензия

Проект предназначен для образовательных и исследовательских целей.