纲要
- 可观测性: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_V2=true
LANGCHAIN_ENDPOINT=https://api.smith.langchain.com
LANGCHAIN_API_KEY=ls__xxxx # 从 LangSmith 控制台生成
LANGCHAIN_PROJECT=observability-demo # 自定义项目名称
在代码入口处加载环境变量:
from dotenv import load_dotenv
load_dotenv()
配置生效后,所有基于 LangChain 组件(Chain、Agent、Tool、LLM 调用)的代码均会被自动追踪,无需手动添加装饰器或注册回调。
核心指标解读
在 LangSmith 的项目面板中,以下指标对日常性能优化与成本控制具有直接指导意义:
- P50 延迟:第 50 百分位的请求耗时,反映典型用户体验。
- P99 延迟:第 99 百分位的耗时,用于定位长尾请求的性能瓶颈。
- Token 消耗:每次调用的输入/输出 Token 数量及累计成本,是成本优化的核心依据。
- 首 Token 时间:流式输出场景下,用户收到首个字符的耗时,直接影响交互体感。
- 错误率:统计周期内的运行失败比例。
点击任意一次运行记录,可查看完整的调用树:从用户输入、Agent 决策、工具调用到最终回答,每一步的耗时、输入输出及模型名称均清晰可见。下图展示了一条典型的 Agent 追踪链路:
私有化部署方案
对于数据主权与安全合规要求较高的场景,LangSmith 提供了完整的自托管方案。官方仓库中包含 Docker Compose 编排文件,集成了前端、后端、ClickHouse、PostgreSQL、Redis 等组件。部署步骤如下:
git clone https://github.com/langchain-ai/langsmith
cd langsmith
docker compose up -d
部署完成后,将环境变量 LANGCHAIN_ENDPOINT 修改为自建服务的地址即可。需注意,私有化部署需要根据实际硬件资源配置适当的存储与计算容量。
完整可运行示例
本节构建一个最小化的可运行示例,演示如何启用 LangSmith 追踪并观察执行结果。
项目结构
observability_demo/
├── main.py
├── .env
└── requirements.txt
依赖安装
pip install langchain 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.py
import os
from dotenv import load_dotenv
load_dotenv()
from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain.tools import tool
from langchain.prompts import ChatPromptTemplate, MessagesPlaceholder
# 定义一个简单的工具函数,模拟外部 API 调用
@tool
def get_weather(city: str) -> str:
"""获取指定城市的天气信息"""
# 实际场景中可替换为真实的 API 请求
return f"{city} 今天晴朗,气温 25°C"
tools = [get_weather]
def main():
# 初始化 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 速览
| API / 组件 | 所属库 | 说明 |
|---|---|---|
ChatOpenAI | langchain_openai | OpenAI 模型封装,支持 model、temperature 等参数 |
create_tool_calling_agent | langchain.agents | 构建支持工具调用的 Agent,要求 langchain>=0.1.0 |
AgentExecutor | langchain.agents | Agent 执行器,管理推理与工具调用循环 |
@tool | langchain.tools | 装饰器,将普通函数转换为 LangChain 工具 |
load_dotenv | python-dotenv | 加载 .env 文件中的环境变量 |
参考文档
- 官方文档:LangSmith 官方文档
- LangChain 追踪概念:LangChain Tracing
- LangSmith GitHub 仓库:langchain-ai/langsmith
总结
可观测性是 AI 应用走向生产环境的必备基础设施。LangSmith 以极低的接入成本提供了全链路追踪、性能指标与成本统计能力,使开发者能够基于数据驱动的方式优化智能体的响应速度与资源消耗。
本文详细介绍了 LangSmith 的配置方法、核心指标解读、私有化部署思路及完整的示例代码,所有示例均基于 LangChain 标准组件,可快速移植到现有项目中。
127



被折叠的 条评论
为什么被折叠?



