ragas

Ragas 用 LLM 裁判给 RAG 链路打分的评测框架。

补充说明

Ragas 把检索质量、回答忠实度和相关性拆成可计算指标，适合在改动分块、embedding 或 prompt 后做回归。它不生成答案，只消费已有的 question、answer、contexts 和 reference。

版本差异很大：0.1 用 datasets.Dataset 和字符串指标名，0.2 起改为 EvaluationDataset / SingleTurnSample 与指标类。混用旧教程会直接 ImportError。

安装与启动

pip install -U ragas langchain-openai
export OPENAI_API_KEY="sk-..."

常用示例

用 OpenAI 裁判评测一个小型 RAG 数据集：

python - <<'PY'
from ragas import EvaluationDataset, SingleTurnSample, evaluate
from ragas.llms import LangchainLLMWrapper
from ragas.embeddings import LangchainEmbeddingsWrapper
from ragas.metrics import AnswerRelevancy, Faithfulness, LLMContextRecall
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

samples = [
    SingleTurnSample(
        user_input="磁盘满了怎么排查？",
        response="先用 df -h 看分区，再用 du 找大目录。",
        retrieved_contexts=["df -h 查看文件系统使用率；du -sh * 定位大目录。"],
        reference="df -h、du、lsof 配合定位磁盘占用。",
    ),
]
dataset = EvaluationDataset(samples=samples)

judge = LangchainLLMWrapper(ChatOpenAI(model="gpt-4o-mini", temperature=0))
embeddings = LangchainEmbeddingsWrapper(OpenAIEmbeddings(model="text-embedding-3-small"))

result = evaluate(dataset=dataset,
                  metrics=[Faithfulness(), AnswerRelevancy(), LLMContextRecall()],
                  llm=judge, embeddings=embeddings)
print(result)
result.to_pandas().to_csv("ragas-scores.csv", index=False)
PY

用本地 vLLM/SGLang 的 OpenAI 兼容接口当裁判，避免数据外发：

python - <<'PY'
from ragas import EvaluationDataset, SingleTurnSample, evaluate
from ragas.llms import LangchainLLMWrapper
from ragas.metrics import Faithfulness
from langchain_openai import ChatOpenAI

judge = LangchainLLMWrapper(ChatOpenAI(
    model="Qwen/Qwen2.5-72B-Instruct",
    base_url="http://localhost:8000/v1",
    api_key="EMPTY", temperature=0))
dataset = EvaluationDataset(samples=[SingleTurnSample(
    user_input="Pod OOMKilled 怎么办？",
    response="提高 memory limit，并排查内存泄漏。",
    retrieved_contexts=["OOMKilled 表示容器超过 memory limit 被杀。"])])
print(evaluate(dataset=dataset, metrics=[Faithfulness()], llm=judge))
PY

易错点与排错

• 旧教程的 from ragas import evaluate 加 datasets.Dataset 在新版本仍可能导入成功，但字段名不匹配，指标静默变成 NaN；先固定 ragas 版本。
• Faithfulness 必须有 response 和 retrieved_contexts；少了 contexts 会报错或跳过，不能只用 question/answer 打分。
• AnswerRelevancy 需要 embeddings，只传 LLM 会报缺参数；本地 embedding 服务还要关闭 OpenAI 的 token 长度预检。
• LLMContextRecall 依赖 reference，没有标准答案时改用无参考指标，不要拿空 reference 硬跑。
• 裁判模型不支持 JSON 模式或 function calling 时，结构化输出解析失败，分数为 NaN；换更强模型或在 vLLM 开 guided decoding。
• 每个样例通常触发多次裁判调用，限流和费用会随样本数放大；先跑 20 到 50 条，再扩到全量。
• 本地裁判并发过高会拖垮推理服务，导致超时被记为低分；限制并发并区分“评测失败”和“质量差”。
• 只看总分定位不到问题，导出 to_pandas() 逐条看 contexts 与 response，必要时打印裁判理由。

读完自测

合上页面，先回答，再展开对照。

1. Faithfulness 最少需要哪些字段？
2. 为什么本地模型当裁判经常得到 NaN？
3. AnswerRelevancy 为什么还需要 embedding 模型？

相关条目

• langchain
• ragflow
• deepeval
• lm-eval
• vllm