使用 @mlflow/vercel 集成 MLflow Tracing 与 Vercel AI SDK：自动追踪 TypeScript/JavaScript LLM 调用

使用 mlflow/vercel 集成 MLflow Tracing 与 Vercel AI SDK自动追踪 TypeScript/JavaScript LLM 调用【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow本篇技术指南围绕开源仓库 MLflow 中的libs/typescript/integrations/vercel集成包展开讲解如何通过mlflow/vercel的MLflowSpanProcessor把 Vercel AI SDK 生成的 OpenTelemetry span 自动翻译为 MLflow Tracing 的 span 格式并导出到 MLflow Tracking Server。读完本文你将掌握安装配置、本地 Server 与 Databricks 两种导出目标、ai.*属性到mlflow.*属性的完整翻译映射以及该处理器底层实现与测试验证细节可直接在自己的 Next.js / Node.js 应用中落地。背景Vercel AI SDK 遥测与 MLflow Tracing 的对接思路Vercel AI SDK 是 TypeScript/JavaScript 生态中主流的 AI 应用开发框架其核心 APIgenerateText、streamText、generateObject、toolCall、embed等在开启experimental_telemetry后会基于 OpenTelemetry 发出带ai.*前缀属性的 span。MLflow Tracing 则是 MLflow 提供的生成式 AI 可观测性能力其服务端通过 OTEL Collector 接收 OTLP traces并在界面上以 LLM 调用链、Chat 对话渲染、Token 用量等方式呈现。mlflow/vercel包当前仓库中版本为0.4.0见 package.json承担了二者之间的翻译层职责它在客户端把 Vercel AI SDK 的 span 属性就地翻译成 MLflow 期望的mlflow.*属性再批量导出到 MLflow 的 OTLP 端点。这样 Vercel AI SDK 开发者无需改动业务代码即可在 MLflow 中复用完整的 Tracing UI。安装与依赖在项目中安装集成包npm install mlflow/vercel需要注意该包将opentelemetry/api与opentelemetry/sdk-trace-base声明为 peer dependencies版本要求均为1.0.0。根据你使用的包管理器npm/pnpm/yarn可能需要手动单独安装这两个依赖否则会出现缺少 peer 依赖的警告或运行时错误。从 package.json 可以看到该包的工程要求engines.node 18即需要 Node.js 18 及以上版本提供main: dist/index.js与types: dist/index.d.tsTypeScript 类型开箱即用导出内容集中在 src/index.ts对外公开MLflowSpanProcessor以及translateSpanForMlflow、translateSpansForMlflow两个底层翻译函数。实际使用时还需要显式安装 OTLP exporter 与 Node tracer provider它们不在该包的依赖范围内npm install opentelemetry/exporter-trace-otlp-proto opentelemetry/sdk-trace-node快速开始本地 MLflow Server Vercel AI SDK第一步启动 MLflow Tracking Server本地有 Python 环境时直接安装并启动pip install mlflow mlflow server --port 5000服务启动后OTLP traces 的接收端点默认为http://localhost:5000/api/2.0/otel/v1/traces。如果本地没有 Python 环境MLflow 也支持 Docker 部署或托管服务方式可参考仓库内 self-hosting 文档仓库中对应目录为 docs/docs/self-hosting。第二步注册 SpanProcessor 并开启 AI SDK 遥测在应用入口如 Next.js 的 instrumentation 文件、Node 服务启动文件中完成初始化import { MLflowSpanProcessor } from mlflow/vercel; import { OTLPTraceExporter } from opentelemetry/exporter-trace-otlp-proto; import { NodeTracerProvider } from opentelemetry/sdk-trace-node; import { generateText } from ai; import { openai } from ai-sdk/openai; const provider new NodeTracerProvider({ spanProcessors: [ new MLflowSpanProcessor( new OTLPTraceExporter({ url: http://localhost:5000/api/2.0/otel/v1/traces, headers: { x-mlflow-experiment-id: your-experiment-id, }, }), ), ], }); provider.register(); const result await generateText({ model: openai(gpt-5), prompt: Whats the weather like in Seattle?, experimental_telemetry: { isEnabled: true }, });这段代码中有三个关键点MLflowSpanProcessor内部组合了BatchSpanProcessor。查看 processor.ts 源码可见构造函数中创建了new BatchSpanProcessor(exporter)因此不需要再把这个处理器额外包进一个BatchSpanProcessor否则会造成重复包装。它实现了标准SpanProcessor接口onStart透传给内部批处理处理器onEnd中先执行translateSpanForMlflow(span)就地翻译属性再交给批量处理器缓存导出forceFlush与shutdown也一并代理。x-mlflow-experiment-id头用于把 traces 归属到指定 Experiment便于在 MLflow UI 中按实验维度检索替换为你的真实 Experiment ID 即可。experimental_telemetry: { isEnabled: true }必须显式开启否则 Vercel AI SDK 不会产出 span翻译与导出也就无从谈起。第三步在 MLflow UI 查看 traces调用完成后打开 MLflow UI默认http://localhost:5000在对应 Experiment 下即可看到 LLM span 链路。得益于mlflow.message.format vercel_ai属性Chat 类的 span 还会以 MLflow 的 Chat UI 对话形式渲染直观展示 prompt、响应与 Token 用量。对接 Databricks Unity Catalog如果你使用 Databricks 托管环境希望把 traces 写入 Unity Catalog 表只需调整 OTLP exporter 的 URL 与请求头new OTLPTraceExporter({ url: DATABRICKS_HOST/api/2.0/otel/v1/traces, headers: { Authorization: Bearer your-databricks-token, X-Databricks-UC-Table-Name: catalog.schema.table_prefix_otel_spans, }, })两个头的作用Authorization: Bearer tokenDatabricks 个人访问令牌认证X-Databricks-UC-Table-Name目标 Unity Catalog 表名格式为catalog.schema.table_prefix_otel_spans即表名需以_otel_spans结尾。特别提醒使用 Databricks 时不要再设置x-mlflow-experiment-id头二者是互斥的导出模式。Databricks 侧的相应能力在官方文档中有说明本仓库的 Python 侧 tracing 目录mlflow/tracing可作为参考实现。属性翻译映射从 ai.* 到 mlflow.*Vercel AI SDK 产出的 span 带有ai.*属性MLflowSpanProcessor在客户端把它们翻译成 MLflow 的格式。完整映射如下Vercel AI SDK 属性MLflow 属性说明ai.operationIdmlflow.spanTypeSpan 类型LLM / TOOL / EMBEDDINGai.prompt.*/ai.response.*mlflow.spanInputs/mlflow.spanOutputs结构化的请求 / 响应数据ai.model.idmlflow.llm.model模型名称ai.model.providermlflow.llm.provider模型供应商名称ai.usage.promptTokens/completionTokensmlflow.chat.tokenUsageToken 用量用于成本追踪chat spanmlflow.message.formatvercel_ai启用 Chat UI 渲染这张表的背后是 translate.ts 中的实际翻译逻辑以下几节从源码层面逐条展开。operationId → spanType 的映射表翻译的核心依据是ai.operationId属性源码中维护了一张完整映射见 translate.tsai.operationIdmlflow.spanTypeai.generateText、ai.generateText.doGenerateLLMai.streamText、ai.streamText.doStreamLLMai.generateObject、ai.generateObject.doGenerateLLMai.streamObject、ai.streamObject.doStreamLLMai.toolCallTOOLai.embed、ai.embed.doEmbed、ai.embedMany、ai.embedMany.doEmbedEMBEDDING值得注意的是ai.embedMany.doEmbed在 Python 服务端的 vercel_ai.py 映射中并未列出而客户端 TS 版本将其补全为EMBEDDING属于客户端更完整的实现。注释还指明该映射与mlflow/tracing/otel/translation/vercel_ai.py中服务端VercelAITranslator的映射互为镜像客户端内联了常量以避免依赖mlflow/core。结构化输入输出的提取规则翻译函数会按操作类型分路径提取mlflow.spanInputs与mlflow.spanOutputsChat do spanai.generateText.doGenerate、ai.streamText.doStream、ai.generateObject.doGenerate、ai.streamObject.doStream把ai.prompt.*前缀属性整体收集成一个对象去掉前缀、逐值做 JSON 解析作为 inputs把ai.response.*前缀属性收集为 outputs。例如ai.prompt.messages、ai.prompt.temperature会被组装成{ messages: [...], temperature: 0.7 }。非 chat span按优先级取第一个命中的裸属性——inputs 依次尝试ai.prompt、ai.toolCall.args、ai.value、ai.valuesoutputs 依次尝试ai.response.text、ai.toolCall.result、ai.response.object、ai.embedding、ai.embeddings取到即返回、不做包装。safeParse实现了最多两层 JSON 解码OTLP 传输可能导致双重编码并对数组逐元素解码解析失败时原样保留字符串因此像ai.prompt.tools中逐个字符串化的工具定义也能被还原为对象数组测试用例见 translate.test.ts。模型与供应商多来源回退mlflow.llm.model的取值优先级为ai.model.id→gen_ai.request.model→gen_ai.response.modelmlflow.llm.provider的优先级为ai.model.provider→gen_ai.system。这保证了即使 AI SDK 某些版本未产出ai.model.id也能从 SDK 自带的gen_ai.*属性AI SDK 已按 GenAI 语义约定发出的属性兜底取到模型名。Token 用量与 Chat UI 格式mlflow.chat.tokenUsage会被组装为 JSON{input_tokens: N, output_tokens: N, total_tokens: N}。输入侧优先级为gen_ai.usage.input_tokens→ai.usage.inputTokens→ai.usage.promptTokens输出侧为gen_ai.usage.output_tokens→ai.usage.outputTokens→ai.usage.completionTokens两侧独立解析、互不干扰缺失的一侧以0填充两侧都缺失则不生成该属性。测试同时覆盖了字符串编码数字150、数字0等边界情况translate.test.ts。此外只有 4 类 chat do span 会被标记mlflow.message.format vercel_ai其他 span顶层ai.generateText、ai.toolCall、ai.embed*等不会设置该属性——这与服务端VercelAITranslator.get_input_value中仅对 chat span 写入MESSAGE_FORMAT的行为保持一致见 vercel_ai.py。翻译器的容错设计源码中体现了几条值得借鉴的健壮性设计绝不丢 span翻译失败时只输出console.debug日志并原样放行该 span翻译循环继续处理后续 span。测试用属性 getter 抛异常的 span 验证了这一点translate.test.ts。不覆盖已有属性如果 span 上已经存在mlflow.spanType、mlflow.spanInputs等属性例如用户自定义 instrumentation 已设置翻译器一律跳过避免破坏既有数据对应测试见 translate.test.ts。非 AI span 完全不动没有ai.operationId的 span如普通 HTTP span不会被翻译原属性原样保留。工具调用 span 重命名当ai.operationId ai.toolCall且存在ai.toolCall.name时会把 span 名称改为工具名如get_weather使调用链在 UI 中更可读见 translate.ts 与对应测试 translate.test.ts。在MLflowSpanProcessor.onEnd中翻译发生在批量导出之前因此导出到 MLflow 的 span 一定是已翻译完成的processor.test.ts 验证了翻译即时生效且导出内容包含mlflow.spanType等属性。测试与工程化该集成包自带完整的 Jest 测试套件tests/translate.test.ts覆盖 span 类型映射、输入输出提取、模型/供应商回退、message format、token usage、工具重命名、双重编码 JSON、批处理、未知 operationId、数值与字符串边界等约 40 个场景tests/processor.test.ts验证onEnd时先翻译后导出、非 AI span 原样透传、forceFlush/shutdown正常清理、部分 span 翻译失败不丢数据。工程脚本定义在 package.json支持npm testJest、npm run buildtsc 编译、npm run lintESLint零警告阈值与npm run formatPrettier。发布产物仅包含dist/目录license 为 Apache-2.0见仓库根目录 LICENSE.txt。适用范围与限制说明本集成面向TypeScript/JavaScript 侧的 Vercel AI SDKNode.js 18若你的 AI 应用是 Python 侧如 LangChain、LlamaIndex可改用 MLflow 对应的 Python tracing 集成服务端翻译器可参考 mlflow/tracing/otel/translation/vercel_ai.py。翻译只处理带ai.operationId的 AI SDK span服务端还会基于 span 自带的gen_ai.*属性如gen_ai.request.model、gen_ai.usage.input_tokens在读取路径上做补充处理客户端翻译与之互补而不冲突。experimental_telemetry.isEnabled需要逐次调用显式开启如需全局开启可在 AI SDK 侧统一配置。OTLP exporter 的 URL 与请求头必须与你的 MLflow Server 或 Databricks 环境匹配Experiment 归属依赖x-mlflow-experiment-id仅本地模式Databricks 模式则依赖X-Databricks-UC-Table-Name。参考资源仓库内集成包源码入口libs/typescript/integrations/vercel/src/index.tsSpanProcessor 实现libs/typescript/integrations/vercel/src/processor.ts属性翻译实现libs/typescript/integrations/vercel/src/translate.ts服务端对应翻译器mlflow/tracing/otel/translation/vercel_ai.pyTypescript SDK 根文档libs/typescript/README.mdMLflow Tracing 相关实现mlflow/tracing【免费下载链接】mlflowThe open source AI engineering platform for agents, LLMs, and ML models. MLflow enables teams of all sizes to debug, evaluate, monitor, and optimize production-quality AI applications while controlling costs and managing access to models and data.项目地址: https://gitcode.com/GitHub_Trending/ml/mlflow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考