手头刚好有个需求把扣子Coze里的机器人接到团队自己微调过的模型上。起初我也以为要等官方把某个新模型加进模型列表折腾一圈才发现Coze 的“自定义模型”入口配合一个 API 聚合服务就能比较简单地把各种模型接进来。下面这篇文章就用 Ace Data Cloud 当例子讲清楚怎么配置、怎么在工作流里用、以及哪些坑值得提前避开。自定义模型这事听起来很技术其实本质不复杂Coze 本身是个“编排层”负责对话管理、插件、知识库和工作流至于最后回答你的那个“大脑”完全可以换成你自己选的模型服务。Ace Data Cloud 这类平台解决的是“协议统一”的问题让 Coze 不用关心每个模型厂商的私有接口格式只需要认一套 OpenAI 兼容的请求方式。适合谁看如果你想把 Coze 默认列表外的模型接进来或者手头有微调过的内部模型想放到 bot 里又或者想统一管理多个模型供应商的 API Key这篇记录可以直接拿来参考。1. 为什么要费劲接自定义模型1.1 默认模型池解决不了的三类需求Coze 默认已经提供了一批模型开箱即用对大多数场景也够用。但“自定义模型”并不是用来替代默认入口的它解决的是默认池覆盖不到的三类需求。第一类模型根本不在列表里。比如某个新出的推理模型或者某个在行业评测里表现不错但你不想等官方适配的模型Coze 的模型列表里没有就只能通过自定义模型方式接入。第二类模型是你的私有资产。团队微调过的垂直领域模型比如专门做客服话术、法律文书、代码检查的模型这类模型只会部署在你自己的服务上不可能出现在 Coze 的默认列表里。你想在 Coze 里用上它唯一的路径就是把它封装成一个 HTTP API再填进自定义模型。第三类公司已经有了统一的模型网关。很多团队会自建或采购一个模型网关所有产品和渠道都从同一个网关拿模型能力方便统一计费、统一审计、统一限流。这种情况下Coze 这边也不需要每家模型配一个 Key而是直接把网关当成一个自定义模型接进来。我自己的项目属于第二类和第三类的混合一边有微调后的内部模型一边想统一走网关避免在多个平台里维护一堆密钥。自定义模型这个入口正好把两件事一起解决了。1.2 一个中转服务解决协议碎片化问题各家大模型的 API 协议并不统一。有的是 OpenAI 兼容格式有的走 Azure 那套有的要求复杂签名还有的返回结构差别很大。Coze 自定义模型不可能为每个厂商写适配器所以它只支持几种主流协议OpenAI 协议、Azure OpenAI 协议、AWS 鉴权模式。你只要按其中一种格式把接口配好Coze 就能把消息发出去并解析返回。Ace Data Cloud 这类聚合服务的价值就在这里。它不是自己训练模型而是把多家模型供应商的 API 统一成一套 OpenAI 兼容格式让你用一个 API Key 访问多个模型。这样做有三个直接好处Coze 侧只需要填一个 Endpoint 和一个 API Key改模型就改请求体里的 model 字段不用重新配置整个连接。计费和日志集中在网关后台能看到每次请求用了哪个模型、消耗了多少 token、响应延迟是多少。如果某个模型服务不稳定网关侧可以配置 fallback不至于让 Coze 机器人直接瘫痪。用人话说Ace Data Cloud 像是“模型界的插座转换头”。Coze 只认识一种插孔规格但你想插很多不同规格的电器那就需要一个转换头把对面全部统一成同一规格。2. 接入前的准备工作和概念清单2.1 用得到的东西真正动手之前先把下面这些东西准备好避免配到一半才发现缺材料Coze 账号并且已经创建好一个机器人应用Ace Data Cloud 账号并且已生成有效的 API Key一个你想要使用的模型 ID这个 ID 必须在网关侧真实存在且已开通如果模型是付费的网关账户里需要有余额或可用配额还有一个容易被忽略的点Coze 的自定义模型请求是云端发起的所以你的模型接口必须是从公网可访问的 HTTPS 地址不能是localhost或者内网地址。这个后面会单独展开。2.2 Endpoint、API Key、Model ID 到底谁是谁很多新手第一次配置自定义模型时会被这三个名词搞混。我直接做一个对照表名词是什么类比在哪里拿Endpoint模型服务接收请求的接口地址通常是https://xxx/v1/chat/completions这种商场的收银台位置网关平台文档或控制台API Key访问接口时用来证明身份的密钥会员卡网关控制台的密钥管理页面Model ID本次调用具体路由到哪个模型的标识你点的菜名网关平台的模型列表重点在于Endpoint 决定“请求发到哪”API Key 决定“你有没有权限调用”Model ID 决定“具体用哪个模型”。三者各有分工不能互相替代。2.3 选模型的几个隐藏判断依据接入前选模型时不要只看“哪个模型聪明”。在 Coze 这种场景里有四个维度比单纯的“聪明”更影响最终体验上下文长度Coze 会把多轮对话历史拼进请求如果模型上下文窗口太小聊天稍微长一点就会报错或者被迫做截断。比如做客服机器人至少选 8K 以上上下文的模型。首字延迟你和机器人对话时感受到的“快慢”主要是首字延迟不是总生成时间。有些大模型效果好但首字特别慢在聊天场景里会显得很笨。是否支持工具调用Coze 的插件和工作流经常需要模型输出结构化的函数调用参数。如果模型不支持 function calling那即使接进来插件类节点也会很难用。计费模式不同模型的输入输出价格差异很大一天调用量上来之后成本差距可能从一个数量级起步。我见过不少团队只看模型榜单就选了个超大杯模型结果接入后既贵又慢日常任务根本用不上那么强的能力。更合理的做法是先把任务分类简单任务走便宜快速的小模型复杂任务才上大模型。3. 在 Coze 里配置 Ace Data Cloud 自定义模型3.1 先从 Ace Data Cloud 拿到三段连接信息配置的第一步是去 Ace Data Cloud 控制台拿到上一节说的三段信息。流程大致是这样的登录控制台后先到 API Key 或令牌管理页面创建一个新的 Key。创建时一般会要求填写备注比如“Coze-客服机器人”方便后面审计时分辨是哪个业务在调用。创建完成后把生成的密钥复制下来。注意这个 Key 通常只在创建时完整显示一次之后就只能重新创建。然后在平台文档或接入指南里找到 Chat Completions 的 Endpoint。大多数 OpenAI 兼容网关的路径都是/v1/chat/completions有些可能带前缀域名比如https://your-gateway.example.com/v1/chat/completions。最后在模型列表里确认你要用的 Model ID。这里一定要睁大眼睛看很多模型 ID 长得像内部代号比如deepseek-v3.1或者qwen-max-0125和你在页面上看到的“中文名”完全不一样。填错了接口会直接返回 model_not_found。3.2 在 Coze 控制台里一步一步填拿到连接信息之后回到扣子控制台路径是进入你的机器人应用找到模型设置区域把模型下拉框切到“自定义模型”然后点击添加或新建。需要填写的核心字段如下模型名称这是你在 Coze 侧看到的名字可以随便起比如“网关-精锐模型”。方便团队识别就行。模型描述建议写清楚这个模型适合什么任务方便其他协作者理解。不填也能跑但团队协作时容易乱。模型类型选大语言模型。API 地址填 Ace Data Cloud 给你的 Endpoint也就是完整的/v1/chat/completions地址。请求认证方式选择 OpenAI 格式或自定义请求头。通常网关支持Authorization: Bearer 你的API Key这种方式。模型 ID填你在网关上确认的那个真实 Model ID这个字段会出现在实际请求的 model 参数里。请求格式绝大多数网关选 OpenAI 格式。如果你的网关用的是 Azure 那套则要填对应的部署名和 API 版本。保存的时候Coze 一般会发一次测试请求所以在保存前最好先用 curl 手动验证一下接口通不通避免在 Coze 后台反复试错。curl https://你的网关域名/v1/chat/completions \ -H Authorization: Bearer YOUR_API_KEY \ -H Content-Type: application/json \ -d { model: 你的ModelID, messages: [{role: user, content: 你好}], temperature: 0.7 }如果能正常返回一段文本说明接口、密钥、模型 ID 三者都对得上再去 Coze 里保存就稳了。注意在自定义模型配置里“模型名称”和“模型 ID”是两码事。模型名称只是让你在 Coze 后台看得明白真正决定请求路由的是模型 ID。填错这个字段最常见的问题就是返回 model_not_found而且极难排查因为你看到的报错往往不是直接告诉你“填错了”而是让你觉得是网络或密钥的问题。3.3 测试时看明白返回报文配置完成后Coze 会在测试面板里让你输入一条消息验证。可以先问一句“你好简单介绍一下自己”。如果配置没问题你在后端日志里看到的响应结构大概长这样{ id: chatcmpl-xxxx, object: chat.completion, model: 你的ModelID, choices: [ { index: 0, message: { role: assistant, content: 你好我是通过自定义模型接入的助手。 }, finish_reason: stop } ] }Coze 解析响应时主要取choices[0].message.content作为模型的回复文本。如果你的网关返回的不是这种结构比如外层包了一层 data或者直接返回了流式 SSE 文本Coze 可能会解析失败。这里有个隐藏坑有些网关默认开启了流式返回stream mode。流式模式在普通 API 调用里是为了节省首字延迟但 Coze 的自定义模型接入如果没勾选对应的流式选项拿到的就是一串data: {...}分片没法正常解析。遇到这种情况要么在网关请求配置里把 stream 关掉要么在 Coze 侧确认有没有流式开关可以打开。4. 接到工作流里才算真正能用4.1 把自定义模型挂成主模型自定义模型配置好之后回到机器人基本配置在模型下拉框里选择刚刚新建的模型。这一步的作用是让整个 bot 的主对话能力都走这个模型。很多人以为这样会丢失 Coze 原有的能力其实不会。知识库、插件、工作流这些依然正常工作自定义模型负责的只是“语言理解和生成”这一层。也就是说模型照样可以调用插件只不过调用请求最终发到了你的外部接口。主模型设置里通常还有一些可选参数比如温度、回答随机性等。要注意的是Coze 界面里有些参数不一定直接透传给外部模型具体得看它实现到哪一层。如果发现温度设置没有生效就直接在你的网关后台配置默认参数或者在代码节点里构造请求时手动传参这样最可控。如果你的机器人开了多 Agent 模式每个子 Agent 也可以单独指定模型。实践下来这种设计特别适合做分工一个 Agent 用便宜模型做信息收集另一个用强模型做最终回答成本能省下一大截。把不同 Agent 挂上同一个自定义模型入口、切换不同的 Model ID也算一种很实用的 Coze 工作流搭建技巧。4.2 在工作流节点按任务分配模型如果你想要更细的控制可以在 Coze 工作流里用“大模型”节点给不同节点分配不同的模型。这比整个 bot 用同一个模型灵活得多。我习惯这么拆工作流第一步是意图识别判断用户是想查资料、写文案还是做总结。这一步不需要很强的模型用一个小模型就够又快又便宜。第二步是真正的任务执行比如写长文、改代码、做翻译这时切换到一个更强的模型质量马上不一样。最后一步如果需要格式整理比如把对话转成 Markdown 文档又可以切回中等模型。如果工作流节点对请求结构的控制要求更高可以直接用代码节点发起 HTTP 请求绕过 Coze 自定义模型的封装自己拼 prompt、自己选模型。这样做的代价是“自由度高、但要自己处理响应解析”适合熟悉接口的人。import requests def main(url: str, api_key: str, model: str, content: str) - dict: resp requests.post( url, headers{Authorization: fBearer {api_key}}, json{ model: model, messages: [{role: user, content: content}], temperature: 0.7 }, timeout60 ) data resp.json() content_text data[choices][0][message][content] return {output: content_text}这种“代码节点直连模型接口”的写法常见于自定义报告生成、Markdown 转 Word 这类需要后面再加工的任务。先把模型输出拿到手里再做文本清洗、格式转换最后再让 Coze 把结果返回给用户。还要专门提醒一句在 Coze 里上传的文件自定义模型不会自动收到文件内容。它只能拿到文本和文件 URL。如果你的下游模型是多模态模型可以把 URL 传给它去解析如果模型只接受文本你就需要先在工作流里用文件解析插件把内容提取出来再拼到提示词里。别指望外部模型直接读 Coze 的知识库或者附件Coze 的私有数据不会以二进制形式传给外部接口。4.3 接本地部署和微调模型的特殊姿势如果你要接的不是云厂商现成模型而是自己微调过的模型情况会稍微复杂一点。核心要求只有一个你的模型服务必须有一个公网可访问的 HTTPS 接口并且返回格式和 OpenAI 兼容。我见过不少人想把自己电脑上用 Ollama 跑的模型接到 Coze 里。技术上可行但你得先搞清楚一个现实Coze 的云端机器发起请求时访问的是公网地址不是你家局域网里的127.0.0.1。如果模型只跑在本地那 Coze 根本够不着它。常见的做法是把模型部署到有公网 IP 的云服务器上或者用网关服务做一层转发。安全方面一定不能图省事。裸奔的推理服务放在公网上等于把模型接口送给全网刷轻则被别人刷爆账单重则模型越权生成不合适内容。我在实际部署中至少会做三件事开启 API 鉴权所有请求必须带 Key在网关侧配好限流按 IP、按 Key 分别限制明确模型的 system 提示词防止用户通过 prompt 注入让模型说出不该说的话用 vLLM、Ollama 这类推理框架启动服务时也要注意监听地址和端口别暴露得过宽。对外提供服务的网关和实际推理服务最好分层放不要把推理端口直接映射到公网。5. 高频报错的排查手册5.1 三类报错脸谱接入过程中报错就那几张熟脸一个个说。第一张是 401 或 403也就是鉴权失败。最常见的不是 Key 错了而是请求头格式不对。比如把 Key 放在了 URL 参数里或者请求头拼成了Authorization: Bearersk-xxx中间少了空格又或者 Key 复制的时候多了一个换行符。这种问题后端日志很难看出来建议先把 curl 跑一遍确认 curl 通再去 Coze 里配。第二张是 404 或 model_not_found。报错原因翻来覆去就是 Model ID 填错了。这里特别提醒模型 ID 严格区分大小写和下划线Qwen-Max和qwen-max可能是两个完全不同的东西。拿不到准确 ID 时别瞎猜直接去网关模型列表页面复制。第三张是超时。Coze 作为调用方对响应时间是有预期的。如果模型生成一篇长文要两三分钟超出后就会触发重试或直接失败。遇到这种情况优先在网关侧把超时时限调大同时检查是不是模型本身排队太久。Ace Data Cloud 这种聚合服务偶尔会看到某个模型因为上游拥堵导致首字延迟变高如果实测经常超时就直接换模型路由。5.2 参数导致的效果类问题还有一类问题不是报错而是“看起来通但用起来不对劲”。比如机器人偶尔答非所问。这通常不是模型不行而是提示词封装的问题。Coze 会把系统提示词、对话历史、用户输入拼成一段发送给自定义模型。有些外部模型对系统提示词的风格很敏感和默认模型的表现差异很大。解决办法很简单把提示词写得显式一点明确告诉模型“你是客服助手只回答业务相关问题不要编造事实”。再比如输出被截断。这个基本是 max_tokens 设置太小。Coze 界面上如果没暴露这个参数就到网关侧设默认值。生成长文本的工作流建议把 max_tokens 调到 2000 以上不然答到一半就停了很难看。还有上下文超限。如果提示词特别长、对话轮次特别多外接模型会直接返回 context_length_exceeded。处理方式有三个减少每次请求里塞的对话轮次给机器人加摘要记忆节点或者换一个上下文窗口更大的模型。5.3 排查速查表症状优先检查项处理办法401/403请求头格式、Key 是否完整用 curl 单独测试确认 Key 和鉴权方式404/model_not_foundModel ID 是否正确从网关模型列表页复制完整 ID超时/重试模型首字延迟、网关负载调大超时时间或换轻量模型路由回复被截断max_tokens、输出长度上限调大 max_tokens或拆分生成任务答非所问系统提示词、上下文拼接精简提示词明确角色和边界context_length_exceeded上下文窗口、对话轮次数量缩短历史轮次启用摘要换大窗口模型这张表我贴在公司内部文档里后来同事接自定义模型遇到问题基本都是先对着表格自查一遍成功率提高了不少。6. 写在最后的实操经验6.1 一次失败接入的经历我自己第一次接入时踩过一个很傻的坑。当时在 Ace Data Cloud 拿到一个模型 ID里面带大写字母和一个点我在 Coze 里填的时候手一抖把点写成了下划线。测试面板报 model_not_found我以为是网络问题反反复检查 API Key、检查 Endpoint唯独没认真看模型 ID。后来把模型 ID 原文重新复制了一遍一次就通了。还有一次同事在 Coze 里把自定义模型名称填成了“客服模型”但实际 Model ID 指向的是另一个通用模型。结果客服部门反馈机器人回答风格不对排查了大半天最后才发现是模型 ID 填错了。这件事之后我们统一规定模型名称必须写成“用途-模型ID”的格式比如“客服-精调版”从命名上杜绝混淆。6.2 给团队的三个建议经历这些之后我给身边团队总结了三条建议第一密钥管理要规范。API Key 只放在 Coze 控制台或安全的环境变量里绝对不要写死在工作流节点里更不要拼在提示词里。工作流日志一旦打出来密钥就可能跟着泄露。第二新接入的模型先小流量试运行。不要一上来就直接把所有用户流量切过去。先在测试环境跑几天盯一下延迟均值、错误率、 token 消耗确认稳定了再全量切换。第三把模型当可替换组件来设计。提示词尽量写得和具体模型解耦别依赖某一个模型的特殊行为。这样以后更换模型时只需要改一个 Model ID不需要重新调整个机器人。我现在反而更倾向把 Coze 当作编排层把模型当作可替换组件。配置自定义模型这事核心不在那几行连接信息而在于后续的模型治理能不能跟上。希望这篇记录能让你少走一次弯路。