本文介绍如何使用 Coze Loop SDK 将 Instructor 的 Trace 数据自动上报到扣子罗盘。
Instructor 是一个基于 Pydantic 的库,旨在简化 LLM 的结构化数据提取。结合 Coze Loop SDK,你可以全面追踪 Instructor 的数据提取过程。Trace 数据将被上报至扣子罗盘,实现完整的可观测性监控。
你需要先安装以下 Python 库:
pip install instructor
pip install openai
pip install pydantic
pip install cozeloop
在上报 Trace 数据前,你需要正确配置环境变量,以确保 Trace 数据能够正确发送到指定的扣子罗盘空间中。环境变量配置格式及说明如下:
COZELOOP_API_TOKEN=***
COZELOOP_WORKSPACE_ID=***
OPENAI_BASE_URL=***
OPENAI_API_KEY=***
OPENAI_MODEL_NAME=***
|
环境变量 |
说明 |
|---|---|
|
COZELOOP_API_TOKEN |
用于设置上报数据时所需的扣子罗盘认证信息,配置为扣子罗盘的个人访问令牌或服务访问令牌,获取方法参考配置个人访问令牌或配置服务访问令牌。 |
|
COZELOOP_WORKSPACE_ID |
配置为扣子罗盘工作空间 ID。获取方法参考获取扣子罗盘空间 ID。 |
|
OPENAI_BASE_URL |
配置 OpenAI 模型服务的 Base URL。推荐使用火山方舟模型服务: |
|
OPENAI_API_KEY |
配置 OpenAI 模型服务的 API Key。如果使用火山方舟模型,请参考 获取 API Key。 |
|
OPENAI_MODEL_NAME |
模型名称,例如 |
你可以使用 Coze Loop SDK 将 Trace 数据上报至扣子罗盘。
下方的示例代码演示如何通过 Coze Loop SDK 追踪 Instructor 的运行状态并将 Trace 数据上报到扣子罗盘。openai_wrapper 是 Coze Loop SDK 提供的封装库,用于简化与 OpenAI API 的交互。你可以通过 openai_wrapper 来调用符合 OpenAI API 标准协议的 LLM,并上报 LLM 调用过程的 Trace 数据到扣子罗盘。
import os
from pydantic import BaseModel
from openai import OpenAI
import instructor
from cozeloop import new_client
from cozeloop.decorator import observe
from cozeloop.integration.wrapper import openai_wrapper
# OpenAI env
os.environ['OPENAI_BASE_URL'] = 'https://ark.cn-beijing.volces.com/api/v3' # use ark model url by default, from https://www.volcengine.com/docs/82379/1361424
os.environ['OPENAI_API_KEY'] = '***' # your api key
os.environ['OPENAI_MODEL_NAME'] = '***' # your model name, like doubao-1-5-vision-pro-32k-250115
# cozeloop client init
# Set the following environment variables first:
# os.environ["COZELOOP_WORKSPACE_ID"] = "your workspace id"
# os.environ["COZELOOP_API_TOKEN"] = "your pat or sat token"
cozeloop_client = new_client()
# Wrap OpenAI client with cozeloop's openai_wrapper to enable tracing.
# This ensures that LLM calls are captured by cozeloop.
# Then patch the wrapped client with instructor for structured data extraction.
patched_openai_client = openai_wrapper(OpenAI(
api_key=os.environ.get('OPENAI_API_KEY'),
base_url=os.environ.get('OPENAI_BASE_URL'),
))
client = instructor.patch(patched_openai_client)
class UserDetail(BaseModel):
name: str
age: int
@observe(span_type="workflow") # Customizing the span type
def extract_user_info(text: str):
"""
This function is decorated with @observe, which creates a span in cozeloop.
The nested LLM call via 'client.chat.completions.create' will be captured
by the 'openai_wrapper' and associated with this span.
"""
user = client.chat.completions.create(
model=os.environ.get('OPENAI_MODEL_NAME'),
response_model=UserDetail,
messages=[
{"role": "user", "content": text},
],
)
return user
def main():
# Example of a manual root span for even more control over the trace hierarchy.
with cozeloop_client.start_span("Instructor_Root_Process", "root") as root_span:
input_text = "Jason is 25 years old"
root_span.set_input(input_text)
print(f"Extracting info from: {input_text}")
user_info = extract_user_info(input_text)
print(f"Extracted info: {user_info}")
root_span.set_output(user_info.model_dump_json())
# Ensure all spans are sent to cozeloop
cozeloop_client.flush()
if __name__ == "__main__":
main()
Coze Loop SDK 的 openai_wrapper 会自动生成 Span。同时,你也可以使用 Coze Loop SDK 自定义 Span。
示例代码演示了如何使用 Coze Loop SDK 自定义 Span。Coze Loop SDK 自动生成的 Span 会与你自定义的 Span 自动关联,并显示在同一条 Trace 中。示例代码中使用了以下方式自定义 Span:
@observe注解自定义了类型为 workflow 的 Span。@observe注解所对应的方法中包含的 LLM 调用会与这个自定义 Span 关联。cozeloop_client.start_span() 手动创建一个自定义 Span 作为 Root Span。@observe(span_type="workflow") # Customizing the span type
def extract_user_info(text: str):
"""
This function is decorated with @observe, which creates a span in cozeloop.
The nested LLM call via 'client.chat.completions.create' will be captured
by the 'openai_wrapper' and associated with this span.
"""
user = client.chat.completions.create(
model=os.environ.get('OPENAI_MODEL_NAME'),
response_model=UserDetail,
messages=[
{"role": "user", "content": text},
],
)
return user
def main():
# Example of a manual root span for even more control over the trace hierarchy.
with cozeloop_client.start_span("Instructor_Root_Process", "root") as root_span:
input_text = "Jason is 25 years old"
root_span.set_input(input_text)
print(f"Extracting info from: {input_text}")
user_info = extract_user_info(input_text)
print(f"Extracted info: {user_info}")
root_span.set_output(user_info.model_dump_json())
# Ensure all spans are sent to cozeloop
cozeloop_client.flush()
上报 Trace 数据后,你可以在扣子罗盘的 Trace 页面,找到并查看 Instructor 上报的 Trace 数据。
要获取上报 Trace 数据的完整示例代码,参考 instructor。