当前位置：首页 > news >正文

NVIDIA NIM 开发者指南：入门

news 2025/11/1 8:22:30

NVIDIA NIM 开发者指南：入门

NVIDIA 开发者计划

想要了解有关 NIM 的更多信息？加入 NVIDIA 开发者计划，即可免费访问任何基础设施云、数据中心或个人工作站上最多 16 个 GPU 上的自托管 NVIDIA NIM 和微服务。

加入免费的 NVIDIA 开发者计划后，您可以随时通过 NVIDIA API 目录访问 NIM。要获得企业级安全性、支持和 API 稳定性，请选择通过我们的免费 90 天 NVIDIA AI Enterprise 试用版使用企业电子邮件地址访问 NIM 的选项。

预先条件

设置

NVIDIA AI Enterprise 许可证：NVIDIA NIM for LLM 可在 NVIDIA AI Enterprise 许可证下自行托管。注册 NVIDIA AI Enterprise 许可证。
NVIDIA GPU：NVIDIA NIM for LLM（NIM for LLM）可在任何具有足够 GPU 内存的 NVIDIA GPU 上运行，但某些模型/GPU 组合经过了优化。还支持启用张量并行的同构多 GPU 系统。有关更多信息，请参阅支持矩阵。
CPU：此版本仅适用于 x86_64 架构
操作系统：任何 Linux 发行版：
- 受 NVIDIA Container 工具包支持
- glibc >= 2.35（参见 ld -v 的输出）
CUDA 驱动程序：按照安装指南操作。我们建议：
- 使用网络存储库作为包管理器安装的一部分，跳过 CUDA 工具包安装，因为库在 NIM 容器中可用，然后
- 安装特定版本的开放内核：

Major Version	EOL	Data Center & RTX/Quadro GPUs	GeForce GPUs
> 550	TBD	X	X
550	Feb. 2025	X	X
545	Oct. 2023	X	X
535	June 2026	X
525	Nov. 2023	X
470	Sept. 2024	X

安装 Docker
安装 NVIDIA Container Toolkit

注意

安装工具包后，请按照 NVIDIA Container Toolkit 文档中“配置 Docker”部分中的说明进行操作。

为确保您的设置正确，请运行以下命令（有关使用 --gpus all 的说明，请参阅“GPU 选择”部分）：

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

此命令应产生类似于以下内容之一的输出，您可以在其中确认 CUDA 驱动程序版本和可用的 GPU。

+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 550.54.14              Driver Version: 550.54.14      CUDA Version: 12.4     |
|-----------------------------------------+------------------------+----------------------+
| GPU  Name                 Persistence-M | Bus-Id          Disp.A | Volatile Uncorr. ECC |
| Fan  Temp   Perf          Pwr:Usage/Cap |           Memory-Usage | GPU-Util  Compute M. |
|                                         |                        |               MIG M. |
|=========================================+========================+======================|
|   0  NVIDIA H100 80GB HBM3          On  |   00000000:1B:00.0 Off |                    0 |
| N/A   36C    P0            112W /  700W |   78489MiB /  81559MiB |      0%      Default |
|                                         |                        |             Disabled |
+-----------------------------------------+------------------------+----------------------++-----------------------------------------------------------------------------------------+
| Processes:                                                                              |
|  GPU   GI   CI        PID   Type   Process name                              GPU Memory |
|        ID   ID                                                               Usage      |
|=========================================================================================|
|  No running processes found                                                             |
+-----------------------------------------------------------------------------------------+

安装适用于 Windows 的 WSL2

某些可下载的 NIM 可在带有适用于 Linux 的 Windows 系统 (WSL) 的 RTX Windows 系统上使用。要启用 WSL2，请执行以下步骤。

确保您的计算机能够按照 WSL2 文档的先决条件部分所述运行 WSL2。
按照安装 WSL 命令中列出的步骤在 Windows 计算机上启用 WSL2。默认情况下，这些步骤会安装 Linux 的 Ubuntu 发行版。有关备选安装的列表，请参阅更改安装的默认 Linux 发行版。

启动用于 LLM 的 NVIDIA NIM

您可以从 API 目录或 NGC 下载并运行您选择的 NIM。

选项 1：从 API 目录

查看此视频，其中说明了以下步骤。

生成 API 密钥

导航到 API 目录。
选择一个模型。
选择一个输入选项。以下示例是一个提供 Docker 选项的模型。并非所有模型都提供此选项，但都包含“Get API Key”链接。

在这里插入图片描述

如果出现提示，选择“获取 API 密钥”并登录。

在这里插入图片描述

选择“Generate Key”

在这里插入图片描述

复制您的密钥并将其存储在安全的地方。不要与他人共享。

在这里插入图片描述

登录 Docker

使用 docker login 命令（如以下屏幕截图所示）登录 Docker。将用户名和密码的占位符替换为您的值。

在这里插入图片描述

下载并启动适用于 LLM 的 NVIDIA NIM

使用以下命令通过 Docker 拉取并运行 NIM。

在这里插入图片描述

要修改 docker 运行参数，请参阅 Docker 运行参数。

现在，您可以跳转到运行推理。

选项 2：从 NGC

生成 API 密钥

需要 NGC API 密钥才能访问 NGC 资源，可以在此处生成密钥：https://org.ngc.nvidia.com/setup/personal-keys。

创建 NGC API 密钥时，请确保至少从“包含的服务”下拉列表中选择了“NGC 目录”。如果要将此密钥重新用于其他目的，则可以包含更多服务。

在这里插入图片描述

导出 API 密钥

将 API 密钥的值作为 NGC_API_KEY 环境变量传递给下一节中的 docker run 命令，以便在启动 NIM 时下载适当的模型和资源。

如果您不熟悉如何创建 NGC_API_KEY 环境变量，最简单的方法是在终端中将其导出：

export NGC_API_KEY=<value>

运行以下命令之一以使该密钥在启动时可用：

# If using bash
echo "export NGC_API_KEY=<value>" >> ~/.bashrc# If using zsh
echo "export NGC_API_KEY=<value>" >> ~/.zshrc

注意
其他更安全的选项包括将值保存在文件中，以便您可以使用 cat $NGC_API_KEY_FILE 或使用密码管理器进行检索。

Docker 登录 NGC

要从 NGC 中提取 NIM 容器映像，请首先使用以下命令通过 NVIDIA Container Registry 进行身份验证：

echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin

使用 $oauthtoken 作为用户名，使用 NGC_API_KEY 作为密码。$ oauthtoken 用户名是一个特殊名称，表示您将使用 API 密钥而不是用户名和密码进行身份验证。

列出可用的 NIM

本文档在多个示例中使用了 ngc CLI 工具。有关下载和配置该工具的信息，请参阅 NGC CLI 文档。

使用以下命令以 CSV 格式列出可用的 NIM。

ngc registry image list --format_type csv nvcr.io/nim/*

此命令应产生以下格式的输出：

Name,Repository,Latest Tag,Image Size,Updated Date,Permission,Signed Tag?,Access Type,Associated Products
<name1>,<repository1>,<latest tag1>,<image size1>,<updated date1>,<permission1>,<signed tag?1>,<access type1>,<associated products1>
...
<nameN>,<repositoryN>,<latest tagN>,<image sizeN>,<updated dateN>,<permissionN>,<signed tag?N>,<access typeN>,<associated productsN>

调用 docker run 命令时使用 Repository 和 Latest Tag 字段，如下节所示。

启动 NIM

以下命令为 llama3-8b-instruct 模型启动 Docker 容器。要为不同的 NIM 启动容器，请将 Repository 和 Latest_Tag 的值替换为上一个 image list 命令中的值，并将 CONTAINER_NAME 的值更改为适当的值。

您可以通过以下命令获取有关模型的信息来判断您拥有正确的 Repository 和 Latest_Tag 值：

ngc registry image info --format_type ascii ${Repository}:${Latest_Tag}

它应该产生如下输出：

----------------------------------------------------------
Model Version Information
Id: 0.10.0+e6f46027-h100x1-fp16-balanced.24.06.15839955
Batch Size:
Memory Footprint:
Number Of Epochs:
Accuracy Reached:
GPU Model:
Access Type:
Associated Products:
Created Date: 2024-06-14T22:28:17.604Z
Description:
Status: UPLOAD_COMPLETE
Total File Count: 11
Total Size: 14.96 GB
----------------------------------------------------------

注意
要部署不适合单个节点的模型，请参阅多节点部署

# Choose a container name for bookkeeping
export CONTAINER_NAME=Llama3-8B-Instruct# The container name from the previous ngc registgry image list command
Repository=nim/meta/llama3-8b-instruct
Latest_Tag=1.2.1# Choose a LLM NIM Image from NGC
export IMG_NAME="nvcr.io/${Repository}:${Latest_Tag}"# Choose a path on your system to cache the downloaded models
export LOCAL_NIM_CACHE=~/.cache/nim
mkdir -p "$LOCAL_NIM_CACHE"# Start the LLM NIM
docker run -it --rm --name=$CONTAINER_NAME \--runtime=nvidia \--gpus all \--shm-size=16GB \-e NGC_API_KEY=$NGC_API_KEY \-v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \-u $(id -u) \-p 8000:8000 \$IMG_NAME

运行推理

在启动期间，NIM 容器会下载所需的资源并开始在 API 端点后面为模型提供服务。以下消息表示启动成功。


INFO: Application startup complete.
INFO: Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

看到此消息后，您可以通过执行推理请求来验证 NIM 的部署。在新终端中，运行以下命令以显示可用于推理的模型列表：

curl -X GET 'http://0.0.0.0:8000/v1/models'

提示
将 curl 命令的结果导入 jq 或 python -m json.tool 等工具，使 API 的输出更易于阅读。例如：curl -s http://0.0.0.0:8000/v1/models | jq。

此命令应产生类似以下内容的输出：

{"object": "list","data": [{"id": "meta/llama3-8b-instruct","object": "model","created": 1715659875,"owned_by": "vllm","root": "meta/llama3-8b-instruct","parent": null,"permission": [{"id": "modelperm-e39aaffe7015444eba964fa7736ae653","object": "model_permission","created": 1715659875,"allow_create_engine": false,"allow_sampling": true,"allow_logprobs": true,"allow_search_indices": false,"allow_view": true,"allow_fine_tuning": false,"organization": "*","group": null,"is_blocking": false}]}]}

OpenAI 完成请求

完成端点通常用于基础模型。使用完成端点，提示将以纯字符串形式发送，并且模型会根据所选的其他参数生成最可能的文本完成。要流式传输结果，请设置“stream”：true。

重要
更新模型名称以满足您的要求。例如，对于 llama3-8b-instruct 模型，您可以使用以下命令：

curl -X 'POST' \'http://0.0.0.0:8000/v1/completions' \-H 'accept: application/json' \-H 'Content-Type: application/json' \-d '{
"model": "meta/llama3-8b-instruct",
"prompt": "Once upon a time",
"max_tokens": 64
}'

您还可以使用 OpenAI Python API 库。

from openai import OpenAI
client = OpenAI(base_url="http://0.0.0.0:8000/v1", api_key="not-used")
prompt = "Once upon a time"
response = client.completions.create(model="meta/llama3-8b-instruct",prompt=prompt,max_tokens=16,stream=False
)
completion = response.choices[0].text
print(completion)# Prints:
# , there was a young man named Jack who lived in a small village at the

OpenAI 聊天完成请求

聊天完成端点通常与聊天或指导调整模型一起使用，这些模型旨在通过对话方式使用。使用聊天完成端点，提示以带有角色和内容的消息形式发送，从而提供了一种自然的方式来跟踪多轮对话。要流式传输结果，请设置“stream”：true。

重要

根据您的要求更新模型名称。例如，对于 llama3-8b-instruct 模型，您可以使用以下命令：


curl -X 'POST' \
'http://0.0.0.0:8000/v1/chat/completions' \-H 'accept: application/json' \-H 'Content-Type: application/json' \-d '{
"model": "meta/llama3-8b-instruct",
"messages": [
{
"role":"user",
"content":"Hello! How are you?"
},
{
"role":"assistant",
"content":"Hi! I am quite well, how can I help you today?"
},
{
"role":"user",
"content":"Can you write me a song?"
}
],
"max_tokens": 32
}'

您还可以使用 OpenAI Python API 库。


from openai import OpenAI
client = OpenAI(base_url="http://0.0.0.0:8000/v1", api_key="not-used")
messages = [{"role": "user", "content": "Hello! How are you?"},{"role": "assistant", "content": "Hi! I am quite well, how can I help you today?"},{"role": "user", "content": "Write a short limerick about the wonders of GPU computing."}
]
chat_response = client.chat.completions.create(model="meta/llama3-8b-instruct",messages=messages,max_tokens=32,stream=False
)
assistant_message = chat_response.choices[0].message
print(assistant_message)# Prints:
# ChatCompletionMessage(content='There once was a GPU so fine,\nProcessed data in parallel so divine,\nIt crunched with great zest,\nAnd computational quest,\nUnleashing speed, a true wonder sublime!', role='assistant', function_call=None, tool_calls=None)

注意
如果您遇到 BadRequestError，并出现错误消息，表明您缺少消息或提示字段，则您可能无意中使用了错误的端点。

例如，如果您发出一个包含用于聊天完成的请求正文的完成请求，您将收到以下错误：

{
“object”：“error”，
“message”：“[{'type': 'missing', 'loc': ('body', 'prompt'), 'msg': 'Field required', ...",
“type”：“BadRequestError”，
“param”：“null,
“code”：400
}

相反，如果您发出一个包含用于完成的请求正文的聊天完成请求，您将收到以下错误：

{
“object”：“error”，
“message”：“[{'type': 'missing', 'loc': ('body', 'messages'), 'msg': 'Field required', ...",
“type”：“BadRequestError”，
“param”：“null,
“code”：400
}

验证您正在使用的端点，例如作为 /v1/completions 或 /v1/chat/completions，已正确配置您的请求。

参数高效微调

参数高效微调 (PEFT) 方法能够高效适应大型预训练模型。目前 NIM 仅支持 LoRA PEFT。有关详细信息，请参阅参数高效微调。

停止容器

如果使用 --name 命令行选项启动 Docker 容器，则可以使用以下命令停止正在运行的容器。

docker stop $CONTAINER_NAME

如果 stop 没有响应，请使用 docker kill。如果您不打算按原样重新启动容器（使用 docker start $CONTAINER_NAME），请在该命令后执行 docker rm $CONTAINER_NAME，在这种情况下，您需要重新使用本节开头的 docker run … 说明为您的 NIM 启动新容器。

如果您没有使用 --name 启动容器，请检查 docker ps 命令的输出以获取您使用的给定映像的容器 ID。

Kubernetes 安装

nim-deploy 展示了 Kubernetes 安装的几种参考实现。这些示例是实验性的，可能需要修改才能在特定集群设置中运行。

从本地资产提供模型

NIM for LLMs 提供的实用程序允许将模型下载到本地目录作为模型存储库或 NIM 缓存。有关详细信息，请参阅实用程序部分。

使用以下命令启动 NIM 容器。从那里，您可以在本地查看和下载模型。

# Choose a container name for bookkeeping
export CONTAINER_NAME=Llama-3.1-8B-instruct# The container name from the previous ngc registgry image list command
Repository=nim/meta/llama-3.1-8b-instruct
Latest_Tag=1.1.0# Choose a LLM NIM Image from NGC
export IMG_NAME="nvcr.io/${Repository}:${Latest_Tag}"# Choose a path on your system to cache the downloaded models
export LOCAL_NIM_CACHE=~/.cache/downloaded-nim
mkdir -p "$LOCAL_NIM_CACHE"# Add write permissions to the NIM cache for downloading model assets
chmod -R a+w "$LOCAL_NIM_CACHE"docker run -it --rm --name=$CONTAINER_NAME \-e LOG_LEVEL=$LOG_LEVEL \-e NGC_API_KEY=$NGC_API_KEY \--gpus all \-v $LOCAL_NIM_CACHE:/opt/nim/.cache \-u $(id -u) \$IMG_NAME \bash -i

使用 list-model-profiles 命令列出可用的配置文件。

list-model-profiles \
-e NGC_API_KEY=$NGC_API_KEY
#SYSTEM INFO
#- Free GPUs:
# - [26b3:10de] (0) NVIDIA RTX 5880 Ada Generation (RTX A6000 Ada) [current utilization: 1%]
# - [26b3:10de] (1) NVIDIA RTX 5880 Ada Generation (RTX A6000 Ada) [current utilization: 1%]
# - [1d01:10de] (2) NVIDIA GeForce GT 1030 [current utilization: 2%]
#MODEL PROFILES
#- Compatible with system and runnable:
# - 19031a45cf096b683c4d66fff2a072c0e164a24f19728a58771ebfc4c9ade44f (vllm-fp16-tp2)
# - 8835c31752fbc67ef658b20a9f78e056914fdef0660206d82f252d62fd96064d (vllm-fp16-tp1)
# - With LoRA support:
# - c5ffce8f82de1ce607df62a4b983e29347908fb9274a0b7a24537d6ff8390eb9 (vllm-fp16-tp2-lora)
# - 8d3824f766182a754159e88ad5a0bd465b1b4cf69ecf80bd6d6833753e945740 (vllm-fp16-tp1-lora)
#- Incompatible with system:
# - dcd85d5e877e954f26c4a7248cd3b98c489fbde5f1cf68b4af11d665fa55778e (tensorrt_llm-h100-fp8-tp2-latency)
# - f59d52b0715ee1ecf01e6759dea23655b93ed26b12e57126d9ec43b397ea2b87 (tensorrt_llm-l40s-fp8-tp2-latency)
# - 30b562864b5b1e3b236f7b6d6a0998efbed491e4917323d04590f715aa9897dc (tensorrt_llm-h100-fp8-tp1-throughput)
# - 09e2f8e68f78ce94bf79d15b40a21333cea5d09dbe01ede63f6c957f4fcfab7b (tensorrt_llm-l40s-fp8-tp1-throughput)
# - a93a1a6b72643f2b2ee5e80ef25904f4d3f942a87f8d32da9e617eeccfaae04c (tensorrt_llm-a100-fp16-tp2-latency)
# - e0f4a47844733eb57f9f9c3566432acb8d20482a1d06ec1c0d71ece448e21086 (tensorrt_llm-a10g-fp16-tp2-latency)
# - 879b05541189ce8f6323656b25b7dff1930faca2abe552431848e62b7e767080 (tensorrt_llm-h100-fp16-tp2-latency)
# - 24199f79a562b187c52e644489177b6a4eae0c9fdad6f7d0a8cb3677f5b1bc89 (tensorrt_llm-l40s-fp16-tp2-latency)
# - 751382df4272eafc83f541f364d61b35aed9cce8c7b0c869269cea5a366cd08c (tensorrt_llm-a100-fp16-tp1-throughput)
# - c334b76d50783655bdf62b8138511456f7b23083553d310268d0d05f254c012b (tensorrt_llm-a10g-fp16-tp1-throughput)
# - cb52cbc73a6a71392094380f920a3548f27c5fcc9dab02a98dc1bcb3be9cf8d1 (tensorrt_llm-h100-fp16-tp1-throughput)
# - d8dd8af82e0035d7ca50b994d85a3740dbd84ddb4ed330e30c509e041ba79f80 (tensorrt_llm-l40s-fp16-tp1-throughput)
# - 9137f4d51dadb93c6b5864a19fd7c035bf0b718f3e15ae9474233ebd6468c359 (tensorrt_llm-a10g-fp16-tp2-throughput-lora)
# - cce57ae50c3af15625c1668d5ac4ccbe82f40fa2e8379cc7b842cc6c976fd334 (tensorrt_llm-a100-fp16-tp1-throughput-lora)
# - 3bdf6456ff21c19d5c7cc37010790448a4be613a1fd12916655dfab5a0dd9b8e (tensorrt_llm-h100-fp16-tp1-throughput-lora)
# - 388140213ee9615e643bda09d85082a21f51622c07bde3d0811d7c6998873a0b (tensorrt_llm-l40s-fp16-tp1-throughput-lora)

您可以使用 download-to-cache 命令将这些配置文件中的任何一个下载到 NIM 缓存。以下示例将 tensorrt_llm-l40s-fp8-tp1-throughput 配置文件下载到 NIM 缓存。

download-to-cache --profile 09e2f8e68f78ce94bf79d15b40a21333cea5d09dbe01ede63f6c957f4fcfab7b

您还可以让 download-to-cache 根据要下载的硬件决定最优配置文件，方法是不提供要下载的配置文件，如以下示例所示。

download-to-cache

有关 download-to-cache 工具的更多信息，请执行以下命令：

download-to-cache -h
# Downloads selected or default model profiles to NIM cache. Can be used to pre-
# cache profiles prior to deployment.# options:
# -h, --help show this help message and exit
# --profiles [PROFILES ...], -p [PROFILES ...]
# Profile hashes to download. If none are provided, the
# optimal profile is downloaded. Multiple profiles can
# be specified separated by spaces.
# --all Set this to download all profiles to cache
# --lora Set this to download default lora profile. This
# expects --profiles and --all arguments are not
# specified.

离线缓存路由

NIM 支持在气隙系统（也称为气墙、气隙或断开网络）中提供模型。如果 NIM 检测到缓存中先前加载的配置文件，它会从缓存中提供该配置文件。使用下载到缓存将配置文件下载到缓存后，可以将缓存传输到气隙系统以运行 NIM，无需任何互联网连接，也无需连接到 NGC 注册表。

要查看此操作，请不要提供 NGC_API_KEY，如以下示例所示。


# Create an example air-gapped directory where the downloaded NIM will be deployed
export AIR_GAP_NIM_CACHE=~/.cache/air-gap-nim-cache
mkdir -p "$AIR_GAP_NIM_CACHE"# Transport the downloaded NIM to an air-gapped directory
cp -r "$LOCAL_NIM_CACHE"/* "$AIR_GAP_NIM_CACHE"# Choose a container name for bookkeeping
export CONTAINER_NAME=Llama-3.1-8B-instruct# The container name from the previous ngc registgry image list command
Repository=nim/meta/llama-3.1-8b-instruct
Latest_Tag=1.1.0# Choose a LLM NIM Image from NGC
export IMG_NAME="nvcr.io/${Repository}:${Latest_Tag}"# Assuming the command run prior was `download-to-cache`, downloading the optimal profile
docker run -it --rm --name=$CONTAINER_NAME \--runtime=nvidia \--gpus all \--shm-size=16GB \-v "$AIR_GAP_NIM_CACHE:/opt/nim/.cache" \-u $(id -u) \-p 8000:8000 \$IMG_NAME# Assuming the command run prior was `download-to-cache --profile 09e2f8e68f78ce94bf79d15b40a21333cea5d09dbe01ede63f6c957f4fcfab7b`
docker run -it --rm --name=$CONTAINER_NAME \--runtime=nvidia \--gpus all \--shm-size=16GB \-e NIM_MODEL_PROFILE=09e2f8e68f78ce94bf79d15b40a21333cea5d09dbe01ede63f6c957f4fcfab7b \-v "$AIR_GAP_NIM_CACHE:/opt/nim/.cache" \-u $(id -u) \-p 8000:8000 \$IMG_NAME

气隙部署（本地模型目录路由）

气隙路由的另一种选择是使用 NIM 容器中的 create-model-store 命令部署创建的模型存储库，以创建单个模型的存储库，如以下示例所示。

create-model-store --profile 09e2f8e68f78ce94bf79d15b40a21333cea5d09dbe01ede63f6c957f4fcfab7b --model-store /path/to/model-repository

# Choose a container name for bookkeeping
export CONTAINER_NAME=Llama-3.1-8B-instruct# The container name from the previous ngc registgry image list command
Repository=nim/meta/llama-3.1-8b-instruct
Latest_Tag=1.1.0# Choose a LLM NIM Image from NGC
export IMG_NAME="nvcr.io/${Repository}:${Latest_Tag}"# Choose a path on your system to cache the downloaded models
export LOCAL_NIM_CACHE=~/.cache/nim
mkdir -p "$LOCAL_NIM_CACHE"export MODEL_REPO=/path/to/model-repository
export NIM_SERVED_MODEL_NAME=my-modeldocker run -it --rm --name=$CONTAINER_NAME \--runtime=nvidia \--gpus all \--shm-size=16GB \-e NIM_MODEL_NAME=/model-repo \-e NIM_SERVED_MODEL_NAME \-v $MODEL_REPO:/model-repo \-u $(id -u) \-p 8000:8000 \$IMG_NAME