供应商与账号接入
本文解决什么问题 / 何时读:使用者要把已有的 API key、订阅登录或插件接入 Magpie,并需要理解接入后模型为什么在客户端里看不见、多个账号为什么落到不同来源、以及额度打满时请求会去哪里。在「新建 provider」「登录后不生效」「客户端选不到模型」「多账号落点随机」这四类问题出现时读本文。
本文只讲接入与接入后的行为。组内路由语义、规则坑位与实测差异以路由治理为准;CLI 写入语法与凭证边界以CLI 与变更边界为准;额度分类与成本边界以额度、任务与成果为准。命令形态一律先以安装版 magpie --version 和实际帮助为准。
以下命令在 Skill 目录内执行,scripts/、config/、state/ 均相对该目录。
三种接入方式
| 方式 | 适用资源 | 命令入口 | 凭证落在哪 | 典型可用模型来源 |
|---|---|---|---|---|
| A. API key | 自有密钥的按量或套餐接口 | magpie provider add <preset> <your-key> |
Magpie 本机 provider 配置(默认 ~/.config/magpie/providers.json,尊重 XDG_CONFIG_HOME) |
该 provider 暴露的 example/model-strong、example/model-fast |
| B. OAuth / 订阅登录 | 有订阅会话或需真人授权的平台 | magpie accounts add <agent>、magpie accounts import <agent> |
登录态由平台侧持有,Magpie 只保存账号引用与状态 | 订阅内模型,如 example/model-strong |
| C. 插件接入 | 由插件封装的平台、自建后端或非标准协议 | 插件安装与插件配置入口(见插件与客户端接入) | 插件自己的配置位置,不经 provider 配置 | 插件自行暴露的模型目录 |
选择顺序:
- 平台给的是可复制的密钥,走 A。
- 平台只给网页登录或订阅会话,走 B。
- 平台需要专用协议或自建服务,走 C;插件尚未安装时先读插件与客户端接入,不要用 A 的 key 形态硬接。
A. API key 接入
命令入口(形态示意,按安装版 magpie provider --help 核对):
magpie provider add <preset> <your-key>步骤:
- 获取 key。在供应商控制台单独生成,命名可辨识(区分个人 / 团队用途),权限取最小范围。key 只在需要时生成一次,不复用、不外发。
- 执行命令。把
<preset>换成安装版提供的供应商预设名,把<your-key>换成实际密钥。为避免落入 shell 历史,用交互式输入或环境变量读取(见安全边界)。 - 回读配置。
magpie providers(安装版对应列表入口)确认 provider 已出现且状态可用;再magpie provider models example/provider-a看它暴露了哪些模型。 - 直连测试。安装版若提供
magpie provider test example/provider-a,用它确认凭证本身可用。命令不存在时,改用一次最小直连请求核凭证(见接入后的验证)。
常见偏差:
| 偏差 | 表现 | 排查与处理 |
|---|---|---|
| key 贴错位置 | key 被当成模型名,模型目录出现异常条目,或 provider 一直不 ready | 回读 provider 条目与模型列表,确认密钥没有落进模型 ID 或其它位置字段;删掉误建条目后重加 |
| 多平台共用一个 key | 一个平台成功,另一个平台报认证失败 | key 与平台一一对应;核对 base URL 与平台绑定,不要跨平台复用同一密钥 |
| key 泄漏到 shell 历史 | 命令可在历史或会话记录中检索到密钥 | 改用交互式输入或环境变量;已泄漏的 key 立即在控制台吊销并重建,不做「先留着」 |
| exit 0 但能力不存在 | magpie provider <子命令> --help 只返回总帮助 |
exit 0 不证明子命令存在;必要时在隔离 HOME/XDG 下核对参数(口径见CLI 与变更边界) |
B. OAuth / 订阅登录接入
命令入口(形态示意,按安装版帮助核对):
magpie accounts add <agent>
magpie accounts import <agent><agent> 是接入方(客户端)标识。add 走新增账号流程,import 用于导入已存在的账号记录。
步骤:
- 触发登录。执行
magpie accounts add <agent>,按提示进入平台授权流程。 - 完成授权。授权页、2FA、验证码都由真人在平台侧完成;代理或网关侧不能代替这一步。
- 确认账号出现。回读账号列表,确认账号标签、状态与是否已启用。列表里只以脱敏标签出现。
- 核模型目录。
magpie provider models example/provider-b确认订阅内模型已暴露;再到客户端侧确认该模型在可见列表内(见可见性控制)。
常见偏差:
| 偏差 | 表现 | 排查与处理 |
|---|---|---|
| 登录态过期 | 请求返回认证类错误,账号标记失效 | 需真人重新登录,网关侧不能代替;先保留失败证据与时间窗再交账号 owner 处理 |
| 团队号与个人号混淆 | 同一 provider 下两个账号外观相近,落点归属说不清 | 用脱敏标签分别标注归属与计费主体;确认归属不是「同一个 provider 的两个账号」就算区分开了 |
| 登录成功但模型仍不可见 | 账号已登录,客户端列表为空 | 先核可见性开关与客户端目录,再核 provider 是否真的暴露该模型;不要先改组 |
| 重复登录生成多个账号 | 同一订阅出现多条账号记录 | 接入前先看账号列表,确认是否已存在;重复记录会增加并发与额度的归因难度 |
C. 插件接入
插件接入用于平台需要专用协议、自建后端或非标准鉴权的情况。形态是「安装插件 → 在插件配置里填自己的凭证 → 插件向 Magpie 暴露一组模型」:凭证落在插件自己的配置位置,不写入 provider 配置,也不参与 provider 级账号并发与队列。
要点:
- 插件暴露的模型与 provider 暴露的模型在客户端侧表现一致,都要过可见性这一关。
- 插件的安装与初始化可能下载其运行时;不希望联网时使用离线方式核对,不自动执行 sync、update 或 plugin install。
- 插件相关的客户端配置、模型目录与排障细节见插件与客户端接入。
可见性控制
可见性回答的是「哪个客户端能看见哪些模型」,与路由组回答的「请求落到哪个模型」是两层事。
| 命令 | 作用 | 典型用途 |
|---|---|---|
magpie visible <agent> ... |
控制该客户端在模型目录里能看见哪些模型 | 客户端装好了但列表为空、想对某个客户端隐藏某组模型 |
magpie provider models <provider> |
查看某个 provider 暴露的模型 | 确认模型是否已被 provider 暴露、模型 ID 是否正确 |
magpie models <agent> |
查看某客户端当前可见的模型列表 | 核可见性调整是否真的生效 |
判读顺序:
- 模型没在目录里,客户端就选不到。先确认模型在 provider 侧已暴露,再确认它在目标客户端的可见列表里。
- 改 Magpie 的组不影响未接入的客户端。客户端没有指向本机网关、或走原生直连时,组内成员和顺序对它没有作用。
- 客户端目录可能是静态快照,不会因 Magpie 新增组而自动刷新;重建目录与重启客户端的核验方法见路由治理。
- 客户端可见目录与「Magpie 是否单独列出组成员」是不同层级,两者都要分开核。
多账号 provider
同一 provider 下挂多个账号时,Magpie 的选择方式有两种。两者不是「有没有生效」的区别,而是「按什么规则选」的区别。
| 行为 | 表现 | 何时用 |
|---|---|---|
| 默认按余量智能挑选 | 系统按各账号剩余额度 / 健康度选,当前余量好的账号优先 | 账号之间能力等价、可互换,谁服务结果都合格 |
| 显式账号顺序 | 按设定顺序尝试,前一个不行才轮到下一个 | 账号之间有偏好差异,如个人账号优先、团队账号兜底 |
何时需要显式顺序:
- 能力不同。账号 A 支持长上下文或图像,账号 B 不支持;余量挑选可能选到 B。
- 额度窗口不同。账号 A 是短周期窗口、账号 B 是长周期窗口,按余量挑选会让消耗落在非预期窗口。
- 账号归属不同。个人账号与团队账号混在同一 provider,余量挑选无法保证不误用他人配额。
- 需要保证不误用他人配额。这一条本身就足以要求显式顺序,而不是依赖余量。
字段口径与设置路径:
| 环节 | 形态 | 说明 |
|---|---|---|
| 配置层级 | provider 级配置项 | 账号顺序挂在 provider 上,不是组内成员顺序。组内 routing 管的是「成员模型之间」,账号顺序管的是「同一 provider 的账号之间」,两层互相独立 |
| GUI 入口 | provider 设置页的账号区 | 调整账号先后顺序 |
| CLI 入口 | 形态示意 magpie provider <account-order> <provider> ... |
子命令名以安装版 magpie provider --help 为准;部分版本可能只在 GUI 暴露该入口 |
| 回读 | 再次读取 provider 的账号列表 | 设置后必须回读确认顺序真的生效 |
| runtime 证据 | routing log 的 per-try tries 与 served model |
运行时实际尝试了哪个账号 |
设置后必须回读确认顺序真的生效。否则会出现「看起来生效、实际仍按余量挑选」:配置层顺序已改,但运行时仍在按余量择一,落点与预期不一致。
「配置顺序 / CLI 声明语义 / runtime 观测」三层的区别,以及为什么 runtime 数组不能反推配置顺序,见路由治理 的 order 三层事实一节。
额度窗口、并发与队列、账号休息
- 额度窗口:短周期(如数小时)、周、月等窗口并存,不同窗口不能换算成一个百分比。
quota.resetsAt、订阅until与积分批次expires_at互不等价;任一项读不到时保留未知,不写成 0,也不按另一种窗口推算。 - 并发:并发上限是账号级的,跨模型、跨组、跨客户端共享同一账号池。多建组不增加容量;两个入口消耗同一账号池时,先核对来源再计容量。
- 队列:有界队列决定排队长度与最长等待时间。等待超时属于队列层,不等于额度耗尽。
- 账号休息:额度打满后账号进入不可用状态,请求转向下一个来源;休息是有起点的时间窗,会自己过期,不是配置错误。
| 现象 | 属于哪一层 | 先查什么 | 不要做什么 |
|---|---|---|---|
| 剩余百分比看起来还有,请求仍被拒 | 额度窗口层 | 各窗口分别读数(magpie quota --json),区分订阅窗口与积分批次 |
不要把多个窗口合成一个百分比再判断 |
| 429、queued、retry in Ns | 并发层 | provider 账号级并发上限与有界队列 | 不要多建组或重复加成员来「扩容」 |
| 账号突然不服务,请求落到下一个来源 | 账号休息层 | 该账号的当前窗口读数与休息时间窗 | 不要立刻改配置、重置账号或删 provider 记录 |
| 请求等待较久但没有失败 | 队列层 | 队列长度与等待时间设置 | 不要把它当成额度耗尽去改额度策略 |
| 客户端看不到刚接入的模型 | 可见性层 | magpie provider models <provider> 与客户端可见列表 |
不要改 Magpie 的组来解决可见性问题 |
| 同一 provider 下两个账号落点说不清 | 账号层 | 显式账号顺序与回读结果 | 不要只凭余量挑选结果反推归属 |
账号级参数按CLI 与变更边界 的原生命令维护:
magpie provider account-concurrency <provider> <account-or-key-id> 1
magpie provider queue <provider> 2 15
magpie provider rpm <provider> <已确认的每分钟上限>省略修改值即为查询。账号并发在跨模型、跨组、跨客户端共享;off 或 0 表示不限,不能当「停用」。
接入后的验证
命令成功不等于已生效。四步逐步做,任一步缺证据都不算接入完成。
直连请求。发一条最小真实请求确认凭证可用:
magpie <agent> <model> <prompt><model>用<provider>/<model-id>或group/<group-id>形态,<prompt>用一句可判定的短请求。看路由日志确认实际 served model。路由日志的 per-try
tries给出尝试序列,served给出最终服务模型。响应体里的model可能是组名,不一定是最终成员。核
magpie usage today落点。看实际 provider/model、状态与错误聚类,确认落点符合预期。注意用量来源可能重叠,不把不同来源直接相加。核配置回读。重新读取 provider、账号与组的配置,确认写入内容与顺序确实落盘。
判定口径:
| 现象 | 结论 |
|---|---|
| 命令返回成功 | 只证明命令执行完,不证明已生效 |
| HTTP 200 | 只证明通道通,不等于任务质量通过;内容质量由任务验收判断 |
| 配置回读一致 | 只证明落盘(记 CONFIG_READBACK_VERIFIED),真实落点仍需代表性请求 |
| 客户端列表出现模型 | 只证明可见性调整生效,不代表路由已指向它 |
辅助入口(按文件名引用,可能尚未落地):
scripts/magpie_preflight.py:接入前自检,核对安装版、配置可读性与前置条件。scripts/magpie_inventory.py:盘点已接入的 provider、账号与模型,输出脱敏清单。scripts/public_release_check.py:发布前扫描文档与脚本中的凭证、真实路径与身份信息。
安全边界
⚠️ 以下为硬性边界,不因「方便验证」放宽。
| 规则 | 具体做法 |
|---|---|
| 凭证只交给 Magpie | key、token、密码不写进任何 Skill 文件、脚本、文档、报告、截图或命令历史 |
| 示例只用占位 | 命令与示例一律用 <your-key>,不出现任何真实 key 或 token 形态的字符串(不写真实长度、前缀或结尾片段) |
| 避免落入历史 | 用交互式输入或环境变量读取密钥;必要时用 read -s 或从受控文件读取,不要把密钥作为命令行参数明文传递 |
| 不粘贴片段 | 报告、日志摘要、issue 与聊天中都不粘贴 key 的任何片段,包括首尾几位 |
| 账号只用脱敏标签 | 账号以 account-a / account-b 形式出现;不写真实账号名、邮箱、昵称与登录标识 |
| 读数也要脱敏 | magpie quota --json 的 raw 含账号信息,不直接输出;magpie provider account-concurrency 可能打印私有账号,只保留限制值 |
| 不整体导出配置 | providers.json 含密钥,不整份放进报告、测试或 Git;读取只在进程内做比较与白名单投影 |
| 不顺手改动 | 一次接入不顺带开启已关闭的供应商、重置额度、切换登录态或改所有客户端默认模型 |
自查口径:文档中出现的每个凭据位置都应是尖括号占位;每个身份都应是脱敏标签;每条路径都应是 <skill-dir>/...,本机私有文件应写成 config/<name>.local.json 或 state/<name>.json;每个端口都应是 <port>。发布前用 scripts/public_release_check.py 或等效人工检查复核一遍。
回读与证据边界
- 接入类结论的证据来源只有三类:安装版 CLI 帮助与回读、配置文件的字段回读、真实请求的 served model。三者互不替代。
- 命令返回成功、配置写入成功,都只是中间证据;「已生效」需要一次落到预期来源的代表性请求。
- 读不到的字段保留未知,不写 0、不按同类字段推算;额度、并发与队列的读数各自独立,不互相推导。
- 本文只描述接入与接入后的行为,不复述组内路由的实测坑细节;相关排障顺序与版本差异见路由治理。
- 命令形态随安装版变化。执行前先读
magpie --version与对应--help;若某子命令只返回总帮助,标NOT_VERIFIED并按CLI 与变更边界 的隔离方式核对,不在生产配置上试探。