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（ノートブック向け）

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つの診断指標を、1回のLLM呼び出しで取得できます。

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が証拠を含むチャンクを取得できなかった
生成時のハルシネーション	正しく取得したものの、情報を捏造した
不完全な回答	正しく取得したものの、回答が部分的だった
誤った解釈	正しく取得したものの、内容を誤解した

📓 デモ用ノートブック全文 — ミニRAGを構築し、詳細な指標でテストできます。

🎯 対象者と目的のデモ — 開発者、顧客、監査担当者などに合わせたQAを生成できます。

🏠 Ollamaローカルデモ — APIキー不要で、100％プライベートなRAG評価を実現します。

---

🏠 ローカルLLMで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 形式で複雑な構造化 QA ペア（質問＋回答＋根拠＋根拠箇所）を生成します。そのため、指示への追従性と JSON 出力能力に優れたモデルが必要です。

モデル	サイズ	最小 RAM	QA 品質	推奨用途
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 チャンク、チャンクごとに QA ペアを 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

RAGScore は、GPU／CPU の競合を避けるため、ローカルの 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 など

---

📊 出力形式

生成された QA ペア（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 エージェントとの統合

RAGScore は、AI エージェントと自動化のために設計されています。

# 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>	ドキュメントから QA ペアを生成
ragscore generate <paths> --audience <who>	特定の対象者向けに QA を調整
ragscore generate <paths> --purpose <why>	ドキュメントの目的に沿って QA を生成
ragscore evaluate <endpoint>	ゴールデン QA を使って 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 に送信	✅ ローカル
生成された QA	✅ ローカル	✅ ローカル
評価結果	✅ ローカル	✅ ローカル

コンプライアンス： 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 の使用では、テレメトリーは送信されません。

機能の利用状況を把握し、信頼性を向上させるために、限定的な匿名の運用メトリクスを収集します。ドキュメントの内容、プロンプト、QA テキスト、モデル出力、API キー、エンドポイント URL、ファイルパスは収集しません。

MCP モードで収集される情報：

• 呼び出された MCP ツール
• LLM プロバイダーとモデル名
• ragscore のバージョン、Python のバージョン、OS の種類
• 成功／失敗のステータス
• ランダムな匿名インストール ID

オプトアウト：

export RAGSCORE_NO_TELEMETRY=1

---

�� リンク

• GitHub • PyPI • Issues • Discussions

---

⭐ RAGScoreがお役に立ちましたら、GitHubでスターをお願いします！
RAGコミュニティのために❤️を込めて作りました