纲要可观测性AI 应用走向生产环境的必要条件LangSmith核心能力全链路追踪自动记录 LLM 调用、工具执行与链式调用性能指标延迟百分位P50/P99、Token 消耗错误监控与调试零侵入集成通过环境变量配置实现自动化追踪关键指标解析首 Token 时间与端到端延迟成本统计与 Token 用量错误率与执行详情私有化部署方案简介完整可运行示例项目结构依赖安装与.env配置main.py启用追踪的 Agent 实现运行与观测面板总结可观测性从“感觉”到“数据”的工程转型AI 应用上线仅是起点持续优化才是常态。传统分布式系统可通过埋点收集性能数据而基于大语言模型的智能体引入了新的复杂性模型调用延迟、Token 消耗、工具链各环节耗时等单纯依赖本地测试难以还原真实生产环境的多样性。LangSmith是 LangChain 团队推出的全栈可观测性平台专为 LLM 应用设计核心能力覆盖以下维度功能描述追踪自动记录每次 LLM 调用、工具执行、链的完整调用链路评估支持创建测试数据集量化回答质量提示词管理版本化提示词模板支持在线调试与回滚在实际开发中追踪功能最为常用无需修改核心业务代码仅通过配置环境变量即可将生产环境的每一次交互完整记录便于后续分析与优化。零侵入集成基于环境变量的配置方式LangChain 已将LangSmith的追踪 SDK 内置在核心包中开发者无需额外安装或显式调用追踪装饰器。只需通过环境变量告知 SDK 数据上报目标。在项目根目录的.env文件中添加以下配置LANGCHAIN_TRACING_V2true LANGCHAIN_ENDPOINThttps://api.smith.langchain.com LANGCHAIN_API_KEYls__xxxx # 从 LangSmith 控制台生成 LANGCHAIN_PROJECTobservability-demo # 自定义项目名称在代码入口处加载环境变量fromdotenvimportload_dotenv load_dotenv()配置生效后所有基于 LangChain 组件Chain、Agent、Tool、LLM调用的代码均会被自动追踪无需手动添加装饰器或注册回调。核心指标解读在LangSmith的项目面板中以下指标对日常性能优化与成本控制具有直接指导意义P50 延迟第 50 百分位的请求耗时反映典型用户体验。P99 延迟第 99 百分位的耗时用于定位长尾请求的性能瓶颈。Token 消耗每次调用的输入/输出 Token 数量及累计成本是成本优化的核心依据。首 Token 时间流式输出场景下用户收到首个字符的耗时直接影响交互体感。错误率统计周期内的运行失败比例。点击任意一次运行记录可查看完整的调用树从用户输入、Agent 决策、工具调用到最终回答每一步的耗时、输入输出及模型名称均清晰可见。下图展示了一条典型的 Agent 追踪链路工具LLM (gpt-4o)AgentExecutor用户工具LLM (gpt-4o)AgentExecutor用户总耗时 2.95s消耗 1200 Token输入请求推理含 Prompt 与历史决策调用 create_todo执行 create_todo返回结果再次推理含工具结果生成最终回答输出回复私有化部署方案对于数据主权与安全合规要求较高的场景LangSmith提供了完整的自托管方案。官方仓库中包含 Docker Compose 编排文件集成了前端、后端、ClickHouse、PostgreSQL、Redis 等组件。部署步骤如下gitclone https://github.com/langchain-ai/langsmithcdlangsmithdockercompose up-d部署完成后将环境变量LANGCHAIN_ENDPOINT修改为自建服务的地址即可。需注意私有化部署需要根据实际硬件资源配置适当的存储与计算容量。完整可运行示例本节构建一个最小化的可运行示例演示如何启用 LangSmith 追踪并观察执行结果。项目结构observability_demo/ ├── main.py ├── .env └── requirements.txt依赖安装pipinstalllangchain langchain-openai python-dotenv适用版本langchain0.1.0langchain-openai0.0.5环境变量配置.envOPENAI_API_KEYsk-xxxx LANGCHAIN_TRACING_V2true LANGCHAIN_ENDPOINThttps://api.smith.langchain.com LANGCHAIN_API_KEYls__xxxx LANGCHAIN_PROJECTobservability-demo其中LANGCHAIN_API_KEY需在 smith.langchain.com 注册并生成。主程序main.py# main.pyimportosfromdotenvimportload_dotenv load_dotenv()fromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportAgentExecutor,create_tool_calling_agentfromlangchain.toolsimporttoolfromlangchain.promptsimportChatPromptTemplate,MessagesPlaceholder# 定义一个简单的工具函数模拟外部 API 调用tooldefget_weather(city:str)-str:获取指定城市的天气信息# 实际场景中可替换为真实的 API 请求returnf{city}今天晴朗气温 25°Ctools[get_weather]defmain():# 初始化 LLM建议使用 gpt-4o-mini 以降低实验成本llmChatOpenAI(modelgpt-4o-mini,temperature0)promptChatPromptTemplate.from_messages([(system,你是一个智能助手可以使用提供的工具回答用户问题。),MessagesPlaceholder(chat_history),(human,{input}),MessagesPlaceholder(agent_scratchpad),])agentcreate_tool_calling_agent(llm,tools,prompt)executorAgentExecutor(agentagent,toolstools,verboseFalse)# 执行两次对话生成追踪数据print(第一次询问)resexecutor.invoke({input:北京今天天气怎么样})print(助手回答:,res[output])print(\n第二次询问)resexecutor.invoke({input:我想记录一个待办事项买水果})print(助手回答:,res[output])if__name____main__:main()运行与观测执行python main.py后登录 LangSmith 控制台在observability-demo项目中即可查看两次完整执行记录涵盖工具调用详情、Token 消耗和端到端延迟。API 速览API / 组件所属库说明ChatOpenAIlangchain_openaiOpenAI 模型封装支持model、temperature等参数create_tool_calling_agentlangchain.agents构建支持工具调用的 Agent要求langchain0.1.0AgentExecutorlangchain.agentsAgent 执行器管理推理与工具调用循环toollangchain.tools装饰器将普通函数转换为 LangChain 工具load_dotenvpython-dotenv加载.env文件中的环境变量参考文档官方文档LangSmith 官方文档LangChain 追踪概念LangChain TracingLangSmith GitHub 仓库langchain-ai/langsmith总结可观测性是 AI 应用走向生产环境的必备基础设施。LangSmith以极低的接入成本提供了全链路追踪、性能指标与成本统计能力使开发者能够基于数据驱动的方式优化智能体的响应速度与资源消耗。本文详细介绍了 LangSmith 的配置方法、核心指标解读、私有化部署思路及完整的示例代码所有示例均基于 LangChain 标准组件可快速移植到现有项目中。 AI Agent从无到有58: 项目可观测性——用 LangSmith 实现全链路追踪
纲要可观测性AI 应用走向生产环境的必要条件LangSmith核心能力全链路追踪自动记录 LLM 调用、工具执行与链式调用性能指标延迟百分位P50/P99、Token 消耗错误监控与调试零侵入集成通过环境变量配置实现自动化追踪关键指标解析首 Token 时间与端到端延迟成本统计与 Token 用量错误率与执行详情私有化部署方案简介完整可运行示例项目结构依赖安装与.env配置main.py启用追踪的 Agent 实现运行与观测面板总结可观测性从“感觉”到“数据”的工程转型AI 应用上线仅是起点持续优化才是常态。传统分布式系统可通过埋点收集性能数据而基于大语言模型的智能体引入了新的复杂性模型调用延迟、Token 消耗、工具链各环节耗时等单纯依赖本地测试难以还原真实生产环境的多样性。LangSmith是 LangChain 团队推出的全栈可观测性平台专为 LLM 应用设计核心能力覆盖以下维度功能描述追踪自动记录每次 LLM 调用、工具执行、链的完整调用链路评估支持创建测试数据集量化回答质量提示词管理版本化提示词模板支持在线调试与回滚在实际开发中追踪功能最为常用无需修改核心业务代码仅通过配置环境变量即可将生产环境的每一次交互完整记录便于后续分析与优化。零侵入集成基于环境变量的配置方式LangChain 已将LangSmith的追踪 SDK 内置在核心包中开发者无需额外安装或显式调用追踪装饰器。只需通过环境变量告知 SDK 数据上报目标。在项目根目录的.env文件中添加以下配置LANGCHAIN_TRACING_V2true LANGCHAIN_ENDPOINThttps://api.smith.langchain.com LANGCHAIN_API_KEYls__xxxx # 从 LangSmith 控制台生成 LANGCHAIN_PROJECTobservability-demo # 自定义项目名称在代码入口处加载环境变量fromdotenvimportload_dotenv load_dotenv()配置生效后所有基于 LangChain 组件Chain、Agent、Tool、LLM调用的代码均会被自动追踪无需手动添加装饰器或注册回调。核心指标解读在LangSmith的项目面板中以下指标对日常性能优化与成本控制具有直接指导意义P50 延迟第 50 百分位的请求耗时反映典型用户体验。P99 延迟第 99 百分位的耗时用于定位长尾请求的性能瓶颈。Token 消耗每次调用的输入/输出 Token 数量及累计成本是成本优化的核心依据。首 Token 时间流式输出场景下用户收到首个字符的耗时直接影响交互体感。错误率统计周期内的运行失败比例。点击任意一次运行记录可查看完整的调用树从用户输入、Agent 决策、工具调用到最终回答每一步的耗时、输入输出及模型名称均清晰可见。下图展示了一条典型的 Agent 追踪链路工具LLM (gpt-4o)AgentExecutor用户工具LLM (gpt-4o)AgentExecutor用户总耗时 2.95s消耗 1200 Token输入请求推理含 Prompt 与历史决策调用 create_todo执行 create_todo返回结果再次推理含工具结果生成最终回答输出回复私有化部署方案对于数据主权与安全合规要求较高的场景LangSmith提供了完整的自托管方案。官方仓库中包含 Docker Compose 编排文件集成了前端、后端、ClickHouse、PostgreSQL、Redis 等组件。部署步骤如下gitclone https://github.com/langchain-ai/langsmithcdlangsmithdockercompose up-d部署完成后将环境变量LANGCHAIN_ENDPOINT修改为自建服务的地址即可。需注意私有化部署需要根据实际硬件资源配置适当的存储与计算容量。完整可运行示例本节构建一个最小化的可运行示例演示如何启用 LangSmith 追踪并观察执行结果。项目结构observability_demo/ ├── main.py ├── .env └── requirements.txt依赖安装pipinstalllangchain langchain-openai python-dotenv适用版本langchain0.1.0langchain-openai0.0.5环境变量配置.envOPENAI_API_KEYsk-xxxx LANGCHAIN_TRACING_V2true LANGCHAIN_ENDPOINThttps://api.smith.langchain.com LANGCHAIN_API_KEYls__xxxx LANGCHAIN_PROJECTobservability-demo其中LANGCHAIN_API_KEY需在 smith.langchain.com 注册并生成。主程序main.py# main.pyimportosfromdotenvimportload_dotenv load_dotenv()fromlangchain_openaiimportChatOpenAIfromlangchain.agentsimportAgentExecutor,create_tool_calling_agentfromlangchain.toolsimporttoolfromlangchain.promptsimportChatPromptTemplate,MessagesPlaceholder# 定义一个简单的工具函数模拟外部 API 调用tooldefget_weather(city:str)-str:获取指定城市的天气信息# 实际场景中可替换为真实的 API 请求returnf{city}今天晴朗气温 25°Ctools[get_weather]defmain():# 初始化 LLM建议使用 gpt-4o-mini 以降低实验成本llmChatOpenAI(modelgpt-4o-mini,temperature0)promptChatPromptTemplate.from_messages([(system,你是一个智能助手可以使用提供的工具回答用户问题。),MessagesPlaceholder(chat_history),(human,{input}),MessagesPlaceholder(agent_scratchpad),])agentcreate_tool_calling_agent(llm,tools,prompt)executorAgentExecutor(agentagent,toolstools,verboseFalse)# 执行两次对话生成追踪数据print(第一次询问)resexecutor.invoke({input:北京今天天气怎么样})print(助手回答:,res[output])print(\n第二次询问)resexecutor.invoke({input:我想记录一个待办事项买水果})print(助手回答:,res[output])if__name____main__:main()运行与观测执行python main.py后登录 LangSmith 控制台在observability-demo项目中即可查看两次完整执行记录涵盖工具调用详情、Token 消耗和端到端延迟。API 速览API / 组件所属库说明ChatOpenAIlangchain_openaiOpenAI 模型封装支持model、temperature等参数create_tool_calling_agentlangchain.agents构建支持工具调用的 Agent要求langchain0.1.0AgentExecutorlangchain.agentsAgent 执行器管理推理与工具调用循环toollangchain.tools装饰器将普通函数转换为 LangChain 工具load_dotenvpython-dotenv加载.env文件中的环境变量参考文档官方文档LangSmith 官方文档LangChain 追踪概念LangChain TracingLangSmith GitHub 仓库langchain-ai/langsmith总结可观测性是 AI 应用走向生产环境的必备基础设施。LangSmith以极低的接入成本提供了全链路追踪、性能指标与成本统计能力使开发者能够基于数据驱动的方式优化智能体的响应速度与资源消耗。本文详细介绍了 LangSmith 的配置方法、核心指标解读、私有化部署思路及完整的示例代码所有示例均基于 LangChain 标准组件可快速移植到现有项目中。