> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

本文介绍如何通过扣子罗盘的 OpenAI Client Wrapper 对接 [LiteLLM Proxy](https://docs.litellm.ai/docs/proxy/quick_start#quick-start---litellm-proxy--configyaml) 来调用 OpenAI 模型，并自动上报 Trace 数据到扣子罗盘。
:::tip 说明
推荐你直接把 LiteLLM Proxy 的 Trace 数据上报到扣子罗盘。参见 [LiteLLM Proxy](/cozeloop/litellm_proxy_native_trace_report)。
:::
关于如何把 LiteLLM SDK 的 Trace 数据上报到扣子罗盘，参见 [LiteLLM SDK](/cozeloop/litellm_sdk_trace_report)。
:::tip 说明
本集成方案与 Low-Level 上报、注解上报完全兼容，能够无缝集成在同一 Trace 调用树中。例如本文的示例代码中，通过`@observe`注解，将注解上报和  OpenAI Client Wrapper 上报的 Trace 数据串联在同一 Trace 调用树中。
:::
## 功能介绍 {#3669a46e}
[LiteLLM](https://docs.litellm.ai/docs/) 是一款开源的、轻量级的大语言模型调用与管理工具。它提供了与 OpenAI API 兼容的统一接口，能够实现对数百家大语言模型提供商及旗下模型进行统一调用与管理。 OpenAI Client Wrapper  是扣子罗盘 SDK 提供的封装工具，它简化了与 OpenAI API 的交互。 开发者可以通过 OpenAI Client Wrapper 对接 LiteLLM Proxy 的 EndPoint 来调用 OpenAI 模型，并上报模型调用过程的 Trace 数据到扣子罗盘，完成可视化分析。
## 准备工作 {#cdc682f3}

1. 安装依赖库。
   安装 Python 依赖库，分别用于调用 AI 模型、对调用过程进行可观测性管理以及将 Trace 数据导出到后端系统。 
   ```Python
   pip install 'litellm[proxy]'
   pip install openai
   pip install cozeloop
   ```

2. 配置 LiteLLM proxy。
   1. 创建 `litellm_config.yaml` 文件，配置[模型参数](https://litellm.vercel.app/docs/proxy/configs)。
      本示例使用 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 模型的服务地址。
      ```Plain Text
      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` 端口。
      ```JSON
      litellm --config litellm_config.yaml
      ```


## 配置环境变量  {#d3585237}
在上报 Trace 数据前，你需要正确配置环境变量 COZELOOP_API_TOKEN 和 COZELOOP_WORKSPACE_ID ，用于指定上报数据时所需的扣子罗盘访问令牌以及空间 ID，以确保数据能够正确发送到指定的扣子罗盘空间中。环境变量配置格式及说明如下：
<!-- @cols-width: 246,595 -->
| | | \
|**环境变量** |**说明** |
|---|---|
| | | \
|COZELOOP_API_TOKEN  |用于设置上报数据时所需的扣子罗盘认证信息，即配置为扣子罗盘的个人访问令牌或服务访问令牌。获取步骤，请参考[配置个人访问令牌](/cozeloop/authentication-for-sdk#05d27a86)、[配置服务访问令牌](/cozeloop/authentication-for-sdk#83f924a1)。 |
| | | \
|COZELOOP_WORKSPACE_ID  |配置为扣子罗盘工作空间 ID。获取步骤，请参考[获取扣子罗盘工作空间 ID](/cozeloop/get_workspace_id_and_token#01dede13)。 |

## 上报 Trace {#d05e7e17}
在本示例中，通过扣子罗盘 SDK 提供的客户端封装器（OpenAI Client Wrapper）及 LiteLLM Proxy 来调用 OpenAI 模型完成问答。同时，借助 `openai_wrapper` 集成能力与 `@observe` 装饰器，扣子罗盘自动采集并上报模型调用、RAG 流程等过程中的 Trace 数据，从而实现对 AI 模型调用过程的全面监控和分析。
:::tip 说明
本示例以 OpenAI chat 功能为例，如果需要使用 responses 接口，只需改为 `responses.create` 方法。
:::
```Python
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 数据 {#99a6de36}
上报 Trace 数据后，你可以在[扣子罗盘](https://loop.coze.cn/)的 **Trace** 页面，找到并单击目标 Span，查看上报的 Trace 数据。
![Image=722x366](https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/4b5c7e6b513a48f496ce12b96687e093~tplv-goo7wpa0wc-image.image)
## 更多示例 {#33b7d128}
关于上报 LiteLLM Proxy Trace 数据的更多示例，请参考 [LiteLLM Proxy](https://github.com/coze-dev/cozeloop-examples/tree/main/python/integration/framework/litellm_proxy)。