如何在Dify中结合LangSmith对Agent的每一个推理步骤进行链路追踪

老敏姑娘_7734

发布时间：2026-07-07 12:47:18

450人浏览过

来源于php中文网

原创

必须升级Dify至v1.4.0+并配置LangSmith追踪：检查dify-sdk版本、注入环境变量、替换TraceQueueManager为LangSmith Client、在LLM和Tool调用处添加log埋点，最后通过LangSmith控制台验证三层嵌套span完整性。

☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜

如何在dify中结合langsmith对agent的每一个推理步骤进行链路追踪

你需要在Dify中精准定位Agent某次会话里模型为何突然跳转到错误工具、提示词微调后RAG召回率下降了37%、或用户连续三次提问后记忆模块丢失上下文——这些都必须靠逐节点的链路追踪来归因，而不是翻日志猜。

确认Dify版本与LangSmith兼容性

确保你使用的是 Dify v1.4.0 或更高版本，低版本不支持外部追踪器注入点。v1.3.x 及以下版本在 CompletionAppGenerateEntity 初始化时未暴露 trace_manager 参数，强行注入会导致 TypeError: unexpected keyword argument 'trace_manager'。

打开 Dify 项目根目录下的 pyproject.toml 或 requirements.txt，检查 dify-sdk 版本是否 ≥ 1.4.0。

【必须升级】 若版本低于 1.4.0，请执行：pip install --upgrade dify-sdk 并重启 Dify 后端服务。

配置LangSmith环境变量并验证连接

LangSmith 不通过 Dify 控制台配置，必须在 Dify 服务启动环境中注入变量。

编辑 Dify 的部署启动脚本（如 docker-compose.yml 中的 environment 块，或 systemd service 文件的 Environment= 行），添加以下四行：

LANGCHAIN_TRACING_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=ls__your_actual_api_key_here
LANGCHAIN_PROJECT=dify-prod-tracing

注意：不要把 LANGCHAIN_API_KEY 写成占位符 ls__xxxxxx，必须是真实密钥；LANGCHAIN_PROJECT 名称不能含空格或特殊字符，否则 LangSmith 后端会拒绝接收 trace。

重启 Dify 服务后，在任意终端执行：curl -s "https://api.smith.langchain.com/projects?api_key=$LANGCHAIN_API_KEY" | jq '.data[0].name'，返回 "dify-prod-tracing" 即表示连接成功。

修改Dify源码注入LangSmith客户端

Dify 默认使用内置 TraceQueueManager，需手动替换为 LangSmith 客户端实例。

定位文件：apps/completion/app_generator.py，找到 generate() 方法内创建 trace_manager 的位置（约第 87 行）：

将原代码：

trace_manager = TraceQueueManager(app_id=app_model.id, user_id=user.id if isinstance(user, Account) else user.session_id)

Dify Workflow DSL Expert

用于创建、编辑、调试或验证自托管 Dify 的工作流 DSL。首先从目标实例导出的工作流入手，进行最小化编辑。

下载

替换为：

from langsmith import Client<br>
langsmith_client = Client()<br>
trace_manager = langsmith_client

⚠️ 这一步不可跳过：Dify 的 CompletionAppGenerateEntity 构造函数虽接受 trace_manager 参数，但其内部仅调用 trace_manager.log() 方法——而 LangSmith Client 对象恰好提供同名方法，且签名完全兼容（log(name, inputs, outputs, ...)），无需额外封装。

启用Dify运行时链路埋点

LangSmith 客户端已就位，但 Dify 默认不会主动上报 LLM 调用、Tool 执行、RAG 检索等事件，必须开启显式埋点。

打开 configs/settings.py，在 LLM_PROVIDER 配置块下方新增：

ENABLE_LANGSMITH_TRACING = True

然后进入 apps/completion/generation/llm_generator.py，在 invoke_llm() 方法开头插入：

if settings.ENABLE_LANGSMITH_TRACING:<br>
  trace_manager.log("llm_invoke", inputs={"prompt": prompt, "model": model_name}, outputs={"raw_response": response_text})

同理，在 apps/completion/generation/tool_executor.py 的 execute_tool() 方法中，于 result = tool.func(**tool_inputs) 后添加：

if settings.ENABLE_LANGSMITH_TRACING:<br>
  trace_manager.log("tool_call", inputs={"tool_name": tool.name, "inputs": tool_inputs}, outputs={"result": result})

这一步决定了你能看到多少层细节：不加这两处埋点，LangSmith 里只有一条空的 root trace，看不到任何子节点。