README.md

---
title: RAG AIEXP 0
emoji: 🔥
colorFrom: blue
colorTo: gray
sdk: gradio
sdk_version: 5.42.0
app_file: app.py
pinned: false
---

# AIEXP — RAG pipeline for normative documents (README)

Кратко: репозиторий содержит конвейер загрузки и подготовки нормативных документов (JSON/CSV/таблицы/изображения), нормализации терминов (марки стали, обозначения соединений), чанкинга, построения векторного индекса и Gradio UI для семантического поиска и ответов.

---

## Содержание README
1. Требования
2. Быстрая установка
3. Переменные окружения / конфигурация
4. Структура данных / куда класть новые документы
5. Процесс подготовки данных (что делает pipeline)
6. Параметры чанкинга и частые ошибки
7. Построение индекса и создание query engine
8. Запуск приложения (локально / Windows)
9. Отладка и полезные утилиты
10. Как добавить новые документы
11. Частые ошибки и их исправления

---

## 1) Требования
- Python 3.10+  
- pip, git  
- Доступ к Hugging Face dataset (repo_id) для загрузки исходных JSON/CSV  
- API-ключи (для LLM / embeddings) при использовании удалённых моделей

Пример зависимостей (создайте requirements.txt):  
- llama-index (соответствующая версия)
- gradio>=5
- sentence-transformers
- huggingface-hub
- sentencepiece (если нужно)
- pandas
- cross-encoder
- другие: см. ваш проектный requirements

---

## 2) Быстрая установка
Windows PowerShell:
```powershell
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
```

Bash / Linux:
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

---

## 3) Переменные окружения / конфигурация
Отредактируйте `config.py` или установите переменные окружения:

PowerShell:
```powershell
$env:GOOGLE_API_KEY="your_google_api_key"
$env:OPENAI_API_KEY="your_openai_api_key"
$env:HF_TOKEN="your_hf_token"
```

Bash:
```bash
export GOOGLE_API_KEY="your_google_api_key"
export OPENAI_API_KEY="your_openai_api_key"
export HF_TOKEN="your_hf_token"
```

Основные настройки в `config.py`:
- CHUNK_SIZE (токены/символы для текстов)
- CHUNK_OVERLAP
- MAX_CHARS_TABLE / MAX_ROWS_TABLE — параметры чанкинга таблиц
- HF_REPO_ID, TABLE_DATA_DIR, JSON_FILES_DIR, IMAGE_DATA_DIR

---

## 4) Структура данных и форматы

AIEXP_RAG/
│── app.py              # Main entry point (Gradio)
│── requirements.txt    # Dependencies
│── data/               # Documents, tables, images
│── notebooks/          # Preprocessing notebooks
│── src/                # Source code (preprocess + rag)

- Текстовые документы: JSON (с полями document_metadata, sections/subsections)
- Таблицы: JSON (sheets → headers, data, table_number, table_title, section, sheet_name)
- Изображения: CSV (строки с полями: Обозначение документа, № Изображения, Название изображения, Описание)

При загрузке pipeline:
- `load_json_documents` — парсит текстовые разделы
- `load_table_documents` — парсит таблицы и запускает `chunk_table_by_content`
- `load_image_documents` — создает описательные чанки

Если вы добавляете новые данные на HF, положите их в соответствующие папки (см. `config.py`).

---

## 5) Что делает pipeline (пошагово)
1. Загрузка файлов с HF (JSON/ZIP/CSV)
2. Извлечение разделов документа (text)
3. Нормализация:
   - `normalize_text` — нормализует типы соединений (C/С)
   - `normalize_steel_designations` — нормализует марки стали (латиница ↔ кириллица)
4. Чанкинг:
   - Текст: SentenceSplitter (CHUNK_SIZE, CHUNK_OVERLAP)
   - Таблицы: собираются строки в чанки по правилам (header + строки) до MAX_CHARS_TABLE или MAX_ROWS_TABLE
5. Метаданные: минимальный набор (type, document_id, table_number, table_title, section, connection_type)
6. Построение VectorStoreIndex из всех чанков

---

## 6) Параметры чанкинга и частые ошибки
- Metadata length > chunk size:
  - Ошибка: ValueError: Metadata length (...) is longer than chunk size (1024).
  - Решение: увеличить CHUNK_SIZE или уменьшить размер поля metadata (не класть большие тексты в metadata).
- Если строки таблиц очень длинные, уменьшение MAX_CHARS_TABLE не даст эффекта — проверяйте длины отдельных строк.
- Рекомендация: комбинировать ограничения по символам и по числу строк (MAX_CHARS_TABLE и MAX_ROWS_TABLE).

---

## 7) Построение индекса и query engine
- create_vector_index(documents) — строит VectorStoreIndex и логирует статистику по типам соединений и таблицам.
- create_query_engine(vector_index, vector_top_k, bm25_top_k, similarity_cutoff, hybrid_top_k) — конфигурируемый гибридный retriever (Vector + BM25 + QueryFusion).
- Ререйтер `rerank_nodes(query, nodes, reranker, top_k, min_score_threshold)` — использует CrossEncoder для финального ранжирования.

Советы:
- Нормализуйте document_id (удалите лишние пробелы, суффиксы года) для точного фильтрования по документу.
- При поиске по типам соединений (C-25 / С-25) всегда нормализуйте символ 'C'/'С' в данных и в запросе.

---

## 8) Запуск приложения (Gradio)
Локально:
```bash
python app.py
```
Важно:
- Вызов `gr.api(...)` должен быть внутри `with gr.Blocks(...) as demo:` блока.
- Функции, которые вы регистрируете как Gradio API, должны иметь полные type-hints (например `def retrieve_chunks(question: str, top_k: int = 20) -> list:`).

---

## 9) Отладка и полезные утилиты
- Логирование: используйте `log_message(...)` — логирование подробностей в stdout/файл.
- Функции для отладки:
  - `debug_search_tables(vector_index, search_term="С-25")` — найдет таблицы по вхождению термина.
  - В `create_query_engine` можно добавить дополнительный перечисляющий лог (поиск по 'C-25' / 'С-25').
- Частые проверки:
  - Сколько чанков получилось: итог в `load_all_documents`.
  - Показать примерные превью чанков при отладке (первые 200 символов).
  - Дедупликация: `deduplicate_nodes(nodes)` — как формируются идентификаторы.

---

## 10) Как добавить новые документы
1. Подготовьте JSON/CSV в формате, согласованном с pipeline.
2. Загрузите в HF dataset (REPO_ID указанный в config.py) в соответствующую директорию:
   - JSON → `JSON_FILES_DIR`
   - Таблицы → `TABLE_DATA_DIR`
   - Изображения (CSV) → `IMAGE_DATA_DIR`
3. Обновите config (если новые директории)
4. Перезапустите `app.py` — или только шаги подготовки:
   - Запустите `load_all_documents(...)` и формирование индекса заново (см. app.initialize_system).

---

## 11) Частые ошибки и быстрые исправления
- Gradio: "Cannot call api() outside of a gradio.Blocks context." → переместить `gr.api(...)` внутрь блока.
- Gradio: "API endpoints must have type hints." → добавить type-hints в сигнатуру.
- Pydantic / Document immutability: "can't set attribute 'text'" → не изменяйте `doc.text` напрямую, создавайте новый `Document(text=..., metadata=doc.metadata)`.
- Метаданные слишком большие → уменьшить metadata или увеличить CHUNK_SIZE.
- Кириллическая/латинская буква 'C' mismatch → нормализуйте и в запросе, и в данных (функция `normalize_text` / `normalize_connection_type`).

---

## Примеры команд (Windows)
Установка env vars (PowerShell):
```powershell
$env:HF_TOKEN="hf_xxx"
$env:GOOGLE_API_KEY="xxx"
$env:OPENAI_API_KEY="xxx"
python app.py
```

---

## Консистентность метаданных (важно)
- Храните в metadata минимально нужные поля:
  - type, document_id, table_number, table_title, section, connection_type, chunk_id/row_start/row_end (при табличных чанках)
- Избегайте кладения больших текстов в metadata.

---

## Testing on Huggingface
https://mrsimple01-rag-aiexp-01.hf.space/