写点什么

Coze 教程 | 第 2 章:Coze 开发环境搭建与配置

  • 2025-09-02
    黑龙江
  • 本文字数:2965 字

    阅读完需:约 10 分钟

本文将手把手带你完成 Coze 开发环境的搭建与配置,让你能快速开始本地化的 AI 智能体开发。

1. Coze 开源概述与环境准备

字节跳动于 2025 年 7 月 26 日正式开源其 AI 智能体开发平台"扣子"(Coze),包含 Coze Studio 可视化开发工具Coze Loop 运维管理系统两大核心组件。它采用 Apache 2.0 许可证,允许免费商业使用,无隐藏条款。

1.1 硬件要求

Coze 的硬件要求非常亲民:


  • CPU:2 核或以上

  • 内存:4GB 或以上

  • 存储空间:至少 2GB 可用空间


这意味着普通家用电脑即可流畅运行,真正将 AI 开发门槛拉低到"家用电脑级"。

1.2 软件依赖

Coze 本地部署的唯一前置依赖是Docker,它的作用是为 Coze 创建隔离的运行环境,避免了繁琐的环境配置工作。


测试开发全景图:人工智能测试、智能驱动、自动化、测试开发、左移右移与DevOps的持续交付


2. 安装 Docker

Docker 是容器化平台,允许你轻松打包、分发和运行应用程序。

2.1 安装步骤

  1. 访问Docker官网下载适合你操作系统的安装包。

  2. 双击安装包,按照向导完成安装(Windows 用户需要启用 Hyper-V 功能,安装过程中若提示重启请同意)。

  3. 安装完成后打开 Docker Desktop,确认状态栏显示"Running"。


💡 提示:如果从 Docker 官网下载速度慢,可以使用国内镜像包。

2.2 验证安装

安装完成后,打开终端或命令提示符,运行以下命令验证 Docker 是否安装成功:


docker --versiondocker compose version
复制代码


如果这两个命令都能正确输出版本信息,说明 Docker 已成功安装。

3. 获取 Coze 源码

Coze 的源代码托管在 GitHub 上,我们可以通过 git 命令获取:


  1. 打开终端(Docker Desktop 内置终端或系统终端)

  2. 执行以下命令克隆代码仓库:


# 克隆Coze Studio代码仓库git clone https://github.com/coze-dev/coze-studio.git
# 进入docker配置目录cd coze-studio/docker
# 复制环境配置文件cp .env.example .env
复制代码


⚠️ 注意:Windows 用户如果使用命令提示符(CMD),可能需要将cp命令替换为copy

copy .env.example .env


对于不熟悉 git 的用户,可以直接在 GitHub 下载 ZIP 压缩包并解压,然后手动进入coze-studio/docker目录创建.env文件。

4. 配置模型服务(关键步骤)

这是最关键的一步,不配置模型将无法创建智能体。Coze 支持多种大语言模型,包括 DeepSeek、OpenAI、Claude、Qwen、Gemini、豆包等。以下以配置 DeepSeek 模型为例:

4.1 创建模型配置文件

  1. 进入模型配置目录:


    # Mac/Linux用户    open ../backend/conf/model/        # Windows用户    start ../backend/conf/model/
复制代码


  1. 复制 DeepSeek 模板文件:


    # 复制DeepSeek模板    cp ../backend/conf/model/template/model_template_ark_volc_deepseek-r1.yaml backend/conf/model/deepseek-r1.yaml
复制代码

4.2 编辑模型配置

用文本编辑器打开新创建的deepseek-r1.yaml文件,修改以下参数:


base_url: "https://api.deepseek.com/v1"api_key: "sk-xxxxxxxx"  # 在DeepSeek平台(https://platform.deepseek.com/)申请model: "deepseek-reasoner"
复制代码


其中api_key需要在DeepSeek平台申请。


以下是几种常见模型的配置参数参考:



💡 提示:豆包模型的 API Key 来自火山引擎(字节的云服务平台),可以在https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey申请。

5. 启动 Coze 服务

完成模型配置后,就可以启动 Coze 服务了:


  1. 确保当前在coze-studio/docker目录中

  2. 执行以下命令启动服务:


docker compose --profile '*' up -d
复制代码


这个命令的含义是:


  • docker compose:使用 Docker Compose 运行服务

  • --profile '*':启用所有 profile 配置

  • up:启动服务(没有就创建容器,有就重启)

  • -d:detached 模式,即在后台运行


首次运行需要下载和构建镜像,可能需要 5-15 分钟(具体时间取决于网络速度)。

6. 访问 Coze 界面

服务启动成功后,打开浏览器访问http://localhost:8888,你就可以看到 Coze Studio 的首页了。


首次访问时,系统会提示你注册账号,输入任意邮箱和密码即可完成注册并登录系统。

7. 避坑指南:常见问题与解决方案

在部署过程中,可能会遇到一些常见问题,以下是解决方案:

7.1 端口冲突错误

如果启动时提示Ports are not available,说明有端口被占用:


解决方案


  • 关闭占用端口的程序(如 3306/6379):


    # Windows查找占用3306端口的进程    netstat -ano | findstr :3306    # 然后使用任务管理器结束对应PID的进程
复制代码


  • 或者修改docker-compose.yml中的端口映射配置,将冲突的端口改为其他未占用端口。

7.2 MySQL 启动失败

如果报错MYSQL_USER cannot be "root"


解决方案


  • 删除系统环境变量中的MYSQL_USERMYSQL_PASSWORD

7.3 Elasticsearch 启动失败

如果报错exit 127或提示"service 'elasticsearch-setup' didn't complete successfully":


解决方案


  • 用 VS Code 或 Notepad++等代码编辑器打开docker/volumes/elasticsearch/setup_es.sh文件。

  • 在编辑器的右下角,你会看到 CRLF 或 LF 的标识,点击它并选择 LF 格式。

  • 保存文件后重新启动服务。

7.4 Windows 特有问题

Windows 用户可能会遇到以下问题:


  1. 命令不存在错误:Windows 系统可能不支持一些 Linux 命令(如cpopen等):

  2. 使用copy代替cp

  3. 使用start代替open

  4. 端口被系统保留:如果出现Ports are not available: exposing port TCP 0.0.0.0:2379错误:


    # 查看端口占用    netstat -ano | findstr :2379    # 重置网络适配器    net stop winnat    net start winnat
复制代码

8. 进阶配置:更换模型

如果你想更换为其他模型(如切换到 Qwen),可以按照以下步骤操作:


  1. 复制模板文件到配置目录:


    cp ../backend/conf/model/template/model_template_basic ../backend/conf/model/qwen.yaml
复制代码


  1. 修改 qwen.yaml 内容:


    id: 2  # 保持唯一性,不可与其他模型重复    name: "qwen3-235b"    meta.conn_config:      base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"      api_key: "阿里百炼申请的KEY"      model: "qwen3-235b-a22b-instruct-2507"
复制代码


  1. 重启服务生效:


    docker compose --profile '*' restart coze-server
复制代码

9. 验证部署是否成功

完成所有步骤后,可以通过以下方式验证 Coze 是否成功部署:


  1. 访问http://localhost:8888,能够看到 Coze 登录界面

  2. 注册账号并登录系统

  3. 尝试创建一个简单的智能体并进行对话测试

  4. 如果遇到"Something error: Internal server error",可以通过查看日志排查问题:


    # Linux/Mac    docker logs coze-server | grep -i 'node execute failed'        # Windows    docker logs coze-server | findstr /i "node execute failed"
复制代码

10. 本章小结

本章详细介绍了 Coze 开发环境的搭建与配置过程,主要包括以下内容:


  1. 环境准备:安装 Docker 作为 Coze 运行的基础环境

  2. 获取源码:从 GitHub 克隆 Coze Studio 代码仓库

  3. 模型配置:配置 DeepSeek 或其他大语言模型作为智能体的核心引擎

  4. 服务启动:使用 Docker Compose 启动所有 Coze 服务

  5. 问题排查:解决部署过程中可能遇到的常见问题

  6. 验证测试:访问 Coze 界面并验证部署是否成功


现在你已经成功搭建了本地的 Coze 开发环境,可以开始创建和测试自己的 AI 智能体了。在下一章中,我们将深入介绍如何使用 Coze 创建你的第一个智能体,并配置其基本功能和特性。


测试开发全景图:人工智能测试、智能驱动、自动化、测试开发、左移右移与DevOps的持续交付


温馨提示:火山引擎等平台提供的免费 API 调用额度是有限的,请注意你的 token 消耗情况。你也可以配置本地模型或其他第三方模型服务,只需修改相应的base_url即可。

用户头像

社区:ceshiren.com 微信:ceshiren2023 2022-08-29 加入

微信公众号:霍格沃兹测试开发 提供性能测试、自动化测试、测试开发等资料、实事更新一线互联网大厂测试岗位内推需求,共享测试行业动态及资讯,更可零距离接触众多业内大佬

评论

发布
暂无评论
Coze教程 | 第2章:Coze开发环境搭建与配置_测吧(北京)科技有限公司_InfoQ写作社区