本文将手把手带你完成Coze开发环境的搭建与配置,让你能快速开始本地化的AI智能体开发。
字节跳动于2025年7月26日正式开源其AI智能体开发平台”扣子”(Coze),包含Coze Studio可视化开发工具和Coze Loop运维管理系统两大核心组件。它采用Apache 2.0许可证,允许免费商业使用,无隐藏条款。
Coze的硬件要求非常亲民:
这意味着普通家用电脑即可流畅运行,真正将AI开发门槛拉低到”家用电脑级”。
Coze本地部署的唯一前置依赖是Docker,它的作用是为Coze创建隔离的运行环境,避免了繁琐的环境配置工作。
Docker是容器化平台,允许你轻松打包、分发和运行应用程序。
提示:如果从Docker官网下载速度慢,可以使用国内镜像包。
安装完成后,打开终端或命令提示符,运行以下命令验证Docker是否安装成功:
docker --version
docker compose version
如果这两个命令都能正确输出版本信息,说明Docker已成功安装。
Coze的源代码托管在GitHub上,我们可以通过git命令获取:
# 克隆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
文件。
这是最关键的一步,不配置模型将无法创建智能体。Coze支持多种大语言模型,包括DeepSeek、OpenAI、Claude、Qwen、Gemini、豆包等。以下以配置DeepSeek模型为例:
进入模型配置目录:
# Mac/Linux用户
open ../backend/conf/model/
# Windows用户
start ../backend/conf/model/
复制DeepSeek模板文件:
# 复制DeepSeek模板
cp ../backend/conf/model/template/model_template_ark_volc_deepseek-r1.yaml backend/conf/model/deepseek-r1.yaml
用文本编辑器打开新创建的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平台申请。
以下是几种常见模型的配置参数参考:
模型类型 | base_url | model参数 | API密钥来源 |
---|---|---|---|
DeepSeek | https://api.deepseek.com/v1 | deepseek-reasoner | DeepSeek平台 |
OpenAI | https://api.openai.com/v1 | gpt-4 | OpenAI平台 |
豆包模型 | - | doubao-seed-1.6 | 火山引擎 |
Qwen | https://dashscope.aliyuncs.com/compatible-mode/v1 | qwen3-235b-a22b-instruct-2507 | 阿里百炼 |
提示:豆包模型的API Key来自火山引擎(字节的云服务平台),可以在https://console.volcengine.com/ark/region:ark+cn-beijing/apiKey申请。
完成模型配置后,就可以启动Coze服务了:
coze-studio/docker
目录中
docker compose --profile '*' up -d
这个命令的含义是:
docker compose
:使用Docker Compose运行服务--profile '*'
:启用所有profile配置up
:启动服务(没有就创建容器,有就重启)-d
:detached模式,即在后台运行首次运行需要下载和构建镜像,可能需要5-15分钟(具体时间取决于网络速度)。
服务启动成功后,打开浏览器访问http://localhost:8888,你就可以看到Coze Studio的首页了。
首次访问时,系统会提示你注册账号,输入任意邮箱和密码即可完成注册并登录系统。
在部署过程中,可能会遇到一些常见问题,以下是解决方案:
如果启动时提示Ports are not available
,说明有端口被占用:
解决方案:
# Windows查找占用3306端口的进程
netstat -ano | findstr :3306
# 然后使用任务管理器结束对应PID的进程
docker-compose.yml
中的端口映射配置,将冲突的端口改为其他未占用端口。如果报错MYSQL_USER cannot be "root"
:
解决方案:
MYSQL_USER
和MYSQL_PASSWORD
。如果报错exit 127
或提示”service ‘elasticsearch-setup’ didn’t complete successfully”:
解决方案:
docker/volumes/elasticsearch/setup_es.sh
文件。Windows用户可能会遇到以下问题:
命令不存在错误:Windows系统可能不支持一些Linux命令(如cp
、open
等):
copy
代替cp
start
代替open
端口被系统保留:如果出现Ports are not available: exposing port TCP 0.0.0.0:2379
错误:
# 查看端口占用
netstat -ano | findstr :2379
# 重置网络适配器
net stop winnat
net start winnat
如果你想更换为其他模型(如切换到Qwen),可以按照以下步骤操作:
复制模板文件到配置目录:
cp ../backend/conf/model/template/model_template_basic ../backend/conf/model/qwen.yaml
修改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"
重启服务生效:
docker compose --profile '*' restart coze-server
完成所有步骤后,可以通过以下方式验证Coze是否成功部署:
# Linux/Mac
docker logs coze-server | grep -i 'node execute failed'
# Windows
docker logs coze-server | findstr /i "node execute failed"
本章详细介绍了Coze开发环境的搭建与配置过程,主要包括以下内容:
现在你已经成功搭建了本地的Coze开发环境,可以开始创建和测试自己的AI智能体了。在下一章中,我们将深入介绍如何使用Coze创建你的第一个智能体,并配置其基本功能和特性。
温馨提示:火山引擎等平台提供的免费API调用额度是有限的,请注意你的token消耗情况。你也可以配置本地模型或其他第三方模型服务,只需修改相应的
base_url
即可。
Copyright 2014-2025 https://www.php.cn/ All Rights Reserved | php.cn | 湘ICP备2023035733号