Чат-бот FAQ RAG — PeopleForce HR SaaS

Интеллектуальная система чат-бота для поддержки FAQ на основе Retrieval-Augmented Generation (RAG). Она обрабатывает документ с часто задаваемыми вопросами HR SaaS-компании, индексирует его в векторной базе данных и отвечает на вопросы пользователей, извлекая наиболее релевантные фрагменты документа для генерации точных ответов с помощью LLM. Это устраняет необходимость ручного поиска и снижает нагрузку на службу поддержки клиентов.

Архитектура RAG

┌──────────────────────────────────────────────────────────────────┐
│                    PIPELINE DE INDEXACIÓN                        │
│                                                                  │
│  faq_document.txt ──► Chunking ──► Embeddings ──► ChromaDB      │
│                     (300 chars,   (text-embedding   (persistente │
│                      50 overlap)   -3-small)         local)      │
└──────────────────────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────────────────────┐
│                    PIPELINE DE CONSULTA                          │
│                                                                  │
│  Pregunta ──► Embedding ──► k-NN Search ──► Contexto ──► LLM    │
│  del usuario   de query     (coseno,        (top-k       (gpt-4o │
│                              ChromaDB)       chunks)      -mini)  │
│                                                     │            │
│                                                     ▼            │
│                                              JSON Response       │
│                                        { user_question,          │
│                                          system_answer,          │
│                                          chunks_related }        │
└──────────────────────────────────────────────────────────────────┘

Related MCP server: RAG-MCP

Установка

1. Клонирование репозитория

git clone <repo-url>
cd kunz-mcp-project

2. Создание виртуального окружения и установка зависимостей

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

pip install -r requirements.txt

3. Настройка API Key

cp .env.example .env
# Edita .env y agrega tu clave de OpenAI:
# OPENAI_API_KEY=sk-...

Использование

Запуск конвейера индексации

python src/build_index.py

Это загружает data/faq_document.txt, разбивает его на фрагменты (chunks), генерирует эмбеддинги и сохраняет их в ChromaDB (data/chroma_db/).

Выполнение запроса

python src/query.py "¿Cuántos días de vacaciones me corresponden?"

Пример вывода JSON:

{
  "user_question": "¿Cuántos días de vacaciones me corresponden?",
  "system_answer": "Todos los colaboradores de tiempo completo tienen derecho a 15 días hábiles de vacaciones al año a partir de su primer aniversario. Con más de 3 años de antigüedad, se reciben 20 días hábiles, y con más de 7 años, 25 días hábiles.",
  "chunks_related": [
    {
      "text": "¿Cuántos días de vacaciones me corresponden?...",
      "metadata": {
        "chunk_index": 1,
        "total_chunks": 30,
        "source": "faq_document.txt"
      }
    }
  ]
}

Запуск агента оценки (Бонус)

python src/evaluator.py

Оценивает ответы в outputs/sample_queries.json и возвращает оценку 0-10 с обоснованием.

MCP-сервер (Model Context Protocol)

Проект включает src/mcp_server.py, который предоставляет RAG-конвейер как MCP-сервер, чтобы ИИ-агенты (Claude Desktop, Cursor, VS Code с Copilot и т. д.) могли вызывать инструменты напрямую.

Доступные инструменты

Предварительные требования

Убедитесь, что вы создали индекс перед запуском сервера:

python src/build_index.py

Вариант А — Запуск напрямую (режим stdio)

python src/mcp_server.py

Это запускает сервер в режиме stdio, совместимом с любым MCP-клиентом.

Вариант Б — Запуск с помощью MCP CLI

mcp run src/mcp_server.py

Вариант В — Интеграция с Claude Desktop

Отредактируйте файл конфигурации Claude Desktop:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hr-faq-rag": {
      "command": "python",
      "args": ["/ruta/absoluta/a/kunz-mcp-project/src/mcp_server.py"],
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Перезапустите Claude Desktop. Сервер появится как доступный инструмент в чате.

Вариант Г — Интеграция с Cursor или VS Code

Добавьте в конфигурацию MCP редактора (.cursor/mcp.json или settings.json):

{
  "mcpServers": {
    "hr-faq-rag": {
      "command": "python",
      "args": ["src/mcp_server.py"]
    }
  }
}

Примечание: сервер считывает OPENAI_API_KEY из файла .env проекта; если редактор не наследует окружение, передайте его явно в блоке "env", как показано в Варианте В.

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

kunz-mcp-project/
├── README.md               # Documentación del proyecto
├── requirements.txt        # Dependencias con versiones
├── .env.example            # Plantilla de variables de entorno
├── config.yaml             # Configuración del modelo, embeddings y RAG
├── data/
│   └── faq_document.txt    # Documento FAQ fuente (≥1000 palabras)
├── src/
│   ├── __init__.py
│   ├── build_index.py      # Pipeline de indexación (load → chunk → embed → store)
│   ├── query.py            # Pipeline de consulta (search → generate → JSON)
│   ├── evaluator.py        # Agente evaluador de calidad (bonus)
│   ├── mcp_server.py       # Servidor MCP (expone los tools vía FastMCP)
│   └── shared/
│       ├── __init__.py
│       ├── config_loader.py  # Carga config.yaml + .env
│       └── logger.py         # Logger con Rich (colores y formato)
└── outputs/
    └── sample_queries.json   # ≥3 ejemplos de consulta-respuesta

Технические решения

Стратегия разбиения (chunking)

Используется RecursiveCharacterTextSplitter с chunk_size=300 и chunk_overlap=50.

• Почему рекурсивный? Иерархические разделители (\n\n → \n → . → ) сохраняют естественные семантические границы текста (разделы, абзацы, предложения), создавая более связные фрагменты, чем при нарезке фиксированного размера.

• Почему 300 символов? Генерирует фрагменты по ~75-125 токенов, что находится в требуемом диапазоне 50-500 токенов. Более мелкие фрагменты улучшают точность векторного поиска за счет уменьшения семантического шума.

• Почему 50 символов перекрытия? Перекрытие обеспечивает непрерывность контекста между соседними фрагментами, предотвращая разрыв важной информации на границе.

Метод векторного поиска

Используется k-NN (k-ближайших соседей) с косинусным сходством по индексу HNSW в ChromaDB.

• Почему k-NN? Это самый прямой и предсказуемый метод поиска похожих векторов. ChromaDB оптимизирует его внутренне с помощью HNSW (Hierarchical Navigable Small World) для сублинейного поиска.

• Почему косинусное сходство? Косинусное сходство измеряет семантическое направление векторов, а не их величину. Это идеально подходит для нормализованных текстовых эмбеддингов, таких как OpenAI (text-embedding-3-small), где векторы с похожим значением указывают в одном направлении.

• Top-k = 3 возвращает от 2 до 5 фрагментов на запрос, что достаточно для обеспечения контекста без внесения шума.

Преимущества RAG

• Обновление без переобучения: Достаточно обновить исходный документ и переиндексировать его, без необходимости дорогостоящей донастройки (fine-tuning) LLM.

• Прозрачность: Каждый ответ включает использованные фрагменты (chunks_related), что позволяет проверить источник информации.

• Атрибуция: Метаданные каждого фрагмента (source, chunk_index) обеспечивают полную прослеживаемость ответа.

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

Файл config.yaml централизует все параметры: