Project

General

Profile

MaaS 渠道接入指南 » History » Version 2

商宗康 商, 09/20/2026 10:22 AM

1 2 商宗康 商
# MaaS 新渠道接入指南
2 1 商宗康 商
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
用到的页面都在后台左侧菜单里:渠道管理、系统配置(分组相关设置)、使用日志。