LiteLLM 是一款开源的、轻量级的大语言模型调用与管理工具。它提供了与 OpenAI API 兼容的统一接口，使你可以统一调用和管理来自数百家供应商的 LLM。LiteLLM 提供了 LiteLLM SDK 和 LiteLLM Proxy。本文仅介绍如何上报 LiteLLM Proxy 的 Trace 数据。关于如何把 LiteLLM SDK 的 Trace 数据上报到扣子罗盘，参见 LiteLLM SDK。

准备工作

你需要先安装以下 Python 库。

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

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

操作步骤

步骤一：配置并启动 LiteLLM Proxy

创建配置文件。

创建 litellm_config.yaml，配置模型参数。本示例以 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 监控功能。

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"]

配置环境变量。

你必须在启动 LiteLLM Proxy 的环境中配置以下环境变量，以便在启动时配置 OpenTelemetry Trace。

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"

环境变量	说明
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。 Authorization：用于设置上报数据时所需的扣子罗盘认证信息，配置为扣子罗盘的个人访问令牌或服务访问令牌，获取访问令牌的步骤，请参考获取扣子罗盘访问令牌。格式为：`Bearer {个人访问令牌或服务访问令牌}`

环境变量

说明

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。
Authorization：用于设置上报数据时所需的扣子罗盘认证信息，配置为扣子罗盘的个人访问令牌或服务访问令牌，获取访问令牌的步骤，请参考获取扣子罗盘访问令牌。格式为：Bearer {个人访问令牌或服务访问令牌}

启动 Proxy。

运行以下命令启动 LiteLLM proxy，该服务在本地将运行在 http://0.0.0.0:4000。

litellm --config litellm_config.yaml

步骤二：上报 Trace

这里以 OpenAI Chat Completions API 为例，调用已启动的 LiteLLM Proxy。

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?")

步骤三：验证结果

上报 Trace 数据后，你可以在扣子罗盘的 Trace 页面，找到并查看 Agent 上报的 Trace 数据。

示例地址

要获取上报 Trace 数据的完整示例代码，参考 litellm_proxy(proxy)。

OpenAI Chat & Responses