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

  1. 登录 RootFlowAI API Key 管理页。
  2. 创建企业网关专用 Key,例如命名为 Company-Sub2API-Claude。
  3. 选择可以使用目标模型的分组,核对模型限制、额度和有效期。
  4. 安全保存完整 Key,随后填入 sub2api 的上游账号。
本地演示的 RootFlowAI 创建 API Key 表单,名称为 Company-Sub2API-Claude,选择 Claude 企业示例分组

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

本地演示的 Key 限制配置:关闭无限额度,示例额度为 USD 200,模型限制选中两个 Claude 模型

图 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 URLhttps://api.rootflowai.com
API Key第 1 步创建的 RootFlowAI 上游 Key
所属分组企业 Claude
模型限制或映射使用上游 Key 实际可用的模型 ID;初次接入保持同名
状态启用
添加账号窗口中选择 Anthropic 平台和 Claude Console API Key 类型

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

上游地址改为 https://api.rootflowai.com,API Key 已遮蔽,模型白名单仅保留 claude-sonnet-4-6

图 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对应上游协议
ClaudeAnthropicAPI Keyhttps://api.rootflowai.com/v1/messages
GPTOpenAIAPI Keyhttps://api.rootflowai.com/v1/responses 或 /v1/chat/completions
GeminiGeminiAPI Keyhttps://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 后缀,但统一使用表中的根地址更便于核对三种平台配置。

Claude、GPT、Gemini 三条上游记录均正常,分别关联平台分组及企业统一模型复合分组

图 S07:账号列表的“分组”列显示关联结果。三个演示上游分别属于对应平台分组,并同时关联 企业统一模型。状态正常、调度开启,只表示配置已启用。查看清晰原图。

5. 为员工配置一个多平台 Key

只需要一个平台时,可以继续使用第 2 步创建的普通分组。需要同一员工 Key 使用多个平台时,创建复合分组:

  1. 在“分组管理”中新建 企业统一模型,平台选择复合平台 composite。
  2. 订阅类型选择标准类型 standard,开启专属分组。
  3. 创建时通过“从分组复制账号”选择前面准备好的平台分组,将对应上游账号关联到复合分组;也可以编辑上游账号,把它直接关联到复合分组。
  4. 确认每个需要使用的平台都有启用的上游账号。这里只建立关联,不需要重复填写相同的上游 Key。
  5. 核对模型路由和价格,然后在下一篇教程中把这个复合分组授权给员工。

使用标准模型名称时,复合分组可识别常见模型前缀,例如 claude-*、gpt-*、gemini-*。企业使用自定义模型别名时,应在该分组的“路由”操作中添加明确规则。

路由字段如何填写
公开模型员工工具发送的模型 ID
匹配方式初次配置优先精确匹配,减少误路由
目标平台该模型实际对应的 Anthropic、OpenAI 或 Gemini 等平台
上游模型RootFlowAI 接受的真实模型 ID;同名时保持一致
端点与实际请求匹配,如 Messages、Responses、Chat Completions 或 Gemini
状态启用

通过“预览”检查模型和端点会命中哪个平台。路由预览只验证规则,不代表已经完成模型调用。新建路由也不会自动补齐模型价格或所有模型元信息。

企业统一模型为 Composite 平台、标准余额计费和专属分组,操作列提供路由入口

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

复合分组已保存三个精确匹配路由,分别对应 Anthropic Messages、OpenAI Responses 和 Gemini 原生端点

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

输入 claude-sonnet-4-6 并选择 Messages,预览显示已匹配到 Anthropic 平台和同名上游模型

图 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 能查到对应上游消耗。其他协议应分别使用对应客户端或请求格式验证;仅看到模型列表或保存成功,不等于生成请求已经打通。

下一步:添加员工与设置预算。返回企业团队接入总览,遇到错误查看常见问题排查。