jetson-llm-serve

Jetson LLM Serve

编码自 Jetson AI Lab GenAI tutorial：在 Orin JetPack 7.2 / L4T r39+ 上，使用上游 vLLM 0.20+（vllm/vllm-openai:latest）；在较旧的 Orin 上，选择 NVIDIA-AI-IOT 预构建的 vLLM 容器；在 Thor 上，使用上游 vLLM 0.20+ 或经过验证的原生 vLLM 0.20+，如果需要 SGLang，则使用 NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3，SGLang 0.5.5.post2）。设置 MAXN，确保 Hugging Face 凭据和缓存可用，然后启动兼容 OpenAI 的服务。LLM 和 VLM 均适用。

目的

提供适用于 Jetson 的 LLM 或 VLM 服务部署方案，使用 vLLM 或 SGLang，包含运行时路径、启动命令、端点和验证步骤。

适用场景

• “在 Jetson 上运行 / 部署 / 托管此模型。”
• “启动一个可供 Open WebUI / 我的应用调用的 vLLM 服务。”
• jetson-inference-mem-tune 生成启动标志后，用户希望实际启动服务。

对于仅询问部署方案的问题，请根据本文档作答，不要启动容器。只有当用户要求检查这台设备或执行部署时，才运行实时预检。

前提条件

• 在 Jetson 主机上运行，或使用可通过 Docker 访问 Jetson GPU 运行时的 Shell。
• 确认目标 Jetson 代际（thor 或 orin）以及模型标识符或本地检查点路径。
• 仅当模型受限或私有时才使用 HF_TOKEN；公开模型应省略令牌环境变量。
• 如果不确定可用内存余量或启动标志，请先使用 jetson-inference-mem-tune。

说明

对于部署方案相关问题，请提供完整的启动方案，而不是尝试将 jetson-llm-serve 作为工具调用。完整答案包括：

• 适用于 Jetson 的运行时路径：Thor 上的上游 vLLM 0.20+（vllm/vllm-openai:latest）或 NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3，SGLang 0.5.5.post2）；较旧 Orin 上的 NVIDIA-AI-IOT vLLM 容器；或 Orin JetPack 7.2 / L4T r39+ 上的上游 vLLM 0.20+。
• 用户指定的模型检查点 / Hugging Face 仓库。
• docker run + 服务命令示例，包含 --host 0.0.0.0 --port 8000。
• 兼容 OpenAI 的端点：http://<jetson-ip>:8000/v1。
• 验证步骤，例如 curl http://localhost:8000/v1/models。

对于 VLM 相关问题，请明确说明 VLM 使用与 LLM 相同的 vLLM 服务流程，只是视觉语言检查点不同。回答 VLM 相关提示时，不要省略 vLLM 或 Jetson 容器。

步骤 1 — 选择运行时路径（按 Jetson 系列）

在 Thor 上使用上游 vLLM 0.20+（vllm/vllm-openai:latest，或经验证的原生 vLLM 0.20+ 安装）。在 Orin JetPack 7.2 / L4T r39+ 上，使用上游 vLLM 0.20+（vllm/vllm-openai:latest）。在较旧的 Orin 版本上，使用 NVIDIA-AI-IOT 预构建 vLLM 镜像（软件包），因为它包含适用于该 JetPack 的正确 CUDA / cuDNN / TensorRT 软件栈。当用户要求使用 SGLang、RAG、工具调用或可编程服务时，在 Thor 上使用 NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3，SGLang 0.5.5.post2）；除非某个 JetPack 匹配版本明确支持，否则不要在 Orin 上推荐原生上游 SGLang。

Jetson 系列	运行时路径
Thor（T5000、T4000）	上游 vLLM 0.20+（vllm/vllm-openai:latest）或 NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3，SGLang 0.5.5.post2）
AGX Orin / Orin NX / Nano	Orin JetPack 7.2 / L4T r39+：上游 vLLM 0.20+（vllm/vllm-openai:latest）；较旧的 Orin：ghcr.io/nvidia-ai-iot/vllm:latest-jetson-orin

检测芯片所属时代以选择镜像标签：

1. 加载检测脚本，使导出的变量在当前 Shell 中保留：

   . skills/jetson-diagnostic/scripts/detect_jetson.sh
   

2. 检查 JETSON_GENERATION（thor 或 orin），并从上表中选择相应的运行时路径。
3. 使用 JETSON_PRODUCT_LINE 进一步细分，例如 thor-agx 或 orin-nano；JETSON_SKU 保留为旧版标识符。

如果需要在调用方 Shell 中使用导出的变量，请勿运行 bash skills/jetson-diagnostic/scripts/detect_jetson.sh；使用 bash 运行会启用子 Shell。

步骤 2 — 设置 MAXN 电源模式

sudo nvpmodel -m 0 && sudo jetson_clocks

只有在用户明确要求受功耗限制的运行时才跳过此步骤；否则，基准测试和服务数据将不一致。

步骤 3 — 运行服务

在 Thor 上使用 vLLM 时，使用上游 vLLM 0.20+（vllm/vllm-openai:latest）或经验证的原生 vLLM 0.20+ 安装：

docker run --rm -it --runtime nvidia --network host --ipc host --name vllm \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN="$HF_TOKEN" \
  vllm/vllm-openai:latest \
  vllm serve <hf-repo-id> \
    --host 0.0.0.0 --port 8000 \
    --max-model-len 8192 \
    --gpu-memory-utilization 0.75 \
    --tensor-parallel-size 1

在 Orin JetPack 7.2 / L4T r39+ 上，使用上游 vLLM 0.20+（vllm/vllm-openai:latest）。在较旧的 Orin 版本上，使用 NVIDIA-AI-IOT 容器：

docker run --rm -it --runtime nvidia --network host --name vllm \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN="$HF_TOKEN" \
  ghcr.io/nvidia-ai-iot/vllm:latest-jetson-orin \
  vllm serve <hf-repo-id> \
    --host 0.0.0.0 --port 8000 \
    --max-model-len 4096 \
    --gpu-memory-utilization 0.85 \
    --tensor-parallel-size 1

仅当使用受限/私有 Hugging Face 模型时才需要 HF_TOKEN；对于不需要 Hub 身份验证的公开模型，请省略 -e HF_TOKEN="$HF_TOKEN" 这一行。在共享系统上，将 HF_TOKEN 作为环境变量传递可能会通过 Docker 检查输出、进程元数据或日志暴露该令牌。请尽可能使用权限范围最窄的令牌，在共享容器使用后轮换/撤销令牌，并在部署环境支持时使用挂载的凭据文件或 Docker secret。

等待 Application startup complete.。服务地址为 http://0.0.0.0:8000/v1。

在 Thor 上运行 SGLang 时，请使用 NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3）；该镜像打包了 SGLang 0.5.5.post2，并注明支持 Jetson Thor。不要根据较早的 SGLang 预发布版结果来判断 Thor 对 SGLang 的支持情况：

docker run --rm -it --runtime nvidia --network host --ipc host --name sglang \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN="$HF_TOKEN" \
  nvcr.io/nvidia/sglang:26.01-py3 \
  python3 -m sglang.launch_server \
    --model-path <hf-repo-id> \
    --host 0.0.0.0 \
    --port 8000 \
    --mem-fraction-static 0.60 \
    --max-running-requests 8

当用户需要 RAG/工具调用工作流、结构化生成或 SGLang 特定的调度功能时，请使用 SGLang。对于普通的高吞吐量 OpenAI 兼容服务，除非用户要求使用 SGLang，否则优先使用 vLLM。

适合 SKU 的默认值

参数	Orin Nano / NX	AGX Orin / Thor
--max-model-len	4096	8192
--gpu-memory-utilization	0.85	0.85
--tensor-parallel-size	1	1

如果服务在启动时发生 OOM，请将 --gpu-memory-utilization 降低 0.05 后重新启动（或运行 jetson-inference-mem-tune，获取针对工作负载的建议）。

量化偏好（比运行时更重要）

对于 vLLM 和 SGLang，请按 Jetson 系列选择检查点格式：

Jetson 系列	首选	可接受的备选方案
Thor	模型／运行时支持时优先选择 NVFP4	W4A16
Orin Nano / NX	W4A16	AWQ 或 GPTQ 4-bit
AGX Orin	W4A16	AWQ 或 GPTQ 4-bit

对于 llama.cpp 和 Ollama，请改用 GGUF 模型量化名称：Orin 和 Thor 均推荐 INT4 / Q4_K_M GGUF；如果内存紧张，请选择更小的 INT4 GGUF 模型。不要将 GGUF Q4_K_M 称为 W4A16/AWQ/GPTQ 模型。对于支持 NVFP4 的运行时，Thor 优先选择并针对 NVFP4 进行调优。

VLM 模式

VLM 使用与 LLM 相同的流程：相同的容器、相同的 vllm serve 调用，只是使用不同的视觉语言检查点。容器负责图像预处理。对于 VLM 专用的浏览器 UI，请使用 live-vlm-webui 容器；对于两者通用的聊天 UI，请使用指向 http://<jetson-ip>:8000/v1 的 Open WebUI。

不要捏造设备容量

提供服务配置方案时，不要编造 RAM 总量、可用内存值、模型大小、JetPack 版本或 SKU／变体名称。如果容量很重要，请运行实时预检（允许执行时），或转交给 jetson-inference-mem-tune / jetson-memory-audit。如果没有实时数据，请说明数值未知，并提供保守的默认值，而不是引用虚构的数字。

预检清单（Agent 应在运行步骤 3 前核实）

• 设备是 Jetson（/proc/device-tree/model 中包含 NVIDIA Jetson）。
• nvpmodel -q 报告已识别的最高性能模式：MAXN 或 MAXN_*，例如 MAXN_SUPER。除非用户明确确认带功耗数值的模式是该设备预期使用的基准测试模式，否则应将其报告为警告。
• 在 Thor 上，启动前检查 MIG 是否已启用（nvidia-smi -L 和 nvidia-smi mig -lgi）。如果已启用 MIG，请警告 vLLM/SGLang 可能只能看到 MIG 切片，或看不到 CUDA 设备。
• 在启用 MIG 或存在显示／摄像头资源争用的 Thor 上，使用 sudo lsof /dev/nvidia* 检查 GPU 用户。显示管理器、Xorg/GNOME 或 nvargus-daemon 可能占用 GPU 设备文件；未经用户明确批准，不要停止服务或更改 MIG 模式。
• 没有名为 vllm 的容器正在运行（docker ps --format '{{.Names}}'）；如果有，请先运行 docker rm -f vllm。
• Docker 已公开 NVIDIA 运行时（docker info | grep -i 'runtimes.*nvidia'），或者 GPU 启用的容器可以运行 nvidia-smi。
• ~/.cache/huggingface 已存在；如果模型受访问控制，请设置 HF_TOKEN。

限制

• 此技能提供服务命令和预检；不会对已部署的服务进行基准测试。
• latest 等容器标签是可变的。对于发布或合规部署，请固定摘要，并将其记录在部署说明中。
• vLLM 和 SGLang 的内存限制仍取决于模型架构、量化方式、上下文长度和并发请求数。如果命令因内存不足而失败，或需要了解内存余量，请使用 jetson-inference-mem-tune。
• Thor 上的 vLLM 要求使用上游 vLLM 0.20 或更新版本。较旧的上游 vLLM 镜像可能无法正确支持 Thor / SM 11.0。
• Thor 上的 SGLang 应使用 NVIDIA SGLang 26.01 或更新版本的发行说明中明确列出 Jetson Thor 支持的版本。NVIDIA SGLang 26.01 包含 SGLang 0.5.5.post2。
• 在 Thor 上，MIG、桌面显示或摄像头服务可能导致容器无法访问完整 GPU。此技能只能检测并发出警告；禁用 MIG 或停止 gdm3、nvargus-daemon 等服务，必须先获得用户明确批准。
• 只有当 Thor 上的主机原生 vLLM/SGLang 安装已在目标 JetPack 上通过验证时，才应使用该安装。

后续操作

• 使用 jetson-llm-benchmark 实际测量已部署的服务。
• 使用 jetson-speculative-decoding，在上面的 vllm serve 命令后追加 --speculative-config '{...}'，以添加 EAGLE-3／草稿模型推测解码。
• 如果服务发生 OOM 或受内存限制，请使用 jetson-inference-mem-tune。

来源

Jetson AI Lab — Jetson 上的生成式 AI 入门：如何运行 LLM 和 VLM 和 NVIDIA-AI-IOT GHCR 软件包。