Coze Loop 是什么

Coze Loop 是一款面向开发者的平台级解决方案，专注于 AI 助手的开发与运营。它解决了 AI 助手开发过程中面临的各种挑战，提供了从开发、调试、评估到监控的全生命周期管理能力。

在商业版的基础上，Coze Loop 推出了开源版本，为开发者免费提供核心基础功能模块。通过开源其核心技术框架，开发者可以根据业务需求进行定制和扩展，促进社区共建、共享与交流，帮助开发者零门槛参与 AI 助手的探索与实践。

Coze Loop 能做什么？

Coze Loop 通过提供全生命周期管理能力，帮助开发者更高效地开发和运营 AI 助手。无论是提示词工程、AI 助手评估，还是部署后的监控与优化，Coze Loop 都提供了强大的工具和智能支持，极大地简化了 AI 助手的开发流程，提升了其运行性能和稳定性。

• 提示词开发：Coze Loop 的提示词开发模块为开发者提供从编写、调试、优化到版本管理的全流程支持。通过可视化 Playground，可以实时交互式测试提示词，让开发者直观比较不同大模型的输出。
• 评估：Coze Loop 的评估模块为开发者提供系统化的评估能力，能够自动对提示词及 Coze 助手的输出进行多维度测试，例如准确性、简洁性、合规性等。
• 可观测性：Coze Loop 为开发者提供整个执行过程的可观测性，完整记录从用户输入到 AI 输出的每一个环节，包括提示词解析、模型调用、工具执行等关键阶段，并自动捕获中间结果和异常信息。

功能列表

功能	功能点
提示词调试	* Playground 调试与对比 * 提示词版本管理
评估	* 管理评估集 管理评估者 * 管理实验
观察	SDK 跟踪上报 * 跟踪数据观察
模型	支持集成 OpenAI、火山引擎 Ark 等模型

快速入门

请参阅 快速入门 ，详细了解如何安装并部署最新版本的 Coze Loop。

部署方式 1：Docker 部署（Docker Compose）

请先安装并启动 Docker 引擎。

步骤：

1. 克隆源代码。 运行以下命令获取最新版本的 Coze Loop 源代码。

   # 克隆代码
   git clone https://github.com/coze-dev/coze-loop.git
   
   # 进入 coze-loop 目录
   cd coze-loop
   

2. 配置模型。

   1. 进入 coze-loop 目录。
   2. 编辑文件 release/deployment/docker-compose/conf/model_config.yaml。
   3. 修改 api_key 和 model 字段。以火山引擎 Ark 为例：
      • api_key：火山引擎 Ark API 密钥。中国地区的用户可参考 火山引擎 Ark 文档，而海外用户则可参考 字节跳动 ModelArk 文档。
      • model：火山引擎 Ark 模型接入点的 Endpoint ID。中国境内的用户可参考 火山引擎 Ark 文档；海外用户则可参考 字节跳动 ModelArk 文档。

3. 启动服务。 运行以下命令，使用 Docker Compose 快速部署 Coze Loop 开源版本。

   # 启动服务（默认：开发模式）
   # 在 coze-loop/ 目录下运行
   make compose-up
   

4. 通过浏览器访问 Coze Loop 开源版本 http://localhost:8082。

部署方式2：使用Helm Chart进行Kubernetes部署

• 已准备好Kubernetes集群，启用了Nginx Ingress插件，并安装了Kubectl和Helm工具。
• 如需在本地快速试用，可使用Minikube部署Kubernetes集群。详细步骤请参阅快速入门。

操作步骤：

1. 运行以下命令获取Helm Chart包。

   helm pull oci://docker.io/cozedev/coze-loop --version 1.0.0-helm
   tar -zxvf coze-loop-1.0.0-helm.tgz && cd coze-loop && rm -f ../coze-loop-1.0.0-helm.tgz
   

2. 配置模型。 进入coze-loop目录，编辑release/deployment/helm-chart/umbrella/conf/model_config.yaml文件。按照以下字段进行配置，以火山引擎Ark为例：

   • api_key：火山引擎Ark API Key。中国大陆用户可参考火山引擎Ark文档，而海外用户则可参考字节跳动ModelArk文档。
   • model：火山引擎Ark模型接入点的Endpoint ID。中国用户可参考火山引擎Ark文档，而海外用户则可参考字节跳动ModelArk文档。

3. 配置Ingress规则。 Ingress用于将服务暴露到外部网络。您需要根据实际集群情况，配置项目目录中的templates/ingress.yaml文件，手动修改ingressClassName等参数，并设置class、instance、host及IP分配等元素。

4. 部署并启动服务。 执行以下命令，使用Helm快速部署Coze Loop开源版本。

   # 在coze-loop/目录下运行
   make helm-up
   # 服务部署完成后，检查集群Pod状态
   make helm-pod
   # 查看服务启动日志。若app和nginx均正常运行，则部署成功
   make helm-logf-app
   make helm-logf-nginx
   

5. 通过浏览器访问Coze Loop开源版。 访问域名和URL取决于您集群分配的域名和URL。

6. 开始自定义您的Coze Loop项目。 参考examples/目录中的示例，修改values.yaml以覆盖默认设置。更改后重新运行make helm-up，使更改生效。

[!WARNING] 若您希望在公有网络环境中部署Coze Loop，建议在开始前评估安全风险，并采取相应的防护措施。可能的安全风险包括账户注册功能、Coze Server监听地址配置、SSRF（服务器端请求伪造）以及部分API中的水平权限提升问题。更多详情请参阅快速入门。

使用Coze Loop开源版

• 提示开发与调试：Coze Loop提供完整的提示词开发流程。
• 评估：Coze Loop的评估功能提供标准的评估数据管理、自动化评估引擎以及实验结果的全面统计。
• 追踪报告与查询：Coze Loop支持自动上报平台创建的提示词调试会话中的追踪信息，实现对每条追踪记录的实时跟踪。
• Coze Loop SDK开源版使用：Coze Loop SDK提供三种语言版本，适用于商业版和开源版。对于开源版，开发者只需在初始化时调整部分参数配置即可。

开发者指南

• 系统架构：了解Coze Loop开源版的技术架构及核心组件。
• 启动模式：安装并部署Coze Loop开源版时，默认的开发模式允许在不重启服务的情况下修改后端文件。
• 模型配置：Coze Loop开源版通过Eino框架支持多种LLM模型。请参阅本文档，查看支持的模型列表并学习如何配置模型。
• 代码开发与测试：了解如何基于Coze Loop开源版进行二次开发和测试。
• 故障排查：学习如何检查容器状态和系统日志。

许可证

本项目采用Apache 2.0许可证。更多详情请参阅LICENSE文件。

社区贡献

我们欢迎社区贡献。有关贡献指南，请参阅CONTRIBUTING和行为准则。期待您的参与！

安全与隐私

如果您发现本项目中存在潜在的安全问题，或认为自己可能发现了此类问题，请通过我们的安全中心或漏洞报告邮箱通知字节跳动安全团队。 请勿创建公开的GitHub Issue。

加入社区

我们致力于构建开放友好的开发者社区。所有对AI Agent开发感兴趣的开发者均欢迎加入我们！

问题报告与功能请求

为高效跟踪和解决各类问题，同时确保透明度与协作，我们建议通过以下方式参与：

• GitHub Issues：提交Bug报告或功能请求
• Pull Requests：贡献代码或文档改进

技术讨论与交流

加入我们的技术讨论群，与其他开发者分享经验，并及时了解项目的最新进展：

• 飞书群聊：请在飞书移动端扫描下方二维码，加入 Coze Loop 技术讨论群。

• Discord 服务器：Coze 社区

• Telegram 群组：Coze

致谢

感谢所有为 Coze Loop 项目做出贡献的开发者和社区成员。特别鸣谢：

• Eino 框架团队提供的大模型集成支持
• CloudWeGo 团队开发的高性能框架
• 所有参与测试与反馈的用户

Coze Loop 快速上手指南

Coze Loop 是面向开发者的 AI Agent 全生命周期管理平台开源版，提供提示词（Prompt）开发、评估、可观测性等核心能力。本指南将帮助中国开发者快速在本地部署并体验基础功能。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux / macOS / Windows (需安装 WSL2 或 Docker Desktop)
• 核心依赖：
  • Docker & Docker Compose：必须安装并启动 Docker Engine。
  • Git：用于克隆源代码。
  • Make：用于执行自动化部署命令。
• 网络环境：由于项目托管于 GitHub，建议配置网络加速或使用国内镜像源拉取代码。
• 模型凭证：需准备大模型 API Key。
  • 国内用户推荐：火山引擎方舟 (Volcengine Ark)。
  • 海外用户推荐：BytePlus ModelArk 或 OpenAI。

安装步骤 (Docker Compose 方式)

这是最推荐的本地快速体验方式。

1. 获取源代码

使用 Git 克隆项目并进入目录：

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

2. 配置大模型

编辑模型配置文件，填入您的 API Key 和模型端点信息。

1. 打开配置文件：release/deployment/docker-compose/conf/model_config.yaml
2. 修改以下字段（以火山引擎方舟为例）：
   • api_key: 填入您的 Volcengine Ark API Key。
   • model: 填入您的模型访问点 Endpoint ID。

提示：国内用户可申请火山引擎方舟服务，具体文档参考 火山引擎方舟文档。

3. 启动服务

在项目根目录下执行以下命令，通过 Docker Compose 启动服务（默认开发模式）：

make compose-up

等待容器启动完成。

4. 访问平台

服务启动成功后，在浏览器中访问：

http://localhost:8082

基本使用

登录 Coze Loop 后，您可以立即开始以下核心操作：

1. 提示词开发与调试 (Prompt Playground)

• 进入 Prompt Development 模块。
• 在可视化 Playground 中输入您的 Prompt 模板。
• 实时选择不同的大模型进行测试，对比输出结果。
• 支持对 Prompt 进行版本管理和迭代优化。

2. 链路追踪与可观测性 (Observability)

• Coze Loop 会自动记录从用户输入到 AI 输出的完整执行链路。
• 在 Observation 模块中，您可以查看详细的 Trace 数据，包括：
  • Prompt 解析过程
  • 模型调用耗时与参数
  • 工具执行中间结果
  • 异常捕获信息

3. 效果评估 (Evaluation)

• 进入 Evaluation 模块，创建评估集。
• 配置评估器（Evaluator），对 Prompt 或 Agent 的输出进行多维度自动打分（如准确性、简洁性、合规性）。
• 查看实验统计报表，辅助决策最优模型或提示词版本。

---

更多高级用法（如 Kubernetes 部署、SDK 集成、二次开发）请参考官方开发者指南。