Skip to main content
Glama
hr-faq-rag
by fellgar246

FAQ RAG 聊天机器人 — PeopleForce HR SaaS

基于 检索增强生成 (RAG) 的智能 HR FAQ 支持聊天机器人系统。它处理 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,将其拆分为块,生成嵌入并将其存储在 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 服务器,以便 AI 代理(Claude Desktop、Cursor、VS Code with Copilot 等)可以直接调用这些工具。

可用工具

工具

描述

ask_hr_faq(question)

完整的 RAG 流水线:在 ChromaDB 中搜索并使用 GPT-4o-mini 生成回答

evaluate_rag_response(user_question, system_answer, chunks_related)

评估 RAG 回答的质量(0-10 分评分及理由)

rebuild_index()

在 ChromaDB 中重新索引 FAQ 文档(更新 FAQ 后很有用)

前提条件

在启动服务器之前,请确保已构建索引:

python src/build_index.py

选项 A — 直接运行 (stdio 模式)

python src/mcp_server.py

这将在 stdio 模式下启动服务器,兼容任何 MCP 客户端。

选项 B — 使用 MCP CLI 运行

mcp run src/mcp_server.py

选项 C — 与 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。该服务器将作为聊天中可用的工具出现。

选项 D — 与 Cursor 或 VS Code 集成

在编辑器的 MCP 配置 (.cursor/mcp.json 或 settings.json) 中添加:

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

注意:服务器从项目的 .env 文件中读取 OPENAI_API_KEY;如果编辑器没有继承该环境,请如选项 C 所示在 "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

技术决策

分块策略

使用 RecursiveCharacterTextSplitter,参数为 chunk_size=300 和 chunk_overlap=50。

  • 为什么使用递归? 分层分隔符 (\n\n → \n → . → ) 保留了文本的自然语义边界(章节、段落、句子),产生的块比固定大小切割更连贯。

  • 为什么是 300 个字符? 生成约 75-125 个 token 的块,在 50-500 个 token 的要求范围内。较小的块通过减少语义噪声提高了向量搜索的准确性。

  • 为什么重叠 50? 重叠确保了相邻块之间的上下文连续性,防止相关信息在边界处被切断。

向量搜索方法

在 ChromaDB 的 HNSW 索引上使用 k-NN (k-最近邻) 和余弦相似度。

  • 为什么使用 k-NN? 这是搜索相似向量最直接且可预测的方法。ChromaDB 在内部使用 HNSW (分层可导航小世界) 进行优化,以实现亚线性搜索。

  • 为什么使用余弦相似度? 余弦相似度衡量向量的语义方向,而不是其大小。它非常适合像 OpenAI (text-embedding-3-small) 这样归一化的文本嵌入,其中含义相似的向量指向相同的方向。

  • Top-k = 3 每次查询返回 2-5 个块,足以提供上下文而不会引入噪声。

RAG 的优势

  • 无需重新训练即可更新:只需更新源文档并重新索引,无需对 LLM 进行昂贵的微调。

  • 透明度:每个回答都包含所使用的块 (chunks_related),允许验证信息来源。

  • 归因:每个块的元数据 (source, chunk_index) 实现了回答的完全可追溯性。


配置

config.yaml 文件集中了所有参数:

参数

值

描述

model.name

gpt-4o-mini

用于生成的 LLM 模型

model.temperature

0.3

低温度以获得一致的回答

embedding.model

text-embedding-3-small

嵌入模型 (1536 维)

rag.chunk_size

300

块的最大字符大小

rag.chunk_overlap

50

块之间的重叠

rag.top_k

3

每次查询检索的块数

rag.collection

faq_hr_saas

ChromaDB 中的集合名称

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      An enterprise-ready MCP server that exposes a RAG tool for retrieving relevant context and metadata from a Qdrant vector database using natural language queries.
      2
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      A Retrieval Augmented Generation MCP server that ingests documents into a local vector database and enables semantic search queries.
      9
      -
    • F
      license
      Not graded
      quality
      C
      maintenance
      MCP server for a modular RAG system that enables natural language question answering over enterprise documents with intent-aware routing, adaptive retrieval, and citation-backed responses.
      -