DeepEval 合成数据实战指南deepeval generate 四种 Golden 生成方法、样式参数与输出契约【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval本篇基于 DeepEval 技能库中的合成数据参考文档 synthetic-data.md 撰写完整覆盖deepeval generate命令的方法选择策略、单轮/多轮样式参数、四种生成方法docs / contexts / scratch / goldens的可复制命令并结合 CLI 实现源码 与 Synthesizer 实现 深入讲解参数默认值、底层上下文构建流程与生成结果的文件契约读完即可为任意 LLM 应用从零构建可复现、可提交的评估数据集。合成数据在 DeepEval 中的定位DeepEval 是 LLM 评估框架其评估的基本单位是goldens黄金样本数据集每个 golden 包含用户输入input、可选的期望输出expected_output以及可选的检索上下文context。当项目中没有现成数据集或希望扩充已有小数据集时参考文档给出的原则是明确的使用deepeval generate命令生成黄金样本不要手工编写或凭空捏造 goldens生成的文件必须可见、可编辑并在合适时随评估套件一起提交到版本库生成前先确认用户是否已有数据集——这是选择生成方法的第一步。这些原则背后有明确的工程理由手工编写的 golden 数量小、容易带主观偏差、不可复现而合成生成可以把数据集做到更大、覆盖更广并且同样的命令参数可以随时重新跑一遍得到同规格的新数据集。参考文档甚至给出了面对“用户坚持手写 golden”时的推荐话术建议用deepeval generate生成更大的数据集如果用户确实想手写一个小种子集也应当在依赖它之前先用deepeval generate --method goldens进行扩充。选择生成方法五种来源的优先级在生成之前先检查可用的源材料。参考文档给出的优先级顺序是用户已有的数据集最优无需生成文档型材料文档目录、知识库、支持文章、产品页面、README——使用--method docs导出的检索上下文——使用--method contexts已有小数据集的扩充——使用--method goldens从零生成——使用--method scratch。文档特别强调文档和知识库是最好的生成来源。如果 AI 应用有 docs、知识库、支持文章、产品页面、README 或导出的检索上下文就不应直接跳到 scratch。--method goldens的扩充场景则适用于三种信号用户明确表示数据集很小、用户对当前数据集不满或检查后发现数据集过小少于 10 条或覆盖面过窄。从源码看command.py 中的GenerationMethod枚举定义了四个方法值docs/contexts/scratch/goldens见 utils.py--variation则区分single-turn与multi-turn两种黄金样本形态。每个方法都有强制选项校验docs 必须传--documents、contexts 必须传--contexts-file、scratch 必须传--num-goldens、goldens 必须传--goldens-file缺失时会通过require_method_option抛出带参数名提示的BadParameter错误。CLI 完整参数速查以下参数表以 generate_command 的实际定义为准确认包含文档命令示例中未出现但 CLI 支持的完整参数参数默认值说明--method必填生成方法docs/contexts/scratch/goldens--variation必填样本形态single-turn/multi-turn--output-dir./synthetic_data生成结果保存目录--file-typejson输出文件类型json/csv/jsonl--file-name时间戳命名输出文件名不带扩展名不能含.--model无用于生成的模型名如gpt-4.1--async-mode/--sync-mode异步是否并发生成--max-concurrent100最大并发生成任务数--include-expected/--no-include-expected开启是否同时生成 expected output / expected outcome--cost-tracking关闭模型支持时打印生成成本--documents无docs 方法的文档路径可重复传入--contexts-file无contexts 方法的上下文 JSON 文件--goldens-file无goldens 方法要扩充的现有文件.json/.csv/.jsonl--num-goldens无scratch 必填scratch 方法要生成的样本数--max-goldens-per-context2每个上下文最多生成的 golden 数--max-goldens-per-golden2goldens 方法中每条现有 golden 最多衍生数--max-contexts-per-document3docs 方法每篇文档最多构建的上下文数--min-contexts-per-document1docs 方法每篇文档最少构建的上下文数--chunk-size1024文档解析的 token 分块大小--chunk-overlap0相邻分块的 token 重叠量--context-quality-threshold0.5上下文质量过滤阈值--context-similarity-threshold0.0上下文分组相似度阈值--max-retries3上下文构建质量检查的最大重试次数文档构建相关的这些参数在 ContextConstructionConfig 中有对应字段默认值与 CLI 完全一致如chunk_size1024、context_quality_threshold0.5、max_retries3CLI 只是把它们显式暴露出来方便不写 Python 的开发者直接调参。单轮与多轮的样式参数参考文档要求在生成前先推断 AI 应用的用例并默认传入样式参数——样式让生成的 golden 更贴近用户真实应用对 docs、contexts、goldens、scratch 四种方法都适用。单轮single-turn推断并传入 4 个参数--scenario用户是谁、处于什么情境--taskAI 应用要完成什么任务--input-format真实用户输入长什么样--expected-output-format好的期望输出应是什么样仅当生成期望输出时。多轮multi-turn推断并传入 5 个参数--scenario-context对话场景与用户情境--conversational-taskAI 应用要跨多轮完成什么--participant-roles对话参与者角色--scenario-format生成的场景应长什么样--expected-outcome-format成功的对话结果应是什么样仅当生成期望结果时。如果从代码库或文档中无法推断用例参考文档给出一个简洁的兜底问法What does your AI app do, who uses it, and what kinds of inputs should the eval dataset cover?从源码看这些参数最终组装成两个 dataclassStylingConfigscenario / task / input_format / expected_output_format和 ConversationalStylingConfigscenario_context / conversational_task / participant_roles / scenario_format / expected_outcome_format由 utils.py 中的single_turn_styling_config/multi_turn_styling_config构造后传给Synthesizer。需要注意一个强制校验scratch 方法对样式参数的要求是硬性约束。validate_scratch_styling 会检查单轮 scratch 必须同时提供--scenario、--task、--input-format多轮 scratch 必须同时提供--scenario-context、--conversational-task、--participant-roles缺失任意一项命令直接报错。generate_goldens_from_scratch 在 Python API 层同样会抛出TypeError。这与参考文档scratch requires the core styling flags的表述完全对应。四种生成方法的完整命令docs基于文档与知识库生成RAG 应用首选适合 RAG 应用或以文档为知识来源的应用。单轮示例继承自参考文档的完整命令deepeval 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对于聊天机器人或多轮 Agent 用例默认生成多轮 goldendeepeval generate \ --method docs \ --variation multi-turn \ --documents ./docs \ --num-goldens 40 \ --scenario-context Users having multi-turn conversations with the app \ --conversational-task Help users complete their task accurately across turns \ --participant-roles User and assistant \ --scenario-format A realistic conversation scenario with product-specific constraints \ --expected-outcome-format The user reaches a correct, actionable resolution grounded in the documents \ --output-dir ./tests/evals \ --file-name .dataset聊天机器人用例只有在用户明确要求先测 QA 对时才退回--variation single-turn。多个文档来源通过重复--documents传入deepeval generate \ --method docs \ --variation single-turn \ --documents ./docs \ --documents ./README.md \ --documents ./support_articles \ --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 .datasetcontexts基于导出的检索上下文生成当项目能把线上检索到的上下文导出为文件时使用。注意文件名是.json扩展名会由--file-type默认 json决定——这里--file-name .dataset实际会产出.dataset.json文件与输出契约一节一致。deepeval generate \ --method contexts \ --variation single-turn \ --contexts-file ./tests/evals/contexts.json \ --num-goldens 40 \ --scenario Users relying on the AI app for context-grounded help \ --task Help users complete their task accurately using retrieved context \ --input-format Natural language requests that should be answered from retrieved context \ --expected-output-format Concise, actionable output grounded in the provided contexts \ --output-dir ./tests/evals \ --file-name .datasetcontexts.json的形状是上下文的列表每个上下文本身是若干 chunk 组成的字符串列表[[chunk 1, chunk 2], [another context chunk]]load_contexts_file 会严格校验这一形状文件不存在、不是合法 JSON、顶层不是列表、或内层元素不是字符串列表都会抛出带清晰提示的BadParameter错误不会静默继续。scratch无文档、无数据集时从零生成适合完全没有材料时的兜底方案样式参数为必填项见上文强制校验。deepeval generate \ --method scratch \ --variation single-turn \ --num-goldens 40 \ --scenario Users asking questions about the app \ --task Answer accurately and concisely \ --input-format Natural language user questions \ --output-dir ./tests/evals \ --file-name .dataset聊天机器人或多轮 Agent 默认使用多轮 scratchdeepeval generate \ --method scratch \ --variation multi-turn \ --num-goldens 40 \ --scenario-context Users having multi-turn conversations with the app \ --conversational-task Help users complete their task accurately across turns \ --participant-roles User and assistant \ --output-dir ./tests/evals \ --file-name .datasetgoldens扩充已有小数据集当用户有一个小的种子数据集、想要更宽覆盖但不想推倒重来时用现有 golden 作为生成种子deepeval generate \ --method goldens \ --variation single-turn \ --goldens-file ./tests/evals/.dataset.json \ --num-goldens 40 \ --scenario Users represented by the existing seed dataset \ --task Expand coverage while preserving the AI apps intended behavior \ --input-format Inputs similar in style and structure to the seed goldens \ --output-dir ./tests/evals \ --file-name .dataset_augmentedload_goldens_file 支持.json/.csv/.jsonl三种种子文件格式内部统一通过EvaluationDataset的add_goldens_from_json_file/add_goldens_from_csv_file/add_goldens_from_jsonl_file加载。此外 validate_golden_variation 会检查种子文件与--variation的匹配多轮扩充要求种子文件中是会话型 goldenConversationalGolden单轮扩充则要求普通 golden不匹配时报错——避免单轮种子强行多轮扩充这类静默失败。源码级原理命令背后的 Synthesizer 调用链deepeval generate的每个命令最终都构造一个Synthesizer实例并调用对应的generate_*方法。以 docs 方法为例generate_goldens_from_docs 的同步路径可以概括为三步上下文构建把--documents交给ContextGenerator按chunk_size默认 1024 token切块结合嵌入模型相似度与批评模型critic model默认复用生成模型做质量过滤——低于--context-quality-threshold默认 0.5的上下文会被重试最多--max-retries次默认 3最终每篇文档产出min_contexts_per_document到max_contexts_per_document默认 1~3个高质量上下文输入合成与演化基于上下文合成初始输入再经过演化evolution改写。从 EvolutionConfig 看默认启用 7 种演化方向且权重均等各 1/7Reasoning、Multi-context、Concretizing、Constrained、Comparative、Hypothetical、In-Breadth——这解释了为什么同样一批文档反复生成会得到不同角度的问题golden 装配与保存每条上下文按--max-goldens-per-context默认 2产出 golden最后由 save_as 落盘。scratch 方法的链路更短generate_goldens_from_scratch 的同步路径为用PromptSynthesizerTemplate根据 scenario/task/input_format 批量生成初始输入 → 逐条_evolve_input演化Multi-context 演化在 scratch 场景下会被 transform_distribution 剔除因为 scratch 没有上下文可用→ 包装成Golden并把实际使用的演化类型写入additional_metadata.evolutions。所有 LLM 交互的结构化输出如SyntheticData、InputFeedback、ConversationalPromptStyling等都定义为 Pydantic 模型见 synthesizer/schema.py这是生成结果字段稳定的基础。数据集规模与成本控制参考文档对规模的建议是量化明确的检查已有数据集规模少于 10 条 golden 的数据集大概率不够应推荐扩充一个可用的首批评估数据集通常是30~50 条 golden如果担心生成成本或时间可以先生成小样本但要向用户说明这只是冒烟测试smoke test不是有评估力度的数据集只有用户明确要求冒烟测试时才生成极小的数据集例如deepeval generate \ --method scratch \ --variation single-turn \ --num-goldens 10 \ --scenario Users asking common questions about the app \ --task Answer accurately using the apps normal behavior \ --input-format Short natural language user questions \ --output-dir ./tests/evals \ --file-name .dataset模型与成本方面用户选定生成模型时通过--model传入如gpt-4.1并开启--cost-tracking打印生成成本模型支持时deepeval generate \ --method scratch \ --variation single-turn \ --num-goldens 40 \ --scenario Users asking common questions about the app \ --task Answer accurately using the apps normal behavior \ --input-format Short natural language user questions \ --model gpt-4.1 \ --cost-tracking \ --output-dir ./tests/evals \ --file-name .dataset从 generate_goldens_from_docs 等实现看synthesis_cost只在using_native_model即使用框架原生支持的模型时累计这也是--cost-tracking文档说明when supported by the model的出处。并发层面--async-mode默认开启配合--max-concurrent默认 100控制并发生成任务数是控制生成时长的主要手段。生成之后加载数据集与推送到 Confident AI生成的文件用 DeepEval 文档化的EvaluationDatasetAPI 加载即可投入评估dataset EvaluationDataset() dataset.add_goldens_from_json_file(file_pathtests/evals/.dataset.json)add_goldens_from_json_file定义在 dataset.py。如果用户尚未登录 Confident AI 或未导出CONFIDENT_API_KEY参考文档建议询问是否要把生成的数据集保存到 Confident AI免费便于后续复用、标注和分享并给出两个选项Yes, save it to Confident AI 或 Maybe later。用户同意时的流程是本地交互式设置用deepeval loginCI 或非交互环境用CONFIDENT_API_KEY然后推送数据集dataset.push(aliasMy Generated Dataset)push方法定义在 dataset.py。输出契约文件落在哪、长什么样参考文档的输出契约Output Contract规定优先生成tests/evals/.dataset.json这样的可见、可提交的文件不要把生成的 golden 只存放在隐藏缓存里——生成结果应当纳入评估套件一起管理。从 save_as 的实现可以确认单轮与多轮 JSON 的具体字段形状单轮 golden每条记录包含 5 个字段input、actual_output、expected_output、context、source_filedocs/contexts 方法下source_file记录上下文来源文件可追溯多轮 golden每条记录包含scenario、expected_outcome、context、source_files来自additional_metadata。同时save_as的约束与 CLI 行为一致file_name不能含.扩展名由--file-type追加、无生成结果时拒绝保存、目录不存在时自动创建os.makedirs。这也是为什么文档中--file-name .dataset配合默认--file-type json最终得到tests/evals/.dataset.json。csv与jsonl两种格式输出相同的字段集便于不同团队的工具链消费。参考资料参考文档主体skills/deepeval/references/synthetic-data.mdCLI 命令定义与参数默认值deepeval/cli/generate/command.py、deepeval/cli/generate/utils.py生成器核心实现deepeval/synthesizer/synthesizer.py、deepeval/synthesizer/config.py、deepeval/synthesizer/schema.py数据集加载与推送deepeval/dataset/dataset.py【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考