Rag Playbook

RAG游戏手册

英语 | 泰语

______________________________________________________________________

英语

RAG（检索增强生成）实现和工具的全面集合，用于构建基于人工智能的文档搜索和问答系统。

项目

RAG MCP服务器

实现模型上下文协议（MCP）的生产就绪RAG服务器，可与Claude Code和其他兼容MCP的AI助手无缝集成。

主要特点：

• 多格式文档支持：PDF、DOCX、PPTX、XLSX、CSV、HTML、JSON、RTF、TXT
• 语义搜索：使用Qdrant矢量数据库的BGE-M3多语言嵌入
• 混合检索：向量相似度+BM25关键字搜索，采用互序融合（RRF）
• LLM驱动的增强功能:

- 用于查询扩展的HyDE（假设文档嵌入） - 查询增强和重写 - 自动摘要和标记 - 交叉编码器重新排序

• 安全强化：路径遍历保护、速率限制、输入验证、UUID验证
• 生产就绪：529多项自动化测试，全面的错误处理

快速开始

# Clone repository
git clone https://github.com/Nuttapon-Moohammadaree/rag-playbook.git
cd rag-playbook/rag-mcp-server

# Install dependencies
npm install

# Configure environment
cp .env.example .env
# Edit .env with your API keys

# Build and run
npm run build
npm run mcp

与Claude Code集成

添加到MCP配置(~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rag": {
      "command": "node",
      "args": ["/path/to/rag-mcp-server/dist/mcp/server.js"],
      "env": {
        "LITELLM_API_KEY": "your-api-key",
        "LITELLM_BASE_URL": "http://localhost:4000/v1",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

MCP工具参考

建筑

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code / MCP Client                  │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                       MCP Server Layer                       │
│    search │ ask │ documents │ llm-enhance                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                        Core Services                         │
│  Retrieval │ Ask │ Ingestion │ Chunking │ Embedding │ LLM   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│                      Storage Layer                           │
│              Qdrant (Vectors) │ SQLite (Metadata)           │
└─────────────────────────────────────────────────────────────┘

技术栈

______________________________________________________________________

泰语

用于创建文档搜索和人工智能查询的RAG（检索增强版）工具集

主要项目

RAG MCP服务器

生产级RAG服务器，具有实施模型上下文协议（MCP），可与云代码和其他支持MCP的AI助手一起使用。

主要特点：

• 支持多种文档格式：PDF、DOCX、PPTX、XLSX、CSV、HTML、JSON、RTF、TXT
• 语义搜索：使用多语言BGE-M3嵌入+Qdrant矢量数据库
• 混合检索：将矢量相似性+BM25关键字搜索与往复排名融合（RRF）相结合
• 由LLM补充:

- 用于扩展查询的Hyde（低光学文档嵌入） - 更新和重写查询 - 自动文档汇总 - 使用交叉编码器对结果进行重新排序

• 安全：路径保护、速率限制、输入检查、UUID检查
• 可用生产：529多个自动测试可用

安装方法

基本要求

• Node.js 18+或Bun
• Qdrant矢量数据库（使用Docker或云运行）
• LiteLLM兼容API端点（用于嵌入和LLM）

安装步骤

# 1. Clone repository
git clone https://github.com/Nuttapon-Moohammadaree/rag-playbook.git
cd rag-playbook/rag-mcp-server

# 2. ติดตั้ง dependencies
npm install

# 3. คัดลอกไฟล์ config
cp .env.example .env

# 4. แก้ไขไฟล์ .env ตามการตั้งค่าของคุณ
nano .env

# 5. Build โปรเจกต์
npm run build

# 6. รันเซิร์ฟเวอร์
npm run mcp

.env设置示例

# LiteLLM API Configuration
LITELLM_API_KEY=your-api-key-here
LITELLM_BASE_URL=http://localhost:4000/v1

# Embedding Model
EMBEDDING_MODEL=bge-m3
EMBEDDING_DIMENSION=1024

# Qdrant Vector Database
QDRANT_URL=http://localhost:6333
QDRANT_COLLECTION=documents

# LLM Features (ตั้งเป็น true เพื่อเปิดใช้งาน)
LLM_MODEL=gpt-4o-mini
AUTO_SUMMARY=false
AUTO_TAGS=false
HYDE_ENABLED=false
RERANKING_ENABLED=false

# Storage Path
SQLITE_PATH=./data/rag.db

使用云代码

MCP配置~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "rag": {
      "command": "node",
      "args": ["/path/to/rag-mcp-server/dist/mcp/server.js"],
      "env": {
        "LITELLM_API_KEY": "your-api-key",
        "LITELLM_BASE_URL": "http://localhost:4000/v1",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

设置云代码后，可以使用以下命令：

MCP工具

1. rag_search -搜索文档

使用语义搜索搜索文档

ค้นหาเอกสารเกี่ยวกับ "วิธีการตั้งค่า Docker"

参数：

2. rag_ask -问问题。

提出问题并从可搜索的上下文中获得答案

ถามคำถาม: "Docker Compose ใช้ยังไง?"

参数：

3. rag_index_document -从文件索引文档

Index ไฟล์ /path/to/document.pdf

参数：

4. rag_index_text -文本索引

Index ข้อความนี้เป็นเอกสารชื่อ "บันทึกการประชุม"

参数：

5. rag_list_documents -显示文档列表

แสดงเอกสารทั้งหมดที่ index แล้ว

参数：

6. rag_delete_document -删除文档

ลบเอกสาร ID: abc-123-def

参数：

7. rag_enhance_query -改进查询

ปรับปรุง query "docker" ให้ดีขึ้น

参数：

支持的文件格式

项目结构

rag-playbook/
├── rag-mcp-server/              # RAG MCP Server หลัก
│   ├── src/
│   │   ├── config/              # การตั้งค่า
│   │   ├── core/
│   │   │   ├── ask/             # บริการตอบคำถาม
│   │   │   ├── chunking/        # แบ่งข้อความเป็น chunks
│   │   │   ├── embedding/       # สร้าง embeddings
│   │   │   ├── ingestion/       # นำเข้าเอกสาร
│   │   │   │   └── parsers/     # ตัวแปลงไฟล์แต่ละประเภท
│   │   │   ├── llm/             # บริการ LLM (HyDE, summarizer)
│   │   │   ├── reranking/       # จัดอันดับผลลัพธ์ใหม่
│   │   │   └── retrieval/       # ค้นหาและดึงข้อมูล
│   │   ├── mcp/
│   │   │   ├── server.ts        # MCP server หลัก
│   │   │   └── tools/           # MCP tools แต่ละตัว
│   │   ├── storage/
│   │   │   ├── qdrant.ts        # เก็บ vectors
│   │   │   └── sqlite.ts        # เก็บ metadata
│   │   ├── types/               # TypeScript definitions
│   │   └── utils/               # utilities (security, cache)
│   ├── .env.example             # ตัวอย่างการตั้งค่า
│   ├── package.json
│   └── README.md                # เอกสารละเอียด
├── rag-mcp-complete-design.md   # เอกสารออกแบบต้นฉบับ
├── CLAUDE.md                    # การตั้งค่า Claude Code
└── README.md                    # ไฟล์นี้

安全功能

发展

cd rag-mcp-server

# รัน tests ทั้งหมด
npm test

# รัน tests พร้อม coverage
npm run test:coverage

# ตรวจสอบ TypeScript
npx tsc --noEmit

# Development mode (auto-rebuild)
npm run dev

测试统计

• 测试次数: 529+
• 测试文件: 23
• 覆盖区域:

- 核心服务（摄取、检索、询问） - 解析器（PDF、DOCX、PPTX等） - 存储（SQLite、Qdrant） - MCP工具 - 安全设施

______________________________________________________________________

许可证

麻省理工学院

作者

努塔蓬·穆哈马达雷

贡献

1. Fork存储库
2. 创建功能分支（git checkout -b feature/amazing-feature)
3. 承诺改变git commit -m 'Add amazing feature')
4. 推到分支git push origin feature/amazing-feature)
5. 打开拉请求