Project

General

Profile

Actions

MaaS 新渠道接入指南

从拿到上游的网址和钥匙,到这条渠道真正开始接活。

先说清楚「渠道」是什么。一条渠道就是一条从上游进货的线路:一个网址、一把钥匙,加上一份「这条线路能供哪些模型」的清单。客户每发一次请求,最后都是沿着某一条渠道送到上游去的。接入渠道,就是把一条新的进货线路接到系统里,让它开始接活。

接入这件事,动作本身不难:填几个字段、勾一批模型、保存。难的是填对。名字怎么起、挂到哪个分组、排在什么位置——这三件事都是从同一组信息推出来的。推错了,线路照样能跑,但钱会走错路,或者客户根本看不到它。

所以顺序是先做判断,再动手填表。 一条线路打几折、能供哪些模型、是什么资源,这三件事没问清楚就去建渠道,大概率要返工。


一、接入之前,先把四样东西要齐

拿到一条新渠道,先跟对方要齐四样东西。这四样不是走流程,它们各自决定后面的一步:

要齐这四样,后面的每一步才有的可依

要问清楚的 用来干什么 缺了会怎样
接口地址 + 密钥(上游的网址,和一把证明请求是我们发的钥匙) 请求发到这里,并且证明是我们发的 渠道建不出来,测试也通不过
模型清单(上游能给哪些模型,要逐条列表) 决定这条线路勾哪些模型 勾多了请求会失败,还查不出原因
成本折扣(走这条线路打几折) 决定名字第二段、排在哪一层 名字起不出来,顺序只能瞎排
资源类型(自部署还是云厂商) 决定名字第四段、要不要新开一个分组 同一个分组里混进不同类型的线路

模型清单一定要是列表,不能是「支持主流模型」这种回答。 让上游把模型名字逐条列出来——我们要拿它去勾选。多勾了不会当场报错,会等到客户发请求的时候才失败。

折扣的口径也要问清楚。 是相对上游官网价的折扣,还是相对我们已经有的某条渠道?口径不一样,两个数字就不能直接比,照着比出来的结果排顺序会排错。

几个词的大白话说法

后台界面上这几个词会反复出现,先混个眼熟:

界面上写的 大白话
渠道 一条进货线路:一个网址 + 一把钥匙 + 一份模型清单
上游 / 供应商 给我们供货的那一方
模型ID 上游给每个模型起的名字。名字对得上,请求才找得到
分组 一个档位。客户挂在哪个分组,就只能用那个分组下面的线路
分组倍率 每个分组打几折,写在这里
优先级 排队的号码。数字越大,越先被用
权重 同一层里几条线路,各分走多少活
自动禁用 一条线路连续失败,系统自动把它下线
auto 客户不指定分组,让系统自己从便宜往贵试

二、名字先定下来,后面每一步都靠它

渠道名不是随手写的备注,它是后面每一步都要用到的线索。我们这套命名固定四段:

{供应商代号}_{成本折扣}_{模型或模型族}_{资源类型}

比如 de_0.52x_kimi-k3_自部署,从头读下来就是:de 这家供应商的 kimi-k3,自部署的资源,走它打 5.2 折。

段位 写什么 在这条名字里是 写错会怎样
第一段 供应商代号 de 认不出是谁家的资源
第二段 成本折扣 0.52x 和「分组倍率」对不上账
第三段 模型或模型族 kimi-k3 一眼看不出这条线路供什么
第四段 资源类型 自部署 同一个分组里混进不同类型的线路

四段各说一件事。第二段和第四段最要紧,一个管排序算钱,一个管线路类型。

名字起得规范,后面排顺序、对账、查问题都不用再去翻表格。四段里有两段要格外小心:第二段的数字,必须和「分组倍率」里那个数字一模一样,不一样就对不上账;第四段说明这条线路属于哪一类资源。

一条线路只装同一类资源。 为什么?因为系统挑线路的时候只看两件事:客户在哪个分组、要的是哪个模型。它不看这条线路是什么类型。所以把自部署和云厂商混在同一个分组里,一旦便宜的线路出问题、请求往下掉,就可能掉到另一类线路上去,中间要多做一次格式转换——能通,但回来的内容可能和平时不一样。


三、把渠道建出来

信息齐了、名字定了,就可以动手建了。

  1. 选类型。 上游那家用的接口格式,我们要选一个对应的。这一步选错,后面填得再对也发不出去。
  2. 填名称。 按第二节的四段式写。一次写对,别用「测试渠道1」这种临时名字——临时名字最后都会变成正式的。
  3. 填接口地址。 把上游给的网址粘进来。粘到域名那一层就够(比如 https://api.example.com),后面的路径系统会自己接上。如果上游给的地址里带着 /v1 这一截,先按去掉 /v1 的填;测试发不通,再把 /v1 加回去试。这一步没有统一答案,以测试能不能通为准。
  4. 填密钥。 照上游给的原文粘,不要自己删空格、不要改大小写——多一个空格就认不过。
  5. 配代理(如果需要)。只有上游那边必须走代理才连得上时才填,平时留空。不确定就问上游。
  6. 保存。

四、勾模型:只勾上游真的支持的

保存之后,进这条渠道,把上游能给我们的模型一个个勾上。勾上的意思,就是告诉系统「这些模型,这条线路供得了」。

只勾上游明确说了支持的。 多勾不会当场报错,会等到客户发请求的时候才失败——那时候你已经在翻日志了,比现在多花两分钟核对要麻烦得多。

同一个模型,在各条线路上的名字要写得一模一样。 上游文档写 kimi-k3,就照抄 kimi-k3,别自己改成 kimi-k3-latest,也别把大小写改了。名字对不上,请求就找不到这条线路。

上游一个系列里有好几个模型(比如 glm 下面还有 glm-5.3、glm-5.2),一条线路一次全勾上就行,不用一个模型建一条。


五、填「分组」:这条线路给谁用

「分组」栏里写分组的名字,可以写好几个,中间用英文逗号隔开。写几个名字,这条线路就同时给几个分组供货。

这里写的名字,必须是系统里已经有的分组。 怎么判断?打开「分组倍率」看一眼,里面列过的名字才算数。没列过的名字写上去,渠道建好了、模型也勾了,客户发请求就是不走到它——这是接入时最常见的「看着都对,就是不工作」。

那这条新线路该挂到哪个分组?看它的折扣数字是不是头一次出现。

flowchart TD
    Q["这个折扣数字,以前出现过吗?"]
    A1["出现过,已经有这个分组"]
    A2["直接挂进那个分组<br/>和同分组的老线路排在一起,一起接活"]
    B1["头一次出现,是个新分组"]
    B2["要新开一个分组<br/>还有四处配置要一起改,见第七节"]

    Q --> A1 --> A2
    Q --> B1 --> B2

折扣数字以前出现过,就挂进老分组;是头一次出现,就要新开一个。

折扣数字以前出现过(比如已经有一个 0.58 的分组),就直接挂进那个分组,和同分组的老线路排在一起,一起接活。折扣数字是头一次出现(比如第一次出现 0.45),就要新开一个分组,并且把第七节那四处配置一起改掉。

顺手记一下这条线路挂在哪几个分组。排队号码是写在渠道身上的,不是写在分组上的——以后调顺序,这几个分组会一起受影响。


六、排优先级:这条线路排在第几位

优先级就是排队的号码,数字越大越先被用。新线路进来,按它的折扣决定放哪一层:折扣最低的排最高,比如 100;次低的一层放 50;再往下 10。

为什么用 100、50、10 这种大数字,而不是 1、2、3?因为用大数字,以后中间还能插进来一条新的。

只有同一层里挤了好几条线路(折扣一样),才轮到权重出场——它决定这几条各分走多少活,按各自的容量来,用 10 / 20 / 30。权重只在同一层里管用,跨层没意义。

动手之前,先看一眼这条线路的「分组」栏。 排队号码是写在渠道身上的,改一次,所有挂着它的分组一起变。新接入的线路一般只挂一两个分组,风险不大;但如果是往一条老线路上补分组,就得当心——你可能顺手把别的业务线的顺序也改了。


七、开了新分组的话,还有四处要一起改

如果这条线路的折扣是以前没出现过的数字,光建渠道是不够的。系统的「分组相关设置」里有四处要同时改。这四处不是「改了更好」,是「缺一处就不生效」。

四处配置,缺一处这个分组就不完整

配置项 它管什么 不改会怎样
分组倍率 每个分组打几折 新分组被判为无效,直接用不了
用户可选分组 全部有哪些分组,也就是一份名单 新分组不出现在账号的分组下拉里
分组特殊可用分组 哪些账号能看到哪些分组 本来要限制可见范围的账号,会看到这个新分组
auto 分组顺序 系统自己挑分组时,从便宜往贵试的顺序 设成 auto 的账号永远轮不到这条新线路

以新接入一条 de_0.45x_kimi-k3_云厂商、新开分组 kimi云厂商 为例,四处改完是这样:

分组倍率 —— 给新分组标价,也就是打几折

{
  "kimi自部署": 0.52,
  "kimi云厂商": 0.45,
  "glm云厂商": 0.33,
  "通用": 1
}

用户可选分组 —— 把它加进「有哪些分组」这份名单

{
  "kimi自部署": "Kimi 自部署",
  "kimi云厂商": "Kimi 云厂商",
  "glm云厂商": "GLM 云厂商",
  "通用": "通用"
}

分组特殊可用分组 —— 决定哪些账号能看到它

{
  "kimi入口": {
    "+:kimi自部署": "可见",
    "+:kimi云厂商": "可见"
  }
}

auto 分组顺序 —— 系统自己挑的时候,按便宜到贵排

["glm云厂商", "kimi云厂商", "kimi自部署", "通用"]

四处里最容易漏的是 auto 分组顺序。只改了分组倍率,分组是存在了,但设成 auto 的账号永远轮不到它——因为 auto 就是「让系统自己挑分组」,挑的顺序照着这个名单从左往右走。名单里没有的名字,等于不存在。


八、自己先测通,再通知客户

配置做完,别急着通知客户,自己先测一遍。

进「渠道管理」,右上角把视图从表格切换成卡片视图——卡片上每条线路的状态和支持的模型一眼就能看到。找到这条新线路,点「测试」,把客户会用到的那几个模型逐个发一条。

测试通过,不等于没问题。 测试是直接打这条线路,中间「挑分组、挑线路」那些步骤全跳过了。所以它只回答一件事:这条线路本身通不通。它不回答另一件事:客户的请求会不会真的被分到这条线路上。这两件事得分开确认。

确认的方法,是打开「使用日志」看真实请求。上线后的头两天盯两件事:

  • 有没有请求真的走到它。 日志里按这条线路的名字筛一下。一条都没有,说明分组或者排队号码没对上,回去检查「分组」栏写的名字对不对、优先级是不是排在了最后。
  • 失败率高不高。 新线路刚接进来,上游那边可能还没调好。失败率明显高于同分组的其他线路,先别急着调顺序,把失败的记录整理一份发给上游。

把这条线路的「自动禁用」打开。 打开之后,它要是连续失败,系统会自动把它下线,不再往上发请求。新线路头几天最容易出问题,这个开关就是给它准备的保险。

没生效的时候,按这个顺序看

现象 先看哪里 通常是这个原因
客户说看不到这个新分组 分组倍率 + 用户可选分组 分组没配全,或者没加进名单
设成 auto 的账号走不到新线路 auto 分组顺序 名单里没有这个分组名
测试能通,日志里却一条请求都没有 渠道的「分组」栏 分组名写错了,或者排队号码排在了最后
请求报「无可用渠道」 渠道的「分组」栏 + 模型勾选 分组名对不上,或者这个模型没勾上

跑顺之后,这条线路就进入日常巡检范围了。后面再出问题,按《MaaS 渠道故障排查》那套顺序查就行。


九、接入顺序

flowchart TD
    S1["先把四样东西要齐<br/>网址、钥匙、模型清单、打几折"]
    S2["按四段式起名字<br/>de_0.52x_kimi-k3_自部署"]
    S3["新建渠道:类型、名称、网址、钥匙<br/>必须走代理的,在这里一并配上"]
    S4["勾模型<br/>只勾上游真的支持的"]
    S5["填「分组」<br/>写已经有的分组名,逗号隔开"]
    S6["排优先级<br/>按折扣放到对应的一层"]
    S7["自己先测一遍<br/>卡片视图里点测试"]
    S8["再通知客户,盯两天日志<br/>看有没有请求真的走到它"]
    X["是新分组?<br/>四处配置一起改"]

    S1 --> S2 --> S3 --> S4 --> S5 --> S6 --> S7 --> S8
    S6 --> X

前面两步是判断,中间四步是填表,最后两步才是验证。顺序反了就要返工。

判断在前,填表在后。 名字、分组、排队号码,都是从「打几折 + 模型清单 + 资源类型」这三样推出来的——这三样清楚了,后面每一步都是照着填。


用到的页面都在后台左侧菜单里:渠道管理、系统配置(分组相关设置)、使用日志。

Updated by 商宗康 商 about 2 months ago · 1 revisions