# Pydantic 评估 ## 概述 Pydantic Evals 使用 Pydantic 模型的代码优先方法为 AI 代理和 LLM 输出提供严格的测试和评估。它支持“评估驱动开发”(EDD)，其中评估套件与应用程序代码一起存在，并受版本控制和 CI/CD 的约束。 ## 核心概念了解这些关键原语： ###案例具有输入、可选预期输出和元数据的单个测试场景。从 pydantic_evals 导入案例案例 = 案例（名称=“退款请求”， input="您的退款政策是什么？", Expected_output="30 天全额退款", 元数据={“类别”：“政策”} ） ### 数据集具有默认评估器的案例集合。输入/输出类型的通用。从 pydantic_evals 导入数据集数据集 = 数据集（案例=[案例1，案例2，案例3]，评估者=[评估者1，评估者2] ） ### 评估者评估输出的逻辑引擎。返回 bool（通过/失败）、float/int（分数）或 str（标签）。 ### 实验当数据集针对任务运行时的时间点性能捕获。 **详细说明**，请参阅 [references/core-concepts.md]() ## 快速入门创建并运行简单的评估：从 pydantic_evals 导入案例，数据集从 pydantic_evals.evaluators 导入包含，LLMJudge # 定义案例案例=[ 案例（名称=“问候语”， input="你好，你是谁？", Expected_output="我是人工智能助手。" ） ] # 定义评估者评估者 = [ 包含(value="AI助手"), LLMJudge(rubric="此回答礼貌吗？回答“通过”或“失败”。") ] # 创建数据集数据集=数据集（案例=案例，评估者=评估者） # 运行评估异步 def my_agent(query: str) -> str: # 这里是你的代理逻辑 return“我是AI助手”。报告 = dataset.evaluate_sync(my_agent) 报告.print() ## 评估器类型 Pydantic Evals 支持从快/便宜到慢/贵的“评估金字塔”： ### 1\.确定性评估器快速、免费、基于代码的检查。用作第一道防线。 * **等于** ：精确相等检查 * **EqualsExpected** ：与 Case.expected_output 比较 * **包含**：子字符串/项目存在 * **IsInstance** ：类型验证 * **MaxDuration** ：延迟 SLA 实施 **策略**：始终在昂贵的法学硕士法官之前运行确定性检查。 ### 2\.法官法学硕士使用辅助法学硕士根据自然语言评分标准对输出进行评分。从 pydantic_evals.evaluators 导入 LLMJudge 法官=法学硕士法官( rubric="回答必须：1) 回答问题，2) 引用上下文，3) 专业", include_input=真， include_expected_output=真，型号='openai:gpt-4o' ） **使用 OpenRouter 进行 LLMJudge：** 从 pydantic_evals.evaluators.llm_as_a_judge 导入 set_default_judge_model 从 pydantic_ai.models.openai 导入 OpenAIChatModel 从 pydantic_ai.providers.openai 导入 OpenAIProvider # 配置OpenRouter作为判断模型提供者 = OpenAIProvider( api_key=os.getenv('OPENROUTER_API_KEY'), base_url='https://openrouter.ai/api/v1' ）模型 = OpenAIChatModel(model_name='gpt-4o-mini', 提供者=提供者) 设置默认判断模型（模型） # 或者直接将模型传递给LLMJudge Judge = LLMJudge(rubric="这样有礼貌吗？", model=model) **标题最佳实践**：具体且可操作，而不是含糊不清。 ### 3\.定制评估器通过继承“Evaluator”来实现任意逻辑。从数据类导入数据类从 pydantic_evals.evaluators 导入 Evaluator、EvaluatorContext @数据类 ValidSQL 类（评估器）： def评估（自我，ctx：EvaluatorContext） - > bool：导入sqlparse 尝试：解析 = sqlparse.parse(ctx.output) 返回 len(已解析) > 0 除外：返回错误 #### 结构化输出的自定义评估器（Pydantic 模型） **重要**：内置评估器（如“Contains”、“Equals”）可用于字符串/列表/字典。它们不适用于 Pydantic 模型输出。对于具有 `output_type=MyModel` 的代理，创建自定义评估器：从数据类导入数据类从 pydantic_evals.evaluators 导入 Evaluator、EvaluatorContext 从 pydantic 导入 BaseModel 类 MyAgentResponse(BaseModel)：消息：str 状态：str 完整：布尔 @数据类类 HasNonEmptyMessage(Evaluator[MyAgentResponse, None]): """检查响应是否有一个非空消息字段。""" 最小长度：int = 1 def evaluate(self, ctx: EvaluatorContext[MyAgentResponse, None]) -> bool: 如果不是 isinstance(ctx.output, MyAgentResponse)：返回错误返回 len(ctx.output.message) >= self.min_length @数据类类 StatusIsValid(Evaluator[MyAgentResponse, None]): """检查状态是否为允许的值之一。""" allowed_values: tuple = ("待处理", "完成", "错误") def evaluate(self, ctx: EvaluatorContext[MyAgentResponse, None]) -> bool: 在 self.allowed_values 中返回 ctx.output.status # 用法评估者 = [ IsInstance(type_name="MyAgentResponse"), # 首先检查类型 HasNonEmptyMessage(min_length=10), 状态有效(), ] ### 4\.基于跨度的评估检查执行跟踪以验证内部代理行为（工具调用、检索步骤）。从 pydantic_evals.evaluators 导入 HasMatchingSpan 从 pydantic_evals.otel 导入 SpanQuery # 验证代理调用特定工具 # 注意：HasMatchingSpan 使用 SpanQuery 获取查询参数 tool_check = HasMatchingSpan( 查询=SpanQuery( name_equals='运行工具', has_attributes={'gen_ai.tool.name': '计算器'} ）） **详细指南**，请参阅 [references/evaluator-types.md]() ## 与 Pydantic AI 集成 ### 将代理定义为任务将代理执行包装在任务函数中：从 pydantic_ai 导入代理 agent = Agent('openai:gpt-4o-mini', system_prompt="你很有帮助。") 异步 def run_agent(query: str) -> str: 结果=等待代理.运行（查询） return result.output # 使用 result.output，而不是 result.data ### 处理依赖关系使用依赖注入进行确定性测试：从数据类导入数据类 @数据类班级部门： api_key: 字符串 # 在测试期间，用模拟覆盖 test_deps = Deps(api_key="test_key") **有关集成指南**，请参阅 [references/integration.md]() ## Logfire 可观察性启用自动跟踪以进行调试：导入日志火 logfire.configure(send_to_logfire='if-token-present') logfire.instrument_pydantic_ai() # 评估现在创建可在 Logfire 仪表板中查看的丰富跟踪好处： * 跟踪每次评估运行 * 可视化代理内部执行情况 * 并排比较实验 * 具有完整上下文的调试失败 ## 数据集管理 ### 保存/加载数据集 # 使用 schema 保存到 YAML dataset.to_file('evals.yaml', fmt='yaml') # 从文件加载 dataset = Dataset.from_file('evals.yaml') **重要**：使用类型化数据集进行正确的序列化： # 定义类型化数据集以避免序列化警告数据集：数据集[str, str, None] = 数据集(...) # 或者当使用自定义评估器从文件加载时从类型导入 NoneType 数据集 = 数据集[MyInputType, MyOutputType, NoneType].from_file( 'evals.yaml', custom_evaluator_types=(MyCustomEvaluator,) ） ### 使用 LLM 生成数据集从 pydantic_evals. Generation 导入generate_dataset 数据集 = 等待生成数据集（ dataset_type=数据集[str, str, None], 型号='openai:o1', n_examples=10, extra_instructions="为客户支持代理生成不同的测试用例" ） ## 最佳实践 1. **快速失败**：在 LLM 评审之前运行确定性评估器 2. **成本与延迟的权衡**： * 提交挂钩：仅限确定性 * PR合并：小型法学硕士对关键案件进行法官 * 每晚构建：完整的法学硕士法官套件 3. **并发** ：使用 `max_concurrency` 参数来避免速率限制 4. **版本控制**：将数据集与代码一起存储在 Git 中 5. **回归测试**：比较实验以检测退化 ## 常见工作流程 ### 工作流程 1：创建评估套件 1. 定义具有输入和预期输出的案例 2. 根据需求选择评估人员 3. 使用案例和评估者创建数据集 4.保存到YAML进行版本控制 ### 工作流程 2：运行评估 1.从文件加载数据集 2.定义任务函数（代理包装器） 3. 运行“dataset.evaluate_sync(task)”或“dataset.evaluate(task)” 4. 使用`report.print()`或Logfire分析报告 **访问结果**：报告 = dataset.evaluate_sync(my_task) 报告.print() # 访问个别案例结果 for case in report.cases: # 注意：使用 .cases，而不是 .case_results print(f"案例：{case.name}") print(f"输出：{case.output}") print(f"通过：{case.passed}") ### 工作流程 3：比较模型 1.针对不同模型运行相同的数据集 2. 为每次运行生成实验 3. 比较指标（通过率、延迟、分数） 4.使用Logfire对比视图 ## 示例演示模式的完整示例文件： * **[references/examples/generate_dataset.py]()** : 使用 LLM 生成测试用例 * **[references/examples/custom_evaluators.py]()** : 实现自定义评估逻辑 * **[references/examples/unit_testing.py]()** : 在 CI/CD 中运行评估 * **[references/examples/compare_models.py]()** : 对不同模型进行基准测试 ## 资源 ###参考资料/ * [core-concepts.md]()：案例、数据集、评估器、实验的详细解释 * [evaluator-types.md]()：深入了解所有评估器类型 * [integration.md]()：Pydantic AI 和 Logfire 集成指南 * [examples/](): 完整的工作示例

派丹提克评估

包含技能