𝐗𝐀𝐈 𝐂𝐨𝐧𝐭𝐫𝐨𝐥

常见问题

BYOK 相关问题

什么是 BYOK（Bring Your Own Key）？ BYOK 意为"携带您自己的密钥"。在 XAI Control 中，这意味着您使用自己在 OpenAI、Claude、DeepSeek、Gemini 等官方平台申请的 API Keys，而不是从 XAI 购买密钥。 平台会以受保护方式托管这些密钥，用于统一路由与治理；仅在授权调用流程中由系统代表您完成必要使用。

核心优势：
  • ✅ 完全掌控：密钥所有权归您，可随时更换、删除或迁移
  • ✅ 零中间费用：API 调用费用直接由您的官方账户扣除，无任何加价
  • ✅ 成本透明：您可以在官方平台（如 OpenAI Dashboard）直接查看原始账单
  • ✅ 数据主权：敏感凭证以受保护方式托管，系统管理员无法直接查看其原始内容
详见《BYOK：您的密钥，您的掌控》

XAI Control 的 BYOK 和 OpenRouter 有什么区别？
特性XAI ControlOpenRouter
是否必须 BYOK✅ BYOK 架构，无其他选项❌ 可选 BYOK 或使用平台付费池
BYOK 费用✅ 完全免费❌ 收取 5% 服务费
免费额度✅ 无限制（使用自己的 Key）⚠️ 100 万次/月后需付费
私有化部署✅ 支持❌ 仅云服务
示例成本对比：如果您每月调用 100M tokens 的 GPT-4，使用 XAI Control 相比 OpenRouter 每月节省约 $1,500。

我的 Provider Keys 安全吗？会不会被 XAI 滥用？ 绝对不会。XAI Control 采用受保护托管与授权链路控制机制：

技术保障：
  • 🔒 受保护托管：平台保存的是受保护的敏感凭证材料，而不是面向外部暴露的普通明文数据
  • 🔒 隔离保护：不同账户的敏感凭证在托管与使用边界上彼此隔离
  • 🔒 无超级管理员：系统管理员、数据库管理员均无法解密您的密钥
  • 🔒 审计日志：所有密钥使用都有完整日志，可追溯到具体请求
  • 🔒 即使数据库泄露：攻击者也无法还原您的 Provider Keys
合规认证：
  • 通过 SOC 2 Type II 认证（计划中）
详见《BYOK：您的密钥，您的掌控》

如果我想停止使用 XAI Control，如何迁移数据？ BYOK 的最大优势就是零供应商锁定：

迁移步骤：
  1. 整理接入配置：通过控制台或既有接入信息整理当前所需配置
  2. 复制密钥：您的原始 Provider Keys 始终在官方平台（如 OpenAI Dashboard），直接复制即可
  3. 切换 base_url：在您的应用或新平台中修改 API 端点
  4. 完成迁移：无需等待审批，立即生效
传统平台的痛点：
  • ❌ 无法导出密钥（您从未拥有）
  • ❌ 需要重新申请所有官方 API Keys
  • ❌ 历史用量数据无法迁移

BYOK 模式下，为什么 XAI Control 还需要我的 XAI API Key？ 这是两类凭证分工：

  1. Provider Key（上游密钥）：您在 OpenAI、Claude 等官方平台申请的原始密钥，由您添加到 XAI Control 并以受保护方式托管；仅在授权调用流程中由系统代表您完成必要使用
  2. XAI API Key（虚拟密钥）：XAI Control 分配给您的代理密钥（格式：sk-Xvs...），用于：
    • 认证您的身份
    • 路由请求到正确的 Provider Key 池
    • 承载您的访问控制与治理规则
    • 记录使用情况与审计信息
工作流程：
您的应用 → 使用 XAI API Key 调用 → XAI Control 验证并路由 → 使用您的 Provider Key 调用官方 API → 费用从您的官方账户扣除

技术问题

为什么有些 API 调用会报 404 Not Found 错误？ 这通常是因为您的 `base_url` 配置不正确。许多库（如 LangChain）要求 `base_url` 必须包含 `/v1` 后缀，而不仅仅是域名。

请检查您的配置，确保其为 `https://api.xaicontrol.com/v1` (针对 OpenAI 兼容接口)。

为什么会报 401: Incorrect API key provided... 错误？ 这个错误表明您的请求被发送到了 OpenAI 的官方服务器，而不是 XAI Control 对应的代理服务。这通常是因为您只配置了 API Key，而没有将 API 的请求地址 (`base_url`) 修改为 `https://api.xaicontrol.com`。

如果我使用的开源项目不支持配置 `base_url` 怎么办？ 在这种情况下，您需要找到该项目的源代码，并将其中的 API 请求地址从 `api.openai.com` 硬编码修改为 `api.xaicontrol.com`。

为什么调用用户管理 API (如 /x-users) 会提示 401 Unauthorized？ 为了防止滥用，调用核心管理 API（如创建/管理子账户）对调用者账户的余额有最低要求。通常，您的账户余额需要大于 `$100` 才能获得相应的调用权限。请确保您的账户资金充足。

创建子账户需要满足什么条件？ 创建子账户需要满足两个主要条件： 1. 您的父账户余额需要大于 `$100`。 2. 为新创建的子账户进行的首次充值额度不能低于 `$2`。

在 XAI XAPI 系统中，每个账户都是独立的。只要一个子账户的余额也满足了上述条件，它同样可以创建自己的子账户。

为什么我的账户还有余额，但提示 "Insufficient balance"？ 为了防止透支和资产损失，当账户余额低于 `$1` 时，系统会禁止新的 API 调用。请及时充值。

为什么会报 429 Too many requests / Rate limit XXX reached？ 这表示命中了当前账户或模型的限流窗口，常见原因包括 `RPM`、`RPH`、`RPD`、`TPM`、`TPH`、`TPD`。如果报错里明确写的是 `RPH`，则表示该模型的每小时请求数已到上限。

请求数限流会在转发前执行；`TPD` 则按成功请求的实际 Token 用量后置累计，若某次成功请求刚好超额，通常从下一次请求开始返回 `429 TPD`。

建议处理方式：
  • 降低并发并加入指数退避重试
  • 先区分具体 reason：`RPM/RPH/RPD/TPM/TPH/TPD`
  • 将负载分散到不同时段或模型
  • 联系管理员提升对应额度或模型 `ModelLimits` 配额

RPH 是 300，为什么只成功了 40 次？ RPH 统计的是进入该窗口判断的尝试请求数，而用量统计只记录成功的请求。并发、自动重试或在触发阈值前失败的请求，都可能消耗 RPH，但不会进入成功用量统计。

例如：1 小时内尝试 300+ 次，其中 40 次成功，其余失败或被限流，因此会看到“成功 40，但 RPH 300 已达上限”。进入 `cooldown` 之后，继续被挡下的请求不会再把计数无上限抬高。

并发请求会全部被拦截吗？触发后要等多久？ 不会整批拦截，系统对每个请求单独判断：达到上限之前的请求会成功，超过上限的会返回 429。

恢复时间取决于命中的限制类型：
  • `RPM/TPM`：通常约 1 分钟
  • `RPH/TPH`：通常约 1 小时
  • `RPD/TPD`：自然日额度，到服务端当天结束后恢复
系统还会使用独立 `cooldown` 抑制反复探测。短窗口命中后，如果客户端持续无退避重试，冷却期会被刷新；日额度命中后，冷却只到当天结束，不会因重试拖到次日以后。

为什么我感觉限额一直不清零？ 先看报错里的 reason：
  • `RPM/RPH/TPM/TPH`：通常表示还在短窗口或 `cooldown` 内
  • `RPD/TPD`：表示当日额度已经用完，需要等服务端业务日期切到下一天
`RPD/TPD` 是自然日额度，不是“过去 24 小时滚动窗口”。如果命中的是短窗口限制，持续重试本身就可能刷新 `cooldown`，所以体感上会像“限制一直持续”。正确做法是降低并发、做指数退避，并根据具体 reason 判断是等窗口恢复还是等到次日。

← Codex CLI / App（API Key 接入）