助手
扣子 AI 帮助与支持
你好,我是 扣子 文档问答助手 🎉 你在阅读当前文档的过程中,无论对文档概念的解释,还是文档内容方面的疑问,都可以随时向我提问,我会全力为你解答
推荐问题
如何快速了解这个空间的核心内容?
有哪些近期更新的重点文档?
我应该从哪些文档开始阅读?
文档反馈

最佳实践

更新于: 2026-06-24 15:45:09

本教程以一个旅游助手为例,介绍如何使用 Go 集成扣子罗盘 SDK 实现对旅游助手的全链路追踪,从用户输入到模型响应的全过程。 在本教程中,你需要先在扣子罗盘控制台中编写 Prompt,并通过扣子罗盘 SDK 拉取 Prompt 并调用模型,然后就能在控制台中查看 SDK 上报的 Trace 数据。

步骤一:编写 Prompt

为了方便演示,本教程以扣子罗盘 Demo 空间中的旅行专家为例。
以下是旅行助手的 Prompt 示例。你也可以根据实际需求,开发一个 Prompt 并提交新版本,详情请参考开发提示词
Image

步骤二:上报数据

以下代码展示了如何使用扣子罗盘 实现完整的链路追踪,从用户输入到模型响应的全过程。

  1. 主流程(main):
    • 初始化 CozeLoop 客户端,启用 Prompt 追踪
    • 创建 root span 追踪整个请求链路
    • 获取并格式化旅行专家 Prompt
    • 调用大模型获取响应
    • 记录输出结果并完成追踪
  2. 模型调用(callLLM):
    • 创建专门的 Model Span
    • 配置火山引擎(VolcEngine)的模型调用参数
    • 记录完整的调用上下文:
      • 输入信息(提示词)
      • 模型配置(提供商、模型名称、参数)
      • Prompt 信息
      • 追踪模型响应和性能指标(Token 使用量)
package main

import (
    "context"
    "os"

    "github.com/coze-dev/cozeloop-go"
    "github.com/coze-dev/cozeloop-go/entity"
    "github.com/coze-dev/cozeloop-go/spec/tracespec"
    "github.com/volcengine/volcengine-go-sdk/service/arkruntime"
    "github.com/volcengine/volcengine-go-sdk/service/arkruntime/model"
    "github.com/volcengine/volcengine-go-sdk/volcengine"
)

var (
    // 初始化cozeloop client
    client, _ = cozeloop.NewClient(cozeloop.WithPromptTrace(true))
)

func main() {
    ctx := context.Background()
    // 准备用户输入
    input := map[string]any{"people_num": "2", "destination": "上海", "days_num": "5", "travel_theme": "自由行"}

    // 创建root span
    ctx, root := client.StartSpan(ctx, "旅行专家", "chain")
    root.SetInput(ctx, input)

    // 拉取Prompt
    prompt, err := client.GetPrompt(ctx, cozeloop.GetPromptParam{PromptKey: "CozeLoop_Travel_Master"})
    if err != nil {
       panic(err)
    }
    messages, err := client.PromptFormat(ctx, prompt, input)
    if err != nil {
       panic(err)
    }

    // 调用模型
    resp, err := callLLM(ctx, messages, prompt)
    if err != nil {
       panic(err)
    }

    root.SetOutput(ctx, *resp.Choices[0].Message.Content.StringValue)
    // root span上报
    root.Finish(ctx)

    // 服务退出前调用Close方法,否则可能造成trace数据丢失
    client.Close(ctx)
}

func callLLM(ctx context.Context, messages []*entity.Message, prompt *entity.Prompt) (*model.ChatCompletionResponse, error) {
    // 创建model span
    ctx, span := client.StartSpan(ctx, "CallLLM", "model")
    defer span.Finish(ctx)

    temperature := float32(0.7)
    maxTokens := 1000
    arkClient := arkruntime.NewClientWithApiKey(
       os.Getenv("ARK_API_KEY"),
    )
    req := model.CreateChatCompletionRequest{
       Model: "doubao-1-5-vision-pro-32k-250115",
       Messages: []*model.ChatCompletionMessage{
          {
             Role: model.ChatMessageRoleSystem,
             Content: &model.ChatCompletionMessageContent{
                StringValue: volcengine.String(*messages[0].Content),
             },
          },
       },
       Temperature: &temperature,
       MaxTokens: &maxTokens,
    }
    span.SetInput(ctx, map[string]interface{}{"messages": req.Messages})
    span.SetModelProvider(ctx, "volcengine")
    span.SetModelName(ctx, req.Model)
    span.SetModelCallOptions(ctx, tracespec.ModelCallOption{
       Temperature: temperature,  
       MaxTokens: int64(maxTokens),
    })
    span.SetPrompt(ctx, *prompt)

    // 调用模型
    resp, err := arkClient.CreateChatCompletion(ctx, req)
    if err != nil {
       span.SetError(ctx, err)
       return nil, err
    }

    span.SetOutput(ctx, resp)
    span.SetInputTokens(ctx, resp.Usage.PromptTokens)
    span.SetOutputTokens(ctx, resp.Usage.CompletionTokens)

    return &resp, nil
}

步骤三:查看 Trace 数据

在完成数据上报后,就可以在扣子罗盘 的观测页面查看 SDK 上报的 Trace 数据了。
Image