DeepEval TypeScript SDK 实战指南用 Vitest 风格测试为 LLM 应用构建端到端评估【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepevalDeepEval 是开源的 LLM 评估框架其 TypeScript SDK 以 Vitest 测试运行器为载体提供 G-Eval、任务完成度、答案相关性、幻觉检测等研究级指标让开发者在本机本地化运行 LLM-as-a-judge 评估。本文从安装、编写第一条测试用例开始完整讲解指标体系、Trace 追踪、框架集成、Judge 模型切换并对照仓库源码深入每个配置项的含义与默认值帮助你为 Agent、RAG 流水线和聊天机器人搭建可复现、可解释的自动化评估流程。Quickstart十分钟跑通第一条 LLM 评估测试安装与登录DeepEval TypeScript SDK 以开发依赖形式安装包名与 Python 版一致npm install --save-dev deepeval登录 Confident AI 可以把评估结果同步到云端、跨多次运行对比效果。登录免费且无需额外写代码——即使不登录评估结果也会照常打印到终端npx deepeval login登录命令由deepeval的 bin 入口提供见 typescript/package.json 中的bin: {deepeval: dist/cli/index.js}CLI 基于 commander 实现子命令包括login、test run、inspect、settings以及一组set-provider/unset-provider命令。编写第一条测试指标默认使用 OpenAI 作为 Judge 模型因此需要先设置OPENAI_API_KEY。SDK 会自动加载.env.local和.env文件对应源码 typescript/src/config/dotenv-handler.ts。import { LLMTestCase, SingleTurnParams } from deepeval/test-case; import { GEval } from deepeval/metrics; import { it, expect } from vitest; import deepeval/vitest; it(gives a correct answer, async () { const correctnessMetric new GEval({ name: Correctness, criteria: Determine if the actual output is correct based on the expected output., evaluationParams: [ SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT, ], threshold: 0.5, }); const testCase new LLMTestCase({ input: What if these shoes dont fit?, // Replace this with the actual output from your LLM application actualOutput: You have 30 days to get a full refund at no extra cost., expectedOutput: We offer a 30-day full refund at no extra costs., }); await expect(testCase).toPass([correctnessMetric]); });运行测试npx deepeval test run example.test.ts得分范围是 0 到 1threshold决定测试是否通过每个指标都会附带解释文本失败时会告诉你失败的原因。从源码看import deepeval/vitest这一步做了三件事见 typescript/src/integrations/vitest/index.mts调用expect.extend({ toPass })注册toPass()匹配器通过beforeAll/afterAll在测试文件层面开启并结束一次评估运行beginEvaluationRun/session.finish()并记录遥测事件通过beforeEach/afterEach调用beginTraceCapture()/endTraceCapture()为每个测试用例捕获 Trace 数据这样npx deepeval inspect才能回放测试执行轨迹。此外它还为 Vitest 的Assertion接口补充了toPass(metrics, options)的类型声明TypeScriptdeclare module vitest让你在测试文件里获得完整的类型提示。在原生 Vitest 下运行npx deepeval test run会自动注入toPass匹配器和测试运行报告器。如果你希望用项目自己的vitest命令运行需要在配置中手动注册import { defineConfig } from vitest/config; export default defineConfig({ test: { setupFiles: [deepeval/vitest], globalSetup: [deepeval/vitest/global-setup], testTimeout: 120_000, hookTimeout: 120_000, }, });globalSetup会在测试进程启动时分配本次运行的 run id通过环境变量传递保证同一会话内多个测试文件的事件被聚合为同一次运行。指标体系从通用 G-Eval 到专用指标所有指标都是从deepeval/metrics导出的类构造时接收一个 options 对象调用后返回score和reason。仓库中每个指标一个目录见 typescript/src/metrics目录内通常包含index.ts、指标实现和schema.ts输出 JSON Schema 校验。通用与自定义指标GEval用纯英文写出任意评估标准让 LLM 按标准打分是最灵活的全能型指标。其实现位于 typescript/src/metrics/g-eval/g-eval.ts核心选项包括选项类型说明namestring指标显示名默认会附加[GEval]后缀evaluationParamsSingleTurnParams[]参与评估的测试用例字段必填且不能为空否则构造器直接抛错criteriastring评估标准自然语言描述evaluationStepsstring[]可选的评估步骤不传时由模型基于 criteria 自动生成generateEvaluationStepsrubricRubric[]评分量表用于替代 0-1 连续打分thresholdnumber通过阈值默认 0.5model模型或字符串指定 Judge 模型strictModeboolean严格模式按整数分Math.trunc计分且阈值固定为 1topLogprobsnumber对支持 logprob 的模型加权备选得分 token默认 20flaky/verboseMode/showIndicatorboolean抖动标记、详细日志、进度指示includeGEvalSuffixboolean是否在指标名后加[GEval]默认 trueSingleTurnParams枚举定义在 typescript/src/test-case/llm-test-case.ts可选值包括INPUT、ACTUAL_OUTPUT、EXPECTED_OUTPUT、CONTEXT、RETRIEVAL_CONTEXT、TOOLS_CALLED、EXPECTED_TOOLS以及 MCP 相关字段MCP_SERVERS、MCP_TOOLS_CALLED、MCP_RESOURCES_CALLED、MCP_PROMPTS_CALLED。DAGMetric当你需要可重复、确定性的判定结果时用 DAGMetric 把多个 LLM 判定组织成一颗决策树按树结构逐节点求值。对应实现位于 typescript/src/metrics/dag。Agentic智能体指标面向 Agent 完整决策轨迹的指标TaskCompletionMetric任务是否完成ToolCorrectnessMetric工具调用是否正确GoalAccuracyMetric目标达成精度StepEfficiencyMetric步骤效率PlanAdherenceMetric是否遵循计划PlanQualityMetric计划质量ToolUseMetric工具使用ArgumentCorrectnessMetric论证正确性这些指标依赖LLMTestCase上的toolsCalled/expectedTools字段类型为ToolCall[]见 typescript/src/test-case/llm-test-case.tsToolCall支持name、description、typeFUNCTION或MCP、reasoning、output、inputParameters。RAG 指标检索增强生成场景下常用AnswerRelevancyMetric答案相关性FaithfulnessMetric忠实度答案是否忠实于检索上下文ContextualRecallMetric上下文召回ContextualPrecisionMetric上下文精确度ContextualRelevancyMetric上下文相关性它们依赖LLMTestCase.retrievalContext字段该字段接受字符串数组或RetrievedContextData对象含context与source两个属性序列化后形如source: context。多轮对话指标KnowledgeRetentionMetric、ConversationCompletenessMetric、TurnRelevancyMetric、TurnFaithfulnessMetric、RoleAdherenceMetric、TopicAdherenceMetric、TurnContextualPrecisionMetric、TurnContextualRecallMetric、TurnContextualRelevancyMetric、ConversationalGEval、ConversationalDAGMetric。多轮指标配合ConversationalTestCase使用后者内部包含turns数组。MCP 指标针对 Model Context Protocol 场景MCPTaskCompletionMetric、MCPUseMetric、MultiTurnMCPUseMetric。它们对应LLMTestCase上的mcpServers、mcpToolsCalled、mcpResourcesCalled、mcpPromptsCalled字段实现见 typescript/src/metrics/mcp。多模态指标TextToImageMetric、ImageEditingMetric、ImageCoherenceMetric、ImageHelpfulnessMetric、ImageReferenceMetric位于 typescript/src/metrics/multimodal-metrics。多模态用例通过LLMTestCase中的图片 slug 自动检测detectMultimodal配合MLLMImage注册表使用。安全、正确性与确定性指标HallucinationMetric、SummarizationMetric、BiasMetric、ToxicityMetric、JsonCorrectnessMetric、PromptAlignmentMetric、PIILeakageMetric、NonAdviceMetric、MisuseMetric、RoleViolationMetric。其中ExactMatchMetric和PatternMatchMetric完全不需要 LLM 参与是零成本、零延迟的确定性指标适合作为回归测试的第一道防线。指标独立使用指标可以脱离测试框架独立运行。先构造指标再调用measure(testCase)随后读取score与reasonimport { AnswerRelevancyMetric } from deepeval/metrics; import { LLMTestCase } from deepeval/test-case; const metric new AnswerRelevancyMetric({ threshold: 0.7 }); await metric.measure( new LLMTestCase({ input: What if these shoes dont fit?, actualOutput: We offer a 30-day full refund at no extra costs., }), ); console.log(metric.score, metric.reason);对于脚本场景可以用evaluate(testCases, metrics)从deepeval主入口导出一次批量打分而不必套用测试套件。Tracing评估完整的 Agent 轨迹用 observe() 包装函数把任意函数包进observe()DeepEval 会记录模型决策、工具调用和中间步骤的有序序列。有了 Trace你评估的不再只是最终答案而是完整的智能体轨迹并能对轨迹中的单个组件单独打分import { observe, updateCurrentSpan } from deepeval/tracing; import { AnswerRelevancyMetric } from deepeval/metrics; import { LLMTestCase } from deepeval/test-case; const retrieve observe({ type: retriever, metrics: [new AnswerRelevancyMetric()], fn: async (query: string) { const output await search(query); updateCurrentSpan({ testCase: new LLMTestCase({ input: query, actualOutput: output }), }); return output; }, });observe、updateCurrentSpan、updateCurrentTrace、traceManager、getCurrentSpan、getCurrentTrace、SpanType等 API 统一从deepeval/tracing导出见 typescript/src/tracing/index.ts。span 类型包括 LLM、Agent、Tool、Retriever 等每种都有对应的更新函数updateLlmSpan、updateRetrieverSpan等。用 evalsIterator() 跑数据集通过evalsIterator()把数据集送入被追踪的应用逐条执行。Trace 级指标评判整条轨迹nextLlmSpan以及nextAgentSpan、nextToolSpan、nextRetrieverSpan则把指标挂载到下一个匹配的组件 span 上实现组件级评分import { EvaluationDataset, Golden } from deepeval/dataset; import { TaskCompletionMetric } from deepeval/metrics; const dataset new EvaluationDataset({ goldens: [new Golden({ input: Whats the weather in Tokyo? })], }); for await (const golden of dataset.evalsIterator({ metrics: [new TaskCompletionMetric()], })) { await myAgent(golden.input); }Golden是最小粒度的数据单元只需input即可创建可选字段包括actualOutput、expectedOutput、context、retrievalContext、toolsCalled、expectedTools等见 typescript/src/dataset/golden.ts。EvaluationDataset同时支持单轮Golden/LLMTestCase与多轮ConversationalGolden/ConversationalTestCase两者不可混用源码会在添加时做类型校验见 typescript/src/dataset/dataset.ts。终端回放 Trace运行npx deepeval inspect即可在终端以交互式 UI 回放 Trace 树。该命令对应 typescript/src/inspect 目录底层基于 React ink 构建终端界面支持 span 树展开、详情查看等操作。框架集成免 observe 的自动追踪如果你在使用成熟的 Agent 框架可以完全跳过observe()——注册集成后框架自身的 span 就会成为 DeepEval 的 Trace其余代码保持不变。各框架仅初始化一行不同框架初始化方式OpenAIinstrumentOpenAI(client)来自deepeval/openaiLangChain / LangGraphnew DeepEvalCallbackHandler({})作为 callback 传入OpenAI AgentssetTraceProcessors([new DeepEvalTracingProcessor()])Mastranew DeepEvalExporter()作为 observability exporterAI SDKconfigureAiSdkTracing()作为experimental_telemetry.tracerOpenInferenceinstrumentOpenInference()每个集成位于deepeval/integrations/name子路径下与 typescript/package.json 中exports字段声明的入口一一对应。注意AI SDK 和 OpenInference 集成需要开启isTestMode: true才能让 Trace 数据到达evalsIterator。选择 Judge 模型指标默认用 OpenAI 作为 Judge因此多数场景只需OPENAI_API_KEY。切换模型有两种方式按指标指定在指标 options 中传model参数全局默认通过 CLI 设置npx deepeval set-anthropic --model claude-opus-5set-provider/unset-provider命令对每个 provider 生成完全一致的交互其声明式配置集中在 typescript/src/cli/providers.ts当前支持以下 providerProvider关键环境变量额外选项OpenAIOPENAI_API_KEY、OPENAI_MODEL_NAME成本跟踪OPENAI_COST_PER_INPUT_TOKEN等Azure OpenAIAZURE_OPENAI_API_KEY、AZURE_MODEL_NAME--base-url、--api-version、--model-version、--deployment-nameAnthropicANTHROPIC_API_KEY、ANTHROPIC_MODEL_NAME成本跟踪AWS BedrockAWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY--regionOllamaOLLAMA_MODEL_NAME--base-url默认http://localhost:11434自动写入占位 keyollamaLocal modelLOCAL_MODEL_NAME、LOCAL_MODEL_BASE_URL--format默认jsonGrokGROK_API_KEY、GROK_MODEL_NAME成本跟踪MoonshotMOONSHOT_API_KEY、MOONSHOT_MODEL_NAME--base-urlDeepSeekDEEPSEEK_API_KEY、DEEPSEEK_MODEL_NAME成本跟踪GeminiGOOGLE_API_KEY、GEMINI_MODEL_NAME--project、--location、--service-account-fileVertex AIPortkeyPORTKEY_API_KEY、PORTKEY_MODEL_NAME--base-url、--providerOpenRouterOPENROUTER_API_KEY、OPENROUTER_MODEL_NAME--base-url、--temperature从 typescript/src/cli/commands/providers.ts 可以看到set-*命令执行时会做三件事把其他 provider 的USE_*开关置空并只启用当前 providerswitchModelProvider、写入模型名与密钥、支持-i/-o覆盖每 token 成本用于未知模型的自定义成本跟踪。-k/--prompt-api-key与-a/--prompt-credentials选项可以在终端以隐藏输入方式录入密钥不适合 CI 环境。其它通用设置可通过npx deepeval settings查看与修改支持--set KEYVALUE、--unset、--list及大小写不敏感的部分匹配过滤set-confident-region可切换 Confident AI 数据区域US / EU / AUset-debug/unset-debug负责日志级别、verbose 模式、gRPC 日志与 Trace 采样率等调试开关详见 typescript/src/cli/commands/settings.ts。Python 与 TypeScript SDK 的差异两个 SDK 共享几乎全部指标以及 Tracing、数据集、Prompt、CLI 和 Confident AI 集成日常工作流一致。TypeScript 版独有的能力包括Vitest 的toPass()匹配器对应 Python 的assert_test、npx deepeval inspectTrace 查看器以及 Python 没有的 Mastra 与 AI SDK 集成。目前仍仅限 Python 的能力Synthesizer——合成数据集生成。TypeScript 需要手写 goldens 或从 Confident AI 拉取Benchmarks——MMLU、HellaSwag、DROP、BIG-Bench Hard、TruthfulQA、HumanEval、GSM8K 等对应 deepeval/benchmarks红队Red teaming与提示词优化RAGAS 指标以及AgentLoopDetectionMetric、ToolPermissionMetricCrewAI、LlamaIndex、Pydantic AI、Google ADK、AWS AgentCore、Strands、Anthropic client 等集成。两个 SDK 位于同一仓库Python 包在 deepeval 目录TypeScript 包在 typescript 目录两者的 provider 环境变量命名相互对齐typescript/src/cli/providers.ts 注释明确说明其镜像了 Python 的deepeval/key_handler.py这意味着你可以放心地在同一套 CI 配置里维护两套语言的评估。实战建议从确定性指标起步先加ExactMatchMetric/PatternMatchMetric做零成本回归再叠加 LLM-as-a-judge 指标控制质量上限阈值按指标场景设置G-Eval 默认阈值 0.5严格场景可开启strictMode得分取整、阈值固定为 1RAG 指标常用 0.6~0.7用 Trace 定位问题组件evalsIterator() span 级指标可以把一次失败的 Agent 轨迹精确归因到检索、工具调用或某个 LLM 步骤在 CI 中运行npx deepeval test run输出与 Vitest 兼容的测试报告配合--savedotenv让密钥与配置落盘到.env.local避免在流水线里硬编码密钥保持两端一致如果团队同时维护 Python 与 TypeScript 服务优先复用同一套数据与评估标准利用两者共享的 Confident AI 数据集同步能力EvaluationDataset.pull/push见 typescript/src/dataset/dataset.ts维持双端口径统一。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
DeepEval TypeScript SDK 实战指南：用 Vitest 风格测试为 LLM 应用构建端到端评估
DeepEval TypeScript SDK 实战指南用 Vitest 风格测试为 LLM 应用构建端到端评估【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepevalDeepEval 是开源的 LLM 评估框架其 TypeScript SDK 以 Vitest 测试运行器为载体提供 G-Eval、任务完成度、答案相关性、幻觉检测等研究级指标让开发者在本机本地化运行 LLM-as-a-judge 评估。本文从安装、编写第一条测试用例开始完整讲解指标体系、Trace 追踪、框架集成、Judge 模型切换并对照仓库源码深入每个配置项的含义与默认值帮助你为 Agent、RAG 流水线和聊天机器人搭建可复现、可解释的自动化评估流程。Quickstart十分钟跑通第一条 LLM 评估测试安装与登录DeepEval TypeScript SDK 以开发依赖形式安装包名与 Python 版一致npm install --save-dev deepeval登录 Confident AI 可以把评估结果同步到云端、跨多次运行对比效果。登录免费且无需额外写代码——即使不登录评估结果也会照常打印到终端npx deepeval login登录命令由deepeval的 bin 入口提供见 typescript/package.json 中的bin: {deepeval: dist/cli/index.js}CLI 基于 commander 实现子命令包括login、test run、inspect、settings以及一组set-provider/unset-provider命令。编写第一条测试指标默认使用 OpenAI 作为 Judge 模型因此需要先设置OPENAI_API_KEY。SDK 会自动加载.env.local和.env文件对应源码 typescript/src/config/dotenv-handler.ts。import { LLMTestCase, SingleTurnParams } from deepeval/test-case; import { GEval } from deepeval/metrics; import { it, expect } from vitest; import deepeval/vitest; it(gives a correct answer, async () { const correctnessMetric new GEval({ name: Correctness, criteria: Determine if the actual output is correct based on the expected output., evaluationParams: [ SingleTurnParams.ACTUAL_OUTPUT, SingleTurnParams.EXPECTED_OUTPUT, ], threshold: 0.5, }); const testCase new LLMTestCase({ input: What if these shoes dont fit?, // Replace this with the actual output from your LLM application actualOutput: You have 30 days to get a full refund at no extra cost., expectedOutput: We offer a 30-day full refund at no extra costs., }); await expect(testCase).toPass([correctnessMetric]); });运行测试npx deepeval test run example.test.ts得分范围是 0 到 1threshold决定测试是否通过每个指标都会附带解释文本失败时会告诉你失败的原因。从源码看import deepeval/vitest这一步做了三件事见 typescript/src/integrations/vitest/index.mts调用expect.extend({ toPass })注册toPass()匹配器通过beforeAll/afterAll在测试文件层面开启并结束一次评估运行beginEvaluationRun/session.finish()并记录遥测事件通过beforeEach/afterEach调用beginTraceCapture()/endTraceCapture()为每个测试用例捕获 Trace 数据这样npx deepeval inspect才能回放测试执行轨迹。此外它还为 Vitest 的Assertion接口补充了toPass(metrics, options)的类型声明TypeScriptdeclare module vitest让你在测试文件里获得完整的类型提示。在原生 Vitest 下运行npx deepeval test run会自动注入toPass匹配器和测试运行报告器。如果你希望用项目自己的vitest命令运行需要在配置中手动注册import { defineConfig } from vitest/config; export default defineConfig({ test: { setupFiles: [deepeval/vitest], globalSetup: [deepeval/vitest/global-setup], testTimeout: 120_000, hookTimeout: 120_000, }, });globalSetup会在测试进程启动时分配本次运行的 run id通过环境变量传递保证同一会话内多个测试文件的事件被聚合为同一次运行。指标体系从通用 G-Eval 到专用指标所有指标都是从deepeval/metrics导出的类构造时接收一个 options 对象调用后返回score和reason。仓库中每个指标一个目录见 typescript/src/metrics目录内通常包含index.ts、指标实现和schema.ts输出 JSON Schema 校验。通用与自定义指标GEval用纯英文写出任意评估标准让 LLM 按标准打分是最灵活的全能型指标。其实现位于 typescript/src/metrics/g-eval/g-eval.ts核心选项包括选项类型说明namestring指标显示名默认会附加[GEval]后缀evaluationParamsSingleTurnParams[]参与评估的测试用例字段必填且不能为空否则构造器直接抛错criteriastring评估标准自然语言描述evaluationStepsstring[]可选的评估步骤不传时由模型基于 criteria 自动生成generateEvaluationStepsrubricRubric[]评分量表用于替代 0-1 连续打分thresholdnumber通过阈值默认 0.5model模型或字符串指定 Judge 模型strictModeboolean严格模式按整数分Math.trunc计分且阈值固定为 1topLogprobsnumber对支持 logprob 的模型加权备选得分 token默认 20flaky/verboseMode/showIndicatorboolean抖动标记、详细日志、进度指示includeGEvalSuffixboolean是否在指标名后加[GEval]默认 trueSingleTurnParams枚举定义在 typescript/src/test-case/llm-test-case.ts可选值包括INPUT、ACTUAL_OUTPUT、EXPECTED_OUTPUT、CONTEXT、RETRIEVAL_CONTEXT、TOOLS_CALLED、EXPECTED_TOOLS以及 MCP 相关字段MCP_SERVERS、MCP_TOOLS_CALLED、MCP_RESOURCES_CALLED、MCP_PROMPTS_CALLED。DAGMetric当你需要可重复、确定性的判定结果时用 DAGMetric 把多个 LLM 判定组织成一颗决策树按树结构逐节点求值。对应实现位于 typescript/src/metrics/dag。Agentic智能体指标面向 Agent 完整决策轨迹的指标TaskCompletionMetric任务是否完成ToolCorrectnessMetric工具调用是否正确GoalAccuracyMetric目标达成精度StepEfficiencyMetric步骤效率PlanAdherenceMetric是否遵循计划PlanQualityMetric计划质量ToolUseMetric工具使用ArgumentCorrectnessMetric论证正确性这些指标依赖LLMTestCase上的toolsCalled/expectedTools字段类型为ToolCall[]见 typescript/src/test-case/llm-test-case.tsToolCall支持name、description、typeFUNCTION或MCP、reasoning、output、inputParameters。RAG 指标检索增强生成场景下常用AnswerRelevancyMetric答案相关性FaithfulnessMetric忠实度答案是否忠实于检索上下文ContextualRecallMetric上下文召回ContextualPrecisionMetric上下文精确度ContextualRelevancyMetric上下文相关性它们依赖LLMTestCase.retrievalContext字段该字段接受字符串数组或RetrievedContextData对象含context与source两个属性序列化后形如source: context。多轮对话指标KnowledgeRetentionMetric、ConversationCompletenessMetric、TurnRelevancyMetric、TurnFaithfulnessMetric、RoleAdherenceMetric、TopicAdherenceMetric、TurnContextualPrecisionMetric、TurnContextualRecallMetric、TurnContextualRelevancyMetric、ConversationalGEval、ConversationalDAGMetric。多轮指标配合ConversationalTestCase使用后者内部包含turns数组。MCP 指标针对 Model Context Protocol 场景MCPTaskCompletionMetric、MCPUseMetric、MultiTurnMCPUseMetric。它们对应LLMTestCase上的mcpServers、mcpToolsCalled、mcpResourcesCalled、mcpPromptsCalled字段实现见 typescript/src/metrics/mcp。多模态指标TextToImageMetric、ImageEditingMetric、ImageCoherenceMetric、ImageHelpfulnessMetric、ImageReferenceMetric位于 typescript/src/metrics/multimodal-metrics。多模态用例通过LLMTestCase中的图片 slug 自动检测detectMultimodal配合MLLMImage注册表使用。安全、正确性与确定性指标HallucinationMetric、SummarizationMetric、BiasMetric、ToxicityMetric、JsonCorrectnessMetric、PromptAlignmentMetric、PIILeakageMetric、NonAdviceMetric、MisuseMetric、RoleViolationMetric。其中ExactMatchMetric和PatternMatchMetric完全不需要 LLM 参与是零成本、零延迟的确定性指标适合作为回归测试的第一道防线。指标独立使用指标可以脱离测试框架独立运行。先构造指标再调用measure(testCase)随后读取score与reasonimport { AnswerRelevancyMetric } from deepeval/metrics; import { LLMTestCase } from deepeval/test-case; const metric new AnswerRelevancyMetric({ threshold: 0.7 }); await metric.measure( new LLMTestCase({ input: What if these shoes dont fit?, actualOutput: We offer a 30-day full refund at no extra costs., }), ); console.log(metric.score, metric.reason);对于脚本场景可以用evaluate(testCases, metrics)从deepeval主入口导出一次批量打分而不必套用测试套件。Tracing评估完整的 Agent 轨迹用 observe() 包装函数把任意函数包进observe()DeepEval 会记录模型决策、工具调用和中间步骤的有序序列。有了 Trace你评估的不再只是最终答案而是完整的智能体轨迹并能对轨迹中的单个组件单独打分import { observe, updateCurrentSpan } from deepeval/tracing; import { AnswerRelevancyMetric } from deepeval/metrics; import { LLMTestCase } from deepeval/test-case; const retrieve observe({ type: retriever, metrics: [new AnswerRelevancyMetric()], fn: async (query: string) { const output await search(query); updateCurrentSpan({ testCase: new LLMTestCase({ input: query, actualOutput: output }), }); return output; }, });observe、updateCurrentSpan、updateCurrentTrace、traceManager、getCurrentSpan、getCurrentTrace、SpanType等 API 统一从deepeval/tracing导出见 typescript/src/tracing/index.ts。span 类型包括 LLM、Agent、Tool、Retriever 等每种都有对应的更新函数updateLlmSpan、updateRetrieverSpan等。用 evalsIterator() 跑数据集通过evalsIterator()把数据集送入被追踪的应用逐条执行。Trace 级指标评判整条轨迹nextLlmSpan以及nextAgentSpan、nextToolSpan、nextRetrieverSpan则把指标挂载到下一个匹配的组件 span 上实现组件级评分import { EvaluationDataset, Golden } from deepeval/dataset; import { TaskCompletionMetric } from deepeval/metrics; const dataset new EvaluationDataset({ goldens: [new Golden({ input: Whats the weather in Tokyo? })], }); for await (const golden of dataset.evalsIterator({ metrics: [new TaskCompletionMetric()], })) { await myAgent(golden.input); }Golden是最小粒度的数据单元只需input即可创建可选字段包括actualOutput、expectedOutput、context、retrievalContext、toolsCalled、expectedTools等见 typescript/src/dataset/golden.ts。EvaluationDataset同时支持单轮Golden/LLMTestCase与多轮ConversationalGolden/ConversationalTestCase两者不可混用源码会在添加时做类型校验见 typescript/src/dataset/dataset.ts。终端回放 Trace运行npx deepeval inspect即可在终端以交互式 UI 回放 Trace 树。该命令对应 typescript/src/inspect 目录底层基于 React ink 构建终端界面支持 span 树展开、详情查看等操作。框架集成免 observe 的自动追踪如果你在使用成熟的 Agent 框架可以完全跳过observe()——注册集成后框架自身的 span 就会成为 DeepEval 的 Trace其余代码保持不变。各框架仅初始化一行不同框架初始化方式OpenAIinstrumentOpenAI(client)来自deepeval/openaiLangChain / LangGraphnew DeepEvalCallbackHandler({})作为 callback 传入OpenAI AgentssetTraceProcessors([new DeepEvalTracingProcessor()])Mastranew DeepEvalExporter()作为 observability exporterAI SDKconfigureAiSdkTracing()作为experimental_telemetry.tracerOpenInferenceinstrumentOpenInference()每个集成位于deepeval/integrations/name子路径下与 typescript/package.json 中exports字段声明的入口一一对应。注意AI SDK 和 OpenInference 集成需要开启isTestMode: true才能让 Trace 数据到达evalsIterator。选择 Judge 模型指标默认用 OpenAI 作为 Judge因此多数场景只需OPENAI_API_KEY。切换模型有两种方式按指标指定在指标 options 中传model参数全局默认通过 CLI 设置npx deepeval set-anthropic --model claude-opus-5set-provider/unset-provider命令对每个 provider 生成完全一致的交互其声明式配置集中在 typescript/src/cli/providers.ts当前支持以下 providerProvider关键环境变量额外选项OpenAIOPENAI_API_KEY、OPENAI_MODEL_NAME成本跟踪OPENAI_COST_PER_INPUT_TOKEN等Azure OpenAIAZURE_OPENAI_API_KEY、AZURE_MODEL_NAME--base-url、--api-version、--model-version、--deployment-nameAnthropicANTHROPIC_API_KEY、ANTHROPIC_MODEL_NAME成本跟踪AWS BedrockAWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY--regionOllamaOLLAMA_MODEL_NAME--base-url默认http://localhost:11434自动写入占位 keyollamaLocal modelLOCAL_MODEL_NAME、LOCAL_MODEL_BASE_URL--format默认jsonGrokGROK_API_KEY、GROK_MODEL_NAME成本跟踪MoonshotMOONSHOT_API_KEY、MOONSHOT_MODEL_NAME--base-urlDeepSeekDEEPSEEK_API_KEY、DEEPSEEK_MODEL_NAME成本跟踪GeminiGOOGLE_API_KEY、GEMINI_MODEL_NAME--project、--location、--service-account-fileVertex AIPortkeyPORTKEY_API_KEY、PORTKEY_MODEL_NAME--base-url、--providerOpenRouterOPENROUTER_API_KEY、OPENROUTER_MODEL_NAME--base-url、--temperature从 typescript/src/cli/commands/providers.ts 可以看到set-*命令执行时会做三件事把其他 provider 的USE_*开关置空并只启用当前 providerswitchModelProvider、写入模型名与密钥、支持-i/-o覆盖每 token 成本用于未知模型的自定义成本跟踪。-k/--prompt-api-key与-a/--prompt-credentials选项可以在终端以隐藏输入方式录入密钥不适合 CI 环境。其它通用设置可通过npx deepeval settings查看与修改支持--set KEYVALUE、--unset、--list及大小写不敏感的部分匹配过滤set-confident-region可切换 Confident AI 数据区域US / EU / AUset-debug/unset-debug负责日志级别、verbose 模式、gRPC 日志与 Trace 采样率等调试开关详见 typescript/src/cli/commands/settings.ts。Python 与 TypeScript SDK 的差异两个 SDK 共享几乎全部指标以及 Tracing、数据集、Prompt、CLI 和 Confident AI 集成日常工作流一致。TypeScript 版独有的能力包括Vitest 的toPass()匹配器对应 Python 的assert_test、npx deepeval inspectTrace 查看器以及 Python 没有的 Mastra 与 AI SDK 集成。目前仍仅限 Python 的能力Synthesizer——合成数据集生成。TypeScript 需要手写 goldens 或从 Confident AI 拉取Benchmarks——MMLU、HellaSwag、DROP、BIG-Bench Hard、TruthfulQA、HumanEval、GSM8K 等对应 deepeval/benchmarks红队Red teaming与提示词优化RAGAS 指标以及AgentLoopDetectionMetric、ToolPermissionMetricCrewAI、LlamaIndex、Pydantic AI、Google ADK、AWS AgentCore、Strands、Anthropic client 等集成。两个 SDK 位于同一仓库Python 包在 deepeval 目录TypeScript 包在 typescript 目录两者的 provider 环境变量命名相互对齐typescript/src/cli/providers.ts 注释明确说明其镜像了 Python 的deepeval/key_handler.py这意味着你可以放心地在同一套 CI 配置里维护两套语言的评估。实战建议从确定性指标起步先加ExactMatchMetric/PatternMatchMetric做零成本回归再叠加 LLM-as-a-judge 指标控制质量上限阈值按指标场景设置G-Eval 默认阈值 0.5严格场景可开启strictMode得分取整、阈值固定为 1RAG 指标常用 0.6~0.7用 Trace 定位问题组件evalsIterator() span 级指标可以把一次失败的 Agent 轨迹精确归因到检索、工具调用或某个 LLM 步骤在 CI 中运行npx deepeval test run输出与 Vitest 兼容的测试报告配合--savedotenv让密钥与配置落盘到.env.local避免在流水线里硬编码密钥保持两端一致如果团队同时维护 Python 与 TypeScript 服务优先复用同一套数据与评估标准利用两者共享的 Confident AI 数据集同步能力EvaluationDataset.pull/push见 typescript/src/dataset/dataset.ts维持双端口径统一。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
