Руководство по использованию RAG системы

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

1. Подготовка окружения

# Клонируйте код в папку с вашим датасетом
# Структура должна быть:
# your_project/
# ├── Dataset_json/
# │   ├── Air Astana/
# │   ├── BRK/
# │   └── ...
# ├── src/
# ├── main.py
# └── ...

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

# Настройте API ключ
cp env_example .env
# Отредактируйте .env и добавьте ваш OPENAI_API_KEY

2. Автоматический быстрый старт

python quick_start.py

Этот скрипт:

• Проверит все требования
• Установит зависимости
• Обработает одну компанию для демонстрации
• Протестирует поисковую систему

3. Полная обработка датасета

# Обработать все компании
python main.py process --dataset-path "Dataset_json" --output-path "vector_dbs"

# Посмотреть статистику
python main.py stats --output-path "vector_dbs"

Подробное использование

Обработка данных по этапам

from src.dataset_processor import DatasetProcessor
from pathlib import Path

# Инициализация
processor = DatasetProcessor(
    dataset_path=Path("Dataset_json"),
    output_path=Path("vector_dbs")
)

# Получить список компаний
companies = processor.get_company_folders()
print(f"Найдено {len(companies)} компаний")

# Обработать одну компанию
success = processor.process_company(companies[0])

# Обработать все компании
results = processor.process_all_companies()

Поиск и получение контекста

from src.search_engine import RAGSearchEngine
from pathlib import Path

# Инициализация поисковой системы
search_engine = RAGSearchEngine(Path("vector_dbs"))

# Поиск по конкретной компании
results = search_engine.search_company(
    company_name="Air Astana",
    query="список аффилированных лиц",
    top_k=10
)

# Создание контекста для LLM
context = search_engine.create_context_for_llm(results)

# Поиск по всем компаниям
all_results = search_engine.search_all_companies(
    query="финансовые показатели",
    top_k_per_company=5
)

Интеграция с существующим кодом

См. examples/integration_example.py - полный пример адаптации существующего кода RAG-Challenge-2-main для работы с новой системой векторизации.

Структура результатов

Формат результата поиска

{
    'text': 'текст чанка',
    'grounding': [
        {
            'page': 101,  # Номер страницы
            'box': {...}  # Координаты на странице
        }
    ],
    'chunk_type': 'table',
    'chunk_id': 'uuid',
    'source_file': 'filename.json',
    'company_name': 'Air Astana',
    'similarity_score': 0.8542
}

Формат для системы ответов

{
    'file_name': 'filename.json',
    'page': 101,
    'text': 'релевантный текст',
    'company_name': 'Air Astana',
    'chunk_id': 'uuid',
    'chunk_type': 'table',
    'similarity_score': 0.8542
}

Управление лимитами API

Система автоматически управляет лимитами OpenAI API:

• TPM (Tokens Per Minute): 1,000,000
• RPM (Requests Per Minute): 3,000
• TPD (Tokens Per Day): 3,000,000

При достижении лимитов система автоматически ожидает.

Обработка больших чанков

Если чанк превышает лимит токенов (8192), система автоматически:

1. Разделяет его на части по предложениям
2. Создает отдельные векторы для каждой части
3. Сохраняет связь с оригинальным чанком
4. Помечает части специальными полями:
   • is_split_part: true
   • original_chunk_id: "original_uuid"
   • chunk_id: "original_uuid_part_0"

Мониторинг и отладка

Логи

Система создает подробные логи в файле rag_processing.log:

# Просмотр логов в реальном времени
tail -f rag_processing.log

# Поиск ошибок
grep ERROR rag_processing.log

Статистика обработки

# Общая статистика
python main.py stats --output-path vector_dbs

# Программная статистика
from src.dataset_processor import DatasetProcessor
processor = DatasetProcessor(Path("dummy"), Path("vector_dbs"))
stats = processor.get_company_stats()

Производительность

Время обработки (примерно)

• 1 компания (2 файла, ~1000 чанков): 5-10 минут
• 10 компаний: 1-2 часа
• Весь датасет (14 компаний): 2-4 часа

Время зависит от:

• Размера чанков
• Скорости интернета
• Лимитов API

Оптимизация

1. Батчинг: Обрабатывайте по 100 чанков за запрос
2. Параллелизм: Система автоматически управляет параллельными запросами
3. Кэширование: Уже обработанные компании пропускаются

Решение проблем

Частые ошибки

1. "API key not found"

   # Проверьте .env файл
   cat .env
   # Должен содержать: OPENAI_API_KEY=your_key_here

2. "Rate limit exceeded"

   • Система автоматически ожидает
   • Если проблема повторяется, уменьшите batch_size в конфигурации

3. "No chunks found"

   • Проверьте структуру JSON файлов
   • Убедитесь что есть поле "chunks"

4. "Company database not found"

   • Убедитесь что компания была обработана
   • Проверьте наличие файлов в vector_dbs/[company]/

Отладка

import logging
logging.basicConfig(level=logging.DEBUG)

# Включит подробные логи для отладки

Расширение функциональности

Добавление новых моделей эмбеддингов

# В src/vectorizer.py измените model_name
vectorizer = ChunkVectorizer(model_name="text-embedding-ada-002")

Кастомные фильтры поиска

# Добавьте фильтрацию по типу чанка
def search_tables_only(search_engine, company, query):
    results = search_engine.search_company(company, query, top_k=20)
    table_results = [r for r in results if r.get('chunk_type') == 'table']
    return table_results[:10]

Интеграция с другими LLM

# В examples/integration_example.py замените _generate_answer_with_llm
def _generate_answer_with_llm(self, question: str, context: str) -> str:
    # Ваша интеграция с Gemini, Claude, etc.
    pass

Поддержка

Для получения помощи:

1. Проверьте логи в rag_processing.log
2. Запустите python quick_start.py для диагностики
3. Изучите примеры в папке examples/