DeepEval 评估接入五问基于 intake 文档的评测工作流入场决策指南【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval本文基于 DeepEval 官方 Agent 技能包中的 intake.md 展开详解在为一个 LLM 应用搭建 DeepEval 评测体系之前必须向用户确认的五个关键问题评估模型、数据集来源、Tracing、Confident AI 结果、迭代轮数、Confident AI 强信号识别规则与数据集分支处理策略。读完后你将掌握 DeepEval 评估工作流SKILL.md 定义的完整闭环的入场决策方法并能结合 deepeval/cli/generate/command.py、deepeval/dataset/dataset.py 等源码理解每个决策项背后的真实实现。一、intake 文档在 DeepEval 技能体系中的位置DeepEval 仓库内置了一套面向 AI Agent 的可执行技能包skills/目录其中主技能 SKILL.md 定义了端到端评估闭环检查目标应用与已有 DeepEval 用法询问 intake 问题本文主题复用已有的指标与数据集有数据集则复用没有则用deepeval generate生成 goldens按需接入 tracing由独立的deepeval-tracing技能负责运行deepeval test run按约定轮数默认 5 轮迭代改进。intake 环节正是第 2 步文档开篇明确约定——“Ask these questions before editing application code. Keep them concise and use the defaults when the user wants you to decide.”即在动任何应用代码之前完成问询提问保持简洁当用户表示“你来定”时直接采用各问题的默认选项而不是追问。前置条件来自 SKILL.md 的 PrerequisitesPython 3.9、pip install deepeval、指标计算与合成生成所需的模型凭证以及 Confident AI 汇报所需的deepeval login。二、五个必问项Required Questions2.1 评估模型DeepEval 用什么模型当“裁判”intake 文档给出的标准问法是“Which evaluation model should DeepEval use? I can use your existing DeepEval config if one is already set.”候选项为复用已有的 DeepEval 配置默认OpenAIAnthropicGemini本地 / 自定义模型由用户提供这一项对应 DeepEval 的评估模型配置能力。从源码结构看deepeval/config/settings.py 提供了Settings.set_model_provider()便捷方法可在edit()原子编辑块内切换模型提供方并持久化若项目里已经存在 DeepEval 配置按 intake 规则应直接复用而不必重复配置。2.2 数据集来源golden 数据集从哪来标准问法“Do you already have a dataset of goldens?”四个候选项已有且已在工作区中已有但需要拖入工作区已有存放在 Confident AI 上没有请帮我生成一个这个分支直接决定了后续走加载路径references/datasets.md还是生成路径references/synthetic-data.md详见第四节的数据集分支详解。2.3 Tracing是否同时接入调用链追踪标准问法注意文档中的强推荐语气“Should I add DeepEval tracing while setting up evals? I strongly recommend yes: traces make failures inspectable, show which step broke, and make each iteration much faster.”候选项是加入 tracing以后再说Maybe latertracing 的价值主张很具体让失败可检查inspectable、能定位是哪一步出错、从而加快每轮迭代速度。这与 SKILL.md 核心原则第 3、6 条一致——“Prefer traced single-turn evals when the app can be instrumented”、“Strongly recommend tracing and Confident AI when the user mentions traces…”。2.4 Confident AI 结果评测结果是否上云标准问法“Do you want eval results on Confident AI? It is free of charge and gives you hosted reports, traces, run history, dashboards, production monitoring, and online evals.”候选项是把结果发到 Confident AI以后再说注意默认措辞把“免费free of charge”与六项能力托管报告、traces、运行历史、仪表盘、生产监控、在线评测绑定在一起备选答案统一使用“Maybe later”而非硬性“no”。这一问的配套规则强信号清单、鉴权方式、deepeval view命令、dataset.pull()/dataset.push()用法在 references/confident-ai.md 中有完整展开其中确认了deepeval login本地交互式与export CONFIDENT_API_KEY...CI/非交互式两种鉴权形态。2.5 迭代轮数跑几轮“评测-改进”循环标准问法“How many eval/improve rounds should I run? I recommend 5 rounds.”候选项推荐 5 轮默认1 轮3 轮自定义数量“轮”的具体含义由 references/iteration-loop.md 定义每一轮 运行评测套件 → 读取失败与分数 → 检查失败用例的 traces → 定位最小改动点 → 修改 prompt/检索/工具说明/解析逻辑 → 重跑 → 汇报变化。该参考文档同时给出单轮的推荐命令形态deepeval test run tests/evals/test_app.py \ --identifier iterating-on-purpose-round-1 \ --num-processes 5 \ --ignore-errors \ --skip-on-missing-params这些参数在 CLI 源码中均可验证见第五节--num-processes、--ignore-errors、--skip-on-missing-params、--identifier都是 deepeval/cli/test/command.py 中真实注册的选项。三、Confident AI 强信号识别与推荐话术intake 文档列出了 12 个“强信号”——只要用户在对话中提到以下任一项就应主动推荐 Confident AI 并解释原因production monitoring生产监控online evals在线评测tracing or traces调用链追踪dashboards仪表盘shared reports共享报告hosted results托管结果run history运行历史comparing eval runs对比多次评测运行debugging agent behavior over time随时间调试 Agent 行为user-facing AI outputs面向用户的 AI 输出user sentiment or intent用户情绪或意图issue tracking for AI interactionsAI 交互的问题跟踪文档同时规定了对应的推荐话术模板“Since you mentioned term, I recommend enabling Confident AI. It gives you hosted reports and trace history for free, which makes it much easier to inspect failures and compare runs across iterations.”即把用户提到的具体信号词填回term位置强调“托管报告与 trace 历史免费便于排查失败、跨迭代对比运行”。配套的 references/confident-ai.md 进一步补充了面向用户应用的判断方法检查代码中是否存在 chat UI、面向人类用户的 API 路由、鉴权用户、客户/支持流程、session ID、反馈按钮等信号以及适合以 trace 标签/元数据形式采集的问题维度用户情绪、用户意图、失败类别、客户层级、路由/功能、是否需要升级人工等。四、数据集分支Dataset Branches详解这是 intake 文档篇幅最大、实操密度最高的部分。四种数据集来源分别对应不同的处理分支4.1 数据集已在工作区只问路径按约定位置找规则如果路径不能从仓库结构中直接看出来就只追问路径优先寻找的候选文件名顺序为tests/evals/.dataset.json、.dataset.json、dataset.json、.jsonl或.csv文件。这与配套文档 references/datasets.md 中的加载 API 一一对应from deepeval.dataset import EvaluationDataset dataset EvaluationDataset() dataset.add_goldens_from_json_file(file_pathtests/evals/.dataset.json) # JSONL / CSV 分别对应 add_goldens_from_jsonl_file / add_goldens_from_csv_file这些方法在 deepeval/dataset/dataset.py 的EvaluationDataset类中均有实现另有push()dataset.py#L895、pull()dataset.py#L933和evals_iterator()dataset.py#L1565。datasets 参考文档还约定了 pytest 侧的写法直接在测试文件中、参数化之前加载数据集不要把加载逻辑藏进conftest.py或自定义 fixture 包装器。4.2 需要把数据集拖入工作区暂停等待不造占位数据规则非常明确问清最终路径后先暂停不要自行生成占位数据集——除非用户改口选择生成。这避免了“占位 goldens 被误当成真实评测集运行”的事故。4.3 数据集在 Confident AI走 pull/导出路径规则优先利用可用的 Confident AI MCP/API/项目上下文把它取回或导出为本地 goldens 文件如果没有这种访问能力就请用户自行导出或提供下载后的数据集路径。对应代码形态见 references/confident-ai.mddataset EvaluationDataset() dataset.pull(aliasMy Evals Dataset)alias 未知时询问用户凭证缺失时请用户先deepeval login或导出到工作区。4.4 没有数据集用deepeval generate生成严禁手写 goldens这是 intake 文档约束最严格的一条分支核心规则逐条如下1输出位置与禁令。用deepeval generate生成输出写入tests/evals/除非项目已有更清晰的评测数据目录不要手工创建或编造 goldens。2生成前先问源材料。选择生成方法之前先问用户有没有文档、知识库、支持文章、产品页面、README、导出的检索上下文或一个小型种子数据集。3方法优先级严格顺序。优先级方法适用条件1--method docs存在文档或知识库首选2--method contexts存在导出的检索上下文3--method goldens已有小规模种子数据集做增广4--method scratch以上都没有纯从零生成这一优先级在 references/synthetic-data.md 中重申为“Existing user-provided dataset documents/knowledge bases exported retrieval contexts existing-goldens augmentation scratch”并强调“Do not jump straight to scratch if the AI app has docs…”。CLI 侧对四种方法的必填参数强制校验与该方法选择完全一致deepeval/cli/generate/command.py 中docs必须带--documents、contexts必须带--contexts-file、scratch必须带--num-goldens、goldens必须带--goldens-file缺参会直接报错。4Styling 风格标志默认必传。对每一种生成方法都要推断 AI 应用的用途并默认传入风格标志single-turn 用--scenario用户是谁、处于什么情境、--task应用要完成什么、--input-format真实输入长什么样、--expected-output-format好的期望输出长什么样multi-turn 则用--scenario-context、--conversational-task、--participant-roles、--scenario-format、--expected-outcome-format。这些标志在 generate/command.py 中逐一注册并由single_turn_styling_config()/multi_turn_styling_config()组装后传给Synthesizergenerate/command.py#L243-L263。5用途不明时补一个三合一问题。问“What does your AI app do, who uses it, and what kinds of inputs should the eval dataset cover?”应用做什么、谁在用、评测数据集应覆盖哪些输入类型。6数据集规模红线。已有数据集不足 10 条 goldens 时“very likely too small”应建议增广一份有实用价值的首次生成数据集通常在 30-50 条用户表示自己的数据集“小、弱、不满意”时用 existing-goldens 增广--method goldens。7聊天机器人/多轮 Agent 默认生成多轮数据集。追加话术模板“Because this is a chatbot or multi-turn agent, I will generate multi-turn goldens by default. If you only want QA pairs for testing for now, say so and I will use single-turn generation.”只有当用户明确表示“先要单轮 QA 对做快速冒烟测试”时才切换为 single-turn。这一默认策略在 references/choose-use-case.md 的“Dataset Default”一节也被重申。一个完整的 docs 方法生成命令示例单轮来自 synthetic-data.mddeepeval generate \ --method docs \ --variation single-turn \ --documents ./docs \ --num-goldens 40 \ --scenario Users relying on the AI app for product-specific help \ --task Help users complete their task accurately using the available documentation \ --input-format Natural language requests with product-specific details \ --expected-output-format Concise, actionable output grounded in the provided documents \ --output-dir ./tests/evals \ --file-name .dataset五、源码佐证CLI 参数默认值与执行链路intake 文档中“use the defaults when the user wants you to decide”的“默认值”在源码中都有明确落点可逐一核对deepeval generate的参数默认值generate/command.py参数默认值说明--output-dir./synthetic_data生成结果保存目录intake 惯例是显式指定./tests/evals--file-typejson输出文件类型--async-mode/--sync-mode异步True是否并发生成--max-concurrent100最大并发生成任务数--include-expected/--no-include-expectedTrue是否生成期望输出/期望结果--cost-trackingFalse模型支持时打印生成成本--max-goldens-per-context2docs/contexts 方法下每个上下文最多生成的 goldens 数--max-goldens-per-golden2goldens 增广方法下每条既有 golden 的增广上限--max-contexts-per-document/--min-contexts-per-document3 / 1每个文档构造的上下文数量上下限--chunk-size/--chunk-overlap1024 / 0文档解析的 token 分块大小与重叠--context-quality-threshold0.5上下文质量最低阈值--max-retries3上下文构造质量检查的最大重试次数源码中还有一个值得注意的工程细节Synthesizer与ContextConstructionConfig通过模块级__getattr__惰性导入generate/command.py#L21-L38PEP 562使deepeval test run等无关命令不必在启动时付出 synthesizer 链的加载代价。deepeval test run的参数链路deepeval/cli/test/command.py--identifier用于标记每轮运行配合 iteration-loop 的--identifier iterating-on-purpose-round-N约定便于在 Confident AI 上跨轮次对比--num-processes N在源码中直接翻译为 pytest 的-n N参数即 pytest-xdist 并行小数据集或机器资源受限时应省略--ignore-errors与--skip-on-missing-params分别通过set_should_ignore_errors()/set_should_skip_on_missing_params()注入运行时开关。SKILL.md 的核心原则第 4 条也强调执行评测用deepeval test run而不是裸pytest。六、复用已有 DeepEval 用法先搜索再提问intake 文档最后一节要求在问不必要的问题之前先搜索代码库中是否已存在 DeepEval 用法搜索模式包括deepeval的 import 语句assert_testevaluate(以Metric结尾的指标类EvaluationDatasetobservedeepeval test rundeepeval generate一旦发现已有用法就把现有的指标、阈值、数据集、模型配置汇总给用户只就缺失的决策项提问。这与 SKILL.md 的“Reuse existing DeepEval metrics, thresholds, datasets, and model settings before introducing new ones”原则互为表里intake 的五个问题并非无条件全问而是“搜索先行、缺口补问”。七、intake 决策速查清单把 intake 文档的完整决策逻辑浓缩为可执行清单先搜索后提问按 8 个模式检索现有 DeepEval 用法已有配置/指标/阈值/数据集一律复用。五问定默认评估模型默认复用现有配置、数据集来源、tracing默认建议加、Confident AI默认建议开、备选 Maybe later、迭代轮数默认 5 轮。强信号即推荐命中 12 个 Confident AI 信号词之一时用固定话术模板推荐并解释“免费托管报告与 trace 历史”的价值。数据集四分支工作区已有 → 按tests/evals/.dataset.json等约定路径查找需拖入 → 问清路径后暂停、不造占位数据在 Confident AI →dataset.pull()或请用户导出没有 →deepeval generate方法按 docs contexts goldens scratch 排序styling 标志默认必传规模目标 30-50 条聊天机器人/多轮 Agent 默认 multi-turn。规模红线不足 10 条视为过小建议增广小规模/弱数据集用--method goldens增广而非手写。进入主流程intake 完成后按 SKILL.md 的 Required Workflow 进入测试形态与模板选择references/pytest-e2e-evals.md、skills/deepeval/templates/下的单轮 tracing/无 tracing/多轮 E2E 模板、数据集准备references/datasets.md / references/synthetic-data.md、tracing 接入deepeval-tracing技能与deepeval test run迭代循环references/iteration-loop.md。适用前提以上工作流基于当前仓库skills/deepeval技能包metadata 标注 Python 3.9、pip install deepeval、模型凭证Confident AI 相关能力需deepeval login或CONFIDENT_API_KEY所有命令与参数均以仓库当前源码为准。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考