在 LLM 应用开发中，LangChain 是串联各类组件的核心框架，而 Langfuse 则是保障应用稳定性的“监控利器”。但当 LangChain 从 0.3.x 升级到 1.0 正式版后，不少开发者遇到了连锁反应——Langfuse 监控面板中 Session ID 和 User ID 突然消失，原本清晰的链路追踪变得“残缺不全”。

今天这篇文章，就带大家复盘这次版本升级引发的兼容性问题，从问题现象、根源分析到最终适配方案，一步步拆解实战中的解决方案，帮你少走弯路！

背景：为什么要升级？

作为 LLM 应用开发者，我们的技术栈选择始终围绕“效率”和“稳定性”：

•LangChain：从 0.3.79 升级到 1.0.1，是为了拥抱正式版的全新架构设计、更稳定的 API 支持以及丰富的新特性（如更灵活的工作流编排、原生异步支持优化）。•Langfuse：同步从 2.60.7 升级到 3.8.1，以适配 LangChain 1.0 的新特性，同时获取更全面的链路追踪和指标分析能力。

原本以为是一次常规的版本迭代，没想到升级后直接触发了监控告警——Langfuse 的 Traces 面板中，所有请求的 Session 和 User 信息全部空白，这对后续的用户行为分析、成本归因和问题排查造成了极大阻碍。

一、问题现象：升级后监控“失明”

1. 升级前的正常配置

在 LangChain 0.3.79 版本中，我们通过直接给 Langfuse CallbackHandler 赋值的方式配置 Session ID 和 User ID，代码逻辑如下：

def __init__(self, response_id: str, langfuse_handler: CallbackHandler, session_id: str):
# 初始化 Langfuse 回调处理器（用于链路追踪）
self.langfuse_handler = langfuse_handler
async def run(self, params: ResponseCreateParams) -> AsyncGenerator[ResponseStreamEvent, None]:
# 直接给 handler 赋值用户ID和会话ID
self.langfuse_handler.user_id = params.user
self.langfuse_handler.session_id = self.session_id
graph = self.response_engine.build_graph()
# 执行工作流并传入回调
async for stream_mode, data in graph.astream(
input={
"query": params.input,
"message_id": self.response_id,
"session_id": self.session_id,
"user_id": params.user,
},
config={
"callbacks": [self.langfuse_handler],
"metadata": {
"langfuse_session_id": self.session_id,
"langfuse_user_id": params.user,
}
},
):
# 流式输出逻辑...

此时 Langfuse 面板能正常显示每一条请求的 Session 和 User 信息，链路追踪完整。

2. 升级后的异常表现

升级 LangChain 1.0.1 和 Langfuse 3.8.1 后，上述代码未做修改，但 Langfuse Traces 面板出现明显异常：

•所有 Trace 记录的 Session ID 和 User ID 均为空白，无法区分不同用户或会话的请求；•其他链路信息（如步骤耗时、Token 消耗）正常显示，排除整体集成失败的可能。

Langfuse 监控异常截图

（升级后 Session 和 User 信息丢失，监控面板“失明”）

二、根源分析：版本升级带来的配置变更

1. 排查方向

既然代码逻辑未变，问题大概率出在版本升级后的兼容性变更上。我们从两个维度展开排查：

•LangChain 1.0 的 API 变更：是否调整了回调处理器（CallbackHandler）的初始化或参数传递方式？•Langfuse SDK 的适配逻辑：是否修改了 Session ID/User ID 的解析规则？

2. 关键发现：Langfuse 回调处理器的解析逻辑变更

通过查看 Langfuse 3.8.1 版本中 langfuse/langchain/CallbackHandler.py 的源码，发现其解析 Session ID 和 User ID 的逻辑发生了变化：

def _parse_langfuse_trace_attributes_from_metadata(
self,
metadata: Optional[Dict[str, Any]],
) -> Dict[str, Any]:
attributes: Dict[str, Any] = {}
if metadata is None:
return attributes
# 从 metadata 中读取 langfuse_session_id
if "langfuse_session_id" in metadata and isinstance(
metadata["langfuse_session_id"], str
):
attributes["session_id"] = metadata["langfuse_session_id"]
# 从 metadata 中读取 langfuse_user_id
if "langfuse_user_id" in metadata and isinstance(
metadata["langfuse_user_id"], str
):
attributes["user_id"] = metadata["langfuse_user_id"]
# 支持从 metadata 中读取 tags
if "langfuse_tags" in metadata and isinstance(metadata["langfuse_tags"], list):
attributes["tags"] = [str(tag) for tag in metadata["langfuse_tags"]]
return attributes

核心结论：Langfuse 3.x 版本不再支持直接给 CallbackHandler 实例赋值 user_id/session_id，而是要求通过 LangChain 的 config.metadata 传递指定键名的参数。

而 LangChain 1.0 恰好对工作流执行的 config 参数格式做了规范，之前直接赋值 handler 的方式在新版本中被废弃，导致参数无法被正确解析，最终表现为监控面板中信息丢失。

三、适配方案：基于 Metadata 的规范配置

根据 Langfuse 最新的解析逻辑，我们需要调整参数传递方式，将 Session ID 和 User ID 通过 config.metadata 传入，具体步骤如下：

1. 核心适配代码

修改 graph.astream 的 config 配置，确保 metadata 中包含 langfuse_session_id 和 langfuse_user_id 键：

async for namespace, stream_mode, data in graph.astream(
input={
"query": params.input,
# 优化 message_id 赋值逻辑，兼容参数传递场景
"message_id": params.metadata["message_id"] if "message_id" in params.metadata and params.metadata["message_id"] != "" else self.response_id,
"session_id": self.session_id,
"user_id": params.user,
"params": params,
},
config={
"callbacks": [self.langfuse_handler],
# 关键：通过 metadata 传递 Langfuse 所需参数
"metadata": {
"langfuse_session_id": self.session_id,  # 对应 Langfuse 的 session_id
"langfuse_user_id": params.user,        # 对应 Langfuse 的 user_id
# 可选：添加标签用于分类筛选
# "langfuse_tags": ["production", "rag-app"]
}
},
stream_mode=["updates", "messages", "custom"],  # LangChain 1.0 新增的流模式配置
subgraphs=True,  # 启用子图追踪，适配 LangChain 1.0 的工作流架构
):
# 流式输出逻辑...

2. 适配要点说明

•参数键名必须严格匹配：Langfuse 会通过 langfuse_session_id、langfuse_user_id 这两个固定键名解析参数，不可自定义；•兼容 LangChain 1.0 的新特性：stream_mode 和 subgraphs 是 LangChain 1.0 中 astream 方法的新增参数，用于支持更灵活的流式输出和子工作流追踪，需根据实际场景配置；•无需修改 CallbackHandler 实例：删除之前直接给 self.langfuse_handler.user_id 赋值的代码，避免冗余。

3. 验证结果

适配后重新部署应用，查看 Langfuse Traces 面板：

•Session ID 和 User ID 已正常显示，能够准确区分不同用户的请求；•链路追踪的完整性不受影响，步骤耗时、Token 消耗等指标正常统计。

Langfuse 监控恢复正常截图

（适配后 Session 和 User 信息正常显示，监控恢复完整）

四、总结与避坑建议

这次版本升级引发的适配问题，本质是框架升级带来的“隐性兼容变更”。结合实战经验，给大家提3点避坑建议：

1. 版本升级前先查兼容性文档

•LangChain 1.0 相比 0.3.x 有大量 API 变更（如回调机制、工作流执行方式），升级前务必查看 LangChain 官方迁移指南[1]；•Langfuse 针对不同 LangChain 版本有明确的适配说明，可参考 Langfuse 集成文档[2] 确认版本兼容性。

2. 理解工具的底层解析逻辑

遇到配置失效问题时，不要只停留在“改代码试效果”，可以通过查看源码（如 Langfuse 的 CallbackHandler 实现）理解参数传递的底层逻辑，这样能更精准地定位问题。

3. 关键监控配置要做回归测试

升级后需重点验证监控、日志等核心可观测性能力：

•确认链路追踪是否完整；•检查关键指标（如 Token 消耗、成本、响应时间）是否正常统计；•验证用户行为归因（如 Session/User 关联）是否准确。

如果你的 LLM 应用也在使用 LangChain + Langfuse 技术栈，或者正准备升级 LangChain 1.0，希望这篇适配指南能帮你避开类似坑点！如果还有其他升级疑问，欢迎在评论区交流～

最后，别忘了给文章点赞、在看，转发给身边有需要的开发者朋友！关注我，持续分享 LLM 应用开发的实战技巧和踩坑经验～

那么，如何系统的去学习大模型LLM？

作为一名深耕行业的资深大模型算法工程师，我经常会收到一些评论和私信，我是小白，学习大模型该从哪里入手呢？我自学没有方向怎么办？这个地方我不会啊。如果你也有类似的经历，一定要继续看下去！这些问题啊，也不是三言两语啊就能讲明白的。

所以我综合了大模型的所有知识点，给大家带来一套全网最全最细的大模型零基础教程。在做这套教程之前呢，我就曾放空大脑，以一个大模型小白的角度去重新解析它，采用基础知识和实战项目相结合的教学方式，历时3个月，终于完成了这样的课程，让你真正体会到什么是每一秒都在疯狂输出知识点。

由于篇幅有限，⚡️ 朋友们如果有需要全套 《2025全新制作的大模型全套资料》，扫码获取~

👉大模型学习指南+路线汇总👈

我们这套大模型资料呢，会从基础篇、进阶篇和项目实战篇等三大方面来讲解。

👉①.基础篇👈

基础篇里面包括了Python快速入门、AI开发环境搭建及提示词工程，带你学习大模型核心原理、prompt使用技巧、Transformer架构和预训练、SFT、RLHF等一些基础概念，用最易懂的方式带你入门大模型。

👉②.进阶篇👈

接下来是进阶篇，你将掌握RAG、Agent、Langchain、大模型微调和私有化部署，学习如何构建外挂知识库并和自己的企业相结合，学习如何使用langchain框架提高开发效率和代码质量、学习如何选择合适的基座模型并进行数据集的收集预处理以及具体的模型微调等等。

👉③.实战篇👈

实战篇会手把手带着大家练习企业级的落地项目（已脱敏），比如RAG医疗问答系统、Agent智能电商客服系统、数字人项目实战、教育行业智能助教等等，从而帮助大家更好的应对大模型时代的挑战。

👉④.福利篇👈

最后呢，会给大家一个小福利，课程视频中的所有素材，有搭建AI开发环境资料包，还有学习计划表，几十上百G素材、电子书和课件等等，只要你能想到的素材，我这里几乎都有。我已经全部上传到CSDN，朋友们如果需要可以微信扫描下方CSDN官方认证二维码免费领取【保证100%免费】

相信我，这套大模型系统教程将会是全网最齐全 最易懂的小白专用课！！