CozeLoop：优化AI智能体开发与运维的开源平台

CozeLoop 是字节跳动开源的 AI 智能体优化平台，基于 Apache 2.0 许可，免费商用。它专注于 AI 智能体的全生命周期管理，涵盖提示词开发、调试、评估和运行监控。平台提供可视化工具，支持开发者快速优化智能体性能，解决开发中的复杂问题。后端使用 Golang 开发，前端基于 TypeScript 和 React，架构高效且易于扩展。CozeLoop 支持多语言 SDK（如 Python、Go、JavaScript），便于集成本地系统。它降低 AI 开发与运维门槛，适合企业和开发者构建高性能 AI 应用，鼓励社区协作。

功能列表

• 提示词开发与调试 ：通过可视化 Playground 实时测试和优化提示词，支持多模型对比。
• 自动化评估 ：管理评估数据集和评估器，自动测试智能体的准确性与合规性。
• 运行监控 ：记录智能体执行全链路数据，实时监控关键节点和异常状态。
• 全生命周期管理 ：支持智能体从开发、调试、评估到部署的完整流程。
• 多语言 SDK ：提供 Python、Go、JavaScript SDK，方便二次开发与系统集成。
• 模型集成 ：支持 OpenAI、火山引擎 Ark 等大模型，灵活配置。
• 开源社区支持 ：基于 Apache 2.0 许可，鼓励社区贡献代码与反馈。
• 国际化支持 ：支持多语言界面，适配全球开发者需求。

使用帮助

安装与部署

CozeLoop 是开源项目，需从 GitHub 仓库克隆代码并本地部署。以下是详细步骤：

1. 环境准备 ：
   • 硬件要求 ：最低 2 核 CPU、4GB 内存。
   • 软件依赖 ：
     • Docker 和 Docker Compose ：确保已安装并启动 Docker 服务。
     • Golang ：建议版本 1.23.4，配置好环境变量。
     • Node.js ：建议 LTS 版本，用于 JavaScript SDK 开发。
     • pnpm ：全局安装 pnpm（推荐版本 9.12.0）：

     npm i -g pnpm@9.12.0
     

2. 克隆仓库 ：
   获取 CozeLoop 源代码：

git clone https://github.com/coze-dev/cozeloop.git
cd cozeloop

1. 配置环境变量 ：
   • 访问 https://loop.coze.cn/console/enterprise/personal/open/oauth/apps 创建 OAuth 应用，获取 client_id、public_key_id 和 private_key。
   • 创建 .env 文件，配置以下内容：

     COZELOOP_WORKSPACE_ID=your_workspace_id
     COZELOOP_JWT_OAUTH_CLIENT_ID=your_client_id
     COZELOOP_JWT_OAUTH_PRIVATE_KEY=your_private_key
     COZELOOP_JWT_OAUTH_PUBLIC_KEY_ID=your_public_key_id
     COZELOOP_API_BASE=https://api.coze.cn
     

2. 配置模型 ：
   • 复制模型配置文件模板（如火山引擎 Ark 模型）：

     cp conf/model/template/model_template_ark.yaml conf/model/ark.yaml
     

   • 编辑 conf/model/ark.yaml，配置以下字段：
     • id：自定义模型 ID，非零整数，全局唯一，部署后不可修改。
     • meta.conn_config.api_key：模型服务 API 密钥，例如火山引擎 Ark API Key（获取方式见 https://www.volcengine.com/docs/82379/1541594）。
     • meta.conn_config.model：模型 Endpoint ID，例如 Ark 模型的 Endpoint ID（获取方式见 https://www.volcengine.com/docs/82379/1099522）。
3. 安装依赖 ：
   • Go 依赖通过 go mod 自动管理：

     go mod tidy
     

   • JavaScript 依赖：

     pnpm install
     rush update
     

4. 构建与运行 ：
   • 构建项目：

     go build
     

   • 启动服务：

     docker compose --profile '*' up -d
     

     首次部署可能需拉取镜像，成功启动后日志显示 Container coze-server Started，通过 http://localhost:3000 访问。

5. 开发模式 ：
   • 默认开发模式支持热重载，修改后端代码无需重启服务。运行：

     ./dev_reload.sh
     

使用核心功能

1. 提示词开发与调试

• 进入 Playground ：登录控制台（https://loop.coze.cn/console/enterprise/personal/open），选择“提示词”模块。
• 创建提示词 ：输入提示词内容，实时测试输出效果。支持多模型对比（如 OpenAI 和 Ark 模型）。示例 Go 代码：

prompt, err := loop.GetPrompt(ctx, loop.GetPromptParam{PromptKey: "test_prompt"})
messages, err := loop.PromptFormat(ctx, prompt, map[string]any{"input": "Hello"})

• 版本管理 ：保存提示词版本，随时切换或回滚。

2. 自动化评估

• 管理评估集 ：上传测试数据集（如 JSON 文件），定义评估指标（如准确性、简洁性）。
• 运行实验 ：选择评估器，自动测试智能体输出，查看统计结果。
• 查看报告 ：控制台显示实验报告，分析模型性能。

3. 运行监控

• Trace 跟踪 ：记录智能体执行全链路数据，包括输入解析、模型调用和输出。Go 示例：

ctx, span := loop.StartSpan(ctx, "root", "custom")
span.SetInput(ctx, "User query")
span.SetOutput(ctx, "AI response")
span.Finish(ctx)
loop.Close(ctx)

• 可视化观察 ：在控制台查看 Trace 数据，分析关键节点和异常状态。

4. SDK 集成

• Python SDK ：用于快速集成：

from cozepy import Coze, TokenAuth
coze = Coze(auth=TokenAuth(os.getenv("COZE_API_TOKEN")))
bot = coze.bots.create(space_id="your_workspace_id", name="TestBot")
print(f"Created bot: {bot.name}")

• JavaScript SDK ：在 frontend 目录运行：

rushx start

5. 国际化支持

• 配置多语言界面，在 conf 目录编辑 i18n 设置，支持英语、简体中文等。

问题排查

• 检查配置 ：确保 .env 和模型配置文件正确。
• 查看日志 ：运行以下命令检查容器状态：

docker ps
docker logs <container_id>

• 网络问题 ：确认 COZELOOP_API_BASE 可访问，检查 Docker 网络。

社区贡献

• 参考 CONTRIBUTING.md 提交代码。安全问题通过 https://security.bytedance.com/src 或邮箱 sec@bytedance.com 报告，勿公开。

应用场景

1. AI 客服优化
   使用 CozeLoop 调试提示词，监控客服智能体性能，提升响应准确性。
2. 模型评估
   开发者通过自动化评估模块测试模型输出，优化 AI 应用效果。
3. 实时监控
   企业监控智能体运行状态，快速发现并修复异常，提升系统稳定性。
4. 多语言应用
   开发全球化的 AI 应用，借助 i18n 支持适配多语言用户需求。

QA

1. CozeLoop 与 Coze Studio 的区别？
   CozeLoop 专注于提示词调试、评估和监控，优化智能体性能；Coze Studio 侧重智能体开发与工作流编排。
2. 如何获取 OAuth 参数？
   访问 https://loop.coze.cn/console/enterprise/personal/open/oauth/apps，创建 OAuth 应用，获取密钥。
3. 支持哪些模型？
   支持 OpenAI、火山引擎 Ark 等模型，需手动配置，详见 https://github.com/coze-dev/cozeloop/wiki/5.-Model-configuration。
4. 是否需要编程经验？
   控制台支持无代码操作，编程用户可通过 SDK 定制功能。
5. 如何加入社区？
   使用飞书扫描 README.md 中的二维码，加入 CozeLoop 技术交流群。