BYE-RAG

企业级 RAG 系统 + MCP 协议集成 | Production-Ready

基于 混合检索（Dense + Sparse） + RRF 融合 + MCP 协议 + 完整评估体系的生产级 RAG 解决方案。

✨ 核心亮点

🔍 混合检索: Dense (语义) + Sparse (BM25) + RRF 融合
🛠️ MCP 集成: 6 个工具函数，原生支持 Claude Desktop
📊 可视化面板: Streamlit Dashboard，6 个管理页面
🎯 评估系统: Ragas 集成，Golden Test Set，回归测试
🔄 链路追踪: Ingestion + Query 全流程可观测
🔌 可插拔架构: 支持多种 LLM、Embedding、向量库

📋 目录

🚀 快速开始

1. 克隆项目

git clone https://github.com/your-org/BYE-RAG.git
cd BYE-RAG

2. 安装依赖

# 创建虚拟环境（推荐）
python -m venv venv
source venv/bin/activate  # Linux/Mac
# 或
venv\Scripts\activate  # Windows

# 安装基础依赖
pip install -r requirements.txt

3. 配置 API Key

编辑 config/settings.yaml：

llm:
  provider: dashscope
  api_key: YOUR_DASHSCOPE_API_KEY  # 替换为你的 API Key
  model: qwen-max

embedding:
  provider: dashscope  
  api_key: YOUR_DASHSCOPE_API_KEY  # 替换为你的 API Key
  model: text-embedding-v3

milvus:
  uri: ./data/db/milvus.db  # 本地文件模式，无需额外安装
  collection_name: rag_collection

4. 启动 Dashboard（推荐）

python scripts/run_dashboard.py

访问 http://localhost:8501，开始使用可视化界面：

📥 上传和摄取文档
🔍 实时查询测试
📊 查看追踪数据
📝 运行评估

5. 或使用命令行

摄取文档

# 摄取单个文件
python scripts/ingest.py data/documents/report.pdf

# 摄取整个目录
python scripts/ingest.py data/documents/

查询

# 基础查询
python scripts/query.py "什么是机器学习？"

# 混合检索 + 重排序
python scripts/query.py "ML 是什么？" --rerank --top-k 10

📦 依赖说明

必需依赖

依赖	版本	用途
Python	≥3.10	运行环境
pymilvus	≥2.3.0	向量数据库客户端
dashscope	latest	通义千问 API
langchain	≥0.1.0	文本分块和工具
streamlit	≥1.30.0	Dashboard 框架
pandas	latest	数据处理

可选依赖

依赖	用途	安装命令
ragas	RAG 评估系统	`pip install ragas`
plotly	Dashboard 图表	`pip install plotly`
rank_bm25	BM25 稀疏编码	已包含在 requirements.txt

文档加载器依赖

依赖	支持格式	安装命令
PyMuPDF	PDF	已包含
python-magic	文件类型检测	已包含

安装所有依赖

# 基础 + 可选
pip install -r requirements.txt
pip install ragas plotly

# 仅安装必需依赖
pip install pymilvus dashscope langchain streamlit pandas PyMuPDF rank_bm25

⚙️ 配置指南

完整配置示例

config/settings.yaml：

# LLM 配置
llm:
  provider: dashscope      # dashscope / openai / azure / ollama
  api_key: YOUR_API_KEY
  model: qwen-max
  temperature: 0.7
  max_tokens: 2000

# Embedding 配置
embedding:
  provider: dashscope
  api_key: YOUR_API_KEY  
  model: text-embedding-v3
  dimension: 2048         # 向量维度

# Milvus 向量库配置
milvus:
  # 本地文件模式（推荐用于开发）
  uri: ./data/db/milvus.db
  
  # 或远程服务器模式
  # uri: http://localhost:19530
  # token: YOUR_TOKEN  # 可选
  
  collection_name: rag_collection
  metric_type: COSINE    # COSINE / L2 / IP

# BM25 稀疏编码配置
sparse_encoder:
  encoder_type: bm25
  k1: 1.5
  b: 0.75

# 混合检索配置
hybrid_search:
  rrf_k: 60              # RRF 融合参数
  alpha: 0.5             # Dense vs Sparse 权重

# 重排序配置
reranker:
  enabled: true
  model: cross-encoder/ms-marco-MiniLM-L-6-v2
  top_n: 5

# 评估配置
evaluation:
  ragas_enabled: true
  threshold: 0.05        # 回归测试阈值（5%）

环境变量配置

也可以通过环境变量配置（优先级高于 YAML）：

# LLM
export LLM_PROVIDER=dashscope
export LLM_API_KEY=your_key
export LLM_MODEL=qwen-max

# Embedding
export EMBEDDING_PROVIDER=dashscope
export EMBEDDING_API_KEY=your_key
export EMBEDDING_MODEL=text-embedding-v3

# Milvus
export MILVUS_URI=./data/db/milvus.db
export MILVUS_COLLECTION=rag_collection

多提供商支持

使用 OpenAI

llm:
  provider: openai
  api_key: YOUR_OPENAI_API_KEY
  model: gpt-4

embedding:
  provider: openai
  api_key: YOUR_OPENAI_API_KEY
  model: text-embedding-3-large

使用 Ollama（本地）

llm:
  provider: ollama
  base_url: http://localhost:11434
  model: llama2

embedding:
  provider: ollama
  base_url: http://localhost:11434
  model: nomic-embed-text

📖 使用方法

Dashboard 使用（推荐）

1. 系统总览

查看系统状态
快速统计信息
配置概览

2. 数据浏览器

浏览已摄取的文档
查看数据块内容
快速搜索

3. Ingestion 管理

上传文档（支持 PDF, MD, TXT）
批量摄取
查看摄取进度
配置 Transform 选项

4. Query 追踪

输入查询测试
查看检索结果
分析性能指标
实时追踪数据

5. Ingestion 追踪

查看摄取历史
分析耗时趋势
步骤详情

6. 评估面板

加载 Golden Test Set
运行 Ragas 评估
查看评估历史
回归测试

命令行使用

数据摄取

# 基础摄取
python scripts/ingest.py document.pdf

# 带选项
python scripts/ingest.py documents/ \
  --batch-size 50 \
  --enable-transform \
  --enable-trace

# 查看帮助
python scripts/ingest.py --help

查询

# 基础查询
python scripts/query.py "查询文本"

# 混合检索
python scripts/query.py "查询文本" \
  --top-k 10 \
  --rerank \
  --enable-trace

# 查看帮助
python scripts/query.py --help

MCP Server

# 启动 MCP Server
python scripts/run_mcp_server.py

# 配置到 Claude Desktop
# 编辑 claude_desktop_config.json:
{
  "mcpServers": {
    "rag-system": {
      "command": "python",
      "args": ["D:\\path\\to\\scripts\\run_mcp_server.py"],
      "cwd": "D:\\path\\to\\RAG-MCP-SERVER"
    }
  }
}

Python API 使用

数据摄取

from src.libs.loader import ComponentLoader
from src.ingestion.pipeline import IngestionPipeline
from src.config.settings import Settings

# 初始化
config = Settings()
loader = ComponentLoader(config)

llm = loader.get_llm()
embedding = loader.get_embedding()
vector_store = loader.get_vector_store()

# 创建 Pipeline
pipeline = IngestionPipeline(
    llm=llm,
    embedding=embedding,
    vector_store=vector_store,
    enable_transform=True,
    enable_trace=True
)

# 摄取文档
result = pipeline.process_file("document.pdf")
print(f"摄取完成: {result['chunks_count']} 个数据块")

混合检索

from src.retrieval.hybrid_search import HybridSearch
from src.retrieval.query_processor import QueryProcessor

# 初始化
processor = QueryProcessor(llm, embedding, sparse_encoder)
hybrid_search = HybridSearch(
    dense_retriever=dense_retriever,
    sparse_retriever=sparse_retriever,
    enable_trace=True
)

# 处理查询
query_result = processor.process("机器学习的应用")

# 混合检索
results = hybrid_search.search(
    dense_vector=query_result["dense_vector"],
    sparse_vector=query_result["sparse_vector"],
    top_k=10,
    rrf_k=60
)

# 结果
for doc in results:
    print(f"分数: {doc['score']:.3f}")
    print(f"内容: {doc['text'][:100]}...")

评估

from src.evaluation import EvalRunner, CompositeEvaluator, RagasEvaluator

# 初始化
ragas_eval = RagasEvaluator(llm=llm, embedding=embedding)
composite = CompositeEvaluator(ragas_evaluator=ragas_eval)
runner = EvalRunner(composite_evaluator=composite)

# 加载测试集
runner.load_test_set("data/test/golden_test_set.json")

# 运行评估
results = runner.run_evaluation(
    include_retrieval=True,
    include_generation=True
)

# 查看结果
summary = results["summary"]
print(f"检索 F1: {summary['retrieval']['avg_f1']:.3f}")
print(f"生成 Faithfulness: {summary['generation']['avg_faithfulness']:.3f}")

📊 系统架构

┌─────────────────────────────────────────┐
│    Claude Desktop (MCP Client)          │
└─────────────────┬───────────────────────┘
                  │ MCP Protocol
          ┌───────▼────────┐
          │  MCP Server    │  6 个工具函数
          │  (Tools API)   │
          └───────┬────────┘
                  │
    ┌─────────────┴──────────────┐
    │                            │
┌───▼────────┐          ┌────────▼────┐
│ Ingestion  │          │  Retrieval  │
│  Pipeline  │          │   Pipeline  │
│            │          │             │
│  Load      │          │  Query      │
│  Split     │          │  Dense      │
│  Transform │          │  Sparse     │
│  Encode    │          │  RRF Fusion │
│  Upsert    │          │  Rerank     │
└────┬───────┘          └─────┬───────┘
     │                        │
     │    ┌──────────────┐    │
     └────►  TraceContext ◄────┘
          │  (链路追踪)  │
          └──────┬───────┘
                 │
     ┌───────────▼────────────┐
     │  Milvus Vector Store   │
     │  Dense + Sparse Index  │
     └────────────────────────┘

🔥 核心特性

1. 混合检索 (Hybrid Search)

为什么需要混合检索？

Dense 检索擅长理解语义，但对关键词不敏感
Sparse 检索擅长精确匹配，但不理解语义
混合检索结合两者优势，提供更好的检索效果

工作原理：

用户查询
  ↓
QueryProcessor (查询改写)
  ↓
┌────────────┬────────────┐
│ Dense      │ Sparse     │
│ Retriever  │ Retriever  │
│ (Embedding)│ (BM25)     │
└─────┬──────┴──────┬─────┘
      │             │
      └──────┬──────┘
             ↓
       RRF Fusion (融合)
             ↓
       Reranker (重排序)
             ↓
         最终结果

2. MCP Server

6 个工具函数：

工具	功能	参数
`ingest_document`	摄取文档	file_path, enable_transform
`query`	混合检索查询	query_text, top_k, enable_rerank
`list_documents`	列出文档	-
`query_knowledge_hub`	知识库查询	collection_name, query
`list_collections`	向量库统计	-
`get_document_summary`	文档摘要	doc_id

Claude Desktop 集成：

配置 claude_desktop_config.json
重启 Claude Desktop
在对话中直接调用工具

示例：

用户: 请帮我摄取 report.pdf 文档
Claude: [自动调用 ingest_document 工具]

用户: 查询"机器学习的应用"
Claude: [自动调用 query 工具并返回结果]

3. Transform 层

可选的数据增强处理：

Transform	功能	何时使用
ChunkRefiner	优化分块边界	提升分块质量
MetadataEnricher	丰富元数据	需要更多上下文
ImageCaptioner	图片描述生成	处理包含图片的文档

启用方式：

pipeline = IngestionPipeline(
    llm=llm,
    embedding=embedding,
    vector_store=vector_store,
    enable_transform=True  # 启用 Transform
)

4. 链路追踪

自动追踪：

每个操作步骤
耗时统计（ms）
错误信息
中间结果

查看追踪：

from src.trace.trace_context import get_trace_recorder

recorder = get_trace_recorder()

# 获取所有追踪
traces = recorder.get_traces()

# 按类型过滤
query_traces = recorder.get_traces(trace_type="query")
ingestion_traces = recorder.get_traces(trace_type="ingestion")

# 查看详情
for trace in query_traces:
    print(f"查询: {trace['query']}")
    print(f"耗时: {trace['duration_ms']} ms")
    print(f"步骤: {len(trace['steps'])}")

5. 评估系统

Ragas 评估指标：

Faithfulness: 答案忠实于上下文
Answer Relevancy: 答案与问题相关性
Context Precision: 上下文精确度
Context Recall: 上下文召回率

Golden Test Set：

预定义的测试查询集合
用于回归测试
跟踪性能变化

使用示例：

# 创建测试集模板
runner.create_test_set_template("data/test/template.json")

# 加载测试集
runner.load_test_set("data/test/golden_test_set.json")

# 运行评估
results = runner.run_evaluation()

# 保存结果
runner.save_results("data/eval_results/eval_20260703.json")

🧪 测试指南

运行测试

# 所有单元测试
pytest tests/unit/ -v

# 特定模块
pytest tests/unit/evaluation/ -v
pytest tests/unit/retrieval/ -v

# E2E 测试
python tests/e2e/test_mcp_client.py
python tests/e2e/test_dashboard.py
python tests/e2e/test_e2e_acceptance.py

# 测试覆盖率
pytest --cov=src tests/unit/

验证脚本

# 完整功能验证
python scripts/test_all.py

# 接口一致性检查
python scripts/check_interface_consistency.py

❓ 常见问题

Q1: 如何切换到 OpenAI？

编辑 config/settings.yaml:

llm:
  provider: openai
  api_key: YOUR_OPENAI_KEY
  model: gpt-4

embedding:
  provider: openai
  api_key: YOUR_OPENAI_KEY
  model: text-embedding-3-large

Q2: 本地运行需要什么？

必需：

Python 3.10+
2GB 磁盘空间（向量数据库）
4GB RAM

可选：

GPU（加速 Embedding，非必需）

Q3: 如何使用远程 Milvus？

milvus:
  uri: http://your-milvus-server:19530
  token: YOUR_TOKEN  # 如果需要
  collection_name: rag_collection

Q4: Dashboard 启动失败？

检查：

是否安装 streamlit: pip install streamlit
端口是否被占用: lsof -i :8501
查看错误日志

Q5: API Key 配置不生效？

检查优先级：

环境变量（最高）
config/settings.yaml
默认值

确保环境变量名称正确：

export LLM_API_KEY=your_key
export EMBEDDING_API_KEY=your_key

Q6: 如何清理数据？

# 清理向量数据库
rm -rf data/db/

# 清理追踪数据
# 在 Dashboard 系统设置页面点击"清理追踪数据"

Q7: 性能优化建议？

摄取优化：

增大 batch_size: --batch-size 100
禁用 Transform（如不需要）: enable_transform=False

查询优化：

减少 top_k: --top-k 5
禁用重排序（如不需要）: 不使用 --rerank

Q8: 如何添加自定义 LLM？

# src/libs/llm/your_provider.py
from .base import BaseLLM

class YourLLM(BaseLLM):
    def generate(self, prompt: str, **kwargs) -> str:
        # 实现生成逻辑
        pass

然后在 ComponentLoader 中注册。

🛠️ 开发指南

项目结构

RAG-MCP-SERVER/
├── src/
│   ├── config/              # 配置管理
│   ├── libs/                # 可插拔组件
│   ├── ingestion/           # 数据摄取
│   ├── retrieval/           # 检索系统
│   ├── mcp_server/          # MCP Server
│   ├── trace/               # 链路追踪
│   ├── dashboard/           # Dashboard
│   └── evaluation/          # 评估系统
├── scripts/                 # 脚本
├── tests/                   # 测试
├── config/                  # 配置文件
├── data/                    # 数据目录
└── README.md

添加新的 LLM 提供商

# src/libs/llm/your_provider.py
from .base import BaseLLM

class YourLLM(BaseLLM):
    def __init__(self, config):
        self.api_key = config.get("your_provider.api_key")
        self.model = config.get("your_provider.model")
    
    def generate(self, prompt: str, **kwargs) -> str:
        # 实现生成逻辑
        response = your_api_call(prompt, **kwargs)
        return response.text

添加新的向量库

# src/libs/vector_store/your_store.py
from .base import BaseVectorStore

class YourVectorStore(BaseVectorStore):
    def upsert(self, ids, texts, vectors, metadatas):
        # 实现上传逻辑
        pass
    
    def search(self, vector, top_k, filters=None):
        # 实现检索逻辑
        pass

代码风格

遵循 PEP 8
类名：PascalCase
函数名：snake_case
使用类型注解
添加 docstring

📄 许可证

MIT License

🤝 贡献

欢迎 PR 和 Issue！

贡献指南

Fork 项目
创建特性分支 (git checkout -b feature/AmazingFeature)
提交更改 (git commit -m 'Add some AmazingFeature')
推送到分支 (git push origin feature/AmazingFeature)
开启 Pull Request

📧 联系

项目问题请提交 GitHub Issue
技术讨论欢迎在 Discussions 中交流

🙏 致谢

感谢以下开源项目：

Milvus - 向量数据库
Streamlit - Dashboard 框架
Ragas - RAG 评估
LangChain - 灵感来源

⭐ 如果这个项目对你有帮助，请给个 Star！

BYE-RAG

✨ 核心亮点

📋 目录

🚀 快速开始

1. 克隆项目

2. 安装依赖

3. 配置 API Key

4. 启动 Dashboard（推荐）

5. 或使用命令行

摄取文档

查询

📦 依赖说明

必需依赖

可选依赖

文档加载器依赖

安装所有依赖

⚙️ 配置指南

完整配置示例

环境变量配置

多提供商支持

使用 OpenAI

使用 Ollama（本地）

📖 使用方法

Dashboard 使用（推荐）

1. 系统总览

2. 数据浏览器

3. Ingestion 管理

4. Query 追踪

5. Ingestion 追踪

6. 评估面板

命令行使用

数据摄取

查询

MCP Server

Python API 使用

数据摄取

混合检索

评估

📊 系统架构

🔥 核心特性

1. 混合检索 (Hybrid Search)

2. MCP Server

3. Transform 层

4. 链路追踪

5. 评估系统

🧪 测试指南

运行测试

验证脚本

❓ 常见问题

Q1: 如何切换到 OpenAI？

Q2: 本地运行需要什么？

Q3: 如何使用远程 Milvus？

Q4: Dashboard 启动失败？

Q5: API Key 配置不生效？

Q6: 如何清理数据？

Q7: 性能优化建议？

Q8: 如何添加自定义 LLM？

🛠️ 开发指南

项目结构

添加新的 LLM 提供商

添加新的向量库

代码风格

📄 许可证

🤝 贡献

贡献指南

📧 联系

🙏 致谢

Latest Blog Posts

MCP directory API