学习笔记 · Obsidian
集成矩阵：模型、框架与编排
选择集成时看“谁拥有调用循环”：Provider SDK 用 wrapper，Agent 框架用原生 exporter/processor，已有 OTel 的系统走 OTel。一个模型调用只能有一个主 instrumentor。
一、选择算法
- 框架是否原生支持 LangSmith？有则优先原生。
- 框架是否原生发 OTel？用其 OTel instrumentation，再由 LangSmith exporter/processor 接收。
- 是否直接调用受支持 Provider SDK？用官方 wrapper。
- 是否 OpenAI-compatible？wrapper 能否识别 usage；否则 traceable + 完整 LLM 契约。
- 都不满足时，用 traceable 包业务边界，或最后使用 REST。
集成目录的 <code>get-started-integrations</code> 与 <code>integrations</code> 当前正文完全相同，是两个入口，不是两套能力。
二、Provider
| Provider | 推荐方式 | 重点 |
|---|---|---|
| OpenAI | Python <code>wrap_openai</code> / JS <code>wrapOpenAI</code> | 自动消息、tool、usage 和流式追踪 |
| Anthropic | SDK wrapper | JS Managed Agents 可追踪，但完整 subagent 追踪当前有限 |
| Bedrock | 在 Converse 调用外用 traceable | 手工补 model/provider/usage |
| DeepSeek | OpenAI-compatible client + traceable | 验证响应 usage 是否写入 run |
| Gemini | beta wrapper，Python/JS | API 可能变；实时语音是另一集成 |
| Mistral | traceable 包调用 | 手工语义契约 |
| OpenAI-compatible | wrapper 或 traceable | wrapper 更容易保留 token、run type |
手工 provider 页面有时简化为“traceable 即可捕获 token/cost”。权威标准仍是 03-LLM成本元数据多模态与检索：没有 usage metadata 就不能保证精确成本。
三、LiteLLM
三种模式：
- 应用函数外包 traceable。
- LiteLLM callback 直接发 LangSmith。
- LiteLLM Proxy 侧配置 callback。
同一调用不要同时启用应用 callback 和 proxy callback，否则会产生重复 trace/成本。异步 callback、batch 和短进程都要显式 flush。
四、结构化输出 Instructor
顺序很重要：
- 先用 LangSmith wrapper 包 OpenAI client。
- 再让 Instructor patch 已包装 client。
反过来可能使 wrapper 看不到底层请求，或让重试/解析 run 层级错误。结构化解析失败和 Provider 请求失败要分成可区分节点。
五、Agent 框架
| 框架 | 接入路径 | 生产注意 |
|---|---|---|
| AutoGen | OTel instrumentor | 敏感内容开关与 OTel exporter |
| CrewAI | OTel instrumentor | 避免与内部 tracing 双写 |
| Google ADK | <code>configure_google_adk</code> | text/tool/multi-agent；Live 另用专用 plugin |
| Mastra | 原生 LangSmith exporter | 需要 storage；关闭废弃 telemetry；仍出现旧 LANGCHAIN_PROJECT |
| Microsoft Agent Framework | 内置 OTel | <code>enable_sensitive_data</code> 决定内容捕获 |
| Pydantic AI | OTel | 文档推荐 langsmith 0.4.26 及以上 |
| Semantic Kernel | OTel | 检查 GenAI semantic attributes |
| Strands Agents | 专用 transform exporter | 保留 Agent/tool 层级 |
| OpenAI Agents SDK | LangSmith processor | Python 0.3.15+、JS 0.5.25+；serverless force flush |
OpenAI Agents JS processor 会显式追踪，即使 <code>LANGSMITH_TRACING</code> 未设置；停用必须用该 processor 自己的配置，不要只依赖环境变量。
六、Vercel AI SDK
当前分三代：
- AI SDK v7：<code>LangSmithTelemetry</code>，要求 AI SDK v7、langsmith 0.7.2+。
- AI SDK v5/v6：<code>wrapAISDK</code>；v6 要求 langsmith 0.3.63+。
- 更旧版本：legacy OTel 方案，已标记 deprecated。
新版能力：
- 全局 register 或单次调用 telemetry。
- generate/stream/tool 嵌套。
- 与 traceable 自动形成父子关系。
- 单次/global metadata、tags、name、client。
- 顶层与 child LLM 分开的 input/output processor。
- serverless 用 <code>awaitPendingTraceBatches</code>；Next.js 可在 <code>after</code> 中等待。
工具执行若要脱敏，要给 tool execute 单独包 traceable；只处理顶层 generateText 不会自动覆盖 tool。
Legacy OTel 方式存在 JS OTel v1/v2、Sentry 和 exporter 兼容注意事项，只用于无法升级的应用。
七、Temporal
Temporal 通过原生 OTel interceptor 把 client、workflow、activity 和内部 LLM 连接为分布式 trace：
- Go：langsmith-go tracer + Temporal OTel interceptor。
- Python：TracerProvider + OTLP HTTP exporter + TracingInterceptor。
- TypeScript：workflow exporter + activity inbound interceptor。
要求 client 和 worker 两端都安装 tracing，并在 worker 关停时 flush。高流量用 TraceIDRatioBased sampler。
文档矛盾/缺口：
- 区域/自托管提示仍写旧 <code>LANGCHAIN_BASE_URL</code>，其他页面使用 <code>LANGSMITH_ENDPOINT</code>。
- TS 示例 client 未展示 tracing interceptor，但 troubleshooting 又要求 client 与 worker 都配置；以 Temporal 当前 SDK 参考为准补齐。
Temporal replay 对 workflow 代码有确定性要求。不要在 workflow replay 中创建重复外部 side effect；真正模型调用更适合 activity。
八、n8n
当前指南针对 self-hosted n8n，使用旧 <code>LANGCHAIN_*</code> 环境变量。需要验证：
- n8n 版本和 LangChain node 是否支持。
- trace 数据是否包含 credentials/表达式结果。
- Cloud n8n 不应按 self-hosted 说明直接推断可用。
九、接入验收
- ○ 同一 Provider 请求只有一条 LLM run。
- ○ Agent、LLM、tool、retriever 层级正确。
- ○ streaming、错误、取消、重试都能结束 run。
- ○ model/provider/usage/cost 可验证。
- ○ serverless/worker 有 flush。
- ○ 敏感内容开关覆盖消息、tool、attachment 和异常。
- ○ 最低版本固定在依赖文件，不依赖文档示例中的浮动 latest。