RAGScore

---

⚡ 2 行代码评估 RAG

# Step 1: Generate QA pairs from your docs
ragscore generate docs/

# Step 2: Evaluate your RAG system
ragscore evaluate http://localhost:8000/query

就这么简单。 立即获取准确率分数和错误的 QA 对。

============================================================
✅ EXCELLENT: 85/100 correct (85.0%)
Average Score: 4.20/5.0
============================================================

❌ 15 Incorrect Pairs:

  1. Q: "What is RAG?"
     Score: 2/5 - Factually incorrect

  2. Q: "How does retrieval work?"
     Score: 3/5 - Incomplete answer

---

🚀 快速开始

安装

pip install ragscore              # Core (works with Ollama)
pip install "ragscore[openai]"    # + OpenAI support
pip install "ragscore[notebook]"  # + Jupyter/Colab support
pip install "ragscore[all]"       # + All providers

已经安装？ 请保持更新，新版本会添加失败诊断和检索上下文捕获等功能：

pip install --upgrade ragscore

选项 1：Python API（适合 Notebook）

非常适合 Jupyter、Colab 和快速迭代。即时生成可视化结果。

from ragscore import quick_test

# 1. Audit your RAG in one line
result = quick_test(
    endpoint="http://localhost:8000/query",  # Your RAG API
    docs="docs/",                            # Your documents
    n=10,                                    # Number of test questions
)

# 1b. Tailored QA — target specific audiences
result = quick_test(
    endpoint="http://localhost:8000/query",
    docs="docs/",
    audience="developers",                   # Who asks the questions?
    purpose="api-integration",               # What's the document for?
)

# 2. See the report
result.plot()

# 3. Inspect failures
bad_rows = result.df[result.df['score'] < 3]
display(bad_rows[['question', 'rag_answer', 'reason']])

丰富的对象 API：

• result.accuracy - 准确率分数
• result.df - 包含所有结果的 Pandas DataFrame
• result.plot() - 3 面板可视化（设置 detailed=True 时为 4 面板）
• result.corrections - 待修正项目列表

选项 2：CLI（生产环境）

生成 QA 对

# Set API key (or use local Ollama - no key needed!)
export OPENAI_API_KEY="sk-..."

# Generate from any document
ragscore generate paper.pdf
ragscore generate docs/*.pdf --concurrency 10

# Tailored QA generation — target specific audiences
ragscore generate docs/ --audience developers --purpose faq
ragscore generate docs/ --audience customers --purpose "pre-sales"
ragscore generate docs/ --audience "compliance auditors" --purpose "security audit"

评估你的 RAG

# Point to your RAG endpoint
ragscore evaluate http://localhost:8000/query

# Custom options
ragscore evaluate http://api/ask --model gpt-4o --output results.json

---

🔬 多指标详细评估

不止于单一分数。添加 detailed=True，即可在一次大模型调用中获得每个答案的 5 个诊断维度。

result = quick_test(
    endpoint=my_rag,
    docs="docs/",
    n=10,
    detailed=True,  # ⭐ Enable multi-metric evaluation
)

# Inspect per-question metrics
display(result.df[[
    "question", "score", "correctness", "completeness",
    "relevance", "conciseness", "faithfulness"
]])

# Radar chart + 4-panel visualization
result.plot()

==================================================
✅ PASSED: 9/10 correct (90%)
Average Score: 4.3/5.0
Threshold: 70%
──────────────────────────────────────────────────
  Correctness: 4.5/5.0
  Completeness: 4.2/5.0
  Relevance: 4.8/5.0
  Conciseness: 4.1/5.0
  Faithfulness: 4.6/5.0
==================================================

指标	衡量内容	评分标准
正确性	与标准答案的语义匹配度	5 = 完全正确
完整性	是否涵盖所有关键要点	5 = 完全涵盖
相关性	是否回答了所提问题	5 = 完全切题
简洁性	是否重点明确、没有赘述	5 = 简洁准确
忠实度	是否存在捏造的说法	5 = 完全忠实

CLI：

ragscore evaluate http://localhost:8000/query --detailed

🔍 失败诊断（--diagnose）

当答案不合格时，--diagnose 会告诉你 原因：检索器漏检、生成器幻觉、答案不完整或理解错误：

ragscore evaluate http://localhost:8000/query --diagnose

🔍 Failure Diagnosis:
  Retriever Miss: 3 (42.9%)
  Generator Hallucination: 2 (28.6%)
  Incomplete Answer: 1 (14.3%)
  Wrong Interpretation: 1 (14.3%)

该功能会使用每个 QA 对生成时已有的 support_span，为评判模型提供依据上下文。与 --detailed 搭配使用可获得完整诊断：

ragscore evaluate http://localhost:8000/query --diagnose --detailed -o results.json

类别	含义
检索器漏检	RAG 未检索到包含证据的文本块
生成器幻觉	检索正确，但捏造了信息
答案不完整	检索正确，但答案不完整
理解错误	检索正确，但误解了内容

📓 完整演示 Notebook — 构建一个迷你 RAG，并使用详细指标进行测试。

🎯 受众与用途演示 — 为开发者、客户、审计员等生成定制 QA。

🏠 Ollama 本地演示 — 无需 API 密钥，实现 100% 私密的 RAG 评估。

---

🏠 使用本地大模型，实现 100% 隐私保护

# Use Ollama - no API keys, no cloud, 100% private
ollama pull llama3.1
ragscore generate confidential_docs/*.pdf
ragscore evaluate http://localhost:8000/query

非常适合： 医疗保健 🏥 • 法律 ⚖️ • 金融 🏦 • 研究 🔬

Ollama 模型推荐

RAGScore 会以 JSON 格式生成复杂的结构化问答对（问题 + 答案 + 推理依据 + 支持文本片段）。这需要具备出色指令遵循能力和 JSON 输出能力的模型。

模型	大小	最低内存	问答质量	推荐用途
llama3.1:70b	40GB	48GB VRAM	出色	GPU 服务（A100、L40）
qwen2.5:32b	18GB	24GB VRAM	出色	GPU 服务（A10、L20）
llama3.1:8b	4.7GB	8GB VRAM	良好	本地首选
qwen2.5:7b	4.4GB	8GB VRAM	良好	不错的本地替代方案
mistral:7b	4.1GB	8GB VRAM	良好	不错的本地替代方案
llama3.2:3b	2.0GB	4GB RAM	一般	仅用 CPU／测试
qwen2.5:1.5b	1.0GB	2GB RAM	较差	不推荐

最低建议使用 8B 及以上的模型。 较小的模型（1.5B–3B）生成的支持文本片段质量较低，处理较长文本块时可能超时。

Ollama 性能指南

# Recommended: 8B model with concurrency 2 for local machines
ollama pull llama3.1:8b
ragscore generate docs/ --provider ollama --model llama3.1:8b

# GPU server (A10/L20): larger model with higher concurrency
ollama pull qwen2.5:32b
ragscore generate docs/ --provider ollama --model qwen2.5:32b --concurrency 5

预期性能（28 个文本块，每个文本块 5 个问答对）：

硬件	模型	耗时	并发数
MacBook（CPU）	llama3.2:3b	~45 分钟	2
MacBook（CPU）	llama3.1:8b	~25 分钟	2
A10（24GB）	llama3.1:8b	~3–5 分钟	5
L20/L40（48GB）	qwen2.5:32b	~3–5 分钟	5
OpenAI API	gpt-4o-mini	~2 分钟	10

为避免 GPU/CPU 争用，RAGScore 会自动将本地 Ollama 的并发数降至 2。

---

🔌 支持的 LLM

提供方	设置	说明
Ollama	ollama serve	本地、免费、私密
OpenAI	export OPENAI_API_KEY="sk-..."	质量最佳
Anthropic	export ANTHROPIC_API_KEY="..."	长上下文
DashScope	export DASHSCOPE_API_KEY="..."	Qwen 模型
vLLM	export LLM_BASE_URL="..."	适用于生产环境
任何兼容 OpenAI 的服务	export LLM_BASE_URL="..."	Groq、Together 等

---

📊 输出格式

生成的问答对（output/generated_qas.jsonl）

{
  "id": "abc123",
  "question": "What is RAG?",
  "answer": "RAG (Retrieval-Augmented Generation) combines...",
  "rationale": "This is explicitly stated in the introduction...",
  "support_span": "RAG systems retrieve relevant documents...",
  "difficulty": "medium",
  "source_path": "docs/rag_intro.pdf"
}

评估结果（--output results.json）

{
  "summary": {
    "total": 100,
    "correct": 85,
    "incorrect": 15,
    "accuracy": 0.85,
    "avg_score": 4.2
  },
  "incorrect_pairs": [
    {
      "question": "What is RAG?",
      "golden_answer": "RAG combines retrieval with generation...",
      "rag_answer": "RAG is a database system.",
      "score": 2,
      "reason": "Factually incorrect - RAG is not a database"
    }
  ]
}

---

🧪 Python API

from ragscore import run_pipeline, run_evaluation

# Generate QA pairs
run_pipeline(paths=["docs/"], concurrency=10)

# Generate tailored QA pairs for specific audiences
run_pipeline(
    paths=["docs/"],
    audience="support engineers",
    purpose="fine-tuning a support chatbot",
)

# Evaluate RAG
results = run_evaluation(
    endpoint="http://localhost:8000/query",
    model="gpt-4o",  # LLM for judging
)
print(f"Accuracy: {results.accuracy:.1%}")

---

🤖 AI Agent 集成

RAGScore 专为 AI Agent 和自动化而设计：

# Structured CLI with predictable output
ragscore generate docs/ --concurrency 5
ragscore evaluate http://api/query --output results.json

# Exit codes: 0 = success, 1 = error
# JSON output for programmatic parsing

CLI 参考：

命令	说明
ragscore generate <paths>	根据文档生成问答对
ragscore generate <paths> --audience <who>	针对特定受众定制问答
ragscore generate <paths> --purpose <why>	根据文档用途生成问答
ragscore evaluate <endpoint>	根据标准问答评估 RAG
ragscore evaluate <endpoint> --detailed	多指标评估
ragscore evaluate <endpoint> --diagnose	对失败原因进行分类
ragscore --help	显示所有命令和选项
ragscore generate --help	显示 generate 选项
ragscore evaluate --help	显示 evaluate 选项

---

⚙️ 配置

无需配置。可选环境变量：

export RAGSCORE_CHUNK_SIZE=512          # Chunk size for documents
export RAGSCORE_QUESTIONS_PER_CHUNK=5   # QAs per chunk
export RAGSCORE_WORK_DIR=/path/to/dir   # Working directory

---

🔐 隐私与安全

数据	云端 LLM	本地 LLM
文档	✅ 本地	✅ 本地
文本块	⚠️ 发送给 LLM	✅ 本地
生成的问答	✅ 本地	✅ 本地
评估结果	✅ 本地	✅ 本地

合规性： GDPR ✅ • HIPAA ✅（使用本地 LLM）• SOC 2 ✅

---

🧪 开发

git clone https://github.com/HZYAI/RagScore.git
cd RagScore
pip install -e ".[dev,all]"
pytest

---

📡 遥测

RAGScore 仅在 MCP 服务模式（ragscore serve）下收集遥测数据。使用标准 CLI 和 Python API 时不会发送遥测数据。

我们会收集有限的匿名运行指标，以了解功能使用情况并提升可靠性。不会收集文档内容、提示词、问答文本、模型输出、API 密钥、端点 URL 或文件路径。

在 MCP 模式下收集：

• 调用的 MCP 工具
• LLM 提供方和模型名称
• ragscore 版本、Python 版本、操作系统类型
• 成功／失败状态
• 随机匿名安装 ID

退出收集：

export RAGSCORE_NO_TELEMETRY=1

---

🔗 链接

• GitHub • PyPI • 问题反馈 • 讨论

---

⭐ 如果 RAGScore 对你有帮助，请在 GitHub 上为我们点亮星标！
为 RAG 社区倾心打造 ❤️