SDK/Python SDK/最佳实践
最佳实践
更新于: 2026-06-24 15:45:09
本教程以一个旅游助手为例,介绍如何使用 Python 集成扣子罗盘 SDK 实现对旅游助手的全链路追踪,从用户输入到模型响应的全过程。 在本教程中,你需要先在扣子罗盘控制台中编写 Prompt,并通过扣子罗盘 SDK 拉取 Prompt 并调用模型,然后就能在控制台中查看 SDK 上报的 Trace 数据。
为了方便演示,本教程以 CozeLoop Demo 空间中的旅行专家为例。
以下是旅行助手的 Prompt 示例。你也可以根据实际需求,开发一个 Prompt 并提交版本,详情请参考开发提示词。
以下代码展示了如何使用扣子罗盘实现完整的链路追踪,从用户输入到模型响应的全过程。
import os
import cozeloop
from cozeloop.spec import tracespec
from openai import OpenAI
from openai.types.chat import ChatCompletionSystemMessageParam
def main():
# 初始化cozeloop client
client = cozeloop.new_client(prompt_trace=True)
# 准备用户输入
input = {"people_num": "2", "destination": "上海", "days_num": "5", "travel_theme": "自由行"}
# 创建root span
root = cozeloop.start_span("旅行专家", "chain")
root.set_input(input)
try:
# 拉取Prompt
prompt = client.get_prompt(prompt_key="CozeLoop_Travel_Master")
cozeloop_messages = client.prompt_format(prompt, input)
messages = [
ChatCompletionSystemMessageParam(
role="system",
content=cozeloop_messages[0].content
)
]
# 调用大模型
response = call_llm(
messages=messages,
prompt=prompt,
)
# 处理最终结果
final_output = response.choices[0].message.content
root.set_output(final_output)
finally:
# root span 上报
root.finish()
# 服务退出前调用Close方法,否则可能造成trace数据丢失
client.close()
def call_llm(messages, prompt):
# 创建model span
model_span = cozeloop.start_span("CallLLM", "model")
ark_client = OpenAI(
base_url="https://ark.cn-beijing.volces.com/api/v3",
api_key=os.environ.get("OPENAI_API_KEY")
)
temperature = 0.7
max_tokens = 1000
try:
# 设置模型参数
model_span.set_input({"messages": messages})
model_span.set_model_provider("volcengine")
model_span.set_model_name("doubao-1-5-vision-pro-32k-250115")
model_span.set_model_call_options(tracespec.ModelCallOption(
temperature=temperature,
max_tokens=max_tokens
))
model_span.set_prompt(prompt=prompt)
# 执行模型调用
response = ark_client.chat.completions.create(
model="doubao-1-5-vision-pro-32k-250115",
messages=messages,
temperature=temperature,
max_tokens=max_tokens
)
model_span.set_output(response)
model_span.set_input_tokens(response.usage.prompt_tokens)
model_span.set_output_tokens(response.usage.completion_tokens)
return response
except Exception as e:
model_span.set_error(e)
raise
finally:
model_span.finish()
if __name__ == '__main__':
main()
在完成数据上报后,就可以在扣子罗盘的观测页面查看 SDK 上报的 Trace 数据了。