用 X-All in one 的 OpenAI 兼容接口完成首个对话调用

X-All in one 是一个把多家基座模型聚合到统一接口下的 AI API 平台，主打自主可控与降本。对开发者来说，它最直接的价值是：业务代码按 OpenAI 的请求格式写一次，就能在 Qwen、GLM、DeepSeek 等不同模型之间切换，而不必为每家厂商各写一套适配层。平台还提供请求追踪、Token 消耗统计、模型性能对比等控制台能力，适合需要快速验证想法的小团队，也适合调用量较大、需要精细核算成本的企业用户。如果你只是想先看看这类聚合平台在站内的定位，可以从 X-All in one 这一条目入手，再回到本文按步骤接入。

下面这篇教程按「注册验证 → 生成密钥 → 发出第一个请求 → 用控制台做成本与稳定性管理」的顺序展开，每一步都给出可直接复制的请求示例。文中涉及的体验金、免费额度、价格折扣等数字属于易变信息，实际以官网当前公示为准。

准备工作

账号与验证

接入的第一步是开通账号。用邮箱完成注册并完成邮箱验证即可，验证通过后账号会自动获得体验金与若干免费模型调用额度，用来做首轮联调。体验金和免费额度的具体数额、有效期、适用模型范围会随活动调整，注册后在控制台的账户或计费页面确认当前数值，不要按旧文章里的数字做预算。

如果你所在的组织需要走采购或合规流程，建议在正式接入前先确认两件事：一是平台是否支持你需要的部署形态（公有 API 调用还是私有化交付），二是数据合规要求是否被满足。素材提到平台提供传输层加密、推理过程分阶段加密以及基于角色与属性的混合权限模型，并声称满足等保三级与 GDPR 相关要求；这类合规声明应以官方当前出具的说明与合同条款为准，不要仅凭介绍页做判断。

客户端环境

请求走的是标准 HTTP，任何能发 HTTPS 请求的语言都可以。素材明确提到提供 Python、Node.js、Java 等语言的 SDK 配置方式，也提到 SDK 文档覆盖多种语言。实际动手时，最省事的做法是先用 curl 验证通路，确认密钥和接口地址没问题，再换到项目里使用的语言 SDK。

需要准备的东西不多：

• 一个已完成邮箱验证的账号
• 控制台里生成的专属 API Key
• 接口基地址（base URL），从控制台的接入说明里获取
• 一个你打算先试的模型名称，从控制台的模型列表里选

API Key 属于凭据，不要写进前端代码、不要提交到公开仓库。建议放在环境变量里，由服务端读取后转发请求。

操作步骤

第一步：在控制台生成 API Key

登录控制台后进入密钥管理区域，生成一个专属 API Key。生成时通常可以给密钥起一个便于识别的名字，并按项目或环境区分——素材提到控制台支持按项目、环境、版本三个维度做用量归因，所以从一开始就按这个粒度命名密钥，后面看报表会轻松很多。例如给测试环境和生产环境各建一个密钥，而不是所有服务共用一个。

密钥生成后只显示一次完整值，复制后立刻存进密码管理器或部署平台的密钥存储里。如果怀疑泄露，直接吊销重建，不要试图「改一改再用」。

第二步：用 curl 验证接口通路

平台提供与 OpenAI 兼容的对话补全接口 /v1/chat/completions，请求体使用标准 OpenAI 格式参数。先用一条最小请求确认密钥、地址、模型名三者都对得上：

export XALLINONE_API_KEY="你的 API Key"
export XALLINONE_BASE_URL="控制台给出的接口基地址"

curl -s "$XALLINONE_BASE_URL/v1/chat/completions" \
  -H "Authorization: Bearer $XALLINONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "你在控制台选定的模型名",
    "messages": [
      {"role": "system", "content": "你是一名简洁的技术助理。"},
      {"role": "user", "content": "用三句话说明什么是向量检索。"}
    ],
    "temperature": 0.3,
    "max_tokens": 512
  }'

几个参数的含义与用法：

• model：必填，取值来自控制台的模型列表。不同基座模型的名称不同，切换模型就是改这一个字段。
• messages：必填，按角色排列的对话数组，system 用于设定行为，user 是用户输入，多轮对话时把历史消息按顺序带上。
• temperature：采样随机度。做分类、抽取这类需要稳定输出的任务时调低，做创意生成时调高。
• max_tokens：限制单次回复的最大长度，用来防止意外超长输出推高费用。

如果返回 401，先检查 Authorization 头里的 Bearer 前缀和密钥是否完整；返回 404 多半是基地址拼错，注意不要在基地址末尾重复加 /v1；返回模型不存在的错误，则回到控制台核对模型名是否在当前账号可用范围内。

第三步：在 Python 中调用

因为接口兼容 OpenAI 协议，可以直接用 OpenAI 官方 Python SDK，把 base_url 指向平台地址即可，业务代码几乎不用改：

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["XALLINONE_API_KEY"],
    base_url=os.environ["XALLINONE_BASE_URL"] + "/v1",
)

resp = client.chat.completions.create(
    model="你在控制台选定的模型名",
    messages=[
        {"role": "system", "content": "你是一名简洁的技术助理。"},
        {"role": "user", "content": "用三句话说明什么是向量检索。"},
    ],
    temperature=0.3,
    max_tokens=512,
)

print(resp.choices[0].message.content)
print(resp.usage)

把 resp.usage 打出来很重要：它给出本次请求的输入与输出 token 数，是后面核算成本、设置预警阈值的依据。建议在开发阶段就把 usage 写进日志，而不是等账单出来再回头查。

第四步：在 Node.js 中调用

Node.js 侧同理，使用 OpenAI 的 JavaScript SDK，只替换 base URL 与密钥来源：

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.XALLINONE_API_KEY,
  baseURL: process.env.XALLINONE_BASE_URL + "/v1",
});

const resp = await client.chat.completions.create({
  model: "你在控制台选定的模型名",
  messages: [
    { role: "system", content: "你是一名简洁的技术助理。" },
    { role: "user", content: "用三句话说明什么是向量检索。" },
  ],
  temperature: 0.3,
  max_tokens: 512,
});

console.log(resp.choices[0].message.content);
console.log(resp.usage);

Java 侧同样按 SDK 文档配置基地址与密钥，请求参数与上面保持一致。三种语言共用同一套请求结构，这也是选择兼容 OpenAI 协议的平台最实际的好处：换语言、换模型都不需要重写调用层。

第五步：配置用量预警

接口跑通之后，紧接着要做的是防止费用失控。控制台提供「用量预警」功能，可以设置阈值告警。建议至少设两档：一档在预算的 50% 左右，用来提前发现异常调用；一档在 80% 左右，用来触发人工介入。阈值具体怎么填取决于你的预算规模，平台本身不限制档数。

配合预警，还要在代码侧做两件事：一是给每次请求设 max_tokens 上限；二是对循环调用、Agent 多跳推理这类容易放大的场景加次数上限，避免一次逻辑错误把额度跑光。

第六步：用模型效能报告做模型选型

控制台提供模型性能对比看板与「模型效能报告」，可以按项目、环境、版本查看 Token 消耗分布。实际用法是：同一批测试用例分别打到两三个候选模型上，对比输出质量与 token 消耗，再决定生产环境用哪个。素材提到平台支持在同一 API 请求中编排不同基座模型，这意味着你可以在不改业务逻辑的前提下做 A/B 切换，把「换模型」当成一次配置变更而不是一次重构。

一个完整示例

下面把前面的步骤串成一个能跑通的最小脚本：读取环境变量、发起一次对话、打印回复与 token 用量、并在用量超过自设阈值时给出提示。适合作为项目里的第一个联调脚本。

import os
import sys
from openai import OpenAI

API_KEY = os.environ.get("XALLINONE_API_KEY")
BASE_URL = os.environ.get("XALLINONE_BASE_URL")
MODEL = os.environ.get("XALLINONE_MODEL", "你在控制台选定的模型名")
TOKEN_ALERT = int(os.environ.get("TOKEN_ALERT", "2000"))

if not API_KEY or not BASE_URL:
    sys.exit("请先设置 XALLINONE_API_KEY 与 XALLINONE_BASE_URL")

client = OpenAI(api_key=API_KEY, base_url=BASE_URL + "/v1")

messages = [
    {"role": "system", "content": "你是一名技术文档编辑，回答保持简洁。"},
    {"role": "user", "content": "把下面这句话改写成一句更清楚的说明：接口返回慢的时候要看看是不是网络问题。"},
]

resp = client.chat.completions.create(
    model=MODEL,
    messages=messages,
    temperature=0.2,
    max_tokens=256,
)

print("回复：", resp.choices[0].message.content)
print("用量：", resp.usage)

total = resp.usage.total_tokens
if total > TOKEN_ALERT:
    print(f"注意：本次消耗 {total} tokens，已超过自设阈值 {TOKEN_ALERT}")

运行前先导出三个环境变量：

export XALLINONE_API_KEY="你的 API Key"
export XALLINONE_BASE_URL="控制台给出的接口基地址"
export XALLINONE_MODEL="你在控制台选定的模型名"
python first_call.py

脚本跑通后，把 messages 换成你真实业务里的提示词，把 MODEL 换成候选模型，重复跑几轮，就能拿到一组可对比的样本。这一步做完，接入工作基本就结束了，剩下的都是围绕成本和稳定性的持续调优。

把示例扩展成多轮对话

单轮请求验证通过后，多轮对话只需要维护好消息数组：每轮把模型的回复以 assistant 角色追加进 messages，再追加新的 user 消息。要注意历史消息会持续占用输入 token，长会话应当做截断或摘要，否则成本会随轮次线性上升。素材没有给出具体的上下文长度上限，实际可用长度以所选模型在控制台标注的规格为准。

把示例扩展成批量任务

批量场景（例如客服工单分类、研报摘要生成）的关键不是单次调用，而是并发与重试。建议：

• 为每个任务记录请求 ID 与 token 用量，便于事后按项目归因
• 对超时和限流错误做指数退避重试，不要立即重发
• 把 temperature 调低，保证同类输入得到稳定输出
• 先用小样本跑通，再放大并发，避免一上来就把额度打满

注意事项

易变信息以官网为准。 体验金金额、免费调用额度、价格折扣、延迟与 SLA 指标、支持的模型清单，都会随平台运营调整。本文不复制这些数字作为承诺，接入前请在控制台或官网核对当前值。

密钥管理。 按项目与环境拆分密钥，生产密钥只放在服务端。定期轮换，发现异常调用立即吊销。

成本控制。 素材提到平台采用毫秒级用量计量、无预留费用、无最低消费、无绑定条款。这类计费方式对用量波动大的团队友好，但也意味着每一次调用都会被如实计入，开发阶段的调试流量同样产生费用。务必在联调期就打开用量预警，并给测试脚本设调用次数上限。

模型切换的兼容性。 虽然请求格式统一，但不同基座模型对提示词的敏感度、对结构化输出的遵循程度并不一致。换模型后要重跑回归用例，不要假设输出格式完全不变。

合规与数据。 平台宣称满足等保三级与 GDPR 相关要求，并提供传输层与推理过程的加密机制。如果你的业务涉及个人数据或受监管行业，应以官方当前提供的合规材料与合同条款为准，必要时走内部法务与安全评审。

技术支持渠道。 素材提到可通过工单获得技术专家响应，并给出响应时限的说法。实际响应时效以官方当前的服务承诺为准，关键项目不要把上线时间完全押在支持响应上。

文档与 SDK。 平台提供多语言 SDK 文档与业务案例。接入时优先按控制台里的接入说明操作，因为基地址、模型名这类信息以控制台为准，第三方文章里的示例可能已经过期。