README.md

metadata

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:

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt

Bash / Linux:

python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

---

3) Переменные окружения / конфигурация

Отредактируйте config.py или установите переменные окружения:

PowerShell:

$env:GOOGLE_API_KEY="your_google_api_key"
$env:OPENAI_API_KEY="your_openai_api_key"
$env:HF_TOKEN="your_hf_token"

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)

Локально:

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):

$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/