Opik Python SDK 的 TestSuiteResult 深入解析测试套件结果的数据结构、通过判定与报告生成【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm导读opik.TestSuiteResult是 Opik Python SDK 中代表一次测试套件Test Suite运行结果的核心对象由opik.run_tests()返回。本文以该对象的官方 API 文档为骨架结合仓库源码test_suite_result.py、suite_result_constructor.py 等逐层拆解其数据结构、三级通过判定规则、执行策略的影响以及结构化报告的生成与解析方式。读完本文你将能读懂测试套件返回结果中的每一个字段并能在 CI 中基于pass_rate、all_items_passed等属性编写自动化断言。一、TestSuiteResult 的定位一次测试套件运行的「成绩单」在 Opik 的回归测试体系中Test Suite 是一组预配置的测试用例item每个用例可以携带独立的断言assertions和执行策略execution policy。调用opik.run_tests(test_suite..., task...)后SDK 会依次完成创建实验experiment对每个测试项调用任务函数task并收集输出用 LLM 判官LLMJudge对输出执行断言打分将原始评估结果汇总为TestSuiteResult并返回。这条调用链的源码入口在 evaluator.py 的run_tests()其内部调用__internal_api__run_test_suite__()最后由 suite_result_constructor.py 的build_suite_result()完成结果装配。TestSuiteResult的官方 docstring 将其职责概括为包含每个测试项在执行策略下的通过/失败状态以及整个套件的总体通过/失败状态。也就是说它是一个聚合视图——向上回答套件过没过向下回答哪个测试项、哪次运行、哪条断言挂了。二、TestSuiteResult 核心数据模型TestSuiteResult定义于 test_suite_result.py其构造参数如下正常情况下用户不会直接实例化它而是由build_suite_result()自动构建构造参数类型说明items_passedint通过满足执行策略的测试项数量items_totalint参与评估的测试项总数item_resultsDict[str, ItemResult]以dataset_item_id为键的逐项结果evaluation_result_EvaluationResult底层的原始评估结果用于暴露实验信息suite_nameOptional[str]测试套件名称total_timeOptional[float]整个评估的总耗时秒2.1 面向使用者的属性通过公开属性可以直接读取结果的核心指标all_items_passed→bool是否所有测试项全部通过。其实现是items_passed items_total这也是判定套件整体通过的唯一定义同时被写入 JSON 报告中的suite_passed字段。items_passed→int通过的测试项数量。items_total→int测试项总数。pass_rate→Optional[float]通过率仅在有断言的测试项中计算。源码中先筛出has_assertions True的项再求比值若没有任何项带断言则返回None。这意味着无断言的测试项既不会拉低通过率也不计入分母。item_results→Dict[str, ItemResult]逐项结果键为dataset_item_id。suite_name→Optional[str]套件名称。total_time→Optional[float]总评估耗时秒。2.2 实验信息透传属性由于TestSuiteResult内部持有EvaluationResult它还透传了三个实验相关属性方便与 Opik 平台联动experiment_id→str本次运行创建的实验 IDexperiment_name→Optional[str]实验名称未显式指定时由 SDK 自动生成experiment_url→Optional[str]在 Opik 仪表盘中查看该实验的链接。这三个字段最终都会出现在生成的 JSON 报告中是连接本地结果与平台可观测数据的桥梁。三、ItemResult单个测试项的细粒度结果ItemResult是与TestSuiteResult同文件定义的一个dataclasses.dataclasstest_suite_result.py描述单个测试项的评估情况字段类型含义dataset_item_idstr数据集测试套件中该项的 IDpassedbool该项是否按执行策略通过has_assertionsbool该项是否有断言被执行runs_passedint该项通过的运行run次数runs_totalint该项实际完成的运行总数configured_runs_per_itemint执行策略配置的每项运行次数pass_thresholdint执行策略要求的最低通过运行次数test_resultsList[TestResult]每次运行的详细测试结果按trial_id排序其中configured_runs_per_item与pass_threshold直接来源于执行策略。执行策略在 execution_policy.py 中定义默认值为DEFAULT_EXECUTION_POLICY { runs_per_item: 1, pass_threshold: 1, }即默认每个测试项运行 1 次、通过 1 次即算通过。当需要对抗 LLM 输出的随机性时可以给某个测试项单独配置{runs_per_item: 5, pass_threshold: 4}——多次采样、多数通过才算该用例通过。四、三级通过判定逻辑源码级整个结果的通过判定是**运行 → 测试项 → 套件**的三级递进结构逻辑集中在 suite_result_constructor.py一次运行RUN通过该次运行的所有断言分数全部通过。判定函数is_score_passed()test_suite_result.py的规则是scoring_failed打分失败一律视为不通过否则当分数值等于布尔True或数值1时视为通过。值得注意的是一个测试项如果没有断言score_results为空其运行默认视为通过。一个测试项ITEM通过runs_passed pass_threshold其中runs_passed统计该测试项下所有通过运行的次数。整个套件SUITE通过items_passed items_total即所有测试项全部通过——套件层面不允许部分通过这与pass_rate允许 0~1 之间的小数形成鲜明对比。这套逻辑的源码注释同样给出了权威描述A RUN passes if all its assertion scores pass (valueTrue or value1); An ITEM passes if runs_passed pass_threshold; The SUITE passes if all items pass.五、run_tests 参数速查与结果对象直接相关的使用面TestSuiteResult由opik.run_tests()产生其签名evaluator.py中与结果形态最相关的参数如下参数默认值说明test_suite必填传入TestSuite跑最新版本或TestSuiteVersion跑指定版本快照task必填接收每个测试项data字典的可调用对象返回dict须含input/output键或其他任意值自动包装为{output: value}experiment_name/experiment_name_prefixNone指定或自动生成实验名称会体现在result.experiment_name中verbose20静默1汇总2详细影响控制台输出与断言明细worker_threads16并行执行任务函数的线程数modelNone用于执行断言打分的模型名generate_reportTrue是否生成 JSON 报告文件report_output_pathNone报告文件路径缺省时写入opik_test_suite_reports/目录scoring_tool_strategyNoneauto/always/never覆盖所有判官的评分工具策略六、结构化报告to_report_dict 与 JSON 落盘6.1 报告字典结构to_report_dict()test_suite_result.pyto_dict()是其别名将结果序列化为可供 CI 消费的字典。顶层结构如下{ suite_passed: true, items_passed: 8, items_total: 8, pass_rate: 1.0, experiment_id: 9f3a..., suite_name: Refund Policy Tests, experiment_name: test-suite-2025-01-01-00-00-00, experiment_url: https://..., total_time_seconds: 42.13, generated_at: 2026-09-12T00:00:0000:00, items: [ { dataset_item_id: ..., passed: true, runs_passed: 5, execution_policy: {runs_per_item: 5, pass_threshold: 4}, runs: [ { trial_id: 0, passed: true, input: {...}, output: ..., trace_id: ..., task_execution_time_seconds: 0.812, scoring_time_seconds: 0.35, assertions: [ {name: Response is polite, passed: true, value: true, scoring_failed: false} ] } ] } ] }报告中对每条断言展开name、passed、value、scoring_failed并在存在时附带reason与metadata每次运行附带trace_id、task_execution_time_seconds、scoring_time_seconds便于回查平台上的完整链路。整体items数组按数据集项分组与item_results字典一一对应。6.2 JSON 文件落盘当generate_reportTrue时file_writer.py 会将上述字典写入本地 JSON 文件未指定report_output_path时默认落在opik_test_suite_reports/目录下文件名为净化后的实验名加.json后缀如opik_test_suite_reports/test-suite-2025-01-01-00-00-00.json。写入时会自动创建父目录并使用indent2保证可读性。6.3 控制台展示结果同时会在终端以面板形式渲染displayer.py展示套件名、Suite result: PASSED/FAILED、Items passed: 8/8、Pass rate: 100.0%、总耗时HH:MM:SS格式、平均任务/打分耗时verbose 2时还会按通过率升序逐条列出每个断言的通过率。若实验 URL 或报告路径存在面板会输出可点击的View results in Opik dashboard与View local detailed report file链接。七、实战示例创建套件、运行并消费结果结合 test_suite.py 的官方示例一个完整的运行 结果消费流程如下import opik client opik.Opik() # 1. 创建测试套件定义套件级全局断言 suite client.create_test_suite( nameRefund Policy Tests, descriptionRegression tests for refund scenarios, global_assertions[ Response does not contain hallucinated information, Response is helpful to the user, ], ) # 2. 插入测试项可携带项级断言与独立执行策略 suite.insert([ { data: {user_input: How do I get a refund?, user_tier: premium}, assertions: [Response is polite], }, { data: {user_input: Is my account hacked?}, assertions: [Response treats the concern with urgency], execution_policy: {runs_per_item: 5, pass_threshold: 4}, }, ]) # 3. 运行测试套件task 接收 data 字典并返回输出 results opik.run_tests( test_suitesuite, taskmy_llm_function, experiment_namerefund-v2-regression, verbose1, ) # 4. 消费 TestSuiteResult print(results.all_items_passed) # 套件是否整体通过 print(results.items_passed, results.items_total) # 8 8 print(results.pass_rate) # 1.0仅统计有断言的项 print(results.experiment_url) # 跳转平台查看实验 print(results.total_time) # 总耗时秒 # 5. 逐项排查找到失败项及其失败断言 for item_id, item in results.item_results.items(): if not item.passed: print(failed item:, item_id) print(runs:, item.runs_passed, /, item.runs_total, threshold:, item.pass_threshold) # 6. 生成结构化报告字典 / 落盘 JSON report results.to_report_dict() # 或 results.to_dict()在 CI 场景中常见的做法是直接断言results.all_items_passed或results.pass_rate 0.95来决定流水线是否继续并通过results.experiment_url将失败详情链接回 Opik 仪表盘人工排查。八、注意事项与最佳实践无断言项不影响 pass_ratepass_rate只统计has_assertionsTrue的测试项无断言的项不会拉低通过率但也不会进入分母套件级all_items_passed则不受此影响。打分失败scoring_failed视为不通过断言打分过程中出现异常时is_score_passed直接返回False保证无法判定不会误报为通过。区分三种通过粒度运行通过 ≠ 测试项通过 ≠ 套件通过。配置runs_per_item 1时单次运行失败并不代表测试项失败只有通过次数低于pass_threshold时该项才判失败。任务函数返回值规范若返回dict必须同时包含input与output键否则validate_task_result()test_suite.py会抛出ValueError返回其他类型则自动包装为{output: result}。报告的generated_at使用 UTC 时间戳跨时区团队比对报告时注意时区转换。相关文件索引类定义与报告序列化test_suite_result.py结果构建与三级判定逻辑suite_result_constructor.py执行策略类型与默认值execution_policy.py运行入口run_testsevaluator.py控制台展示displayer.pyJSON 报告落盘file_writer.py套件 API 与任务校验test_suite.py【免费下载链接】comet-llmDebug, evaluate, and monitor your LLM applications, RAG systems, and agentic workflows with comprehensive tracing, automated evaluations, and production-ready dashboards.项目地址: https://gitcode.com/GitHub_Trending/co/comet-llm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考