Coze Studio 本地部署指南：集成 Ollama 与 OpenRouter

前言：搭建你自己的 AI Agent 工作室

Coze Studio 是由字节跳动开源的一款低代码 AI Agent 开发平台。它提供了一套可视化的工具集，让开发者能够以极少的代码量快速构建、调试和部署 AI 智能体、应用程序和工作流。这种方式不仅降低了技术门槛，也为打造高度定制化的 AI 产品提供了坚实的基础。

所谓 AI Agent，即能够理解用户意图、自主规划并执行复杂任务的智能程序。在本地部署 Coze Studio，意味着你可以完全控制自己的数据和模型，为开发和实验提供了绝佳的私密性与灵活性。

平台后端采用 Golang，前端为 React + TypeScript 组合，整体基于微服务与领域驱动设计（DDD）架构，保证了系统的高性能与高扩展性。

本文将指导你完成 Coze Studio 开源版的本地部署，并配置连接本地 Ollama 以及 OpenRouter 的模型服务。

1. 安装 Ollama：拥有你的私人大模型

Ollama 是一个轻量级、可扩展的本地大语言模型运行框架。它极大地简化了在个人计算机上运行 Llama 3, Qwen 和 Gemma 等模型的流程。拥有 Ollama，你可以在完全离线的环境中，利用 AI 处理私有数据，无需依赖任何第三方云服务，兼顾安全与成本。

访问 https://ollama.com/，根据你的操作系统（macOS, Linux, Windows）下载并安装对应的客户端。安装过程非常直观，遵循向导即可。

拉取模型

安装完成后，需要从 Ollama 的模型库中下载一个模型到本地。以 Qwen 模型为例，其模型库提供了不同参数规模的版本。

(图片来源: https://ollama.com/library/qwen)

不同规模的模型对内存（RAM）有不同要求，这也是选择时需要考虑的因素：

• 7B 模型：建议 16GB RAM
• 14B 模型：建议 32GB RAM
• 72B 模型：建议 64GB RAM

很多模型还提供了量化 (Quantization) 版本。量化是指在保持模型性能的同时，通过降低权重精度来减小模型体积和内存占用的技术，让模型能在消费级硬件上更高效地运行。

打开终端（Terminal 或命令提示符），输入以下命令来拉取一个中等规模的模型：

ollama run qwen:14b

此命令将自动从云端下载并解压指定的模型。具体用时取决于网络状况。

2. 安装 Docker：应用部署的标准化工具

Docker 是一种容器化技术，它将应用程序及其所有依赖项打包到一个标准的、可移植的“容器”中。简单来说，Docker 就像一个标准化的集装箱，而 Coze Studio 就是我们要装载的货物。通过 Docker，我们可以轻松地在任何支持 Docker 的机器上运行 Coze Studio，无需担心复杂的环境配置和依赖冲突。

访问 https://www.docker.com/，下载并安装 Docker Desktop。它同样为 macOS, Linux 和 Windows 提供了图形化的安装界面。

3. 本地部署 Coze Studio

3.1 环境要求

• 硬件：确保机器至少拥有 2 核 CPU 和 4 GB 内存。
• 软件：提前安装 Docker、Docker Compose，并确保 Docker 服务已启动。

3.2 获取 Coze Studio 源码

若本机已安装 Git，执行 git clone 命令是获取源码最直接的方式。

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

如果未安装 Git，也可以直接从 GitHub 页面下载 ZIP 压缩包。

3.3 为 Coze Studio 配置模型

Coze Studio 支持多种模型服务，包括 Ark（火山方舟）、OpenAI、DeepSeek、Claude、Ollama、Qwen 和 Gemini。

使用代码编辑器打开 coze-studio 项目。在 backend/conf/model/template 目录下，存放着不同模型服务的配置模板。

配置本地 Ollama 模型

1. 将 model_template_ollama.yaml 模板文件复制到 backend/conf/model 目录。
2. 将其重命名，例如 model_ollama_qwen14b.yaml。
3. 编辑该文件，以配置 qwen:14b 模型为例：

注意：id 字段必须是全局唯一的非零整数。对于已经上线的模型，切勿修改其 id，否则会导致调用失败。配置前，可以运行 ollama list 命令查看本地已有的模型。

配置 OpenRouter 模型

OpenRouter 是一个模型聚合服务，它允许开发者通过统一的 API 接口调用来自不同供应商的多种模型，简化了 API Key 的管理和模型切换流程。

1. 将 model_template_deepseek.yaml 模板文件复制到 backend/conf/model 目录。
2. 重命名为 model_openrouter_ds_v2.yaml。
3. 编辑文件，以配置 DeepSeek-V2 为例，并填入从 OpenRouter 获取的 api_key。

如果还没有 OpenRouter 的 API Key，可以访问其官网注册并创建。

3.4 部署并启动服务

配置好模型后，在终端中进入项目的 docker 目录，然后运行以下命令：

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

--profile '*' 参数会确保 docker-compose.yml 文件中定义的所有服务（包括可选服务）都会被启动。首次部署会拉取并构建镜像，耗时较长。

启动后，可以在 Docker Desktop 的界面中查看所有服务的状态。当 coze-server 服务的状态指示灯变为绿色，即表示 Coze Studio 已成功启动。

每次修改配置文件后，都需要执行以下命令重启服务以使配置生效：

docker compose --profile '*' restart coze-server

3.5 使用 Coze Studio

服务启动后，在浏览器中访问 http://localhost:8888/。

首次使用时，输入邮箱和密码注册新用户。成功登录后，点击右上角的 Create 按钮，选择 Create agent。

为你的 Agent 命名并确认。

进入 Agent 设计界面后，点击模型列表，即可看到已配置的所有模型。

现在，可以通过右侧底部的聊天框来测试模型是否正常工作。

1. 测试本地 Ollama qwen:14b 服务

   

2. 测试线上 OpenRouter DeepSeek-V2 服务

   

如果遇到调用异常，可以通过 Docker Desktop 查看 coze-server 容器的日志来进行排查。