AI 原生开放教材

外观

扣子 Coze 官方文档官方文档·中文原件 ↓

扣子 Coze 官方文档 ​

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.

本文介绍如何通过 OpenTelemetry Python SDK 上报 Trace 数据到扣子罗盘。

功能介绍 {#0220d907} ​

你可以使用各种语言的 OpenTelemetry SDK 将 Trace 数据上报到扣子罗盘。通过OpenTelemetry SDK 上报时，开发者需要直接在代码中引入 OpenTelemetry SDK 来创建和管理 Trace 数据（例如创建 Span、设置 Attribute、记录 Event 等）。 本文以 Python SDK 为例，介绍如何通过 OpenTelemetry SDK将应用程序的 Trace 数据上报至扣子罗盘平台，从而实现对应用程序性能和行为的高效监控与分析。

准备工作 {#3636e836} ​

使用 OpenTelemetry Python SDK 前，需要先安装 Python SDK 以及相关的依赖库。

  1. 安装 Python SDK。 Opentelemetry Python SDK 要求 Python 3.9 或以上版本。你可以通过如下方法查看 Python 版本 。

    Python
    # 查看 Python 版本   
python --version 
 
# 回显信息显示已安装 3.9.2 版本 
Python 3.9.2

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

    Python
    pip install openai
pip install opentelemetry-sdk
pip install opentelemetry-exporter-otlp

配置环境变量 {#3374bc77} ​

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

Python
OTEL_EXPORTER_OTLP_HEADERS=cozeloop-workspace-id={CozeLoop空间ID},Authorization=Bearer {个人访问令牌或服务访问令牌}
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=https://api.coze.cn/v1/loop/opentelemetry/v1/traces

| | | \

环境变量说明
OTEL_EXPORTER_OTLP_HEADERS用于设置上报数据时所需的扣子罗盘认证信息和工作空间标识。包括如下参数：
* cozeloop-workspace-id：配置为扣子罗盘工作空间 ID。获取空间 ID 的步骤，请参考获取扣子罗盘工作空间 ID。
* Authorization：配置为扣子罗盘的个人访问令牌或服务访问令牌，获取访问令牌的步骤，请参考配置个人访问令牌、配置服务访问令牌。
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT用于指定 OpenTelemetry 数据的上报地址，固定为 https://api.coze.cn/v1/loop/opentelemetry/v1/traces。

上报 Trace {#832fc71d} ​

完成上述配置后，你可以使用 OpenAI SDK 调用 AI 模型进行对话，并通过 OpenTelemetry Python SDK 上报 Trace 数据到扣子罗盘。本文以调用火山方舟的 doubao-1-5-vision-pro-32k-250115 模型为例，展示如何通过 OpenTelemetry 记录并上报调用 AI 模型过程中的各种信息，包括输入参数、输出结果、调用耗时等，从而实现对 AI 模型调用过程的全面监控和分析。 示例代码及重要字段说明如下：

  • api_key：火山方舟模型的 API Key。获取步骤，请参考API Key 管理。
  • model：火山方舟模型的 ID。获取步骤，请参考获取 Model ID。在调用火山方舟模型前，你需要先开通对应的模型。
  • call_model：Span 名称，请根据实际情况修改。
Python
client = OpenAI(api_key={填写你的API_KEY}, base_url="https://ark.cn-beijing.volces.com/api/v3")

otlp_exporter = OTLPSpanExporter(
    timeout=10,
)
trace.set_tracer_provider(TracerProvider())
trace.get_tracer_provider().add_span_processor(
    BatchSpanProcessor(otlp_exporter)
)
tracer = trace.get_tracer(__name__)

def call_model():
    model = "doubao-1-5-vision-pro-32k-250115"
    with tracer.start_as_current_span("call_model") as span:
        span.set_attribute("cozeloop.span_type", "model")
        span.set_attribute("session.id", "thread-1")
        span.set_attribute("user.id", "user-1")
        span.set_attribute("messaging.message.id", "message-1")
        span.set_attribute("error.message", "mock error")

        span.set_attribute("gen_ai.system", "ark")
        span.set_attribute("gen_ai.operation.name", "chat")
        span.set_attribute("gen_ai.request.model", model)
        span.set_attribute("llm.request.type", "chat")
        span.set_attribute("gen_ai.request.temperature", 0.6)

        messages = [
            {"role": "system", "content": "你是一个专业的沟通师，擅长解答科普知识，回答不要超过100个字."},
            {
                "role": "user",
                "content": "月球离地球有多远."
            }
        ]

        for i, message in enumerate(messages):
            span.set_attribute(f"gen_ai.prompt.{i}.content", str(message["content"]))
            span.set_attribute(f"gen_ai.prompt.{i}.role", str(message["role"]))

        completion = client.chat.completions.create(
            model=model,
            messages=messages
        )

        span.set_attribute("gen_ai.completion.0.content", str(completion.choices[0].message.content))
        span.set_attribute("gen_ai.completion.0.role", "assistant")
        span.set_attribute("gen_ai.usage.input_tokens", completion.usage.prompt_tokens)
        span.set_attribute("gen_ai.usage.output_tokens", completion.usage.completion_tokens)

        # little_span是span的子节点
        with tracer.start_as_current_span("after_call_model") as little_span:
            time.sleep(1) # 模拟一些操作
            little_span.set_attribute("process_result", "bad")
            little_span.add_event("exception", {
                "exception.message": "mock error message",
                "exception.stacktrace": "mock error stacktrace"
            })

        return completion

if __name__ == "__main__":
    call_model()

验证结果 {#6090b005} ​

OpenTelemetry Python SDK 上报 Trace 数据后，你可以在扣子罗盘的 Trace 页面，找到并单击目标 Span，查看上报的 Trace 数据。例如下图的 Trace 数据展示了模型交互全流程与详情：系统设定了一个专业沟通师、擅长科普的角色，当用户向大模型提问月球离地球有多远时 ，由ark 提供的doubao-1-5-vision-pro-32k-250115模型成功响应，涉及 279 个 Token，输出了详细科普内容。整个调用流程含 call_model（7.85 秒 ）及后续 after_call_model（1.00 秒 ）环节。 Image=700x377