Nebius Token Factory

Nebius Token Factory 为模型目录提供托管推理服务。AISIX 为应用提供稳定别名，同时由网关保存 Token Factory API Key。

准备工作

开始前，请准备以下内容：

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具备写入权限的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或使用开源 AISIX 网关快速入门中的 Docker 环境。配置网关以加载声明式资源文件。
• 一个 Nebius Token Factory API Key。
• curl 和 jq。

使用 AISIX Cloud 配置

导出 AISIX Cloud 连接信息：

# AISIX_CP 是 Admin API 基础 URL；需要包含 /api，且末尾不包含斜杠
# 本地 On-Premises 快速入门使用 http://localhost:8080/api
export AISIX_CP="YOUR_AISIX_CLOUD_ADMIN_API_URL"
export AISIX_TOKEN="YOUR_ADMIN_TOKEN"
export ENV_ID="YOUR_ENVIRONMENT_ID"

Nebius 是提供 OpenAI 兼容 API 的社区目录服务提供方。AISIX 通过 openai 适配器连接，并使用 Bearer Token 对上游请求进行身份认证。

创建服务提供方密钥

export NEBIUS_API_KEY="YOUR_NEBIUS_API_KEY"

PROVIDER_KEY_ID=$(
  curl -sS -X POST "$AISIX_CP/provider_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "nebius-prod",
      "provider": "nebius",
      "api_key": "'"${NEBIUS_API_KEY}"'",
      "api_base": "https://api.tokenfactory.nebius.com/v1",
      "allowed_environments": ["'"${ENV_ID}"'"]
    }' | jq -er '.provider_key.id'
)

echo "$PROVIDER_KEY_ID"

不要在目录服务提供方密钥中添加 adapter。AISIX 会从目录中派生 openai 适配器和 Bearer 身份认证方案。即使同步目录中已有相同值，显式设置 API Base 仍可在配置中清楚显示目标地址。

创建模型

Nebius 模型 ID 包含发布方命名空间。请使用完整 ID 创建别名：

MODEL_ID=$(
  curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/models" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "nebius-llama-prod",
      "model_name": "meta-llama/Llama-3.3-70B-Instruct",
      "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
    }' | jq -er '.model.id'
)

echo "$MODEL_ID"

如需使用其他模型，请从当前 Nebius 模型目录中复制相应 ID，不要删除或更改发布方前缀。

创建调用方 API Key

AISIX_API_KEY=$(
  curl -sS -X POST "$AISIX_CP/environments/$ENV_ID/api_keys" \
    -H "Authorization: Bearer $AISIX_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "display_name": "nebius-caller",
      "allowed_models": ["'"${MODEL_ID}"'"]
    }' | jq -er '.plaintext'
)

echo "$AISIX_API_KEY"

使用开源 AISIX 网关配置

导出上游凭证，并选择应用将发送给网关的调用方 API Key：

export NEBIUS_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

为此服务提供方创建完整的声明式资源文件：

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "nebius-prod"
    provider: "nebius"
    adapter: "openai"
    api_key: ${NEBIUS_API_KEY}
    api_base: "https://api.tokenfactory.nebius.com/v1"

models:
  - display_name: "nebius-llama-prod"
    provider: "nebius"
    model_name: "meta-llama/Llama-3.3-70B-Instruct"
    provider_key: "nebius-prod"

api_keys:
  - display_name: "nebius-caller"
    key_env: CALLER_API_KEY
    allowed_models:
      - "nebius-llama-prod"

如果 AISIX 安装在本地，请在加载前校验文件：

aisix validate --resources resources.yaml

校验后，请在网关进程环境中提供所引用的环境变量并启动网关。仅当这些变量已可用于现有网关进程时才重新加载；否则，请使用更新后的环境重启网关。

如果使用 Docker，请调整开源 AISIX 网关快速入门中的校验和启动命令。挂载此 resources.yaml 文件，并在两个命令中使用 -e 传入该文件引用的每个环境变量。资源加载后，准备下文共用的验证请求：

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关 Origin：

# 本地快速入门使用 http://127.0.0.1:3000
export AISIX_PROXY="YOUR_AISIX_GATEWAY_ORIGIN"

通过 AISIX 代理发送 Chat Completions 请求：

curl -sS -X POST "$AISIX_PROXY/v1/chat/completions" \
  -H "Authorization: Bearer $AISIX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nebius-llama-prod",
    "messages": [
      {
        "role": "user",
        "content": "Say hello from Nebius Token Factory."
      }
    ]
  }'

上游请求使用 POST /v1/chat/completions、准确的 Nebius 模型 ID，以及 Authorization: Bearer <NEBIUS_API_KEY>。

查看模型能力

Nebius Token Factory 在同一 API 根地址上提供 Chat、推理、视觉、嵌入、重排和图片模型。能力仍取决于所选模型。本指南中的 meta-llama/Llama-3.3-70B-Instruct 是当前的纯文本 Chat 模型，支持函数工具和结构化输出，但不是推理或视觉模型。

在规范化 Chat Completions 请求上，AISIX 会转发 OpenAI 风格的工具、结构化输出控制、带类型的图片或视频内容块，以及 reasoning_effort 等顶层字段。对于支持推理的 Nebius 模型，AISIX 会将上游 reasoning_content 或 reasoning 规范化为返回的助手消息中的 reasoning_content。当 n 大于 1 时 Nebius 可返回多个选项，但 AISIX 在规范化 Chat 路由上只返回第一个选项。应用需要全部选项或其他服务提供方原生响应结构时，请使用透传路由。

端点覆盖范围

路由	使用 Nebius 别名时的行为
/v1/chat/completions	支持，包括流式传输、工具、结构化输出、推理，以及所选模型支持的多模态内容。
/v1/completions	对接受旧版 Completions 协议的 Nebius 模型，通过 openai 适配器支持。
/v1/responses	通过 Responses 桥接支持；该桥接会转换为 Chat Completions，而非调用 Nebius 原生 Responses API。没有 Chat 等价项的字段（包括状态和原生工具语义）会被忽略；Responses 推理控制和 Nebius 推理输出不会保留。需要原生 Responses 语义时请使用透传路由。
/v1/messages	通过 Anthropic 到 Chat 的转换支持，并非 Nebius 原生 Messages API。桥接不会将 Nebius 推理保留为 Anthropic 思考块。/v1/messages/count_tokens 要求 Anthropic 后端模型，因此会拒绝此配置。
/v1/embeddings	使用当前 Nebius 嵌入模型（例如 Qwen/Qwen3-Embedding-8B）的独立别名时支持。
/v1/files	支持上传、列出、检索、删除和内容下载。AISIX 会重写返回的文件 ID，使后续规范化调用路由到同一别名。
/v1/fine_tuning/jobs	支持创建、列出、检索和取消。在创建请求中，model 必须是上游 Nebius 基础模型 ID，而非 AISIX 别名。
/v1/batches 和 /v1/audio/*	不支持。Nebius 未在此 API 根地址上发布兼容的 OpenAI Batch 或音频路由。
/v1/images/generations	返回 400 而被拒绝，因为规范化路由要求 provider: openai。可通过透传路由使用 Nebius 原生图片生成路由。
/v1/rerank	返回 400 而被拒绝，因为规范化路由只接受 openai、cohere 和 jina。可通过透传路由使用 Nebius 原生重排路由。
/v1/videos	返回 501 not_implemented 而被拒绝。Nebius 不提供视频生成路由；向兼容 Chat 模型输入视频是另一项能力。
/passthrough/nebius/*	通过已配置的透传路由可用于 /v1 目标下的 Nebius 原生路由，包括 /responses、/images/generations、/rerank 和 /models。

规范化文件和微调响应使用 AISIX 路由 ID。Nebius 独有的 /files/{id}/link 以及微调 /events 或 /checkpoints 等路由，需要通过透传路由使用原始 Nebius ID。路由不会解码 AISIX 路由 ID，因此工作流需要这些原生操作时，请从一开始就通过透传路由创建和管理资源。

本页的 /passthrough/nebius 路径假定一条透传路由认领该前缀，target_url 设为 https://api.tokenfactory.nebius.com/v1 并挂上 Nebius 服务提供方密钥；在调用方 Key 的 allowed_routes 上授予该路由。

透传路由不会重写 AISIX 模型别名或资源 ID，请在原生请求体中发送确切的 Nebius 模型 ID。由于路由的 target_url 以 /v1 结尾，/passthrough/nebius/responses 和 /passthrough/nebius/v1/responses 都会到达 https://api.tokenfactory.nebius.com/v1/responses；AISIX 会移除一个重复的版本路径段。

透传路由绑定固定的目标和凭证，而不是从调用方可访问的模型别名借用；模型允许列表也不管控它。不同的 Nebius 账号或 API 根地址请各配一条路由。AISIX 会检测 Chat、Completions 和 Responses 信封，并记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。除非挂载 hold-back 输出安全护栏，否则路由会增量中继服务提供方响应和 SSE。文件和微调管理调用属于零 Token 操作，AISIX 不会将 Nebius 训练费用计入推理成本核算。请参阅透传路由。

故障排查

现象	检查项
上游返回 401 或 403	确认 Nebius API Key 和项目访问权限。
上游返回 404	确认 api_base 中包含 /v1，并验证请求的路由与模型兼容。
找不到模型	保留发布方命名空间以及模型名称的大小写。
创建服务提供方密钥时返回 400	使用 provider: "nebius"，且不要设置 adapter。

后续步骤

你已将 AISIX 连接到 Nebius Token Factory，并验证了模型别名。接下来可阅读以下指南：

• 模型别名：为别名配置路由、重试行为或成本元数据。
• API Key 与模型限流：为别名配置请求数和 Token 限制。
• 路由与故障转移：在 Nebius 与提供同一模型的其他服务提供方之间执行故障转移。
• 服务提供方兼容性：查看支持的代理端点和服务提供方特有限制。