DeepEval 单轮端到端评估如何用 evals_iterator 与 tracing 构建测试用例【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepevalDeepEval 的单轮端到端评估把 LLM 应用当作黑盒每次交互只有「一个输入 → 一个输出」用LLMTestCase承载打分对象。官方文档给出了两条执行路径一是dataset.evals_iterator()配合 tracing二是直接构造LLMTestCase传给evaluate()。本文聚焦前者——当你的应用代码可以或可以改为被 instrument 时evals_iterator()会在循环里自动完成四件事开启一个 test run、yield 每条 golden、从捕获到的 trace 构建LLMTestCase、用你传入的 metrics 打分并把 trace 与分数一起上传。适用前提是你能在应用中加入observePython/observe()TypeScript或某个框架集成如果测试的是无法改动的第三方 API这条路走不通应改用文档中的 Approach 2evaluate()。准备安装与数据集先安装 deepevalpip install deepeval单轮评估的数据集由Golden对象组成每个 golden 是一条测试用例的前身再包进EvaluationDataset。文档给出了四种获取方式最简单的是直接写在代码里from deepeval.dataset import Golden, EvaluationDataset goldens [ Golden(inputWhat is your name?), Golden(inputChoose a number between 1 and 100), # ... ] dataset EvaluationDataset(goldensgoldens)这个 dataset 只存在于当前这次运行中——不推送、不保存适合一次性评估。其他来源可选分支从 CSV 加载dataset.add_goldens_from_csv_file(file_pathexample.csv, input_col_namequery)从 JSON 加载dataset.add_goldens_from_json_file(file_pathexample.json, input_key_namequery)从 Confident AI 拉取dataset.pull(aliasMy Evals Dataset)需要先登录。注意一个EvaluationDataset只能装单轮或只能装多轮 golden不能混装文件里两种混在一起会直接报错。第一步用 tracing 给应用加测点这是evals_iterator()的前置条件。以手动插桩为例把顶层函数用observe包起来再用update_current_trace(...)写入 trace 级的测试用例字段from deepeval.tracing import observe, update_current_trace from deepeval.metrics import TaskCompletionMetric observe() def my_ai_agent(query: str) - str: answer ... # call your LLM here update_current_trace(inputquery, outputanswer) return answer几个文档明确的关键点update_current_trace的参数名与LLMTestCase一一对应唯一例外是actual_output在 trace/span 上改叫output。可以在不同 span 里多次调用update_current_trace值会跨调用合并后调用的覆盖先调用的——这让 trace 级测试用例随数据流逐步积累完整。如果你用的是 LangChain、LangGraph、OpenAI、Pydantic AI、CrewAI 等框架deepeval 提供了对应的一行或几行插桩入口例如 LangChain 传CallbackHandlerOpenAI 用from deepeval.openai import OpenAI替换原 import 并配合with trace():完整接口见 tracing 文档/evaluation-llm-tracing.mdx)。第二步用 evals_iterator 循环评估插桩完成后用迭代器循环 golden。文档示例Async 变体默认且最快import asyncio from deepeval.metrics import TaskCompletionMetric for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): task asyncio.create_task(my_ai_agent(golden.input)) dataset.evaluate(task)Sync 变体调试、限流场景、或某些 Jupyter 环境下from deepeval.evaluate import AsyncConfig for golden in dataset.evals_iterator( metrics[TaskCompletionMetric()], async_configAsyncConfig(run_asyncFalse), ): my_ai_agent(golden.input)evals_iterator()有六个可选参数全部按需使用参数用途metrics作用于trace 级的BaseMetric列表即端到端指标给整条 trace 打分identifier该 test run 在 Confident AI 上的字符串标签async_configAsyncConfig控制并发如上面的run_asyncFalsedisplay_configDisplayConfig控制控制台输出error_configErrorConfig控制错误处理cache_configCacheConfig控制缓存metrics传入后是 trace 级挂载只判断可观测结果的指标属于端到端指标分析内部有序 span 的指标则属于轨迹评估。文档建议在单次运行中保持指标精简——不超过 5 个由 2~3 个通用指标加 1~2 个自定义指标GEval或自定义 metric组成。验证查看测试运行结果每次迭代器运行都会把快照写到磁盘可以直接用deepeval inspect在终端 TUI 里打开查看 metric 分数、失败原因、输入输出、工具调用和检索上下文deepeval inspect不带参数时Python 版会自动读取最近一次运行重写的.deepeval/.latest_run_full.json也可以显式指向文件或目录deepeval inspect ./experiments/test_run_20260512_174200.json deepeval inspect ./experiments # 目录内最新的 test_run_*.json deepeval inspect --folder ./experiments # 用显式 flag 指定目录TUI 的操作↑/↓或j/k移动h/l折叠/展开 span←/→或n/p在不同 trace 间切换/按名称过滤 spany把选中节点复制为 JSONY复制整条 trace?查看键位表q退出。这个 TUI 是 trace 查看器只对捕获了 trace 的运行有意义——没有插桩的evaluate()运行看不到 span 树。Python 端 TUI 依赖一个可选 extras 包Textual 剪贴板支持需要单独安装pip install deepeval[inspect]两个行为细节在交互式终端里evals_iterator()运行结束且至少一个测试用例捕获了 trace 时deepeval 会主动提示在 TUI 中打开。可以用DisplayConfig(inspect_after_runFalse)按次关闭或用环境变量DEEPEVAL_NO_INSPECT_PROMPT1全局关闭例如 CI 里。若已执行deepeval login登录 Confident AI同一份运行会额外生成可在平台上的测试报告包含每个测试用例的分数、原因及其背后 trace这是可选的云端能力本地评估不需要账号。可选记录超参数如果你想对比不同模型/提示词配置下的分数可以在每次 test run 上记录超参数。值必须是str | int | float或Prompt对象import deepeval from deepeval.metrics import TaskCompletionMetric deepeval.log_hyperparameters def hyperparameters(): return {model: gpt-4.1, system_prompt: Be concise.} for golden in dataset.evals_iterator(metrics[TaskCompletionMetric()]): my_ai_agent(golden.input)边界与限制迭代器路径要求你的应用能被插桩observe或框架集成测试无法修改的第三方 API 时只能用evaluate()手动构造LLMTestCase。同一 trace 运行中不能混装LLMTestCase与ConversationalTestCase多轮评估也不走evals_iterator()只支持evaluate()。如果要在 CI/CD 里跑同一套单轮评估文档给出的做法是把迭代器/evaluate()换成 pytest 断言assert_test(goldengolden, metrics[...])再用deepeval test run test_llm_app.py执行失败指标会直接让构建失败参数与 YAML 流水线示例见 unit testing in CI/CD 文档。如果之后想给单个组件检索器、工具调用、内部 LLM 调用单独打分同一套 trace 支持挂observe(metrics[...])做 component-level 评估不需要改动现有插桩。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
