操作指南

本节中的每个指南都针对您作为有经验的用户在使用 Ragas 时可能遇到的实际问题提供了专注的解决方案。这些指南设计得简洁直接，为您的问题提供快速解决方案。我们假设您对 Ragas 的概念有基本了解且能够熟练使用。如果不是，请先浏览 快速入门 （Get Started）部分。

如何将 LLM 对齐为评判器

在本指南中，您将学习如何使用 Ragas 系统地评估和对齐作为评判器（LLM-as-judge）的大语言模型，使其与人类专家的判断保持一致。

• 构建可重用的评判器对齐评估管道
• 分析评判器与人类标签之间的不一致模式
• 迭代优化评判器提示词，提高与专家决策的一致性

为什么先对齐您的 LLM 评判器？

在运行评估实验之前，将您的 LLM 评判器对齐到特定用例非常重要。一个未对齐的评判器就像指向错误方向的指南针——您基于其指导做出的每一项改进都会让您离目标越来越远。将评判器对齐以匹配专家判断，确保您正在改进真正重要的东西。这个对齐步骤是可靠评估的基础。

真正的价值：审视您的数据

虽然构建一个对齐的 LLM 评判器很有用，但真正的业务价值来自于系统地分析您的数据并理解失败模式。评判器对齐过程迫使您深入检查边缘情况、明确评估标准，并揭示关于什么使响应好坏的洞察。将评判器视为扩展您分析能力的工具，而不是替代它。

设置您的环境

我们创建了一个简单的模块，您可以安装并运行，这样您就可以专注于理解评估过程，而不是创建应用程序。

uv pip install"ragas[examples]"export OPENAI_API_KEY="your-api-key-here"

完整代码
您可以在此处查看评判器对齐评估管道的完整代码。

了解数据集

我们将使用 EvalsBench 数据集，其中包含专家标注的 LLM 对业务问题的响应示例。每一行包括：

• question ：原始问题
• grading_notes ：一个好的响应应涵盖的关键点
• response ：LLM 生成的响应
• target ：人类专家的二元判断（通过/失败）

下载数据集：

# Create datasets folder and download the datasetmkdir-pdatasetscurl-odatasets/benchmark_df.csv https://raw.githubusercontent.com/vibrantlabsai/EvalsBench/main/data/benchmark_df.csv

加载并检查数据集：

importpandasaspdfromragasimportDatasetdefload_dataset(csv_path:str=None)->Dataset:"""Load annotated dataset with human judgments. Expected columns: question, grading_notes, response, target (pass/fail) """path=csv_pathor"datasets/benchmark_df.csv"df=pd.read_csv(path)dataset=Dataset(name="llm_judge_alignment",backend="local/csv")for_,rowindf.iterrows():dataset.append({"question":row["question"],"grading_notes":row["grading_notes"],"response":row["response"],"target":(row["target"]),})returndataset# Load the datasetdataset=load_dataset()print(f"Dataset loaded with{len(dataset)}samples")

数据集示例行：

数据集中包含同一问题的多个响应——有些通过，有些失败。这有助于评判器学习可接受和不可接受响应之间的细微差别。

理解您的基准真相
评判器对齐的质量完全取决于基准真相标签的质量。在生产场景中，请让主要领域专家参与——其判断对您的用例最关键的人（例如，心理健康 AI 的心理学家、法律 AI 的律师，或支持聊天机器人的客户服务总监）。他们一致的判断成为评判器对齐的黄金标准。您不需要标注每个示例——一个有代表性的样本（涵盖各种场景的 100-200 个示例）足以进行可靠的对齐。

理解评估方法

在本指南中，我们评估数据集中已有的响应，而不是生成新的响应。这种方法确保评估运行之间的结果可重现，让我们能够专注于评判器对齐而非响应生成。

评估工作流是：数据集行（问题 + 响应）→ 评判器 → 与人类目标比较

定义评估指标

对于评判器对齐，我们需要两个指标：

• 主要指标：accuracy（LLM 评判器） ——评估响应并返回通过/失败决策及原因。
• 对齐指标：judge_alignment ——检查评判器的决策是否与人类专家的 verdict 匹配。

设置评判器指标

定义一个简单的基线评判器指标，根据评分要点评估响应：

fromragas.metricsimportDiscreteMetric# Define the judge metric with a simple baseline promptaccuracy_metric=DiscreteMetric(name="accuracy",prompt="Check if the response contains points mentioned from the grading notes and return 'pass' or 'fail'.\n\nResponse: {response}\nGrading Notes: {grading_notes}",allowed_values=["pass","fail"],)

对齐指标

对齐指标用于比较评判器的决策与人类专家的 verdict：

fromragas.metrics.discreteimportdiscrete_metricfromragas.metrics.resultimportMetricResult@discrete_metric(name="judge_alignment",allowed_values=["pass","fail"])defjudge_alignment(judge_label:str,human_label:str)->MetricResult:"""Compare judge decision with human label."""judge=judge_label.strip().lower()human=human_label.strip().lower()ifjudge==human:returnMetricResult(value="pass",reason=f"Judge={judge}; Human={human}")returnMetricResult(value="fail",reason=f"Judge={judge}; Human={human}")

实验函数

实验函数编排完整的评估管道——使用评判器评估响应并测量对齐度：

fromtypingimportDict,Anyfromragasimportexperimentfromragas.metricsimportDiscreteMetricfromragas_examples.judge_alignmentimportjudge_alignment# The metric we created above@experiment()asyncdefjudge_experiment(row:Dict[str,Any],accuracy_metric:DiscreteMetric,llm,):"""Run complete evaluation: Judge → Compare with human."""# Step 1: Get response (in production, this is where you'd call your LLM app)# For this evaluation, we use pre-existing responses from the datasetapp_response=row["response"]# Step 2: Judge evaluates the responsejudge_score=awaitaccuracy_metric.ascore(question=row["question"],grading_notes=row["grading_notes"],response=app_response,llm=llm,)# Step 3: Compare judge decision with human targetalignment=judge_alignment.score(judge_label=judge_score.value,human_label=row["target"])return{**row,"judge_label":judge_score.value,"judge_reason":judge_score.reason,"alignment":alignment.value,"alignment_reason":alignment.reason,}

运行基线评估

执行评估管道并收集结果

importosfromopenaiimportAsyncOpenAIfromragas.llmsimportllm_factoryfromragas_examples.judge_alignmentimportload_dataset# Load datasetdataset=load_dataset()print(f"Dataset loaded with{len(dataset)}samples")# Initialize LLM clientopenai_client=AsyncOpenAI(api_key=os.environ.get("OPENAI_API_KEY"))llm=llm_factory("gpt-4o-mini",client=openai_client)# Run the experimentresults=awaitjudge_experiment.arun(dataset,name="judge_baseline_v1_gpt-4o-mini",accuracy_metric=accuracy_metric,llm=llm,)# Calculate alignment ratepassed=sum(1forrinresultsifr["alignment"]=="pass")total=len(results)print(f"✅ Baseline alignment:{passed}/{total}passed ({passed/total:.1%})")

📋 输出（基线 v1）

2025-10-0822:40:00,334-Loaded datasetwith160samples2025-10-0822:40:00,334-Initializing LLM clientwithmodel:gpt-4o-mini2025-10-0822:40:01,858-Running baseline evaluation...Running experiment:100%|████████████████████████|160/160[04:35<00:00,1.72s/it]2025-10-0822:44:37,149-✅ Baseline alignment:121/160passed(75.6%)

初始性能分析

评估生成全面的 CSV 结果，包含所有输入（ question 、 grading_notes 、 response ）、人类目标、评判器的决策及推理，以及对齐比较。

分析错误和失败模式

运行基线评估后，我们可以分析不一致模式，以了解评判器在哪些方面与人类专家存在分歧。

基线性能：75.6% 对齐度（160 个样本中 121 个正确）

让我们查看错误分布：
📋 代码

importpandasaspd# Load resultsdf=pd.read_csv('experiments/judge_baseline_v1_gpt-4o-mini.csv')# Analyze misalignmentsfalse_positives=len(df[(df['judge_label']=='pass')&(df['target']=='fail')])false_negatives=len(df[(df['judge_label']=='fail')&(df['target']=='pass')])print(f"False positives (judge too lenient):{false_positives}")print(f"False negatives (judge too strict):{false_negatives}")

📋 输出

Falsepositives(judge too lenient):39Falsenegatives(judge too strict):0

关键观察： 所有 39 个不一致（24.4%）都是假阳性——评判器判定为"通过"但人类专家判定为"失败"的情况。基线评判器过于宽松，遗漏了评分要点中缺失关键概念的响应。

失败案例示例

以下是评判器错误地通过了缺失关键概念的响应的示例：

错误的常见模式：

1. 评分要点中遗漏 1-2 个特定概念，同时涵盖其他概念
2. 隐含 vs 显式覆盖——评判器接受隐含概念，我们需要显式提及
3. 缩写术语未正确解码（例如，“mkt demand” = market demand（市场需求），“post-$” = post-money valuation（投后估值））
4. 关键标记被忽略——标有 * 或 ! 的要点通常是必不可少的

改进评判器提示词

基于错误分析，我们需要创建一个改进的提示词，使其能够：

1. 理解评分要点中使用的缩写
2. 识别关键标记（ * 、 ! 、特定数字）
3. 要求所有概念都存在，而不仅仅是大部分
4. 接受语义等价物（同一概念的不同表述）
5. 平衡严格性——不过于宽松也不过于严格

创建改进的 v2 提示词

定义具有全面评估标准的增强评判器指标：

fromragas.metricsimportDiscreteMetric# Define improved judge metric with enhanced evaluation criteriaaccuracy_metric_v2=DiscreteMetric(name="accuracy",prompt="""Evaluate if the response covers ALL the key concepts from the grading notes. Accept semantic equivalents but carefully check for missing concepts. ABBREVIATION GUIDE - decode these correctly: • Financial: val=valuation, post-$=post-money, rev=revenue, ARR/MRR=Annual/Monthly Recurring Revenue, COGS=Cost of Goods Sold, Opex=Operating Expenses, LTV=Lifetime Value, CAC=Customer Acquisition Cost • Business: mkt=market, reg/regs=regulation/regulatory, corp gov=corporate governance, integr=integration, S&M=Sales & Marketing, R&D=Research & Development, acq=acquisition • Technical: sys=system, elim=elimination, IP=Intellectual Property, TAM=Total Addressable Market, diff=differentiation • Metrics: NPS=Net Promoter Score, SROI=Social Return on Investment, proj=projection, cert=certification EVALUATION APPROACH: Step 1 - Parse grading notes into distinct concepts: - Separate by commas, semicolons, or line breaks - Each item is a concept that must be verified - Example: "*Gross Margin* >40%, CAC, LTV:CAC >3:1" = 3 concepts Step 2 - For each concept, check if it's addressed: - Accept semantic equivalents (e.g., "customer acquisition cost" = "CAC") - Accept implicit coverage when it's clear (e.g., "revenue forecasting" covers "historical vs forecasted rev") - Be flexible on exact numbers (e.g., "around 40%" acceptable for ">40%") Step 3 - Count missing concepts: - Missing 0 concepts = PASS - Missing 1+ concepts = FAIL (even one genuinely missing concept should fail) - Exception: If a long list (10+ items) has 1 very minor detail missing but all major points covered, use judgment CRITICAL RULES: 1. Do NOT require exact wording - "market demand" = "mkt demand" = "demand analysis" 2. Markers (* or !) mean important, not mandatory exact phrases: - "*traction evidence*" can be satisfied by discussing metrics, growth, or validation - "!unbiased assumptions" can be satisfied by discussing assumption methodology 3. Numbers should be mentioned but accept approximations: - "$47B to $10B" can be "$47 billion dropped to around $10 billion" - "LTV:CAC >3:1" can be "LTV to CAC ratio of at least 3 to 1" or "3x or higher" 4. FAIL only when concepts are genuinely absent: - If notes mention "liquidation prefs, anti-dilution, board seats" but response only has board seats → FAIL - If notes mention "scalability, tech debt, IP" but response never discusses technical risks → FAIL - If notes mention "GDPR compliance" and response never mentions GDPR or EU regulations → FAIL 5. PASS when ALL concepts present: - All concepts covered, even with different wording → PASS - Concepts addressed implicitly when clearly implied → PASS - Minor phrasing differences → PASS - One or more concepts genuinely absent → FAIL Response: {response} Grading Notes: {grading_notes} Are ALL distinct concepts from the grading notes covered in the response (accepting semantic equivalents and implicit coverage)?""",allowed_values=["pass","fail"],)

使用 LLM 优化提示词
在明确识别错误模式后，您可以使用 LLM 来优化提示词。您也可以使用 LLM 来识别错误，但请务必审查它们，确保与基准真相标签保持一致。您还可以使用编码智能体（如 Cursor、Claude Code）或框架（如 DSPy）来系统地优化评判器提示词。

使用改进后的提示词重新运行评估

使用增强的 v2 提示词再次运行评估（设置与基线相同，只需替换指标）：

# Use the same dataset and LLM setup from the baseline evaluation aboveresults=awaitjudge_experiment.arun(dataset,name="judge_accuracy_v2_gpt-4o-mini",accuracy_metric=accuracy_metric_v2,# ← Using improved v2 promptllm=llm,)passed=sum(1forrinresultsifr["alignment"]=="pass")total=len(results)print(f"✅ V2 alignment:{passed}/{total}passed ({passed/total:.1%})")

📋 输出（改进版 v2）

2025-10-0823:42:11,650-Loaded datasetwith160samples2025-10-0823:42:11,650-Initializing LLM clientwithmodel:gpt-4o-mini2025-10-0823:42:12,730-Running v2 evaluationwithimproved prompt...Running experiment:100%|██████████|160/160[04:39<00:00,1.75s/it]2025-10-0823:46:52,740-✅ V2 alignment:139/160passed(86.9%)

显著改进！对齐度从 75.6% 提升到了 86.9%。

如果需要进一步迭代：

• 分析剩余错误以识别模式（它们是假阳性还是假阴性？）
• 标注您的推理以及标签——这将有助于改进 LLM 评判器，您也可以将这些作为 few-shot 示例添加
• 使用更智能的模型——像 GPT-5 或 Claude 4.5 Sonnet 这样更强大的模型通常作为评判器表现更好
• 利用 AI 助手——本指南是使用 Cursor AI 智能体创建的，用于分析失败并迭代提示词。您可以使用 AI 编码智能体（Cursor、Claude 等）或框架（如 DSPy）来系统地优化评判器提示词
• 当对齐度在连续 2-3 次迭代中达到平稳状态或满足您的业务阈值时停止

您已完成的工作

您已使用 Ragas 构建了一个系统化的评估管道，它能够：

• 使用清晰的指标测量评判器与专家判断的对齐度
• 通过结构化错误分析识别失败模式
• 通过可重现的实验跟踪评估运行中的改进

这个对齐的评判器成为您进行可靠 AI 评估的基础。有了一个可以信任的评判器，您现在可以自信地评估您的 RAG 管道、智能体工作流或任何 LLM 应用程序——知道指标的改进转化为质量的真正提升。