LangSmith 快速入门：3分钟实现 OpenAI 调用与应用的全链路追踪

摘要： 在构建大模型应用时，无论是直接调用 OpenAI API，还是构建复杂的 RAG（检索增强生成）系统，开发者都需要一种能够洞察内部运行机制的工具。LangSmith 不仅能无缝集成 LangChain，还能通过简单的包装器直接追踪原生的 OpenAI 调用。本文将手把手教你如何使用 wrap_openai 和 @traceable 装饰器，从零开始追踪你的 LLM 应用。

1. 前言：为什么我们需要追踪？

在开发大模型应用时，我们经常面临两个痛点：

• API 调用黑盒：直接使用 openai 库时，我们很难直观地看到每次请求的 Token 消耗、耗时以及具体的输入输出细节。
• 逻辑断层：在 RAG 或 Agent 应用中，如果最终答案错误，很难定位是“检索环节”出了问题，还是“模型生成环节”出了问题。
  LangSmith 提供了极其轻量级的解决方案，无需重构整个代码架构，只需几行代码即可实现全链路可视化。

2. 环境准备

首先，确保你已经安装了必要的 Python 库：

pip install openai langsmith

同时，你需要设置 LangSmith 的环境变量以启用追踪（获取 API Key） ：

import os
os.environ["LANGCHAIN_TRACING_V2"] = "true"
os.environ["LANGCHAIN_API_KEY"] = "lsv2_sk_..." # 替换为你的 Key
os.environ["LANGCHAIN_PROJECT"] = "My-Quickstart" # 项目名称

3. 基础篇：追踪 OpenAI 调用

很多时候，我们的应用是基于原生 OpenAI SDK 开发的，不想引入 LangChain 的复杂概念。这时，LangSmith 的 wrap_openai 包装器就派上用场了。

它可以在不改变原有 client 使用习惯的情况下，自动捕获所有 API 请求并发送到 LangSmith 平台。

3.1 代码实现

假设我们有一个简单的 RAG 逻辑（为了演示，Retriever 部分进行了 Mock）：

from openai import OpenAI
from langsmith.wrappers import wrap_openai

# 1. 使用 wrap_openai 包装原生客户端
openai_client = wrap_openai(OpenAI())

# 模拟一个检索器
def retriever(query: str):
    # 实际场景中这里会是向量数据库检索
    results = ["Harrison worked at Kensho"]
    return results

# 定义端到端的 RAG 函数
def rag(question):
    # A. 检索步骤
    docs = retriever(question)
    
    # B. 构建 Prompt
    system_message = """Answer the users question using only the provided information below:
    
    {docs}""".format(docs="\n".join(docs))
    
    # C. 调用 OpenAI
    return openai_client.chat.completions.create(
        messages=[
            {"role": "system", "content": system_message},
            {"role": "user", "content": question},
        ],
        model="gpt-4o-mini",
    )

# 执行调用
response = rag("where did harrison work")
print(response.choices[0].message.content)

3.2 效果查看

运行上述代码后，登录 LangSmith 控制台。你会看到一个名为 chat.completions.create 的 Run。点击进入，你可以清晰地看到传入的 system_message 包含了检索到的上下文，以及模型的最终回复。

4. 进阶篇：追踪整个应用程序流水线

仅仅追踪 OpenAI 调用往往是不够的。我们更希望看到整个业务流程（比如“先检索，再生成”）。这时候，我们需要使用 Python 的魔法——装饰器。

LangSmith 提供了 @traceable 装饰器，可以将任何 Python 函数变成 LangSmith 中可追踪的节点。

4.1 代码实现

我们在刚才的代码基础上，仅做一个小小的修改：给 rag 函数加上装饰器。

from openai import OpenAI
from langsmith import traceable  # 引入装饰器
from langsmith.wrappers import wrap_openai

openai_client = wrap_openai(OpenAI())

def retriever(query: str):
    results = ["Harrison worked at Kensho"]
    return results

# 【关键修改】添加 @traceable 装饰器
@traceable 
def rag(question):
    docs = retriever(question)
    system_message = """Answer the users question using only the provided information below:
    
    {docs}""".format(docs="\n".join(docs))
    
    return openai_client.chat.completions.create(
        messages=[
            {"role": "system", "content": system_message},
            {"role": "user", "content": question},
        ],
        model="gpt-4o-mini",
    )

# 再次执行调用
rag("where did harrison work")

4.2 效果对比

再次查看 LangSmith 控制台，你会发现截然不同的视图：

层级结构：顶层不再是 chat.completions.create，而是 rag 函数。
子运行：展开 rag 节点，你会看到它包含了一个子节点，即底层的 OpenAI 调用。
全景视图：这让你一眼就能看出这是一个完整的 RAG 流程，而不仅仅是一次孤立的 API 请求。

视图结构示意：

📦 rag (Root)
└── 📦 chat.completions.create (Child)
├── Input: System Message + User Question
└── Output: “Harrison worked at Kensho…”

5. 总结

通过本文的实践，我们掌握了两种核心追踪技巧：

• wrap_openai：零侵入式地接入原生 OpenAI 代码，适合存量项目的快速监控。
• @traceable：自定义业务逻辑的追踪边界，适合构建复杂的 RAG 或 Agent 流水线。
  这两个工具是 LangSmith 生态中最轻量但也最强大的入口。接下来，你可以尝试将 retriever 函数也加上 @traceable，从而构建一个包含“检索”和“生成”两个阶段的完整 Trace 图谱。

参考资源：

LangSmith 官方文档: https://docs.smith.langchain.com/
OpenAI Python SDK: https://github.com/openai/openai-python
希望这篇快速入门指南能帮助你更好地掌控你的 LLM 应用！🎉