扣子 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 协议将 CrewAI 运行过程的 Trace 数据自动上报到扣子罗盘。

功能介绍 {#bf8f246f}

CrewAI 是一个用于自主编排 AI 应用的框架，通过与 OpenTelemetry 集成，能够自动捕获应用程序在调用大模型时的关键操作和性能指标，并将这些信息作为 Trace 数据上报到扣子罗盘，完成可视化分析。本集成方案适用于需要监控 CrewAI 调用大模型的过程、分析 AI 应用性能或排查 Agent 执行问题的场景。 本文以 Python SDK 为例，介绍如何通过 OpenTelemetry SDK 将应用程序的 Trace 数据上报至扣子罗盘平台，从而实现对应用程序性能和行为的高效监控与分析。

准备工作 {#b6f8ffe4}

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

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

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

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

   pip install openai
   pip install opentelemetry-sdk
   pip install opentelemetry-exporter-otlp
   pip install openinference-instrumentation-crewai
   pip install openinference-instrumentation-litellm
   pip install crewai

配置环境变量 {#1d55a2b8}

在上报 Trace 数据前，你需要正确配置 OpenTelemetry 的环境变量，以确保 CrewAI 应用能够正常调用 OpenAI 模型，并能正确发送 Trace 数据到指定的扣子罗盘空间中。环境变量配置格式及说明如下：

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
OPENAI_BASE_URL=***
OPENAI_API_KEY=***

| | | \

环境变量	说明
OTEL_EXPORTER_OTLP_HEADERS	设置上报数据时所需的扣子罗盘认证信息和工作空间标识。包括如下参数：
	* cozeloop-workspace-id：配置为扣子罗盘工作空间 ID。获取步骤，请参考获取扣子罗盘工作空间 ID。
	* Authorization：配置为扣子罗盘的个人访问令牌或服务访问令牌。获取步骤，请参考配置个人访问令牌、配置服务访问令牌。
OTEL_EXPORTER_OTLP_TRACES_ENDPOINT	指定 OpenTelemetry Trace 数据的上报地址，固定为 https://api.coze.cn/v1/loop/opentelemetry/v1/traces。
OPENAI_BASE_URL	配置 OpenAI 模型的服务地址。
	* 推荐使用方舟模型，其 BASE_URL 固定为 https://ark.cn-beijing.volces.com/api/v3。
	* 使用其他 OpenAI 模型时，配置为其对应的 BASE_URL 即可。
OPENAI_API_KEY	配置 OpenAI 模型的 API Key。
	* 推荐使用方舟模型，其 API Key 获取步骤，请参考 API Key 管理。
	* 使用其他 OpenAI 模型时，配置为其对应的 API Key 即可。

上报 Trace {#c4789068}

完成上述配置后，你可以调用 OpenAI 模型开展 AI 对话，并通过 OpenTelemetry Python SDK 上报 Trace 数据到扣子罗盘。以下示例将分别展示自动上报 Trace 数据与上报自定义 Span 节点数据的具体实现方式。

自动上报 {#70858454}

在本示例中，使用 CrewAI 框架调用火山方舟的 doubao-1-5-vision-pro-32k-250115 模型完成 HTML 代码生成任务，并通过 OpenTelemetry SDK 自动收集和上报 OpenAI 模型执行过程中的 Trace 数据到扣子罗盘，包括 LLM 调用、Agent 执行过程、任务生命周期等数据，从而实现对 AI 模型调用过程的全面监控和分析。

import os
from opentelemetry import trace
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import (
    BatchSpanProcessor,
)
from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter

os.environ['OPENAI_BASE_URL'] = 'https://ark.cn-beijing.volces.com/api/v3' # use ark model url by default, refer: https://www.volcengine.com/docs/82379/1361424
os.environ['OPENAI_API_KEY'] = '***'  # 设置一个大模型的api key

os.environ["OTEL_EXPORTER_OTLP_ENDPOINT"] = "https://api.coze.cn/v1/loop/opentelemetry/v1/traces"
os.environ["OTEL_EXPORTER_OTLP_HEADERS"] = "cozeloop-workspace-id=***,Authorization=Bearer ***"

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__)

# OpenInference自动检测
from openinference.instrumentation.crewai import CrewAIInstrumentor
from openinference.instrumentation.litellm import LiteLLMInstrumentor

CrewAIInstrumentor().instrument(skip_dep_check=True)
LiteLLMInstrumentor().instrument()

from crewai import Agent, Task, Crew, LLM

llm = LLM(
    model="openai/doubao-1-5-vision-pro-32k-250115",  # 配置模型名，如果是openai协议的模型，以openai/为前缀
)

# 定义Agent，带有roles and goals
coder = Agent(
    role='软件工程师',
    goal='根据指令，写出优雅清晰的代码',
    backstory='对软件技术有敏锐观察力的高级程序员',
    llm=llm,
)

# 为Agent创建任务
task1 = Task(
    description="定义HTML，用于制作带有标题的简单网站 - 你好! CozeLoop monitors your CrewAI agent!",
    expected_output="清晰简洁的HTML代码",
    agent=coder
)

# 创建Crew实例
crew = Crew(
    agents=[coder],
    tasks=[task1],
)

# 设置自定义Span节点 root_span
with tracer.start_as_current_span("root_span") as span:
    span.set_attribute("cozeloop.span_type", "custom")
    
    # 启动 crewAI kickoff
    result = crew.kickoff()
    print(result)

上报自定义节点 {#cda12c06}

如果你需要上报自定义 Span 节点，可以使用 OpenTelemetry SDK 手动创建 Span 并上报。OpenTelemetry SDK 手动上报的节点数据支持和自动上报的节点数据串联，形成完整的 Trace 调用树。 自定义的 OpenTelemetry Span，attribute 和 event 规范需遵循 OpenTelemetry 字段映射。

# 设置自定义 Span 节点 root_span
with tracer.start_as_current_span("root_span") as span:
    span.set_attribute("cozeloop.span_type", "custom")
    
    # 启动 crewAI kickoff
    result = crew.kickoff()
    print(result)

查看 Trace {#5c7d2849}

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

更多示例 {#bf7f782f}

关于上报 CrewAI Trace 数据的更多示例，请参考 CrewAI。