jetson-inference-mem-tune

Jetson 推理内存调优

根据 Jetson SKU／变体和用户的工作负载，推荐推理运行时及需要传入的特定内存相关标志。不包含量化方案选择——这部分由 model-benchmarking 技能负责——但会指出各运行时能够高效处理的最低精度。

用途

将实时的 jetson-memory-audit 快照转换为 Jetson 上 LLM／VLM 服务的运行时和启动标志建议。用户需要适配模型、降低 OOM 风险或切换到内存占用更低的服务栈时使用。

适用场景

• “在 Orin Nano 8 GB 上运行 7B 模型，我应该使用哪种服务栈？”
• “vLLM 出现 OOM 了，--gpu-memory-utilization 和 --max-model-len 应该设为多少？”
• “同一个模型，内存占用更低——我能从 vLLM 切换到 llama.cpp 吗？”
• jetson-memory-audit 显示某个模型服务是 NvMap／PSS 占用最高的进程之后。

前置条件

• 首先获取目标 Jetson 当前的 jetson-memory-audit/scripts/audit.sh JSON 快照。
• 了解预期工作负载：llm-server、vlm-server、embedding 或 rag。
• 如果用户指定了目标空闲内存，请通过 --target-mb 传入；否则让脚本使用 SKU 默认值。

可用脚本

脚本	用途	参数
scripts/recommend.py	读取审计 JSON，并输出运行时及启动标志建议。	--audit PATH、--runtime、--workload、--target-mb、--human。

如果你的 Agent 运行时支持 run_script，请调用 run_script("scripts/recommend.py", ["--audit", "/tmp/audit.json", "--runtime", "auto", "--workload", "llm-server"])，并总结返回的 JSON。否则，从仓库根目录使用 python3 运行脚本。

操作说明

1. 运行 jetson-memory-audit/scripts/audit.sh，获取设备基线信息。
2. 运行 scripts/recommend.py --audit /tmp/audit.json --runtime auto --workload llm-server --target-mb 6000，获取运行时和标志建议的 JSON。
3. Agent 展示建议的运行时和准确的 CLI 标志。用户（或外层 Agent）使用这些标志启动／重启服务。
4. 重新运行审计以验证结果。

预期工作流

针对具体提示使用 scripts/recommend.py，并依据它输出的 JSON 作答。如果无法直接执行，请以 python3 {baseDir}/scripts/recommend.py ... 运行。

• 对于 vLLM OOM 相关提示，使用 --runtime vllm --workload llm-server 运行，并从 launch_flags 中给出具体的 --gpu-memory-utilization=<0.x> 和 --max-model-len=<number> 数值。
• 对于“内存占用最低”或 Orin Nano 8 GB 相关提示，使用 --runtime auto --workload llm-server 运行；优先采用 JSON 中的运行时。如果选择了 llama-cpp，请明确说明 GGUF／4-bit 之间的权衡。
• 对于 SGLang 相关提示，使用 --runtime sglang 运行，并引用 --mem-fraction-static、--max-running-requests 以及任何上下文／KV 缓存说明。
• 对于“从 vLLM 切换到 llama.cpp”相关提示，使用 --runtime llama-cpp 运行，并引用 -ngl、-c 和 --no-mmap。

限制

• 建议的新鲜度取决于审计 JSON。停止服务、更改电源模式或重启模型服务后，请重新运行 jetson-memory-audit。
• 脚本根据 SKU 默认值和审计总量估算内存压力；具体模型的 KV 缓存、量化和 tokenizer 行为仍可能需要通过基准测试确定。
• 此技能只输出标志，不会启动、停止或重启模型服务。

错误处理

• 退出码 2：无法读取或解析审计 JSON，或其中不包含有效的数值内存字段。请用户重新运行 jetson-memory-audit/scripts/audit.sh。
• 退出码 3：请求的运行时或工作负载不受支持。请使用 scripts/recommend.py --help 中列出的 --runtime 和 --workload 值重新运行。
• launch_flags 为空或缺失：不要编造备用标志。报告脚本失败，并要求用户提供新的审计结果或使用受支持的运行时。

recommend.py 的输出契约

{
  "sku": "orin-nx",
  "variant": "orin-nx-16gb",
  "mem_total_gb": 16,
  "runtime": "vllm",
  "rationale": "Highest throughput at this memory budget given continuous batching + paged attention.",
  "launch_flags": [
    "--gpu-memory-utilization=0.55",
    "--max-model-len=4096",
    "--max-num-seqs=8",
    "--enable-prefix-caching"
  ],
  "alternatives": [
    { "runtime": "llama-cpp", "rationale": "Lower memory floor with GGUF Q4_K_M.", "launch_flags": ["-ngl 28", "-c 4096", "--no-mmap"] }
  ],
  "notes": ["Lower --gpu-memory-utilization further if you also run a small VLM alongside."]
}

涵盖的运行时

运行时	最适合的场景	关键内存参数	首选安装路径
llama.cpp	预算最紧；GGUF；Orin Nano 级设备	-ngl、-c、--mlock、--no-mmap	ghcr.io/nvidia-ai-iot/llama_cpp:latest-jetson-{orin,thor}
vLLM	通过连续批处理实现高吞吐量服务	--gpu-memory-utilization、--max-model-len、--max-num-seqs、--enable-prefix-caching	Thor 和 Orin JetPack 7.2 / L4T r39+：上游 vLLM 0.20+（vllm/vllm-openai）容器或经验证的原生 vLLM 0.20+。较旧的 Orin：NVIDIA-AI-IOT 镜像
SGLang	可编程工作流（RAG、工具使用、结构化输出）	--mem-fraction-static、--mem-fraction-dynamic、--max-running-requests	Thor：NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3、SGLang 0.5.5.post2）。Orin：与 JetPack 匹配的环境
TensorRT Edge-LLM	NVIDIA 调优的生产服务	按 SKU 构建配置文件；paged-KV；KV 复用	目标 JetPack 对应的供应商文档

Orin JetPack 7.2 / L4T r39+ 支持上游 vLLM 0.20+。对于较旧的 Orin 版本，优先使用 NVIDIA-AI-IOT 预构建的 vLLM 镜像（如有），因为这些镜像附带与 JetPack 匹配的 CUDA/cuDNN/TensorRT 技术栈。对于 Thor，优先使用上游 vLLM 0.20+（vllm/vllm-openai）或经验证的原生 vLLM 0.20+ 安装；对于 SGLang，请使用 NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3、SGLang 0.5.5.post2），或明确列出 Jetson Thor 支持的更新版 NVIDIA SGLang 发行说明。不要强行在 Thor 上使用仅适用于 Orin 的 Jetson 容器路径，也不要假定 Orin 支持原生上游 SGLang。

量化建议

使用特定于运行时的量化名称。vLLM 和 SGLang 通常使用 Hugging Face 检查点，例如 W4A16、AWQ、GPTQ、FP16 或 NVFP4。llama.cpp 和 Ollama 使用 GGUF 模型，因此应推荐 INT4/Q4_K_M 风格的 GGUF。

运行时系列	Jetson 系列	首选方案	备用方案
vLLM / SGLang	Thor	模型/运行时支持时使用 NVFP4	W4A16
vLLM / SGLang	Orin Nano / NX	W4A16	AWQ 或 GPTQ 4-bit
vLLM / SGLang	AGX Orin	W4A16	AWQ 或 GPTQ 4-bit
llama.cpp / Ollama	Orin 和 Thor	GGUF INT4 / Q4_K_M	内存紧张时使用更小的 INT4 GGUF 模型

不要将 GGUF Q4_K_M 描述为 W4A16/AWQ/GPTQ。除非输出包含 quant 字段，否则不要比较 Thor NVFP4 与 Orin W4A16 的结果。

运行时命令指南

以内存参数为准的来源是 recommend.py，然后将其 launch_flags 放入对应的服务命令中。请将命令指南保留在此技能中，而不要拆分成单独的小型参考文件，这样 Agent 就能一次性读取完整的指令集。

对于运行 JetPack 7.2 / L4T r39+ 的 Orin 上的 vLLM，请使用上游 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-model-id-or-local-path> \
    --host 0.0.0.0 \
    --port 8000 \
    --gpu-memory-utilization 0.60 \
    --max-model-len 4096 \
    --max-num-seqs 8 \
    --enable-prefix-caching

对于 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-model-id-or-local-path> \
    --host 0.0.0.0 \
    --port 8000 \
    --gpu-memory-utilization 0.75 \
    --max-model-len 8192 \
    --max-num-seqs 32 \
    --enable-prefix-caching

Thor 上的 vLLM 说明：不要根据 vLLM 0.20 之前的结果判断 Thor 支持情况；上游 vLLM 从 vLLM 0.20+ 开始支持 Thor。

对于 Thor 上的 SGLang，请使用 NVIDIA SGLang 26.01（nvcr.io/nvidia/sglang:26.01-py3）。NVIDIA SGLang 26.01 包含 SGLang 0.5.5.post2，并明确列出对 Jetson Thor 的支持。不要根据较早的预发布版 SGLang 结果判断 Thor 支持情况。除非更新版 NVIDIA SGLang 的发行说明表明已修复这些已知问题，否则不要在 Thor 上推荐 gpt-oss 或 FP8 路径。

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-model-id-or-local-path> \
    --host 0.0.0.0 \
    --port 8000 \
    --mem-fraction-static 0.60 \
    --max-running-requests 8

对于 llama.cpp，请使用 NVIDIA-AI-IOT llama.cpp 镜像（如果可用），或使用与 JetPack 匹配的构建版本中的 llama-server 二进制文件。在 Orin 和 Thor 上都从 GGUF INT4 / Q4_K_M 开始；如果审计显示内存紧张，则选择更小的 INT4 GGUF 模型。

docker run --rm -it --runtime nvidia --network host --name llama-cpp \
  -v "$PWD/models:/models:ro" \
  ghcr.io/nvidia-ai-iot/llama_cpp:latest-jetson-<orin-or-thor> \
  llama-server \
    -m /models/<model>.gguf \
    --host 0.0.0.0 \
    --port 8000 \
    -ngl 28 \
    -c 4096 \
    --no-mmap \
    --flash-attn

流程（脚本已实现此流程）

1. 选择能满足用户所需功能（连续批处理？结构化生成？CPU 卸载？）的最轻量运行时。
2. 选择满足用户准确性要求的最低精度（参见 model-benchmarking 技能）。
3. 调整运行时的内存参数（vLLM 从 gpu-memory-utilization 开始，llama.cpp 从 n-gpu-layers 和 ctx-size 开始），找到能维持目标吞吐量的最小内存占用。
4. 使用 jetson-memory-audit 重新测量。

安全

只读。此技能不会启动、停止或重启模型服务。它只会输出参数；由用户（或外部编排 Agent）负责调用运行时。