This document curates the most common questions Shreya and I received while teaching 700+ engineers & PMs AI Evals. Warning: These are sharp opinions about what works in most cases. They are not universal truths. Use your judgment.本文档整理了我和 Shreya 在向 700 多名工程师和产品经理教授 AI 评估课程时收到的最常见问题。警告：这些内容包含关于在大多数情况下如何行之有效的个人观点，并非普世真理。请根据实际情况自行判断。
How to use this FAQ如何使用本常见问题解答（FAQ）
Browse the questions that interest you, or choose a guide below for a curated reading path through the FAQs and related articles.浏览你感兴趣的问题，或在下方选择一份指南，获取针对 FAQ 和相关文章的精选阅读路径。
| Where are you? | This sounds like me |
|---|---|
| I’m new to evals | I’ve heard the term, but I’m not sure what evals involve or whether I need them. |
| I don’t know what to test | I’m building an AI product, but I haven’t figured out which failures to measure or what good performance looks like. |
| I don’t trust my eval scores | We have evals, but the scores don’t match our judgment of the outputs, or tests pass while users still encounter problems. |
| My product feels too hard to evaluate | Our outputs are subjective, long, or involve many steps. Even a knowledgeable person has trouble deciding whether they’re right. |
| Evals take too much time or money | We’re spending too much effort reviewing outputs, maintaining tests, or running evaluators. |
All questions所有问题
Browse all questions by section.按章节浏览所有问题。
- Getting Started & Fundamentals
- Q: What are AI Evals?问：什么是 AI 评估？
- Q: What is a trace?问：什么是追踪（Trace）？
- Q: What’s a minimum viable evaluation setup?问：什么是最小可行性评估方案？
- Q: How much of my development budget should I allocate to evals?问：我应该在评估上投入多少开发预算？
- Q: Will today’s evaluation methods still be relevant in 5-10 years given how fast AI is changing?问：鉴于 AI 发展如此迅速，现在的评估方法在 5-10 年后还有意义吗？
- Q: How do I make the case for investing in evaluations to my team?问：如何向团队证明投资评估的必要性？
- Error Analysis & Data Collection
- Q: Why is "error analysis" so important in AI evals, and how is it performed?问：为什么“错误分析”在 AI 评估中如此重要，它是如何执行的？
- Q: Do I need a reference answer or rubric before annotating data?问：在标注数据之前，我需要准备参考答案或评分标准吗？
- Q: Should I record problems that aren’t the model’s fault?问：我是否应该记录那些并非模型导致的错误？
- Q: How many examples do I need for an eval?问：进行评估需要多少个示例？
- Q: How do I surface problematic traces for review beyond user feedback?问：除了用户反馈外，我该如何发现有问题的追踪以供审查？
- Q: How often should I re-run error analysis on my production system?问：我应该多久对生产系统进行一次错误分析？
- Q: What should I do when my "gold" eval dataset becomes stale?问：当我的“黄金”评估数据集过期时，我该怎么办？
- Q: What is the best approach for generating synthetic data?问：生成合成数据的最佳方法是什么？
- Q: Are there scenarios where synthetic data may not be reliable?问：是否存在合成数据可能不可靠的情况？
- Q: How can I do evals when traces contain sensitive data?问：当追踪包含敏感数据时，我该如何进行评估？
- Q: How do I approach evaluation when my system handles diverse user queries?问：当我的系统处理各种各样的用户查询时，我该如何进行评估？
- Q: How can I efficiently sample production traces for review?问：我该如何高效地采样生产环境的追踪以进行审查？
- Evaluation Design & Methodology
- Q: Why do you recommend binary (pass/fail) evaluations instead of 1-5 ratings (Likert scales)?问：为什么你们建议使用二元（通过/失败）评估，而不是 1-5 分评分（李克特量表）？
- Q: Should I practice eval-driven development?问：我应该实践“评估驱动开发”吗？
- Q: Should I build automated evaluators for every failure mode I find?问：我应该为我发现的每种故障模式都建立自动化评估器吗？
- Q: Should I use "ready-to-use" evaluation metrics?问：我应该使用“现成”的评估指标吗？
- Q: Are similarity metrics (BERTScore, ROUGE, etc.) useful for evaluating LLM outputs?问：相似度指标（BERTScore、ROUGE 等）对评估大模型输出有用吗？
- Q: Can I use the same model for both the main task and evaluation?问：我可以使用同一个模型同时进行主要任务和评估吗？
- Q: How much context should I give a LLM judge?问：我应该给大模型裁判多少上下文信息？
- Q: How do we evaluate a model’s ability to express uncertainty or "know what it doesn’t know"?问：我们如何评估模型表达不确定性或“知道自己不知道什么”的能力？
- Human Annotation & Process
- Q: How many people should annotate my LLM outputs?问：应该有多少人来标注我的大模型输出？
- Q: How can I make AI outputs easier for people to evaluate?问：我该如何让 AI 的输出更易于人工评估？
- Q: Should product managers and engineers collaborate on error analysis? How?问：产品经理和工程师应该合作进行错误分析吗？如何合作？
- Q: Can I help with evals if I’m not a domain expert?问：如果我不是领域专家，我能参与评估工作吗？
- Q: Should I outsource annotation & labeling to a third party?问：我应该将标注工作外包给第三方吗？
- Q: How do you review a trace that is really large?问：如何审查非常大的追踪？
- Q: What parts of evals can be automated with LLMs?问：评估的哪些部分可以用大模型实现自动化？
- Q: Should I stop writing prompts manually in favor of automated tools?问：我是否应该停止手动编写提示词，转而使用自动化工具？
- Tools & Infrastructure
- Q: Should I build a custom annotation tool or use something off-the-shelf?问：我应该构建自定义标注工具还是使用现成的产品？
- Q: What makes a good custom interface for reviewing LLM outputs?问：什么样的自定义界面适合审查大模型输出？
- Q: What gaps in eval tooling should I be prepared to fill myself?问：我应该准备好填补评估工具链中的哪些空白？
- Q: What’s your favorite eval vendor?问：你们最喜欢的评估供应商是谁？
- Q: How should I version and manage prompts?问：我应该如何对提示词进行版本管理？
- Q: What should go in the system prompt vs. the user prompt?问：系统提示词（System Prompt）和用户提示词（User Prompt）应该分别包含什么内容？
- Production & Deployment
- Q: How are evaluations used differently in CI/CD vs. monitoring production?问：在 CI/CD 中使用评估与在生产环境监控中使用评估有什么区别？
- Q: What’s the difference between guardrails & evaluators?问：护栏（Guardrails）和评估器（Evaluators）有什么区别？
- Q: Can my evaluators also be used to automatically fix or correct outputs in production?问：我的评估器可以同时用于自动修复或纠正生产环境中的输出吗？
- Q: How much time should I spend on model selection?问：我应该花多少时间在模型选择上？
- Domain-Specific Applications
- Q: Is RAG dead?问：RAG（检索增强生成）过时了吗？
- Q: How should I approach evaluating my RAG system?问：我应该如何评估我的 RAG 系统？
- Q: How do I choose the right chunk size for my document processing tasks?问：我该如何为文档处理任务选择合适的块（Chunk）大小？
- Q: How do I debug multi-turn conversation traces?问：我该如何调试多轮对话的追踪？
- Q: How do I evaluate sessions with human handoffs?问：我该如何评估包含人工介入的会话？
- Q: How do I evaluate complex multi-step workflows?问：我该如何评估复杂的多步骤工作流？
- Q: How do I evaluate agentic workflows?问：我该如何评估智能体工作流？
Getting Started & Fundamentals入门与基础
Q: What are AI Evals?
AI evals are tests that tell you whether an AI system is doing what you want. They give your team feedback when the product drifts from user needs or business goals. The failures they catch also become data you can use to improve the system.AI 评估是用来判断 AI 系统是否在执行你预期任务的测试。当产品偏离用户需求或业务目标时，它们会为你的团队提供反馈。它们所捕获的故障也会成为你改进系统的数据。
More formally, evaluation is the systematic measurement of quality. Each eval checks one behavior on relevant examples and returns a score or structured review. Most AI products need several evals because they can fail in different ways.更正式地说，评估是对质量的系统性测量。每次评估都会在相关示例上检查一种行为，并返回分数或结构化的审查结果。大多数 AI 产品需要多种评估，因为它们可能以不同的方式失败。
When you hear the word “evals,” it usually refers to one of two things: model benchmarks or product evals.当你听到“评估”这个词时，它通常指的是以下两者之一：模型基准测试或产品评估。
Model benchmarks模型基准测试
Model benchmarks compare general-purpose models on shared tasks. Model providers publish these benchmark results when they release new models. Common examples include GPQA Diamond for graduate-level science reasoning, Terminal-Bench for agents doing complex work in command-line environments, and MMLU for knowledge and reasoning across a wide range of subjects. These scores can help you choose a promising model as a starting point. To assess quality on your own tasks you need product evals, which we discuss next.模型基准测试是在共享任务上比较通用模型。模型提供商在发布新模型时会公布这些基准测试结果。常见的例子包括用于研究生水平科学推理的 GPQA Diamond、用于命令行环境中执行复杂工作的智能体测试 Terminal-Bench，以及跨广泛学科知识和推理的 MMLU。这些分数可以帮助你选择一个有前景的模型作为起点。要评估你自己任务的质量，你需要产品评估，我们将在下文中讨论。
Product evals产品评估
Product evals measure whether your specific AI product does what you want it to do. They turn your judgment about what a good product experience looks like into metrics you can track. Product evals encompass all components of your product, including the model, prompts, retrieval, tools, and application code. This flavor of evals are focused on capturing failures that matter to users and the business.产品评估衡量的是你的特定 AI 产品是否在做你想做的事。它们将你对什么是良好产品体验的判断转化为可以追踪的指标。产品评估涵盖了你产品的所有组件，包括模型、提示词、检索、工具和应用程序代码。这类评估专注于捕捉对用户和业务重要的故障。
Consider an order-cancellation agent. Its product evals might check whether it selected the correct order and waited for the cancellation tool to succeed before telling the user the order was canceled. A high score on GPQA Diamond or Terminal-Bench gives you little information on this, because those benchmarks don’t have access to your systems.以一个订单取消智能体为例。它的产品评估可能会检查它是否选择了正确的订单，并在告诉用户订单已取消之前等待取消工具执行成功。GPQA Diamond 或 Terminal-Bench 的高分对你几乎没有参考价值，因为这些基准测试无法访问你的系统。
There are several mechanisms you can use to implement product evals, including code assertions, human review, LLM judges, and online experiments. The right method depends on the failure being measured, and is discussed in greater detail in this series.你可以使用多种机制来实现产品评估，包括代码断言、人工审查、大模型裁判和在线实验。正确的方法取决于所测量的故障类型，本系列文章将对此进行更详细的讨论。
In the rest of the AI Evals FAQ, we focus on product evals. It starts with analyzing traces to discover real failure modes. We then turn important failures into targeted evals and use the results to guide changes. Finally, rerunning the evals tells us whether the system improved.在 AI 评估 FAQ 的其余部分，我们将重点关注产品评估。它始于分析追踪以发现真实的故障模式。然后，我们将重要的故障转化为有针对性的评估，并利用结果指导改进。最后，重新运行评估以确认系统是否有所改进。
Where to start with evals评估入门指南
If you are completely new to product-specific evals, see these posts:如果你是特定产品评估的完全新手，请参阅以下文章：
| Guide | What it covers | |
|---|---|---|
 |
Part 1: Your AI Product Needs Evals | Build a domain-specific evaluation system with scoped tests, trace review, human evaluation, and experiments. |
 |
Part 2: Using LLM-as-a-Judge For Evaluation: A Complete Guide | Capture a domain expert’s judgment, automate it with an LLM judge, and validate the judge against human labels. |
 |
Part 3: A Field Guide to Rapidly Improving AI Products | Use error analysis, realistic data, and trustworthy evals to run a sustained product-improvement loop. |
↗ Focus view↗ 焦点视图
Q: What is a trace?
A trace is the complete record of all actions, messages, tool calls, and data retrievals from a single initial user query through to the final response. It includes every step across all agents, tools, and system components in a session: multiple user messages, assistant responses, retrieved documents, and intermediate tool interactions.追踪（Trace）是从初始用户查询到最终响应的完整记录，包含所有操作、消息、工具调用和数据检索。它涵盖了会话中所有智能体、工具和系统组件的每一步：多条用户消息、助手响应、检索到的文档以及中间的工具交互。
Note on terminology: Different observability vendors use varying definitions of traces and spans. Alex Strick van Linschoten’s analysis highlights these differences (screenshot below):术语说明：不同的可观测性供应商对追踪（Trace）和跨度（Span）的定义各不相同。Alex Strick van Linschoten 的分析强调了这些差异（见下图）：
Q: What’s a minimum viable evaluation setup?
Start with error analysis, not infrastructure. Spend 30 minutes manually reviewing 20-50 LLM outputs whenever you make significant changes. Use one domain expert who understands your users as your quality decision maker (a “benevolent dictator”).从错误分析开始，而不是基础设施。每当你做出重大变更时，花 30 分钟手动审查 20-50 个大模型输出。找一位了解你用户的领域专家作为你的质量决策者（即“仁慈的独裁者”）。
Use a notebook to review traces and analyze data, or build your own custom annotation interface with an AI coding assistant like Claude or Codex. Either way, you can write arbitrary code, visualize data, and iterate quickly. The video below shows a simple annotation interface built inside a notebook.使用笔记本（Notebook）来审查追踪并分析数据，或者利用 Claude 或 Codex 等 AI 编码助手构建你自己的自定义标注界面。无论哪种方式，你都可以编写任意代码、可视化数据并快速迭代。下面的视频展示了一个在笔记本内构建的简单标注界面。
Watch “Build Your Own Eval Tools With Notebooks!” on YouTube在 YouTube 上观看“用笔记本构建你自己的评估工具！”
Q: How much of my development budget should I allocate to evals?
It’s important to recognize that evaluation is part of the development process rather than a distinct line item, similar to how debugging is part of software development.重要的是要认识到，评估是开发过程的一部分，而不是一个单独的项目，就像调试是软件开发的一部分一样。
You should always be doing error analysis. When you discover issues through error analysis, many will be straightforward bugs you’ll fix immediately. These fixes don’t require separate evaluation infrastructure as they’re just part of development.你应该始终进行错误分析。当你通过错误分析发现问题时，许多问题会是你可以立即修复的直接 Bug。这些修复不需要单独的评估基础设施，因为它们只是开发的一部分。
The decision to build automated evaluators comes down to cost-benefit analysis. If you can catch an error with a simple assertion or regex check, the cost is minimal and probably worth it. But if you need to align an LLM-as-judge evaluator, consider whether the failure mode warrants that investment.构建自动化评估器的决定归结为成本效益分析。如果你能用简单的断言或正则表达式检查来捕获错误，那么成本极低且很值得。但如果你需要对齐一个“大模型作为裁判”的评估器，请考虑该故障模式是否值得那种投资。
In the projects we’ve worked on, we’ve spent 60-80% of our development time on error analysis and evaluation. Expect most of your effort to go toward understanding failures (i.e. looking at data) rather than building automated checks.在我们参与的项目中，我们将 60-80% 的开发时间花在了错误分析和评估上。预计你的大部分精力将用于理解故障（即查看数据），而不是构建自动化检查。
Be wary of optimizing for high eval pass rates. If you’re passing 100% of your evals, you’re likely not challenging your system enough. A 70% pass rate might indicate a more meaningful evaluation that’s actually stress-testing your application. Focus on evals that help you catch real issues, not ones that make your metrics look good.警惕为了追求高评估通过率而进行优化。如果你的评估通过率为 100%，你很可能没有对系统提出足够的挑战。70% 的通过率可能意味着一项更有意义的评估，它正在真正对你的应用程序进行压力测试。专注于那些能帮你捕获真实问题的评估，而不是那些让你的指标看起来漂亮的评估。
Q: Will today’s evaluation methods still be relevant in 5-10 years given how fast AI is changing?
Yes. Even with perfect models, you still need to verify they’re solving the right problem. The need for systematic error analysis, domain-specific testing, and monitoring will still be important.是的。即使模型完美，你仍然需要验证它们是否解决了正确的问题。系统性错误分析、领域特定测试和监控的需求依然至关重要。
Today’s prompt engineering tricks might become obsolete, but you’ll still need to understand failure modes. Additionally, a LLM cannot read your mind, and research shows that people need to observe the LLM’s behavior in order to properly externalize their requirements.今天的提示词工程技巧可能会过时，但你仍然需要了解故障模式。此外，大模型无法读懂你的心思，研究表明人们需要观察大模型的行为才能正确地梳理和表达他们的需求。
For deeper perspective on this debate, see these two viewpoints: “The model is the product” versus “The model is NOT the product”.关于这场辩论的更深层次视角，请参阅这两个观点：“模型即产品”与“模型不是产品”。
Q: How do I make the case for investing in evaluations to my team?
Don’t try to sell your team on “evals”. Instead, show them what you find when you look at the data.不要试图向你的团队推销“评估”。相反，向他们展示你在查看数据时所发现的问题。
Start by doing the error analysis yourself. Look at 50 to 100 real user conversations and find the most common ways the product is failing. Use these findings to tell a story with data.从亲自进行错误分析开始。查看 50 到 100 个真实的用户对话，找出产品失败的最常见方式。利用这些发现，用数据讲一个故事。
Present your team with:向你的团队展示：
- A list of the top failure modes you discovered.你发现的最主要故障模式列表。
- Metrics showing how often high-impact errors are happening.显示高影响力错误发生频率的指标。
- Surprising ways that users are interacting with the product.用户与产品交互中令人惊讶的方式。
- Reports on the bugs you found and fixed, framed as “prevented production issues”.关于你发现并修复的 Bug 的报告，将其描述为“预防了生产环境问题”。
Frame evaluation as part of development, not optional testing. Keep a running log of the errors you catch, what you learned, the fix, and the likely impact you avoided. Share it weekly or monthly. A concrete report such as “we caught 47 issues before users saw them” makes the value easier to see than an abstract pitch about evals.将评估视为开发的一部分，而不是可选的测试。保留一份你捕获的错误、所学到的知识、修复方案以及所避免的潜在影响的运行日志。每周或每月分享一次。一份具体的报告，例如“我们在用户看到问题之前捕获了 47 个问题”，比关于评估的抽象推销更容易让人看到价值。
This approach builds trust. Don’t just show dashboards and metrics; tell the story of what you’re finding in the data. By narrating your findings, you teach the team what you’re learning, providing immediate value. When you fix an issue, show how the error rate for that specific problem went down. Soon, your team will see the progress and ask how you’re doing it. Let results instead of methods lead the conversation.这种方法可以建立信任。不要只展示仪表盘和指标；要讲述你在数据中发现的故事。通过叙述你的发现，你教会了团队你所学到的东西，从而提供了直接的价值。当你修复一个问题时，展示该特定问题的错误率是如何下降的。很快，你的团队就会看到进展并询问你是如何做到的。让结果而不是方法来主导对话。
This is similar to classic machine learning projects, where outcomes are speculative and progress is bounded by iterating on experiments. In this situation, it’s important that you share the learnings from each experiment to show progress and encourage investment.这类似于经典的机器学习项目，其结果具有推测性，进度受限于实验的迭代。在这种情况下，分享每次实验的学习成果以展示进展并鼓励投资非常重要。
Error Analysis & Data Collection错误分析与数据收集
Q: Why is "error analysis" so important in AI evals, and how is it performed?
Error analysis is the most important activity in evals. Error analysis helps you decide what evals to write in the first place. It allows you to identify failure modes unique to your application and data. The process involves:错误分析是评估中最重要的一环。错误分析能帮你决定首先编写哪些评估。它允许你识别应用程序和数据特有的故障模式。该过程包括：
1. Creating a Dataset1. 创建数据集
Gathering representative traces of user interactions with the LLM. If you do not have any data, you can generate synthetic data to get started.收集用户与大模型交互的代表性追踪。如果你没有任何数据，可以生成合成数据来开始。
2. Open Coding2. 开放编码（Open Coding）
Human annotator(s) (ideally a benevolent dictator) review and write open-ended notes about traces, noting any issues. This process is akin to “journaling” and is adapted from qualitative research methodologies. Start by annotating at least 30 traces yourself before reviewing suggestions from an agent. When beginning, it is recommended to focus on noting the first failure observed in a trace, as upstream errors can cause downstream issues, though you can also tag all independent failures if feasible. A domain expert should be performing this step.人工标注者（理想情况下是一位仁慈的独裁者）审查并写下关于追踪的开放式笔记，记录任何问题。这个过程类似于“写日记”，改编自定性研究方法。在审查智能体的建议之前，先自己标注至少 30 个追踪。开始时，建议重点记录追踪中观察到的第一个故障，因为上游错误可能导致下游问题，尽管如果可行，你也可以标记所有独立的故障。此步骤应由领域专家执行。
3. Axial Coding3. 轴向编码（Axial Coding）
Categorize the open-ended notes into a “failure taxonomy.” In other words, group similar failures into distinct categories. Axial coding is the most important step. At the end, count the number of failures in each category. You can use an LLM to help with this step.将开放式笔记分类为“故障分类法”。换句话说，将相似的故障归入不同的类别。轴向编码是最重要的一步。最后，统计每个类别中的故障数量。你可以使用大模型来协助这一步。
4. Iterative Refinement4. 迭代完善
Have your agent cluster the data and choose a diverse initial sample. After your first 30 annotations, let it search the remaining traces for likely instances of the failures you described. Accept or reject its suggestions and keep iterating until you reach theoretical saturation, meaning new reviews stop revealing failure modes or changing existing ones.让你的智能体对数据进行聚类并选择一个多样化的初始样本。在你完成前 30 个标注后，让它在剩余的追踪中搜索你所描述的故障的可能实例。接受或拒绝它的建议，并不断迭代，直到达到理论饱和，这意味着新的审查不再揭示故障模式或改变现有的故障模式。
A working pool of roughly 100 diverse traces is a useful guardrail for this human-agent loop. The agent can focus your attention on the most informative traces, so you no longer have to read all 100 sequentially. See how many examples you need for each kind of eval for the full breakdown.一个包含大约 100 个多样化追踪的工作池是这种人机循环的有用护栏。智能体可以将你的注意力集中在最有信息量的追踪上，这样你就不必按顺序阅读所有 100 个。请参阅每种评估所需的示例数量以获取完整细分。
You should frequently revisit this process. There are advanced ways to sample data more efficiently, like clustering, sorting by user feedback, and sorting by high probability failure patterns. Over time, you’ll develop a “nose” for where to look for failures in your data.你应该经常重温这个过程。有一些高级方法可以更有效地采样数据，例如聚类、按用户反馈排序以及按高概率故障模式排序。随着时间的推移，你将培养出一种在数据中寻找故障的“嗅觉”。
Do not skip error analysis. It ensures that the evaluation metrics you develop are supported by real application behaviors instead of counter-productive generic metrics (which most platforms nudge you to use). For examples of how error analysis can be helpful, see this video, or this blog post.不要跳过错误分析。它确保你开发的评估指标是由真实的应用程序行为支持的，而不是由适得其反的通用指标（大多数平台会引导你使用这些指标）支持的。有关错误分析如何提供帮助的示例，请参阅此视频或此博客文章。
Here is a visualization of the error analysis process by one of our students, Pawel Huryn - including how it fits into the overall evaluation process:这是我们的学生 Pawel Huryn 对错误分析过程的可视化——包括它如何融入整个评估过程：
Q: Do I need a reference answer or rubric before annotating data?
No. Writing a rubric before you review examples can get in the way.不需要。在审查示例之前编写评分标准可能会适得其反。
Let’s get some definitions out of the way:让我们先明确一些定义：
- A reference answer is an example of a correct response.参考答案是一个正确响应的示例。
- A rubric is a set of criteria for judging a response, such as whether it follows the refund policy.评分标准是一组评判响应的标准，例如它是否遵循退款政策。
Both can help, but treat your initial expectations as a starting point that you will revise.两者都有帮助，但请将你最初的期望视为一个起点，你之后会对其进行修订。
It’s often better to wait until you’ve reviewed some examples before developing a detailed rubric. Reviewers can become so focused on checking each item that they overlook problems outside the rubric. It’s important to give reviewers room to notice things you didn’t anticipate. This change in what you consider good is called “criteria drift”.通常最好等到你审查了一些示例后再制定详细的评分标准。审查者可能会过于专注于检查每一项，以至于忽略了评分标准之外的问题。给审查者留出空间来注意到你未预料到的事情很重要。这种对“什么是好”的判断标准的变化被称为“标准漂移”（Criteria Drift）。
For example, let’s say you have a support agent that handles refunds and it escalates refunds to a human per your policy. You might only realize that the process is frustrating for the user after reading a few interactions. Don’t underestimate the degree of criteria drift that will happen as you review examples!例如，假设你有一个处理退款的客服智能体，并且它根据你的政策将退款升级给人工。你可能只有在阅读了几次交互后才意识到这个过程对用户来说很令人沮丧。不要低估在审查示例时会发生的标准漂移程度！
We recommend using error analysis to systematically review examples and decide what might belong in the rubric. This involves writing open-ended notes about what looks wrong, then group similar notes to see which problems recur. See this live demo for a walkthrough.我们建议使用错误分析来系统地审查示例，并决定什么可能属于评分标准。这包括写下关于什么看起来不对的开放式笔记，然后将相似的笔记分组以查看哪些问题反复出现。查看此现场演示以获取完整演练。
After doing error analysis, you can write a better rubric informed by user and application behavior. You should periodically do error analysis to make sure your rubric is current.在进行错误分析后，你可以根据用户和应用程序行为编写更好的评分标准。你应该定期进行错误分析，以确保你的评分标准是最新的。
Q: Should I record problems that aren’t the model’s fault?
Yes. When reviewing interactions, write down anything that makes the product less useful. This includes missing or broken features that have nothing to do with the model. Additionally, don’t focus on why the error occurred, as that should only come after you prioritize which issues to fix.是的。在审查交互时，写下任何使产品变得不那么有用的东西。这包括与模型无关的缺失或损坏的功能。此外，不要专注于错误发生的原因，因为这应该只在你确定了优先修复哪些问题之后才进行。
For example, a support agent might tell a customer that an order has shipped without providing a tracking link. Even if your AI doesn’t have the ability to fetch a tracking link, record that problem. A prerequisite to building evals is to identify and prioritize which issues to fix through error analysis. Some of these issues may end up being engineering or design issues that don’t need an automated evaluator, but they are still important to fix!例如，客服智能体可能会告诉客户订单已发货，但没有提供追踪链接。即使你的 AI 没有能力获取追踪链接，也要记录下这个问题。构建评估的前提是通过错误分析识别并优先处理需要修复的问题。其中一些问题最终可能成为不需要自动化评估器的工程或设计问题，但它们仍然很重要！
Lastly, we’ve found that deferring root-cause analysis and focusing on problems allows you to write higher-quality annotations while looking at more data.最后，我们发现推迟根本原因分析并专注于问题本身，可以让你在查看更多数据的同时写出更高质量的标注。
Q: How many examples do I need for an eval?
Building evals is a pipeline, and each stage needs a different amount of data. We describe these stages below:构建评估是一个流水线，每个阶段都需要不同数量的数据。我们将在下面描述这些阶段：
| Stage | What to do |
|---|---|
| 1. Review the application | Read traces and write down the ways your application fails. This process is called error discovery. Start with 100 diverse traces and annotate at least the first 30 yourself. |
| 2. Create and validate evaluators | Choose between two evaluator types. Use a code-based eval when an objective rule can identify the failure. Include Pass and Fail examples for every condition and important edge case. Use an LLM judge when the failure requires human judgment. Label 100 to 200 examples for each failure mode. |
| 3. Build a repeatable eval set | Collect examples that represent important workflows and confirmed failures. Run this set when you change your application. These sets often grow to 100 or more examples. |
Stage 1: Review traces to find failures阶段 1：审查追踪以发现故障
A trace is a complete record of one user session with your application. Ask a coding agent to help you sample the initial pool so it covers different users and workflows. Our evals plugin can help with sampling and build an annotation interface for your traces.追踪是用户与你的应用程序进行一次会话的完整记录。请编码智能体协助你采样初始池，以便它涵盖不同的用户和工作流。我们的评估插件可以帮助采样并为你的追踪构建标注界面。
Review at least 30 traces yourself亲自审查至少 30 个追踪
We recommend annotating at least 30 traces with a process called error discovery yourself before asking the agent to suggest failures. Write free-text notes about anything that seems wrong from the user’s perspective. These examples give the agent a concrete record of your judgment.我们建议你自己标注至少 30 个追踪，采用一种称为“错误发现”的过程，然后再要求智能体建议故障。写下关于从用户角度看任何看起来不对的自由文本笔记。这些示例为智能体提供了你判断的具体记录。
Keep this first pass manual. If the agent starts suggesting problems too early, its guesses can bias your judgment. You may miss failures that depend on product context or your definition of a good user experience.保持第一轮手动进行。如果智能体过早开始建议问题，它的猜测可能会偏向你的判断。你可能会错过依赖于产品上下文或你对良好用户体验定义的故障。
After 30 traces, ask the agent to search the remaining pool for similar examples. Review every suggestion yourself. Accept or reject each one and correct the agent when it misunderstands your criteria.在 30 个追踪之后，让智能体在剩余的池中搜索类似的示例。亲自审查每一个建议。接受或拒绝每一个，并在智能体误解你的标准时纠正它。
When to stop何时停止
Continue until new traces stop revealing failure modes or changing existing ones. Qualitative researchers call this theoretical saturation. We recommend reviewing at least 100 traces. Continue past 100 while you are still learning.继续进行，直到新的追踪不再揭示故障模式或改变现有的故障模式。定性研究人员称之为“理论饱和”。我们建议审查至少 100 个追踪。在仍有收获的情况下，继续超过 100 个。
If you want to see the process done live, watch the live walkthrough. The video shows how Shreya Shankar uses an agent to review traces quickly while keeping a human in charge of the failure criteria.如果你想看现场演示，请观看现场演练。视频展示了 Shreya Shankar 如何使用智能体快速审查追踪，同时让人类负责故障标准。
This review produces a failure taxonomy, which is a list of the specific ways your application fails. Use that taxonomy to decide which evaluators to build.此审查会产生一个故障分类法，即你的应用程序发生故障的具体方式列表。使用该分类法来决定构建哪些评估器。
Stage 2: Create and validate evaluators阶段 2：创建并验证评估器
Choose an evaluator for each important failure mode. The evaluator type determines how many labeled examples you need. Code-based evals work for objective rules. LLM judges work for failures that require human judgment.为每个重要的故障模式选择一个评估器。评估器类型决定了你需要多少标注示例。代码评估适用于客观规则。大模型裁判适用于需要人工判断的故障。
Code-based evals need coverage代码评估需要覆盖率
Use a code-based eval when a deterministic rule can identify the failure. Examples include checking whether JSON parses or whether a tool call uses the correct arguments.当确定性规则可以识别故障时，使用基于代码的评估。示例包括检查 JSON 是否解析成功，或工具调用是否使用了正确的参数。
The number of examples depends on the scenarios the check covers. At minimum, include examples that should Pass and Fail for every condition. Add important edge cases you found during error discovery. A check with one rule may need only a few examples that Pass and a few that Fail.示例的数量取决于检查所涵盖的场景。至少包括每个条件下应该“通过”和“失败”的示例。添加你在错误发现期间发现的重要边缘案例。一个只有一条规则的检查可能只需要几个通过和几个失败的示例。
LLM judges need labeled examples大模型裁判需要标注示例
Use an LLM judge when the failure requires subjective or domain-specific judgment. Plan to label 100 to 200 examples for each failure mode. Reuse labeled traces from error discovery when they match the failure mode, then collect more until you reach that range. The labels should come from a trusted domain expert and contain enough Pass and Fail examples to evaluate both classes.当故障需要主观或领域特定的判断时，使用大模型裁判。计划为每种故障模式标注 100 到 200 个示例。当它们与故障模式匹配时，重用错误发现中的标注追踪，然后收集更多，直到达到该范围。标注应来自受信任的领域专家，并包含足够的“通过”和“失败”示例以评估这两个类别。
Split these examples into train, dev, and test sets. Use 10 to 20 percent for train examples that may appear in the prompt. Use 40 to 45 percent for dev while refining the judge. Reserve the remaining 40 to 45 percent for one final test. When possible, include 30 to 50 Pass examples and 30 to 50 Fail examples in both the dev and test sets.将这些示例拆分为训练集、开发集和测试集。使用 10% 到 20% 作为可能出现在提示词中的训练示例。使用 40% 到 45% 作为开发集，用于完善裁判。保留剩余的 40% 到 45% 用于最终测试。尽可能在开发集和测试集中都包含 30 到 50 个“通过”示例和 30 到 50 个“失败”示例。
The validation guide explains the full process. The judge-validation flashcard is a good visual reference as well.验证指南解释了整个过程。裁判验证抽认卡也是一个很好的视觉参考。
After validating the evaluators, assemble the examples you will run repeatedly during development.在验证评估器后，整理你在开发过程中将反复运行的示例。
Stage 3: Build the repeatable eval set阶段 3：构建可重复的评估集
Start with examples from error discovery that capture important failure modes. Add confirmed failures as you find them.从捕获重要故障模式的错误发现示例开始。随着你的发现，添加已确认的故障。
A purpose-built eval set often grows to 100 or more examples. Coverage determines the final size. Each important workflow and known failure should be represented, and the set should remain cheap enough to run often. Code-based checks and LLM judges can run over the same examples. The CI evals FAQ explains how to use this set during development.专门构建的评估集通常会增长到 100 个或更多示例。覆盖率决定了最终大小。每个重要的工作流和已知故障都应该被表现出来，并且该集合应该保持足够便宜以便经常运行。代码评估和大模型裁判可以在相同的示例上运行。CI 评估 FAQ 解释了如何在开发过程中使用此集合。
Q: How do I surface problematic traces for review beyond user feedback?
While user feedback is a good way to narrow in on problematic traces, other methods are also useful. Here are three complementary approaches:虽然用户反馈是锁定有问题的追踪的一种好方法，但其他方法也很有用。这里有三种互补的方法：
Start with random sampling从随机采样开始
The simplest approach is reviewing a random sample of traces. If you find few issues, escalate to stress testing: create queries that deliberately test your prompt constraints to see if the AI follows your rules.最简单的方法是审查随机抽取的追踪样本。如果你发现的问题很少，请升级到压力测试：创建故意测试你提示词约束的查询，以查看 AI 是否遵循你的规则。
Use evals for initial screening使用评估进行初步筛选
Use existing evals to find problematic traces and potential issues. Once you’ve identified these, you can proceed with the typical evaluation process starting with error analysis.使用现有的评估来查找有问题的追踪和潜在问题。一旦确定了这些，你就可以开始从错误分析开始的典型评估过程。
Leverage efficient sampling strategies利用高效的采样策略
For more sophisticated trace discovery, use outlier detection, metric-based sorting, and stratified sampling to find interesting traces. Generic metrics can serve as exploration signals to identify traces worth reviewing, even if they don’t directly measure quality.对于更复杂的追踪发现，使用异常检测、基于指标的排序和分层采样来查找有趣的追踪。通用指标可以作为探索信号来识别值得审查的追踪，即使它们不能直接测量质量。
Q: How often should I re-run error analysis on my production system?
Re-run error analysis when making significant changes: new features, prompt updates, model switches, or major bug fixes. A useful heuristic is to set a goal for reviewing at least 100+ fresh traces each review cycle. Typical review cycles we’ve seen range from 2-4 weeks. See this FAQ on how to sample traces effectively.在做出重大变更时重新进行错误分析：新功能、提示词更新、模型切换或重大 Bug 修复。一个有用的启发式方法是设定一个目标，即在每个审查周期内审查至少 100 多个新的追踪。我们看到的典型审查周期范围是 2-4 周。请参阅此 FAQ 以了解如何有效采样追踪。
Between major analyses, review 10-20 traces weekly, focusing on outliers: unusually long conversations, sessions with multiple retries, or traces flagged by automated monitoring. Adjust frequency based on system stability and usage growth. New systems need weekly analysis until failure patterns stabilize. Mature systems might need only monthly analysis unless usage patterns change. Always analyze after incidents, user complaint spikes, or metric drift. Scaling usage introduces new edge cases.在重大分析之间，每周审查 10-20 个追踪，重点关注异常值：异常长的对话、多次重试的会话或被自动化监控标记的追踪。根据系统稳定性和使用增长调整频率。新系统需要每周分析，直到故障模式稳定。成熟系统可能只需要每月分析，除非使用模式发生变化。在发生事件、用户投诉激增或指标漂移后，务必进行分析。使用规模的扩大会引入新的边缘案例。
Q: What should I do when my "gold" eval dataset becomes stale?
Eval datasets naturally get stale as your product and users change. Use regular error analysis to find new problems and update your examples or reference answers. How often you review depends on your use case and how quickly your product or usage changes.随着你的产品和用户发生变化，评估数据集自然会过期。使用定期的错误分析来发现新问题并更新你的示例或参考答案。审查频率取决于你的用例以及你的产品或使用情况变化的快慢。
Like unit tests, evals can catch problems that return after a fix. However, evals often cost considerably more than unit tests to maintain and run. Therefore, you should weigh each eval’s cost against the value of its signals. If everything keeps passing, this is a sign that the eval is no longer useful and should be retired or run less often.像单元测试一样，评估可以捕获修复后返回的问题。然而，评估的维护和运行成本通常比单元测试高得多。因此，你应该权衡每个评估的成本与其信号的价值。如果一切一直通过，这表明该评估不再有用，应该停用或减少运行频率。
As your eval set changes, its scores may no longer be directly comparable with older scores. That is ok! One purpose of evals are to provide you with challenges you can hill climb against. These challenges should change as your product evolves to help you keep improving.随着你的评估集发生变化，其分数可能不再能与旧分数直接比较。没关系！评估的目的之一是为你提供可以持续爬升的挑战。随着产品的演进，这些挑战应该随之改变，以帮助你不断改进。
For tracking progress with metrics over longer time horizons, it’s often better to use product metrics in addition to evals. Examples of product metrics include: churn, active users, revenue, etc.为了在更长的时间范围内跟踪指标进度，除了评估之外，使用产品指标通常更好。产品指标的示例包括：流失率、活跃用户、收入等。
Q: What is the best approach for generating synthetic data?
A common mistake is prompting an LLM to "give me test queries" without structure, resulting in generic, repetitive outputs. A structured approach using dimensions produces far better synthetic data for testing LLM applications.一个常见的错误是提示大模型“给我测试查询”而不加结构，导致输出通用且重复。使用维度（Dimensions）的结构化方法可以为测试大模型应用程序产生更好的合成数据。
When should I use synthetic data for evals?我应该何时使用合成数据进行评估？
Use synthetic data to start error analysis before you have enough production traffic, or to test a known failure that appears rarely in real data. Define the variation you need, generate examples, run them through the full system, and review the resulting traces.在你有足够的生产流量之前，或者为了测试在真实数据中很少出现的已知故障，请使用合成数据。定义你需要的变化，生成示例，通过整个系统运行它们，并审查生成的追踪。
Synthetic data cannot tell you how common a failure is in production. It can also miss details that matter in specialized domains. Compare synthetic examples with real data as soon as real data becomes available. See when synthetic data may be unreliable for cases that require extra review.合成数据无法告诉你故障在生产环境中有多常见。它也可能错过专业领域中重要的细节。一旦真实数据可用，请立即将合成示例与真实数据进行比较。对于需要额外审查的情况，请参阅何时合成数据可能不可靠。
Define important dimensions first首先定义重要的维度
Start by defining dimensions: categories that describe different aspects of user queries. Each dimension captures one type of variation in user behavior. For example:首先定义维度：描述用户查询不同方面的类别。每个维度捕获用户行为的一种变化类型。例如：
- For a recipe app, dimensions might include Dietary Restriction (vegan, gluten-free, none), Cuisine Type (Italian, Asian, comfort food), and Query Complexity (simple request, multi-step, edge case).对于食谱应用程序，维度可能包括饮食限制（纯素、无麸质、无）、菜肴类型（意大利菜、亚洲菜、舒适食物）和查询复杂度（简单请求、多步骤、边缘案例）。
- For a customer support bot, dimensions could be Issue Type (billing, technical, general), Customer Mood (frustrated, neutral, happy), and Prior Context (new issue, follow-up, resolved).对于客户支持机器人，维度可以是问题类型（账单、技术、常规）、客户情绪（沮丧、中立、高兴）和先前上下文（新问题、后续、已解决）。
Start with failure hypotheses. If you lack intuition about failure modes, use your application extensively or recruit friends to use it. Then choose dimensions targeting those likely failures.从故障假设开始。如果你缺乏对故障模式的直觉，请广泛使用你的应用程序或招募朋友使用它。然后选择针对那些可能故障的维度。
Create tuples manually first: Write 20 tuples by hand. Each tuple selects one value from each dimension. Example: (Vegan, Italian, Multi-step). This manual work helps you understand your problem space.先手动创建元组：手工编写 20 个元组。每个元组从每个维度中选择一个值。示例：（纯素、意大利菜、多步骤）。这种手工工作有助于你理解你的问题空间。
Scale with two-step generation:通过两步生成进行扩展：
- Generate structured tuples: Have the LLM create more combinations like (Gluten-free, Asian, Simple)生成结构化元组：让大模型创建更多组合，如（无麸质、亚洲菜、简单）
- Convert tuples to queries: In a separate prompt, turn each tuple into natural language将元组转换为查询：在单独的提示词中，将每个元组转换为自然语言
This separation avoids repetitive phrasing. The (Vegan, Italian, Multi-step) tuple becomes: "I need a dairy-free lasagna recipe that I can prep the day before."这种分离避免了重复的措辞。（纯素、意大利菜、多步骤）元组变为：“我需要一个可以提前准备的无乳制品千层面食谱。”
Generation approaches生成方法
You can generate tuples two ways:你可以通过两种方式生成元组：
Cross product then filter: Generate all dimension combinations, then filter with an LLM. Guarantees coverage including edge cases. Use when most combinations are valid.笛卡尔积然后过滤：生成所有维度组合，然后用大模型过滤。保证覆盖率，包括边缘案例。当大多数组合有效时使用。
Direct LLM generation: Ask the LLM to generate tuples directly. This produces more realistic combinations, but it tends toward generic outputs and misses rare scenarios. Use it when many dimension combinations are invalid.直接大模型生成：让大模型直接生成元组。这会产生更真实的组合，但往往趋向于通用输出并错过罕见场景。当许多维度组合无效时使用。
Fix obvious problems first: Don’t generate synthetic data for issues you can fix immediately. If your prompt doesn’t mention dietary restrictions, fix the prompt rather than generating specialized test queries.先修复明显的问题：不要为你能够立即修复的问题生成合成数据。如果你的提示词没有提到饮食限制，请修复提示词，而不是生成专门的测试查询。
After iterating on your tuples and prompts, run these synthetic queries through your actual system to capture full traces. A pool of roughly 100 diverse traces is a useful starting point for failure discovery. Have an agent help with sampling, annotate at least 30 traces yourself, then review the agent’s suggestions until your learning plateaus. See how many examples you need for error discovery for the full explanation.在对元组（tuples）和提示词进行迭代后，将这些合成查询运行在你的实际系统中，以捕获完整的追踪记录。大约 100 条多样化的追踪记录是发现故障的一个很好的起点。让智能体协助采样，你自己至少标注 30 条追踪记录，然后审查智能体的建议，直到你的学习达到平台期。参阅关于错误发现所需样本数量的完整解释。
Here is a visual that helps visualize the process.这是一张有助于直观理解该过程的图示。
Q: Are there scenarios where synthetic data may not be reliable?
Yes: synthetic data can mislead or mask issues. For guidance on generating synthetic data when appropriate, see What is the best approach for generating synthetic data?是的：合成数据可能会产生误导或掩盖问题。关于在适当情况下生成合成数据的指导，请参阅“生成合成数据的最佳方法是什么？”
Common scenarios where synthetic data fails:合成数据失效的常见场景：
Complex domain-specific content: LLMs often miss the structure, nuance, or quirks of specialized documents (e.g., legal filings, medical records, technical forms). Without real examples, critical edge cases are missed.复杂的领域特定内容：大语言模型（LLM）往往会忽略专业文档（如法律文件、医疗记录、技术表格）的结构、细微差别或特殊之处。如果没有真实示例，关键的边缘情况就会被漏掉。
Low-resource languages or dialects: For low-resource languages or dialects, LLM-generated samples are often unrealistic. Evaluations based on them won’t reflect actual performance.低资源语言或方言：对于低资源语言或方言，LLM 生成的样本通常不切实际。基于这些样本的评估将无法反映实际性能。
When validation is impossible: If you can’t verify synthetic sample realism (due to domain complexity or lack of ground truth), real data is important for accurate evaluation.无法验证的情况：如果你无法验证合成样本的真实性（由于领域复杂性或缺乏基准事实），那么真实数据对于准确评估至关重要。
High-stakes domains: In high-stakes domains (medicine, law, emergency response), synthetic data often lacks subtlety and edge cases. Errors here have serious consequences, and manual validation is difficult.高风险领域：在高风险领域（医学、法律、应急响应），合成数据往往缺乏微妙之处和边缘情况。这些领域的错误会带来严重后果，且人工验证非常困难。
Underrepresented user groups: For underrepresented user groups, LLMs may misrepresent context, values, or challenges. Synthetic data can reinforce biases in the training data of the LLM.代表性不足的用户群体：对于代表性不足的用户群体，LLM 可能会曲解其背景、价值观或面临的挑战。合成数据可能会强化 LLM 训练数据中已有的偏见。
Q: How can I do evals when traces contain sensitive data?
There is no replacement for looking at real interactions. This situation is not ideal, but there are some things you can do. Here are some options, in order of preference:查看真实交互是无可替代的。这种情况虽然不理想，但你仍可以采取一些措施。以下是按优先顺序排列的几种方案：
Try to find real data you are allowed to inspect. A customer may agree to share a subset of traces, or test users may let you review their interactions. Even limited access gives you examples of how people use the product.尝试寻找你获准查看的真实数据。客户可能同意分享一部分追踪记录，或者测试用户可能允许你审查他们的交互。即使是有限的访问权限，也能为你提供人们如何使用产品的示例。
If you cannot inspect the data yourself, work with domain experts who are allowed to see it. Make your product easier for them to verify as part of their normal work. For example, a medical research assistant could show a clinician the evidence behind each claim and flag conflicting sources for review. The clinician can correct a specific claim or resolve a conflict while using the product. Those decisions can provide additional data for evals, subject to the same restrictions on what you can store and share.如果你无法亲自查看数据，请与获准查看数据的领域专家合作。让你的产品在他们的日常工作中更容易被验证。例如，医疗研究助理可以向临床医生展示每项结论背后的证据，并标记出相互冲突的来源以供审查。临床医生在使用产品时可以纠正特定的结论或解决冲突。这些决定可以为评估提供额外的数据，前提是同样遵守关于存储和分享内容的限制。
To design this well, learn how the experts check an answer. Give them links to the supporting evidence and smaller pieces of work they can review. Asking whether the final answer was helpful often tells you too little about what went wrong. I discuss this approach in this post.为了设计好这一流程，需要了解专家是如何检查答案的。为他们提供支持性证据的链接以及他们可以审查的较小工作单元。询问最终答案是否有帮助，通常无法让你了解哪里出了问题。我在本文中讨论了这种方法。
Redact or edit traces so they can be shared. If sensitive information cannot be stored, redact it before logging. Redaction tools can miss sensitive information, so check their output. When edited traces can be shared, removing personal information and changing sensitive details can make real examples usable for review. Check that those edits preserve the behavior you need to evaluate.对追踪记录进行脱敏或编辑，以便分享。如果敏感信息不能存储，请在记录前将其脱敏。脱敏工具可能会遗漏敏感信息，因此请务必检查其输出。当编辑后的追踪记录可以分享时，删除个人信息并修改敏感细节可以使真实示例可用于审查。请检查这些编辑是否保留了你需要评估的行为。
If none of the above options are possible, synthetic data should be your last resort. Synthetic data can help you find initial problems but has the downside that it only gives you limited evidence about how real users will behave. Read more about when synthetic data may be unreliable.如果上述方案均不可行，合成数据应作为最后手段。合成数据可以帮助你发现初步问题，但缺点是它只能提供关于真实用户行为的有限证据。阅读更多关于合成数据何时可能不可靠的内容。
Q: How do I approach evaluation when my system handles diverse user queries?
Complex applications often support vastly different query patterns—from “What’s the return policy?” to “Compare pricing trends across regions for products matching these criteria.” Each query type exercises different system capabilities, leading to confusion on how to design eval criteria.复杂的应用程序通常支持差异巨大的查询模式——从“退货政策是什么？”到“比较符合这些条件的产品在各地区的定价趋势”。每种查询类型都会调用不同的系统能力，导致在设计评估标准时感到困惑。
Error Analysis is all you need. Your evaluation strategy should emerge from observed failure patterns (e.g. error analysis), not predetermined query classifications. Rather than creating a massive evaluation matrix covering every query type you can imagine, let your system’s actual behavior guide where you invest evaluation effort.错误分析（Error Analysis）是你所需要的一切。你的评估策略应从观察到的失败模式（即错误分析）中产生，而不是预先设定的查询分类。不要试图创建一个涵盖你能想象到的每一种查询类型的庞大评估矩阵，而应让系统的实际行为来指导你在哪里投入评估精力。
During error analysis, you’ll likely discover that certain query categories share failure patterns. For instance, all queries requiring temporal reasoning might struggle regardless of whether they’re simple lookups or complex aggregations. Similarly, queries that need to combine information from multiple sources might fail in consistent ways. These patterns discovered through error analysis should drive your evaluation priorities. It could be that query category is a fine way to group failures, but you don’t know that until you’ve analyzed your data.在错误分析过程中，你很可能会发现某些查询类别具有共同的失败模式。例如，所有需要时间推理的查询，无论它们是简单的查找还是复杂的聚合，都可能表现不佳。同样，需要组合多个来源信息的查询也可能以一致的方式失败。通过错误分析发现的这些模式应驱动你的评估优先级。查询类别可能是一种很好的分组失败的方式，但在分析数据之前，你无法预知这一点。
To see an example of basic error analysis in action, see this video.要查看基础错误分析的实际示例，请观看此视频。
Watch “Error Analysis: The Highest ROI Technique In AI Engineering” on YouTube在 YouTube 上观看“错误分析：AI 工程中投资回报率最高的技术”
Q: How can I efficiently sample production traces for review?
There are many ways to sample production traces for review. Here are some common methods.采样生产环境追踪记录以供审查的方法有很多。以下是一些常用方法。
| Method | What it does | Main limitation |
|---|---|---|
| Random | Selects traces with equal probability. | A small batch can miss rare cases. |
| Clustering | Groups traces by similar content and selects examples from each group. | The result depends on the features and clustering choices. |
| Data analysis | Reviews extreme values such as latency or tool count. | An extreme value may have nothing to do with quality. |
| Classification | Uses an evaluator or another model to flag likely failures. | It favors problems the classifier already knows how to find. |
| Feedback | Selects traces with negative user feedback. | It misses problems that users do not report. |
The table above orders sampling methods from the most exploratory to the most targeted. When you’re starting out, you should optimize for exploration of the data. As you learn more, you can start to lean more heavily on signals to select traces. The proper mix of methods depends on your goals and requires experimentation.上表按从探索性最强到针对性最强对采样方法进行了排序。刚开始时，你应该优化数据的探索。随着了解的深入，你可以开始更多地依赖信号来选择追踪记录。方法的正确组合取决于你的目标，并需要通过实验来确定。
Keep some random traces in every batch. This gives you a chance to find failure modes that your current signals do not describe.在每一批次中保留一些随机追踪记录。这让你有机会发现当前信号未能描述的失败模式。
How do I measure rare failure modes?我该如何衡量罕见的失败模式？
Use targeted sampling to find rare failures. Search for signals that correlate with the failure, such as a specific tool sequence, unusually long traces, retries, or a known input pattern. Review the targeted batch to collect examples and improve the failure definition.使用针对性采样来查找罕见失败。搜索与失败相关的信号，例如特定的工具序列、异常长的追踪记录、重试或已知的输入模式。审查针对性批次以收集示例并完善失败定义。
This flashcard from our evals flashcards series visualizes these methods.我们评估系列抽认卡中的这张抽认卡展示了这些方法。
Use labels to choose the next traces使用标签来选择下一批追踪记录
We can borrow a technique from machine learning called active learning to sample production traces. In active learning, a system asks a person to label the data points that would be most useful for its next update.我们可以借用机器学习中称为主动学习（active learning）的技术来采样生产环境的追踪记录。在主动学习中，系统会要求人工标注对下一次更新最有用的数据点。
In Shreya Shankar’s walkthrough, Claude Code clusters traces and chooses examples from each cluster for review. A monitor command watches annotations.json for new labels. When a label arrives, the agent updates a failure taxonomy and looks for similar cases or different failures.在 Shreya Shankar 的演示中，Claude Code 对追踪记录进行聚类，并从每个簇中选择示例进行审查。监控命令会观察 annotations.json 中的新标签。当标签到达时，智能体会更新失败分类法，并寻找类似的案例或不同的失败情况。
Watch “How to Automate AI Evals (Correctly)” on YouTube在 YouTube 上观看“如何（正确地）自动化 AI 评估”
In the above video, active learning is used in the context of error analysis to find new cases to review. However, this approach can be used anywhere in the workflow where you are annotating data.在上述视频中，主动学习是在错误分析的背景下使用的，旨在寻找新的案例进行审查。然而，这种方法可以用在工作流中任何需要标注数据的地方。
👉 Want to learn more about AI Evals? Check out our AI Evals course. It’s a live cohort with hands on exercises and office hours. Here is a 25% discount code for readers. 👈👉 想了解更多关于 AI 评估的知识吗？查看我们的 AI 评估课程。这是一个包含动手练习和答疑时间的现场同侪课程。这是给读者的 25% 折扣码。 👈
Evaluation Design & Methodology评估设计与方法论
Q: Why do you recommend binary (pass/fail) evaluations instead of 1-5 ratings (Likert scales)?
Engineers often believe that Likert scales (1-5 ratings) provide more information than binary evaluations, allowing them to track gradual improvements. However, this added complexity often creates more problems than it solves in practice.工程师通常认为李克特量表（1-5 分评分）比二元评估提供更多信息，允许他们跟踪渐进式的改进。然而，这种增加的复杂性在实践中往往带来的问题多于解决的问题。
Binary evaluations force clearer thinking and more consistent labeling. Likert scales introduce significant challenges: the difference between adjacent points (like 3 vs 4) is subjective and inconsistent across annotators, detecting statistical differences requires larger sample sizes, and annotators often default to middle values to avoid making hard decisions.二元评估能促使思考更清晰，标注更一致。李克特量表引入了重大挑战：相邻分值（如 3 分和 4 分）之间的差异是主观的，且在不同标注者之间不一致；检测统计学差异需要更大的样本量；标注者往往倾向于选择中间值以避免做出困难的决定。
Having binary options forces people to make a decision rather than hiding uncertainty in middle values. Binary decisions are also faster to make during error analysis - you don’t waste time debating whether something is a 3 or 4.使用二元选项会迫使人们做出决定，而不是将不确定性隐藏在中间值中。在错误分析期间，二元决策也更快——你不会浪费时间争论某件事是 3 分还是 4 分。
For tracking gradual improvements, consider measuring specific sub-components with their own binary checks rather than using a scale. For example, instead of rating factual accuracy 1-5, you could track “4 out of 5 expected facts included” as separate binary checks. This preserves the ability to measure progress while maintaining clear, objective criteria.对于跟踪渐进式改进，考虑测量特定的子组件并进行各自的二元检查，而不是使用量表。例如，与其将事实准确性评为 1-5 分，不如将“包含 5 个预期事实中的 4 个”作为单独的二元检查来跟踪。这既保留了衡量进展的能力，又保持了清晰、客观的标准。
Start with binary labels to understand what ‘bad’ looks like. Numeric labels are advanced and usually not necessary.从二元标签开始，以了解“糟糕”是什么样子的。数字标签属于进阶用法，通常是不必要的。
Q: Should I practice eval-driven development?
Generally no. Eval-driven development (writing evaluators before implementing features) sounds appealing but creates more problems than it solves. Unlike traditional software where failure modes are predictable, LLMs have infinite surface area for potential failures. You can’t anticipate what will break.通常不是。评估驱动开发（在实现功能之前编写评估器）听起来很有吸引力，但带来的问题多于解决的问题。与失败模式可预测的传统软件不同，大语言模型具有无限的潜在失败面。你无法预见什么会出错。
A better approach is to start with error analysis. Write evaluators for errors you discover, not errors you imagine. This avoids getting blocked on what to evaluate and prevents wasted effort on metrics that have no impact on actual system quality.更好的方法是从错误分析开始。为你发现的错误编写评估器，而不是为你想象的错误编写。这可以避免在评估什么的问题上陷入僵局，并防止在对实际系统质量没有影响的指标上浪费精力。
Exception: Eval-driven development may work for specific constraints where you know exactly what success looks like. If adding “never mention competitors,” writing that evaluator early may be acceptable.例外：评估驱动开发可能适用于某些特定约束条件，即你确切知道成功是什么样子的。如果需要添加“禁止提及竞争对手”，那么尽早编写该评估器是可以接受的。
Most importantly, always do a cost-benefit analysis before implementing an eval. Ask whether the failure mode justifies the investment. Error analysis reveals which failures actually matter for your users.最重要的是，在实施评估之前始终进行成本效益分析。询问该失败模式是否值得投入。错误分析会揭示哪些失败对你的用户真正重要。
Q: Should I build automated evaluators for every failure mode I find?
Focus automated evaluators on failures that persist after fixing your prompts. Many teams discover their LLM doesn’t meet preferences they never actually specified - like wanting short responses, specific formatting, or step-by-step reasoning. Fix these obvious gaps first before building complex evaluation infrastructure.将自动化评估器集中在修复提示词后仍然存在的失败上。许多团队发现他们的 LLM 未能满足他们从未明确指定的偏好——例如希望回答简短、特定的格式或分步推理。在构建复杂的评估基础设施之前，先修复这些显而易见的差距。
Consider the cost hierarchy of different evaluator types. Simple assertions and reference-based checks (comparing against known correct answers) are cheap to build and maintain. LLM-as-Judge evaluators require 100+ labeled examples, ongoing weekly maintenance, and coordination between developers, PMs, and domain experts. This cost difference should shape your evaluation strategy.考虑不同评估器类型的成本层级。简单的断言和基于参考的检查（与已知正确答案进行比较）构建和维护成本较低。LLM-as-Judge（将 LLM 作为裁判）评估器需要 100 多个已标注示例、持续的每周维护以及开发者、产品经理和领域专家之间的协调。这种成本差异应决定你的评估策略。
Only build expensive evaluators for problems you’ll iterate on repeatedly. Since LLM-as-Judge comes with significant overhead, save it for persistent generalization failures - not issues you can fix trivially. Start with cheap code-based checks where possible: regex patterns, structural validation, or execution tests. Reserve complex evaluation for subjective qualities that can’t be captured by simple rules.只为你会反复迭代的问题构建昂贵的评估器。由于 LLM-as-Judge 伴随着巨大的开销，请将其留给持久的泛化失败问题，而不是那些你可以轻易解决的问题。尽可能从基于代码的廉价检查开始：正则模式、结构验证或执行测试。将复杂的评估留给无法通过简单规则捕获的主观质量。
Q: Should I use "ready-to-use" evaluation metrics?
No. Generic evaluations waste time and create false confidence when you use them as quality measures. However, they can still help you find traces to inspect.不是。通用评估浪费时间，并且当你将它们用作质量衡量标准时会产生虚假的信心。然而，它们仍然可以帮助你找到需要审查的追踪记录。
Why are generic eval metrics misleading?为什么通用评估指标具有误导性？
Generic evaluation metrics are everywhere. Eval libraries contain scores like helpfulness, coherence, quality, etc. promising easy evaluation. These metrics measure abstract qualities that may not matter for your use case. Good scores on them don’t mean your system works.通用评估指标无处不在。评估库中包含诸如有用性、连贯性、质量等分数，承诺提供简单的评估。这些指标衡量的是抽象的质量，可能对你的用例并不重要。在这些指标上获得高分并不意味着你的系统能正常工作。
Instead, conduct error analysis to understand failures. Define binary failure modes based on real problems. Create custom evaluators for those failures and validate them against human judgment.相反，应进行错误分析以了解失败原因。根据实际问题定义二元失败模式。为这些失败创建自定义评估器，并根据人类判断来验证它们。
Experienced practitioners may use generic metrics as exploration signals. Once you understand why they fail as quality measures, you can use them to find interesting traces for human review.经验丰富的从业者可能会将通用指标用作探索信号。一旦你理解了它们作为质量衡量标准为何会失败，你就可以利用它们来寻找值得人工审查的有趣追踪记录。
Q: Are similarity metrics (BERTScore, ROUGE, etc.) useful for evaluating LLM outputs?
Generic metrics like BERTScore, ROUGE, cosine similarity, etc. are not useful for evaluating LLM outputs in most AI applications. Instead, we recommend using error analysis to identify metrics specific to your application’s behavior. We recommend designing binary pass/fail.) evals (using LLM-as-judge) or code-based assertions.在大多数 AI 应用中，诸如 BERTScore、ROUGE、余弦相似度等通用指标对于评估 LLM 输出并无用处。相反，我们建议使用错误分析来识别特定于你应用程序行为的指标。我们建议设计二元通过/失败评估（使用 LLM-as-judge）或基于代码的断言。
As an example, consider a real estate CRM assistant. Suggesting showings that aren’t available (can be tested with an assertion) or confusing client personas (can be tested with a LLM-as-judge) is problematic . Generic metrics like similarity or verbosity won’t catch this. A relevant quote from the course:作为一个例子，考虑一个房地产 CRM 助手。建议不可用的房源（可以通过断言测试）或混淆客户角色（可以通过 LLM-as-judge 测试）是有问题的。相似度或冗长程度等通用指标无法捕捉到这一点。课程中的一句相关引言：
“The abuse of generic metrics is endemic. Many eval vendors promote off the shelf metrics, which ensnare engineers into superfluous tasks.”“对通用指标的滥用是普遍存在的。许多评估供应商推广现成的指标，这使工程师陷入了多余的任务中。”
Similarity metrics aren’t always useless. They have utility in domains like search and recommendation (and therefore can be useful for optimizing and debugging retrieval for RAG). For example, cosine similarity between embeddings can measure semantic closeness in retrieval systems, and average pairwise similarity can assess output diversity (where lower similarity indicates higher diversity).相似度指标并非毫无用处。它们在搜索和推荐等领域具有效用（因此对于优化和调试 RAG 的检索可能很有用）。例如，嵌入之间的余弦相似度可以衡量检索系统中的语义接近度，而平均成对相似度可以评估输出的多样性（相似度越低表示多样性越高）。
Q: Can I use the same model for both the main task and evaluation?
For LLM-as-Judge selection, using the same model is usually fine because the judge is doing a different task than your main LLM pipeline. While research has shown that models can exhibit bias when evaluating their own outputs, what ultimately matters is how well your judge aligns with human judgments. The judges we recommend building do scoped binary classification tasks. We’ve found that iterative alignment with human labels is usually achievable on this constrained task.对于 LLM-as-Judge 的选择，使用相同的模型通常是可以的，因为裁判执行的任务与你的主要 LLM 流水线不同。虽然研究表明模型在评估自身输出时可能表现出偏见，但最终重要的是你的裁判与人类判断的一致性程度。我们建议构建的裁判执行的是范围明确的二元分类任务。我们发现，在这个受限任务上，通常可以实现与人类标签的迭代对齐。
Focus on achieving high True Positive Rate (TPR) and True Negative Rate (TNR) with your judge on a held out labeled test set. If you struggle to achieve good alignment with human scores, then consider trying a different model. However onboarding new model providers may involve non-trivial effort in some organizations, which is why we don’t advocate for using different models by default unless there’s a specific alignment issue.专注于使你的裁判在留出的标注测试集上实现高真阳性率（TPR）和真阴性率（TNR）。如果你难以实现与人类分数良好的对齐，那么考虑尝试不同的模型。然而，在某些组织中引入新的模型提供商可能涉及非同小可的工作量，这就是为什么我们不主张默认使用不同模型，除非存在特定的对齐问题。
When selecting judge models, start with the most capable models available to establish strong alignment with human judgments. You can optimize for cost later once you’ve established reliable evaluation criteria.选择裁判模型时，先从可用的最强模型开始，以建立与人类判断的强对齐。一旦建立了可靠的评估标准，以后可以再针对成本进行优化。
Q: How much context should I give a LLM judge?
Give each judge only the parts of the trace it needs for its failure mode. Do not give every judge the same full trace by default. Extra context can cause context rot and make the judge worse.只给每个裁判提供其失败模式所需的追踪记录部分。默认情况下，不要给每个裁判提供相同的完整追踪记录。额外的上下文会导致上下文退化，并使裁判表现变差。
Finding the right pieces of context often requires experimentation. Test your choices by comparing the judge’s decisions with human labels. Then, inspect disagreements to see whether the judge lacked necessary evidence or was distracted by irrelevant information.寻找合适的上下文片段通常需要实验。通过将裁判的决定与人类标签进行比较来测试你的选择。然后，检查分歧之处，看看裁判是缺乏必要证据，还是被无关信息分散了注意力。
If you’re unsure whether a piece of information helps, try an ablation study. This means removing one piece at a time and checking how the results change against human labels. If performance stays the same or improves, you may be able to leave it out.如果你不确定某条信息是否有帮助，可以尝试消融研究（ablation study）。这意味着一次删除一个片段，并检查结果相对于人类标签的变化。如果性能保持不变或有所提高，你或许可以将其剔除。
Long-running agents can produce large traces that fill or exceed the judge’s context window. For these cases, consider giving the judge a tool to search the parts it needs. However, don’t add this unless you absolutely need it, as a tool like this adds additional complexity, cost, and latency.长时间运行的智能体可能会产生巨大的追踪记录，填满或超过裁判的上下文窗口。对于这些情况，考虑给裁判提供一个工具来搜索它需要的部分。但是，除非绝对必要，否则不要添加此功能，因为这样的工具会增加额外的复杂性、成本和延迟。
Q: How do we evaluate a model’s ability to express uncertainty or "know what it doesn’t know"?
Many applications require a model that can refuse to answer a question when it lacks sufficient information. To evaluate whether this refusal behavior is well-calibrated, you need to test if the model refuses at the appropriate times without refusing to answer questions it should be able to answer.许多应用程序需要一个能够在缺乏足够信息时拒绝回答问题的模型。为了评估这种拒绝行为是否校准良好，你需要测试模型是否在适当的时候拒绝，同时又不会拒绝回答它应该能够回答的问题。
To do this effectively, you should construct an evaluation set that has the following components:为了有效地做到这一点，你应该构建一个包含以下组件的评估集：
- Answerable Questions: Scenarios where a correct, verifiable answer is present in the model’s provided context or general knowledge.可回答的问题：模型提供的上下文或通用知识中存在正确、可验证答案的场景。
- Unanswerable Questions: Scenarios designed to tempt the model to hallucinate. These include questions with false premises, queries about information explicitly missing from context, or topics far outside its knowledge base.不可回答的问题：旨在诱导模型产生幻觉的场景。这些包括前提错误的问题、关于上下文中明确缺失信息的查询，或远超其知识库的主题。
While the exact proportion isn’t critical, a balanced set with a roughly equal number of answerable and unanswerable questions is a good starting point. The diversity and difficulty of the questions are more important than the precise ratio.虽然确切的比例并不关键，但一个包含大致相等数量的可回答和不可回答问题的平衡集是一个很好的起点。问题的多样性和难度比精确的比例更重要。
The evaluation itself is a binary (Pass/Fail) check of the model’s judgment. A “Pass” requires the model to satisfy two conditions: it must answer the answerable questions while also refusing to answer the unanswerable ones. A failure is defined as providing a fabricated answer to an unanswerable question, which indicates poor calibration.评估本身是对模型判断的二元（通过/失败）检查。“通过”要求模型满足两个条件：它必须回答可回答的问题，同时拒绝回答不可回答的问题。失败定义为对不可回答的问题提供编造的答案，这表明校准不佳。
In the research literature, this capability is known as “Abstention Ability.” To improve this behavior, it is worth searching for this term on Arxiv to understand the latest techniques.在研究文献中，这种能力被称为“弃权能力”（Abstention Ability）。为了改善这种行为，值得在 Arxiv 上搜索该术语以了解最新技术。
Human Annotation & Process人工标注与流程
Q: How many people should annotate my LLM outputs?
For most small to medium-sized companies, appointing a single domain expert as a “benevolent dictator” is the most effective approach. This person becomes the definitive voice on quality standards. The expert might be a psychologist for a mental health chatbot or a lawyer for legal document analysis.对于大多数中小型公司而言，任命一名领域专家作为“仁慈的独裁者”是最有效的方法。此人成为质量标准的最终权威。专家可能是心理健康聊天机器人的心理学家，或者是法律文档分析的律师。
A single expert eliminates annotation conflicts and prevents the paralysis that comes from “too many cooks in the kitchen”. The benevolent dictator can incorporate input and feedback from others, but they drive the process. If you feel like you need five subject matter experts to judge a single interaction, it’s a sign your product scope might be too broad.单一专家消除了标注冲突，并防止了“人多手杂”带来的瘫痪。仁慈的独裁者可以吸收他人的输入和反馈，但他们主导整个流程。如果你觉得需要五位主题专家来判断一次交互，这说明你的产品范围可能太广了。
However, larger organizations or those operating across multiple domains (like a multinational company with different cultural contexts) may need multiple annotators. When you do use multiple people, you’ll need to measure their agreement using metrics like Cohen’s Kappa, which accounts for agreement beyond chance. However, use your judgment. Even in larger companies, a single expert is often enough.然而，大型组织或跨多个领域运营的组织（如具有不同文化背景的跨国公司）可能需要多名标注者。当你确实使用多个人时，你需要使用 Cohen’s Kappa 等指标来衡量他们的一致性，该指标考虑了超出偶然性的一致性。不过，要运用你的判断力。即使在大公司，单一专家通常也足够了。
How should annotators resolve disagreements?标注者应该如何解决分歧？
Have annotators label the same examples independently before they discuss them. Measure agreement and collect the cases where their labels differ. During an alignment session, ask which part of the rubric caused the disagreement and what rule would make the next decision clear.让标注者在讨论前独立标注相同的示例。衡量一致性并收集标签不同的案例。在对齐会议中，询问评分标准的哪一部分导致了分歧，以及什么规则能让下一次决策变得清晰。
Update the rubric with a definition, rule, or example that covers the disputed case. Then relabel affected examples. If the annotators still disagree, assign a domain expert to make the final decision and record the reason.用涵盖争议案例的定义、规则或示例更新评分标准。然后重新标注受影响的示例。如果标注者仍然存在分歧，则指派一名领域专家做出最终决定并记录原因。
Start with a benevolent dictator whenever feasible. Only add complexity when absolutely necessary.尽可能从仁慈的独裁者开始。只有在绝对必要时才增加复杂性。
Q: How can I make AI outputs easier for people to evaluate?
Start by scrutinizing your product design. It’s often helpful to surface intermediate outputs users can check before a final result. For example, suppose you have an agent that writes a medical report by synthesizing a patient’s medical history. Instead of asking a doctor to provide feedback on the report, show the extracted facts with links to the source material and let doctors correct a fact or resolve conflicting evidence before generating the report. This also keeps the doctor involved and helps them build trust by checking the work as they go. This is a sketch of how such an interface might look:从审视你的产品设计开始。在最终结果出来之前，向用户展示他们可以检查的中间输出通常很有帮助。例如，假设你有一个智能体通过综合患者病史来撰写医疗报告。与其让医生对报告提供反馈，不如展示提取的事实并附上原始资料的链接，让医生在生成报告前纠正事实或解决冲突的证据。这也让医生参与其中，并通过边做边检查工作来帮助他们建立信任。这是此类界面可能外观的草图：
For more discussion on designing for verification, see “It’s Hard to Eval” Is a Product Smell. The post expands on this example and discusses several others with before-and-after mockups.关于为验证而设计的更多讨论，请参阅“‘评估很难’是一种产品瑕疵”。该文章扩展了这个例子，并讨论了其他几个带有前后对比模型的示例。
After you have designed for verification, make sure the review interface removes friction from reviewing data. See the advice on building a review interface. Some common tips include:在为验证完成设计后，确保审查界面消除了审查数据的摩擦。参阅关于构建审查界面的建议。一些常见的提示包括：
- Display outputs in a familiar format. Render generated emails as emails, and use syntax highlighting for code.以熟悉的格式显示输出。将生成的电子邮件渲染为电子邮件，并对代码使用语法高亮。
- Keep the context reviewers need on the same screen. Put less important details in sections they can expand when needed.将审查者需要的上下文放在同一屏幕上。将不重要的细节放在他们需要时可以展开的部分。
- Add keyboard shortcuts for moving between examples and recording judgments. Make it easy to save notes without reaching for the mouse.添加用于在示例间移动和记录判断的键盘快捷键。使保存笔记变得容易，无需伸手去拿鼠标。
- Show progress, such as “45 of 100 examples reviewed,” so reviewers know how much work remains.显示进度，例如“已审查 100 个示例中的 45 个”，以便审查者知道还剩下多少工作。
Next, debug the review process. First, try fewer examples so reviewers have time to inspect each one carefully. Have people review the same examples independently and discuss disagreements. You can also review examples together to see where people get stuck. Disagreement can reveal unclear instructions or missing information.接下来，调试审查流程。首先，尝试较少的示例，以便审查者有时间仔细检查每一个。让人独立审查相同的示例并讨论分歧。你也可以一起审查示例，看看人们在哪里卡住了。分歧可以揭示不明确的指令或缺失的信息。
Q: Should product managers and engineers collaborate on error analysis? How?
At the outset, collaborate to establish shared context. Engineers catch technical issues like retrieval issues and tool errors. PMs identify product failures like unmet user expectations, confusing responses, or missing features users expect.起初，通过协作来建立共同的背景。工程师捕捉检索问题和工具错误等技术问题。产品经理识别未满足用户期望、令人困惑的回答或用户期望缺失的功能等产品失败。
As time goes on you should lean towards a benevolent dictator for error analysis: a domain expert or PM who understands user needs. Empower domain experts to evaluate actual outcomes rather than technical implementation. Ask “Has an appointment been made?” not “Did the tool call succeed?” The best way to empower the domain expert is to give them custom annotation tools that display system outcomes alongside traces. Show the confirmation, generated email, or database update that validates goal completion. Keep all context on one screen so non-technical reviewers focus on results.随着时间的推移，你应该倾向于为错误分析任命一名仁慈的独裁者：一位了解用户需求的领域专家或产品经理。授权领域专家评估实际结果，而不是技术实现。询问“是否已经预约成功？”而不是“工具调用是否成功？”授权领域专家的最好方法是为他们提供自定义标注工具，在追踪记录旁边显示系统结果。显示确认信息、生成的电子邮件或验证目标完成的数据库更新。将所有上下文保持在一个屏幕上，以便非技术审查者专注于结果。
Q: Can I help with evals if I’m not a domain expert?
Yes, especially when you’re beginning with evals. I’m often surprised by the number of low-hanging fruit I find while reviewing data that don’t require domain knowledge. For example, I’ve found issues like this in specialized domains as an outsider:是的，特别是当你刚开始进行评估时。我经常惊讶于在审查数据时发现的那些不需要领域知识的低垂果实。例如，作为一个局外人，我在专业领域发现了这样的问题：
- Text message chatbots getting confused by the conversational flow of lots of short, broken-up messages people tend to write in text versus chat.短信聊天机器人被人们在短信中倾向于写的许多简短、破碎的信息的对话流所困惑，这与聊天软件不同。
- Lack of query disambiguation or follow-up when users’ requests are obviously vague.当用户的请求明显模糊时，缺乏查询消歧或后续跟进。
- Not having proper instrumentation, logging or traces to begin with.一开始就没有适当的仪表化、日志记录或追踪记录。
- Lack of widgets, UI elements or other affordances that help users complete tasks versus over-reliance on text responses.缺乏帮助用户完成任务的组件、UI 元素或其他可供性，而是过度依赖文本回答。
Furthermore, ask a domain expert to walk through an example and explain why it is good or bad. Watch what they check and which evidence they need. Use what you learn to build a better annotation interface that makes reviewing easier.此外，请领域专家遍历一个示例并解释它为什么好或坏。观察他们检查什么以及他们需要什么证据。利用你所学到的知识构建一个更好的标注界面，使审查变得更容易。
You can also help the team collect interactions and review them regularly. For example, see how product managers and engineers can collaborate on error analysis to get an idea of how to structure cross-functional collaboration.你也可以帮助团队收集交互并定期审查它们。例如，查看产品经理和工程师如何协作进行错误分析，以了解如何构建跨职能协作。
Lastly, make sure you leave judgments that require specialized knowledge to the expert. However, don’t assume you need domain expertise to start being useful!最后，确保将需要专业知识的判断留给专家。但是，不要假设你需要领域专业知识才能开始发挥作用！
Q: Should I outsource annotation & labeling to a third party?
Outsourcing error analysis is usually a big mistake (with some exceptions). The core of evaluation is building the product intuition that only comes from systematically analyzing your system’s failures. You should be extremely skeptical of this process being delegated.外包错误分析通常是一个巨大的错误（有一些例外）。评估的核心是建立只有通过系统地分析系统失败才能获得的产品直觉。你应该对将此过程外包持高度怀疑态度。
The Dangers of Outsourcing外包的危险
When you outsource annotation, you often break the feedback loop between observing a failure and understanding how to improve the product. Problems with outsourcing include:当你外包标注时，你通常会打破观察失败和理解如何改进产品之间的反馈循环。外包的问题包括：
- Superficial Labeling: Even well-defined metrics require nuanced judgment that external teams lack. A critical misstep in error analysis is excluding domain experts from the labeling process. Outsourcing this task to those without domain expertise, like general developers or IT staff, often leads to superficial or incorrect labeling.
肤浅的标注：即使定义明确的指标也需要外部团队所缺乏的细致判断。错误分析中的一个关键失误是将领域专家排除在标注过程之外。将此任务外包给那些没有领域专业知识的人（如普通开发人员或 IT 人员）通常会导致肤浅或错误的标注。 - Loss of Unspoken Knowledge: A principal domain expert possesses tacit knowledge and user understanding that cannot be fully captured in a rubric. Involving these experts helps uncover their preferences and expectations, which they might not be able to fully articulate upfront.
隐性知识的丢失：首席领域专家拥有无法在评分标准中完全捕捉的隐性知识和用户理解。让这些专家参与进来有助于揭示他们可能无法预先完全表达的偏好和期望。 - Annotation Conflicts and Misalignment: Without a shared context, external annotators can create more disagreement than they resolve. Achieving alignment is a challenge even for internal teams, which means you will spend even more time on this process.标注冲突和不一致：没有共享的上下文，外部标注者可能会制造比他们解决的更多的分歧。即使对于内部团队来说，实现对齐也是一项挑战，这意味着你将在这个过程中花费更多时间。
The Recommended Approach: Build Internal Capability推荐方法：构建内部能力
Instead of outsourcing, focus on building an efficient internal evaluation process.与其外包，不如专注于建立高效的内部评估流程。
1. Appoint a “Benevolent Dictator”. For most teams, the most effective strategy is to appoint a single, internal domain expert as the final decision-maker on quality. This individual sets the standard, ensures consistency, and develops a sense of ownership.1. 任命一名“仁慈的独裁者”。对于大多数团队，最有效的策略是任命一名内部领域专家作为质量的最终决策者。此人设定标准、确保一致性并培养主人翁意识。
2. Use a collaborative workflow for multiple annotators. If multiple annotators are necessary, follow a structured process to ensure alignment: * Draft an initial rubric with clear Pass/Fail definitions and examples. * Have each annotator label a shared set of traces independently to surface differences in interpretation. * Measure Inter-Annotator Agreement (IAA) using a chance-corrected metric like Cohen’s Kappa. * Facilitate alignment sessions to discuss disagreements and refine the rubric. * Iterate on this process until agreement is consistently high.2. 为多名标注者使用协作工作流。如果必须使用多名标注者，请遵循结构化流程以确保对齐：* 起草一份包含清晰通过/失败定义和示例的初步评分标准。* 让每位标注者独立标注一组共享的追踪记录，以显现解释上的差异。* 使用 Cohen’s Kappa 等经偶然性校正的指标衡量标注者间一致性（IAA）。* 促进对齐会议以讨论分歧并完善评分标准。* 迭代此流程，直到一致性始终保持在高水平。
How to Handle Capacity Constraints如何处理容量限制
Building internal capacity does not mean you have to label every trace. Use these strategies to manage the workload:建立内部能力并不意味着你必须标注每一条追踪记录。使用这些策略来管理工作负载：
- Smart Sampling: Review a small, representative sample of traces thoroughly. It is more effective to analyze 100 diverse traces to find patterns than to superficially label thousands.
智能采样：彻底审查一小部分具有代表性的追踪记录。分析 100 条多样化的追踪记录以发现模式，比肤浅地标注数千条更有效。 - The “Think-Aloud” Protocol: To make the most of limited expert time, use this technique from usability testing. Ask an expert to verbalize their thought process while reviewing a handful of traces. This method can uncover deep insights in a single one-hour session.
“有声思维”协议：为了充分利用有限的专家时间，请使用这种来自可用性测试的技术。要求专家在审查少量追踪记录时口述他们的思考过程。这种方法可以在一小时的单次会话中揭示深刻的见解。 - Build Lightweight Custom Tools: Build custom annotation tools to streamline the review process, increasing throughput.构建轻量级自定义工具：构建自定义标注工具以简化审查流程，提高吞吐量。
Exceptions for External Help外部帮助的例外情况
While outsourcing the core error analysis process is not recommended, there are some scenarios where external help is appropriate:虽然不建议外包核心错误分析流程，但在某些情况下外部帮助是适当的：
- Purely Mechanical Tasks: For highly objective, unambiguous tasks like identifying a phone number or validating an email address, external annotators can be used after a rigorous internal process has defined the rubric.
纯机械任务：对于高度客观、无歧义的任务（如识别电话号码或验证电子邮件地址），在经过严格的内部流程定义评分标准后，可以使用外部标注者。 - Tasks Without Product Context: Well-defined tasks that don’t require understanding your product’s specific requirements can be outsourced. Translation is a good example: it requires linguistic expertise but not deep product knowledge.
没有产品上下文的任务：不需要了解你产品特定要求的定义明确的任务可以外包。翻译就是一个很好的例子：它需要语言专业知识，但不需要深厚的产品知识。 - Engaging Subject Matter Experts: Hiring external SMEs to act as your internal domain experts is not outsourcing; it is bringing the necessary expertise into your evaluation process. For example, AnkiHub hired 4th-year medical students to evaluate their RAG systems for medical content rather than outsourcing to generic annotators.聘请主题专家：聘请外部主题专家（SME）担任你的内部领域专家不是外包；而是将必要的专业知识引入你的评估流程。例如，AnkiHub 聘请了四年级医学生来评估其医疗内容的 RAG 系统，而不是外包给普通标注者。
Q: How do you review a trace that is really large?
Traces can get large when an agent runs for a long time or retrieves a large amount of context. A useful heuristic is to focus on the first upstream failure. Errors tend to compound, which means you can prioritize earlier ones to save time.当智能体运行时间过长或检索了大量上下文时，追踪记录可能会变得很大。一个有用的启发式方法是关注第一个上游失败。错误往往会累积，这意味着你可以优先处理较早的错误以节省时间。
Use progressive disclosure in your review tool by showing the most relevant information first and letting reviewers expand details as needed. For example, show the conversation initially, with tool outputs collapsed until a reviewer needs to inspect them.在你的审查工具中使用渐进式披露，先显示最相关的信息，并允许审查者根据需要展开细节。例如，最初显示对话，将工具输出折叠起来，直到审查者需要检查它们。
If a single trace is still too large to review, work with the domain expert to identify what they need to check. Build a tool that extracts the relevant evidence and links back to its location in the trace or retrieved document. For example, when reviewing an answer about a long contract, the tool could show the relevant clauses with links to their original pages. Always validate this kind of extraction with a domain expert.如果单条追踪记录仍然太大而无法审查，请与领域专家合作确定他们需要检查的内容。构建一个提取相关证据并链接回追踪记录或检索文档中位置的工具。例如，在审查关于一份长合同的答案时，工具可以显示相关条款并链接到原始页面。始终与领域专家验证这种提取。
Quality is more important than quantity. You can usually learn more from carefully investigating a few failures than from rushing through many traces.质量重于数量。你通常能从仔细调查少数几个失败中获得的收益，要多于匆忙处理大量追踪记录。
Q: What parts of evals can be automated with LLMs?
LLMs can speed up parts of your eval workflow, but they can’t replace human judgment where your expertise is essential. For example, if you let an LLM handle all of error analysis (i.e., reviewing and annotating traces), you might overlook failure cases that matter for your product. Suppose users keep mentioning “lag” in feedback, but the LLM lumps these under generic “performance issues” instead of creating a “latency” category. You’d miss a recurring complaint about slow response times and fail to prioritize a fix.LLM 可以加速你评估工作流的某些部分，但它们无法在你的专业知识至关重要的领域取代人类判断。例如，如果你让 LLM 处理所有的错误分析（即审查和标注追踪记录），你可能会忽略对你的产品至关重要的失败案例。假设用户在反馈中不断提到“卡顿”，但 LLM 将这些归入通用的“性能问题”类别，而不是创建一个“延迟”类别。你就会错过关于响应缓慢的反复投诉，并无法优先修复它。
That said, LLMs are valuable tools for accelerating certain parts of the evaluation workflow when used with oversight.话虽如此，LLM 在监督下使用时，是加速评估工作流某些部分的宝贵工具。
Here are some areas where LLMs can help:以下是 LLM 可以提供帮助的一些领域：
- First-pass axial coding: After you’ve open coded 30–50 traces yourself, use an LLM to organize your raw failure notes into proposed groupings. This helps you quickly spot patterns, but always review and refine the clusters yourself. Note: If you aren’t familiar with axial and open coding, see this faq.第一轮轴向编码：在你亲自开放编码了 30-50 条追踪记录后，使用 LLM 将你的原始失败笔记整理成建议的分组。这有助于你快速发现模式，但请务必亲自审查和完善这些簇。注意：如果你不熟悉轴向编码和开放编码，请参阅此常见问题解答。
- Mapping annotations to failure modes: Once you’ve defined failure categories, you can ask an LLM to suggest which categories apply to each new trace (e.g., “Given this annotation: [open_annotation] and these failure modes: [list_of_failure_modes], which apply?”).
将标注映射到失败模式：一旦你定义了失败类别，你可以要求 LLM 建议每个新追踪记录适用的类别（例如，“给出这个标注：[open_annotation] 和这些失败模式：[list_of_failure_modes]，哪些适用？”）。 - Suggesting prompt improvements: When you notice recurring problems, have the LLM propose concrete changes to your prompts. Review these suggestions before adopting any changes.
建议提示词改进：当你注意到反复出现的问题时，让 LLM 提出具体的提示词修改建议。在采用任何更改之前，请审查这些建议。 - Analyzing annotation data: Use LLMs or AI-powered notebooks to find patterns in your labels, such as “reports of lag increase 3x during peak usage hours” or “slow response times are mostly reported from users on mobile devices.”分析标注数据：使用 LLM 或 AI 驱动的笔记本查找标签中的模式，例如“关于卡顿的报告在高峰使用时段增加了 3 倍”或“响应缓慢大多由移动设备用户报告”。
However, you shouldn’t outsource these activities to an LLM:然而，你不应该将这些活动外包给 LLM：
- Initial open coding: Always read through the raw traces yourself at the start. This is how you discover new types of failures, understand user pain points, and build intuition about your data. Never skip this or delegate it.
初始开放编码：在开始时，一定要亲自通读原始追踪记录。这是你发现新类型失败、理解用户痛点并建立数据直觉的方式。永远不要跳过这一点或将其委派出去。 - Validating failure taxonomies: LLM-generated groupings need your review. For example, an LLM might group both “app crashes after login” and “login takes too long” under a single “login issues” category, even though one is a stability problem and the other is a performance problem. Without your intervention, you’d miss that these issues require different fixes.
验证失败分类法：LLM 生成的分组需要你的审查。例如，LLM 可能会将“登录后应用崩溃”和“登录耗时过长”都归入单一的“登录问题”类别，即使一个是稳定性问题，另一个是性能问题。如果没有你的干预，你就会错过这些问题需要不同修复方法的事实。 - Ground truth labeling: For any data used for testing/validating LLM-as-Judge evaluators, hand-validate each label. LLMs can make mistakes that lead to unreliable benchmarks.
基准事实标注：对于任何用于测试/验证 LLM-as-Judge 评估器的数据，请手动验证每个标签。LLM 可能会犯导致基准不可靠的错误。 - Root cause analysis: LLMs may point out obvious issues, but only human review will catch patterns like errors that occur in specific workflows or edge cases—such as bugs that happen only when users paste data from Excel.根本原因分析：LLM 可能会指出显而易见的问题，但只有人工审查才能捕捉到特定工作流或边缘情况中的错误模式——例如只有当用户从 Excel 粘贴数据时才会发生的错误。
In conclusion, start by examining data manually to understand what’s actually going wrong. Use LLMs to scale what you’ve learned, not to avoid looking at data.总之，从手动检查数据开始，以了解到底哪里出了问题。使用 LLM 来扩展你的所学，而不是为了避免查看数据。
Q: Should I stop writing prompts manually in favor of automated tools?
Automating prompt engineering can be tempting, but you should be skeptical of tools that promise to optimize prompts for you, especially in early stages of development. When you write a prompt, you are forced to clarify your assumptions and externalize your requirements. Good writing is good thinking 1. If you delegate this task to an automated tool too early, you risk never fully understanding your own requirements or the model’s failure modes.自动化提示词工程可能很诱人，但你应该对那些承诺为你优化提示词的工具持怀疑态度，尤其是在开发的早期阶段。当你编写提示词时，你被迫澄清你的假设并外化你的需求。好的写作即好的思考。如果你过早地将此任务委托给自动化工具，你将面临永远无法完全理解自身需求或模型失败模式的风险。
This is because automated prompt optimization typically hill-climb a predefined evaluation metric. It can refine a prompt to perform better on known failures, but it cannot discover new ones. Discovering new errors requires error analysis. Furthermore, research shows that evaluation criteria tends to shift after reviewing a model’s outputs, a phenomenon known as “criteria drift” 2. This means that evaluation is an iterative, human-driven sensemaking process, not a static target that can be set once and handed off to an optimizer.这是因为自动化提示词优化通常会在预定义的评估指标上进行爬坡。它可以细化提示词以在已知失败上表现更好，但它无法发现新的失败。发现新错误需要错误分析。此外，研究表明，在审查模型输出后，评估标准往往会发生偏移，这种现象被称为“标准漂移”。这意味着评估是一个迭代的、由人类驱动的意义构建过程，而不是一个可以设置一次并交给优化器的静态目标。
A pragmatic approach is to use LLMs to improve your prompt based on open coding (open-ended notes about traces). This way, you maintain a human in the loop who is looking at the data and externalizing their requirements. Once you have a high-quality set of evals, prompt optimization can be effective for that last mile of performance.一种务实的方法是基于开放编码（关于追踪记录的开放式笔记）使用 LLM 来改进你的提示词。通过这种方式，你保持了一个观察数据并外化其需求的人在回路中。一旦你拥有了一套高质量的评估集，提示词优化对于实现最后一公里的性能提升是有效的。
👉 Want to learn more about AI Evals? Check out our AI Evals course. It’s a live cohort with hands on exercises and office hours. Here is a 25% discount code for readers. 👈
Tools & Infrastructure工具与基础设施
Q: Should I build a custom annotation tool or use something off-the-shelf?
Build a custom annotation tool. This is the single most impactful investment you can make for your AI evaluation workflow. With AI-assisted development tools like Cursor or Lovable, you can build a tailored interface in hours. I often find that teams with custom annotation tools iterate ~10x faster.构建一个自定义标注工具。这是你为 AI 评估工作流所能做的最具影响力的投资。借助 Cursor 或 Lovable 等 AI 辅助开发工具，你可以在几小时内构建出一个量身定制的界面。我常发现，拥有自定义标注工具的团队迭代速度快约 10 倍。
Custom tools excel because:自定义工具之所以出色，是因为：
- They show all your context from multiple systems in one place它们能将来自多个系统的所有上下文集中在一处显示
- They can render your data in a product specific way (images, widgets, markdown, buttons, etc.)它们能以产品特定的方式渲染数据（图像、组件、Markdown、按钮等）
- They’re designed for your specific workflow (custom filters, sorting, progress bars, etc.)它们是专为你特定的工作流而设计的（自定义过滤器、排序、进度条等）
Off-the-shelf tools may be justified when you need to coordinate dozens of distributed annotators with enterprise access controls. Even then, many teams find the configuration overhead and limitations aren’t worth it.当需要协调数十名分布式标注员并进行企业级权限控制时，现成的工具或许是合理的选择。即便如此，许多团队仍发现其配置开销和局限性并不划算。
Isaac’s Anki flashcard annotation app shows the power of custom tools—handling 400+ results per query with keyboard navigation and domain-specific evaluation criteria that would be nearly impossible to configure in a generic tool.Isaac 的 Anki 抽认卡标注应用展示了自定义工具的力量——它通过键盘导航和领域特定的评估标准，每条查询可处理 400 多个结果，这在通用工具中几乎是不可能配置出来的。
Watch “Building Eval Tools with FastHTML” on YouTube在 YouTube 上观看“使用 FastHTML 构建评估工具”
Q: What makes a good custom interface for reviewing LLM outputs?
Great interfaces make human review fast, clear, and motivating. We recommend building your own annotation tool customized to your domain. The following features are possible enhancements we’ve seen work well, but you don’t need all of them. The screenshots shown are illustrative examples to clarify concepts. In practice, I rarely implement all these features in a single app. It’s ultimately a judgment call based on your specific needs and constraints.优秀的界面能让人工审核变得快速、清晰且富有动力。我们建议构建专属于你所在领域的自定义标注工具。以下功能是我们认为效果良好的潜在增强项，但你无需全部采用。所展示的截图仅为阐明概念的示意示例。在实践中，我很少会在单个应用中实现所有这些功能。这最终取决于你的具体需求和约束条件，需要你自行判断。
1. Render Traces Intelligently, Not Generically:1. 智能渲染追踪记录，而非通用渲染：
Present the trace in a way that’s intuitive for the domain. If you’re evaluating generated emails, render them to look like emails. If the output is code, use syntax highlighting. Allow the reviewer to see the full trace (user input, tool calls, and LLM reasoning), but keep less important details in collapsed sections that can be expanded. Here is an example of a custom annotation tool for reviewing real estate assistant emails:以该领域直观的方式呈现追踪记录。如果你正在评估生成的电子邮件，请将其渲染成邮件的样子。如果输出是代码，请使用语法高亮。允许审核员查看完整的追踪记录（用户输入、工具调用和 LLM 推理），但将不太重要的细节放在可展开的折叠部分中。以下是一个用于审核房地产助手邮件的自定义标注工具示例：
2. Show Progress and Support Keyboard Navigation:2. 显示进度并支持键盘导航：
Keep reviewers in a state of flow by minimizing friction and motivating completion. Include progress indicators (e.g., “Trace 45 of 100”) to keep the review session bounded and encourage completion. Enable hotkeys for navigating between traces (e.g., N for next), applying labels, and saving notes quickly. Below is an illustration of these features:通过减少摩擦和激励完成任务，让审核员保持心流状态。加入进度指示器（例如“第 45/100 条追踪记录”）以限定审核会话并鼓励完成。启用快捷键以便在追踪记录间导航（例如用 N 键进入下一条）、应用标签并快速保存备注。以下是这些功能的示意图：
3. Trace navigation through clustering, filtering, and search:3. 通过聚类、过滤和搜索进行追踪记录导航：
Allow reviewers to filter traces by metadata or search by keywords. Semantic search helps find conceptually similar problems. Clustering similar traces (like grouping by user persona) lets reviewers spot recurring issues and explore hypotheses. Below is an illustration of these features:允许审核员按元数据过滤追踪记录或按关键词搜索。语义搜索有助于发现概念上相似的问题。对相似的追踪记录进行聚类（例如按用户画像分组）可以让审核员发现反复出现的问题并探索假设。以下是这些功能的示意图：
4. Prioritize labeling traces you think might be problematic:4. 优先标注你认为可能有问题的追踪记录：
Surface traces flagged by guardrails, CI failures, or automated evaluators for review. Provide buttons to take actions like adding to datasets, filing bugs, or re-running pipeline tests. Display relevant context (pipeline version, eval scores, reviewer info) directly in the interface to minimize context switching. Below is an illustration of these ideas:将护栏机制、CI 失败或自动化评估器标记出的追踪记录呈现出来以供审核。提供按钮以执行诸如添加到数据集、提交 Bug 或重新运行流水线测试等操作。直接在界面中显示相关上下文（流水线版本、评估分数、审核员信息），以最大限度地减少上下文切换。以下是这些想法的示意图：
General Principle: Keep it minimal通用原则：保持极简
Keep your annotation interface minimal. Only incorporate these ideas if they provide a benefit that outweighs the additional complexity and maintenance overhead.保持你的标注界面极简。只有在这些想法带来的收益超过其增加的复杂性和维护开销时，才将其纳入。
Q: What gaps in eval tooling should I be prepared to fill myself?
Most eval tools handle the basics well: logging complete traces, tracking metrics, prompt playgrounds, and annotation queues. These are table stakes. Here are four areas where you’ll likely need to supplement existing tools.大多数评估工具都能很好地处理基础功能：记录完整追踪、跟踪指标、提示词演练场和标注队列。这些是基本门槛。以下是你可能需要补充现有工具的四个领域。
Watch for vendors addressing these gaps: it’s a strong signal they understand practitioner needs.关注那些正在填补这些空白的供应商：这是一个强有力的信号，表明他们了解从业者的需求。
1. Error Analysis and Pattern Discovery1. 错误分析与模式发现
After reviewing traces where your AI fails, can your tooling automatically cluster similar issues? For instance, if multiple traces show the assistant using casual language for luxury clients, you need something that recognizes this broader “persona-tone mismatch” pattern. We recommend building capabilities that use AI to suggest groupings, rewrite your observations into clearer failure taxonomies, help find similar cases through semantic search, etc.在回顾 AI 失败的追踪记录后，你的工具能否自动聚类相似的问题？例如，如果多条追踪记录显示助手对高端客户使用了随意的语言，你需要一种能识别这种更广泛的“人设语气不匹配”模式的工具。我们建议构建能够利用 AI 建议分组、将你的观察重写为更清晰的失败分类法、通过语义搜索帮助查找类似案例等功能的工具。
2. AI-Powered Assistance Throughout the Workflow2. 全流程 AI 辅助
The most effective workflows use AI to accelerate every stage of evaluation. During error analysis, you want an LLM helping categorize your open-ended observations into coherent failure modes. For example, you might annotate several traces with notes like “wrong tone for investor,” “too casual for luxury buyer,” etc. Your tooling should recognize these as the same underlying pattern and suggest a unified “persona-tone mismatch” category.最高效的工作流会利用 AI 加速评估的每个阶段。在错误分析过程中，你需要一个 LLM 来帮助将你的开放式观察分类为连贯的失败模式。例如，你可能会用“对投资者语气不对”、“对豪宅买家太随意”等备注标注多条追踪记录。你的工具应该识别出这些属于同一个潜在模式，并建议一个统一的“人设语气不匹配”类别。
You’ll also want AI assistance in proposing fixes. After identifying 20 cases where your assistant omits pet policies from property summaries, can your workflow analyze these failures and suggest specific prompt modifications? Can it draft refinements to your SQL generation instructions when it notices patterns of missing WHERE clauses?你还需要 AI 协助提出修复方案。在确定了 20 个你的助手从房产摘要中遗漏宠物政策的案例后，你的工作流能否分析这些失败并建议具体的提示词修改？当它注意到缺少 WHERE 子句的模式时，能否起草对你 SQL 生成指令的优化建议？
Good workflows also help you conduct data analysis of your annotations and traces. I like using notebooks with AI in-the-loop like Julius or Hex. These help me discover insights like “location ambiguity errors spike 3x when users mention neighborhood names” or “tone mismatches occur 80% more often in email generation than other modalities.”好的工作流还能帮助你对标注和追踪记录进行数据分析。我喜欢使用像 Julius 或 Hex 这样带有 AI 循环的笔记本。它们能帮我发现诸如“当用户提到社区名称时，位置歧义错误会激增 3 倍”或“语气不匹配在邮件生成中的发生率比其他模态高 80%”这样的见解。
3. Custom Evaluators Over Generic Metrics3. 优于通用指标的自定义评估器
Be prepared to build most of your evaluators from scratch. Generic metrics like “hallucination score” or “helpfulness rating” rarely capture what actually matters for your application—like proposing unavailable showing times or omitting budget constraints from emails. In our experience, successful teams spend most of their effort on application-specific metrics.准备好从零开始构建大部分评估器。像“幻觉分数”或“有用性评分”这样的通用指标很少能捕捉到对你应用真正重要的事情——比如提议了不可用的看房时间，或在邮件中遗漏了预算限制。根据我们的经验，成功的团队会将大部分精力花在应用特定的指标上。
4. APIs That Support Custom Annotation Apps4. 支持自定义标注应用的 API
Custom annotation interfaces work best for most teams. This requires observability platforms with thoughtful APIs. I often have to build my own libraries and abstractions just to make bulk data export manageable. You shouldn’t have to paginate through thousands of requests or handle timeout-prone endpoints just to get your data. Look for platforms that provide true bulk export capabilities and, crucially, APIs that let you write annotations back efficiently.对于大多数团队来说，自定义标注界面效果最好。这需要具备深思熟虑 API 的可观测性平台。我经常不得不构建自己的库和抽象层，仅仅是为了让批量数据导出变得可控。你不应该为了获取数据而不得不分页浏览成千上万个请求，或处理容易超时的端点。寻找那些提供真正批量导出功能，且至关重要的是，提供能让你高效回写标注的 API 的平台。
Q: What’s your favorite eval vendor?
Eval tools are in an intensely competitive space. It would be futile to compare their features. If I tried to do such an analysis, it would be invalidated in a week! Vendors I encounter the most organically in my work are: Langsmith, Arize and Braintrust.评估工具处于一个竞争极其激烈的领域。比较它们的功能是徒劳的。如果我试图进行这样的分析，它在一周内就会失效！我在工作中接触最多的供应商是：Langsmith、Arize 和 Braintrust。
When I help clients with vendor selection, the decision weighs heavily towards who can offer the best support, as opposed to purely features. This changes depending on size of client, use case, etc. Yes - it’s mainly the human factor that matters, and dare I say, vibes.当我协助客户进行供应商选择时，决策很大程度上取决于谁能提供最好的支持，而不是仅仅看功能。这会根据客户规模、用例等因素而改变。没错——主要是人为因素起作用，甚至可以说，是“感觉”。
I have no favorite vendor. At the core, their features are very similar - and I often build custom tools on top of them to fit my needs.我没有最喜欢的供应商。从核心上看，它们的功能非常相似——我经常在它们之上构建自定义工具以满足我的需求。
Here is a video series that has a live commentary on the relative strengths and weaknesses of the three aforementioned vendors.这是一个视频系列，对上述三家供应商的相对优缺点进行了现场评论。
Q: How should I version and manage prompts?
There is an unavoidable tension between keeping prompts close to the code vs. an environment that non-technical stakeholders can access.在将提示词保留在代码附近与提供给非技术利益相关者访问的环境之间，存在一种不可避免的张力。
My preferred approach is storing prompts in Git. This treats them as software artifacts that are versioned, reviewed, and deployed atomically with the application code. While the Git command line is unfriendly for non-technical folks, the GitHub web interface and the GitHub Desktop app make it very approachable. When I was working at GitHub, I worked with many non-technical professionals, including lawyers and accountants, who used these tools effectively. Here is a blog post aimed at non-technical folks to get started.我首选的方法是将提示词存储在 Git 中。这将其视为软件制品，进行版本控制、审核，并与应用程序代码原子化地部署。虽然 Git 命令行对非技术人员不友好，但 GitHub Web 界面和 GitHub Desktop 应用使其变得非常易用。我在 GitHub 工作时，曾与许多非技术专业人士（包括律师和会计师）共事，他们都能有效地使用这些工具。这是一篇旨在帮助非技术人员入门的博文。
Alternatively, most vendors in the LLM tooling space, such as observability platforms like Arize, Braintrust, and LangSmith, offer dedicated prompt management tools. These are accessible for rapid iteration but risk creating additional layers of indirection.或者，LLM 工具领域的大多数供应商，如 Arize、Braintrust 和 LangSmith 等可观测性平台，都提供专门的提示词管理工具。这些工具便于快速迭代，但存在引入额外间接层的风险。
Why prompt management tools often fall short: AI products typically involve many moving parts: tools, RAG, agents, etc. Prompt management tools are inherently limiting because they can’t easily execute your application’s code. Even when they can, there’s often significant indirection involved, making it difficult to test prompts with your system’s capabilities.为什么提示词管理工具往往力不从心：AI 产品通常涉及许多动态部分：工具、RAG、代理等。提示词管理工具本质上是受限的，因为它们无法轻易执行你的应用程序代码。即使可以，也往往涉及大量的间接操作，使得用你系统的能力来测试提示词变得困难。
When possible, a notebook provides a great solution for prompt experimentation If you have Python entry points into your codebase or your codebase is written in Python, Jupyter notebooks are particularly powerful for this purpose. You can experiment with prompts and iterate on your actual AI agents with their full tool and RAG capabilities. This makes it much easier to understand how your system works in practice. Additionally, you can create widgets and small user interfaces within notebooks, giving you the best of both worlds for experimentation and iteration. To see what this looks like in practice, Teresa Torres gives a fantastic, hands-on walkthrough of how she, as a PM, used notebooks for the entire eval and experimentation lifecycle:在可能的情况下，笔记本为提示词实验提供了一个很好的解决方案。如果你的代码库有 Python 入口点，或者你的代码库是用 Python 编写的，Jupyter 笔记本在此目的上特别强大。你可以通过实验提示词并利用其完整的工具和 RAG 能力来迭代你的实际 AI 代理。这使得理解系统在实践中如何工作变得容易得多。此外，你可以在笔记本内创建小部件和小型用户界面，从而在实验和迭代方面兼得鱼与熊掌。要了解这在实践中是什么样子，Teresa Torres 提供了一个精彩的实操演练，展示了她作为一名产品经理（PM）如何将笔记本用于整个评估和实验生命周期：
Watch “From Noob to Automated Evals In A Week (as a PM) w/Teresa Torres” on YouTube在 YouTube 上观看“从小白到自动化评估（作为 PM）w/Teresa Torres”
If notebooks are not feasible for your code base, an integrated prompt environment can be effective for experimentation. Either way, I prefer to version and manage prompts in Git.如果笔记本对于你的代码库不可行，集成的提示词环境对于实验也是有效的。无论哪种方式，我都倾向于在 Git 中对提示词进行版本控制和管理。
Q: What should go in the system prompt vs. the user prompt?
Nothing beats experimentation. Test both approaches (ideally with evals) with your specific model and use case. Models handle system and user prompts differently, and these differences vary by provider and model version. Move instructions between prompts and measure which produces better results for your specific task.没有什么比实验更重要。用你特定的模型和用例测试这两种方法（最好通过评估）。模型处理系统提示词和用户提示词的方式不同，这些差异因提供商和模型版本而异。在提示词之间移动指令，并衡量哪种方式能为你的特定任务产生更好的结果。
General guidelines: Put static instructions and role definitions in the system prompt. Put dynamic content, examples, and task-specific details in the user prompt. Think of the system prompt as the model’s constitution—rules that apply across all requests. Include identity, behavioral constraints, output format requirements, and standing instructions: “You are a medical assistant. Never provide diagnoses. Always recommend consulting a healthcare provider.”通用准则：将静态指令和角色定义放在系统提示词中。将动态内容、示例和任务特定细节放在用户提示词中。将系统提示词视为模型的宪法——适用于所有请求的规则。包括身份、行为约束、输出格式要求和常设指令：“你是一名医疗助手。严禁提供诊断。始终建议咨询医疗保健提供者。”
The user prompt contains the actual task, relevant context, few-shot examples, and data to process. Documents for analysis, query-specific variations, and contextual information belong here. When the distinction feels unclear, prefer the user prompt. It’s more portable across models and easier to debug.用户提示词包含实际任务、相关上下文、少样本示例和要处理的数据。分析文档、查询特定的变体和上下文信息都属于这里。当两者区别不明确时，优先选择用户提示词。它在不同模型间更具可移植性，也更容易调试。
Production & Deployment生产与部署
Q: How are evaluations used differently in CI/CD vs. monitoring production?
CI evals protect against known regressions before deployment. Online monitoring find failures in production traffic and estimate how often they occur.CI 评估在部署前防范已知回归。在线监控则用于发现生产流量中的故障并估计其发生频率。
Evals in CICI 中的评估
Test datasets for CI are small (in many cases 100+ examples) and purpose-built. Examples cover core features, regression tests for past bugs, and known edge cases. Since CI tests are run frequently, the cost of each test has to be carefully considered (that’s why you carefully curate the dataset). Favor assertions or other deterministic checks over LLM-as-judge evaluators.CI 的测试数据集通常很小（在许多情况下为 100+ 个示例）且专为特定目的构建。示例涵盖核心功能、过去 Bug 的回归测试以及已知的边界情况。由于 CI 测试运行频繁，必须仔细考虑每次测试的成本（这就是为什么你要精心策划数据集）。优先使用断言或其他确定性检查，而非“LLM 作为评判者”的评估器。
Onnline monitoring for production生产环境的在线监控
For evaluating production traffic, you can sample live traces and run evaluators against them asynchronously. Since you usually lack reference outputs on production data, you might rely more on on more expensive reference-free evaluators like LLM-as-judge. Additionally, track confidence intervals for production metrics. If the lower bound crosses your threshold, investigate further.对于生产流量的评估，你可以对实时追踪记录进行采样，并异步运行评估器。由于生产数据通常缺乏参考输出，你可能更依赖于昂贵的无参考评估器，如“LLM 作为评判者”。此外，跟踪生产指标的置信区间。如果下限跨越了你的阈值，请进行深入调查。
Connect the two systems连接这两个系统
These two systems are complementary: when production monitoring reveals new failure patterns through error analysis and evals, add representative examples to your CI dataset. This mitigates regressions on new issues.这两个系统是互补的：当生产监控通过错误分析和评估揭示出新的失败模式时，将代表性示例添加到你的 CI 数据集中。这可以缓解新问题带来的回归。
Here is a visual that helps contrast the approaches.这是一张有助于对比这些方法的图示。
Q: What’s the difference between guardrails & evaluators?
Guardrails are inline safety checks that sit directly in the request/response path. They validate inputs or outputs before anything reaches a user, so they typically are:护栏机制是直接位于请求/响应路径中的内联安全检查。它们在任何内容到达用户之前验证输入或输出，因此它们通常是：
- Fast and deterministic – typically a few milliseconds of latency budget.快速且确定性的——通常只有几毫秒的延迟预算。
- Simple and explainable – regexes, keyword block-lists, schema or type validators, lightweight classifiers.简单且可解释的——正则表达式、关键词黑名单、模式或类型验证器、轻量级分类器。
- Targeted at clear-cut, high-impact failures – PII leaks, profanity, disallowed instructions, SQL injection, malformed JSON, invalid code syntax, etc.针对明确的、高影响的失败——PII 泄露、亵渎、禁止指令、SQL 注入、格式错误的 JSON、无效的代码语法等。
If a guardrail triggers, the system can redact, refuse, or regenerate the response. Because these checks are user-visible when they fire, false positives are treated as production bugs; teams version guardrail rules, log every trigger, and monitor rates to keep them conservative.如果触发了护栏，系统可以对响应进行脱敏、拒绝或重新生成。由于这些检查在触发时用户可见，误报会被视为生产 Bug；团队会对护栏规则进行版本控制，记录每次触发，并监控触发率以保持其保守性。
On the other hand, evaluators typically run after a response is produced. Evaluators measure qualities that simple rules cannot, such as factual correctness, completeness, etc. Their verdicts feed dashboards, regression tests, and model-improvement loops, but they do not block the original answer.另一方面，评估器通常在响应生成后运行。评估器衡量简单规则无法衡量的质量，如事实准确性、完整性等。它们的判定结果为仪表板、回归测试和模型改进循环提供输入，但它们不会阻塞原始答案。
Evaluators are usually run asynchronously or in batch to afford heavier computation such as a LLM-as-a-Judge. Inline use of an LLM-as-Judge is possible only when the latency budget and reliability targets allow it. Slow LLM judges might be feasible in a cascade that runs on the minority of borderline cases.评估器通常异步或批量运行，以负担更重的计算，例如“LLM 作为评判者”。仅当延迟预算和可靠性目标允许时，才可能内联使用“LLM 作为评判者”。缓慢的 LLM 评判者可能适用于在少数边缘案例上运行的级联中。
Apply guardrails for immediate protection against objective failures requiring intervention. Use evaluators for monitoring and improving subjective or nuanced criteria. Together, they create layered protection.应用护栏以实现针对需要干预的客观失败的即时保护。使用评估器来监控和改进主观或细微的标准。两者结合，形成分层保护。
Word of caution: Do not use llm guardrails off the shelf blindly. Always look at the prompt.警告：不要盲目使用现成的 LLM 护栏。务必查看提示词。
Q: Can my evaluators also be used to automatically fix or correct outputs in production?
Yes, but only a specific subset of them. This is the distinction between an evaluator and a guardrail that we previously discussed. As a reminder:是的，但仅限于其中的特定子集。这就是我们之前讨论过的评估器与护栏之间的区别。提醒一下：
- Evaluators typically run asynchronously after a response has been generated. They measure quality but don’t interfere with the user’s immediate experience.
评估器通常在响应生成后异步运行。它们衡量质量，但不干扰用户的即时体验。 - Guardrails run synchronously in the critical path of the request, before the output is shown to the user. Their job is to prevent high-impact failures in real-time.护栏在请求的关键路径中同步运行，在输出显示给用户之前。它们的工作是实时防止高影响的失败。
There are two important decision criteria for deciding whether to use an evaluator as a guardrail:决定是否将评估器用作护栏有两个重要的决策标准：
Latency & Cost: Can the evaluator run fast enough and cheaply enough in the critical request path without degrading user experience?延迟与成本：评估器能否在关键请求路径中足够快速且廉价地运行，而不降低用户体验？
Error Rate Trade-offs: What’s the cost-benefit balance between false positives (blocking good outputs and frustrating users) versus false negatives (letting bad outputs reach users and causing harm)? In high-stakes domains like medical advice, false negatives may be more costly than false positives. In creative applications, false positives that block legitimate creativity may be more harmful than occasional quality issues.错误率权衡：误报（阻塞了好的输出并令用户沮丧）与漏报（让坏的输出到达用户并造成伤害）之间的成本效益平衡如何？在医疗建议等高风险领域，漏报的代价可能高于误报。在创意应用中，阻塞合法创意的误报可能比偶尔的质量问题更有害。
Most guardrails are designed to be fast (to avoid harming user experience) and have a very low false positive rate (to avoid blocking valid responses). For this reason, you would almost never use a slow or non-deterministic LLM-as-Judge as a synchronous guardrail. However, these tradeoffs might be different for your use case.大多数护栏的设计都是快速的（以避免损害用户体验）并具有极低的误报率（以避免阻塞有效的响应）。因此，你几乎永远不会将缓慢或非确定性的“LLM 作为评判者”用作同步护栏。然而，这些权衡对于你的用例可能有所不同。
Q: How much time should I spend on model selection?
Many developers fixate on model selection as the primary way to improve their LLM applications. Start with error analysis to understand your failure modes before considering model switching. As Hamel noted in office hours, “I suggest not thinking of switching model as the main axes of how to improve your system off the bat without evidence. Does error analysis suggest that your model is the problem?”许多开发者专注于模型选择，将其作为改进 LLM 应用的主要方式。在考虑更换模型之前，请先从错误分析开始，以了解你的失败模式。正如 Hamel 在办公时间所指出的：“我建议不要在没有证据的情况下，直接将切换模型作为改进系统的主要手段。错误分析是否表明模型就是问题所在？”
Domain-Specific Applications领域特定应用
Q: Is RAG dead?
Question: Should I avoid using RAG for my AI application after reading that “RAG is dead” for coding agents?问题：在读到“RAG 已死”对于编码代理的说法后，我应该避免在我的 AI 应用中使用 RAG 吗？
Many developers are confused about when and how to use RAG after reading articles claiming “RAG is dead.” Understanding what RAG actually means versus the narrow marketing definitions will help you make better architectural decisions for your AI applications.许多开发者在读到声称“RAG 已死”的文章后，对何时以及如何使用 RAG 感到困惑。理解 RAG 的实际含义而非狭隘的营销定义，将有助于你为 AI 应用做出更好的架构决策。
The viral article claiming RAG is dead specifically argues against using naive vector database retrieval for autonomous coding agents, not RAG as a whole. This is a crucial distinction that many developers miss due to misleading marketing.声称 RAG 已死的病毒式文章专门反对将简单的向量数据库检索用于自主编码代理，而非否定整个 RAG。这是一个关键的区别，由于误导性的营销，许多开发者忽略了这一点。
RAG simply means Retrieval-Augmented Generation - using retrieval to provide relevant context that improves your model’s output. The core principle remains essential: your LLM needs the right context to generate accurate answers. The question isn’t whether to use retrieval, but how to retrieve effectively.RAG 仅仅意味着检索增强生成——利用检索来提供相关上下文，从而改善模型的输出。其核心原则依然必不可少：你的 LLM 需要正确的上下文来生成准确的答案。问题不在于是否使用检索，而在于如何有效地检索。
For coding applications, naive vector similarity search often fails because code relationships are complex and contextual. Instead of abandoning retrieval entirely, modern coding assistants like Claude Code still uses retrieval —they just employ agentic search instead of relying solely on vector databases, similar to how human developers work.对于编码应用，简单的向量相似度搜索往往会失败，因为代码关系复杂且具有上下文相关性。现代编码助手（如 Claude Code）并没有完全放弃检索，它们只是采用了代理式搜索，而不是仅仅依赖向量数据库，这与人类开发者的工作方式类似。
You have multiple retrieval strategies available, ranging from simple keyword matching to embedding similarity to LLM-powered relevance filtering. The optimal approach depends on your specific use case, data characteristics, and performance requirements. Many production systems combine multiple strategies or use multi-hop retrieval guided by LLM agents.你有多种检索策略可供选择，从简单的关键词匹配到嵌入相似度，再到 LLM 驱动的相关性过滤。最优方法取决于你的具体用例、数据特征和性能要求。许多生产系统结合了多种策略，或使用由 LLM 代理引导的多跳检索。
Unfortunately, “RAG” has become a buzzword with no shared definition. Some people use it to mean any retrieval system, others restrict it to vector databases. Focus on the ultimate goal: getting your LLM the context it needs to succeed. Whether that’s through vector search, agentic exploration, or hybrid approaches is a product and engineering decision.不幸的是，“RAG”已经成为一个没有统一定义的流行语。有些人用它指代任何检索系统，另一些人则将其限定为向量数据库。专注于最终目标：让你的 LLM 获得成功所需的上下文。无论是通过向量搜索、代理式探索还是混合方法，这都是产品和工程决策。
Rather than following categorical advice to avoid or embrace RAG, experiment with different retrieval approaches and measure what works best for your application. For more info on RAG evaluation and optimization, see this series of posts.与其遵循避免或拥抱 RAG 的绝对建议，不如尝试不同的检索方法，并衡量哪种方法最适合你的应用。有关 RAG 评估和优化的更多信息，请参阅此系列文章。
Q: How should I approach evaluating my RAG system?
RAG systems have two distinct components that require different evaluation approaches: retrieval and generation.RAG 系统有两个截然不同的组件，需要不同的评估方法：检索和生成。
Start with retrieval evaluation从检索评估开始
The retrieval component is a search problem. Evaluate it using traditional information retrieval (IR) metrics. Common examples include Recall@k (of all relevant documents, how many did you retrieve in the top k?), Precision@k (of the k documents retrieved, how many were relevant?), or MRR (how high up was the first relevant document?). The specific metrics you choose depend on your use case. These metrics are pure search metrics that measure whether you’re finding the right documents (more on this below).检索组件是一个搜索问题。使用传统的信息检索 (IR) 指标对其进行评估。常见的例子包括 Recall@k（在所有相关文档中，你在前 k 个结果中检索到了多少？）、Precision@k（在检索到的 k 个文档中，有多少是相关的？）或 MRR（第一个相关文档排在多靠前的位置？）。你选择的具体指标取决于你的用例。这些指标是纯粹的搜索指标，用于衡量你是否找到了正确的文档（详见下文）。
To evaluate retrieval, create a dataset of queries paired with their relevant documents. Generate this synthetically by taking documents from your corpus, extracting key facts, then generating questions those facts would answer. This reverse process gives you query-document pairs for measuring retrieval performance without manual annotation.要评估检索，请创建一个由查询及其相关文档组成的数据集。通过从你的语料库中提取文档，提取关键事实，然后生成这些事实可以回答的问题来综合生成此数据集。这个逆向过程为你提供了查询-文档对，无需人工标注即可衡量检索性能。
Next, evaluate generation接下来，评估生成
For the generation component, check how well the LLM uses the retrieved context and whether it answers the question. Use error analysis to identify failure modes, collect human labels, build targeted LLM judges, and validate those judges against human annotations.对于生成组件，检查 LLM 对检索到的上下文的使用情况，以及它是否回答了问题。使用错误分析来识别失败模式，收集人工标签，构建有针对性的 LLM 评判者，并根据人工标注验证这些评判者。
Jason Liu’s “There Are Only 6 RAG Evals” provides a framework that maps well to this separation. His Tier 1 covers traditional IR metrics for retrieval. Tiers 2 and 3 evaluate relationships between Question, Context, and Answer. These include whether the context is relevant (C|Q), whether the answer is faithful to context (A|C), and whether the answer addresses the question (A|Q).Jason Liu 的“只有 6 种 RAG 评估”提供了一个与这种分离非常吻合的框架。他的第一层涵盖了用于检索的传统 IR 指标。第二层和第三层评估问题、上下文和答案之间的关系。这些包括上下文是否相关 (C|Q)、答案是否忠实于上下文 (A|C) 以及答案是否解决了问题 (A|Q)。
In addition to Jason’s six evals, error analysis on your specific data may reveal domain-specific failure modes that warrant their own metrics. For example, a medical RAG system might consistently fail to distinguish between drug dosages for adults versus children, or a legal RAG might confuse jurisdictional boundaries. These patterns emerge only through systematic review of actual failures. Once identified, you can create targeted evaluators for these specific issues beyond the general framework.除了 Jason 的六项评估外，对你特定数据的错误分析可能会揭示出需要其自身指标的领域特定失败模式。例如，医疗 RAG 系统可能持续无法区分成人与儿童的药物剂量，或者法律 RAG 可能混淆司法管辖区边界。这些模式只有通过对实际失败的系统性回顾才能发现。一旦识别出来，你就可以为这些特定问题创建超出通用框架的目标评估器。
Finally, when implementing Jason’s Tier 2 and 3 metrics, don’t just use prompts off the shelf. The standard LLM-as-judge process requires several steps: error analysis, prompt iteration, creating labeled examples, and measuring your judge’s accuracy against human labels. Once you know your judge’s True Positive and True Negative rates, you can correct its estimates to determine the actual failure rate in your system. Skip this validation and your judges may not reflect your actual quality criteria.最后，在实现 Jason 的第二层和第三层指标时，不要只是直接使用现成的提示词。标准的“LLM 作为评判者”流程需要几个步骤：错误分析、提示词迭代、创建标注示例以及根据人工标签衡量你的评判者的准确性。一旦你知道了你的评判者的真阳性和真阴性率，你就可以修正其估计值，以确定系统中实际的失败率。跳过此验证，你的评判者可能无法反映你实际的质量标准。
In summary, debug retrieval first using IR metrics, then tackle generation quality using properly validated LLM judges.总之，先使用 IR 指标调试检索，然后使用经过适当验证的 LLM 评判者来解决生成质量问题。
Q: How do I choose the right chunk size for my document processing tasks?
Unlike RAG, where chunks are optimized for retrieval, document processing assumes the model will see every chunk. The goal is to split text so the model can reason effectively without being overwhelmed. Even if a document fits within the context window, it might be better to break it up. Long inputs can degrade performance due to attention bottlenecks, especially in the middle of the context. Two task types require different strategies:与 RAG（其中分块针对检索进行了优化）不同，文档处理假设模型将看到每一个分块。目标是分割文本，使模型能够有效推理而不会不堪重负。即使文档适合上下文窗口，将其拆分也可能更好。长输入可能会因注意力瓶颈而降低性能，特别是在上下文的中间部分。两种任务类型需要不同的策略：
1. Fixed-Output Tasks → Large Chunks1. 固定输出任务 → 大分块
These are tasks where the output length doesn’t grow with input: extracting a number, answering a specific question, classifying a section. For example:这些任务的输出长度不会随输入增长：提取数字、回答特定问题、对章节分类。例如：
- “What’s the penalty clause in this contract?”“合同中的惩罚条款是什么？”
- “What was the CEO’s salary in 2023?”“CEO 在 2023 年的薪水是多少？”
Use the largest chunk (with caveats) that likely contains the answer. This reduces the number of queries and avoids context fragmentation. However, avoid adding irrelevant text. Models are sensitive to distraction, especially with large inputs. The middle parts of a long input might be under-attended. Furthermore, if cost and latency are a bottleneck, you should consider preprocessing or filtering the document (via keyword search or a lightweight retriever) to isolate relevant sections before feeding a huge chunk.使用可能包含答案的最大分块（需注意）。这减少了查询数量并避免了上下文碎片化。然而，避免添加不相关的文本。模型对干扰很敏感，尤其是在输入量很大的情况下。长输入的中间部分可能没有得到充分关注。此外，如果成本和延迟是瓶颈，你应该考虑在输入巨大分块之前（通过关键词搜索或轻量级检索器）对文档进行预处理或过滤，以隔离相关部分。
2. Expansive-Output Tasks → Smaller Chunks2. 扩展输出任务 → 小分块
These include summarization, exhaustive extraction, or any task where output grows with input. For example:这些包括摘要、穷举式提取或任何输出随输入增长的任务。例如：
- “Summarize each section”“总结每一节”
- “List all customer complaints”“列出所有客户投诉”
In these cases, smaller chunks help preserve reasoning quality and output completeness. The standard approach is to process each chunk independently, then aggregate results (e.g., map-reduce). When sizing your chunks, try to respect content boundaries like paragraphs, sections, or chapters. Chunking also helps mitigate output limits. By breaking the task into pieces, each piece’s output can stay within limits.在这些情况下，较小的分块有助于保持推理质量和输出完整性。标准方法是独立处理每个分块，然后聚合结果（例如 Map-Reduce）。在确定分块大小时，尽量尊重内容边界，如段落、章节或篇章。分块还有助于缓解输出限制。通过将任务拆解为小块，每个片段的输出都可以保持在限制范围内。
General Guidance通用指导
It’s important to recognize why chunk size affects results. A larger chunk means the model has to reason over more information in one go – essentially, a heavier cognitive load. LLMs have limited capacity to retain and correlate details across a long text. If too much is packed in, the model might prioritize certain parts (commonly the beginning or end) and overlook or “forget” details in the middle. This can lead to overly coarse summaries or missed facts. In contrast, a smaller chunk bounds the problem: the model can pay full attention to that section. You are trading off global context for local focus.认识到分块大小为何影响结果非常重要。较大的分块意味着模型必须一次性对更多信息进行推理——本质上，认知负荷更重。LLM 在长文本中保留和关联细节的能力有限。如果填充内容过多，模型可能会优先处理某些部分（通常是开头或结尾），而忽略或“忘记”中间的细节。这可能导致过于粗糙的摘要或遗漏事实。相比之下，较小的分块限定了问题：模型可以全神贯注于该部分。你是在用全局上下文换取局部聚焦。
No rule of thumb can perfectly determine the best chunk size for your use case – you should validate with experiments. The optimal chunk size can vary by domain and model. I treat chunk size as a hyperparameter to tune.没有任何经验法则可以完美确定适合你用例的最佳分块大小——你应该通过实验进行验证。最佳分块大小因领域和模型而异。我将分块大小视为一个需要调整的超参数。
Q: How do I debug multi-turn conversation traces?
Start simple. Check if the whole conversation met the user’s goal with a pass/fail judgment. Look at the entire trace and focus on the first upstream failure. Read the user-visible parts first to understand if something went wrong. Only then dig into the technical details like tool calls and intermediate steps.从简单开始。通过通过/失败判定检查整个对话是否达到了用户的目标。查看整个追踪记录，并专注于第一个上游故障。先阅读用户可见的部分，以了解是否出了问题。只有这样，再深入研究工具调用和中间步骤等技术细节。
Multi-agent trace logging多代理追踪记录日志
For multi-agent flows, assign a session or trace ID to each user request and log every message with its source (which agent or tool), trace ID, and position in the sequence. This lets you reconstruct the full path from initial query to final result across all agents.对于多代理流程，为每个用户请求分配一个会话或追踪 ID，并记录每条消息及其来源（哪个代理或工具）、追踪 ID 以及在序列中的位置。这使你能够重建从初始查询到跨所有代理的最终结果的完整路径。
Annotation strategy标注策略
Annotate only the first failure in the trace at first. Downstream failures often cascade from the first issue, so fixing the upstream failure can resolve the dependent ones. As you gain experience, you can annotate independent failure modes within the same trace to speed up error analysis.起初只标注追踪记录中的第一个故障。下游故障往往是由第一个问题级联引发的，因此修复上游故障可以解决依赖它的故障。随着经验的积累，你可以标注同一追踪记录内独立的失败模式，以加快错误分析。
Simplify when possible尽可能简化
When you find a failure, reproduce it with the simplest possible test case. Here’s an example: suppose a shopping bot gives the wrong return policy on turn 4 of a conversation. Before diving into the full multi-turn complexity, simplify it to a single turn: “What is the return window for product X1000?” If it still fails, you’ve proven the error isn’t about conversation context - it’s likely a basic retrieval or knowledge issue you can debug more easily.当你发现故障时，用最简单的测试用例复现它。这是一个例子：假设购物机器人在对话的第 4 轮给出了错误的退货政策。在深入研究复杂的多轮对话之前，将其简化为单轮：“产品 X1000 的退货窗口期是多久？”如果它仍然失败，你就证明了错误与对话上下文无关——这很可能是一个基本的检索或知识问题，你可以更轻松地调试它。
Test case generation测试用例生成
You have two main approaches. First, simulate users with another LLM to create realistic multi-turn conversations. Second, use “N-1 testing” where you provide the first N-1 turns of a real conversation and test what happens next. The N-1 approach often works better since it uses actual conversation prefixes rather than fully synthetic interactions, but is less flexible.你有两种主要方法。第一，用另一个 LLM 模拟用户以创建真实的多轮对话。第二，使用“N-1 测试”，即提供真实对话的前 N-1 轮并测试接下来会发生什么。N-1 方法通常效果更好，因为它使用实际的对话前缀而非完全合成的交互，但灵活性较低。
The key is balancing thoroughness with efficiency. Not every multi-turn failure requires multi-turn analysis.关键在于平衡彻底性与效率。并非每个多轮故障都需要多轮分析。
When the conversation includes tools or several agents, use a transition failure matrix to find hotspots of errors.当对话包含工具或多个代理时，使用转换失败矩阵来查找错误热点。
Q: How do I evaluate sessions with human handoffs?
Capture the complete user journey in your traces, including human handoffs. The trace continues until the user’s need is resolved or the session ends, not when AI hands off to a human. Log the handoff decision, why it occurred, context transferred, wait time, human actions, final resolution, and whether the human had sufficient context. Many failures occur at handoff boundaries where AI hands off too early, too late, or without proper context.在你的追踪记录中捕获完整的用户旅程，包括人工交接。追踪记录持续到用户需求得到解决或会话结束，而不是 AI 交接给人时。记录交接决策、发生原因、转移的上下文、等待时间、人工操作、最终解决方案以及人工是否拥有足够的上下文。许多故障发生在 AI 交接过早、过晚或没有适当上下文的交接边界上。
Evaluate handoffs as potential failure modes during error analysis. Ask: Was the handoff necessary? Did the AI provide adequate context? Track both handoff quality and handoff rate. Sometimes the best improvement reduces handoffs entirely rather than improving handoff execution.在错误分析期间，将交接评估为潜在的失败模式。问：交接是否有必要？AI 是否提供了足够的上下文？跟踪交接质量和交接率。有时最好的改进是完全减少交接，而不是改进交接的执行。
Q: How do I evaluate complex multi-step workflows?
Log the entire workflow from initial trigger to final business outcome. Include LLM calls, tool usage, human approvals, and database writes in your traces. You will need this visibility to properly diagnose failures.记录从初始触发到最终业务结果的整个工作流。在你的追踪记录中包括 LLM 调用、工具使用、人工审批和数据库写入。你需要这种可见性来正确诊断故障。
Use both outcome and process metrics. Outcome metrics verify the final result meets requirements: Was the business case complete? Accurate? Properly formatted? Process metrics evaluate efficiency: step count, time taken, resource usage. Process failures are often easier to debug since they’re more deterministic, so tackle them first.同时使用结果指标和过程指标。结果指标验证最终结果是否满足要求：业务案例是否完整？准确？格式是否正确？过程指标评估效率：步骤计数、花费时间、资源使用。过程故障通常更容易调试，因为它们更具确定性，所以先解决这些。
Segment your error analysis by workflow stages. Early stage failures (understanding user input) differ from middle stage failures (data processing) and late stage failures (formatting output). Early stage improvements have more impact since errors cascade in LLM chains.按工作流阶段细分你的错误分析。早期阶段故障（理解用户输入）不同于中期阶段故障（数据处理）和后期阶段故障（格式化输出）。早期阶段的改进影响更大，因为错误会在 LLM 链中级联。
Use transition failure matrices to analyze where workflows break. Create a matrix showing the last successful state versus where the first failure occurred. This reveals failure hotspots and guides where to invest debugging effort.使用转换失败矩阵来分析工作流在哪里中断。创建一个矩阵，显示上一个成功状态与第一个故障发生的位置。这揭示了失败热点，并指导你将调试精力投入到哪里。
Q: How do I evaluate agentic workflows?
We recommend evaluating agentic workflows in two phases:我们建议分两个阶段评估代理工作流：
1. End-to-end task success. Treat the agent as a black box and decide whether it met the user’s goal. Define a precise success rule per task and measure it with human review or validated LLM judges. Record the first upstream failure during error analysis.1. 端到端任务成功。将代理视为黑盒，并决定它是否达到了用户的目标。为每个任务定义精确的成功规则，并用人工审核或经过验证的 LLM 评判者来衡量它。在错误分析期间记录第一个上游故障。
Once error analysis reveals which workflows fail most often, move to step-level diagnostics to understand why they’re failing.一旦错误分析揭示了哪些工作流最常失败，就转向步骤级诊断以了解它们为何失败。
2. Step-level diagnostics. After you log the system’s traces, you can score individual components such as:2. 步骤级诊断。记录系统的追踪记录后，你可以对各个组件进行评分，例如：
- Tool choice: check whether the agent selected the appropriate tool.工具选择：检查代理是否选择了合适的工具。
- Parameter extraction: check whether the inputs were complete and well-formed.参数提取：检查输入是否完整且格式良好。
- Error handling: check how the agent handled empty results or API failures.错误处理：检查代理如何处理空结果或 API 故障。
- Context retention: check whether the agent preserved earlier constraints.上下文保留：检查代理是否保留了早期的约束。
- Efficiency: count the steps, seconds, and tokens spent.效率：计算花费的步骤、秒数和 Token。
- Goal checkpoints: verify key milestones in long workflows.目标检查点：验证长工作流中的关键里程碑。
How do I test tool calls?我该如何测试工具调用？
Test the tool name, arguments, result, and resulting state as separate checks. Use code assertions when the expected behavior is objective. For example, verify that the agent selected cancel_order, passed the correct order ID, received a successful response, and changed the order status before it told the user that cancellation succeeded.将工具名称、参数、结果和产生的状态作为单独的检查进行测试。当预期行为是客观的时，使用代码断言。例如，验证代理选择了 cancel_order，传递了正确的订单 ID，收到了成功响应，并在告知用户取消成功之前更改了订单状态。
Also test authorization and preconditions. A valid tool call can still be wrong if the user did not approve the action or the system skipped a required check.还要测试授权和前提条件。如果用户未批准该操作或系统跳过了必要的检查，有效的工具调用仍然可能是错误的。
Example: “Find Berkeley homes under $1M and schedule viewings” breaks into: parameters extracted correctly, relevant listings retrieved, availability checked, and calendar invites sent. Each checkpoint can pass or fail independently, making debugging tractable.示例：“查找伯克利 100 万美元以下的房产并预约看房”可以拆解为：参数提取正确、检索到相关房源、检查可用性以及发送日历邀请。每个检查点都可以独立通过或失败，这使得调试变得可控。
Use transition failure matrices to understand error patterns. Create a matrix where rows represent the last successful state and columns represent where the first failure occurred. This is a great way to understand where the most failures occur.利用转换失败矩阵来理解错误模式。创建一个矩阵，其中行表示上一个成功状态，列表示首次失败发生的位置。这是了解故障多发环节的绝佳方法。
Transition matrices show where failures cluster. In this example, GenSQL → ExecSQL transitions cause 12 failures while DecideTool → PlanCal causes only 2. The counts show where to investigate first. Here is another text-to-SQL example from Bryan Bischof:转换矩阵展示了故障集中的位置。在此示例中，GenSQL → ExecSQL 的转换导致了 12 次失败，而 DecideTool → PlanCal 仅导致 2 次。这些计数指明了应首先调查的方向。以下是 Bryan Bischof 提供的另一个文本转 SQL 示例：
In this example, Bryan shows variation in transition matrices across experiments. How you organize your transition matrix depends on the specifics of your application. For example, Bryan’s text-to-SQL agent has an inherent sequential workflow which he exploits for further analytical insight. You can watch his full talk for more details.在此示例中，Bryan 展示了不同实验中转换矩阵的变化。如何组织转换矩阵取决于您的具体应用。例如，Bryan 的文本转 SQL 智能体具有固有的顺序工作流，他利用这一点获得了更深入的分析洞察。您可以观看他的完整演讲以了解更多详情。
Watch “Stop Managing AI Projects Like Traditional Software” on YouTube在 YouTube 上观看“停止像管理传统软件一样管理 AI 项目”
Creating Test Cases for Agent Failures为智能体故障创建测试用例
Creating test cases for agent failures follows the same principles as our previous FAQ on debugging multi-turn conversation traces. Reproduce the error with the simplest test that still fails. Use a multi-turn test only when the failure depends on conversation context.为智能体故障创建测试用例遵循与我们之前关于调试多轮对话轨迹的常见问题解答中相同的原则。用仍会失败的最简单测试来复现错误。仅当故障依赖于对话上下文时，才使用多轮测试。
👉 Want to learn more about AI Evals? Check out our AI Evals course. It’s a live cohort with hands on exercises and office hours. Here is a 25% discount code for readers. 👈
Footnotes脚注
Paul Graham, “Writes and Write-Nots”↩︎Paul Graham, “Writes and Write-Nots”↩︎
Shreya Shankar, et al., “Who Validates the Validators? Aligning LLM-Assisted Evaluation of LLM Outputs with Human Preferences”↩︎Shreya Shankar, et al., “Who Validates the Validators? Aligning LLM-Assisted Evaluation of LLM Outputs with Human Preferences”↩︎