开源版coze本地部署与试用
AI-摘要
Tianli GPT
AI初始化中...
介绍自己
生成本文简介
推荐相关文章
前往主页
前往tianli博客
开源版coze本地部署与试用
官方部署文档：
https://github.com/coze-dev
https://github.com/coze-dev/coze-studio
服务器信息：
主机名
IP
操作系统
规格
GPU情况
备注
ksp-registry
172.20.0.22
Ubuntu 20.04.3 LTS
1
- 2025-08-25 08:26:13
一、背景与环境信息
-
官方部署文档：
-
服务器信息：
主机名 IP 操作系统 规格 GPU情况 备注 ksp-registry 172.20.0.22 Ubuntu 20.04.3 LTS 12c20g+300G NVIDIA A40*1
此文档使用docker-compose的方式来部署coze。
二、部署操作
2.1 下载安装源码
# 克隆代码
root@ksp-registry:/opt/code_repos# git clone -b release/v0.2.4 https://github.com/coze-dev/coze-studio.git
<p>SHELL
2.2 执行部署
#（1）启动部署前，需先确定几个可用模型。从模板目录复制 doubao-seed-1.6 模型的模版文件，并粘贴到配置文件目录
# 需要什么模型就复制什么对应厂商的配置文件并修改，一个配置文件对应一个具体的模型
# 模型配置文档：https://github.com/coze-dev/coze-studio/wiki/3.-%E6%A8%A1%E5%9E%8B%E9%85%8D%E7%BD%AE
cp backend/conf/model/template/model_template_ollama.yaml backend/conf/model/ollama-gemma3-4b.yaml
#在配置文件目录下，修改模版文件
cd backend/conf/model
#（2）修改文件ollama-gemma3-4b.yaml
vi ollama-gemma3-4b.yaml
<p>SHELL
1 id: 68010 #整个coze环境中，每个模型id必须唯一，且最好不要修改
2 name: gemma3-4b #可以修改名字
...
49 meta:
50 protocol: ollama
51 capability:
52 function_call: true
53 input_modal:
54 - text
55 input_tokens: 128000
56 json_mode: false
57 max_tokens: 128000
58 output_modal:
59 - text
60 output_tokens: 16384
61 prefix_caching: false
62 reasoning: false
63 prefill_response: false
64 conn_config:
65 base_url: "http://172.20.0.22:11434" #ollama提供服务的base url，最好使用IP
66 api_key: "" #我的ollama服务没有启用api key。如果使用qwen等模型需要
67 timeout: 0s
68 model: "gemma3:4b" #ollama中管理的模型名称
69 temperature: 0.6
70 frequency_penalty: 0
71 presence_penalty: 0
72 max_tokens: 4096
73 top_p: 0.95
74 top_k: 20
75 stop: []
76 custom: {}
77 status: 0
...
377 coze-web:
378 # build:
379 # context: ..
380 # dockerfile: frontend/Dockerfile
381 image: opencoze/web:latest
382 container_name: coze-web
383 restart: always
384 ports:
385 - "8888:80"
386 # - "443:443" # SSL port (uncomment if using SSL)
387 volumes:
388 - ./nginx/nginx.conf:/etc/nginx/nginx.conf:rw # Main nginx config ###从ro修改为rw
389 - ./nginx/conf.d/default.conf:/etc/nginx/conf.d/default.conf:rw # Proxy config ###从ro修改为rw（否则无法修改此文件）
390 # - ./nginx/ssl:/etc/nginx/ssl:ro # SSL certificates (uncomment if using SSL)
391 depends_on:
392 - coze-server
393 networks:
394 - coze-network
...
YAML
#（3）修改docker-compose.yml 文件
#修改minio容器使用的镜像为minio/minio，否则coze-minio一直启动失败后反复重启、同时无日志信息可查看
root@ksp-registry:/opt/code_repos/coze-studio/docker# cp docker-compose.yml docker-compose.yml.bak
root@ksp-registry:/opt/code_repos/coze-studio/docker# vi docker-compose.yml
...
162 minio:
163 # image: minio/minio:RELEASE.2025-06-13T11-33-47Z-cpuv1
164 image: minio/minio
...
SHELL
#（4）复制.env文件
root@ksp-registry:/opt/code_repos/coze-studio/docker# cp .env.example .env
#修改.env文件，否则使用"服务器IP:8888"访问web界面并注册时会报错、失败，日志提示“connect() failed (111: Connection refused) while connecting to upstream”
root@ksp-registry:/opt/code_repos/coze-studio/docker# vi .env
1 # Server
2 #export LISTEN_ADDR="http://localhost${LISTEN_ADDR}"
3 export LISTEN_ADDR="0.0.0.0:8888"
...
SHELL
#（5）启动服务、查看所有相关容器
root@ksp-registry:/opt/code_repos/coze-studio/docker# docker-compose up -d
root@ksp-registry:/opt/code_repos/coze-studio/docker# docker-compose ps
SHELL
https://s2.loli.net/2025/08/14/TSnruVeDczq7ER8.png
2.3 登录web界面
浏览器访问 http://172.20.0.22/ 即可打开 Coze Studio。其中 8888 为后端监听端口。
输入邮箱与密码注册后使用。
2.4 插件配置
参考：配置官方插件工具
https://s2.loli.net/2025/08/14/1Ce7S4WFJRDXzUy.png
2.5 配置基础组件
上传组件(暂未成功)
#1.设置上传组件类型。
root@ksp-registry:/opt/code_repos/coze-studio-v0.2.4/docker# vi .env
export FILE_UPLOAD_COMPONENT_TYPE="storage"
<p>#2.为上传组件添加秘钥等配置。 同样在 docker 目录的 .env 文件中，根据组件类型填写以下配置。
#使用默认的minio。
#2.1. 在 Coze studio 项目的 docker/.env 文件中，FILE_UPLOAD_COMPONENT_TYPE 设置为 storage。
#2.2. 在 Storage component 区域，设置 STORAGE_TYPE 为 minio。
#2.3. 在 MiniO 区域，我稍微做了一个参数MINIO_ENDPOINT的修改（本来想配置成外网映射后的地址，但重启服务时报错：init minio client failed check bucket opencoze exist failed Get "http://175.6.40.93:61872/opencoze/?location=": dial tcp 175.6.40.93:61872: i/o timeout，不知如何处理，暂放弃）</p>
<h1 id="MiniIO">MiniIO</h1>
<p>export MINIO_ROOT_USER=minioadmin
export MINIO_ROOT_PASSWORD=minioadmin123
export MINIO_DEFAULT_BUCKETS=milvus
export MINIO_AK=$MINIO_ROOT_USER
export MINIO_SK=$MINIO_ROOT_PASSWORD
#export MINIO_ENDPOINT="minio:9000"
export MINIO_ENDPOINT="172.20.0.22:49402"
#export MINIO_ENDPOINT="175.6.40.93:61872"
export MINIO_API_HOST="http://${MINIO_ENDPOINT}"</p>
<p>SHELL
配置向量化模型（Embedding）
Coze Studio 开源版支持自定义设置知识库向量化依赖的 Embedding 模型，使知识库的向量化环节效果更符合指定场景的业务需求。
此处向量化存储模块使用默认的milvus，按照如下方式设置 Embedding 模型。
#编辑.env
root@ksp-registry:/opt/code_repos/coze-studio/docker# vi .env
<p>SHELL
...
# 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 four 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"
export EMBEDDING_TYPE="ollama"
# ollama embedding
export OLLAMA_EMBEDDING_BASE_URL="http://172.20.0.22:11434" # (string, required) Ollama embedding base_url
export OLLAMA_EMBEDDING_MODEL="nomic-embed-text:latest" # (string, required) Ollama embedding model
export OLLAMA_EMBEDDING_DIMS="768" # (int, required) Ollama embedding dimensions
...
TOML
#重启服务
root@ksp-registry:/opt/code_repos/coze-studio/docker# docker-compose up -d --force-recreate --no-deps coze-server
SHELL
配置AI 生成模型（Model）
Coze Studio 知识库提供文本转 SQL（NL2SQL）、一句话生成 Query（Message to Query）、图像标注（Image Annotation）、workflow 大模型节点召回知识库等功能，这些功能统一依赖于 Coze Studio 预配置的 AI 生成模型。在 Coze Studio 开源版中使用这些功能前，你需要先配置这个AI 生成模型。
- 此处配置的 AI 生成模型只在 NL2SQL、Message to Query、Image Annotation、Workflow knowledge recall 四个场景中生效。
- 如果需要在不同场景中使用不同模型，你可以通过添加前缀来针对特定场景应用特定配置，例如图片标注场景需要配置视觉模型，其余场景不需要，则可以新增
export IA_BUILTIN_CM_OPENAI_MODEL="xxx"来配置图片标注场景专用的视觉模型。
#编辑.env
root@ksp-registry:/opt/code_repos/coze-studio/docker# vi .env
<p>SHELL
...
# Model for knowledge nl2sql, messages2query (rewrite), image annotation, workflow knowledge recall
# add prefix to assign specific model, downgrade to default config when prefix is not configured:
# 1. nl2sql: NL2SQL_ (e.g. NL2SQL_BUILTIN_CM_TYPE)
# 2. messages2query: M2Q_ (e.g. M2Q_BUILTIN_CM_TYPE)
# 3. image annotation: IA_ (e.g. IA_BUILTIN_CM_TYPE)
# 4. workflow knowledge recall: WKR_ (e.g. WKR_BUILTIN_CM_TYPE)
# supported chat model type: openai / ark / deepseek / ollama / qwen / gemini
#export BUILTIN_CM_TYPE="ark"
export BUILTIN_CM_TYPE="ollama"
# type ollama
export BUILTIN_CM_OLLAMA_BASE_URL="http://172.20.0.22:11434"
export BUILTIN_CM_OLLAMA_MODEL="qwen2.5:32b"
...
TOML
#重启服务
root@ksp-registry:/opt/code_repos/coze-studio/docker# docker-compose up -d --force-recreate --no-deps coze-server
SHELL
设置 OCR 组件
Coze Studio 知识库的 ORC 能力由火山引擎 OCR 产品提供服务。在 Coze Studio 开源版中开启 OCR 功能前，应先开通火山引擎 OCR 产品，并在本地项目中填写 ORC 配置，将 OCR 组件的 AK、SK 配置为火山引擎的密钥对。
访问 Hi，这里是API服务：通用文字识别开通（或试用。试用只是QPS上限为1，比正式开通时的10小）字节跳动火山引擎的通用文字识别功能。未开通时如下图。其中，QPS（Queries Per Second）上限 是指该服务每秒能处理的最大请求量，是衡量服务并发处理能力的关键指标。
https://s2.loli.net/2025/08/14/UL8R6Abha9GVYWI.png
试用或正式开通后，参考 Access Key（密钥）管理 获取火山账号的 AK 和 SK。
然后配置到.env文件中。
#编辑.env
root@ksp-registry:/opt/code_repos/coze-studio/docker# vi .env
<p>SHELL
...
# Settings for OCR
# If you want to use the OCR-related functions in the knowledge base feature，You need to set up the OCR configuration.
# Currently, Coze Studio has built-in Volcano OCR.
# Supported OCR types: `ve`, `paddleocr`
export OCR_TYPE="ve"
# ve ocr
export VE_OCR_AK="AKLTZWI1ZmQ5YzUxNjVkNDQ3N2FjN2Nk**************"
export VE_OCR_SK="TVRRMllqRTFOelpoT1dKbE5EQXpOR0pt****************************"
...
TOML
#重启服务
root@ksp-registry:/opt/code_repos/coze-studio/docker# docker-compose up -d --force-recreate --no-deps coze-server
SHELL
2.6 创建知识库
https://s2.loli.net/2025/08/14/KsYRJTi5IdmQq1G.png
https://s2.loli.net/2025/08/14/yNZoQEdejDnk83p.png
https://s2.loli.net/2025/08/14/tWd3EHeYkv4U8CA.png
https://s2.loli.net/2025/08/14/boJ2U85KDOyrxBf.png
等待文档的处理进度达到100%，才可使用此知识库。
2.7 创建智能体
https://s2.loli.net/2025/08/14/z4iI1AygYstDKlT.png
https://s2.loli.net/2025/08/14/wvYAaSHzF79kQXG.png
https://s2.loli.net/2025/08/14/tA5ivmg9yxMkhnr.png
相关系统提示词如下：
# 角色：{#InputSlot placeholder="角色名称" mode="input"#}领克汽车手册使用助手{#/InputSlot#}
{#InputSlot placeholder="角色概述和主要职责的一句话描述" mode="input"#}领克汽车手册使用助手对《领克汽车用户手册》非常熟悉，能够回复用户关于此品牌汽车的相关信息与操作步骤{#/InputSlot#}
<h2 id="目标：">目标：</h2>
<p>{#InputSlot placeholder="角色的工作目标，如果有多目标可以分点列出，但建议更聚焦1-2个目标" mode="input"#}1. 可以回复关于领克汽车的相关介绍信息
2. 也可以告诉用户关于使用领克汽车的操作细节
3. 可以告诉用户使用领克汽车过程中的注意事项{#/InputSlot#}</p>
<h2 id="技能：">技能：</h2>
<ol>
<li>{#InputSlot placeholder="为了实现目标，角色需要具备的技能1" mode="input"#}具有分析问题的能力，能快速准确地识别用户问题的关键{#/InputSlot#}</li>
<li>{#InputSlot placeholder="为了实现目标，角色需要具备的技能2" mode="input"#}识别出问题后，能够快速从知识库中现有的文档中搜索相关内容{#/InputSlot#}</li>
<li>{#InputSlot placeholder="为了实现目标，角色需要具备的技能3" mode="input"#}搜索到相关内容后，能将这些内容作为上下文，对它们进行提炼与综合，以以精简的内容回复用户的问题{#/InputSlot#}</li>
<li>{#InputSlot placeholder="为了实现目标，角色需要具备的技能3" mode="input"#}请尽量以清晰明了的形式对回复内容进行排版，如果有必要可以分点阐述{#/InputSlot#}</li>
<li>{#InputSlot placeholder="为了实现目标，角色需要具备的技能3" mode="input"#}请尽量指出回复内容的出处{#/InputSlot#}</li>
</ol>
<h2 id="输出格式：">输出格式：</h2>
<p>{#InputSlot placeholder="如果对角色的输出格式有特定要求，可以在这里强调并举例说明想要的输出格式" mode="input"#}请以markdown格式给出回复内容。{#/InputSlot#}</p>
<h2 id="限制：">限制：</h2>
<ul>
<li>{#InputSlot placeholder="描述角色在互动过程中需要遵循的限制条件1" mode="input"#}对于你不知道的问题、在知识库中没有找到相关内容的问题，请直接回复“不好意思，这个问题我暂时不知道”，严禁凭空捏造回复内容{#/InputSlot#}</li>
<li>{#InputSlot placeholder="描述角色在互动过程中需要遵循的限制条件2" mode="input"#}不能辱骂、恐吓或威胁用户，回复内容中请规避色情与暴力相关内容{#/InputSlot#}</li>
</ul>
<p>TOML
测试无误后，点击右上角的“发布”按钮进行发布。
四、问题
4.1 创建知识库并上传文件时，文档反复“处理中”
2025年8月20日，使用main分支部署后，创建知识库并上传文件时，页面上显示文档反复“处理中”。
https://s2.loli.net/2025/08/20/Li1tUJqC9wyZIez.png
coze-server 容器日志反复打印如下信息：
https://s2.loli.net/2025/08/20/h7IWD3K6xEaLHTp.png
解决办法：我下载release/v0.2.4，重新部署。
4.2 知识库文档向量化时提示“SearchStore operation failed: store search store failed”
从nomic-embed-text:latest转到使用bge-m3:latest，知识库中上传文件时解析到50%左右提示“code=105000004 message=SearchStore operation failed: store search store failed, err: [Store] upsert failed, the length(102400) of float data should divide the dim(768)”
解决办法：
参考“Issue #537 · coze-dev/coze-studio”，停止所有coze容器，然后删除data整个目录，修改好.env文件然后启动coze服务。
本文是原创文章，采用 CC BY-NC-ND 4.0 协议，完整转载请注明来自 程序员小航
评论
匿名评论
隐私政策
你无需删除空行，直接评论以获取最佳展示效果
