Pydantic Evals 第三方评测框架集成把 Ragas 与 DeepEval 指标封装为自定义 Evaluator【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai本篇基于 pydantic-ai 仓库的 第三方集成文档 与 Pydantic Evals 评测器源码讲解如何在不引入硬依赖的前提下把 Ragas、DeepEval 等上游评测框架的具体指标封装为 Pydantic Evals 的自定义Evaluator并复用数据集、报告与结果管线。读完本文你可以自行实现与上游框架逐分对齐的评测适配器并理解框架底层如何执行、校验和记录这些评测结果。为什么需要第三方框架集成Pydantic Evals 不对任何特定指标框架做硬依赖。当团队已经在用 Ragas、DeepEval 或其他评分库时Evaluator基类提供了一个轻量入口把上游指标包一层适配器就能在任何 Pydantic Evals 数据集里运行。这一点在 pyproject.toml 中可以直接验证pydantic-evals的动态依赖只有rich、logfire-api、pydantic、pydantic-ai-slim、anyio、pyyamlragas和deepeval既不在核心依赖里也不在任何可选依赖组中可选组仅logfire。但原文档给出了一条重要决策建议写适配器之前应先确认优先使用原生评测器。如果基于评分细则rubric的LLMJudge见标准质量指标页面提供的现成 rubric或自定义评测器已能覆盖你的场景那通常更简单——零额外依赖分数还能干净地落入报告。只有当你确实需要上游实现的精确行为时才使用下述集成与已发表基准可复现、与现有评测套件保持口径一致、或上游框架有原生侧未暴露的能力。同一数据集内可以混合外部评测器和原生评测器。集成模式三步封装上游指标每个框架集成遵循同一模式继承Evaluator基类把ctx.inputs、ctx.output、ctx.expected_output和元数据适配成上游指标所需的输入结构返回float分数、bool断言、EvaluationReason或这些类型的dict。官方给出的适配器示例刻意保持紧凑——你可以按需扩展模型选择、阈值、按 case 开关等团队所需的任何配置。Evaluator 基类与返回值类型封装的契约来自 evaluator.py 中的Evaluator子类必须实现evaluate可以用def同步也可以用async def异步框架自动兼容两种形式允许的返回类型由EvaluatorOutput定义evaluator.py#L49EvaluationScalar | EvaluationReason | Mapping[str, ...]EvaluationScalar bool | int | Annotated[float, Field(allow_inf_nanFalse)] | strevaluator.py#L27int和有限float视为分数str视为标签bool视为断言。注意float被显式约束为有限值——返回NaN或±inf会在执行期触发EvaluatorFailure而不是静默记录EvaluationReasonevaluator.py#L34-L46携带标量value和可选的reason解释是封装上游指标最推荐的返回形式因为上游框架的打分理由可以被保留到报告中。另外Evaluator继承的BaseEvaluator_base.py带有一个严格的元类_StrictABCMeta如果你的子类没有实现evaluate会在类定义时就抛TypeError而不是等到实例化才报错。BaseEvaluator.as_spec()还会把评测器序列化为EvaluatorSpecspec.py默认值字段会被自动剔除这让你的适配器能像内置评测器一样被写入 YAML/JSON 数据集定义。EvaluatorContext适配器能拿到的数据适配层的全部输入来自 EvaluatorContext字段包括ctx.namecase 名称ctx.inputs/ctx.output任务输入与实际输出ctx.metadatacase 元数据可为None适配器里通常要先判空ctx.expected_output期望输出可为None;ctx.duration、ctx.metrics、ctx.attributes、ctx.span_tree执行耗时、自定义指标/属性、OpenTelemetry span 树等可用于行为类检查但对纯文本评分指标一般用不到。Ragas封装 Faithfulness 指标ragas需单独安装pip install ragas不包含在pydantic-evals中。下面的适配器把ragas.metrics.Faithfulness包装成单轮single-turn评分。每个 case 需要在 inputs 或 metadata 中提供检索到的上下文from dataclasses import dataclass from ragas.dataset_schema import SingleTurnSample from ragas.metrics import Faithfulness from pydantic_evals.evaluators import EvaluationReason, Evaluator, EvaluatorContext dataclass class RagasFaithfulness(Evaluator): Wrap ragas.metrics.Faithfulness as a Pydantic Evals evaluator. context_field: str context async def evaluate(self, ctx: EvaluatorContext) - EvaluationReason: metadata ctx.metadata or {} retrieved_contexts metadata.get(self.context_field, []) if isinstance(retrieved_contexts, str): retrieved_contexts [retrieved_contexts] sample SingleTurnSample( user_inputstr(ctx.inputs), responsestr(ctx.output), retrieved_contextsretrieved_contexts, ) metric Faithfulness() score await metric.single_turn_ascore(sample) return EvaluationReason(valuefloat(score), reasonfragas.Faithfulness {score:.3f})设计要点context_field是 dataclass 字段默认context让上下文的存放键名可配置用ctx.metadata or {}防御metadata为None的情况EvaluatorContext.metadata的类型注解允许None兼容上下文是单个字符串的写法统一转成列表因为 Ragas 提供异步评分入口single_turn_ascoreevaluate用async def实现避免阻塞事件循环返回EvaluationReason并把分数写进reason让报告里既有序数分也有解释文本。使用方式与内置评测器完全一致from pydantic_evals import Case, Dataset dataset Dataset( namerag_eval, cases[ Case( inputsWhat is the capital of France?, metadata{context: [Paris is the capital of France.]}, ), ], evaluators[RagasFaithfulness()], )同一模式适用于ragas.metrics.answer_relevancy、context_precision等其他评分指标换成对应的 metric 类并按需要替换SingleTurnSample的字段即可。DeepEval封装 GEval 指标deepeval同样需单独安装pip install deepeval不包含在pydantic-evals中。这个适配器把 DeepEval 的GEval指标封装为按准则criteria对LLMTestCase打分。由于 DeepEval 的measure是同步的评测器也用同步实现from dataclasses import dataclass from deepeval.metrics import GEval from deepeval.test_case import LLMTestCase, LLMTestCaseParams from pydantic_evals.evaluators import EvaluationReason, Evaluator, EvaluatorContext dataclass class DeepEvalGEval(Evaluator): Wrap deepeval.metrics.GEval as a Pydantic Evals evaluator. metric_name: str criteria: str threshold: float 0.5 def evaluate(self, ctx: EvaluatorContext) - dict[str, float | bool | EvaluationReason]: test_case LLMTestCase( inputstr(ctx.inputs), actual_outputstr(ctx.output), expected_outputNone if ctx.expected_output is None else str(ctx.expected_output), ) metric GEval( nameself.metric_name, criteriaself.criteria, evaluation_params[LLMTestCaseParams.INPUT, LLMTestCaseParams.ACTUAL_OUTPUT], thresholdself.threshold, ) metric.measure(test_case) return { f{self.metric_name}_score: EvaluationReason(valuefloat(metric.score), reasonmetric.reason or ), f{self.metric_name}_pass: bool(metric.success), }设计要点metric_name同时作为 DeepEval 指标名和输出前缀一个适配器实例产出一对结果{name}_score带理由的分数和{name}_pass是否过阈值threshold默认0.5对应 DeepEval 的通过线metric.success被映射为布尔断言列expected_output is None时显式传None给LLMTestCase避免把 Python 的None变成字符串None。同一个包装器可以复用给 DeepEval 的FaithfulnessMetric、AnswerRelevancyMetric、HallucinationMetric等换成对应的 metric 类并填充相关的LLMTestCase字段例如 faithfulness 需要retrieval_context。框架如何执行你的适配器源码视角理解执行管线能帮你确认适配器够用的边界。run_evaluator 是入口调用evaluator.evaluate_async(ctx)——同步实现会原样返回结果异步实现被await见 Evaluator.evaluate_async所以 Ragas 的async def和 DeepEval 的def写法各自天然合适传入可选的RetryConfig时会用 tenacity 重试包裹evaluate_async网络类指标两个框架都要自调 LLM可因此获得重试能力原始返回值经过 PydanticTypeAdapter以revalidate_instancesalways重新校验_run_evaluator.py#L110-L114返回非法类型会转为ValueError标量结果会被包进映射键名取get_default_evaluation_name()默认即类名如RagasFaithfulness返回dict时则以 dict 的键作为各结果名如DeepEvalGEval的{name}_score/{name}_pass任何异常都被捕获为EvaluatorFailure含error_message、error_stacktrace、error_type记为该 case 的评测器失败而不是让整个数据集跑挂每个评测器调用都被包在名为evaluator: {evaluator_name}的 logfire span 里方便在 Logfire 中按评测器查询。此外Evaluator还提供get_evaluator_version()默认返回None当你的适配器行为变化换了上游指标版本、改了阈值语义时可以覆写它打一个版本标签如v2在线评测看板可以据此过滤掉旧版本的结果而无需删除历史数据。依赖与运行成本注意事项原文档的依赖说明部分要点如下可结合仓库证据确认ragas和deepeval都是可选依赖——不随pydantic-evals安装也不属于任何依赖组。只在真正使用这些集成的项目中安装避免污染所有评测环境的依赖树pyproject.toml 中optional-dependencies仅有logfire这两个库会发起自己的 LLM 调用与你的数据集任务执行相互独立。运行包含这些评测器的数据集时要预留出额外的 API 用量和时长预算适配器本身是普通 dataclassdataclass装饰器是必需的——_StrictABCMeta要求在类定义时完成evaluate的实现检查。选型速查需求建议评分细则能覆盖、零额外依赖原生LLMJudgerubric 或GEval标准质量指标需要与上游框架精确对齐可复现、口径一致本文的 Ragas / DeepEval 适配器模式领域特化逻辑、外部 API 校验等自定义评测器同一数据集可以混合以上评测器原生评测器负责常规模块第三方适配器负责必须逐分对齐的指标结果统一进入同一份报告与同一套失败/版本标记体系。【免费下载链接】pydantic-aiHow Python does AI. Agents, realtime voice, image generation, embeddings. Every model, every interface, typed end to end.项目地址: https://gitcode.com/GitHub_Trending/py/pydantic-ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考