七牛云 AI 大模型推理服务接入：双协议端点与模型清单怎么查

手上一个已经跑通的项目要换模型供应商，这事最烦人的地方从来不是”哪家效果好”。代码是按 OpenAI SDK 写的，服务部署在国内机房，第一版接的是境外聚合平台——功能都对，但链路上时不时来一次超时，重试打上去又变成重复计费，日志里一半的报错最后查出来跟模型本身无关。这种时候你要找的不是一个更强的模型，是一个不用在网络层赌运气的入口。

七牛云的 AI 大模型推理服务就是冲这个位置来的：官方的定位话术直接写着”大陆直连 API，无需配置代理”。下面这篇把接入路径拆开讲——哪个 base url、两个端点分别对应什么协议、模型清单怎么查才靠得住、计费按什么口径走。需要先说清楚的是，本文所有事实来自官方文档与官网口径，我没有用账号逐项跑过控制台；凡是文档没写明的，我会直说没写明，不替它补。凡是会变的数字（单价、免费额度的具体数量、限流阈值、模型总数）本文一律不抄，只讲机制——这类值抄进文章里，过两个月就是错误信息。

一、“大陆直连”解决的是可达性，不解决别的

先把这条定位的边界划清楚，因为它最容易被读成”所以什么都省了”。

直连解决的是网络可达性这一层：调用方在境内，请求不需要绕代理出去再绕回来。这件事的价值在工程上是实打实的——省掉一个代理组件，意味着少一层需要自己运维的东西，少一个会单独挂掉的故障点，也少一类”到底是模型慢还是链路慢”的归因纠缠。做过跨境调用排障的人都知道，最难受的不是失败率高，而是失败原因分不清：同一个超时，可能是对端限流、可能是中间链路抖动、也可能是你的重试策略自己把自己打死了。把链路这一层拿掉之后，剩下的问题至少是可归因的。

但它不解决的事情更需要点明：直连不等于低延迟（延迟取决于对端的推理排队与生成长度）、不等于高可用（平台侧照样会有容量波动）、也不等于你不需要做降级。换供应商只是把一类风险换成了另一类，该做的重试、退避、超时分级、备用供应商切换，一样都不能省。这一层的通用取舍和”到底该不该自己把模型跑起来”的账，是另一个话题，可以对照看自建推理还是直接调 API。

二、一个 base url，两种协议：/chat/completions 与 /messages

接入上最值得说的一点在这里。按官方「实时推理请求 API 接入说明」的口径，它的 base url 是：

https://api.qnaigc.com/v1

而这个 base url 底下同时兼容两种接口格式——文档原文是「兼容 OpenAI API 和 Anthropic API 接口格式」。对应的两个端点分工很清楚：

• OpenAI 格式：/v1/chat/completions
• Anthropic 格式：/v1/messages

这个设计的实际意义，得从客户端生态的角度看才说得通。OpenAI 的 chat/completions 是目前事实上的通用形状，绝大多数 SDK、框架、老项目都是按它写的；而 Anthropic 的 messages 形状不同，请求体结构、消息组织方式、响应字段都是另一套，它不是 OpenAI 协议的子集，客户端不可能靠改个 base url 就互通。问题在于，现在有一批越来越常用的工具——尤其是命令行里的编码助手那一类——只认 Anthropic 那套协议，它们期望你给的是一个 messages 端点。

所以双协议的价值不在”能力更强”，而在你不用为了迁移去改客户端。判断该走哪个端点，其实只有一条判据：看你的调用方是按哪套协议写的。

• 手上的代码或框架是 OpenAI SDK、或任何兼容 OpenAI 的库 → 走 /v1/chat/completions，改 base url 与 key 就行。这条路上最常见的翻车是 base url 多一段或少一段（比如把 /v1 重复拼一次），排查顺序见base url 怎么填和用 OpenAI SDK 接第三方模型。
• 客户端只吃 Anthropic 协议（典型的就是那类要你填 ANTHROPIC_BASE_URL 的工具）→ 走 /v1/messages。

这里有一处我必须坦白：Anthropic 那一侧的鉴权头写法、以及协议字段的覆盖程度，不在本文依据的文档范围内。 拿到的原文只确认了”兼容这两种格式”以及两个端点路径，没有逐字段列出 Anthropic 侧支持到哪一步。兼容层这种东西，覆盖度差异往往就藏在细节里——流式事件的分帧、工具调用的字段、多模态内容块的处理，都有可能只覆盖常用路径。所以如果你要走 Anthropic 端点，别假设它和上游逐字段等价，以官方文档（新文档站在 apidocs.qnaigc.com，带 FAQ；旧文档在 developer.qiniu.com/aitokenapi）和实际返回为准，把你真正用到的那几个字段先打一遍。多协议兼容层的通用坑，OpenAI 兼容层是怎么一回事那篇讲得更细。

三、为什么”列模型”是接入的第一步，而不是可选步骤

很多人接一个新平台的第一个动作是直接抄一段示例代码改改就发请求，然后卡在一个看起来毫无信息量的报错上。更稳的第一步是先把模型清单拉下来。官方给了两种方式，都照文档原文：

curl 直接问：

curl "$OPENAI_BASE_URL/models" -H "Authorization: Bearer $OPENAI_API_KEY"

或者用 Python 的 OpenAI SDK，调 client.models.list()，遍历返回里的 models.data，取每个 model.id。

为什么这一步值得单独做？三个理由。

第一，模型清单是易变的，官方页面上的数量口径不是契约。 官网给过一个具体的支持数量，覆盖 DeepSeek、Qwen、GLM、Kimi、MiniMax 这些国产系列，也包含 Claude、GPT、Gemini 等海外模型。数量我不抄——这个数每过一段时间就动一次，上新、下架、改版本号都会让它变。真正有权威性的清单只有一个：你的 key 此刻调 /models 返回的那份。文章里的列表、别人博客里的截图、甚至官网宣传页，都只是参考。

第二，model 字段写错的失败形态很不友好。 模型标识是字符串，大小写、连字符、版本后缀差一个字符就是另一个不存在的名字。而这类错误返回的往往是一个笼统的参数错误或找不到模型，看不出到底是名字错了、还是这个模型对你的 key 不开放。先把清单拉下来、把你要用的 id 从返回里复制出去，能省掉整个下午。

第三，这一步顺带验证了三件事：key 是有效的、base url 拼对了、网络是通的。这三件事一旦被 /models 的 200 响应证实，后面发生的任何问题就都是业务层的问题了。排障最贵的成本是范围不清，这一步等于免费缩小了一半的排查面。

顺带说一个容易踩的差异：在第三方工具集成的场景里，模型引用常见的是 qiniu/<modelId> 这种带前缀的形式。 也就是说，同一个模型在直接调 API 时用的名字，和你在某个支持多家供应商的工具里填的名字，可能长得不一样——前者是裸的模型 id，后者带一个标识供应商的前缀。这类工具通常要用前缀来决定把请求路由给哪家，所以它是工具侧的命名约定，不是平台改了模型名。接入时如果在 SDK 里能跑通、在某个工具里填同样的名字却不认，先怀疑是不是缺了这个前缀。

四、请求体的形状：先跑通最小集，再加参数

按文档口径，请求体是标准的 OpenAI 格式 JSON，必填两项：

• messages：一个数组，每个元素带 role 和 content；
• model：模型标识，就是上一节从 /models 里取出来的那个 id。

可选项里文档点到了 stream，用来开流式返回。

我的建议是接入时把参数收到最小——只发 messages 和 model，确认能拿到一次完整响应；然后单独验一次 stream，因为流式是另一条代码路径，出问题的姿势和非流式完全不同（连接提前断开、分帧解析、客户端缓冲），很多人是在上线前一天才发现流式那条路没测过。至于文档里没有明确列出的其他参数（采样参数、惩罚项、工具调用等等），官方文档在本文依据的范围内没有逐项说明支持情况，以官方文档最新版本和实际返回为准。 我不替它列一份”应该支持”的参数表——兼容层最不该猜的就是这个，猜错了会让读者以为某个参数生效了，实际上被静默忽略。

五、计费与限流：一个写清楚了，一个没公开

计费机制是清楚的：按量计费，按实际消耗的 token 数收费，每月初出账。 另外平台有免费额度（具体数量属于随时会调的数字，本文不写，以控制台当时显示为准）。

这套机制里有一个工程含义值得单独拎出来：按 token 计费 + 月初出账，意味着账单本身不能当实时成本监控用。 你在月中看不到一张结清的账，能看到的只有用量；而真正把成本打爆的场景（某个循环把同一段长上下文反复发了一万次、某个重试策略在对端超时时无限重发、某个用户把整本文档粘进对话）都是几小时内发生的。指望出账来发现它，已经晚了一个月。

所以按量计费的平台，成本控制必须做在你自己这一侧，至少三件事：在调用出口统计 token 用量并按业务维度打标（哪个功能、哪个用户、哪个模型）；给单次请求的输入长度设硬上限，超了直接截断或拒绝，别让一个异常输入变成一次超长计费；给重试设次数上限和退避，明确哪些错误码值得重试、哪些重试就是浪费钱。这三件事做在网关层最省事，一次做完所有业务都受益。

限流这件事，官方公开文档里没有给出具体的 RPM / TPM / 并发上限数值。 这不是没找到就含糊过去——核实的结论就是官方公开文档未给出这些数值，所以本文不填任何数字，以控制台的配额页与官方文档（apidocs.qnaigc.com，其 FAQ 值得先翻一遍）为准。

限流阈值不公开，工程上怎么办？把它当成一个未知量来设计，而不是等着某天被它打中：

1. 并发上限做成可热改的配置，不要写死在代码里。真撞上限流的时候，你需要的是改一个配置值，而不是发一次版。
2. 把限流类错误单独分流。它和参数错误、模型不存在、服务端异常是完全不同的处置逻辑：限流要退避重试，参数错误重试一万次也还是错。这条不做，监控上就永远看不清到底是你打太猛还是对端出问题。
3. 自己压一遍测出软上限。上生产前用真实的请求形状（真实的上下文长度，不是一句 hello）阶梯式加并发，记录开始出现限流或延迟明显抬头的那个点，把生产并发设在它下面留足余量。文档没给的数，只能自己量；但要注意这个量出来的值是当时当刻的，平台侧调整配额后它就失效了，别当成永久结论。
4. 区分”限流”和”排队”。有些平台在压力下不是拒绝你，而是让你排队，表现出来就是延迟变长而不是报错。这两种表现对客户端超时设置的要求不一样，压测时顺手把延迟分布也记下来。

六、接入前先确认的几件事

按上面这些机制，给一份动手前的清单，按顺序做：

• 用 /models 拉一次清单，确认 key 有效、base url 拼对、目标模型在列；把要用的 id 原样复制进配置，别手打。
• 确认你的客户端是哪套协议，据此选 /v1/chat/completions 还是 /v1/messages；只要用到 Anthropic 端点，就把你真正依赖的那几个字段单独验一遍，别假设逐字段等价。
• 非流式先通，再单独验流式。
• 出口处把 token 用量按业务维度统计起来，输入长度设硬上限。
• 把并发数和重试策略做成配置项，限流错误单独分类，再自己压一遍摸出软上限。
• 关键业务准备一条备用供应商的切换路径。哪家都可能有容量波动，切换能力比选谁更重要。
• 把平台的文档入口记在项目文档里（apidocs.qnaigc.com 与旧站 developer.qiniu.com/aitokenapi），限流和额度这类会变的东西，只信文档和控制台的当时值。

七、诚实的判断：平台侧的海外模型，别当成官方直连

最后说两句可能不太讨喜的话。

清单里带着 Claude、GPT、Gemini 这些海外模型，这是平台侧提供的兼容访问，不等于你接的是模型厂商的官方接口。 中间隔着平台自己的接入与转发实现，那么新特性什么时候跟上、哪些参数被透传哪些被忽略、版本对应哪个上游快照、长上下文和多模态这类重负载的表现如何，都取决于平台这一层怎么做，而不是上游文档怎么写。这不是说平台侧访问不能用——它对”我就想快速验证一下这个模型适不适合我的任务”这种需求非常合适。但如果你的业务逻辑要依赖某个模型的特定行为细节，那就得按实际表现验证，不能拿上游官方文档当作对这个入口的承诺。把上游文档的描述直接写进你的技术方案，是我见过最隐蔽的一类返工来源。

另一件事：限流数值不公开，本身就是一条选型信息。 我不想把它渲染成缺点——很多平台在配额上做动态调整，公开一个固定数值反而容易误导。但对你来说，后果是实在的：你没法在纸上算出”这个入口能不能扛住我的峰值”，只能先小流量跑起来，靠自己的压测和监控把这条边界摸出来。这决定了接入的正确姿势是渐进式的：先小流量、先非关键路径、先把观测埋好，确认了边界再往上压。如果你的项目状态是”下周就要全量切过来，没有时间做灰度”，那这个未知量就是真风险，该重新排一下节奏。

至于它和 ModelScope、PPIO 这些国内平台放在一起该按什么维度比，那是另一篇的事：国内推理平台横向。这里只留一句：本文的全部事实来自官方文档与官网口径，涉及具体价格、免费额度数量、限流阈值、模型总数的部分我一律没写——不是漏了，是这些值只有控制台上当时显示的那份才算数。