20 Newsgroups RAG Homework

Учебный RAG на открытом текстовом корпусе 20 Newsgroups. Pipeline: datasets.json -> documents.jsonl -> chunks.jsonl -> TF-IDF index -> retrieval -> demo-answer -> Streamlit UI.

Требования

• Python 3.10+
• uv

Быстрый старт

uv sync
uv run python scripts/prepare_datasets.py
uv run python scripts/build_index.py
uv run streamlit run app/main.py

Если data/raw/datasets.json уже лежит в репозитории, можно начинать с пересборки индекса:

uv run python scripts/build_index.py
uv run streamlit run app/main.py

Проверка из консоли

uv run python scripts/check_retrieval.py
uv run python scripts/check_generator.py
uv run python scripts/evaluate_retrieval.py
uv run pytest tests/ -v

В среде без установленного pytest можно запустить fallback-runner:

python scripts/run_tests.py

Последняя локальная проверка:

• scripts/prepare_datasets.py: 1200 records (300 x 4 categories).
• scripts/build_index.py: 1200 documents, 2877 chunks, matrix (2877, 11882).
• python -m pytest tests/ -v: 11 passed.
• scripts/evaluate_retrieval.py: retrieval@3=1.00 (4/4).
• Streamlit UI проверен на http://localhost:8501: positive-вопрос возвращает источники, negative-вопрос Citibank mortgage escrow дает отказ.

Данные

Источник: 20 Newsgroups bydate train split.

Скрипт scripts/prepare_datasets.py создает 1200 записей: по 300 из comp.graphics, rec.autos, sci.med, sci.space.

Подробности: doc/DATA.md.

Demo-вопросы

Тип	Вопрос	Ожидание
demo	What did NASA or the shuttle program discuss about space missions?	ответ с источниками sci.space
demo	What car engine oil or maintenance advice appears in the corpus?	ответ с источниками rec.autos
demo	How do the messages discuss computer graphics images and rendering?	ответ с источниками comp.graphics
negative	Citibank mortgage escrow	отказ без выдумок

Структура

app/
  config.py       paths and constants
  tfidf.py        transparent TF-IDF + cosine
  chunker.py      paragraph chunking
  retriever.py    top-k search
  generator.py    demo-answer and refusal
  main.py         Streamlit UI
scripts/
  prepare_datasets.py
  ingest.py
  build_index.py
  check_retrieval.py
  check_generator.py
  evaluate_retrieval.py
tests/
doc/
data/

Ограничения MVP

• Поиск lexical: TF-IDF ищет совпадающие слова, а не смысловые embeddings.
• Ответ demo-режима строится из фрагментов; внешняя LLM не подключена.
• Корпус содержит исторические публичные сообщения newsgroups, поэтому выводы не являются экспертной рекомендацией.

Улучшения

Реализованы два улучшения: диагностичный Streamlit UI с threshold/history и простой retrieval-eval. Подробнее: IMPROVEMENTS.md.