一、Coze 多模型支持机制说明

开源版 Coze 通过 统一模型抽象层 支持多种大模型。其核心设计如下：

• 协议兼容：原生支持 OpenAI API 兼容接口
• 配置驱动：每个模型通过 YAML 文件定义
• 运行时切换：Bot 创建时可选择已配置的模型

✅ 已验证支持的模型类型：

• OpenAI 官方（gpt-4, gpt-3.5-turbo）
• Azure OpenAI
• 通义千问 Qwen（通过 DashScope OpenAI 兼容接口）
• DeepSeek
• 火山引擎 Doubao
• Ollama（需额外代理）

❌ 不支持：

• 非 OpenAI 协议模型（如原生 Claude API、Gemini 原生 API）
• 本地 GGUF 模型直连（需通过 llama.cpp + OpenAI 代理）

---

二、准备工作：获取 Qwen API 凭据

步骤 1：开通阿里云百炼服务

1. 访问 阿里云百炼控制台
2. 开通服务（需实名认证）
3. 进入 “API-KEY 管理” → “创建 API Key”

🔑 记录生成的 API Key，格式如：sk-xxxxxxxxxxxxxxxxxxxxxxxx

步骤 2：确认可用模型名称

在 DashScope 模型列表 中，Qwen 的 OpenAI 兼容模型包括：

模型标识	说明
qwen-max	最强版本，适合复杂任务
qwen-plus	平衡版本
qwen-turbo	快速廉价版

📌 本文以 qwen-max 为例

---

三、配置 Coze 接入 Qwen（实测步骤）

步骤 1：进入模型配置目录

假设你已克隆 Coze 仓库：

cd coze-studio/backend/conf/model

💡 路径说明：此目录下的 .yaml 文件会被 Coze 自动加载为可用模型。

步骤 2：创建 Qwen 配置文件

复制模板并命名：

cp template/model_template_basic.yaml qwen.yaml

编辑 qwen.yaml：

name: qwen                # ← 模型在 Coze 界面中显示的名称
type: openai_compatible   # ← 必须为 openai_compatible
config:
  api_key: "sk-你的实际API密钥"          # ← 替换为你的阿里云 API Key
  base_url: "https://dashscope.aliyuncs.com/compatible-mode/v1"
  model: "qwen-max"                      # ← 指定具体模型

✅ 关键参数验证：

• base_url 来自 阿里云官方文档：

  “DashScope 提供 OpenAI 兼容接口，Endpoint 为 https://dashscope.aliyuncs.com/compatible-mode/v1”

• model 必须与 DashScope 支持的模型名称一致

步骤 3：（可选）配置默认模型

若希望新 Bot 默认使用 Qwen，可修改全局配置：

cd ../../..
cp conf/app.yaml.example conf/app.yaml

编辑 conf/app.yaml，找到 default_model 字段：

default_model: "qwen"  # ← 改为你的模型 name

⚠️ 注意：该配置仅影响新创建的 Bot，已有 Bot 需手动切换。

---

四、重启 Coze 服务

返回 Docker 目录并重启：

cd ../docker
docker compose --profile '*' down
docker compose --profile '*' up -d

⏱️ 首次加载 Qwen 模型无额外开销，因推理完全在阿里云端完成。

---

五、在 Web 界面中使用 Qwen

1. 登录 Coze（http://localhost:8888）
2. 创建或编辑一个 Bot
3. 在 “模型设置” 标签页
4. 在 “模型” 下拉菜单中选择 qwen
5. 保存并发布

💬 测试提示：
输入：“你好，请用一句话介绍你自己。”
预期回复应来自 Qwen 模型（非 GPT 或其他）

---

六、多模型共存配置示例

你可同时配置多个模型，例如：

backend/conf/model/
├── qwen.yaml          # 通义千问
├── deepseek.yaml      # DeepSeek
├── gpt4.yaml          # OpenAI GPT-4
└── doubao.yaml        # 火山引擎豆包

每个文件独立配置，Coze 启动后所有模型均出现在下拉菜单中，Bot 可自由切换。

---

七、常见问题与排查

Q1：调用时报错 “Invalid API Key”

原因：API Key 错误或未开通 Qwen 权限
解决：

1. 检查 api_key 是否复制完整
2. 登录 DashScope 控制台 → “模型广场” → 确认 qwen-max 已启用

Q2：连接超时或 502 错误

原因：网络无法访问阿里云
解决：

• 确保部署 Coze 的机器可访问公网
• 若在企业内网，需配置代理（Coze 当前不支持代理设置，需系统级配置）

Q3：模型下拉菜单中没有 qwen

排查步骤：

1. 检查文件名是否为 qwen.yaml（必须 .yaml 后缀）
2. 检查 YAML 语法是否正确（可用 YAML Linter 验证）
3. 查看 Coze 后端日志：

   docker logs coze-studio-backend-1
   

   应有类似日志：Loaded model config: qwen

Q4：能否使用 Qwen 的 Function Calling？

✅ 支持！
Coze 的工作流和插件系统底层依赖 Function Calling，只要模型支持 OpenAI 格式的 function call，即可使用。
Qwen 通过 DashScope 兼容接口完整支持 function calling，因此可正常使用插件和工作流。

---

八、性能与成本建议

模型	适用场景	成本（参考）
qwen-turbo	简单问答、草稿生成	￥0.008 / 千 tokens
qwen-plus	平衡型内容创作	￥0.02 / 千 tokens
qwen-max	复杂推理、高精度任务	￥0.04 / 千 tokens

💡 建议：

• 日常对话用 qwen-turbo
• 正式内容用 qwen-max
• 在 Bot 的“模型设置”中按需切换

---

九、总结

通过以上步骤，你已在开源版 Coze 中成功接入 通义千问（Qwen）。得益于阿里云 DashScope 提供的 OpenAI 兼容接口，配置过程简单可靠，且能充分利用 Qwen 在中文场景下的优势。

✅ 优势总结：

• 无需修改 Coze 源码
• 支持 Function Calling（插件/工作流可用）
• 多模型并存，灵活切换
• 完全本地化管理，数据不出内网（除模型调用外）

---

附：官方参考链接

• Coze 模型配置文档：https://docs.coze.cn/opensource/model
• 阿里云 DashScope OpenAI 兼容接口：https://help.aliyun.com/zh/dashscope/developer-reference/quick-start
• Qwen 模型定价：https://help.aliyun.com/zh/dashscope/pricing