Sdev

[Menzorg]

add rag and some fixes

[Menzorg]

@claude опиши основные места изменений, и проанализируй.

[claude]

Claude finished @Menzorg's task in 1m 56s —— View job

---

Анализ изменений PR #4

Задачи:

• Прочитать изменённые файлы
• Проанализировать основные места изменений
• Подготовить детальный обзор

---

Основные изменения

Этот PR добавляет полноценную RAG (Retrieval Augmented Generation) систему в проект и сопутствующие исправления. Всего 19 коммитов, 236 добавлений, 7 удалений в 9 файлах.

1. Реализация RAG-инструмента (src/engine/agents/tools/rag_tool.py)

Основной функционал:

• Интеграция с PGVector через langchain-postgres для векторного поиска
• Использование эмбеддингов nomic-embed-text-v2-moe (Ollama)
• Гибридный поиск: векторный + keyword-matching

Детали реализации:

# Векторный поиск (similarity_search, k=5)
docs = client.similarity_search(query, k=5)

# Keyword scoring с фильтрацией стоп-слов
keywords = set(query.split()) - set(RUSSIAN_STOP_WORDS)
for doc in docs:
    score += 1 if keyword in doc.page_content else 0

# Возврат топ-2 документов

Стоп-слова (строки 16-56):

• Добавлен обширный список русских стоп-слов (местоимения, предлоги, союзы, частицы)
• Цель: улучшить качество keyword-matching, исключив слова с низким семантическим весом

Логирование:

• Подробное логирование скоров и выбранных документов
• Полезно для отладки качества RAG-ответов

Проблемы:

1. ⚠️ Хардкод коллекции (строка 66): collection_name="law" зашит в код, несмотря на параметр collection
2. ⚠️ Хардкод URL эмбеддингов (строка 65): base_url='http://localhost:11434' не использует Config.LLM_BASE_URL
3. ⚠️ Низкий k: k=5 может быть мало для сложных запросов
4. ⚠️ Простой scoring: Подсчёт вхождений ключевых слов (score += 1) не учитывает TF-IDF или позицию слова

2. Конфигурация (src/engine/config.py)

Изменения (строки 31, 92-97):

VECTOR_PORT = os.getenv("VECTOR_PORT", "7432")  # Новый порт для pgvector

@staticmethod
def get_vector_dsn() -> str:
    """Отдельный DSN для векторной БД"""
    # Формирование connection string для pgvector

Анализ:

• ✅ Правильное разделение портов: основная БД (5432) vs векторная БД (7432)
• ✅ Переиспользование логики get_postgres_dsn() для экранирования паролей
• ⚠️ Возможна избыточность: если pgvector работает на той же БД, нужен ли отдельный порт?

3. Регистрация инструмента (src/engine/agents/tools/registry.py)

Изменения (строка 11):

from .rag_tool import rag_search

Проблема:

• ❌ Импорт без регистрации: инструмент импортирован, но НЕ зарегистрирован в ToolRegistry.__init__
• Это означает, что агенты не смогут использовать rag_search, пока кто-то явно не вызовет registry.register("rag_search", rag_search)

Где должна быть регистрация?
Судя по архитектуре, вероятно в src/engine/services/engine_service.py при инициализации ToolRegistry.

4. Промпт юриста (src/engine/prompts/lawyer.md)

Изменения:

Прежде чем ответить всегда проверяй факты на актуальность 
при помощи инструмента поиска в RAG. Там лежат различные 
кодексы РФ (такие как гражданский и жилищный).

Если в RAG ничего не найдено и ты отвечаешь за счёт только 
своих знаний - уточняй это в конце ответа.

Анализ:

• ✅ Правильная интеграция RAG в workflow агента
• ✅ Требование прозрачности (указывать источник ответа)
• ⚠️ Инструкция предполагает, что rag_search доступен агенту, но см. проблему с регистрацией выше

5. Зависимости (requirements.txt)

Добавлено:

langchain-postgres>=0.0.16  # PGVector через LangChain
psycopg2>=2.9.11            # PostgreSQL драйвер для pgvector

Анализ:

• ✅ langchain-postgres — современная альтернатива прямому pgvector
• ✅ psycopg2 — необходим для pgvector
• ⚠️ Нет версии для nomic-embed-text-v2-moe — предполагается, что Ollama установлен отдельно

6. Конфигурация окружения (.env.example)

Добавлено:

VECTOR_PORT=7432

Анализ:

• ✅ Документирует новый параметр
• ⚠️ Нет комментариев о том, что это за порт и зачем он нужен

7. Runner (src/engine/run.py)

Изменения (строка 35):

• Удалена пустая строка (косметика)

8. AI Service (src/engine/services/ai_service.py)

Изменения (строка 125):

max_tokens=256,  # Было: max_tokens=512

Анализ:

• ⚠️ Сокращение лимита токенов: с 512 до 256
• Влияние: AI-ответы будут короче
• Причина: вероятно, для ускорения или экономии ресурсов
• ⚠️ Может обрезать детальные юридические ответы с цитатами из RAG

9. Новый скрипт перезапуска (local_restart_v2.sh)

Функционал:

• Полный скрипт для graceful restart Engine
• Работа через screen с логированием
• Автоматические миграции перед стартом
• Health check после запуска
• Обработка зависших портов (fuser -k 8100/tcp)

Анализ:

• ✅ Продуманная обработка ошибок
• ✅ Логи в файл + вывод в консоль
• ✅ Полезные подсказки после запуска
• ⚠️ Хардкод пути к virtualenv (.rugpt/bin/activate) — должен соответствовать проекту

---

Критические замечания

🔴 Высокий приоритет

1. RAG-инструмент не зарегистрирован

   • rag_search импортирован в registry.py, но не добавлен в ToolRegistry
   • Эффект: агенты не смогут вызывать RAG
   • Fix: добавить registry.register("rag_search", rag_search) в инициализацию

2. Игнорируется параметр collection

   • rag_search(query, collection) принимает collection, но всегда использует "law"
   • Эффект: невозможно искать в других коллекциях
   • Fix: collection_name=collection or "law"

3. Хардкод конфигурации в rag_tool.py

   • base_url='http://localhost:11434' вместо Config.LLM_BASE_URL
   • Эффект: невозможно переключить Ollama на другой хост
   • Fix: использовать Config.LLM_BASE_URL

🟡 Средний приоритет

4. Сокращение max_tokens до 256

   • Может обрезать детальные RAG-ответы с цитатами из кодексов
   • Рекомендация: протестировать на реальных запросах или сделать конфигурируемым

5. Отсутствие обработки ошибок в rag_search

   • Нет try/except для подключения к БД или эмбеддингам
   • Эффект: падение агента при сбое pgvector/Ollama
   • Fix: обернуть в try/except с логированием

6. Простой keyword scoring

   • Подсчёт вхождений (score += 1) слишком примитивен
   • Улучшение: TF-IDF, взвешивание по позиции, учёт форм слова (лемматизация)

🟢 Низкий приоритет

7. Отсутствие документации RAG-настройки

   • .env.example не объясняет VECTOR_PORT
   • Fix: добавить комментарий

8. Дублирование логики DSN

   • get_postgres_dsn() и get_vector_dsn() почти идентичны
   • Улучшение: универсальный метод get_dsn(port)

---

Архитектурные решения

✅ Хорошие решения

1. Гибридный поиск (векторный + keyword)

   • Компенсирует слабости чисто векторного поиска
   • Особенно важно для юридических терминов

2. Разделение портов БД

   • Позволяет масштабировать векторную БД независимо

3. Список стоп-слов

   • Повышает точность keyword-matching для русского языка

4. Интеграция через LangChain

   • Стандартный интерфейс, легко заменить pgvector на другое решение

⚠️ Сомнительные решения

1. Хардкод коллекции "law"

   • Нарушает гибкость системы
   • Противоречит параметру функции

2. Топ-2 документа (строка 82)

   • Почему именно 2? Нет обоснования
   • Может быть недостаточно для сложных вопросов

3. Отсутствие кеширования

   • Одинаковые запросы будут повторно искать в БД
   • Рекомендация: добавить TTL-кеш для частых запросов

---

Итоговая оценка

Функциональность: RAG-система реализована корректно, но требует доработки перед production.

Качество кода: Средний уровень. Есть хардкод, отсутствует обработка ошибок.

Тестирование: Отсутствует (нет тестов в PR).

Документация: Минимальная (только промпт юриста).

Рекомендации перед мержем

1. ✅ Зарегистрировать rag_search в ToolRegistry
2. ✅ Убрать хардкод collection_name и base_url
3. ✅ Добавить обработку ошибок в rag_tool.py
4. ✅ Протестировать на реальных юридических запросах
5. ⚠️ Рассмотреть возврат max_tokens к 512 или сделать конфигурируемым

---

| Branch: sdev