扣子罗盘（Coze Loop）开源版本地部署，构建一站式AI Agent调试、评估、监控平台

扣子罗盘（Coze Loop） 是由字节跳动开发的一款专注于 AI Agent 全生命周期管理的平台级工具，旨在解决 AI 应用开发中调试难、评估主观、线上问题定位低效等痛点。其核心定位是为开发者提供从开发、测试到运维的闭环支持。

一、Coze Loop 的能干什么？

1. Prompt 开发

• • 扣子罗盘的 Prompt 开发模块为开发者提供了从编写、调试、优化到版本管理的全流程支持，通过可视化 Playground 实现 Prompt 的实时交互测试，让开发者能够直观比较不同大语言模型的输出效果
• • 扣子罗盘内置了智能调优能力，结合 AI 和评估反馈，帮助开发者持续优化 Prompt。
• • 版本管理功能完整记录了 Prompt 的迭代历史，支持版本比对和快速回滚，确保开发过程的可控性和可追溯性

2. 评测

• • 扣子罗盘评测模块为开发者提供系统化的评测能力，能够对 Prompt 和扣子智能体的输出效果进行多维度自动化检测，例如准确性、简洁性和合规性等。
• • 扣子罗盘支持快速构建评测数据集，通过预置评估规则，实现从输入到输出的端到端质量验证。
• • 通过内置的大模型评估器模板，扣子罗盘观测既能满足快速验证需求，也能适应复杂场景的深度评测

3. 观测(Trace)

• • 扣子罗盘为开发者提供了全链路执行过程的可视化观测能力，完整记录从用户输入到 AI 输出的每个处理环节，包括 Prompt 解析、模型调用和工具执行等关键节点，并自动捕获中间结果和异常状态
• • 通过精准定位错误发生环节、分析各环节耗时以识别性能瓶颈、自动统计 Token 消耗，扣子罗盘观测帮助开发者快速定位和修复问题
• • 扣子罗盘观测支持与 Eino、Langchain 等主流框架的集成，提供 SDK 用于 Trace 数据上报，并支持平台提示词（Prompt）、扣子智能体和扣子 AI 应用数据的自动上报

二、Coze Loop 开源版和云端版本的区别

Coze Loop分为cloud版和开源版本，cloud版提供云端服务，开源版提供本地部署能力。到底开源版本的体验如何，和cloud版有什么区别呢？我从本地部署和实战操作得出以下结论：

三、Coze Loop 本地部署

扣子罗盘开源版提供了Docker compose，用户可以通过Docker compose进行本地部署。
如果是windows用户，建议使用WSL平台进行部署，我试过直接在Windows上 的docker进行部署，但构建镜像过程就有一些坑，后面解决后，结果是docker compose启动后有些容器总是报一些莫名的错误，不想折腾，直接上WSL部署了。

以下是WSL本地部署的步骤：

1. 准备工作

• • GO 环境：已安装 Go，且版本为 1.23.4 及以上版本。
• • Docker 环境：提前安装 Docker、Docker Compose，并启动 Docker 服务
• • 模型：已开通 OpenAI 或火山方舟等在线模型服务

2. 拉取源码

执行以下命令，获取 Coze Loop 最新版本的源码。

# 克隆代码 
git clone https://github.com/coze-dev/coze-loop.git

# 进入coze-loop目录下
cd coze-loop

3. 配置模型

正式安装 Coze Loop 开源版之前，你需要准备可选的模型，否则访问 Coze Loop 开源版时将无法选择模型来启动 Prompt 调试或评测。
目前支持的模型有：

• • Ark/ArkBot （火山方舟）
• • OpenAI
• • DeepSeek
• • Claude
• • Gemini
• • Ollama
• • Qwen
• • Qianfan

此处以火山方舟模型为例，演示配置模型文件的操作步骤

(1) 进入目录 conf/default/app/runtime/。
编辑文件 model_config.yaml，修改 api_key 和 model 字段。

4. 启动 Coze Loop

执行以下命令，使用 Docker Compose 拉取构建 Coze Loop 开源版镜像并启动容器。

# 启动服务，默认为开发模式
docker compose up --build

拉取构建镜像时间会比较长，请耐心等待。

容器启动成功后，会显示以下信息：

启动的容器有：

5. 访问 Coze Loop

浏览器访问 http://localhost:8082/ ，即可进入 Coze Loop 开源版。

输入初始账号密码，点击注册即可完成注册并进入 Coze Loop 开源版。
主界面如下：

可以看到Prompt工程、评测、观测三个核心模块都有

对比一下云端版的主页：

显然开源版的界面简化了不少

四、Coze Loop 功能探索

1. Prompt工程

Prompt工程是Coze Loop开源版核心的功能，用户可以在这里创建、管理、调试 Prompt。

下面以一个简单的“客服对话情感评估” 提示词为例，演示如何使用 Coze Loop 开源版进行 Prompt 调试。

创建 Prompt后，进行详情页，输入提示词后就可以进行调试：

可以观察到，Coze Loop 开源版支持配置模型和调试参数，直接运行，并查看结果。

但是开源版少了一个重要的功能，就是提示词的快捷优化功能，这是云端版的界面，多个一个快捷优化的按钮，可以对提示词使用大模型进行自动优化：

除此之外，开源版也支持版本记录管理，调试记录查看，还有自由对比模式，可以对比和参照多个 Prompt 的调试结果 ，如下：

总的来说，开源版功能相对完整，但缺少了提示示快捷优化的功能，虽然提示词的优化功能也可以通过使用其它免费大模型进行，但需要用户手动进行，比较麻烦。

2. 评测

评测功能是 Coze Loop 开源版的核心的功能，用户可以在这里创建、管理、执行评测任务。
Coze Loop 评测功能分为三个模块：

• • 第一是先创建评测集
• • 第二是创建评估器
• • 第三是执行评测实验

创建评测集

支持手工添加评测数据集，也可以从csv文件中导入生成评测数据集。
创建成功如下：

这个开源版和云版本没有什么不同

创建评估器

评估器其实就是选择一个大模型和提示词，然后生成一个评估器，提示词内置了一些常用评估场景的模板，可以自行修改。
如下：

开源版本和云版本主要的不同就是云端版本可以选择的提示词模板更多

创建实验

创建实验就是选择一个评测集和一个评估器，然后再选择一个评测对象，最后生成一个可执行的实验，执行结果就是对评测集的评估结果。
这里最大的不同就是开源版只能选择Prompt做为评测对象，但云端版本可以选择Prompt、Coze智能体、Coze工作流做为评测对象，说明云端版本的Coze studio和Coze Loop数据都是打通的，但目前开源版本还未打通.

开源版本的评测对象选择：

云端版本的评测对象选择：

配置完成后发起实验：

实验结果：
列出的实验结果明细

指标统计：
支持各种聚合的指标统计

总的来说，除了评测对象目前只能选Prompt，其他功能都还算完善。

3. 观测（Trace）

观测功能支持查看模型调用的trace信息，开源版本目前只支持Prompt开发和SDK上报。开源版本如下：

云端版本则跟Coze云端版本打通，Coze 云端的调用会自动上报到Coze Loop的观测功能，并且云端版本还多了统计、自动化任务评测的功能。云端版本界面如下：

1、Prompt开发

就是进行Prompt开发过程的调试调用会自动上报到Trace中，可以直接查看

2、SDK上报

使用Coze Loop SDK上报的调用，需要在AI Agent应用代码手动上报到Trace中，然后才能查看
Coze Loop 提供多语言 SDK（Go、Python 和 Node.js），支持开发者通过标准化接口集成 Trace 数据上报。Coze Loop SDK 支持 PAT（个人访问令牌）鉴权，确保与Coze Loop服务的安全高效交互。

Coze Loop SDK
Coze Loop SDK 支持集成 Eino 和 Langchain 框架，快速实现 AI 应用的接入和数据上报。同时，也支持通过使用 Coze Loop的 API 以更加灵活的方式进行数据上报。

Coze Loop 三个语言的 SDK 均适用于商业版和开源版。对于开源版，开发者只需要初始化时修改以下环境变量配置：

1、COZELOOP_API_BASE_URL：
Coze Loop开源版部署的后端地址：http://localhost:8888

2、COZELOOP_WORKSPACE_ID：
Coze Loop开源版中已创建的空间 ID。
可以在URL地址获取，如：http://localhost:8082/console/enterprise/personal/space/7532054799722741761/pe/prompts
WorkspaceId为7532054799722741761

3、COZELOOP_API_TOKEN
Coze Loop开源版中生成的个人令牌
在账户-API授权中创建：

4. LangGraph调用Coze Loop SDK进行Trace上报

下面就以LangGraph 为例，调用Coze Loop SDK进行Trace的上报,调用代码如下面：

import cozeloop
from cozeloop.integration.langchain.trace_callback import LoopTracer

from langchain_core.runnables import RunnableConfig
from langchain_deepseek import ChatDeepSeek
from langgraph.prebuilt import create_react_agent
from langchain_core.tools import  tool

from dotenv import load_dotenv  # 用于加载环境变量
# 加载 .env 文件中的环境变量
# 配置CozeLoop环境变量
#COZELOOP_API_TOKEN=
#COZELOOP_WORKSPACE_ID=
#COZELOOP_API_BASE_URL=http://localhost:8888
load_dotenv()  


@tool
defget_weather(city_name: str) -> str:
    """根据城市名称查询天气"""
    # 模拟天气数据返回
    returnf"{city_name}的天气是晴天，温度为22度，湿度65%"


# 创建cozeloop client
client = cozeloop.new_client()
# 注册callback
trace_callback_handler = LoopTracer.get_callback_handler(client)

llm_model = ChatDeepSeek(model="deepseek-chat")
llm_model = llm_model.bind_tools(tools=[get_weather])

agent = create_react_agent(llm_model, [get_weather])
output = agent.invoke(
    {"messages": "帮我查询一下北京的天气"},
    RunnableConfig(callbacks=[trace_callback_handler]),
)

print(output)

# 程序退出前，需要调用Close方法，否则可能造成trace数据上报丢失。Close后无法再执行任何操作。
client.close()

执行以上代码上报成功后，可以在Coze Loop 查看数据Trace信息：

可以看到大模型链路的基本信息有打印出来，但是并没有显示完整的大模型输出参数，用过LangSmith的就知道，LangSmith 的trace信息会更加完整和细致，包括了大模型的完整输出参数，以及大模型调用的工具信息。以下是同样调用LangSmith的Trace信息：