DeepEval 评测数据集EvaluationDataset完整指南本地文件加载、Confident AI 拉取与 Pytest 评测规范【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval本文基于 DeepEval 技能参考文档skills/deepeval/references/datasets.md展开系统讲解评测数据集的选取规则、EvaluationDataset的四种加载方式本地 JSON/JSONL/CSV 与 Confident AI 云端拉取、单轮与多轮数据集的类型约束以及 Pytest 评测的官方代码规范。读完本文你可以直接复制可运行的数据集加载与参数化测试代码并结合仓库源码理解各参数、默认值与底层解析逻辑。一、数据集来源的严格顺序与规模基线DeepEval 技能文档对数据集从哪里来给出了不可妥协的顺序约束见 datasets.md先问用户是否已有数据集已有 → 直接用文档化的EvaluationDatasetAPI 加载不要自行发明包装函数没有 → 参考 synthetic-data.md 用deepeval generate命令生成而不是手写或编造 goldens。文档同时给出了两条规模经验值首次生成的评测数据集建议 3050 条 goldens少于 10 条 goldens 的数据集大概率太小应检查规模必要时用deepeval generate --method goldens对已有种子集做增强augmentation。如果用户坚持手写 goldens文档建议明确告知生成的 goldens 通常偏差更小、可复现性更强若最终采用少量手工种子集应先用deepeval generate --method goldens扩充后再投入正式评测。二、EvaluationDataset 数据模型单轮与多轮互斥所有加载 API 的宿主类是 EvaluationDataset它在 deepeval/dataset/__init__.py 中与Golden、ConversationalGolden、Persona一同导出。理解加载行为前先理解两个 golden 模型定义于 deepeval/dataset/golden.py模型适用场景关键字段Golden单轮评测input必填、actual_output、expected_output、context、retrieval_context、tools_called、expected_tools、additional_metadata、name、comments、source_file、custom_column_key_valuesConversationalGolden多轮对话 / Agent 评测scenario必填、expected_outcome、turnsTurn列表、persona或已弃用的user_description、context单轮与多轮是互斥的这一点在源码中有硬性校验dataset.pydef add_test_case(self, test_case: Union[LLMTestCase, ConversationalTestCase]): ... if isinstance(test_case, LLMTestCase): if self._conversational_goldens or self._conversational_test_cases: raise TypeError(You cannot add LLMTestCase to a multi-turn dataset.) ... elif isinstance(test_case, ConversationalTestCase): if self._goldens or self._llm_test_cases: raise TypeError(You cannot add ConversationalTestCase to a single-turn dataset.) self._multi_turn Trueadd_golden对Golden/ConversationalGolden做同样的双向校验。数据集在构造或首次添加时根据首个元素确定_multi_turn标志此后dataset.goldens与dataset.test_cases属性会自动返回对应类型的列表。因此文档强调加载完成后一个数据集要么全是单轮、要么全是多轮不能混放Golden和ConversationalGolden。三、加载本地文件JSON / JSONL / CSV文档给出的最简用法from deepeval.dataset import EvaluationDataset # 本地 JSON dataset EvaluationDataset() dataset.add_goldens_from_json_file(file_pathtests/evals/.dataset.json) # 本地 JSONL dataset EvaluationDataset() dataset.add_goldens_from_jsonl_file(file_pathtests/evals/.dataset.jsonl) # 本地 CSV dataset EvaluationDataset() dataset.add_goldens_from_csv_file(file_pathtests/evals/.dataset.csv)3.1 JSON 加载add_goldens_from_json_fileJSON 文件应为对象数组。结合 add_goldens_from_json_file 的源码签名各键名参数及默认值如下参数默认值说明file_path必填JSON 文件路径input_key_nameinput单轮输入字段actual_output_key_nameactual_output模型实际输出可选字段expected_output_key_nameexpected_output期望输出context_key_namecontext上下文列表retrieval_context_key_nameretrieval_context检索上下文支持带source的RetrievedContextDatatools_called_key_name/expected_tools_key_nametools_called/expected_tools工具调用解析为ToolCall对象comments_key_name/name_key_namecomments/name备注与名称source_file_key_namesource_file来源文件标记additional_metadata_key_nameadditional_metadata自定义元数据dictcustom_column_key_values_key_namecustom_column_key_values自定义列键值对scenario_key_name/turns_key_namescenario/turns多轮场景描述与轮次expected_outcome_key_name/user_description_key_nameexpected_outcome/user_description多轮期望结果与用户描述persona_key_namepersona多轮人格dict 会自动构造为Persona对象encoding_typeutf-8文件编码一个值得注意的实现细节源码中逐条检查是否存在scenario键且非空来判定该行是ConversationalGolden还是Goldendataset.py#L700。但结合第二节的类型互斥校验可知实际使用中一个 JSON 文件仍应只承载一种类型——EvaluationDataset.__init__以首个 golden 决定_multi_turn混入另一类型会在add_golden处抛出TypeError。3.2 JSONL 加载add_goldens_from_jsonl_fileadd_goldens_from_jsonl_file 的键名参数与 JSON 版基本一致额外提供了两个分隔符参数context_col_delimiter与retrieval_context_col_delimiter默认均为|。它的context解析比 JSON 版更宽容——既接受原生列表也接受用分隔符拼接的字符串dataset.py#L786-L795并且对逐行解析失败会报出具体行号contains invalid JSON on line N便于定位坏行。3.3 CSV 加载add_goldens_from_csv_fileadd_goldens_from_csv_file 默认列名input、actual_output、expected_output、context、retrieval_context、tools_called、expected_tools、comments、name、source_file、additional_metadata、custom_column_key_values以及多轮列scenario、turns、expected_outcome、user_description。文档特别提示如果 CSV 使用了自定义列名必须在调用时显式传入对应的列名参数。CSV 加载依赖pandas未安装会提示pip install pandas。列表值单元格使用统一的分隔符约定定义于 deepeval/dataset/utils.py普通列表context等用|分隔工具列表tools_called、expected_tools用;分隔单元格内容是 JSON 字符串解析失败时回退为按分隔符拆分retrieval_context中的RetrievedContextData会以deepeval_source...,deepeval_context...标记串持久化加载时自动还原utils.py#L81-L99保证存/读往返无损。同样地源码以该行scenario列是否有值区分多轮行并构造ConversationalGoldendataset.py#L634-L648。3.4 保存save_as 与加载互为镜像EvaluationDataset.save_as(file_type, directory, file_name, include_test_cases)支持json/csv/jsonl三种格式dataset.py#L1226-L1289写出的字段与上述加载默认键名/列名完全对齐因此deepeval generate生成的.dataset.json可以被add_goldens_from_json_file零改动读回。四、Confident AI 云端数据集pull 与 push当用户声明数据集存放在 Confident AI且凭据deepeval login或CONFIDENT_API_KEY可用时文档指定使用dataset EvaluationDataset() dataset.pull(aliasMy Evals Dataset)pull 的完整参数参数默认值说明alias必填数据集别名finalizedTrue只拉取已标注定稿的 goldensauto_convert_goldens_to_test_casesFalse拉取后是否自动把 goldens 转为 test casespublicFalse是否拉取公共数据集versionNone指定数据集版本拉取后数据集会记录_alias、_id、_version并根据响应中是goldens还是conversationalGoldens自动确定单/多轮模式dataset.py#L975-L978。反向操作push(alias, finalized, version)会校验非空并 POST 到 Confident AIdataset.py#L895-L931配合 synthetic-data.md 的生成后询问是否保存到 Confident AI流程本地生成的数据集可以一键云端复用与标注。此外还有queue追加未定稿 goldens、create_version、get_versions、delete、update_golden、delete_golden等维护方法全部需要有效的 Confident AI 凭据。五、Pytest 官方规范参数化、add_test_case 与多轮模拟器文档对 Pytest 集成有两条明确的不要做约束数据集加载必须直接写在测试文件里、且紧邻参数化之前不要把加载逻辑藏进conftest.py或自定义 fixture 包装。官方单轮模板test_single_turn_no_tracing.py正是这一规范的落地from deepeval import assert_test from deepeval.dataset import EvaluationDataset, Golden from deepeval.test_case import LLMTestCase dataset EvaluationDataset() dataset.add_goldens_from_json_file(file_pathtests/evals/.dataset.json) pytest.mark.parametrize(golden, dataset.goldens) def test_single_turn_no_tracing(golden: Golden): actual_output ai_app.run_ai_app(golden.input) test_case LLMTestCase( inputgolden.input, actual_outputactual_output, expected_outputgetattr(golden, expected_output, None), contextgetattr(golden, context, None), retrieval_contextgetattr(golden, retrieval_context, None), ) assert_test(test_casetest_case, metricsSINGLE_TURN_NO_TRACING_METRICS)两个补充规范先构建后断言的端到端 test case 要回填数据集。文档要求用dataset.add_test_case(...)把运行时构造的 test case 加回数据集必要时改为对dataset.test_cases参数化。从源码看dataset.py#L211-L231add_test_case会自动写入_dataset_alias、_dataset_id、_dataset_rank保持与云端数据集的追踪关联。多轮 / 聊天机器人评测走模拟器路径。加载后的多轮数据集包含ConversationalGolden应把dataset.goldens传给ConversationSimulator.simulate(...)生成ConversationalTestCase供 pytest 参数化。官方多轮模板test_multi_turn_e2e.py展示了标准写法simulator ConversationSimulator(model_callbackai_app.chatbot_callback) dataset EvaluationDataset() dataset.add_goldens_from_json_file(file_pathtests/evals/.dataset.json) pytest.mark.parametrize( test_case, simulator.simulate( conversational_goldensdataset.goldens, max_user_simulationsMAX_TURNS, ), ) def test_multi_turn(test_case): assert_test(test_casetest_case, metricsMULTI_TURN_METRICS)simulate内部由ConversationalGolden的scenario、persona/user_description与expected_outcome驱动 LLM 扮演用户逐轮对话max_user_simulations限制最大轮数这正是第四节中多轮字段scenario、turns、expected_outcome的下游消费者。六、无数据集时的生成路径deepeval generate文档将没有数据集的情形全部导向 synthetic-data.md其生成方法优先级为已有用户数据集 文档知识库--method docs 导出检索上下文--method contexts 现有小数据集增强--method goldens 从零生成--method scratch。以 docs 方法为例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生成产物建议放在tests/evals/.dataset.json作为可见、可编辑、可提交进版本库的评测资产随后用第三节的add_goldens_from_json_file加载。EvaluationDataset自身也提供generate_goldens_from_docs/generate_goldens_from_contexts/generate_goldens_from_scratch三个 Python 等价入口dataset.py#L1153-L1224底层均委托给Synthesizer。七、速查清单数据集来源顺序已有 → 直接加载没有 →deepeval generate不要手写 goldens规模目标 3050 条少于 10 条视为过小用--method goldens增强本地文件add_goldens_from_json_file/add_goldens_from_jsonl_file/add_goldens_from_csv_file自定义列名/键名必须显式传参CSV 依赖 pandas云端dataset.pull(alias...)需 Confident AI 凭据finalized/version/public控制拉取范围Pytest加载紧邻参数化、不藏 confteste2e 用dataset.add_test_case(...)回填类型约束单轮Golden与多轮ConversationalGolden在同一个数据集中互斥源码强制校验多轮链路ConversationalGolden→ConversationSimulator.simulate(...)→ConversationalTestCase→assert_test。所有 API 与参数的最终依据均可在 deepeval/dataset/dataset.py、deepeval/dataset/golden.py 与 deepeval/dataset/utils.py 中逐行核对。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepEval 评测数据集（EvaluationDataset）完整指南：本地文件加载、Confident AI 拉取与 Pytest 评测规范
DeepEval 评测数据集EvaluationDataset完整指南本地文件加载、Confident AI 拉取与 Pytest 评测规范【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval本文基于 DeepEval 技能参考文档skills/deepeval/references/datasets.md展开系统讲解评测数据集的选取规则、EvaluationDataset的四种加载方式本地 JSON/JSONL/CSV 与 Confident AI 云端拉取、单轮与多轮数据集的类型约束以及 Pytest 评测的官方代码规范。读完本文你可以直接复制可运行的数据集加载与参数化测试代码并结合仓库源码理解各参数、默认值与底层解析逻辑。一、数据集来源的严格顺序与规模基线DeepEval 技能文档对数据集从哪里来给出了不可妥协的顺序约束见 datasets.md先问用户是否已有数据集已有 → 直接用文档化的EvaluationDatasetAPI 加载不要自行发明包装函数没有 → 参考 synthetic-data.md 用deepeval generate命令生成而不是手写或编造 goldens。文档同时给出了两条规模经验值首次生成的评测数据集建议 3050 条 goldens少于 10 条 goldens 的数据集大概率太小应检查规模必要时用deepeval generate --method goldens对已有种子集做增强augmentation。如果用户坚持手写 goldens文档建议明确告知生成的 goldens 通常偏差更小、可复现性更强若最终采用少量手工种子集应先用deepeval generate --method goldens扩充后再投入正式评测。二、EvaluationDataset 数据模型单轮与多轮互斥所有加载 API 的宿主类是 EvaluationDataset它在 deepeval/dataset/__init__.py 中与Golden、ConversationalGolden、Persona一同导出。理解加载行为前先理解两个 golden 模型定义于 deepeval/dataset/golden.py模型适用场景关键字段Golden单轮评测input必填、actual_output、expected_output、context、retrieval_context、tools_called、expected_tools、additional_metadata、name、comments、source_file、custom_column_key_valuesConversationalGolden多轮对话 / Agent 评测scenario必填、expected_outcome、turnsTurn列表、persona或已弃用的user_description、context单轮与多轮是互斥的这一点在源码中有硬性校验dataset.pydef add_test_case(self, test_case: Union[LLMTestCase, ConversationalTestCase]): ... if isinstance(test_case, LLMTestCase): if self._conversational_goldens or self._conversational_test_cases: raise TypeError(You cannot add LLMTestCase to a multi-turn dataset.) ... elif isinstance(test_case, ConversationalTestCase): if self._goldens or self._llm_test_cases: raise TypeError(You cannot add ConversationalTestCase to a single-turn dataset.) self._multi_turn Trueadd_golden对Golden/ConversationalGolden做同样的双向校验。数据集在构造或首次添加时根据首个元素确定_multi_turn标志此后dataset.goldens与dataset.test_cases属性会自动返回对应类型的列表。因此文档强调加载完成后一个数据集要么全是单轮、要么全是多轮不能混放Golden和ConversationalGolden。三、加载本地文件JSON / JSONL / CSV文档给出的最简用法from deepeval.dataset import EvaluationDataset # 本地 JSON dataset EvaluationDataset() dataset.add_goldens_from_json_file(file_pathtests/evals/.dataset.json) # 本地 JSONL dataset EvaluationDataset() dataset.add_goldens_from_jsonl_file(file_pathtests/evals/.dataset.jsonl) # 本地 CSV dataset EvaluationDataset() dataset.add_goldens_from_csv_file(file_pathtests/evals/.dataset.csv)3.1 JSON 加载add_goldens_from_json_fileJSON 文件应为对象数组。结合 add_goldens_from_json_file 的源码签名各键名参数及默认值如下参数默认值说明file_path必填JSON 文件路径input_key_nameinput单轮输入字段actual_output_key_nameactual_output模型实际输出可选字段expected_output_key_nameexpected_output期望输出context_key_namecontext上下文列表retrieval_context_key_nameretrieval_context检索上下文支持带source的RetrievedContextDatatools_called_key_name/expected_tools_key_nametools_called/expected_tools工具调用解析为ToolCall对象comments_key_name/name_key_namecomments/name备注与名称source_file_key_namesource_file来源文件标记additional_metadata_key_nameadditional_metadata自定义元数据dictcustom_column_key_values_key_namecustom_column_key_values自定义列键值对scenario_key_name/turns_key_namescenario/turns多轮场景描述与轮次expected_outcome_key_name/user_description_key_nameexpected_outcome/user_description多轮期望结果与用户描述persona_key_namepersona多轮人格dict 会自动构造为Persona对象encoding_typeutf-8文件编码一个值得注意的实现细节源码中逐条检查是否存在scenario键且非空来判定该行是ConversationalGolden还是Goldendataset.py#L700。但结合第二节的类型互斥校验可知实际使用中一个 JSON 文件仍应只承载一种类型——EvaluationDataset.__init__以首个 golden 决定_multi_turn混入另一类型会在add_golden处抛出TypeError。3.2 JSONL 加载add_goldens_from_jsonl_fileadd_goldens_from_jsonl_file 的键名参数与 JSON 版基本一致额外提供了两个分隔符参数context_col_delimiter与retrieval_context_col_delimiter默认均为|。它的context解析比 JSON 版更宽容——既接受原生列表也接受用分隔符拼接的字符串dataset.py#L786-L795并且对逐行解析失败会报出具体行号contains invalid JSON on line N便于定位坏行。3.3 CSV 加载add_goldens_from_csv_fileadd_goldens_from_csv_file 默认列名input、actual_output、expected_output、context、retrieval_context、tools_called、expected_tools、comments、name、source_file、additional_metadata、custom_column_key_values以及多轮列scenario、turns、expected_outcome、user_description。文档特别提示如果 CSV 使用了自定义列名必须在调用时显式传入对应的列名参数。CSV 加载依赖pandas未安装会提示pip install pandas。列表值单元格使用统一的分隔符约定定义于 deepeval/dataset/utils.py普通列表context等用|分隔工具列表tools_called、expected_tools用;分隔单元格内容是 JSON 字符串解析失败时回退为按分隔符拆分retrieval_context中的RetrievedContextData会以deepeval_source...,deepeval_context...标记串持久化加载时自动还原utils.py#L81-L99保证存/读往返无损。同样地源码以该行scenario列是否有值区分多轮行并构造ConversationalGoldendataset.py#L634-L648。3.4 保存save_as 与加载互为镜像EvaluationDataset.save_as(file_type, directory, file_name, include_test_cases)支持json/csv/jsonl三种格式dataset.py#L1226-L1289写出的字段与上述加载默认键名/列名完全对齐因此deepeval generate生成的.dataset.json可以被add_goldens_from_json_file零改动读回。四、Confident AI 云端数据集pull 与 push当用户声明数据集存放在 Confident AI且凭据deepeval login或CONFIDENT_API_KEY可用时文档指定使用dataset EvaluationDataset() dataset.pull(aliasMy Evals Dataset)pull 的完整参数参数默认值说明alias必填数据集别名finalizedTrue只拉取已标注定稿的 goldensauto_convert_goldens_to_test_casesFalse拉取后是否自动把 goldens 转为 test casespublicFalse是否拉取公共数据集versionNone指定数据集版本拉取后数据集会记录_alias、_id、_version并根据响应中是goldens还是conversationalGoldens自动确定单/多轮模式dataset.py#L975-L978。反向操作push(alias, finalized, version)会校验非空并 POST 到 Confident AIdataset.py#L895-L931配合 synthetic-data.md 的生成后询问是否保存到 Confident AI流程本地生成的数据集可以一键云端复用与标注。此外还有queue追加未定稿 goldens、create_version、get_versions、delete、update_golden、delete_golden等维护方法全部需要有效的 Confident AI 凭据。五、Pytest 官方规范参数化、add_test_case 与多轮模拟器文档对 Pytest 集成有两条明确的不要做约束数据集加载必须直接写在测试文件里、且紧邻参数化之前不要把加载逻辑藏进conftest.py或自定义 fixture 包装。官方单轮模板test_single_turn_no_tracing.py正是这一规范的落地from deepeval import assert_test from deepeval.dataset import EvaluationDataset, Golden from deepeval.test_case import LLMTestCase dataset EvaluationDataset() dataset.add_goldens_from_json_file(file_pathtests/evals/.dataset.json) pytest.mark.parametrize(golden, dataset.goldens) def test_single_turn_no_tracing(golden: Golden): actual_output ai_app.run_ai_app(golden.input) test_case LLMTestCase( inputgolden.input, actual_outputactual_output, expected_outputgetattr(golden, expected_output, None), contextgetattr(golden, context, None), retrieval_contextgetattr(golden, retrieval_context, None), ) assert_test(test_casetest_case, metricsSINGLE_TURN_NO_TRACING_METRICS)两个补充规范先构建后断言的端到端 test case 要回填数据集。文档要求用dataset.add_test_case(...)把运行时构造的 test case 加回数据集必要时改为对dataset.test_cases参数化。从源码看dataset.py#L211-L231add_test_case会自动写入_dataset_alias、_dataset_id、_dataset_rank保持与云端数据集的追踪关联。多轮 / 聊天机器人评测走模拟器路径。加载后的多轮数据集包含ConversationalGolden应把dataset.goldens传给ConversationSimulator.simulate(...)生成ConversationalTestCase供 pytest 参数化。官方多轮模板test_multi_turn_e2e.py展示了标准写法simulator ConversationSimulator(model_callbackai_app.chatbot_callback) dataset EvaluationDataset() dataset.add_goldens_from_json_file(file_pathtests/evals/.dataset.json) pytest.mark.parametrize( test_case, simulator.simulate( conversational_goldensdataset.goldens, max_user_simulationsMAX_TURNS, ), ) def test_multi_turn(test_case): assert_test(test_casetest_case, metricsMULTI_TURN_METRICS)simulate内部由ConversationalGolden的scenario、persona/user_description与expected_outcome驱动 LLM 扮演用户逐轮对话max_user_simulations限制最大轮数这正是第四节中多轮字段scenario、turns、expected_outcome的下游消费者。六、无数据集时的生成路径deepeval generate文档将没有数据集的情形全部导向 synthetic-data.md其生成方法优先级为已有用户数据集 文档知识库--method docs 导出检索上下文--method contexts 现有小数据集增强--method goldens 从零生成--method scratch。以 docs 方法为例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生成产物建议放在tests/evals/.dataset.json作为可见、可编辑、可提交进版本库的评测资产随后用第三节的add_goldens_from_json_file加载。EvaluationDataset自身也提供generate_goldens_from_docs/generate_goldens_from_contexts/generate_goldens_from_scratch三个 Python 等价入口dataset.py#L1153-L1224底层均委托给Synthesizer。七、速查清单数据集来源顺序已有 → 直接加载没有 →deepeval generate不要手写 goldens规模目标 3050 条少于 10 条视为过小用--method goldens增强本地文件add_goldens_from_json_file/add_goldens_from_jsonl_file/add_goldens_from_csv_file自定义列名/键名必须显式传参CSV 依赖 pandas云端dataset.pull(alias...)需 Confident AI 凭据finalized/version/public控制拉取范围Pytest加载紧邻参数化、不藏 confteste2e 用dataset.add_test_case(...)回填类型约束单轮Golden与多轮ConversationalGolden在同一个数据集中互斥源码强制校验多轮链路ConversationalGolden→ConversationSimulator.simulate(...)→ConversationalTestCase→assert_test。所有 API 与参数的最终依据均可在 deepeval/dataset/dataset.py、deepeval/dataset/golden.py 与 deepeval/dataset/utils.py 中逐行核对。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
