𝐗𝐀𝐈 𝐗𝐀𝐏𝐈

三分钟看懂：企业级 AI Router 的专业架构与快速上手

Posted October 5, 2025 ‐ 5 min read

你可能只关心两件事：① 这到底是什么；② 现在就能不能用。本文先给“马上能用”的方法，再用通俗语言把我们的专业架构与安全理念讲清楚。

若你想“使用官方账号（而非 API Key）”接入工具，请参考：
• Claude Code 官方账号接入 → 使用 XAI Control 分发 Claude Code
• OpenAI Codex 官方账号接入 → 通过 XAI Control 分发 OpenAI Codex

一句话说明我们是什么

一套“企业级 AI API 入口”。你只改 Base URL，就能用你自己的密钥（BYOK）调用 OpenAI / Anthropic / OpenAI Codex / Claude Code 等主流能力；同时内置限速、白名单、智能路由和可审计记账，适合直接上生产。

支持什么（开箱即用）

  • OpenAI 兼容：/v1/chat/completions、/v1/responses、/v1/embeddings、/v1/audio/* 等
  • Anthropic 兼容：/v1/messages
  • OpenAI Codex / gpt‑*-codex（代码补全）
  • Claude Code（IDE 辅助编码）：见《Claude Code 集成》
  • 其他主流：Gemini、Mistral、Cohere、DeepSeek、Grok、Perplexity…（带上 Provider Key 即插即用）

60 秒跑通（真的）

  1. 准备一把 API Key（你录入的 Provider Key）

  2. 只改 Base URL 即可：

export XAI_API_KEY="sk-Xvs..."
curl https://api.xaixapi.com/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}]}'

Node.js：

import OpenAI from "openai";
const client = new OpenAI({ apiKey: process.env.XAI_API_KEY, baseURL: "https://api.xaixapi.com/v1" });
const res = await client.chat.completions.create({ model: "gpt-4o-mini", messages: [{ role: "user", content: "hello" }] });

Python：

from openai import OpenAI
client = OpenAI(api_key="sk-Xvs...", base_url="https://api.xaixapi.com/v1")
resp = client.chat.completions.create(model="gpt-4o-mini", messages=[{"role":"user","content":"hello"}])

不改 SDK，不换写法，只改 base URL。

架构设计（通俗版）

我们的系统分三层，名字很学术，解释很简单：

  1. 控制平面（定规则）：

    • 模型映射（Model Mapper）：把旧名字映射到新模型，A/B 切换不改代码。
    • Level 映射（Level Mapper）：不同模型走不同“池子”，按成本/时延/稳定性分层。
    • Switch Over：明确“主备池”切换关系（如 1→2），触发条件可审计。
    • 资源白名单（Resources）：限制只允许哪些 API 路径。
    • 模型限速（Model Limits）：对贵模型设刚性上限，避免费用暴冲。

  2. 路由平面（跑得快）：

    • 同 Level 轮询选 Key，原子索引+细粒度锁，减少抖动。
    • 错误休眠：出错的 Key 暂停一会儿，别“连坐”健康 Key。
    • 显式切换：同 Level 重试不行，再按规则跨 Level，绝不黑箱兜底。
    • 传输优化：热连接池、HTTP/2、大缓冲、流式回传，压低尾延迟。

  3. 数据平面（看得清）：

    • 细粒度计量：按用户/模型/时间维度聚合，请求/Token/成本一目了然。
    • 管控闭环：AllowIPs/AllowModels/Resources 三类白名单 + Dashboard/Logs 统一可见。

安全与合规（四句话）

  • BYOK‑first：永远用“你的密钥”，不做隐式回落，不越计费与审计边界。
  • 密钥加密：敏感材料入库前清洗+加密；调用时即时解密，不落盘、不入日志。
  • 白名单到位：IP / 模型 / 资源三类白名单，继承不越级。
  • 失败可预期：超限/越权立即失败，避免“看不见的超支”。

成本与治理（也很直观）

  • 账单直达 Provider，折扣照常生效。
  • 用户/模型硬上限，先保护，再服务。
  • 自托管不加价，政策透明、总额可控。

下一步