Rag Eval Engine

RAG Eval Engine

Production-grade Retrieval-Augmented Generation with built-in evaluation harness

Features · Quick Start · Architecture · MCP · API · Config

______________________________________________________________________

这是什么？

RAG Eval发动机是一种 完整的RAG系统 这不仅仅是回答问题，而是不断地回答 衡量它对这些问题的回答程度。每个查询都经过一个完整的评估流程，对可信度、相关性和幻觉率进行评分，让您实时了解RAG质量。

问题： 大多数RAG系统都是黑匣子。你把文件塞进去，得到答案，并希望它们是好的。

解决方案： 将评估纳入管道本身。每个查询都会得到评分。每个指标都会随着时间的推移而跟踪。你可以准确地看到质量何时下降以及原因。

______________________________________________________________________

特性

混合检索

• 向量搜索 通过Qdrant（余弦相似度）
• 稀疏搜索 通过BM25关键字匹配
• 互逆排序融合 将两者与可配置的alpha权重合并
• 调整语义理解和关键字精度之间的平衡

文件摄入

• 支持 PDF、DOCX、TXT、Markdown，以及15+种代码文件类型
• 3组块策略：固定大小、递归（默认）、语义（句子边界感知）
• 可配置的块大小和重叠，具有令牌感知大小
• 带有进度跟踪的批量嵌入

语义查询缓存（FACT模式）

• 基于嵌入 Qdrant上的相似性匹配 _query_cache 收集
• 可配置阈值（默认0.95）和TTL（默认1小时）
• 使用延迟节省仪表板进行缓存命中跟踪
• 缓存命中率低于1000毫秒的响应

多提供商LLM路由

• 奥拉玛先 （qwen2.5编码器、llama3、mistral、deepseek等）
• 开放人工智能 （gpt-4o、gpt-4o-mini、o1、o3 mini）
• Anthropic 通过httpx连接（claude-3.5-onnet，claude-3-opus）——不依赖SDK
• 自动路由： claude-* → 人类学， gpt-* → OpenAI，其他→ 奥拉玛
• 每次查询成本跟踪 基于令牌的计算
• 流媒体SSE 对于所有三个提供商
• 使用令牌预算的上下文窗口管理

MCP服务器

• 将RAG暴露为 MCP工具 适用于克劳德代码/任何MCP客户端
• 工具： rag_query, rag_retrieve, rag_ingest_text, rag_collections, rag_metrics
• 基于stdio的JSON-RPC 2.0（标准MCP传输）
• 通过以下方式进行零配置注册 mcp-config.json

自适应检索（自学习）

• 自动调谐 基于历史评估分数的alpha和top-k
• 将检索参数与忠实度+相关性相关联
• 对alpha值进行分类，并为每个集合选择最佳配置
• 激活调优前至少需要10个查询

评价（差异化因素）

• 内联评估 对每个查询（轻量级模式）或对测试数据集进行全批评估
• 启发式回退 当法学硕士评委不在场时
• 所有结果都存储在SQLite中，并带有时间戳，用于时间序列分析
• 自动生成 文档中的测试问题

仪表板（6页）

• 深色模式 具有系统偏好检测和手动切换功能
• 响应式 --在带有可折叠侧边栏的移动设备上工作
• 实时流媒体 --LLM生成时显示手表令牌
• 骨架加载 闪烁状态替换所有加载微调器
• 吐司通知 用于成功/错误反馈
• CSV导出 用于评估指标
• 键盘快捷键 — Ctrl+K 为了聚焦查询，侧边栏中的导航提示
• 缓存命中徽章 查询响应的成本跟踪

截图

______________________________________________________________________

MCP服务器

RAG评估引擎可以用作MCP服务器，让Claude Code（或任何MCP客户端）直接查询您的知识库。

设置

添加到您的 .claude/settings.json 或项目 .mcp.json:

{
  "mcpServers": {
    "rag-eval-engine": {
      "command": "python",
      "args": ["-m", "src.mcp_server"],
      "cwd": "/path/to/rag-eval-engine"
    }
  }
}

可用工具

______________________________________________________________________

建筑

┌─────────────────────────────────────────────────────┐
│                   Next.js Dashboard                  │
│  Query | Documents | Retrieval | Eval | Test Sets    │
└──────────────────────┬──────────────────────────────┘
                       │ REST API + SSE
┌──────────────────────▼──────────────────────────────┐
│                  FastAPI Gateway                      │
│  /ingest  /query  /retrieve  /evaluate  /metrics     │
└───┬──────────┬──────────┬──────────┬────────────────┘
    │          │          │          │
┌───▼───┐ ┌───▼───┐ ┌───▼────┐ ┌───▼─────┐
│Ingest │ │Hybrid │ │Generate│ │Evaluate │
│Pipeline│ │Ranker │ │Engine  │ │Engine   │
└───┬───┘ └───┬───┘ └───┬────┘ └───┬─────┘
    │    ┌────┴────┐    │          │
    ▼    ▼         ▼    ▼          ▼
┌────────┐┌──────┐┌──────┐┌──────┐┌────────┐
│Qdrant  ││Vector││BM25  ││Ollama││SQLite  │
│VectorDB││Search││Index ││/LLM  ││Metrics │
└────────┘└──────┘└──────┘└──────┘└────────┘

______________________________________________________________________

技术栈

______________________________________________________________________

快速开始

先决条件

• Python 3.12+
• Node.js 20+
• 奥拉玛 在本地运行
• Qdrant 本地运行（或通过Docker）

1.启动基础设施

# Start Qdrant
docker run -d -p 6333:6333 -v qdrant_data:/qdrant/storage qdrant/qdrant

# Pull an LLM model
ollama pull qwen2.5-coder:14b

2.启动API

cp .env.example .env  # edit as needed
pip install -e ".[dev]"
uvicorn src.main:app --reload --port 8000

3.启动仪表板

cd dashboard
npm install
npm run dev

打开 http://localhost:3000

Docker Compose（全栈）

docker compose up -d

这启动了Qdrant、API和带有健康检查和资源限制的仪表板。Ollama一定在主机上跑步。

______________________________________________________________________

api参考

______________________________________________________________________

配置

所有设置都可以通过环境变量（前缀 RAG_)或 .env 文件：

# Infrastructure
RAG_QDRANT_URL=http://localhost:6333
RAG_OLLAMA_URL=http://localhost:11434

# Embeddings
RAG_EMBEDDING_MODEL=all-MiniLM-L6-v2      # or BAAI/bge-base-en-v1.5, text-embedding-3-small

# Chunking
RAG_CHUNKING_STRATEGY=recursive            # or fixed, semantic
RAG_CHUNK_SIZE=512                         # tokens per chunk
RAG_CHUNK_OVERLAP=50                       # overlap between chunks

# LLM
RAG_DEFAULT_MODEL=qwen2.5-coder:14b       # default LLM model

# Retrieval
RAG_HYBRID_ALPHA=0.7                       # 0=pure BM25, 1=pure vector
RAG_DEFAULT_TOP_K=5                        # chunks to retrieve

# Evaluation
RAG_EVAL_ON_QUERY=true                     # evaluate every query
RAG_EVAL_LIGHTWEIGHT=true                  # only faithfulness+relevance per query

# Cache
RAG_CACHE_ENABLED=true                     # enable semantic query cache
RAG_CACHE_THRESHOLD=0.95                   # similarity threshold for cache hits
RAG_CACHE_TTL_SECONDS=3600                 # cache entry time-to-live

# Cloud LLM (optional)
OPENAI_API_KEY=sk-...                      # enables gpt-4o, gpt-4o-mini
ANTHROPIC_API_KEY=sk-ant-...               # enables claude-3.5-sonnet, claude-3-opus

______________________________________________________________________

项目结构

rag-eval-engine/
├── src/
│   ├── main.py                    # FastAPI entry point + middleware
│   ├── config.py                  # Pydantic settings
│   ├── mcp_server.py              # MCP server (JSON-RPC over stdio)
│   ├── caching/
│   │   └── query_cache.py         # Semantic query cache (FACT pattern)
│   ├── ingestion/
│   │   ├── loader.py              # PDF, DOCX, text, code loading
│   │   ├── chunker.py             # 3 chunking strategies
│   │   └── embedder.py            # Local + OpenAI embeddings → Qdrant
│   ├── retrieval/
│   │   ├── vector_search.py       # Qdrant semantic search
│   │   ├── sparse_search.py       # BM25 keyword search
│   │   ├── hybrid_ranker.py       # Reciprocal Rank Fusion
│   │   └── auto_tune.py           # Adaptive retrieval param optimization
│   ├── generation/
│   │   ├── prompt_builder.py      # RAG prompt construction
│   │   ├── llm_client.py          # Ollama + OpenAI + Anthropic, streaming
│   │   └── cost_tracker.py        # Token-based cost calculation
│   ├── evaluation/
│   │   ├── metrics.py             # Faithfulness, relevance, hallucination scoring
│   │   ├── eval_pipeline.py       # Query pipeline + batch eval + cache
│   │   └── test_sets.py           # Test dataset management + auto-generation
│   ├── routes/
│   │   ├── ingest.py              # /api/ingest, /api/collections
│   │   ├── retrieve.py            # /api/retrieve
│   │   ├── query.py               # /api/query (+ SSE streaming)
│   │   └── evaluate.py            # /api/evaluate, /api/metrics, /api/test-sets
│   └── db/
│       └── models.py              # SQLite schema + migrations
├── dashboard/                     # Next.js 14 App Router
│   └── src/
│       ├── app/
│       │   ├── page.tsx           # Query Playground (streaming + eval + cache)
│       │   ├── documents/         # Document upload & management
│       │   ├── retrieval/         # Retrieval Explorer + auto-tune
│       │   ├── eval/              # Evaluation dashboard + cost + cache stats
│       │   ├── test-sets/         # Test set management & batch eval
│       │   └── settings/          # Configuration & status
│       ├── components/
│       │   ├── sidebar.tsx        # Navigation + keyboard shortcuts
│       │   ├── toast.tsx          # Toast notification system
│       │   └── skeleton.tsx       # Shimmer skeleton loading components
│       └── lib/
│           ├── api.ts             # Type-safe API client
│           └── utils.ts           # Formatting utilities
├── tests/                         # 68 tests
├── eval_datasets/                 # Sample Q&A pairs
├── sample_docs/                   # Sample PDFs for testing
├── mcp-config.json                # MCP server registration config
├── .github/workflows/ci.yml       # CI pipeline (lint, type check, test, build)
├── docker-compose.yml             # Full stack with health checks
├── Dockerfile                     # Python API container
└── pyproject.toml                 # Project metadata & deps

______________________________________________________________________

测试

pip install -e ".[dev]"
pytest tests/ -v

68次测试 涵盖：

• 分块策略（固定、递归、语义）——24个测试
• BM25索引和互逆秩融合——15个测试
• 评估指标评分与启发式——21项测试
• API端点集成-8项测试

______________________________________________________________________

关键设计决策

1. 奥拉玛先：专为当地法学硕士设计。无需API密钥即可开始。云提供商是可选的。
2. 混合检索：纯向量搜索会错过关键字匹配。纯BM25缺少语义意义。RRF为您提供两者。
3. Eval内置：不是单独的工具或管道。每个查询都可以选择在线评分。
4. 语义缓存：基于嵌入的缓存捕获语义相似的查询，而不仅仅是精确匹配。点击时响应低于1000毫秒。
5. 自学习检索：系统将检索参数与eval分数相关联，并随时间自动调整alpha/top-k。
6. SQLite用于度量：零配置，WAL模式用于并发访问。Metrics是一个只写大量追加的工作负载，非常适合SQLite。
7. 启发式回退：当LLM判断缓慢或不可用时，单词重叠启发式算法提供近似分数。
8. MCP集成：通过模型上下文协议将您的知识库作为AI编码助手的工具公开。

______________________________________________________________________

许可证

麻省理工学院