🚀 GraphRAG System - Автоматическая система ответов на вопросы

Соревнование: Data Feeling School RAG Challenge

📋 Описание

Современная система GraphRAG (Graph Retrieval-Augmented Generation) для автоматических ответов на вопросы.

Ключевые особенности:

🎯 Структурный парсинг документов - извлечение знаний на основе структуры документа
📊 Neo4j граф знаний - хранение информации в виде графа с отношениями
🔍 Векторный поиск - семантический поиск через embeddings (OpenRouter)
🤖 LLM для ответов - точная генерация ответов через OpenRouter GPT-4.1
🔗 Богатая сеть отношений - связи между секциями, сотрудниками, технологиями, годами
📈 Статистика - автоматический расчет метрик по сотрудникам
🌐 Универсальность - адаптируется к данным

🏗️ Архитектура

Пайплайн обработки данных

flowchart TD
    A[📁 Данные] --> |ITB.txt<br/>itb_employees.csv| B[📊 build_graph_simple.py]
    
    B --> |Парсинг структуры| C{Обработка}
    C --> |Создание узлов| D[Topic, Person, Position, etc.]
    C --> |OpenRouter API| E[Генерация embeddings]
    C --> |Анализ связей| F[Создание отношений]
    C --> |Вычисления| G[Статистика]
    
    D --> H[(Neo4j Graph DB)]
    E --> H
    F --> H
    G --> H
    
    H --> |Граф знаний| I[🤖 graphrag_qa.py]
    
    I --> J{GraphRAG Engine}
    J --> |Retrieval| K[GraphRetriever<br/>- Keyword search<br/>- Vector search<br/>- Hybrid search]
    J --> |Generation| L[AnswerGenerator<br/>- LLM GPT-4.1<br/>- Strict formatting<br/>- Fallback mode]
    
    K --> M[Контекст из графа]
    M --> L
    L --> N[📄 answers_raw.csv]
    
    N --> O[🔮 create_submission.py]
    O --> |LaBSE embeddings| P[✅ submission.csv]
    
    style A fill:#e1f5ff
    style H fill:#ffe1e1
    style I fill:#fff4e1
    style P fill:#e1ffe1
    style J fill:#f0e1ff

Легенда:

📁 Входные данные - текстовые файлы и CSV
📊 Построение графа - парсинг и структурирование
🗄️ Neo4j - граф знаний с узлами и связями
🤖 GraphRAG - поиск контекста + генерация ответов
✅ Результат - submission.csv для отправки

📥 Данные

⚠️ Данные не включены в репозиторий!

Скачайте данные с Kaggle: https://www.kaggle.com/competitions/data-feeling-school-rag-challenge/data

Распакуйте в папку data/. См. data/README_DATA.txt для инструкций.

Структура данных:

data/
  ├── ITB.txt                  # Текст о компании (структурированный)
  ├── itb_employees.csv        # Сотрудники (Name, Position, Sex, Age, Salary)
  ├── itb_questions.csv        # 135 вопросов для ответов
  └── sample_submission.csv    # Пример формата submission

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

1. Разворачивание Neo4j (опционально)

Если у вас нет Neo4j сервера, можно быстро развернуть через Docker:

# Запустить Neo4j через docker-compose
docker-compose up -d

# Проверить статус
docker-compose ps

# Логи
docker-compose logs -f neo4j

После запуска Neo4j будет доступен:

🌐 Web UI: http://localhost:7474/
🔌 Bolt: bolt://localhost:7687
🔑 Логин: neo4j / Пароль: password123 (измените в docker-compose.yml!)

Остановка:

docker-compose down

Полная очистка данных:

docker-compose down -v

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

pip install -r requirements.txt

Зависимости:

neo4j - подключение к Neo4j
pandas - работа с данными
openai - LLM и embeddings через OpenRouter
sentence-transformers - локальные embeddings для submission
python-dotenv - загрузка .env файла

3. Настройка `.env`

Скопируйте .env.example в .env:

cp .env.example .env

Заполните .env своими настройками:

# Neo4j Connection
NEO4J_URI=bolt://localhost:7687        # или bolt://ваш-сервер:7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=password123             # если используете docker-compose

# OpenRouter API
OPENROUTER_API_KEY=sk-or-v1-your-api-key

# LLM Settings
LLM_PROVIDER=openrouter
LLM_MODEL=openai/gpt-4.1
EMBEDDING_MODEL=openai/text-embedding-3-large

# GraphRAG Settings
USE_VECTOR_SEARCH=True
VECTOR_SEARCH_WEIGHT=0.5
MAX_SEARCH_NODES=30

Важно:

🔑 OpenRouter API ключ можно получить на https://openrouter.ai/
🗄️ Все креденшиалы только в .env
🐳 Если используете локальный Docker Neo4j - URI: bolt://localhost:7687

4. Запуск

Полный пайплайн (рекомендуется):

python run_full_pipeline.py

Это автоматически запустит все 3 этапа:

📊 Построение графа знаний
🤖 Генерация ответов через GraphRAG
🔮 Создание submission.csv

Или пошагово:

# Шаг 1: Построить граф
python build_graph_simple.py

# Шаг 2: Ответить на вопросы
python graphrag_qa.py

# Шаг 3: Создать submission
python create_submission.py

📦 Компоненты

1. `build_graph_simple.py` - Построение графа

Что делает:

📖 Парсит ITB.txt по структуре (заголовки **Header**)
👥 Загружает сотрудников из itb_employees.csv
🔢 Генерирует embeddings через OpenRouter
🔗 Создает богатую сеть отношений
📈 Вычисляет статистику (зарплаты, возраст, гендер)
🔍 Создает векторные индексы для поиска

Типы узлов:

Topic - секции из ITB.txt (с content и embeddings)
Person - сотрудники (с position, age, salary, sex, embeddings)
Position - должности
Company - компания ИТБ
Year - года (2002, 2005, 2010...)
Technology - технологии (ИИ, биотехнологии...)
Statistic - статистические данные

Типы отношений:

NEXT - последовательные секции
MENTIONS - упоминания компании
REFERS_TO_YEAR - ссылки на года
DISCUSSES - обсуждение технологий
MENTIONS_PERSON - упоминания людей
MENTIONS_POSITION - упоминания должностей
HOLDS_POSITION - сотрудник занимает должность

2. `graphrag_qa.py` - GraphRAG система

GraphRetriever (Retrieval):

Извлечение ключевых слов из вопроса
Keyword search - поиск по тексту в узлах
Vector search - семантический поиск через embeddings
Hybrid search - комбинация keyword + vector с весами
Сбор контекста: узлы + их соседи + статистика

AnswerGenerator (Generation):

LLM режим - OpenRouter GPT-4.1 с строгим промптом
Fallback режим - rule-based извлечение без LLM
Строгие правила форматирования:
- Года → только число (2002)
- Количество → точный формат из текста ("пять")
- Проценты → с % (15%)
- Перечисления → все элементы через запятую
- Короткие односложные ответы

3. `create_submission.py` - Генерация submission

Использует локальную модель cointegrated/LaBSE-en-ru
⚠️ НЕ использует OpenRouter для submission embeddings
Батч-обработка ответов
Создает финальный submission.csv

4. `config.py` - Централизованная конфигурация

Загрузка настроек из .env

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

Все настройки через .env файл:

Neo4j

NEO4J_URI - адрес сервера (bolt://host:7687)
NEO4J_USER - пользователь
NEO4J_PASSWORD - пароль

OpenRouter (LLM & Embeddings)

OPENROUTER_API_KEY - API ключ
LLM_MODEL - модель для ответов (openai/gpt-4.1)
EMBEDDING_MODEL - модель для embeddings (openai/text-embedding-3-large)

GraphRAG

USE_VECTOR_SEARCH - использовать векторный поиск (True/False)
VECTOR_SEARCH_WEIGHT - вес векторного поиска в hybrid (0.0-1.0)
MAX_SEARCH_NODES - макс. узлов для поиска
GRAPH_DEPTH - глубина навигации по графу
EMBEDDING_BATCH_SIZE - размер батча для embeddings

🔍 Визуализация графа

Структура данных в Neo4j

graph LR
    Topic[🔷 Topic<br/>name, content<br/>section_number<br/>embedding]
    Person[👤 Person<br/>name, position<br/>age, salary, sex<br/>embedding]
    Position[💼 Position<br/>name]
    Company[🏢 Company<br/>name: ИТБ]
    Year[📅 Year<br/>value: 2002..]
    Technology[⚙️ Technology<br/>name]
    Statistic[📊 Statistic<br/>type, values]
    
    Topic -->|NEXT| Topic
    Topic -->|MENTIONS| Company
    Topic -->|REFERS_TO_YEAR| Year
    Topic -->|DISCUSSES| Technology
    Topic -->|MENTIONS_PERSON| Person
    Topic -->|MENTIONS_POSITION| Position
    Person -->|HOLDS_POSITION| Position
    
    style Topic fill:#4a9eff
    style Person fill:#ff9d4a
    style Position fill:#ffeb4a
    style Company fill:#ff4a4a
    style Year fill:#b84aff
    style Technology fill:#4aff88
    style Statistic fill:#ff4ab8

Скриншот реального графа

Граф знаний компании ИТБ в Neo4j Browser

Cypher запросы для исследования

Откройте Neo4j Browser и выполните Cypher запросы:

// Посмотреть статистику
MATCH (n)
RETURN labels(n)[0] as Type, count(*) as Count
ORDER BY Count DESC

// Найти все топики
MATCH (t:Topic)
RETURN t.name, t.section_number
ORDER BY t.section_number
LIMIT 20

// Найти сотрудников и их должности
MATCH (p:Person)-[:HOLDS_POSITION]->(pos:Position)
RETURN p.name, p.age, p.salary, pos.name
ORDER BY p.salary DESC

// Найти связи технологий
MATCH (t:Topic)-[:DISCUSSES]->(tech:Technology)
RETURN tech.name, count(t) as mentions
ORDER BY mentions DESC

// Статистика по зарплатам
MATCH (s:Statistic {type: 'salary'})
RETURN s.average, s.minimum, s.maximum, s.total_employees

📊 Результаты

После запуска создаются:

✅ Neo4j граф - структурированные знания с отношениями и embeddings
✅ answers_raw.csv - промежуточные ответы на вопросы
✅ submission.csv - финальный файл с embeddings для отправки

🎓 Возможные улучшения

1. Улучшение качества ответов

Fine-tuning промптов для разных типов вопросов
Использование chain-of-thought reasoning
Re-ranking результатов поиска

2. Расширение графа

Извлечение дат и событий
Добавление иерархических связей
Создание временной шкалы

3. Оптимизация поиска

Настройка весов hybrid search
Использование multiple vector indexes
Добавление full-text search индексов

4. Альтернативные LLM

Anthropic Claude (через OpenRouter)
Локальные модели (LLaMA, Mistral)
Специализированные QA модели

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

kaggle/
├── .env                      # ⚠️ Конфигурация (не в git!)
├── .env.example              # Шаблон конфигурации
├── .gitignore                # Игнорируемые файлы
├── .cursorignore             # Файлы для AI ассистента
├── docker-compose.yml        # 🐳 Docker Compose для Neo4j
├── requirements.txt          # Python зависимости
├── README.md                 # Документация (этот файл)
│
├── config.py                 # ⚙️ Централизованная конфигурация
│
├── build_graph_simple.py     # 📊 [Этап 1] Построение графа
├── graphrag_qa.py            # 🤖 [Этап 2] GraphRAG Q&A система
├── create_submission.py      # 🔮 [Этап 3] Генерация submission
├── run_full_pipeline.py      # 🚀 Полный пайплайн (запускает все 3 этапа)
├── data/                     # 📁 Данные (скачать с Kaggle)
│   ├── ITB.txt               # Текст о компании ИТБ
│   ├── itb_employees.csv     # Данные сотрудников
│   ├── itb_questions.csv     # 135 вопросов для ответов
│   ├── sample_submission.csv # Пример формата submission
│   ├── neo4j.png             # 📸 Визуализация графа
│   └── README_DATA.txt       # 📥 Ссылка для скачивания данных
│
├── answers_raw.csv           # ✅ Результат: ответы на вопросы
└── submission.csv            # ✅ Результат: файл для отправки

🎉 Полная инструкция запуска

# 1. Разворачивание Neo4j (если нет своего сервера)
docker-compose up -d
# Проверьте: http://localhost:7474/

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

# 3. Настройка окружения
cp .env.example .env
# Отредактируйте .env:
# - NEO4J_URI=bolt://localhost:7687 (если Docker)
# - OPENROUTER_API_KEY=ваш-ключ

# 4. Скачивание данных
# Скачайте с Kaggle и распакуйте в data/
# См. data/README_DATA.txt

# 5. Запуск пайплайна
python run_full_pipeline.py

# 6. Результат
# → submission.csv готов для отправки! 🚀

Время выполнения: ~5-10 минут
Качество: зависит от настройки промптов и параметров поиска

Navigation Menu

Repository files navigation

🚀 GraphRAG System - Автоматическая система ответов на вопросы

📋 Описание

Ключевые особенности:

🏗️ Архитектура

Пайплайн обработки данных

📥 Данные

Структура данных:

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

1. Разворачивание Neo4j (опционально)

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

3. Настройка `.env`

4. Запуск

📦 Компоненты

1. `build_graph_simple.py` - Построение графа

2. `graphrag_qa.py` - GraphRAG система

3. `create_submission.py` - Генерация submission

4. `config.py` - Централизованная конфигурация

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

Neo4j

OpenRouter (LLM & Embeddings)

GraphRAG

🔍 Визуализация графа

Структура данных в Neo4j

Скриншот реального графа

Cypher запросы для исследования

📊 Результаты

🎓 Возможные улучшения

1. Улучшение качества ответов

2. Расширение графа

3. Оптимизация поиска

4. Альтернативные LLM

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

🎉 Полная инструкция запуска

About

Releases

Packages

Contributors

Languages

Name		Name	Last commit message	Last commit date
data		data
.env.example		.env.example
.gitignore		.gitignore
README.md		README.md
build_graph_simple.py		build_graph_simple.py
config.py		config.py
create_submission.py		create_submission.py
docker-compose.yml		docker-compose.yml
graphrag_qa.py		graphrag_qa.py
requirements.txt		requirements.txt
run_full_pipeline.py		run_full_pipeline.py

Latest commit

History

Folders and files

Repository files navigation

🚀 GraphRAG System - Автоматическая система ответов на вопросы

📋 Описание

Ключевые особенности:

🏗️ Архитектура

Пайплайн обработки данных

📥 Данные

Структура данных:

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

1. Разворачивание Neo4j (опционально)

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

3. Настройка .env

4. Запуск

📦 Компоненты

1. build_graph_simple.py - Построение графа

2. graphrag_qa.py - GraphRAG система

3. create_submission.py - Генерация submission

4. config.py - Централизованная конфигурация

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

Neo4j

OpenRouter (LLM & Embeddings)

GraphRAG

🔍 Визуализация графа

Структура данных в Neo4j

Скриншот реального графа

Cypher запросы для исследования

📊 Результаты

🎓 Возможные улучшения

1. Улучшение качества ответов

2. Расширение графа

3. Оптимизация поиска

4. Альтернативные LLM

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

🎉 Полная инструкция запуска

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

3. Настройка `.env`

1. `build_graph_simple.py` - Построение графа

2. `graphrag_qa.py` - GraphRAG система

3. `create_submission.py` - Генерация submission

4. `config.py` - Централизованная конфигурация