NVIDIA NIM

NVIDIA NIM 为 NVIDIA 和第三方模型提供托管推理接口。应用通过稳定的 AISIX 别名选择这些模型，同时由网关保存 NVIDIA API Key。

NVIDIA 在同一个托管端点上提供来自多个发布方的模型，包括 NVIDIA Nemotron、Meta Llama、OpenAI gpt-oss、DeepSeek、Qwen、Google Gemma、Mistral AI 和 Microsoft 模型。

前提条件

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

一套 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 是社区目录服务提供方，其托管端点接受 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 文档中 OpenAI 客户端库访问托管 NIM API 时使用的 base_url Root。Chat 路由以 POST https://integrate.api.nvidia.com/v1/chat/completions 的形式挂载在该 Root 下，而 AISIX 会向 api_base 追加 /chat/completions，因此该值必须以 /v1 结尾。AISIX 会移除粘贴进来的 /chat/completions 等端点后缀以及尾部斜杠，但应将 Root 本身视为约定，不要依赖这种修正行为。

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

警告

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

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

创建模型

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。

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

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，通常是发布方片段缺失或拼写错误。

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

NIM 既是托管 API，也是可自行运行的容器；只有托管 API 属于此目录服务提供方。在自有集群中运行的 NIM 微服务会在自身地址（例如 http://10.0.0.5:8000/v1）上提供 OpenAI 兼容路由，并改为通过私有端点路径接入 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`

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

配置 NVIDIA 特定行为

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

推理控制因模型而异

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 细节需要配置。NVIDIA 的非对称检索模型系列（例如 NV-EmbedQA 和 E5）要求将 input_type 设置为 query 或 passage，使用错误值会降低检索准确率。input_type 不是 OpenAI Embeddings 参数，而 AISIX Embeddings 路由仅使用一组固定字段构建上游请求体，即 model、input、encoding_format 和 dimensions，因此调用方请求体中的 input_type 不会到达 NVIDIA。

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

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

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

NVIDIA 还提供了另一种表达同一含义的方式，专门面向无法发送 input_type 的 OpenAI 客户端：在模型名称后追加 -query 或 -passage 后缀，例如 nvidia/nv-embedqa-e5-v5-passage。这种形式完全不需要服务提供方密钥覆盖，因此两种检索模式可以共享同一个服务提供方密钥，仅通过各别名上的 model_name 区分。如果 NVIDIA 文档为你的模型列出了该后缀，请优先使用这种方式；否则再回退到 default_body_fields。不接受 input_type 的对称 Embedding 模型两者都不需要。有关字段定义，请参阅 request.default_body_fields；并在 NVIDIA Embedding API 参考中确认模型接受哪种形式。

端点覆盖范围

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

路由	使用 NVIDIA 别名时的行为
`/v1/chat/completions`	支持，包括 `stream: true`。
`/v1/responses`	通过聊天适配器路径上的 Responses 桥接支持。
`/v1/messages`	通过转换支持 Anthropic 结构的调用方。`/v1/messages/count_tokens` 的 Token 计数需要使用 Anthropic 后端模型。
`/v1/embeddings`	当别名指向 NVIDIA Embedding 模型时支持。请参阅将 Embeddings 路由到 NeMo Retriever 模型。
`/v1/images/generations`	返回 `400` 并拒绝。该路由仅接受服务提供方为 `openai` 的模型。
`/v1/rerank`	返回 `400` 并拒绝。该路由仅接受 `openai`、`cohere` 和 `jina` 服务提供方值。请参阅下方说明。
`/v1/videos`	返回 `501 not_implemented` 并拒绝。视频路由的服务提供方允许列表中不包含 `nvidia`。
`/passthrough/nvidia/*`	支持服务提供方原生路由，但网关标准化能力有限。请参阅服务提供方透传。

NVIDIA 确实发布了重排序模型，但即使不考虑服务提供方允许列表，也无法通过 /v1/rerank 访问：NVIDIA 文档将重排序定义为 POST /v1/ranking，请求体包含 query 对象和 passages 数组，这与该路由标准化的路径和请求体均不相同。请使用 NVIDIA 重排序 API 参考中的路径和请求体，通过服务提供方透传访问重排序模型。透传会转发到所选模型的服务提供方密钥 Base URL；因此，如果所需检索路由由不同于 Chat Base 的主机提供，请为该主机创建第二个服务提供方密钥，并阅读服务提供方透传，了解 AISIX 如何在同一服务提供方的多个密钥之间进行选择。

后续步骤

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

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

前提条件​

使用 AISIX Cloud 配置​

创建服务提供方密钥​

创建模型​

创建调用方 API Key​

使用开源 AISIX 网关配置​

验证服务提供方连接​

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

配置 NVIDIA 特定行为​

推理控制因模型而异​

Token 限制参数名称​

将 Embeddings 路由到 NeMo Retriever 模型​

端点覆盖范围​

后续步骤​