DeepEval TypeScript 集成模块移植全景集成矩阵、横切缺口与框架文档就绪度【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval本指南基于 typescript/src/integrations/README.md 展开系统梳理 DeepEval TypeScript SDK 的框架集成层LangChain、LangGraph、OpenAI Agents、Mastra、Vercel AI SDK、OpenInference与 Python 侧的移植对齐现状哪些能力已就绪、哪些存在横切缺口、每个框架页能诚实写到什么程度以及按性价比排序的补齐路线。读完本文你将能对照当前仓库源码快速判断任意一个框架集成的可用边界并理解各缺口背后的底层机制AsyncLocalStorage 暂存上下文、OTel 双路导出、capture sink 竞争等。模块总览六个模块覆盖七个框架行DeepEval TypeScript SDK 的集成模块位于typescript/src/integrations/其定位与 Python 侧 deepeval/integrations/ 一一对应。README 开篇即点明本模块的性质它是文档素材同时也是补齐 Python 对齐度parity的待办清单backlog。六个模块、覆盖七个框架行其中四个是真正的 Python 移植两个是 TypeScript 独有LangChainLangGraph 复用同一 handler— 移植自 PythonOpenAI Agents— 移植自 PythonOpenInference— 移植自 Python顶层src/openai/对应 Python 的deepeval.openai— 移植Mastra— TS 独有Python 无对应模块Vercel AI SDKsrc/integrations/ai-sdk/— TS 独有Python 无对应模块Python 侧有七个模块至今没有 TS 等价物Anthropic、LlamaIndex、CrewAI、AgentCore、Strands、Google ADK、Pydantic AI另外 Python 还单独提供hugging_face模块TS 也没有对应实现。其中四个AgentCore、Strands、Google ADK、Pydantic AI在 Python 侧都属于 OTel 模式共享同一个SpanInterceptorContextAwareSpanProcessor模式——这意味着补齐评估会话eval-session概念即下文缺口 2是移植这四个模块的前置条件。从源码结构看Python 侧其余集成均集中在 deepeval/integrations/ 下anthropic/、llama_index/、crewai/、agentcore/、strands/、google_adk/、pydantic_ai/目录齐全与 README 的清单吻合。另外Python 第四大能力列deepeval test run现在有了 TS 等价物——一个 Vitest 集成提供expect(...).toPass()匹配器但它尚年轻、未逐集成验证因此 README 没有把它填进下面的矩阵避免用猜测填充其自身的 parity backlog 记录在 typescript/src/evaluate/test-run/README.md。集成矩阵三种能力列的判定标准矩阵的三个能力列语义与 Python README 一致减去deepeval test run列Bare— 不包裹任何observe(...)直接调用框架能否在 Confident AI 产生 traceobserve()nesting— 被observe(...)包裹时集成的 span 能否挂入外层 deepeval trace而不是另起一条独立 traceevalsIterator— 在dataset.evalsIterator(...)期间span 能否到达traceManager从而让 trace/span 级指标参与评分。集成模式入口Bareobserve()nestingevalsIterator源码位置OpenAI原生客户端包装instrumentOpenAI(client)YesYesYestypescript/src/openai/LangChain回调处理器new DeepEvalCallbackHandler({})YesNoYestypescript/src/integrations/langchain/LangGraph复用 LangChain 的 handlernew DeepEvalCallbackHandler({})YesNoYestypescript/src/integrations/langchain/OpenAI AgentsTrace processornew DeepEvalTracingProcessor()YesYesYestypescript/src/integrations/openai-agents/MastraExporternew DeepEvalExporter(config)YesNoYes存在 sink 冲突typescript/src/integrations/mastra/Vercel AI SDKOpenTelemetryconfigureAiSdkTracing(options)Yes仅isTestMode仅isTestModetypescript/src/integrations/ai-sdk/OpenInferenceOpenTelemetryinstrumentOpenInference(options)Yes仅isTestMode仅isTestModetypescript/src/integrations/openinference/一句话结论没有任何一个集成达到 Python 全量对齐。没有任何集成能把metric挂到框架自建的 span 上——暂存上下文staging contexts存在且携带其余一切字段但metrics在四处被注释两个 OTel 模式集成AI SDK、OpenInference只有在手动开启标志后span 才会进入本地 trace 树。横切缺口按阻塞程度排序的七个问题这些缺口横跨所有集成修复任何一个通常能同时解锁多个文档页面。README 按阻塞程度排序我们从最关键的开始。缺口 1组件级指标——metrics从暂存上下文中被注释Python 的 deepeval/tracing/context.py 导出next_agent_span、next_llm_span、next_tool_span、next_retriever_span。每个都是一个上下文管理器把指标以及update_current_span接受的所有字段暂存到集成接下来打开的下一个对应类型 span 上with next_llm_span(metrics[AnswerRelevancyMetric()]): agent.invoke(...) # 回调打开的第一个 LLM span 会拾取该指标TS 中没有这些名字的函数但暂存机制本身已经存在——这个缺口比没有等价物要窄也是重写任何框架页之前最需要知道的一件事。typescript/src/tracing/trace-context.ts 定义了LlmSpanContext和AgentSpanContext背后是两个AsyncLocalStorage存储通过setTracingContext(opts, fn)从deepeval/tracing导出暂存由三个集成消费draintypescript/src/openai/patch.ts、typescript/src/integrations/openai-agents/callback.ts、typescript/src/integrations/ai-sdk/processor.ts。它是**环境作用域ambient-scope**而非 Python 的每种 span 一次性消费语义因此更接近 Python 自己的LlmSpanContext而不是next_*_span。README 依据消费点逐一核对给出各字段当前携带情况字段OpenAIOpenAI AgentsAI SDKexpectedOutput、expectedTools、context、retrievalContextYesNoNopromptYesYesLLM span—metricCollectionYesYesagent / LLM / tool—metrics被注释被注释被注释metrics就是全部缺口。它不是在设计中缺席而是在四个位置被注释掉——两个上下文类型上的字段、setTracingContext里的 trace 赋值、OpenAI patch 中的消费点// src/tracing/trace-context.ts export type LlmSpanContext { prompt?: Prompt; // metrics?: BaseMetric[]; // src/openai/patch.ts return await observe({ type: llm, // metrics: llmContext?.metrics, metricCollection: llmContext?.metricCollection,因此现状是组件级metric collectionsConfident AI 在线评估路径对 OpenAI 和 OpenAI Agents 已经可用而组件级metrics所有文档页使用的本地评估路径不可用。把四个位置解开并接线是本模块杠杆率最高的改动。当前源码进展提示从仓库现状看trace-context.ts 中两个上下文类型的metrics字段已不再注释metrics?: BaseMetric[]就写在类型定义里setTracingContext也保留了if (opts.metrics) currentTrace.metrics opts.metrics的赋值且文件底部通过_setAmbientPayloadReader把ctx.metrics/ctx.toolsMetrics接入了 pending-context 读取链。README 中的代码片段描述的是撰写时的快照可以推断该缺口在源码层面已部分收敛但各集成消费点是否全部接通metrics仍需按上文四类消费点逐一验证后才能在文档中承诺。LangChain 有一条独立的、无关的逃生通道hatch。它完全不读 ALS 上下文handleLLMStart改为从 LangChain 每次调用的metadata中取metrics、metricCollection和prompt直接赋给 LLM span// src/integrations/langchain/callback-handler.ts const metrics metadata?.[metrics]; llmSpan.metrics metrics;因此config: { metadata: { metrics: [...] } }今天就能到达 LangChain 的 LLM span路上没有任何注释挡道。但handleToolStart和handleRetrieverStart接收同样的metadata参数却直接忽略且没有 agent span 可挂——所以这条路只覆盖一个集成的一种 span 类型。它尚未被端到端测试文档化之前需要先验证对应 callback-handler.ts。要达到 Python 对齐需要解开上面四个位置的metrics注释在 LangChain 和 Mastra 的 span 打开路径上加消费点两者都不读 ALS 上下文并决定保留环境作用域语义还是引入 Python 的一次性语义仅第一个匹配 span 消费暂存配置。缺口 2没有评估会话概念——OTel 集成需要手动开关Python 的trace_manager.is_evaluating在evals_iterator打开EvalSession时置为 trueContextAwareSpanProcessor读取它把结束的 OTel span 路由到 REST 路径经由trace_manager而不是 OTLP。这正是 OTel 模式集成在迭代器内自动工作的原因。TS 没有EvalSession也没有isEvaluating。evalsIterator改为安装 capture sinktraceManager.setTraceCaptureSink而该 sink 只在traceManager.endTrace时触发——所以只有通过traceManager构建 span 的集成才对迭代器可见。对 AI SDK 和 OpenInference 而言这条路被一个手动选项门控// src/integrations/ai-sdk/processor.tsopeninference/processor.ts 同构 if (this.options.isTestMode) { traceManager.addSpan(deepEvalSpan); traceManager.addSpanToTrace(deepEvalSpan); }这带来两个后果用户必须记得传isTestMode: true才能评估而且即便如此两个 processor 都保持注册span 既进traceManager又被批量导出到 OTLP——Python 刻意只路由到一个委托方以避免双重导出。需要的修复在traceManager上加一个由evalsIterator设置的 eval-session 标志让isTestMode默认跟随它并做互斥路由。缺口 3LangChain 与 Mastra 的observe()嵌套是坏的文档承诺 LangChain span 会嵌套在外部 observed span 之下但实际做不到。handler 总是把traceUuidOverride传进enterCurrentContext而这个参数的存在意义就是绕过 async-local storage// src/integrations/langchain/utils.ts if (traceUuidOverride) { // 调用方驱动的放置基于 run_id/parent_run_id。不要查询 // AsyncLocalStorage它在 LangGraph server 下不可靠。 traceUuid traceUuidOverride; parentUuid parentUuidOverride; }override 来自RunHierarchyTracker.ensureTrace()它从不查询getCurrentTrace()——在没有父 run 时无条件调用traceManager.startNewTrace()。所以observe()内的 LangChain run 会落进一条没有父级的独立 trace。这个 ALS 绕过对当初要解决的 LangGraph-server 场景是正确的。缺的是回退逻辑ensureTrace()在存在环境 trace 时应采纳它根 chain span 应挂到环境 span 之下。DeepEvalExporterMastra有同样的问题但原因更简单——它从不调用getCurrentTrace()只调traceManager.startNewTrace()所以每次导出的 Mastra run 都是独立 trace。DeepEvalTracingProcessorOpenAI Agents是这两个模块应该参照的标杆它先查getCurrentTrace()只有不存在时才新建 trace见 openai-agents/callback.ts。缺口 4trace 级测试用例取自trace.input而非 goldenevaluateTrace直接基于 trace 构建 trace scope 的测试用例// src/evaluate/trace-eval.ts function scopeToTestCase(scope: BaseSpan | Trace): LLMTestCase { return new LLMTestCase({ input: asString(scope.input), actualOutput: asString(scope.output),而 Python 的迭代器路径使用golden.input并回退到golden.expected_output。由于集成把trace.input设成框架的原始负载TS 的 trace 级指标评的是JSON.stringify({messages: [...]})而不是用户的问题且 golden 的expectedOutput被丢弃。这是静默错误——分数看起来合理实际是错的。它影响所有evalsIterator({ metrics })不只是集成。需要把 golden 传进evaluateTrace。当前源码进展提示从当前 trace-eval.ts 看文件已新增goldenToTraceTestCase(golden, trace)优先取golden.input、trace.expectedOutput ?? golden.expectedOutput并由turnTestCase(trace, golden)在有 golden 时优先走该路径。可以推断 README 记录的该缺口在源码上已得到缓解但evaluateTrace内部各调用点是否全部切换到位仍需结合测试用例确认。缺口 5测试运行器集成存在但没有任何集成对它做过验证deepeval test run现在驱动 Vitestexpect(golden).toPass()对测试刚产出的 trace 打分——集成用户在 CI 里会用到的那套模式已经可用。但尚未检查每个集成的 span 是否真的落进那条 trace因为按测试捕获使用的正是缺口 2 和缺口 6 覆盖的那个 sink。运行器自身的 backlog 在 typescript/src/evaluate/test-run/README.md。缺口 6evalsIterator、Mastra 与测试运行器争夺同一个 capture sinksetTraceCaptureSink写入一个全局单槽而现在有三个消费者evalsIterator进入时设置、退出时清为undefinedDeepEvalExporter从config.traceCaptureSink设置Vitest 的beforeEach每个测试设置、afterEach清除。谁最后执行谁赢任一方的清理都会悄悄丢掉其他人的 sink。需要的是订阅者列表而不是单槽。当前源码进展提示从当前 mastra/exporter.ts 看Mastra 侧已改为traceManager.addTraceCaptureSink(config.traceCaptureSink)并持有返回的退订函数unsubscribeSinkshutdown()时再退订——这暗示traceManager的 sink 已具备订阅语义。README 的单槽描述属于撰写时快照订阅化改造是否已全面落地evalsIterator、Vitest 侧是否同步切换需在typescript/src/tracing/下核对。缺口 7OpenInference 从发布包里不可达typescript/src/integrations/openinference/ 本身是完整的导出instrumentOpenInference、createOpenInferenceProcessors、OpenInferenceSpanProcessor但 typescript/package.json 的exports和typesVersions中都没有./integrations/openinference键。exports映射是穷尽式的所以该 specifier 在运行时抛ERR_PACKAGE_PATH_NOT_EXPORTED在nodenext下抛 TS2307。在键被加进去之前它无法被文档化。另外./integrations是导出并映射的但src/integrations/index.ts是空文件该 specifier 解析到一个零导出的模块。要么把四个公开入口做成 barrel 文件要么删掉这个键。LangChain / LangGraph 特有问题除了横切项LangChain 集成与 Python 的分歧使/integrations/frameworks/langchain页面的部分内容对 TS 不可写没有 agent span嵌套 chain 也没有 span。handleChainStart仅在parentUuid undefined时创建 span类型为SpanType.CUSTOM。Python 为每个chain 都建 span对 LangGraph 这种有嵌套 chain 的场景很重要文档的 trace 图也展示了Agent:根节点带嵌套子节点。TS 产出的是通用 custom 根节点下的扁平树。注意 callback-handler.ts 当前实现已把根 span 类型写作SpanType.AGENTfuncName: runName ?? Langchain Chain RunREADME 撰写时的CUSTOM类型描述或已更新——但只有根 chain 有 span、嵌套节点无 span的扁平结构依旧成立。工具装饰器不存在。patch-tool.ts 整体被注释index.ts只导出DeepEvalCallbackHandler而文档在两处宣传 deepeval 工具装饰器。构造器 kwargs 已对齐。name、tags、metadata、threadId、userId、testCaseId、turnId、metrics、metricCollection都被接受并应用——只有大小写与 Python 不同thread_id→threadId。文档的 API 参考表是 Python 拼写需要加Switch但这是文档修复不是 SDK 修复。metrics/metricCollection是 trace 级的与 Python 一致两者都赋在根 chain 的 trace 上并做了守卫以免覆盖外层updateCurrentTrace(...)。评估脚本应优先用evalsIterator({ metrics })构造器 kwarg 是给线上流量的在线评估用的。各框架文档就绪度每个页面今天能诚实写什么文档约定Switch、Only、languagesfrontmatter在 .cursor/rules/docs-languages.mdc迁移状态在 docs/LANGUAGES.md页面位于docs/content/integrations/frameworks/。横切缺口适用于所有页面本节是每个页面作者实际会遇到的问题以及现有 Python 页的哪些章节能保留。建议从 OpenAI 和 OpenAI Agents 开始——只有这两个是所有能力列全 Yes且 OpenAI Agents 是 LangChain、Mastra 尚缺的环境 trace 采纳参考实现。OpenAI —frameworks/openai入口instrumentOpenAI(client)来自deepeval/openai。它是原地 patch 客户端而不是 re-export 一个子类——所以 Python 页的drop-in replacement改你的 import框架不成立TS 案例需要自己的叙述。从当前 openai/index.ts 看instrumentOpenAI用模块级let registered false守卫并提前返回只有第一个传入的 client 会被 patch第二个 client 静默地未被插桩——README 标注的 footgun 依然存在。LlmSpanContext一节比其他任何地方都更贴切TS 有同样的概念用setTracingContext({ llmSpanContext: {...} }, fn)暂存而 OpenAI patch 是唯一消费所有字段的消费点见缺口 1。expectedOutput、expectedTools、context、retrievalContext、prompt、metricCollection都落到 LLM span 上只有metrics曾是被注释项当前源码的 pending-context 链已接上metrics见缺口 1 的进展提示。pytest /deepeval test run章节变成 Vitest expect(golden).toPass()。第二个 footgunupdateAllAttributes(...)只在if (llmContext …)内执行而getLlmContext()在未暂存setTracingContext时返回undefined。在 bare 路径上LLM span 可能拿不到 input、output 或toolsCalled——else分支只是打印getLlmContext() returned undefined见 patch.ts。矩阵中 OpenAI 的 Bare Yes 是基于trace 被创建判定的bare 时 span 是否被填充尚未测试。OpenAI Agents —frameworks/openai-agents入口new DeepEvalTracingProcessor()经addTraceProcessor接入。嵌套与evalsIterator都可用且这是采纳环境 trace 的参考实现——先查getCurrentTrace()再决定是否新建callback.ts这正是 LangChain 和 Mastra 没做的事。Python 的Agent/function_tool垫片——agent_metrics、llm_metrics、metrics、confident_prompt——没有 TS 等价物openai-agents/ 只导出 processor所以你用 SDK 自己的Agent和tool。暂存上下文部分弥补了差异onSpanStart按 span 类型读metricCollectionagent span 读 agent 上下文、LLM span 读 LLM 上下文、tool span 读toolsMetricCollectiononSpanEnd把llmSpanContext.prompt连同其 alias、hash、version、label 拷到 LLM span 上callback.ts。所以 prompt 绑定一节有真实的 TS 对应物组件章节可以按metric collections写——但不能按metrics写。LangChain —frameworks/langchain四个移植中最缺的一个按代价排序trace 级指标评的是错误文本缺口 4。handleChainStart把trace.input设为 LangChain 原始负载scopeToTestCase再 stringify所以evalsIterator({ metrics })评的是{messages:[{role:user,content:…}]}而不是问题本身golden 的expectedOutput被丢弃。这直接命中页面第一个示例。requiresTrace的指标读嵌套 span dict暴露较少。当前源码已引入 golden 优先的turnTestCase见缺口 4 进展提示。没有 agent span、没有嵌套 chain span。只有根 chain 有 spanREADME 记为SpanType.CUSTOM当前源码为SpanType.AGENT未设runName时名为Langchain Chain Run。Python 页的Agent: math_agenttrace 图对 TS 是错的。LLM、tool、retriever span 存在且通过RunHierarchyTracker正确嵌套。组件指标只有 LLM span 有走 LangChain 的config.metadata——见缺口 1 的逃生通道。tool、retriever、agent 小节保持不可写。observe()嵌套是坏的缺口 3把 LangChain run 包进observe的模式是假的。没有工具装饰器——patch-tool.ts 整体注释但页面在两处宣传它。不是缺口的部分构造器 kwargs 完全对齐只有thread_id→threadId大小写差异API 参考表只需加Switch。LangGraph —frameworks/langgraph复用DeepEvalCallbackHandler因此继承上述所有 LangChain 项。RunHierarchyTracker的存在就是为了 LangGraph-server 场景——那里 ALS 在回调间丢失——这就是缺口 3 中 ALS 绕过不能简单删除的原因它需要环境 trace 回退而不是移除。这个页面从未双语过所以是全新撰写而非重写。Mastra — 暂无页面TS 独有new DeepEvalExporter(config)配置项详见 mastra/exporter.tsapiKey、environment、name、tags、metadata、threadId、userId、testCaseId、turnId、metricCollection、traceMetricCollection、llmMetricCollection、agentMetricCollection、toolMetricCollectionMap、prompt、debug、traceCaptureSink。需要从零写页面。两个前置阻塞observe()嵌套坏掉exporter 从不调用getCurrentTrace()见 exporter.ts 的ensureTrace无条件startNewTraceconfig.traceCaptureSink与evalsIterator、Vitest runner 在全局单槽上冲突缺口 6当前源码已改为addTraceCaptureSink订阅式见进展提示。Vercel AI SDKtracing— 暂无页面TS 独有configureAiSdkTracing(options)选项见 ai-sdk/index.tsapiKey、otelEndpoint、name、isTestMode、debug、environment、traceMetricCollectioncreateDeepEvalProcessors在无 key 时只返回本地 processor 并关闭 OTLP有 key 时才装配 OTLP 导出器。它区别于integrations/models/ai-sdk——后者覆盖AISDKModel作为 judge 模型且已是双语页面——选 URL 时不要让人误以为两者是同一个集成。进入迭代器需要isTestMode: true且此时会双重导出缺口 2。OpenInference — 暂无页面且不可发布被缺失的子路径导出直接阻塞缺口 7。此外与 AI SDK 一样有isTestMode的注意事项。其OpenInferenceSpanProcessor负责把 OpenInference 语义约定属性openinference.span.kind、llm.input_messages.{i}.message.content、tool.name等映射为内部 span实现见 openinference/processor.ts。建议的工作顺序按性价比排序的补齐路线README 给出了明确的执行顺序每项都标注了成本与收益解开暂存上下文上的metrics缺口 1——四处注释行立即解锁 OpenAI 和 OpenAI Agents 的组件级评估。在文档收益面前这是本模块最便宜的一项。基于 golden 的 trace 测试用例缺口 4——小改动止住静默错误评分。评估会话路由缺口 2——让 AI SDK / OpenInference 无需手动标志即可在迭代器内工作并消灭双重导出。修复 LangChain 和 Mastra 的observe()嵌套缺口 3——让已有文档章节变为真实照抄 OpenAI Agents 的getCurrentTrace()检查。LangChain trace 形状——agent span 嵌套 chain span让文档中的 trace 树符合现实。工具装饰器——完成或删除patch-tool.ts并让文档二选一对齐。capture sink 订阅者列表缺口 6——小的正确性修复当前源码的 Mastra 侧已呈现订阅式接口可先核对traceManager整体是否已切换。在 LangChain 和 Mastra 消费暂存上下文缺口 1 后半——两者都不读getLlmContext()/getAgentContext()会错过第 1 步解锁的能力。导出 OpenInference缺口 7——只是 typescript/package.json 里加一个键不是代码改动。结语把 README 当作一张活的差距地图这份 README 的价值在于它把TS 集成层离 Python 全量对齐还差什么拆解成了可执行、可验证、可按性价比排序的清单而不是一句含糊的还没移植完。对文档作者它是每个框架页能诚实写到什么程度的边界依据对 SDK 贡献者它是按依赖关系排好的工作队列对使用者它明确划出了今天就能用的能力OpenAI、OpenAI Agents 的完整三列以及 LangChain 经由metadata的组件指标逃生通道与必须等修复的禁区LangChain 的observe()嵌套、AI SDK / OpenInference 的isTestMode门控、OpenInference 的不可导入。同时请记住这是一份快照型 backlog。正如上文多处当前源码进展提示所示仓库源码已经在若干缺口上metrics字段、golden 优先的测试用例构造、订阅式 capture sink出现演进迹象。在使用本文结论前最稳妥的做法是回到对应源码文件现场核对——这正是这份 README 自始至终倡导的工作方式一切以源码为准文档永远跟在其后。【免费下载链接】deepevalThe LLM Evaluation Framework项目地址: https://gitcode.com/GitHub_Trending/de/deepeval创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考