前几天扣子也是发布了开源代码，公司也是看到啥就想试试，所以也尝试在本地部署了一版，也是踩了许许多多奇葩的坑

在这里先对字节的开源表示非常的感谢，但是对于那个下几把写的配置教程表示务必强烈的谴责，浪费我好几天时间真是太NC了

直接步入正题

第一步  首先拉取代码

git clone https://github.com/coze-dev/coze-studio.git

拉完代码看一下结构，主要关注docker文件夹

backend文件夹是go语言写的后端代码

frontend文件夹是前端代码

docker文件夹是是docker的各种配置和搭建项目相关的文件和命令，这里个文件夹非常的重要

以下是Docker目录下的文件

docker-compose.yml：熟悉docker的小伙伴应该都知道是用来干啥的，用于拉取镜像，配置docker内部网络环境以及拉取镜像，端口映射都在这个文件里，如果构建项目时提示端口号冲突就得修改这个文件里的端口映射，这种比较基础的就不在这里说了
.env.example：这个是环境变量的模板 

暂时只关注这些文件就行

切换目录到指定目录

切记使用powershell，不要用cmd

 cd "D:\MyWork\Coze Studio\coze-studio\docker"  // 替换成你自己的路径，一定要导航到Docker目录下

第二步  复制大模型配置文件

此处官方给出的示例是：

cp backend/conf/model/template/model_template_ark_doubao-seed-1.6.yaml backend/conf/model/ark_doubao-seed-1.6.yaml

这里官方文档中用的是豆包的大模型，当然你也可以直接去文件夹下面Ctrl+C再Ctrl+V过来

选择你要用的大模型的模板配置文件，当让可以不止一个，文件名看着改就行了，在启动的时候会扫描这个目录下所有的文件

从模板的路径 backend/conf/model/template 

复制到 backend/conf/model 路径下

我这里用了豆包，deepseek和通义千问的大模型

配置要点

在模型复制过来之后，特别需要注意的一点就是这些文件中的Id不要一样，即截图中红框的部分

接下来要修改的只有大模型的配置部分

1.豆包

    conn_config:
        base_url: "https://ark.cn-beijing.volces.com/api/v3/"
        api_key: "48xxxxxxxxxxxxxxxxxxxxxxxxxd7"
        timeout: 0s
        model: "ep-xxxxxxxxxxxx-psp8r"
        temperature: 0.1
        frequency_penalty: 0
        presence_penalty: 0
        max_tokens: 4096
        top_p: 0.7
        top_k: 0
        stop: []

申请豆包接入点

要用豆包的大模型，首先需要去进行申请，给找不到地方的小伙伴截个图

baseurl ：https://ark.cn-beijing.volces.com/api/v3/

这个配置项疑似与这个有关，但是我没试过切换到其他的节点下申请接入点各位如果尝试使用其他接入点的话可以在评论里告知一下是否需要改baseurl

apiKey：从apikey管理里复制一个

model：使用截图中红框中的部分，既接入点的Id，不要直接写model的名字或者接入点的名字

2.通义千问

conn_config:
        base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
        api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxx"
        timeout: 0s
        model: "qwen3-coder-plus"
        temperature: 0.7
        frequency_penalty: 0
        presence_penalty: 0
        max_tokens: 4096

baseurl：配置项使用使用例子里的这个
api_key：同样从apikey管理里复制一个，但是需要注意apikey所对应的业务空间有没有开通对应的大模型

model：通义就得用对应model的code，同样为不知道怎么找的小伙伴放一个截图

3.deepseek

conn_config:
        base_url: "https://api.deepseek.com"
        api_key: "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxx"
        timeout: 0s
        model: "deepseek-chat"
        temperature: 0.1
        frequency_penalty: 0
        presence_penalty: 0
        max_tokens: 4096

和通义差不多，就不过多介绍了，在deepseek官方文档写得很清楚，就比上面两个用着舒服多了

文档地址：首次调用 API | DeepSeek API Docshttps://api-docs.deepseek.com/zh-cn/

第三步  项目部署 

当这里完成之后就已经可以部署项目了，参考官方的教程

cp .env.example .env
docker compose --profile '*' up -d

同样使用powershell，每次复制一行执行一行
cp .env.example .env  复制.env.example模板并命名为.env，当然你也可以手动进行这一步操作

这个文件里基本都是Coze要用的模型配置，插件配置，后面遇到的一些问题需要通过修改这个文件来解决，暂时先不动他
docker compose --profile '*' up -d 通过环境变量构建镜像并运行容器

三步完成之后如果控制台没报错就项目就正常启动成功了，由于我本地已经部署完了所以这里复制我们老大在Linux下运行起来的截图

项目部署时的疑难杂症部分

1：端口号冲突

解决方案：修改docker-compose.yml文件中，对应镜像的宿主机端口号

2：拉取镜像的时候超时，全都拉不下来

解决方案：设置镜像加速，这个找百度问问或者问问在线的ai，有很多方案，当然也可以使用科学上网工具

3：nsqamin拉取失败

解决方案：别慌重新拉一次就好了，只有他第一次会失败，后面再拉取一次就ok了

4：显示全部运行成功了，但是Coze-server过几秒自己就挂了

查看错误信息显示：cannot unmarshal !!str ':0 into modelmgr.Modelstatus

解决方案：官方配置文档受害者，参考上面的例子修改豆包的yaml文件配置，baseurl记得填上

如果你没有出现以上任何错误那么恭喜你，通过http://localhost:8888/已经能够正常访问本地部署的项目地址了

5：与大模型对话时提示超时或请求失败

如果在你进入创建智能体、应用时，红框部分没有下拉框，或者是没有可选择的大模型，那么就说明你在前面的步骤中配置的大模型参数存在问题，要么是baseurl错了，要么是模型错了

此时你在右边与创建的智能体对话会提示请求失败

在解决上述所有问题之后，你的智能体已经能够进行对话了，并且能够正常的创建和发布，此时还会有什么问题呢；更大的坑还在后面

第四步  知识库相关的疑难杂症

问题介绍

大部分智能体都会用到一个东西，那就是知识库

创建一个知识库，然后准备上传文件

在上传文件时，我们需要关注框选的部分

先思考一下：

我们上传的文件类型是什么？如何AI如何识别文件中的元素？

答案是：向量模型

在前面的步骤中，我们配置了项目中对话交互使用的模型，但是他们基本用于意图识别，对话交流，并不具备识别文件和其中元素的功能，所以我们需要额外配置一个用于处理文件的大模型，并由他将识别的数据保存在milvusdb/milvus中

而milvusdb/milvus，你可以查看你的docker，里面已经在本地部署好了

如何配置向量模型

打开前文中提到的.env文件，找到Settings for Embedding，这里使用ark方式，理论上字节自定义的接入点也支持openai的方式

# Settings for Embedding
# The Embedding model relied on by knowledge base vectorization does not need to be configured
# if the vector database comes with built-in Embedding functionality (such as VikingDB). Currently,
# Coze Studio supports three access methods: openai, ark, ollama, and custom http. Users can simply choose one of them when using
# embedding type: openai / ark / ollama / http
export EMBEDDING_TYPE="ark" # 这里配置我们使用哪种方式调用向量模型，参数就是上一行中的4种类型
export EMBEDDING_MAX_BATCH_SIZE=100
# openai embedding #如果选择使用openai方式，则需要配置下面这些行
export OPENAI_EMBEDDING_BASE_URL=""    # (string) OpenAI base_url
export OPENAI_EMBEDDING_MODEL=""       # (string) OpenAI embedding model
export OPENAI_EMBEDDING_API_KEY=""     # (string) OpenAI api_key
export OPENAI_EMBEDDING_BY_AZURE=false  # (bool) OpenAI by_azure
export OPENAI_EMBEDDING_API_VERSION="" # OpenAI azure api version
export OPENAI_EMBEDDING_DIMS=1024      # (int) 向量维度
export OPENAI_EMBEDDING_REQUEST_DIMS=1024

# ark embedding #如果选择使用ark方式，则需要配置下面这些行
export ARK_EMBEDDING_MODEL="ep-xxxxxxxxxxxxxxxxxx"
export ARK_EMBEDDING_AK="48xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export ARK_EMBEDDING_DIMS="2048" # (int) 向量维度,根据你的向量模型进行配置，看你的向量模型支持多少
export ARK_EMBEDDING_BASE_URL="https://ark.cn-beijing.volces.com/api/v3/"

# ollama embedding #如果选择使用ollama 方式，则需要配置下面这些行
export OLLAMA_EMBEDDING_BASE_URL=""
export OLLAMA_EMBEDDING_MODEL=""
export OLLAMA_EMBEDDING_DIMS=""

# http embedding #如果选择使用本地部署的向量模型，则需要配置下面这些行
export HTTP_EMBEDDING_ADDR=""
export HTTP_EMBEDDING_DIMS=1024

依旧参考上文中创建接入点的部分，创建一个新的接入点，但是！

模型一定要选择 Doubao-embedding-large | text-250515

当前尝试了好几个在线的向量模型，接入后都会报错，导致在向知识库上传文件时卡在10%，甚至干脆0%，或者在进度达到50%后归零

其他的就是配置问题了

ARK_EMBEDDING_MODEL：填写申请的接入点Id

ARK_EMBEDDING_AK：填写管理里复制的Key

ARK_EMBEDDING_BASE_URL：主要url不要以 / 结尾，这也会导致请求向量模型的时候出现错误

如果你在上传文件的时候提示，请求向量模型报错，那么一定是以上的配置出现了错误，当你这个配置都ok之后，那么进行文件上传的时候就一定可以了？？？吗？

OCR配置

回到上传文件的截图中，有一个

当你上传的文件中存在复杂的元素，例如pdf和docx中插入了图片，就需要使用到OCR扫描件，当然。这个也需要进行配置，如果在没有配置OCR的情况下又勾选了这个选项也会出现上传文件卡在10%的问题

找到.env中的Settings for OCR，然后前往火山申请接入的地址，这里也可以参考官方文档5. 基础组件配置 · coze-dev/coze-studio Wikihttps://github.com/coze-dev/coze-studio/wiki/5.-%E5%9F%BA%E7%A1%80%E7%BB%84%E4%BB%B6%E9%85%8D%E7%BD%AE接入申请的地址也顺便贴出来人像人体https://console.volcengine.com/ai/ability/info/3 在这里申请成功之后会直接给出AK和SK，直接填入即可

# ve ocr
export VE_OCR_AK="Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
export VE_OCR_SK="Wxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

追加一个错误的处理


2025/08/13 更新
在上传资源库文件时提示
err: failed to get resource sts token. err=EmptyStaticCreds: static credentials are empty
原因是源代码中获取配置文件中时使用的key与实际配置的不一样
在前些天拉代码的时候都是使用的ARK_EMBEDDING_AK，今天官方抽风想换个名但是只提交了配置文件并修改了官方文档，源码没改或者改了没提交
代码读取配置

实际配置文件

所以这样就很清楚了，解决方案有两个
1：修改配置文件中参数名为ARK_EMBEDDING_AK
或者改源码将
arkEmbeddingAK = os.Getenv("ARK_EMBEDDING_AK")
改为
arkEmbeddingAK = os.Getenv("ARK_EMBEDDING_API_KEY")
错误已经提交给官方，估计提交完代码就修复了

# windows
Logo
DAMO开发者矩阵

DAMO开发者矩阵，由阿里巴巴达摩院和中国互联网协会联合发起，致力于探讨最前沿的技术趋势与应用成果，搭建高质量的交流与分享平台，推动技术创新与产业应用链接，围绕“人工智能与新型计算”构建开放共享的开发者生态。

更多推荐

cover

精准饲喂系统：养猪巡检机器人与智能饲喂器联动，开启智慧养猪新模式

avatar DAMO开发者矩阵
cover

2026科技风向标：大模型、Agent、具身智能，谁将引领AI新纪元？

avatar DAMO开发者矩阵
cover

AI赋能中国智造：制造业10大变革场景深度解析！引领工业4.0新风口！

avatar DAMO开发者矩阵