Model-free NIM 基础使用方法

无需为每个模型单独构建专属容器镜像，即可运行任意受支持的模型。

默认情况下，NIM 容器内置一份模型 manifest，用于指定要服务的模型。而在 Model-free（model-free） 模式下，你可以将一个通用的 NIM 容器指向任意受支持的模型，例如 Modelscope 仓库、S3 存储桶或本地目录。NIM 会在启动时自动生成 manifest 并服务该模型。

Model-free NIM 适用于以下场景：

灵活的单镜像部署：一个容器镜像即可通过安全审查，并服务任意受支持的模型。
零日（Day-0）模型支持：无需等待模型专属 NIM 容器，即可服务新发布的模型。
自定义与微调模型：提供与推理后端完全兼容的调参列表，允许用户灵活的自定义性能。

注意： 无论模型托管在何处，如果其架构不受容器内推理后端（SGLang 或 vLLM）支持，则 NIM 同样无法支持该模型。本容器使用 SGLang 后端，因此自动生成的 profile 描述以 sglang- 为前缀。

下文示例统一使用环境变量 NIM_LLM_IMAGE 表示Model-free NIM 容器镜像：

export NIM_LLM_IMAGE=io.chancloud.com/cnd-enterprise/nim-base-container/sglang-model-free-nim:1.0.1

配置模型

可通过 以下任一方式 指定模型。如果两者都提供，则后端 CLI 位置参数优先。

方式一：`NIM_MODEL_PATH` 环境变量

使用 NIM_MODEL_PATH 在运行时将容器指向目标模型：

docker run --gpus=all \
  -e NIM_MODEL_PATH=modelscope://deepseek-ai/DeepSeek-V4-Flash \
  -e MODELSCOPE_API_TOKEN=<your-token> \
  -p 8000:8000 \
  ${NIM_LLM_IMAGE}

方式二：后端 CLI 位置参数

使用后端位置参数在运行时传入模型路径。该透传方式对 SGLang 和 vLLM 后端均适用；profile 描述会根据所运行的镜像加上 sglang- 或 vllm- 前缀。

docker run --gpus=all \
  -e MODELSCOPE_API_TOKEN=<your-token> \
  -p 8000:8000 \
  ${NIM_LLM_IMAGE} \
  modelscope://deepseek-ai/DeepSeek-V4-Flash

支持的模型来源

下表列出Model-free NIM 支持的模型来源，以及所需的 URI 前缀和示例。

前缀	来源	示例
`hf://`	Hugging Face Hub	`hf://meta-llama/Llama-3.1-8B-Instruct`
`ngc://`	NVIDIA NGC	`ngc://nim/meta/llama-3.3-70b-instruct:hf`
`s3://`	AWS S3 / S3 兼容存储	`s3://my-bucket/my-org/my-model`
`modelscope://`	ModelScope Hub	`modelscope://LLM-Research/Llama-3.2-1B-Instruct:d3e...`
`gs://`	Google Cloud Storage	`gs://my-bucket/my-org/my-model`
(绝对路径)	本地目录	`/mnt/models/my-llama`

配置部署选项

Model-free NIM 会为张量并行（TP）、流水线并行（PP）和 LoRA 的组合生成对应的 profile。可通过 以下任一方式 选择部署配置；如果两者都提供，则后端 CLI 参数优先。

方式一：`NIM_MODEL_PROFILE` 环境变量

先运行 list-model-profiles 查看可用 profile，然后选择其一：

docker run --gpus=all \
  -e NIM_MODEL_PATH=modelscope://deepseek-ai/DeepSeek-V4-Flash \
  -e NIM_MODEL_PROFILE=sglang-bf16-tp2-pp1 \
  -e MODELSCOPE_API_TOKEN=<your-token> \
  -p 8000:8000 \
  ${NIM_LLM_IMAGE}

方式二：后端 CLI 参数（透传）

使用后端 CLI 参数在传入模型路径的同时附加运行时选项。NIM 透传机制与参数名称在 SGLang 和 vLLM 后端上保持一致。以下示例设置张量并行：

docker run --gpus=all \
  -e MODELSCOPE_API_TOKEN=<your-token> \
  -p 8000:8000 \
  ${NIM_LLM_IMAGE} \
  modelscope://deepseek-ai/DeepSeek-V4-Flash \
  --tensor-parallel-size 2

SGLang 和 vLLM 后端均支持以下参数：

参数	用途	默认值
`--tensor-parallel-size`	GPU 数量	1
`--pipeline-parallel-size`	节点数量	1
`--enable-lora`	启用 LoRA adapter 支持	关闭

注意： 请在所选镜像上运行 list-model-profiles，以确认其生成的是 sglang-* 还是 vllm-* profile。

列出 Profile

使用 list-model-profiles 命令查看为指定模型生成的 profile：

docker run --gpus=all \
  -e NIM_MODEL_PATH=modelscope://deepseek-ai/DeepSeek-V4-Flash \
  -e MODELSCOPE_API_TOKEN=<your-token> \
  ${NIM_LLM_IMAGE} \
  list-model-profiles

S3 专用环境变量

变量	是否必需	用途
`AWS_ACCESS_KEY_ID`	是	AWS access key
`AWS_SECRET_ACCESS_KEY`	是	AWS secret key
`AWS_REGION` 或 `AWS_DEFAULT_REGION`	是	AWS region（如 `us-east-1`）
`AWS_ENDPOINT_URL`	仅 S3 兼容存储	自定义 endpoint（如 MinIO 的 `http://localhost:9000`）
`AWS_S3_USE_PATH_STYLE`	仅 S3 兼容存储	设为 `true` 以使用 path-style 端点（MinIO 等）

离线（Air-Gap）部署

Model-free NIM 在离线环境中的行为取决于 NIM_MODEL_PATH 的取值类型。

本地路径（`/abs/path/to/model`）

NIM 直接读取模型目录，无需任何网络访问，不会重新生成 manifest，也不需要任何凭据。这是最简单的离线部署方式——只需预先准备好模型目录并挂载进容器即可。

远程 URI（`ngc://`、`hf://`、`s3://` 等）

NIM 会在首次部署时根据 URI 生成运行时 manifest，并自动在容器内部的缓存目录（NIM_CACHE_PATH）中保存一份副本。在后续重启时——包括严格的离线环境中——NIM 会在同一缓存卷中找到已缓存的 manifest 并 直接复用，无需任何对外网络或鉴权调用，也不需要额外的环境变量。

由此可实现以下离线重新部署流程：

首次部署（联网环境）：携带凭据和远程 URI 运行容器。NIM 下载模型、生成 manifest，并在 NIM_CACHE_PATH 中保存副本。
传输：确保 NIM 缓存位于可在 Pod 重启后保留的 PVC 或持久卷上，或将缓存目录传输到离线环境。
重新部署（离线环境）：挂载同一缓存卷。NIM 找到已缓存的 manifest 并跳过重新生成，无需任何凭据或网络访问。

提示： 若上游模型更新后需要强制重新生成 manifest，请在重启前从持久缓存目录中删除 nim_runtime_manifest.yaml（例如宿主机上挂载到容器内 NIM_CACHE_PATH 默认值 /opt/nim/.cache 的目录）。

示例

下面的示例演示如何使用不同的模型来源和 profile 选择方式运行Model-free NIM。

示例一：Modelscope 模型，TP=2

先查看Modelscope模型的可用 profile，然后以 TP=2 运行该模型。

设置模型路径：

export MODEL=modelscope://deepseek-ai/DeepSeek-V4-Flash

列出可用 profile：

docker run --gpus=all \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -e MODELSCOPE_API_TOKEN \
  -e NIM_MODEL_PATH=$MODEL \
  ${NIM_LLM_IMAGE} \
  list-model-profiles

示例输出：

- Compatible with system and runnable:
  - c214460d2ad7a379660126062912d2aeecaa74a3ce14ab9966cd135de49a73f2 (sglang-tp1-pp1-...)
- With LoRA support:
  - 289b03eb8c26104f416dd0a1055004e31fd9e4b0f84fe2e59754a3ceb710976a (sglang-tp1-pp1-...-lora)

通过以下任一方式启动 NIM：

使用 NIM_MODEL_PROFILE 选择 profile：

docker run --gpus=all \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -e MODELSCOPE_API_TOKEN \
  -e NIM_MODEL_PROFILE=sglang-tp1-pp1-0bdd169fb413e457cef3feda64108b085f73d16b \
  -e NIM_MODEL_PATH=$MODEL \
  -p 8000:8000 \
  ${NIM_LLM_IMAGE}

或通过 SGLang CLI 参数覆盖 profile：

docker run --gpus=all \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -e MODELSCOPE_API_TOKEN \
  -p 8000:8000 \
  ${NIM_LLM_IMAGE} \
  $MODEL --tensor-parallel-size 2

示例二：S3 托管模型，使用自动选择的默认 profile

从 S3 服务模型，并让 NIM 自动选择默认的兼容 profile。

设置模型路径：

export MODEL=s3://my-bucket/my-org/my-fine-tuned-model

携带所需的 S3 凭据启动 NIM：

docker run --gpus=all \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -e NIM_MODEL_PATH=$MODEL \
  -e AWS_ACCESS_KEY_ID=<key> \
  -e AWS_SECRET_ACCESS_KEY=<secret> \
  -e AWS_REGION=us-east-1 \
  -p 8000:8000 \
  ${NIM_LLM_IMAGE}

示例三：本地模型，指定 TP=8 profile

从本地目录服务模型，并显式选择一个 TP=8 的 profile。

设置模型路径：
```
export MODEL=/mnt/models/my-120b-model
```

使用所选 profile 启动 NIM：

docker run --gpus=all \
  -v "$LOCAL_NIM_CACHE:/opt/nim/.cache" \
  -v /mnt/models:/mnt/models \
  -e NIM_MODEL_PROFILE=<tp8_profile> \
  -e NIM_MODEL_PATH=$MODEL \
  -p 8000:8000 \
  ${NIM_LLM_IMAGE}

配置模型​

方式一：NIM_MODEL_PATH 环境变量​

方式二：后端 CLI 位置参数​

支持的模型来源​

配置部署选项​

方式一：NIM_MODEL_PROFILE 环境变量​

方式二：后端 CLI 参数（透传）​

列出 Profile​

S3 专用环境变量​

离线（Air-Gap）部署​

本地路径（/abs/path/to/model）​

远程 URI（ngc://、hf://、s3:// 等）​

示例​

示例一：Modelscope 模型，TP=2​

示例二：S3 托管模型，使用自动选择的默认 profile​

示例三：本地模型，指定 TP=8 profile​