NVIDIA NIM API 接入手册

作者：Bob 最后更新：2026-04-23 定位：个人/团队免费调用 NVIDIA 托管的 100+ 开源顶级大模型（Llama、GLM、Qwen、DeepSeek、Kimi、GPT-OSS、Nemotron…）的完整接入指南，所有示例基于实测可复现。 底层逻辑：NVIDIA 用自家推理栈（TensorRT-LLM + Triton）把一批开源大模型包成 OpenAI 兼容的 REST 服务，免费给开发者试用，是"零门槛一站式调顶级开源模型"的最佳跳板之一。

---

0. TL;DR（三句话 + 一段 curl）

1. Base URL：https://integrate.api.nvidia.com/v1，完全 OpenAI 兼容
2. 鉴权：Authorization: Bearer nvapi-xxx（key 格式固定以 nvapi- 开头）
3. 首选模型：通用用 meta/llama-3.3-70b-instruct，中文用 z-ai/glm4.7，代码用 qwen/qwen3-coder-480b-a35b-instruct，思考用 deepseek-ai/deepseek-v3.2 或 moonshotai/kimi-k2-thinking

export NVAPI_KEY=nvapi-xxxxxxxx
curl -s https://integrate.api.nvidia.com/v1/chat/completions \
  -H "Authorization: Bearer $NVAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta/llama-3.3-70b-instruct",
    "messages": [{"role":"user","content":"Hello"}],
    "max_tokens": 128
  }'

---

1. 平台概览

1.1 术语对齐

名称	是什么
build.nvidia.com	NVIDIA 对外的模型市场 / 开发者门户，在这里注册账号、浏览模型、生成 API key
NVIDIA NIM（NVIDIA Inference Microservices）	底层推理微服务框架，每个模型打包成一个容器，既可自托管也可用 NVIDIA 云托管
integrate.api.nvidia.com	NVIDIA 云托管的统一 API 入口，OpenAI 协议兼容
NGC（NVIDIA GPU Cloud）	容器/模型仓库，自托管 NIM 时需要 NGC key

对应用开发者来说：注册 build.nvidia.com → 拿 nvapi key → 打 integrate.api.nvidia.com 就够了。

1.2 免费额度（2026-04 现状）

• 新账号默认 1,000 credits，可在论坛申请升到 5,000 credits
• 速率限制 40 RPM（requests/minute），可申请升到 200+
• 不需要绑定信用卡；credits 用完后可以通过 NVIDIA 开发者论坛重新申请或等待重置
• "免费用一年"是早期宣传的不精确说法，当前为固定 credit 额度制

参考：NVIDIA Developer Forums - NIM API Credits

---

2. 鉴权与 Base URL

2.1 获取 API Key

1. 访问 https://build.nvidia.com 用 Google / GitHub / 邮箱登录
2. 右上角头像 → API Keys → Generate API Key
3. 勾选 NGC Catalog + Public API Endpoints
4. 复制形如 nvapi-XXXXXXXXXXXXXXXX... 的长串（约 70 位），只显示一次，务必立刻保存

2.2 base URL 一览

场景	URL
Chat / Completions / Embeddings（主力）	https://integrate.api.nvidia.com/v1
Reranker 等领域特化	https://ai.api.nvidia.com/v1
自托管 NIM 容器	http://localhost:8000/v1（默认）

2.3 环境变量约定（推荐）

# ~/.bashrc 或 .env
export NVIDIA_API_KEY=nvapi-xxxxxxxx
export OPENAI_API_KEY=$NVIDIA_API_KEY      # 复用 OpenAI SDK 时
export OPENAI_BASE_URL=https://integrate.api.nvidia.com/v1

红线：绝不能把 key 写进 git 仓库。使用 .env + python-dotenv 或云平台 secrets 管理。

---

3. 端点清单

路径	方法	说明	OpenAI 协议
/v1/models	GET	列出当前账号可见的全部模型	✅ 兼容
/v1/chat/completions	POST	聊天补全（主力）	✅ 完全兼容
/v1/completions	POST	旧式文本补全	✅ 兼容
/v1/embeddings	POST	文本向量化	⚠️ 需额外 input_type
/v1/images/generations	POST	文本生图（部分模型）	⚠️ 字段有差异

结论：绝大多数情况，把你手头任何 OpenAI 兼容客户端的 base_url 换成 NVIDIA 的 URL + 换 api_key 即可工作。

---

4. 模型目录（实测 2026-04-20 快照，共 129 个 id）

目录会随时漂移（下架/重命名/上新），永远先用 /v1/models 取最新，再从下表挑选。本节只列出实战里值得关注的模型。

4.1 中文/通用对话首选

Model ID	厂商	规格	特性	实测（2026-04-22~23）
z-ai/glm-5.1	智谱	MoE 旗舰	代码/工具/长上下文；非 thinking，直接出 content	✅ HTTP 200，冷启动 91s，finish=stop
z-ai/glm4.7	智谱	44B	中文强，带 reasoning_content 思维链	✅ 4s，thinking 模型
qwen/qwen3.5-397b-a17b	阿里	397B MoE	最大 Qwen，性价比之王	✅ 11s，finish=stop
qwen/qwen3-next-80b-a3b-instruct	阿里	80B MoE	中英双优，非 thinking	✅ 秒级
qwen/qwen3-next-80b-a3b-thinking	阿里	80B MoE	thinking 版	✅ 目录存在
moonshotai/kimi-k2.5	Moonshot	通用	新版	✅ 42s，必须 max_tokens≥1024 否则 content 空
moonshotai/kimi-k2-thinking	Moonshot	思考模型	长链推理	✅ 目录存在

4.2 英文/通用对话首选

Model ID	厂商	规格	特性	实测（2026-04-22~23）
meta/llama-3.3-70b-instruct	Meta	70B	综合首选，稳定快速，工具调用好	✅ 秒级，finish=stop
openai/gpt-oss-120b	OpenAI	120B	thinking 模型，自报 ChatGPT	✅ 秒级
openai/gpt-oss-20b	OpenAI	20B	轻量 thinking 版	✅ 目录存在
mistralai/mistral-large-3-675b-instruct-2512	Mistral	675B	欧洲旗舰	✅ 65s，finish=stop
meta/llama-4-maverick-17b-128e-instruct	Meta	17B MoE	Llama 4 新架构	✅ 目录存在
meta/llama-3.1-405b-instruct	Meta	405B	最大 Llama，适合复杂任务	⚠️ 2026-04-22 实测 >180s 超时，近期上游不稳，非首选

4.3 代码专用

Model ID	特色
qwen/qwen3-coder-480b-a35b-instruct	480B 编码 MoE，顶级代码模型
qwen/qwen2.5-coder-32b-instruct	轻量代码，响应快
mistralai/codestral-22b-instruct-v0.1	Mistral 家代码
mistralai/devstral-2-123b-instruct-2512	软件工程 Agent 专用
bigcode/starcoder2-15b	老牌开源代码
nvidia/mistral-nemo-minitron-8b-8k-instruct	轻量代码推理

4.4 推理 / 思考模型（带 reasoning_content 字段）

Model ID	说明
deepseek-ai/deepseek-v3.2	DeepSeek 最新（注意：deepseek-r1 已不在目录）
deepseek-ai/deepseek-v3.1-terminus	前一代，改进推理与代理能力
qwen/qwen3-next-80b-a3b-thinking	Qwen 思考版
moonshotai/kimi-k2-thinking	Moonshot 思考版
z-ai/glm4.7	GLM 默认带思维链
openai/gpt-oss-120b	GPT-OSS 默认 thinking
nvidia/llama-3.3-nemotron-super-49b-v1.5	NV 强推理 Nemotron
nvidia/llama-3.1-nemotron-ultra-253b-v1	NV 顶级 Nemotron

⚠️ 坑：DeepSeek V3 家族 2026-04-20 实测存在上游 prefill 超时（HTTP 504 / >120s 无响应），生产环境需加重试 + 备选模型。

4.5 NVIDIA 自研 Nemotron 系列

Model ID	规格	特色	实测
nvidia/llama-3.3-nemotron-super-49b-v1.5	49B	平衡首选，thinking 模型	✅ 秒级
nvidia/llama-3.1-nemotron-ultra-253b-v1	253B	NV 改造 Llama	✅ 目录存在
nvidia/nemotron-3-super-120b-a12b	120B MoE	Mamba-Transformer 混合，长上下文	✅ 目录存在
nvidia/nvidia-nemotron-nano-9b-v2	9B	边缘轻量	✅ 目录存在
nvidia/llama-3.1-nemoguard-8b-content-safety	8B	内容安全检测	✅ 目录存在
nvidia/llama-3.1-nemoguard-8b-topic-control	8B	话题控制	✅ 目录存在
nvidia/nemotron-4-340b-instruct	340B	NV 旗舰	❌ 2026-04-22 实测 HTTP 404（目录列出但不可调）

4.6 多模态（VLM）

Model ID	输入
meta/llama-3.2-90b-vision-instruct	图 + 文
meta/llama-3.2-11b-vision-instruct	图 + 文（轻量）
microsoft/phi-4-multimodal-instruct	图/音/文
google/gemma-3-27b-it / -12b-it / -4b-it	图 + 文
nvidia/llama-3.1-nemotron-nano-vl-8b-v1	图 + 文（NV 轻量）
nvidia/nemotron-nano-12b-v2-vl	图 + 文
nvidia/neva-22b	图 + 文

4.7 Embedding / Rerank

Model ID	维度	备注
nvidia/nv-embedqa-e5-v5	1024	✅ 实测 OK；必须带 input_type:"query"\|"passage"
nvidia/nv-embed-v1	4096	通用高质量
nvidia/nv-embedcode-7b-v1	-	代码向量
nvidia/nv-embedqa-mistral-7b-v2	-	QA 优化
baai/bge-m3	1024	多语种
snowflake/arctic-embed-l	-	轻量

4.8 你可能会踩的下架/改名坑（2026-04-22~23 实测）

❌ 已下架 / 不能调 / 不稳	✅ 替代
deepseek-ai/deepseek-r1	deepseek-ai/deepseek-v3.2
nvidia/llama-3.1-nemotron-70b-instruct（目录可见但调用 404）	nvidia/llama-3.3-nemotron-super-49b-v1.5
nvidia/nemotron-4-340b-instruct（目录可见但调用 404）	nvidia/llama-3.1-nemotron-ultra-253b-v1
meta/llama-3.1-405b-instruct（>180s 超时，上游不稳）	qwen/qwen3.5-397b-a17b（397B MoE, 11s） 或 mistralai/mistral-large-3-675b-instruct-2512
deepseek-ai/deepseek-v3.1-terminus / v3.2（HTTP 504 上游超时）	meta/llama-3.3-70b-instruct 或 openai/gpt-oss-120b
qwen/qwen2.5-72b-instruct	qwen/qwen3-next-80b-a3b-instruct
zhipu-ai/glm-*、zai-org/glm-*	✅ 正确前缀是 z-ai/

4.9 一页纸推荐（2026-04-23 快照）

用途选型，直接抄：

MODEL_ALIAS = {
    # 中文（实测 finish=stop, 非 thinking, 直接出 content）
    "chat-zh":       "z-ai/glm-5.1",                          # 旗舰中文
    "chat-zh-fast":  "qwen/qwen3-next-80b-a3b-instruct",      # 秒级响应
    "chat-zh-top":   "qwen/qwen3.5-397b-a17b",                # 397B MoE, 11s

    # 英文 / 通用
    "chat":          "meta/llama-3.3-70b-instruct",           # 综合首选
    "chat-strong":   "mistralai/mistral-large-3-675b-instruct-2512",  # 675B

    # 思考 / 推理
    "reason":        "openai/gpt-oss-120b",                   # 思考模型
    "reason-nv":     "nvidia/llama-3.3-nemotron-super-49b-v1.5",

    # 代码
    "code":          "qwen/qwen3-coder-480b-a35b-instruct",

    # 多模态
    "vision":        "meta/llama-3.2-90b-vision-instruct",

    # 向量（必传 input_type）
    "embed":         "nvidia/nv-embedqa-e5-v5",
}

---

5. 调用示例（四种方式，全部实测可跑）

5.1 curl

非流式最小示例：

curl -s https://integrate.api.nvidia.com/v1/chat/completions \
  -H "Authorization: Bearer $NVAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta/llama-3.3-70b-instruct",
    "messages": [{"role": "user", "content": "一句话解释 GPU 是什么"}],
    "max_tokens": 200,
    "temperature": 0.3
  }'

流式（SSE）：

curl -sN https://integrate.api.nvidia.com/v1/chat/completions \
  -H "Authorization: Bearer $NVAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "meta/llama-3.3-70b-instruct",
    "messages": [{"role":"user","content":"数到5"}],
    "stream": true,
    "max_tokens": 60
  }'

列模型：

curl -s https://integrate.api.nvidia.com/v1/models \
  -H "Authorization: Bearer $NVAPI_KEY" | jq '.data[].id' | sort -u

5.2 Python requests（零依赖）

import os, requests

NVAPI_KEY = os.environ["NVIDIA_API_KEY"]
BASE = "https://integrate.api.nvidia.com/v1"

resp = requests.post(
    f"{BASE}/chat/completions",
    headers={
        "Authorization": f"Bearer {NVAPI_KEY}",
        "Content-Type": "application/json",
    },
    json={
        "model": "meta/llama-3.3-70b-instruct",
        "messages": [
            {"role": "system", "content": "你是严谨的技术顾问。"},
            {"role": "user",   "content": "NVIDIA NIM 是什么？"}
        ],
        "max_tokens": 512,
        "temperature": 0.7,
    },
    timeout=60,
)
resp.raise_for_status()
print(resp.json()["choices"][0]["message"]["content"])

流式增量打印：

import os, json, requests

with requests.post(
    "https://integrate.api.nvidia.com/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['NVIDIA_API_KEY']}",
             "Content-Type": "application/json"},
    json={
        "model": "meta/llama-3.3-70b-instruct",
        "messages": [{"role": "user", "content": "给我写首五言绝句"}],
        "stream": True,
        "max_tokens": 200,
    },
    stream=True,
    timeout=60,
) as r:
    for line in r.iter_lines(decode_unicode=True):
        if not line or not line.startswith("data: "):
            continue
        payload = line[6:]
        if payload == "[DONE]":
            break
        delta = json.loads(payload)["choices"][0]["delta"]
        if piece := delta.get("content"):
            print(piece, end="", flush=True)

5.3 OpenAI Python SDK（最推荐，改两行即可）

# pip install openai
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["NVIDIA_API_KEY"],
    base_url="https://integrate.api.nvidia.com/v1",
)

resp = client.chat.completions.create(
    model="z-ai/glm4.7",
    messages=[{"role": "user", "content": "用中文介绍你自己"}],
    temperature=0.3,
    max_tokens=512,
)
msg = resp.choices[0].message
print("正文：", msg.content)
# GLM / gpt-oss 等 thinking 模型会把思路放这里：
print("思维链：", getattr(msg, "reasoning_content", None))

流式：

stream = client.chat.completions.create(
    model="meta/llama-3.3-70b-instruct",
    messages=[{"role": "user", "content": "写个冒泡排序 Python 实现"}],
    stream=True,
    max_tokens=512,
)
for chunk in stream:
    piece = chunk.choices[0].delta.content or ""
    print(piece, end="", flush=True)

5.4 LangChain（官方 NVIDIA 包）

pip install langchain-nvidia-ai-endpoints

import os
from langchain_nvidia_ai_endpoints import ChatNVIDIA

os.environ["NVIDIA_API_KEY"] = "nvapi-xxxxx"

llm = ChatNVIDIA(
    model="meta/llama-3.3-70b-instruct",
    temperature=0.3,
    max_tokens=512,
)
print(llm.invoke("什么是 TensorRT-LLM？").content)

也可以用通用 ChatOpenAI：

from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    api_key=os.environ["NVIDIA_API_KEY"],
    base_url="https://integrate.api.nvidia.com/v1",
    model="meta/llama-3.3-70b-instruct",
)

5.5 Node.js（OpenAI 官方 SDK）

npm install openai

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.NVIDIA_API_KEY,
  baseURL: "https://integrate.api.nvidia.com/v1",
});

const resp = await client.chat.completions.create({
  model: "meta/llama-3.3-70b-instruct",
  messages: [{ role: "user", content: "Hello" }],
  max_tokens: 200,
});

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

---

6. Thinking 模型的特殊处理（务必读）

实测 z-ai/glm4.7、openai/gpt-oss-*、qwen/*-thinking、moonshotai/kimi-k2-thinking、nvidia/llama-3.3-nemotron-super-*、deepseek-ai/deepseek-v3.* 这批模型，响应里会把思路塞在 message.reasoning_content 字段，用户实际想看的"答案"在 message.content。

典型响应结构：

{
  "choices": [{
    "message": {
      "role": "assistant",
      "content": "",                    // ← 可能为空！
      "reasoning_content": "让我想想...", // ← 思考过程在这里
      "tool_calls": []
    },
    "finish_reason": "length"            // ← max_tokens 被思考吃完了
  }]
}

要点： 1. max_tokens 要给够（≥ 1024）否则思考过程会把额度耗光，content 空白 2. 前端渲染时建议折叠 reasoning_content（类似 ChatGPT 的 "Thinking..." 展开） 3. 非 thinking 的对应版本（如 qwen/qwen3-next-80b-a3b-instruct，不带 -thinking 后缀）响应里 reasoning_content 是 null，可直接拿 content

---

7. Embedding 调用（含 input_type 坑）

curl -s https://integrate.api.nvidia.com/v1/embeddings \
  -H "Authorization: Bearer $NVAPI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nvidia/nv-embedqa-e5-v5",
    "input": "iGaming 行业的 KYC 是什么意思",
    "input_type": "query"
  }'

必坑：nv-embedqa-* 系列必须带 input_type，取值： - "query" — 检索侧（用户问题） - "passage" — 语料侧（知识库文档）

漏传会 422。其他 embed 模型（如 baai/bge-m3）不需要。

响应：

{
  "object": "list",
  "data": [{"index": 0, "embedding": [...1024 个 float...], "object": "embedding"}],
  "model": "nvidia/nv-embedqa-e5-v5",
  "usage": {"prompt_tokens": 6, "total_tokens": 6}
}

---

8. 工具调用 / 结构化输出

完全按 OpenAI 官方协议（tools + tool_choice + response_format）来用。实测 Llama 3.3 70B、Qwen3 系列、GLM 4.7/5.1、Mistral Large 都支持。

from openai import OpenAI, pydantic_function_tool
from pydantic import BaseModel

class GetWeather(BaseModel):
    city: str
    unit: str = "celsius"

client = OpenAI(api_key=os.environ["NVIDIA_API_KEY"],
                base_url="https://integrate.api.nvidia.com/v1")

resp = client.chat.completions.create(
    model="meta/llama-3.3-70b-instruct",
    messages=[{"role": "user", "content": "北京现在多少度？"}],
    tools=[pydantic_function_tool(GetWeather)],
    tool_choice="auto",
)
print(resp.choices[0].message.tool_calls)

JSON 严格模式：

resp = client.chat.completions.create(
    model="meta/llama-3.3-70b-instruct",
    messages=[{"role": "user", "content": '提取："Alice 25 岁" 为 JSON'}],
    response_format={"type": "json_object"},
)

---

9. 错误体格式（实测两套并存，务必同时处理）

9.1 路由/鉴权层（请求甚至没进到模型容器）

// HTTP 403 鉴权失败
{"status": 403, "title": "Forbidden", "detail": "Authorization failed"}

// HTTP 404 模型不存在
{"status": 404, "title": "Not Found",
 "detail": "Function 'xxx': Not found for account 'iGOqADbdolYjRmuQgfcaVDuHRHp6gAfMrDciJqkC8Qw'"}

小贴士：404 的 detail 里会带 account id，排查支持工单时就是它。

也有时是纯文本 404（路由完全匹配不上路径或未知 model id 的某些场景）：

HTTP 404
404 page not found

9.2 NIM 模型容器内部（Pydantic 校验失败）

// HTTP 400 字段类型错误
{"error": {"message": "1 validation error:\n  {'type': 'list_type', 'loc': ('body', 'messages'), 'msg': 'Input should be a valid list', ...}\n\n  File \"/usr/local/lib/python3.12/...\""}}

这会泄漏内部 Python 路径。如果你要把 NIM 的 API 再代理给最终用户，务必自己包一层错误整形。

9.3 上游超时

HTTP 504    （Gateway Timeout）
（空 body）

主要发生在大型 thinking 模型（DeepSeek V3、Nemotron Ultra）上，请求要带重试 + 备选模型。

---

10. NVIDIA 扩展字段（非 OpenAI 标准）

实测响应体里除了标准字段，还会带：

字段	示例	用途
message.reasoning_content	"让我想想..."	thinking 模型的思路
message.token_ids	[1,2,3,...]	返回 token id 序列
choices[].stop_reason	null	NIM 附加的停止原因
prompt_logprobs / prompt_token_ids	—	prompt 级别分析
kv_transfer_params	—	KV cache 迁移参数
nvext.worker_id	{"prefill_worker_id":..., "decode_worker_id":...}	哪台 GPU 处理的
nvext.timing	{"prefill_time_ms":381, "ttft_ms":381, "total_time_ms":4096, "kv_hit_rate":0.0}	延迟分解
service_tier / system_fingerprint	OpenAI 同名字段	通常为 null

闭环建议：把 nvext.timing.ttft_ms 和 kv_hit_rate 采集到 Grafana，可以直接观测 NIM 真实延迟、缓存命中率。

---

11. 限速与重试最佳实践

11.0 实测速率（2026-04-22）

50 并发打 meta/llama-3.3-70b-instruct（max_tokens=8 最小体积）：

50 requests, wall time 24.1s
  HTTP 200 : 18
  HTTP 429 : 32   body={"status":429,"title":"Too Many Requests"}
                  Retry-After: (未返回)

结论（实测，非文档推断）： - 并发上限 ≈ 20（免费层），超了同步返回 429，非排队 - 稳态吞吐 ≈ 40 RPM（50 req / 24s ≈ 40 RPM 窗口） - 没有 Retry-After header，客户端必须自己实现指数退避 - 429 响应体是 {"status":429,"title":"Too Many Requests"}，没有 detail - 升配额去 NVIDIA Developer Forum 开工单，带上账号 id（从 404 detail 提取）

11.1 生产级客户端封装

import time, random, requests
from requests.adapters import HTTPAdapter
from urllib3.util.retry import Retry

def nvidia_session():
    s = requests.Session()
    retry = Retry(
        total=5,
        backoff_factor=1.5,          # 1.5s, 3s, 6s, 12s, 24s
        status_forcelist=[429, 500, 502, 503, 504],
        allowed_methods=["POST", "GET"],
        respect_retry_after_header=True,
    )
    s.mount("https://", HTTPAdapter(max_retries=retry))
    return s

session = nvidia_session()

11.2 并发控制（40 RPM / 20 并发 免费层）

from collections import deque
import time, threading

class RPMLimiter:
    def __init__(self, rpm=35):                       # 留 5 的余量
        self.rpm = rpm
        self.bucket = deque()
        self.lock = threading.Lock()

    def acquire(self):
        with self.lock:
            now = time.monotonic()
            while self.bucket and self.bucket[0] <= now - 60:
                self.bucket.popleft()
            if len(self.bucket) >= self.rpm:
                time.sleep(60 - (now - self.bucket[0]) + 0.1)
            self.bucket.append(time.monotonic())

limiter = RPMLimiter(rpm=35)

---

12. 常见问题 FAQ

Q1：官方说"免费用一年"是真的吗？ A：早期宣传不精确。实际是新账号默认 1000 credits，用完可以在开发者论坛申请补发。不绑卡，不到期，但也不是无限用。

Q2：这个 key 能不能在生产环境直接用？ A：不建议。理由：(1) 免费层有 40 RPM 限制；(2) NIM 云托管的 SLA 未正式承诺；(3) 模型目录会漂移（实测已出现 id 下架）。生产环境要么用企业版，要么用自托管 NIM 容器，要么用 OpenRouter/together.ai 等付费聚合。

Q3：为什么我调 deepseek-r1 报 404？ A：目录里没有 deepseek-r1。当前只有 deepseek-ai/deepseek-v3.1-terminus、deepseek-v3.2、deepseek-coder-6.7b-instruct。先 GET /v1/models | grep deepseek 再用。

Q4：为什么 Llama Nemotron 70B (nvidia/llama-3.1-nemotron-70b-instruct) 能出现在 /v1/models 列表里，调用却 404？ A：已知现象：目录和实际路由不完全同步。凡是历史有名的老模型，都以调用返回为准，遇到 404 换替代（nvidia/llama-3.3-nemotron-super-49b-v1.5）。

Q5：GLM 系列用哪个？ A：目录里存在 z-ai/glm5、z-ai/glm4.7、z-ai/glm-5.1。优先 z-ai/glm-5.1（最新旗舰），次选 z-ai/glm4.7（实测稳定带思维链）。注意前缀是 z-ai/ 不是 zai-org/ 或 zhipu-ai/。

Q6：返回体里 content 是空字符串？ A：大概率是 thinking 模型把 max_tokens 用在 reasoning_content 上了。

• 方案 A：把 max_tokens 加到 ≥ 2048
• 方案 B：换非 thinking 版本（-instruct 后缀而非 -thinking）

Q7：curl 超时（HTTP 504）？ A：大模型 prefill 慢，典型 DeepSeek V3/V3.1 / Nemotron Ultra。处理：(1) 缩短 prompt；(2) 加客户端重试；(3) 备选模型（Llama 3.3 70B 基本不会 504）。

Q8：需要 GPU 吗？ A：不需要。调 integrate.api.nvidia.com 就是纯 HTTP，NVIDIA 在云端用他们的 GPU 算，你这边 CPU + 网络就够。只有自托管 NIM 容器时才需要 NVIDIA GPU。

Q9：有 Chinese-focus 的模型优先级建议吗？ A：按中文能力排序（实战感受）：z-ai/glm4.7 > qwen/qwen3.5-397b-a17b > qwen/qwen3-next-80b-a3b-instruct > moonshotai/kimi-k2.5 > meta/llama-3.3-70b-instruct。

Q10：账号被封怎么办？ A：靠账号 ID（从 404 detail 里提取，如 iGOqADbdolYjRmuQgfcaVDuHRHp6gAfMrDciJqkC8Qw）到 NVIDIA Developer Forums 发帖带账号 ID + key 前 10 位。

---

13. 实测附录（证据链）

本手册基于 2026-04-20 / 2026-04-22 用真实 key 跑出的 HTTP 测试。关键原始证据落盘在本机 /tmp/：

文件	内容	大小
/tmp/nvidia_models.json	GET /v1/models 完整返回（129 个 id）	12 KB
/tmp/nvidia_llama33.json	Llama-3.3-70b 非流式响应	832 B
/tmp/nvidia_glm.json	GLM-4.7 响应（含 reasoning_content）	1.8 KB
/tmp/nvidia_qwen.json	Qwen3-next 响应	814 B
/tmp/nvidia_stream.txt	Llama-3.3 流式 SSE 原始 chunk	2.9 KB
/tmp/nvidia_embed.json	nv-embedqa-e5-v5 1024 维	19 KB
/tmp/nvidia_gptoss.json	gpt-oss-120b（thinking 模型证据）	-
/tmp/nvidia_nemotron_super.json	llama-3.3-nemotron-super-49b-v1.5	-

实测结论： - ✅ Key 有效；账号 id：iGOqADbdolYjRmuQgfcaVDuHRHp6gAfMrDciJqkC8Qw - ✅ 可用（实测 HTTP 200）： - Meta: llama-3.3-70b-instruct（秒级，最稳） - 智谱: z-ai/glm-5.1（91s 冷启动，中文旗舰）、z-ai/glm4.7（thinking） - 阿里: qwen/qwen3.5-397b-a17b（11s，性价比之王）、qwen/qwen3-next-80b-a3b-instruct - Moonshot: moonshotai/kimi-k2.5（42s，max_tokens 必须 ≥1024） - Mistral: mistralai/mistral-large-3-675b-instruct-2512（675B, 65s） - OpenAI: openai/gpt-oss-120b（thinking） - NVIDIA: llama-3.3-nemotron-super-49b-v1.5（thinking） - Embedding: nvidia/nv-embedqa-e5-v5（1024 维） - ❌ 上游超时（HTTP 504 或 >180s）： - meta/llama-3.1-405b-instruct（>180s） - deepseek-ai/deepseek-v3.1-terminus / v3.2（504） - ❌ 目录可见但不可调（HTTP 404）： - nvidia/nemotron-4-340b-instruct - nvidia/llama-3.1-nemotron-70b-instruct - ⚠️ 速率限制实测：50 并发 → 18 通过 + 32 返回 HTTP 429（无 Retry-After header），稳态 ≈ 40 RPM、并发上限 ≈ 20

---

14. 集成到项目的推荐姿势

14.1 统一 LLM Client（OpenAI SDK 双插头）

# llm_client.py
import os
from openai import OpenAI

PROVIDERS = {
    "nvidia": dict(
        api_key=os.environ.get("NVIDIA_API_KEY"),
        base_url="https://integrate.api.nvidia.com/v1",
    ),
    "openai": dict(
        api_key=os.environ.get("OPENAI_API_KEY"),
        base_url="https://api.openai.com/v1",
    ),
}

def get_client(provider: str = "nvidia") -> OpenAI:
    return OpenAI(**PROVIDERS[provider])

# 路由到不同 provider 的 model 别名（2026-04-23 实测 ✅）
MODEL_ALIAS = {
    "chat":        ("nvidia", "meta/llama-3.3-70b-instruct"),                    # 综合首选，秒级
    "chat-zh":     ("nvidia", "z-ai/glm-5.1"),                                   # 中文旗舰
    "chat-zh-fast":("nvidia", "qwen/qwen3-next-80b-a3b-instruct"),               # 中文快选
    "chat-strong": ("nvidia", "qwen/qwen3.5-397b-a17b"),                         # 397B, 11s
    "chat-eu":     ("nvidia", "mistralai/mistral-large-3-675b-instruct-2512"),   # 675B 欧洲旗舰
    "code":        ("nvidia", "qwen/qwen3-coder-480b-a35b-instruct"),            # 代码
    "embed":       ("nvidia", "nvidia/nv-embedqa-e5-v5"),                        # 需传 input_type
    "vision":      ("nvidia", "meta/llama-3.2-90b-vision-instruct"),             # 多模态
    "reason":      ("nvidia", "openai/gpt-oss-120b"),                            # thinking
    "reason-nv":   ("nvidia", "nvidia/llama-3.3-nemotron-super-49b-v1.5"),       # NV thinking
    "fallback":    ("openai", "gpt-4o-mini"),
}
# ⚠️ 2026-04-22~23 实测黑名单：meta/llama-3.1-405b-instruct（>180s 超时）、
#    nvidia/nemotron-4-340b-instruct（404）、deepseek-ai/deepseek-v3.x（504）

def chat(alias: str, messages, **kw):
    provider, model = MODEL_ALIAS[alias]
    return get_client(provider).chat.completions.create(
        model=model, messages=messages, **kw)

14.2 Thinking 模型输出清洗

def extract_answer(resp) -> dict:
    msg = resp.choices[0].message
    return {
        "answer": msg.content or "",
        "thinking": getattr(msg, "reasoning_content", None) or "",
        "tool_calls": msg.tool_calls or [],
        "finish_reason": resp.choices[0].finish_reason,
    }

14.3 ENV 模板（.env.example）

# NVIDIA NIM
NVIDIA_API_KEY=nvapi-__REPLACE_ME__
NVIDIA_BASE_URL=https://integrate.api.nvidia.com/v1

# OpenAI 兼容复用（可选）
OPENAI_API_KEY=${NVIDIA_API_KEY}
OPENAI_BASE_URL=${NVIDIA_BASE_URL}

---

15. 参考链接

官方

• build.nvidia.com - 模型市场 / API Key 管理
• NVIDIA NIM 官方文档
• NIM for LLMs - API Reference
• NIM for LLMs - Getting Started
• NIM for LLMs - Function Calling
• NIM for Vision Language Models
• NIM for Embedding / Retrieval

集成库

• langchain-nvidia-ai-endpoints
• liteLLM NVIDIA NIM Provider
• LlamaIndex NVIDIA
• Vercel AI SDK - OpenAI Compatible - NIM

社区 & 故障排查

• NVIDIA Developer Forums
• Forum: NIM API Credits
• Forum: 429 Too Many Requests
• NVIDIA Developer Blog - Deploying Gen AI with NIM

---

结语：这份手册写到这里是 2026-04-22 的快照。模型目录会天天变，原则是"先 GET /v1/models、再从本文档的分类表里挑 id、遇 404/504 看 §9 和 §12"，三步闭环即可。