追踪 LiteLLM 应用

• 使用 LangSmith SDK (@traceable) 进行应用级追踪。
• 使用 LiteLLM 内置的 langsmith 回调 进行模型级日志记录。
• 使用 LiteLLM 代理 进行网关级追踪。

​

安装

pip install litellm langsmith openai

​

使用 LiteLLM Python SDK

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

​

使用 LANGSMITH_TRACING 和 traceable

1. 设置以下环境变量，为 LiteLLM Python SDK 用法启用 LangSmith 追踪：
   export LANGSMITH_API_KEY="your_api_key"
   export LANGSMITH_PROJECT="litellm-integration"
   export LANGSMITH_TRACING="true"
   
   在 LangSmith UI 中创建 LangSmith API 密钥。 根据你使用的提供商，你还需要设置 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,
       )
       # 返回助手消息，以便 LangSmith UI 显示 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 参数成为追踪输入，返回的助手消息对象成为追踪输出。LiteLLM 调用本身正常运行——@traceable 通过可观测性包装它，而不是修改其行为。这种方法追踪的是你的应用逻辑，而不仅仅是模型调用。
   有关使用 @traceable 的更多通用示例，请参阅 自定义检测 页面。

​

使用 langsmith 回调记录 LiteLLM 调用

1. 设置以下环境变量：
   export LANGSMITH_API_KEY="your_api_key"
   export LANGSMITH_PROJECT="litellm-integration"
   
   在 LangSmith UI 中创建 LangSmith API 密钥。 根据你使用的提供商，你还需要设置 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
   
   # 启用 LiteLLM → LangSmith 回调
   litellm.success_callback = ["langsmith"]
   
   # 对于短期运行的脚本，立即发送而不是等待批量刷新
   litellm.langsmith_batch_size = 1
   
   async def main():
       response = await acompletion(
           model="gpt-4o",
           messages=[
               {"role": "user", "content": "Explain observability in LLM systems."}
           ],
       )
   
       # 打印助手消息内容以进行本地验证
       print(response["choices"][0]["message"]["content"])
   
       # 在进程退出前留出时间让后台记录器刷新
       await asyncio.sleep(1)
   
   if __name__ == "__main__":
       asyncio.run(main())
   
   该回调将 LiteLLM 的模型请求和响应数据直接发送到 LangSmith，包括提供商元数据和令牌使用情况。由于 LiteLLM 控制有效负载，与 @traceable 示例相比，输入 和 输出 列可能包含额外的元数据。

​

使用 LiteLLM 代理

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"
   
   LiteLLM 代理作为单独的服务运行。如果你在代理级别启用 LangSmith 追踪，必须在代理的运行时环境中配置 LANGSMITH_API_KEY 和相关环境变量。这些设置不会与你的应用进程共享。
3. 启动代理：
   litellm --config config.yaml
   
   默认情况下，代理在 http://localhost:4000/v1 运行。你的应用使用任何 OpenAI 兼容客户端（Python、JavaScript、curl 等）调用它。 启用 callbacks: ["langsmith"] 后，代理会将模型请求和响应数据直接发送到 LangSmith。客户端应用中无需进行追踪配置。
4. 从另一个终端窗口调用代理：
   Python

   JavaScript

   from openai import OpenAI
   
   client = OpenAI(
       base_url="http://localhost:4000/v1",
       api_key="anything"  # 代理可能需要密钥，但默认情况下不验证
   )
   
   response = client.chat.completions.create(
       model="gpt-4o",
       messages=[
           {"role": "user", "content": "What is LiteLLM?"}
       ],
   )
   
   print(response.choices[0].message.content)
   
   客户端发送正常的聊天补全请求，代理处理提供商路由和响应格式化。

​

后续步骤

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