追踪 LiteLLM 应用

LiteLLM 提供了一个统一接口，使用一致的 OpenAI 兼容 API 来调用 LLM 提供商。它既可以作为 Python SDK 直接嵌入你的应用，也可以作为一个代理服务器为客户端应用暴露 OpenAI 兼容的端点。

本指南展示如何使用以下方式，通过 LangSmith 追踪 LiteLLM 调用：

• LangSmith SDK（@traceable）用于应用级追踪。
• LiteLLM 内置的 langsmith 回调用于模型级日志记录。
• LiteLLM Proxy用于网关级追踪。

安装

在使用 LiteLLM Python SDK 或 LiteLLM Proxy 时，安装以下内容：

Python SDK

pip install litellm langsmith openai

Proxy usage

npm install openai langsmith

本指南中的示例使用 OpenAI 模型，但你也可以为你的用例安装必要的提供商。

使用 LiteLLM Python SDK

LiteLLM 支持两种将追踪发送到 LangSmith 的方式，它们运行在不同的层级：

• LangSmith SDK 追踪 配合 LANGSMITH_TRACING=true，通过 LangSmith SDK 启用应用级追踪。当你想追踪更广泛的业务逻辑、多步骤流程或用 @traceable 创建的 span 时，这很有用。
• LiteLLM 内置的 langsmith 回调直接从 LiteLLM 记录模型调用。当你想专门追踪 LiteLLM 请求，或运行异步应用时，推荐使用此项。

NOTE

请避免对同一 LiteLLM 调用同时启用 LiteLLM 的 langsmith 回调和 LangSmith 追踪，因为这可能导致重复的追踪。

使用 LANGSMITH_TRACING 和 traceable

你可以将 LANGSMITH_TRACING=true 与 @traceable 结合使用，以在 LangSmith 中获得可预测的追踪。这种方式确保 Input 和 Output 列反映你的函数参数和返回值，让你能够保留完整的消息结构（包括 role 和 content）。它在简单的同步脚本中也能可靠工作，无需 asyncio 事件循环或额外的回调配置。

1. 设置以下环境变量，为 LiteLLM Python SDK 用法启用 LangSmith 追踪：

   export LANGSMITH_API_KEY="your_api_key"
   export LANGSMITH_PROJECT="litellm-integration"
   export LANGSMITH_TRACING="true"

   创建 LangSmith API 密钥，可在 LangSmith UI中完成。

   根据你所使用的提供商，你还需要设置 API 密钥：

   export OPENAI_API_KEY="your_openai_key"

2. 将以下代码添加到你的脚本文件中：

   from langsmith import traceable
   from litellm import completion
   
   @traceable(name="LiteLLM Chat Completion")
   def run(messages):
       response = completion(
           model="gpt-4o",
           messages=messages,
       )
       # Return the assistant message so the LangSmith UI shows role + content
       return response["choices"][0]["message"]
   
   messages = [
       {"role": "user", "content": "Explain observability in LLM systems."}
   ]
   
   result = run(messages)
   print(result["content"])

   @traceable 将你的函数作为一次 LangSmith 运行进行插桩。当设置了 LANGSMITH_TRACING=true 时，LangSmith 会自动：

   • 在函数被调用时创建一个运行。
   • 将函数参数记录为运行输入。
   • 执行函数体（包括 LiteLLM 调用）。
   • 将函数的返回值记录为运行输出。
   • 捕获时间、错误和嵌套 span（如有）。

   在此示例中，messages 参数成为追踪输入，返回的 assistant 消息对象成为追踪输出。LiteLLM 调用本身正常运行——@traceable 用可观测性包裹它，而不修改其行为。这种方式追踪的是你的应用逻辑，而不仅仅是模型调用。

TIP

有关使用 @traceable 的更通用示例，请参阅自定义插桩页面。

使用 langsmith 回调记录 LiteLLM 调用

LiteLLM 可以使用其内置的回调系统将追踪直接发送到 LangSmith。当你在一个异步 Python 服务内运行 LiteLLM，并希望 LiteLLM 自身发出模型级日志时，这很有用。

LiteLLM 回调在异步环境中运行。在使用 litellm.acompletion() 进行异步调用时，你可以启用 langsmith 回调来记录成功的模型调用。

TIP

这种方式最适合异步应用。对于简单的同步脚本，请使用上一节所示的 @traceable 方式。

1. 设置以下环境变量：

   export LANGSMITH_API_KEY="your_api_key"
   export LANGSMITH_PROJECT="litellm-integration"

   创建 LangSmith API 密钥，可在 LangSmith UI中完成。

   根据你所使用的提供商，你还需要设置 API 密钥：

   export OPENAI_API_KEY="your_openai_key"

2. 要在一个最小化脚本中运行此代码：

   • 使用 acompletion()（异步 API）。
   • 用 asyncio.run(...) 运行以创建事件循环。
   • 设置 langsmith_batch_size = 1 以立即刷新。

   import asyncio
   import litellm
   from litellm import acompletion
   
   # Enable LiteLLM → LangSmith callback
   litellm.success_callback = ["langsmith"]
   
   # For short-lived scripts, send immediately instead of waiting for batch flush
   litellm.langsmith_batch_size = 1
   
   async def main():
       response = await acompletion(
           model="gpt-4o",
           messages=[
               {"role": "user", "content": "Explain observability in LLM systems."}
           ],
       )
   
       # Print the assistant message content for local verification
       print(response["choices"][0]["message"]["content"])
   
       # Allow time for background logger to flush before process exit
       await asyncio.sleep(1)
   
   if __name__ == "__main__":
       asyncio.run(main())

   该回调将 LiteLLM 的模型请求和响应数据直接发送到 LangSmith，包括提供商元数据和 token 用量。由于由 LiteLLM 控制负载，与 @traceable 示例相比，Input 和 Output 列可能包含额外的元数据。

使用 LiteLLM Proxy

LiteLLM 代理作为独立服务器运行，并暴露一个 OpenAI 兼容的 API。

1. 要让代理将请求直接记录到 LangSmith，请在 config.yaml 中配置回调：

   model_list:
     - model_name: gpt-4o
       litellm_params:
         model: openai/gpt-4o
   
   litellm_settings:
     callbacks: ["langsmith"]

2. 在你的代理环境中设置环境变量：

   export LANGSMITH_API_KEY="your_api_key"
   export LANGSMITH_PROJECT="litellm-proxy"
   export OPENAI_API_KEY="your_openai_key"

NOTE

LiteLLM 代理作为独立服务运行。如果你在代理层级启用 LangSmith 追踪，必须在代理的运行时环境中配置 LANGSMITH_API_KEY 及相关环境变量。这些设置不会与你的应用进程共享。

3. 启动代理：

   litellm --config config.yaml

   默认情况下，代理运行在 http://localhost:4000/v1。你的应用使用任何 OpenAI 兼容客户端（Python、JavaScript、curl 等）调用它。

   启用 callbacks: ["langsmith"] 后，代理会将模型请求和响应数据直接发送到 LangSmith。客户端应用无需追踪配置。

4. 从另一个终端窗口调用代理：

Python

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000/v1",
    api_key="anything"  # proxy may require a key but doesn't validate it by default
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[
        {"role": "user", "content": "What is LiteLLM?"}
    ],
)

print(response.choices[0].message.content)

JavaScript

import OpenAI from "openai";

const client = new OpenAI({
apiKey: "anything",
baseURL: "http://localhost:4000/v1",
});

const response = await client.chat.completions.create({
model: "gpt-4o",
messages: [
    { role: "user", content: "Explain LiteLLM tracing." }
],
});

console.log(response.choices[0].message.content);

客户端发送一个普通的聊天补全请求，代理负责提供商路由和响应格式化。

后续步骤

• 在 LangSmith 中查看追踪
• 添加自定义元数据
• 过滤并采样追踪

---