Phoenix 预置 Evaluators 完全指南：LLM 评判器与代码评判器的选型、调用与落地验证

可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载本篇技术指南围绕 Arize Phoenix 提供的预置Pre-BuiltEvaluators展开覆盖 Pythonphoenix.evals.metrics与 TypeScriptarizeai/phoenix-evals两大生态的导入方式、12 个 LLM 评判器的输入字段 / 标签 / 优化方向对照、Faithfulness 与 Hallucination 的适用边界、PII 检测的结构化输出以及 RetrievalRelevance 的字段约定与常见误用。读完本文你将能够为 RAG、多轮 Agent、内容安全等场景正确选型评判器并在 Phoenix 中对 Trace 批量跑分、按分数排序定位异常样本最后用人工标注做上线前的准确率验证。提示预置评判器适合探索与快速验证若用于生产环境务必先做人工一致性验证目标 80% 一致或基于 自定义模板 构建领域专属评判器。一、预置 Evaluators 全景命名约定与导入方式Phoenix 的预置评判器分为两类LLM 评判器LLM-judged基于大模型打分与代码评判器code-based基于确定性算法。命名遵循统一约定PythonNameEvaluator从phoenix.evals.metrics导入TypeScriptcreateNameEvaluator从arizeai/phoenix-evals导入。在仓库的 Python 包导出清单 中可以确认全部导出符号CompletenessEvaluator、ConcisenessEvaluator、CorrectnessEvaluator、DocumentRelevanceEvaluator、exact_match、FaithfulnessEvaluator、HallucinationEvaluator、MatchesRegex、PiiDetectionEvaluator、PrecisionRecallFScore、RefusalEvaluator、RetrievalRelevanceEvaluator、ToolInvocationEvaluator、ToolResponseHandlingEvaluator、ToolSelectionEvaluator、ToxicityEvaluator、UserFrictionEvaluator。TypeScript 侧则在 js/packages/phoenix-evals/src/llm 与 code 目录 提供对应工厂函数。1.1 完整评判器对照表下表汇总 12 个 LLM 评判器。输入字段名在 Python 中为 snake_caseTypeScript 中为 camelCase。对于minimize方向的评判器高分代表坏结果例如 PII 被检测到、内容有毒。评判器输入字段Python 名标签1.0 / 0.0优化方向Concisenessinput,outputconcise/verbosemaximizeCorrectnessinput,outputcorrect/incorrectmaximizeFaithfulnessinput,output,contextfaithful/unfaithfulmaximizeHallucinationinput,outputhallucinated/groundedminimizePiiDetectionconversationpii_detected/no_pii_detectedminimizeRefusalinput,outputrefused/answeredneutralRetrievalRelevanceinput,contextrelevant/irrelevantmaximizeToolInvocationinput,available_tools,tool_selectioncorrect/incorrectmaximizeToolResponseHandlinginput,tool_call,tool_result,outputcorrect/incorrectmaximizeToolSelectioninput,available_tools,tool_selectioncorrect/incorrectmaximizeToxicitytexttoxic/non-toxicminimizeUserFrictionconversation,user_messagefriction/no_frictionminimize这些评判器的底层提示词模板由 YAML 配置编译而来仓库中 prompts/classification_evaluator_configs 目录存放了全部 14 份原始模板含上表 12 个外加COMPLETENESS与DOCUMENT_RELEVANCE编译产物分别位于 Python 生成配置 与 TypeScript 生成配置。1.2 代码评判器LLM 评判器之外Phoenix 还随包提供了确定性的代码评判器零模型成本、结果完全可复现Pythonexact_match、MatchesRegex、PrecisionRecallFScore同样从phoenix.evals.metrics导入TypeScript位于arizeai/phoenix-evals/code对应实现见 js/packages/phoenix-evals/src/codecreatePrecisionRecallFScoreEvaluators、createF1Evaluator、createExactMatchEvaluator等详见 evaluators-code-typescript.md。代码评判器常作为基线baseline与 LLM 评判器对照先跑出确定性指标的分布再用 LLM 评判器覆盖代码评判器无法衡量的语义维度。二、快速上手Python 与 TypeScript 的实例化所有预置 LLM 评判器都遵循构造一个带模型的评判器 → 对输入字典求值的模式。2.1 Pythonfrom phoenix.evals import LLM from phoenix.evals.metrics import FaithfulnessEvaluator llm LLM(provideropenai, modelgpt-4o) faithfulness_eval FaithfulnessEvaluator(llmllm)LLM是 Phoenix evals 的模型抽象层底层通过适配器对接 OpenAI、Anthropic、Google、LangChain、LiteLLM 等实现位于 packages/phoenix-evals/src/phoenix/evals/llm/adapters。构造评判器时可以额外传入**kwargs这些参数会被透传给 LLM 客户端例如temperature0.0、max_tokens256用于压低打分随机性。以 FaithfulnessEvaluator 实现 为例每个评判器在类级别声明NAME、PROMPT由生成配置编译为PromptTemplate、CHOICES、DIRECTION并用一个 PydanticInputSchema定义与校验输入字段——Faithfulness要求input查询、output回答、context参考文本三个必填字段。求值结果是一个Score对象包含label、score1.0/0.0、explanation模型给出的解释、metadata如所用模型名与direction其数据模型见 evaluators.py 中的 Score 定义。2.2 TypeScriptimport { createFaithfulnessEvaluator } from arizeai/phoenix-evals; import { openai } from ai-sdk/openai; const faithfulnessEval createFaithfulnessEvaluator({ model: openai(gpt-4o) });TypeScript 工厂函数接受模型Vercel AI SDK 风格的model与可选覆盖项。以 createRetrievalRelevanceEvaluator 实现 为例未传name、choices、promptTemplate、optimizationDirection时会回落到生成配置中的默认值并继续透传其余参数给底层createClassificationEvaluator——这意味着你可以为每个使用场景覆盖标签集合或优化方向而无需重写提示词。三、Faithfulness 与 Hallucination一对容易混淆的兄弟两者都检查回答是否被事实源支持区别在于事实源是什么Faithfulness针对单独提供的context如检索到的文档判断回答是否忠实适合 RAG。其输入为input、output、context三字段faithful记 1.0、unfaithful记 0.0方向为 maximize见 faithfulness.py。Hallucination以对话本身为事实源input需放入助手看到的完整历史——包括之前的轮次、工具调用及其结果最后一条消息是正在回答的用户轮次output是助手最新回复没有context字段适合多轮 Agent 与聊天场景。由于检测到幻觉是坏结果方向为minimizehallucinated记 1.0、grounded记 0.0见 hallucination.py 中的示例当对话中工具只返回30 天退货窗口而助手回答电子产品 90 天可退时被判为hallucinated。选型口诀手头有检索文档就选 Faithfulness没有独立上下文、靠对话自证就选 Hallucination。四、PII 检测整条记录筛查与可解析的 FINDINGS 输出PiiDetectionEvaluator用于检测对话记录中的个人身份信息PII方向为minimize检出 PII 是坏结果。4.1 关键约定筛查整条记录唯一输入字段conversation应包含一切内容——系统指令、工具调用与结果、检索到的文档——不仅仅是用户看到的部分。实现上输入模式只要求一个conversation字段见 pii_detection.py。结构化解释评判器的explanation是结构化的FINDINGS:块或FINDINGS: none每一行形如- type: 类别 | source: 来源可按实例解析出类别与来源user_message、assistant_response、tool_call_or_result、system_instructions、retrieved_document。占位符与脱敏不报[REDACTED]、555-01xx号码、example.com邮箱以及任何被标记为样例的内容都会被故意忽略因此不要用假标识符构造测试用例来评估该评判器。4.2 模板中的完整判据在 PII_DETECTION_CLASSIFICATION_EVALUATOR_CONFIG.yaml 中可以读到完整的判定 rubric包含直接个人标识姓名、用户名、出生日期、生物识别数据、联系方式与位置邮箱、电话、住址、精确地理定位、政府与国籍标识SSN/DNI、护照、驾照、财务卡号、IBAN、支付凭证、健康病历、医保号、受保护属性种族、宗教、性取向、雇佣与教育、在线与技术标识IP、MAC、Cookie、凭证与密钥密码、API Key、私钥、关系与其他标识共十大类并配套 11 条判定规则如形式上下文判定而非核实真实身份角色邮箱不算 email_address组合型准标识符也计数等。该 YAML 同时声明了choicespii_detected: 1.0/no_pii_detected: 0.0与optimization_direction: minimize是了解评判器行为边界的第一手资料。五、RetrievalRelevance 深潜字段约定决定你测的是什么RetrievalRelevanceEvaluator是源无关source-agnostic的评判器检索信息可以来自向量检索、工具/函数调用、MCP 服务器、网络搜索或数据库查询。它以整体方式给检索步骤打分——只要检索信息的任何有意义的组成部分实质上有助于回答请求该步骤就判为relevant。标签relevant/irrelevant分数被最大化relevant记 1.0、irrelevant记 0.0每条结果附带评判器的explanation。在 retrieval_relevance.py 中可以看到输入模式只有input与context两个字段context的字段描述明确要求本步骤检索到的外部信息所有条目拼接在一起。5.1 两种粒度单文档 vs 整步评估单文档评估只传入一个检索文档作为context逐个文档判断相关性整步评估把所有返回条目拼接为一个context值衡量整个检索步骤是否成功。5.2 两个字段约定搞错会悄悄改变你的测量对象input应该是用户的原始请求——例如 Trace 根节点的input.value——而不是改写后的工具参数或生成的 SQL 查询context应包含你想评估的那个范围的检索信息单文档就放一个文档整步评估就拼接所有返回条目。5.3 相关性 ≠ 正确性过时或之后被推翻的信息只要确实切题仍会判relevant而一次失败的检索——报错、超时或未找到结果——应判irrelevant。5.4 完整示例from phoenix.evals import LLM from phoenix.evals.metrics import RetrievalRelevanceEvaluator relevance_eval RetrievalRelevanceEvaluator(llmLLM(provideropenai, modelgpt-4o-mini)) scores relevance_eval.evaluate({ input: What is the capital of France?, context: Paris is the capital and largest city of France., }) print(scores[0].label) # relevantimport { createRetrievalRelevanceEvaluator } from arizeai/phoenix-evals; import { openai } from ai-sdk/openai; const evaluator createRetrievalRelevanceEvaluator({ model: openai(gpt-4o-mini) }); const result await evaluator.evaluate({ input: What is the capital of France?, context: Paris is the capital and largest city of France., }); console.log(result.label); // relevant需要注意RetrievalRelevanceEvaluator接受llm及任意**kwargs透传给 LLM 客户端如temperature0.0且要求模型支持工具调用tool calling或结构化输出structured output——这是所有基于分类模板的评判器的共同前置条件。TypeScript 工厂在常规分类评判器参数之上还允许覆盖name、choices、promptTemplate与optimizationDirection。六、什么时候该用预置评判器场景建议探索阶段找出值得人工 review 的 Trace找离群样本按分数排序生产环境必须先验证人工一致率 80%领域专属场景构建自定义评判器七、探索模式对整批 Trace 跑分并定位低分样本对 Trace 批量评估时最常用的入口是phoenix.evals.evaluate_dataframe。它接受一个 DataFrame 与一个评判器列表返回包含每列评分结果的 DataFramefrom phoenix.evals import evaluate_dataframe results_df evaluate_dataframe(dataframetraces, evaluators[faithfulness_eval]) # Score columns contain dicts — extract numeric scores scores results_df[faithfulness_score].apply( lambda x: x.get(score, 0.0) if isinstance(x, dict) else 0.0 ) low_scores results_df[scores 0.5] # Review these high_scores results_df[scores 0.9] # Also sample从 executors.py 的源码结构看evaluate_dataframe底层会使用同步或异步执行器SyncExecutor/AsyncExecutor并支持并发与速率限制适合对数千条 Trace 批量跑分同时phoenix.evals.tracing提供求值追踪能力每次evaluate调用本身也会产生可观测的 span。注意评分列中的值可能是字典含score、label、explanation等用上述apply提取数值后再过滤 0.5的低分样本优先人工审查 0.9的高分样本也值得抽样复核防止假阳性高分。八、上线前验证人工一致率必须 80%预置评判器以及任何 LLM 评判器在进入生产前必须用人工标注验证其可靠性。最直接的方式是用scikit-learn的分类报告对比人工标签与评判器标签from sklearn.metrics import classification_report print(classification_report(human_labels, evaluator_results[label])) # Target: 80% agreement评判标准是人工一致率 80%。若未达标优先考虑更换更强的基础模型如从gpt-4o-mini升级到gpt-4o调整temperature等调用参数让打分更稳定基于 自定义模板 编写领域专属提示词或参考 fundamentals-model-selection.md 的模型选型建议为领域数据构建自定义评判器。九、延伸阅读evaluators-overview.md评判器体系总览LLM / 代码 / 自定义分类evaluators-custom-templates.md自定义提示词模板与标签/方向覆盖evaluators-rag.mdRAG 场景的评判器组合方案evaluators-code-typescript.mdTypeScript 代码评判器arizeai/phoenix-evals/codevalidation-evaluators-python.md 与 validation-evaluators-typescript.mdPython/TypeScript 侧的验证流程prompts/classification_evaluator_configs全部预置评判器的 YAML 提示词与判据仓库内可读原文packages/phoenix-evals/src/phoenix/evals/metricsPython 侧全部评判器实现源码。赞分享可观测性AI 评测LLMOpsAI 应用人工智能【免费下载链接】phoenixAI Observability Evaluation项目地址https://gitcode.com/gh_mirrors/phoenix13/phoenix点击查看免费下载相关推荐Haystack Evaluators 全解LLM 评判器与检索评估指标组件的深度实现指南Haystack Evaluators 全解LLM 评判器与检索评估指标组件的深度实现指南 本文基于 Haystack 2.20 版 Evaluators A人工智能大模型RAGAI AgentNLP5分钟掌握Parsec VDD解锁Windows虚拟显示器的终极解决方案5分钟掌握Parsec VDD解锁Windows虚拟显示器的终极解决方案 你是否曾遇到这样的困扰想要进行游戏串流却没有物理显示器可用或者需要在远程服务器上可观测性AI 评测LLMOpsAI 应用人工智能Oumi 内置 LLM Judge 完全指南Generic、Doc QA 与 Rubric 三类评判器的开箱即用实践Oumi 内置 LLM Judge 完全指南Generic、Doc QA 与 Rubric 三类评判器的开箱即用实践 Oumi OSS 为常见的模型评估任务提人工智能大模型预训练微调强化学习模型推理服务模型评测MCP 服务分布式训练模型量化上一篇如何构建毫秒级实时语音转文字系统WhisperLiveKit技术深度解析下一篇微软的Proxy项目安装和配置指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考