> ## 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.

本文介绍如何把 LiteLLM Proxy 的 Trace 数据上报到扣子罗盘。
# 功能介绍 {#feature_intro}
[LiteLLM](https://docs.litellm.ai/docs/) 是一款开源的、轻量级的大语言模型调用与管理工具。它提供了与 OpenAI API 兼容的统一接口，使你可以统一调用和管理来自数百家供应商的 LLM。LiteLLM 提供了 LiteLLM SDK 和 LiteLLM Proxy。本文仅介绍如何上报 LiteLLM Proxy 的 Trace 数据。关于如何把 LiteLLM SDK 的 Trace 数据上报到扣子罗盘，参见 [LiteLLM SDK](/cozeloop/litellm_sdk_trace_report)。
# 准备工作 {#preparation}
你需要先安装以下 Python 库。

* **openai**：OpenAI Python SDK，用于调用所有符合 OpenAI API 标准协议的 LLM。
* **litellm[proxy]**：对调用过程进行追踪以及将 Trace 数据导出到后端系统。

```Python
pip install openai
pip install 'litellm[proxy]'==1.80.5 # 为了模型节点友好渲染，建议litellm版本<=1.80.5
```

# 操作步骤 {#fe212827}
## 步骤一：配置并启动 LiteLLM Proxy {#step1}

1. 创建配置文件。

创建 `litellm_config.yaml`，配置 [模型参数](https://litellm.vercel.app/docs/proxy/configs)。本示例以 Azure 的 `gpt-5-2025-08-07` 模型为例，LiteLLM Proxy 会将其统一转换为标准的 OpenAI 数据结构。你也可以使用其他 LiteLLM 支持的模型。
对于本示例中的配置文件，确保完成以下操作：

* 将 `<azure-api-key>` 替换为你的真实 Azure OpenAI API key。
* 将 `<azure-api-endpoint>` 替换为你的真实 Azure Endpoint。
* 确保 `model` 字段以模型厂商为前缀（例如本例中的 `azure`）。
* 确保 `callbacks` 字段包括 `"otel"`，启用 LiteLLM Proxy 的 OpenTelemetry 监控功能。

```YAML
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>
      
litellm_settings:
  callbacks: ["otel"]
```


2. 配置环境变量。

你必须在启动 LiteLLM Proxy 的环境中配置以下环境变量，以便在启动时配置 OpenTelemetry Trace。
```Bash
export OTEL_EXPORTER="otlp_http"
export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT="https://api.coze.cn/v1/loop/opentelemetry/v1/traces"
export OTEL_EXPORTER_OTLP_TRACES_HEADERS="cozeloop-workspace-id={your cozeloop workspace id},Authorization=Bearer pat_xxx"
```

<!-- @cols-width: 280,595 -->
| | | \
|**环境变量** |**说明** |
|---|---|
| | | \
|OTEL_EXPORTER |固定设置为 `otlp_http`。 |
| | | \
|OTEL_EXPORTER_OTLP_TRACES_ENDPOINT |固定设置为 `https://api.coze.cn/v1/loop/opentelemetry/v1/traces`。 |
| | | \
|OTEL_EXPORTER_OTLP_TRACES_HEADERS |OpenTelemetry SDK 数据上报的认证头信息。形如：`cozeloop-workspace-id={your cozeloop workspace id},Authorization=Bearer pat_xxx` |\
| | |\
| |* **cozeloop-workspace-id**：配置为扣子罗盘工作空间 ID。获取空间 ID 的步骤，请参考[获取扣子罗盘工作空间 ID](https://loop.coze.cn/open/docs/cozeloop/opentelemetry_sdk_trace_report#44f141a8)。 |\
| |* **Authorization**：用于设置上报数据时所需的扣子罗盘认证信息，配置为扣子罗盘的个人访问令牌或服务访问令牌，获取访问令牌的步骤，请参考[获取扣子罗盘访问令牌](https://loop.coze.cn/open/docs/cozeloop/opentelemetry_sdk_trace_report#bec3736a)。 格式为：`Bearer {个人访问令牌或服务访问令牌}` |


3. 启动 Proxy。

运行以下命令启动 LiteLLM proxy，该服务在本地将运行在 http://0.0.0.0:4000。
```Bash
litellm --config litellm_config.yaml
```

## 步骤二：上报 Trace {#step2}
这里以 OpenAI Chat Completions API 为例，调用已启动的 LiteLLM Proxy。
```Python
import os
from openai import OpenAI

# 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(
    base_url=base_url,
    api_key=api_key,
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather in a given location",
            "parameters": {
                "type": "object",
                "properties": {
                    "location": {
                        "type": "string",
                        "description": "The city and state, e.g. San Francisco, CA",
                    },
                    "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]},
                },
                "required": ["location", "unit"],
            }
        }
    }
]


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


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,
        tools=tools,
    )
    print(res)


if __name__ == '__main__':
    rag("Where is John worked?")
```

## 步骤三：验证结果 {#73a00648}
上报 Trace 数据后，你可以在[扣子罗盘](https://loop.coze.cn/)的 **Trace** 页面，找到并查看 Agent 上报的 Trace 数据。
<div style="text-align: center"><img src="https://p9-arcosite.byteimg.com/tos-cn-i-goo7wpa0wc/8346558c8d2d44bc8bc7da4db10220e0~tplv-goo7wpa0wc-image.image" width="3012px" height="1650px" /></div>

# 示例地址 {#b40e14c1}
要获取上报 Trace 数据的完整示例代码，参考 [litellm_proxy(proxy)](https://github.com/coze-dev/cozeloop-examples/tree/main/python/integration/framework/litellm_proxy(proxy))。