UPSTREAM CONNECTION
将 RootFlowAI 接入 sub2api
配置 RootFlowAI 上游 Key、Claude/GPT/Gemini 连接、模型分组和复合路由,让员工通过企业网关访问模型。
本页由企业管理员操作:先创建一个可用的模型分组和 RootFlowAI 上游连接,再根据需要配置复合分组,让员工一个 Key 使用多个模型平台。
配置参考 sub2api v0.2.21,运行模式为 standard。请先完成企业网关部署,并确认 RootFlowAI 账户有可用余额和所需模型权限。
本页 S05–S08 来自实际部署的本地 sub2api v0.2.21,使用演示分组、模型和假 Key。截图展示配置方法;上游模型权限与实际调用需要按第 7 步另行验证。
1. 在 RootFlowAI 创建专用上游 Key
- 登录 RootFlowAI API Key 管理页。
- 创建企业网关专用 Key,例如命名为
Company-Sub2API-Claude。 - 选择可以使用目标模型的分组,核对模型限制、额度和有效期。
- 安全保存完整 Key,随后填入 sub2api 的上游账号。

图 S04-A:点击“创建 API Key”,在“名称”中填写企业网关用途,并在“令牌分组”中选择账户已授权的分组。查看清晰原图。

图 S04-B:向下滚动,核对“可用额度(USD)”及“模型限制”。选择模型后,该 Key 仅允许调用所选模型;不选择时不额外限制模型范围,仍受账户和分组权限约束。查看清晰原图。
以上为本地 mock 数据的实际界面截图,未创建真实 Key。分组名称、两个模型和 USD 200 额度均为示例,实际应按账户权限与企业预算设置,并核对有效期;选择模型不会增加账户原有的模型权限。
上游 Key 用于企业网关连接 RootFlowAI,不直接发给员工。需要不同模型平台或预算隔离时,可在同一个 RootFlowAI 账户下分别创建专用 Key。
2. 创建第一个模型分组
先以 Claude 为例。在 sub2api 管理员后台打开“分组管理”,新增一个分组:
| 字段 | 建议填写 | 说明 |
|---|---|---|
| 名称 | 企业 Claude | 供管理员和员工识别 |
| 平台 | Anthropic | 对应 Claude Messages 协议 |
| 订阅类型 | 标准类型 standard | 使用员工余额进行内部计费 |
| 专属分组 | 开启 | 只有管理员授权的员工才能使用 |
| 分组倍率 | 初始可用 1 | 表示按 sub2api 当前价格基准记录,不代表与采购价一致 |
保存后再关联上游账号。如果有模型白名单,先只开放企业实际需要且上游 Key 有权限的模型。不要把分组当作公司部门;它首先承载平台、路由、计价与授权配置。
3. 添加 RootFlowAI 上游账号
打开“账号管理”,新增上游账号。以 Claude 为例:
| 字段 | 填写内容 |
|---|---|
| 名称 | RootFlowAI-Claude |
| 平台 | Anthropic |
| 接入类型 | API Key |
| Base URL | https://api.rootflowai.com |
| API Key | 第 1 步创建的 RootFlowAI 上游 Key |
| 所属分组 | 企业 Claude |
| 模型限制或映射 | 使用上游 Key 实际可用的模型 ID;初次接入保持同名 |
| 状态 | 启用 |

图 S05:平台选择 Anthropic,账号类型选择 Claude Console / API Key。选中后地址框会先显示官方默认值,下一步要换成 RootFlowAI 地址。查看清晰原图。

图 S06:上方地址输入框填写 https://api.rootflowai.com,API Key 输入框保持遮蔽,模型白名单只保留企业需要的模型 ID。图中 claude-sonnet-4-6 为示例;以你的上游权限为准。查看清晰原图。
这里选择 API Key,不需要执行 OAuth 登录或导入订阅账号。上游界面可能出现“官方 API Key”等说明,本场景使用的是 RootFlowAI Key,必须同时填写 RootFlowAI 的自定义地址。
4. 增加 GPT 或 Gemini 连接
按企业需要,分别创建对应平台分组和上游账号。先使用下表的根地址,避免把完整请求路径填入 Base URL:
| 模型平台 | sub2api 平台 | 接入类型 | 上游 Base URL | 对应上游协议 |
|---|---|---|---|---|
| Claude | Anthropic | API Key | https://api.rootflowai.com | /v1/messages |
| GPT | OpenAI | API Key | https://api.rootflowai.com | /v1/responses 或 /v1/chat/completions |
| Gemini | Gemini | API Key | https://api.rootflowai.com | /v1beta/models/{model}:generateContent 等原生路径 |
本表只说明地址和协议关系,不表示所有 Key 都已开通全部模型。以 RootFlowAI 账户的可用模型和所选协议能力为准;不能仅凭模型名称判断它支持哪个接口。
GPT 用于 Codex 时,需要上游账号支持 Responses,并在账号中正确设置 Responses API 支持方式;不要把仅支持 Chat Completions 的连接当作原生 Responses 连接。已有代理或客户端配置不应自动覆盖这里的平台选择。
Base URL 填根地址;不要填写 /account、登录页、完整 /v1/messages 或 /v1/responses 请求地址。v0.2.21 的 OpenAI 地址逻辑也可处理 /v1 后缀,但统一使用表中的根地址更便于核对三种平台配置。

图 S07:账号列表的“分组”列显示关联结果。三个演示上游分别属于对应平台分组,并同时关联 企业统一模型。状态正常、调度开启,只表示配置已启用。查看清晰原图。
5. 为员工配置一个多平台 Key
只需要一个平台时,可以继续使用第 2 步创建的普通分组。需要同一员工 Key 使用多个平台时,创建复合分组:
- 在“分组管理”中新建
企业统一模型,平台选择复合平台composite。 - 订阅类型选择标准类型
standard,开启专属分组。 - 创建时通过“从分组复制账号”选择前面准备好的平台分组,将对应上游账号关联到复合分组;也可以编辑上游账号,把它直接关联到复合分组。
- 确认每个需要使用的平台都有启用的上游账号。这里只建立关联,不需要重复填写相同的上游 Key。
- 核对模型路由和价格,然后在下一篇教程中把这个复合分组授权给员工。
使用标准模型名称时,复合分组可识别常见模型前缀,例如 claude-*、gpt-*、gemini-*。企业使用自定义模型别名时,应在该分组的“路由”操作中添加明确规则。
| 路由字段 | 如何填写 |
|---|---|
| 公开模型 | 员工工具发送的模型 ID |
| 匹配方式 | 初次配置优先精确匹配,减少误路由 |
| 目标平台 | 该模型实际对应的 Anthropic、OpenAI 或 Gemini 等平台 |
| 上游模型 | RootFlowAI 接受的真实模型 ID;同名时保持一致 |
| 端点 | 与实际请求匹配,如 Messages、Responses、Chat Completions 或 Gemini |
| 状态 | 启用 |
通过“预览”检查模型和端点会命中哪个平台。路由预览只验证规则,不代表已经完成模型调用。新建路由也不会自动补齐模型价格或所有模型元信息。

图 S08-A:确认分组的平台为 Composite、计费类型为“标准(余额)”、类型为“专属”,再点击操作列中的“路由”。上游关联结果见图 S07。查看清晰原图。

图 S08-B:演示模型分别路由到对应平台和端点。公开模型与上游模型保持同名,减少初次配置时的映射问题。查看清晰原图。

图 S08-C:向下滚动到“预览”,输入模型 ID、选择实际请求端点,再点击右侧运行按钮。本地预览显示命中 Anthropic 和同名模型;此操作不发送生成请求。查看清晰原图。
不要尝试把一个普通 Key 同时绑定多个普通分组。这里的多平台访问由复合分组完成。完整规则见 sub2api 复合分组文档。
6. 核对内部价格
在向员工分配预算前,核对 sub2api 中目标模型的输入、输出、缓存等价格,以及分组倍率。对于自定义模型或别名,确认对应平台下已有正确价格。
初期采用默认价格和倍率 1 时,员工余额代表按该价格基准计算的内部预算。它不是 RootFlowAI 采购成本的自动镜像。需要按成本分摊时,参考 RootFlowAI 模型价格和计费说明进行校准,避免把缓存或倍率重复计算。
7. 完成第一次验证
创建一名试点员工,分配少量内部余额,授权目标分组并创建员工 Key。详细步骤见添加员工与设置预算。
以 OpenAI Responses 为例,在管理员自己的测试终端中执行。使用 Bash,先输入企业域名和实际可用的 GPT 模型 ID,再在隐藏输入中粘贴试点员工 Key:
export COMPANY_AI_URL="https://ai.example.com"
read -r -p "实际可用的 GPT 模型 ID: " COMPANY_AI_MODEL
read -r -s -p "试点员工 API Key: " COMPANY_AI_KEY
printf '\n'
export COMPANY_AI_MODEL
python3 - <<'PY' > /tmp/company-ai-probe.json
import json, os
print(json.dumps({
"model": os.environ["COMPANY_AI_MODEL"],
"input": "Reply with company-ai-ok",
"max_output_tokens": 64,
"stream": False
}))
PY
curl --fail-with-body --max-time 120 "$COMPANY_AI_URL/v1/responses" \
-H "Authorization: Bearer $COMPANY_AI_KEY" \
-H "Content-Type: application/json" \
--data-binary @/tmp/company-ai-probe.json
unset COMPANY_AI_KEY
rm -f /tmp/company-ai-probe.json实际模型请求会消耗 RootFlowAI 上游额度,并按企业配置记录员工内部用量。先检查域名、权限和模型 ID,再发送一次短请求;错误未定位前不要反复重试。
完成标志:收到有效模型回复,sub2api 能查到该试点员工的使用记录,RootFlowAI 能查到对应上游消耗。其他协议应分别使用对应客户端或请求格式验证;仅看到模型列表或保存成功,不等于生成请求已经打通。