企业官网建设流程全解析

纲要

• 可观测性：AI 应用走向生产环境的必要条件
• LangSmith核心能力
  • 全链路追踪：自动记录 LLM 调用、工具执行与链式调用
  • 性能指标：延迟百分位（P50/P99）、Token 消耗
  • 错误监控与调试
• 零侵入集成：通过环境变量配置实现自动化追踪
• 关键指标解析
  • 首 Token 时间与端到端延迟
  • 成本统计与 Token 用量
  • 错误率与执行详情
• 私有化部署方案简介
• 完整可运行示例
  • 项目结构
  • 依赖安装与.env配置
  • main.py：启用追踪的 Agent 实现
  • 运行与观测面板
• 总结

可观测性：从“感觉”到“数据”的工程转型

AI 应用上线仅是起点，持续优化才是常态。传统分布式系统可通过埋点收集性能数据，而基于大语言模型的智能体引入了新的复杂性：模型调用延迟、Token 消耗、工具链各环节耗时等，单纯依赖本地测试难以还原真实生产环境的多样性。

LangSmith是 LangChain 团队推出的全栈可观测性平台，专为 LLM 应用设计，核心能力覆盖以下维度：

在实际开发中，追踪功能最为常用：无需修改核心业务代码，仅通过配置环境变量即可将生产环境的每一次交互完整记录，便于后续分析与优化。

零侵入集成：基于环境变量的配置方式

LangChain 已将LangSmith的追踪 SDK 内置在核心包中，开发者无需额外安装或显式调用追踪装饰器。只需通过环境变量告知 SDK 数据上报目标。

在项目根目录的.env文件中添加以下配置：

LANGCHAIN_TRACING_V2=true LANGCHAIN_ENDPOINT=https://api.smith.langchain.com LANGCHAIN_API_KEY=ls__xxxx # 从 LangSmith 控制台生成 LANGCHAIN_PROJECT=observability-demo # 自定义项目名称

在代码入口处加载环境变量：

fromdotenvimportload_dotenv load_dotenv()

配置生效后，所有基于 LangChain 组件（Chain、Agent、Tool、LLM调用）的代码均会被自动追踪，无需手动添加装饰器或注册回调。

核心指标解读

在LangSmith的项目面板中，以下指标对日常性能优化与成本控制具有直接指导意义：

• P50 延迟：第 50 百分位的请求耗时，反映典型用户体验。
• P99 延迟：第 99 百分位的耗时，用于定位长尾请求的性能瓶颈。
• Token 消耗：每次调用的输入/输出 Token 数量及累计成本，是成本优化的核心依据。
• 首 Token 时间：流式输出场景下，用户收到首个字符的耗时，直接影响交互体感。
• 错误率：统计周期内的运行失败比例。

点击任意一次运行记录，可查看完整的调用树：从用户输入、Agent 决策、工具调用到最终回答，每一步的耗时、输入输出及模型名称均清晰可见。下图展示了一条典型的 Agent 追踪链路：

私有化部署方案

对于数据主权与安全合规要求较高的场景，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

适用版本：langchain>=0.1.0，langchain-openai>=0.0.5

环境变量配置.env

OPENAI_API_KEY=sk-xxxx LANGCHAIN_TRACING_V2=true LANGCHAIN_ENDPOINT=https://api.smith.langchain.com LANGCHAIN_API_KEY=ls__xxxx LANGCHAIN_PROJECT=observability-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°C"tools=[get_weather]defmain():# 初始化 LLM，建议使用 gpt-4o-mini 以降低实验成本llm=ChatOpenAI(model="gpt-4o-mini",temperature=0)prompt=ChatPromptTemplate.from_messages([("system","你是一个智能助手，可以使用提供的工具回答用户问题。"),MessagesPlaceholder("chat_history"),("human","{input}"),MessagesPlaceholder("agent_scratchpad"),])agent=create_tool_calling_agent(llm,tools,prompt)executor=AgentExecutor(agent=agent,tools=tools,verbose=False)# 执行两次对话，生成追踪数据print("第一次询问：")res=executor.invoke({"input":"北京今天天气怎么样？"})print("助手回答:",res["output"])print("\n第二次询问：")res=executor.invoke({"input":"我想记录一个待办事项：买水果"})print("助手回答:",res["output"])if__name__=="__main__":main()

运行与观测

执行python main.py后，登录 LangSmith 控制台，在observability-demo项目中即可查看两次完整执行记录，涵盖工具调用详情、Token 消耗和端到端延迟。

API 速览

参考文档

• 官方文档：LangSmith 官方文档
• LangChain 追踪概念：LangChain Tracing
• LangSmith GitHub 仓库：langchain-ai/langsmith

总结

可观测性是 AI 应用走向生产环境的必备基础设施。LangSmith以极低的接入成本提供了全链路追踪、性能指标与成本统计能力，使开发者能够基于数据驱动的方式优化智能体的响应速度与资源消耗。

本文详细介绍了 LangSmith 的配置方法、核心指标解读、私有化部署思路及完整的示例代码，所有示例均基于 LangChain 标准组件，可快速移植到现有项目中。