ruwiki-test/README.md

RuWiki -> SchoolNotes

Асинхронная система упрощения статей RuWiki для школьного образования с использованием LLM OpenAI.

Описание

Система автоматически:

• Загружает статьи из русской Википедии
• Упрощает содержимое для учеников 8-11 классов с помощью OpenAI GPT
• Сохраняет оригинальный и упрощённый текст в SQLite
• Обрабатывает статьи параллельно

Архитектура

graph TD
    A[CLI / AsyncRunner] -->|URLs| B[TaskQueue asyncio_anyio]
    B --> C[Worker_N coroutine]
    C --> D[RuWikiAdapter]
    C --> E[TextSplitter]
    C --> F[LLMProvider]
    C --> G[WriteQueue]
    G --> H[(SQLite aiosqlite)]

Установка

Требования

• Python ≥ 3.10
• OpenAI API ключ

Установка зависимостей

# Создание виртуального окружения
python -m venv .venv
source .venv/bin/activate  # Linux/Mac
# или
.venv\Scripts\activate     # Windows

# Установка зависимостей
pip install -r requirements.txt

# Для разработки
pip install -r requirements-dev.txt

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

1. Скопируйте env_example.txt в .env:

cp env_example.txt .env

2. Настройте конфигурацию в env:

OPENAI_API_KEY=your_openai_api_key_here
...

Использование

Основные команды

# Обработка статей из файла
python -m src.cli process input.txt

# Принудительная обработка (повторная)
python -m src.cli process input.txt --force

# Ограничение количества статей
python -m src.cli process input.txt --max-articles 10

# Настройка количества workers
python -m src.cli process input.txt --max-workers 5

# Проверка здоровья системы
python -m src.cli health

# Просмотр статей в БД
python -m src.cli list-articles --limit 20

# Статистика по файлу с URL
python -m src.cli stats input.txt

Формат файла с URL

# input.txt
https://ru.ruwiki.ru/wiki/Изотопы
https://ru.ruwiki.ru/wiki/Вещественное_число
https://ru.ruwiki.ru/wiki/Митоз

Примеры

# Обработка тестовых статей
python -m src.cli process input.txt --max-articles 3 --max-workers 2

# Вывод результатов в JSON
python -m src.cli list-articles --format json --status completed

# Настройка логирования
python -m src.cli --log-level DEBUG --log-format json process input.txt

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

Основные параметры в .env:

# OpenAI
OPENAI_API_KEY=your_openai_api_key_here
OPENAI_MODEL=gpt-4o
OPENAI_TEMPERATURE=0.0
OPENAI_PROXY_URL='socks5h://37.18.73.60:5566'  # socks5 recommended

# База данных
DB_PATH=./data/wiki.db

# Производительность
MAX_CONCURRENT_LLM=5
OPENAI_RPM=200
MAX_CONCURRENT_WIKI=10

# Логирование
LOG_LEVEL=INFO
LOG_FORMAT=json

# Обработка текста
CHUNK_SIZE=2000
CHUNK_OVERLAP=200

# Надёжность
MAX_RETRIES=3
RETRY_DELAY=1.0
CIRCUIT_FAILURE_THRESHOLD=5
CIRCUIT_RECOVERY_TIMEOUT=60

Мониторинг

Логи

# Структурированные логи в JSON
python -m src.cli --log-format json process input.txt

# Отладочные логи
python -m src.cli --log-level DEBUG process input.txt

Метрики

• Скорость обработки: статей/минуту
• Процент успеха
• Среднее время обработки
• Использование токенов

Health Check

python -m src.cli health

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

# Все тесты
python -m pytest

# С покрытием
python -m pytest --cov=src --cov-report=html

# Без покрытия (быстрее)
python -m pytest --no-cov

# Только unit тесты
python -m pytest tests/test_models.py tests/test_adapters.py

# Интеграционные тесты
python -m pytest tests/test_integration.py

# Конкретный тест
python -m pytest tests/test_adapters.py::TestLLMProviderAdapter::test_simplify_text_success -v

Статус тестов

• ✅ 71 тест - все проходят
• ✅ Unit тесты - адаптеры, модели, сервисы
• ✅ Интеграционные тесты - база данных, файловые операции
• ✅ Системные тесты - полный цикл обработки

Примеры результатов

Исходная статья (фрагмент)

'''Изотопы''' (от {{lang-grc|ἴσος}} «равный» и {{lang-grc|τόπος}} «место») — разновидности атомов химического элемента с одинаковым количеством протонов, но различным количеством нейтронов в ядре...

Упрощённая версия

'''Изотопы''' — это разные виды атомов одного элемента.

== Что такое изотопы ==
У атомов одного элемента всегда одинаковое число протонов. Но число нейтронов может быть разным. Атомы с разным числом нейтронов называются изотопами...

Разработка

Качество кода

# Форматирование
black src/ tests/

# Проверка стиля
ruff check src/

# Типы
mypy src/

# Безопасность
bandit -r src/

Структура проекта

ruwiki_test/
├── src/
│   ├── adapters/          # Адаптеры для внешних API
│   ├── models/            # Модели данных
│   ├── services/          # Бизнес-логика
│   ├── cli.py            # CLI интерфейс
│   └── runner.py         # Основной runner
├── tests/                 # Тесты
├── data/                  # База данных
└── requirements.txt       # Зависимости