MaaS 新渠道接入指南 » History » Version 1
商宗康 商, 09/20/2026 10:23 AM
| 1 | 1 | 商宗康 商 | # MaaS 新渠道接入指南 |
|---|---|---|---|
| 2 | |||
| 3 | *从拿到上游的网址和钥匙,到这条渠道真正开始接活。* |
||
| 4 | |||
| 5 | 先说清楚「渠道」是什么。一条渠道就是一条从上游进货的线路:一个网址、一把钥匙,加上一份「这条线路能供哪些模型」的清单。客户每发一次请求,最后都是沿着某一条渠道送到上游去的。接入渠道,就是把一条新的进货线路接到系统里,让它开始接活。 |
||
| 6 | |||
| 7 | 接入这件事,动作本身不难:填几个字段、勾一批模型、保存。难的是填对。名字怎么起、挂到哪个分组、排在什么位置——这三件事都是从同一组信息推出来的。推错了,线路照样能跑,但钱会走错路,或者客户根本看不到它。 |
||
| 8 | |||
| 9 | **所以顺序是先做判断,再动手填表。** 一条线路打几折、能供哪些模型、是什么资源,这三件事没问清楚就去建渠道,大概率要返工。 |
||
| 10 | |||
| 11 | --- |
||
| 12 | |||
| 13 | ## 一、接入之前,先把四样东西要齐 |
||
| 14 | |||
| 15 | 拿到一条新渠道,先跟对方要齐四样东西。这四样不是走流程,它们各自决定后面的一步: |
||
| 16 | |||
| 17 | *要齐这四样,后面的每一步才有的可依* |
||
| 18 | |||
| 19 | | 要问清楚的 | 用来干什么 | 缺了会怎样 | |
||
| 20 | | --- | --- | --- | |
||
| 21 | | 接口地址 + 密钥(上游的网址,和一把证明请求是我们发的钥匙) | 请求发到这里,并且证明是我们发的 | 渠道建不出来,测试也通不过 | |
||
| 22 | | 模型清单(上游能给哪些模型,要逐条列表) | 决定这条线路勾哪些模型 | 勾多了请求会失败,还查不出原因 | |
||
| 23 | | 成本折扣(走这条线路打几折) | 决定名字第二段、排在哪一层 | 名字起不出来,顺序只能瞎排 | |
||
| 24 | | 资源类型(自部署还是云厂商) | 决定名字第四段、要不要新开一个分组 | 同一个分组里混进不同类型的线路 | |
||
| 25 | |||
| 26 | **模型清单一定要是列表,不能是「支持主流模型」这种回答。** 让上游把模型名字逐条列出来——我们要拿它去勾选。多勾了不会当场报错,会等到客户发请求的时候才失败。 |
||
| 27 | |||
| 28 | **折扣的口径也要问清楚。** 是相对上游官网价的折扣,还是相对我们已经有的某条渠道?口径不一样,两个数字就不能直接比,照着比出来的结果排顺序会排错。 |
||
| 29 | |||
| 30 | ### 几个词的大白话说法 |
||
| 31 | |||
| 32 | 后台界面上这几个词会反复出现,先混个眼熟: |
||
| 33 | |||
| 34 | | 界面上写的 | 大白话 | |
||
| 35 | | --- | --- | |
||
| 36 | | **渠道** | 一条进货线路:一个网址 + 一把钥匙 + 一份模型清单 | |
||
| 37 | | **上游 / 供应商** | 给我们供货的那一方 | |
||
| 38 | | **模型ID** | 上游给每个模型起的名字。名字对得上,请求才找得到 | |
||
| 39 | | **分组** | 一个档位。客户挂在哪个分组,就只能用那个分组下面的线路 | |
||
| 40 | | **分组倍率** | 每个分组打几折,写在这里 | |
||
| 41 | | **优先级** | 排队的号码。数字越大,越先被用 | |
||
| 42 | | **权重** | 同一层里几条线路,各分走多少活 | |
||
| 43 | | **自动禁用** | 一条线路连续失败,系统自动把它下线 | |
||
| 44 | | **auto** | 客户不指定分组,让系统自己从便宜往贵试 | |
||
| 45 | |||
| 46 | --- |
||
| 47 | |||
| 48 | ## 二、名字先定下来,后面每一步都靠它 |
||
| 49 | |||
| 50 | 渠道名不是随手写的备注,它是后面每一步都要用到的线索。我们这套命名固定四段: |
||
| 51 | |||
| 52 | `{供应商代号}_{成本折扣}_{模型或模型族}_{资源类型}` |
||
| 53 | |||
| 54 | 比如 `de_0.52x_kimi-k3_自部署`,从头读下来就是:de 这家供应商的 kimi-k3,自部署的资源,走它打 5.2 折。 |
||
| 55 | |||
| 56 | | 段位 | 写什么 | 在这条名字里是 | 写错会怎样 | |
||
| 57 | | --- | --- | --- | --- | |
||
| 58 | | 第一段 | 供应商代号 | `de` | 认不出是谁家的资源 | |
||
| 59 | | 第二段 | 成本折扣 | `0.52x` | 和「分组倍率」对不上账 | |
||
| 60 | | 第三段 | 模型或模型族 | `kimi-k3` | 一眼看不出这条线路供什么 | |
||
| 61 | | 第四段 | 资源类型 | `自部署` | 同一个分组里混进不同类型的线路 | |
||
| 62 | |||
| 63 | > 四段各说一件事。第二段和第四段最要紧,一个管排序算钱,一个管线路类型。 |
||
| 64 | |||
| 65 | 名字起得规范,后面排顺序、对账、查问题都不用再去翻表格。四段里有两段要格外小心:**第二段的数字,必须和「分组倍率」里那个数字一模一样**,不一样就对不上账;**第四段说明这条线路属于哪一类资源**。 |
||
| 66 | |||
| 67 | **一条线路只装同一类资源。** 为什么?因为系统挑线路的时候只看两件事:客户在哪个分组、要的是哪个模型。它不看这条线路是什么类型。所以把自部署和云厂商混在同一个分组里,一旦便宜的线路出问题、请求往下掉,就可能掉到另一类线路上去,中间要多做一次格式转换——能通,但回来的内容可能和平时不一样。 |
||
| 68 | |||
| 69 | --- |
||
| 70 | |||
| 71 | ## 三、把渠道建出来 |
||
| 72 | |||
| 73 | 信息齐了、名字定了,就可以动手建了。 |
||
| 74 | |||
| 75 | 1. **选类型。** 上游那家用的接口格式,我们要选一个对应的。**这一步选错,后面填得再对也发不出去。** |
||
| 76 | 2. **填名称。** 按第二节的四段式写。一次写对,别用「测试渠道1」这种临时名字——临时名字最后都会变成正式的。 |
||
| 77 | 3. **填接口地址。** 把上游给的网址粘进来。粘到域名那一层就够(比如 `https://api.example.com`),后面的路径系统会自己接上。如果上游给的地址里带着 `/v1` 这一截,先按去掉 `/v1` 的填;测试发不通,再把 `/v1` 加回去试。**这一步没有统一答案,以测试能不能通为准。** |
||
| 78 | 4. **填密钥。** 照上游给的原文粘,不要自己删空格、不要改大小写——多一个空格就认不过。 |
||
| 79 | 5. **配代理**(如果需要)。只有上游那边必须走代理才连得上时才填,平时留空。不确定就问上游。 |
||
| 80 | 6. **保存。** |
||
| 81 | |||
| 82 | --- |
||
| 83 | |||
| 84 | ## 四、勾模型:只勾上游真的支持的 |
||
| 85 | |||
| 86 | 保存之后,进这条渠道,把上游能给我们的模型一个个勾上。**勾上的意思,就是告诉系统「这些模型,这条线路供得了」。** |
||
| 87 | |||
| 88 | **只勾上游明确说了支持的。** 多勾不会当场报错,会等到客户发请求的时候才失败——那时候你已经在翻日志了,比现在多花两分钟核对要麻烦得多。 |
||
| 89 | |||
| 90 | **同一个模型,在各条线路上的名字要写得一模一样。** 上游文档写 `kimi-k3`,就照抄 `kimi-k3`,别自己改成 `kimi-k3-latest`,也别把大小写改了。名字对不上,请求就找不到这条线路。 |
||
| 91 | |||
| 92 | 上游一个系列里有好几个模型(比如 glm 下面还有 glm-5.3、glm-5.2),一条线路一次全勾上就行,不用一个模型建一条。 |
||
| 93 | |||
| 94 | --- |
||
| 95 | |||
| 96 | ## 五、填「分组」:这条线路给谁用 |
||
| 97 | |||
| 98 | 「分组」栏里写分组的名字,可以写好几个,中间用英文逗号隔开。写几个名字,这条线路就同时给几个分组供货。 |
||
| 99 | |||
| 100 | **这里写的名字,必须是系统里已经有的分组。** 怎么判断?打开「分组倍率」看一眼,里面列过的名字才算数。没列过的名字写上去,渠道建好了、模型也勾了,客户发请求就是不走到它——这是接入时最常见的「看着都对,就是不工作」。 |
||
| 101 | |||
| 102 | 那这条新线路该挂到哪个分组?看它的折扣数字是不是头一次出现。 |
||
| 103 | |||
| 104 | ```mermaid |
||
| 105 | flowchart TD |
||
| 106 | Q["这个折扣数字,以前出现过吗?"] |
||
| 107 | A1["出现过,已经有这个分组"] |
||
| 108 | A2["直接挂进那个分组<br/>和同分组的老线路排在一起,一起接活"] |
||
| 109 | B1["头一次出现,是个新分组"] |
||
| 110 | B2["要新开一个分组<br/>还有四处配置要一起改,见第七节"] |
||
| 111 | |||
| 112 | Q --> A1 --> A2 |
||
| 113 | Q --> B1 --> B2 |
||
| 114 | ``` |
||
| 115 | |||
| 116 | > 折扣数字以前出现过,就挂进老分组;是头一次出现,就要新开一个。 |
||
| 117 | |||
| 118 | 折扣数字以前出现过(比如已经有一个 0.58 的分组),就直接挂进那个分组,和同分组的老线路排在一起,一起接活。折扣数字是头一次出现(比如第一次出现 0.45),就要新开一个分组,并且把第七节那四处配置一起改掉。 |
||
| 119 | |||
| 120 | 顺手记一下这条线路挂在哪几个分组。排队号码是写在渠道身上的,不是写在分组上的——以后调顺序,这几个分组会一起受影响。 |
||
| 121 | |||
| 122 | --- |
||
| 123 | |||
| 124 | ## 六、排优先级:这条线路排在第几位 |
||
| 125 | |||
| 126 | 优先级就是排队的号码,数字越大越先被用。新线路进来,按它的折扣决定放哪一层:折扣最低的排最高,比如 100;次低的一层放 50;再往下 10。 |
||
| 127 | |||
| 128 | 为什么用 100、50、10 这种大数字,而不是 1、2、3?**因为用大数字,以后中间还能插进来一条新的。** |
||
| 129 | |||
| 130 | 只有同一层里挤了好几条线路(折扣一样),才轮到权重出场——它决定这几条各分走多少活,按各自的容量来,用 10 / 20 / 30。权重只在同一层里管用,跨层没意义。 |
||
| 131 | |||
| 132 | > **动手之前,先看一眼这条线路的「分组」栏。** 排队号码是写在渠道身上的,改一次,所有挂着它的分组一起变。新接入的线路一般只挂一两个分组,风险不大;但如果是往一条老线路上补分组,就得当心——你可能顺手把别的业务线的顺序也改了。 |
||
| 133 | |||
| 134 | --- |
||
| 135 | |||
| 136 | ## 七、开了新分组的话,还有四处要一起改 |
||
| 137 | |||
| 138 | 如果这条线路的折扣是以前没出现过的数字,光建渠道是不够的。系统的「分组相关设置」里有四处要同时改。**这四处不是「改了更好」,是「缺一处就不生效」。** |
||
| 139 | |||
| 140 | *四处配置,缺一处这个分组就不完整* |
||
| 141 | |||
| 142 | | 配置项 | 它管什么 | 不改会怎样 | |
||
| 143 | | --- | --- | --- | |
||
| 144 | | **分组倍率** | 每个分组打几折 | 新分组被判为无效,直接用不了 | |
||
| 145 | | **用户可选分组** | 全部有哪些分组,也就是一份名单 | 新分组不出现在账号的分组下拉里 | |
||
| 146 | | **分组特殊可用分组** | 哪些账号能看到哪些分组 | 本来要限制可见范围的账号,会看到这个新分组 | |
||
| 147 | | **auto 分组顺序** | 系统自己挑分组时,从便宜往贵试的顺序 | 设成 auto 的账号永远轮不到这条新线路 | |
||
| 148 | |||
| 149 | 以新接入一条 `de_0.45x_kimi-k3_云厂商`、新开分组 `kimi云厂商` 为例,四处改完是这样: |
||
| 150 | |||
| 151 | *分组倍率 —— 给新分组标价,也就是打几折* |
||
| 152 | |||
| 153 | ```json |
||
| 154 | { |
||
| 155 | "kimi自部署": 0.52, |
||
| 156 | "kimi云厂商": 0.45, |
||
| 157 | "glm云厂商": 0.33, |
||
| 158 | "通用": 1 |
||
| 159 | } |
||
| 160 | ``` |
||
| 161 | |||
| 162 | *用户可选分组 —— 把它加进「有哪些分组」这份名单* |
||
| 163 | |||
| 164 | ```json |
||
| 165 | { |
||
| 166 | "kimi自部署": "Kimi 自部署", |
||
| 167 | "kimi云厂商": "Kimi 云厂商", |
||
| 168 | "glm云厂商": "GLM 云厂商", |
||
| 169 | "通用": "通用" |
||
| 170 | } |
||
| 171 | ``` |
||
| 172 | |||
| 173 | *分组特殊可用分组 —— 决定哪些账号能看到它* |
||
| 174 | |||
| 175 | ```json |
||
| 176 | { |
||
| 177 | "kimi入口": { |
||
| 178 | "+:kimi自部署": "可见", |
||
| 179 | "+:kimi云厂商": "可见" |
||
| 180 | } |
||
| 181 | } |
||
| 182 | ``` |
||
| 183 | |||
| 184 | *auto 分组顺序 —— 系统自己挑的时候,按便宜到贵排* |
||
| 185 | |||
| 186 | ```json |
||
| 187 | ["glm云厂商", "kimi云厂商", "kimi自部署", "通用"] |
||
| 188 | ``` |
||
| 189 | |||
| 190 | 四处里最容易漏的是 **auto 分组顺序**。只改了分组倍率,分组是存在了,但设成 auto 的账号永远轮不到它——因为 auto 就是「让系统自己挑分组」,挑的顺序照着这个名单从左往右走。名单里没有的名字,等于不存在。 |
||
| 191 | |||
| 192 | --- |
||
| 193 | |||
| 194 | ## 八、自己先测通,再通知客户 |
||
| 195 | |||
| 196 | 配置做完,别急着通知客户,自己先测一遍。 |
||
| 197 | |||
| 198 | 进「渠道管理」,右上角把视图从表格切换成**卡片视图**——卡片上每条线路的状态和支持的模型一眼就能看到。找到这条新线路,点「测试」,把客户会用到的那几个模型逐个发一条。 |
||
| 199 | |||
| 200 | **测试通过,不等于没问题。** 测试是直接打这条线路,中间「挑分组、挑线路」那些步骤全跳过了。所以它只回答一件事:这条线路本身通不通。它不回答另一件事:客户的请求会不会真的被分到这条线路上。这两件事得分开确认。 |
||
| 201 | |||
| 202 | 确认的方法,是打开「使用日志」看真实请求。上线后的头两天盯两件事: |
||
| 203 | |||
| 204 | - **有没有请求真的走到它。** 日志里按这条线路的名字筛一下。一条都没有,说明分组或者排队号码没对上,回去检查「分组」栏写的名字对不对、优先级是不是排在了最后。 |
||
| 205 | - **失败率高不高。** 新线路刚接进来,上游那边可能还没调好。失败率明显高于同分组的其他线路,先别急着调顺序,把失败的记录整理一份发给上游。 |
||
| 206 | |||
| 207 | > **把这条线路的「自动禁用」打开。** 打开之后,它要是连续失败,系统会自动把它下线,不再往上发请求。新线路头几天最容易出问题,这个开关就是给它准备的保险。 |
||
| 208 | |||
| 209 | ### 没生效的时候,按这个顺序看 |
||
| 210 | |||
| 211 | | 现象 | 先看哪里 | 通常是这个原因 | |
||
| 212 | | --- | --- | --- | |
||
| 213 | | 客户说看不到这个新分组 | 分组倍率 + 用户可选分组 | 分组没配全,或者没加进名单 | |
||
| 214 | | 设成 auto 的账号走不到新线路 | auto 分组顺序 | 名单里没有这个分组名 | |
||
| 215 | | 测试能通,日志里却一条请求都没有 | 渠道的「分组」栏 | 分组名写错了,或者排队号码排在了最后 | |
||
| 216 | | 请求报「无可用渠道」 | 渠道的「分组」栏 + 模型勾选 | 分组名对不上,或者这个模型没勾上 | |
||
| 217 | |||
| 218 | 跑顺之后,这条线路就进入日常巡检范围了。后面再出问题,按《MaaS 渠道故障排查》那套顺序查就行。 |
||
| 219 | |||
| 220 | --- |
||
| 221 | |||
| 222 | ## 九、接入顺序 |
||
| 223 | |||
| 224 | ```mermaid |
||
| 225 | flowchart TD |
||
| 226 | S1["先把四样东西要齐<br/>网址、钥匙、模型清单、打几折"] |
||
| 227 | S2["按四段式起名字<br/>de_0.52x_kimi-k3_自部署"] |
||
| 228 | S3["新建渠道:类型、名称、网址、钥匙<br/>必须走代理的,在这里一并配上"] |
||
| 229 | S4["勾模型<br/>只勾上游真的支持的"] |
||
| 230 | S5["填「分组」<br/>写已经有的分组名,逗号隔开"] |
||
| 231 | S6["排优先级<br/>按折扣放到对应的一层"] |
||
| 232 | S7["自己先测一遍<br/>卡片视图里点测试"] |
||
| 233 | S8["再通知客户,盯两天日志<br/>看有没有请求真的走到它"] |
||
| 234 | X["是新分组?<br/>四处配置一起改"] |
||
| 235 | |||
| 236 | S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8 |
||
| 237 | S6 --> X |
||
| 238 | ``` |
||
| 239 | |||
| 240 | > 前面两步是判断,中间四步是填表,最后两步才是验证。顺序反了就要返工。 |
||
| 241 | |||
| 242 | **判断在前,填表在后。** 名字、分组、排队号码,都是从「打几折 + 模型清单 + 资源类型」这三样推出来的——这三样清楚了,后面每一步都是照着填。 |
||
| 243 | |||
| 244 | --- |
||
| 245 | |||
| 246 | 用到的页面都在后台左侧菜单里:渠道管理、系统配置(分组相关设置)、使用日志。 |