NVIDIA NIM

NVIDIA NIM 将模型封装为可在自有基础设施中运行的推理微服务。NVIDIA 也通过托管 API 端点提供部分 NIM。应用通过稳定的 AISIX 别名选择这些模型，同时由网关保存 NVIDIA API Key。

本指南配置 https://integrate.api.nvidia.com/v1 上共享的托管 LLM Chat API，以及发布兼容 /v1/embeddings 路由的 Embedding 模型。API Catalog 还包含使用模型特定路径、请求体或主机的检索、视觉生成、语音及其他 NIM。托管目录及可用模型会随时间变化，因此将此共享配置用于其他 NIM 系列前，请查看所选模型的 API 参考。

前提条件

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

• 一套 AISIX 环境：
  • 对于 AISIX Cloud，需要一个已关联网关的环境和具有写入作用域的 Admin Token。对于 On-Premises，请按照 AISIX Cloud 快速入门操作。如需申请 Hybrid Cloud 访问权限，请联系 API7。
  • 对于开源 AISIX 网关，请准备本地 AISIX 安装，或采用开源 AISIX 网关快速入门中的 Docker 部署方式。配置网关以加载声明式资源文件。
• 一个用于托管 NIM API 的 NVIDIA API Key，可从 build.nvidia.com 上的模型页面生成。
• 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"

为 NVIDIA 支持的 Chat Completions 路由创建服务提供方密钥、模型别名和调用方 API Key。

NVIDIA 是社区目录服务提供方，其共享托管 LLM 端点接受 OpenAI Chat Completions 请求。AISIX 通过 openai 适配器连接，使用 Bearer Token 对上游请求进行身份认证，并将 NVIDIA API Root 用作 api_base。AISIX 不会注册 NVIDIA 特定的请求或响应重写。有关与标准 OpenAI 格式不同的字段，请参阅配置 NVIDIA 特定行为。

Dashboard 将 NVIDIA 归入 All providers (community)，并将其传输协议兼容性标记为推定兼容，而非已验证。

创建服务提供方密钥

创建用于保存 NVIDIA 凭证和 API Root 的服务提供方密钥：

# 请替换为实际值
export NVIDIA_API_KEY="YOUR_PROVIDER_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": "nvidia-prod",
    "provider": "nvidia",
    "api_key": "'"${NVIDIA_API_KEY}"'",
    "api_base": "https://integrate.api.nvidia.com/v1",
    "allowed_environments": ["'"${ENV_ID}"'"]
  }' | jq -r '.provider_key.id')

echo "$PROVIDER_KEY_ID"

❶ provider 为 nvidia。AISIX Cloud Admin API 接受该值，因为 nvidia 是其缓存的 models.dev 目录 ID 之一；它会根据目录的社区默认规则分配 openai 适配器和 Bearer 身份认证。adapter 字段仅适用于 BYO 服务提供方密钥，因此不要在此设置。

❷ api_key 保存 NVIDIA API Key。NVIDIA 使用 HTTP Bearer 身份认证来认证托管 NIM API，这正是 openai 适配器已发送的认证方式。该值遵循服务提供方密钥中的凭证处理行为。

❸ api_base 为 https://integrate.api.nvidia.com/v1，这是 NVIDIA 为共享托管 LLM API 记录的 Root。Chat 路由以 POST https://integrate.api.nvidia.com/v1/chat/completions 的形式挂载在该 Root 下，而 AISIX 会向 api_base 追加 /chat/completions，因此该值必须止于 /v1。AISIX 会移除粘贴进来的 /chat/completions 等端点后缀以及尾部斜杠，但应将 Root 本身视为约定，不要依赖这种修正行为。

不要把这个 Root 复用于所有 API Catalog 条目。例如，托管重排序使用 https://ai.api.nvidia.com 下的检索专用端点，视觉生成 NIM 也会发布其他路径。若所选模型不使用共享 LLM 或 Embeddings 路由，请按照该模型 API 参考中的准确 API Root 创建独立的服务提供方密钥。

对于 nvidia，该字段可选：models.dev 在其 api 字段中发布了相同 URL；省略该字段时，AISIX Cloud Admin API 会自动填充。示例中显式设置该字段，以便每个密钥所指向的 Root 在配置中清晰可见。

警告

切勿让 nvidia 服务提供方密钥缺少已解析的 api_base。对于任何非 OpenAI 厂商，OpenAI 系列桥接不会回退到默认 OpenAI 主机，因此空的 Base URL 会在请求时产生上游配置错误，而不会将携带 NVIDIA 凭证的请求错误发送到其他厂商主机。

该命令将返回的服务提供方密钥 ID 保存到 PROVIDER_KEY_ID。

创建模型

在共享托管 LLM 和 Embeddings 路由上，NVIDIA 通常按发布方组织为模型 ID 设置命名空间，格式为 <publisher>/<model>。发布方片段是这些 ID 的组成部分，不能省略。目前的示例如下：

模型 ID	发布方
nvidia/nvidia-nemotron-nano-9b-v2	NVIDIA
meta/llama-3.3-70b-instruct	Meta
openai/gpt-oss-120b	OpenAI

大多数别名错误都源于以下两个命名细节：

• 部分 NVIDIA 发布的模型名称已经以 nvidia- 开头，因此完整 ID 会重复该片段，例如 nvidia/nvidia-nemotron-nano-9b-v2。这是正确格式，并非拼写错误。
• build.nvidia.com 上的模型页面 URL 使用页面 Slug，而不是模型 ID。Llama 3.3 70B Instruct 页面路径中使用 llama-3_3-70b-instruct，而 API 模型 ID 是 meta/llama-3.3-70b-instruct。请从模型页面的代码示例中复制 ID，而不要从地址栏复制。

创建别名前，请在 NVIDIA NIM API 参考中查看相应模型页面，同时确认当前端点与请求正文中的模型 ID。部分特定领域 API 使用的模型值与带发布方命名空间的目录卡片名称不同。

创建调用方将在请求中发送的模型别名：

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": "nvidia-llama-prod",
    "model_name": "meta/llama-3.3-70b-instruct",
    "provider_key_id": "'"${PROVIDER_KEY_ID}"'"
  }' | jq -r '.model.id')

echo "$MODEL_ID"

❶ display_name 是调用方通过 model 发送的别名。

❷ model_name 是包含发布方片段的 NVIDIA 模型 ID。不要从提供相同权重但不使用发布方前缀的服务提供方沿用 llama-3.3-70b-instruct 等裸标识符。

❸ provider_key_id 将该别名关联到 NVIDIA 服务提供方密钥。

创建调用方 API Key

创建可访问该模型别名的调用方 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": "nvidia-caller",
    "allowed_models": ["'"${MODEL_ID}"'"]
  }' | jq -r '.plaintext')

echo "$AISIX_API_KEY"

allowed_models 值必须引用上一步保存的模型 ID。写入后，配置会自动投射到关联的网关。

使用开源 AISIX 网关配置

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

export NVIDIA_API_KEY="YOUR_PROVIDER_API_KEY"
export CALLER_API_KEY="YOUR_CALLER_API_KEY"

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

resources.yaml

_format_version: "1"

provider_keys:
  - display_name: "nvidia-prod"
    provider: "nvidia"
    adapter: "openai"
    api_key: ${NVIDIA_API_KEY}
    api_base: "https://integrate.api.nvidia.com/v1"

models:
  - display_name: "nvidia-llama-prod"
    provider: "nvidia"
    model_name: "meta/llama-3.3-70b-instruct"
    provider_key: "nvidia-prod"

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

如果 AISIX 安装在本地，请先验证文件再加载：

aisix validate --resources resources.yaml

验证后，在网关进程环境中提供文件所引用的环境变量，然后启动网关。仅当现有网关进程已经能够访问这些变量时才重新加载；否则，请使用更新后的环境重启网关。

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

export AISIX_API_KEY="$CALLER_API_KEY"

验证服务提供方连接

导出 AISIX 网关源站地址：

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

通过 AISIX 代理发送聊天补全请求：

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

网关返回 OpenAI 兼容响应，其中会回显调用方面向的别名 nvidia-llama-prod。如果请求失败，请检查服务提供方密钥的 api_key、api_base Root，以及 model_name 中带发布方命名空间的模型 ID。上游 404 通常表示模型 ID 不正确、模型已不可用，或有效的目录模型被发送到了错误的共享路由。

在托管 API 与自行托管 NIM 之间选择

NIM 微服务既可作为容器运行在自有基础设施中，也可通过 NVIDIA 托管 API 端点访问；只有托管 API 属于 nvidia 目录服务提供方。在自有集群中运行的 LLM NIM 会在自身地址（例如 http://10.0.0.5:8000/v1）上提供 OpenAI 兼容 API，并改为通过私有端点路径接入 AISIX。请使用自带端点进行配置。

对比项	托管 NIM API	自行托管的 NIM 微服务
服务提供方值	nvidia	AISIX Cloud Admin API 中使用 byo，或在声明式 resources.yaml 中使用自定义标签
adapter 字段	不接受。适配器从目录中派生。	接受，并设置为 openai。
api_base	https://integrate.api.nvidia.com/v1；省略时使用目录中的默认值	必填。填写容器 Root，例如 http://10.0.0.5:8000/v1。
模型 ID	带发布方命名空间，例如 meta/llama-3.3-70b-instruct	容器提供服务的模型名称
定价元数据	可用时从 models.dev 获取；请核验计费信息，或在模型别名上覆盖 cost	由你在模型别名上自行提供 cost

同时运行两者是一种常见配置：一个服务提供方密钥用于托管 API 的突发容量，另一个 BYO 密钥用于自行托管的 NIM，并由路由模型在两个别名之间执行故障转移。请参阅路由与故障转移。

当前自行托管 LLM NIM除 Chat Completions 外，还可公开原生 /v1/completions、/v1/responses、/v1/messages 和 /v1/messages/count_tokens 端点。把端点配置为 openai 适配器不会让 AISIX 原生转发每条路由：规范化 /v1/responses 和 /v1/messages 会通过 Chat 适配器转换，而规范化 /v1/messages/count_tokens 要求 Anthropic 协议的服务提供方密钥。

应用需要 NIM 容器的原生请求和响应契约时，请使用透传路由，把 NIM 根地址设为路由的 target_url。

若要原生使用 Messages 和 Token 计数，还可为同一个 NIM Root 创建独立的 BYO 服务提供方密钥和模型别名，并设置 adapter: anthropic。AISIX 随后会把规范化 /v1/messages 和 /v1/messages/count_tokens 请求发送到兼容 Anthropic 的 NIM 端点。该密钥应与用于 Chat、Responses 桥接和 Embeddings 的 openai 适配器密钥分开。

配置 NVIDIA 特定行为

由于 nvidia 没有 AISIX 精选的适配器映射，AISIX 不会为其注册请求或响应重写。网关会原样发送 OpenAI 请求格式，这适用于 NVIDIA 的 Chat 路由；所有 NVIDIA 特定差异都需由你处理。请使用服务提供方密钥覆盖配置这些差异，覆盖配置会应用于引用该密钥的每个模型。

能力支持取决于具体模型和端点。某个目录条目支持工具、结构化输出、推理或多模态输入，不代表其他 NVIDIA 模型也接受相同字段或内容块格式。AISIX 会转发 OpenAI 形态的 Chat 字段和未知顶层参数；部分多模态 NIM 则需要模型专用路由、HTML 媒体标签或 NVCF 资产引用。请检查模型自身的推理参考，不要根据 NIM 系列名称推断支持范围。AISIX 还只返回兼容 OpenAI Chat 响应中的第一个 Choice；调用方需要全部生成结果时，请勿请求大于 1 的 n。

推理控制因模型而异

NVIDIA 未定义适用于整个服务提供方的统一推理字段。发布的每个模型都有自己的请求 Schema，因此启用或限制推理的控制方式因模型而异。例如，nvidia/nvidia-nemotron-nano-9b-v2 通过提示词中的 /think 和 /no_think 控制 Token 切换推理，而其他模型则接受 reasoning_effort 等顶层参数。在依赖某项控制前，请在 NVIDIA NIM API 参考中的对应模型页面确认；一个 NIM 接受的控制可能会被另一个 NIM 忽略或拒绝。

传递这些控制无需额外网关配置。提示词级控制 Token 位于消息内容中，而 AISIX 会将无法识别的顶层 Chat 参数原样转发到上游，因此模型特定参数会不加修改地发送到 NVIDIA：

{
  "model": "nvidia-nemotron-prod",
  "messages": [
    {
      "role": "user",
      "content": "Plan a three-step migration."
    }
  ],
  "reasoning_effort": "low"
}

在响应侧，无论流式还是非流式响应，只要上游已在规范的 reasoning_content 字段中返回推理内容，AISIX 都会予以保留。如果某个 NIM 在不同的 delta 路径上流式返回推理内容，请在服务提供方密钥上设置 response.reasoning_field。

Token 限制参数名称

社区默认规则未为 nvidia 注册 param_renames，因此 AISIX 会沿用调用方发送的参数名称传递 max_tokens 和 max_completion_tokens。NVIDIA LLM API 文档使用 max_tokens。因此，客户端发送较新的 max_completion_tokens 时，该限制会以一个上游可能不处理的名称转发。如遇此情况，请在服务提供方密钥上添加重命名配置：

{
  "request": {
    "param_renames": {
      "max_completion_tokens": "max_tokens"
    }
  }
}

如果请求同时携带这两个名称，AISIX 会使用原始面向调用方名称所对应的值。

将 Embeddings 路由到 NeMo Retriever 模型

NVIDIA 在同一目录中发布 NeMo Retriever Embedding 模型，而 AISIX 通过同一 openai 适配器分发 /v1/embeddings，因此指向 Embedding 模型的别名可用于该路由。

多个 NVIDIA Embedding 字段需要特殊处理。NVIDIA 的非对称检索模型系列（例如 NV-EmbedQA 和 E5）要求将 input_type 设置为 query 或 passage，使用错误值会降低检索准确率。当前 Retriever NIM Schema 还可定义 modality、embedding_type 和 truncate 等字段。AISIX Embeddings 路由只会使用一组封闭字段构建上游请求正文，即 model、input、encoding_format 和 dimensions，因此调用方请求正文中的 NVIDIA 专用字段不会到达上游。

请改为通过 request.default_body_fields 在服务提供方密钥上设置该字段：

{
  "request": {
    "default_body_fields": {
      "input_type": "passage"
    }
  }
}

AISIX 会在 Embeddings 路径（而不仅是 Chat 路径）上将这些字段合并到出站请求体中。由于服务提供方密钥覆盖会应用于引用该密钥的每个模型，因此请为每种检索模式分别创建一个服务提供方密钥：一个携带用于索引的 input_type: passage，另一个携带用于搜索的 input_type: query，再让相应模型别名指向各自密钥。

其他固定 NVIDIA 字段（例如 truncate）也可使用 request.default_body_fields。必须随请求或每项输入变化的值（例如混合 modality 数组）不能通过静态服务提供方密钥配置表达，需要使用透传路由。

不接受 input_type 的对称 Embedding 模型无需配置服务提供方密钥覆盖。字段定义请参阅 request.default_body_fields，并在 NVIDIA Embedding API 参考中确认你的模型是否要求 input_type。

端点覆盖范围

由适配器分发的路由接受 nvidia 服务提供方值，而使用自身服务提供方允许列表的路由会拒绝该值。

路由	使用 NVIDIA 别名时的行为
/v1/chat/completions	在共享托管 LLM 路由上支持，包括 stream: true。模型能力仍取决于具体模型。
/v1/completions	AISIX 会通过 OpenAI 适配器转发此路由。当前自托管 LLM NIM 提供该路由，但 NVIDIA 未将其记录为共享托管 LLM API 的通用路由；仅当所选上游明确支持时使用。
/v1/responses	通过 Chat 上的 Responses 桥接支持，即使自托管 NIM 提供原生 Responses 端点也不例外。桥接会保留文本和函数调用轮次，但会合成新响应；状态、托管工具、推理控制和其他没有 Chat 等价项的字段会被丢弃。合成的 Responses 输出不表示上游推理文本。
/v1/messages	通过 Chat 转换支持 Anthropic 格式调用方，而非原生 NIM Messages 透传。NIM 推理不会作为 Anthropic thinking 块返回。/v1/messages/count_tokens 要求采用 Anthropic 协议的服务提供方密钥。
/v1/embeddings	当别名指向 NVIDIA Embedding 模型时支持。请参阅将 Embeddings 路由到 NeMo Retriever 模型。
/v1/images/generations	对 NVIDIA 别名返回 400 并拒绝。NVIDIA Visual GenAI NIM 可提供原生兼容 OpenAI 的图片路由，但规范化 AISIX 路由只接受服务提供方为 openai 的模型。
/v1/rerank	返回 400 并拒绝。该路由仅接受 openai、cohere 和 jina 服务提供方值。请参阅下方说明。
/v1/videos	返回 501 not_implemented 并拒绝。Visual GenAI NIM 可在 /v1/videos/generations 提供原生视频生成，但规范化 AISIX 视频路由的服务提供方允许列表中不包含 nvidia。
/v1/audio/*	会转发到兼容 OpenAI 的音频路径，但共享托管 LLM API 和自托管 LLM NIM 不提供这些路由。Speech NIM 使用独立 API；请通过以文档根地址为目标的透传路由访问。
/v1/files、/v1/batches、/v1/fine_tuning/jobs	AISIX 可通过 OpenAI 适配器分派这些路由，但共享托管 API 和当前自托管 LLM NIM 都不提供对应的 OpenAI Jobs API，因此上游会拒绝请求。NIM 模型定制或 LoRA 管理使用不同协议。
/passthrough/nvidia/*	通过已配置的透传路由可用于服务提供方原生路由，网关标准化能力有限。

NVIDIA 确实发布了重排序模型，但即使不考虑服务提供方允许列表，也无法通过 /v1/rerank 访问。当前自托管 Retriever NIM 将其记录为 POST /v1/ranking，请求体包含 query 对象和 passages 数组；路径和请求体均不匹配规范化路由，托管目录重排还可能使用不同主机和路径。请使用所选模型的 NVIDIA 重排序 API 参考中的端点和请求体，通过透传路由访问。

本页的 /passthrough/nvidia 路径假定一条透传路由认领该前缀，target_url 设为 https://integrate.api.nvidia.com/v1 并用 NVIDIA 服务提供方密钥做凭证注入；在调用方 Key 的 allowed_routes 上授予路由名称。路由绑定一个固定目标和凭证——请求体中的模型不会选择凭证，AISIX 别名也不会重写为上游模型 ID——因此其他根地址（例如 https://ai.api.nvidia.com 下的检索端点）上的 NIM 请另建路由。路由会增量中继包括 SSE 在内的上游响应。AISIX 会检测 Chat、Completions 和 Responses 信封，并记录受支持的用量字段。没有可识别载体字段的请求保持不透明：缓冲响应记录零 Token，而不透明 SSE 仍可记录顶层受支持的 usage 字段。需要别名重写、Token 核算或 AISIX 成本估算时，请优先使用规范化推理路由。目录定价只是 AISIX 估算所用的元数据，并不代表 NVIDIA 的实际账单；目前许多 NVIDIA 目录模型的已发布成本为零或缺失。

后续步骤

你已将 AISIX 连接到 NVIDIA NIM 托管 API，并验证了模型别名。接下来可阅读以下指南：

• 模型别名：为该别名配置路由、重试行为或成本元数据。
• 路由与故障转移：在托管 NIM API 和自行托管的 NIM 之间执行故障转移。
• 自带端点：连接自行运行的 NIM 微服务。
• 服务提供方兼容性：查看支持的代理端点及服务提供方特定的限制。