Coze 教程 | 第 2 章:Coze 开发环境搭建与配置
本文将手把手带你完成 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 安装步骤
访问Docker官网下载适合你操作系统的安装包。
双击安装包,按照向导完成安装(Windows 用户需要启用 Hyper-V 功能,安装过程中若提示重启请同意)。
安装完成后打开 Docker Desktop,确认状态栏显示"Running"。
💡 提示:如果从 Docker 官网下载速度慢,可以使用国内镜像包。
2.2 验证安装
安装完成后,打开终端或命令提示符,运行以下命令验证 Docker 是否安装成功:
如果这两个命令都能正确输出版本信息,说明 Docker 已成功安装。
3. 获取 Coze 源码
Coze 的源代码托管在 GitHub 上,我们可以通过 git 命令获取:
打开终端(Docker Desktop 内置终端或系统终端)
执行以下命令克隆代码仓库:
⚠️ 注意: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 创建模型配置文件
进入模型配置目录:
复制 DeepSeek 模板文件:
4.2 编辑模型配置
用文本编辑器打开新创建的deepseek-r1.yaml
文件,修改以下参数:
其中api_key
需要在DeepSeek平台申请。
以下是几种常见模型的配置参数参考:
💡 提示:豆包模型的 API Key 来自火山引擎(字节的云服务平台),可以在https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey申请。
5. 启动 Coze 服务
完成模型配置后,就可以启动 Coze 服务了:
确保当前在
coze-studio/docker
目录中执行以下命令启动服务:
这个命令的含义是:
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):
或者修改
docker-compose.yml
中的端口映射配置,将冲突的端口改为其他未占用端口。
7.2 MySQL 启动失败
如果报错MYSQL_USER cannot be "root"
:
解决方案:
删除系统环境变量中的
MYSQL_USER
和MYSQL_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 用户可能会遇到以下问题:
命令不存在错误:Windows 系统可能不支持一些 Linux 命令(如
cp
、open
等):使用
copy
代替cp
使用
start
代替open
端口被系统保留:如果出现
Ports are not available: exposing port TCP 0.0.0.0:2379
错误:
8. 进阶配置:更换模型
如果你想更换为其他模型(如切换到 Qwen),可以按照以下步骤操作:
复制模板文件到配置目录:
修改 qwen.yaml 内容:
重启服务生效:
9. 验证部署是否成功
完成所有步骤后,可以通过以下方式验证 Coze 是否成功部署:
访问http://localhost:8888,能够看到 Coze 登录界面
注册账号并登录系统
尝试创建一个简单的智能体并进行对话测试
如果遇到"Something error: Internal server error",可以通过查看日志排查问题:
10. 本章小结
本章详细介绍了 Coze 开发环境的搭建与配置过程,主要包括以下内容:
环境准备:安装 Docker 作为 Coze 运行的基础环境
获取源码:从 GitHub 克隆 Coze Studio 代码仓库
模型配置:配置 DeepSeek 或其他大语言模型作为智能体的核心引擎
服务启动:使用 Docker Compose 启动所有 Coze 服务
问题排查:解决部署过程中可能遇到的常见问题
验证测试:访问 Coze 界面并验证部署是否成功
现在你已经成功搭建了本地的 Coze 开发环境,可以开始创建和测试自己的 AI 智能体了。在下一章中,我们将深入介绍如何使用 Coze 创建你的第一个智能体,并配置其基本功能和特性。
测试开发全景图:人工智能测试、智能驱动、自动化、测试开发、左移右移与DevOps的持续交付
温馨提示:火山引擎等平台提供的免费 API 调用额度是有限的,请注意你的 token 消耗情况。你也可以配置本地模型或其他第三方模型服务,只需修改相应的
base_url
即可。
评论