助手
扣子 AI 帮助与支持
你好,我是 扣子 文档问答助手 🎉 你在阅读当前文档的过程中,无论对文档概念的解释,还是文档内容方面的疑问,都可以随时向我提问,我会全力为你解答
推荐问题
如何快速了解这个空间的核心内容?
有哪些近期更新的重点文档?
我应该从哪些文档开始阅读?
文档反馈

[Offline]LiteLLM Proxy: 通过 OpenAI Client Wrapper 上报

更新于: 2026-06-24 15:45:09

本文介绍如何通过扣子罗盘的 OpenAI Client Wrapper 对接 LiteLLM Proxy 来调用 OpenAI 模型,并自动上报 Trace 数据到扣子罗盘。

说明

推荐你直接把 LiteLLM Proxy 的 Trace 数据上报到扣子罗盘。参见 LiteLLM Proxy

关于如何把 LiteLLM SDK 的 Trace 数据上报到扣子罗盘,参见 LiteLLM SDK

说明

本集成方案与 Low-Level 上报、注解上报完全兼容,能够无缝集成在同一 Trace 调用树中。例如本文的示例代码中,通过@observe注解,将注解上报和 OpenAI Client Wrapper 上报的 Trace 数据串联在同一 Trace 调用树中。

功能介绍

LiteLLM 是一款开源的、轻量级的大语言模型调用与管理工具。它提供了与 OpenAI API 兼容的统一接口,能够实现对数百家大语言模型提供商及旗下模型进行统一调用与管理。 OpenAI Client Wrapper 是扣子罗盘 SDK 提供的封装工具,它简化了与 OpenAI API 的交互。 开发者可以通过 OpenAI Client Wrapper 对接 LiteLLM Proxy 的 EndPoint 来调用 OpenAI 模型,并上报模型调用过程的 Trace 数据到扣子罗盘,完成可视化分析。

准备工作

  1. 安装依赖库。
    安装 Python 依赖库,分别用于调用 AI 模型、对调用过程进行可观测性管理以及将 Trace 数据导出到后端系统。

    pip install 'litellm[proxy]'
    pip install openai
    pip install cozeloop
    
  2. 配置 LiteLLM proxy。

    1. 创建 litellm_config.yaml 文件,配置模型参数
      本示例使用 Azure 模型厂商的 gpt-5-2025-08-07 模型,通过 LiteLLM proxy 统一转换为标准 OpenAI 数据结。你也可以使用 LiteLLM 支持的其他模型。

      • model:模型名称,需以模型厂商为前缀,例如 azure/gpt-5-2025-08-07
      • api_key :设置为 OpenAI 模型的 API Key。
      • api_base:设置为 OpenAI 模型的服务地址。
      model_list:
        - model_name: my-gpt-model
          litellm_params:
            model: azure/gpt-5-2025-08-07
            api_base: <azure-api-endpoint>
            api_key: <azure-api-key>
      
    2. 运行命令启动 LiteLLM proxy,LiteLLM proxy 将运行在 http://0.0.0.0:4000 端口。

      litellm --config litellm_config.yaml
      

配置环境变量

在上报 Trace 数据前,你需要正确配置环境变量 COZELOOP_API_TOKEN 和 COZELOOP_WORKSPACE_ID ,用于指定上报数据时所需的扣子罗盘访问令牌以及空间 ID,以确保数据能够正确发送到指定的扣子罗盘空间中。环境变量配置格式及说明如下:

环境变量

说明

COZELOOP_API_TOKEN

用于设置上报数据时所需的扣子罗盘认证信息,即配置为扣子罗盘的个人访问令牌或服务访问令牌。获取步骤,请参考配置个人访问令牌配置服务访问令牌

COZELOOP_WORKSPACE_ID

配置为扣子罗盘工作空间 ID。获取步骤,请参考获取扣子罗盘工作空间 ID

上报 Trace

在本示例中,通过扣子罗盘 SDK 提供的客户端封装器(OpenAI Client Wrapper)及 LiteLLM Proxy 来调用 OpenAI 模型完成问答。同时,借助 openai_wrapper 集成能力与 @observe 装饰器,扣子罗盘自动采集并上报模型调用、RAG 流程等过程中的 Trace 数据,从而实现对 AI 模型调用过程的全面监控和分析。

说明

本示例以 OpenAI chat 功能为例,如果需要使用 responses 接口,只需改为 responses.create 方法。

import os
from openai import OpenAI
from cozeloop import new_client
from cozeloop.decorator import observe
from cozeloop.integration.wrapper import openai_wrapper

# cozeloop client init env
os.environ["COZELOOP_WORKSPACE_ID"] = "your workspace id"
os.environ["COZELOOP_API_TOKEN"] = "your token"

# model env
base_url = os.environ.get('OPENAI_BASE_URL') or "http://0.0.0.0:4000"  # litellm proxy url
api_key = os.environ.get('OPENAI_API_KEY') or "anything" # anything, because we are using litellm proxy
model_name = os.environ.get('OPENAI_MODEL_NAME') or "my-gpt-model" # use model name you set in litellm proxy config

openai_client = openai_wrapper(OpenAI(
    base_url=base_url,
    api_key=api_key,
))


def retriever():
    results = ["John worked at Beijing"]
    return results


@observe
def rag(question):
    docs = retriever()
    system_message = """Answer the question using only the provided information below:

    {docs}""".format(docs="\n".join(docs))

    res = openai_client.chat.completions.create(    # chat completion
        messages=[
            {"role": "system", "content": system_message},
            {"role": "user", "content": question},
        ],
        model=model_name,
    )
    print(res)


if __name__ == '__main__':
    # Set environment variables first (Assuming you are using a PAT or SAT token.).
    # os.environ["COZELOOP_WORKSPACE_ID"] = "your workspace id"
    # os.environ["COZELOOP_API_TOKEN"] = "your token"

    client = new_client()
    rag("Where is John worked?")
    client.flush()

查看 Trace 数据

上报 Trace 数据后,你可以在扣子罗盘Trace 页面,找到并单击目标 Span,查看上报的 Trace 数据。
Image

更多示例

关于上报 LiteLLM Proxy Trace 数据的更多示例,请参考 LiteLLM Proxy