TrnRT部署完全指南:Docker镜像+离线编译缓存+一键serve,serving主机零编译

原创2026-11-11 17:48:011,754 阅读

TrnRT部署完全指南:Docker镜像+离线编译缓存+一键serve,serving主机零编译

TrnRT 部署只需三件事:构建一个 Docker 镜像、在普通 CPU 主机上预生成离线编译缓存、再在 trn2.48xlarge 上执行一条 serve 命令。TrnRT 是 RunAnywhere 推出的开源 LLM 推理引擎,面向 AWS Trainium2 芯片,以 NKI megakernels 运行 GLM-5.3-Flash,支持 100 万 token 上下文和 OpenAI 兼容 API——而它最大的工程亮点是:serving 主机上默认零编译,所有图(graph)都提前编译好,启动即加载。

部署前先搞清楚:需要哪些资源

TrnRT 的部署模型是"编译与推理分离":编译发生在任意 x86_64 主机上,推理发生在 Trainium2 上。

角色 要求
Serving 主机 1 台 trn2.48xlarge:16 颗 Trainium2 芯片(每颗 96 GiB HBM)、192 vCPU、2 TB 内存
编译主机 任意带 Docker 的 x86_64 主机,不需要 NeuronCore,内存越大编译越快
模型 zai-org/GLM-5.3-Flash(320B MoE、18B 激活、FP8),检查点约 328 GB
软件 Docker;镜像内含 Neuron SDK 2.32(neuronx-cc 2.27)与 Python 3.13

两台主机可以合并,但编译步骤只需要 CPU 和内存,用便宜实例更划算。主机准备细节(AMI、neuron-ls 检查、磁盘规划)见 docs/AWS.md 和 docs/DEPLOY.md。

第一步:构建 TrnRT 的 Docker 镜像

镜像基于 AWS Neuron 官方的 vLLM 推理基础镜像(按 digest 固定版本),在此之上升级 transformers 到支持 glm5_next 架构的版本,然后安装 TrnRT 本体。

git clone https://gitcode.com/gh_mirrors/tr/trnrt && cd trnrt
docker build -f docker/Dockerfile \
  --build-arg TRNRT_VERSION=$(python3 -c 'import trnrt; print(trnrt.__version__)') \
  --build-arg TRNRT_REVISION=$(git rev-parse HEAD) -t trnrt .

构建过程会调用 docker/check_image.py 逐项校验镜像里的每个 Neuron 组件和版本,任何一项不达标构建直接失败。镜像约 26.7 GB,建议编译主机和 serving 主机各建一份,省得来回传输 8 GB 的基础镜像下载。Dockerfile 完整内容见 docker/Dockerfile。

第二步:在 CPU 主机上构建离线编译缓存

这是"零编译"的关键。一张编译图只依赖权重的形状、dtype 和每层 MoE 的少量打包决策值,与权重数值无关——所以缓存只需从检查点的 config.json、tokenizer 文件和 safetensors 头部(几 MB)就能构建,无需下载 328 GB 权重,也不需要 GPU/NeuronCore。

整个缓存流水线由 trnrt/compile/farm.py 驱动,共五个子命令,每步都是独立的 docker run --rm:

  1. compile shapes:把检查点的 config.json、tokenizer JSON 和全部 safetensors 头部拉进 $OUT/shapes,作为权重的"替身";
  2. compile decisions:用 HTTP range 读取每个 MoE 层的少量张量,算出加载期决策(capture 拒绝猜测这些值);
  3. compile capture:在 meta 设备上捕获服务器要运行的全部图(32 个 tensor-parallel rank),产物是 HLO 文件和缓存键元数据;-- 之后的参数必须与 serve 的引擎参数完全一致;
  4. compile compile:neuronx-cc 对每张图做真正的编译,按主机可用内存并行调度(每个进程默认预留 30 GB),OOM 被杀的任务自动单独重试一次;
  5. compile strip:剥掉 NEFF 里的调试信息——1M token 配置下运行时会在主机内存中多份持有 NEFF,不 strip 的话两个引擎的 NEFF 根本放不下。
OUT=/data/trnrt REV=eb9eb208eb0d988989d07a6a12d0fdeb5f52574a
mkdir -p $OUT/nki $OUT/work
trnrt() { docker run --rm -e HF_TOKEN -v $OUT:$OUT \
  -v $OUT/nki:/var/tmp/nki-intermediate-cache trnrt "$@"; }
trnrt compile shapes zai-org/GLM-5.3-Flash --revision $REV --out $OUT
trnrt compile decisions --model zai-org/GLM-5.3-Flash --revision $REV --out $OUT
trnrt compile capture --out $OUT -- --model $OUT/shapes
trnrt compile compile --out $OUT --work-root $OUT/work
trnrt compile strip --out $OUT

💡 $OUT/nki 存 NKI 内核二进制,capture 和 compile 必须看到同一个目录,跨机拆分步骤时记得把它连同缓存一起拷走。编译耗时以小时计,提前规划。

第三步:在 trn2.48xlarge 上一键 serve

把 $OUT/cache 和 $OUT/nki 拷到 serving 主机,下载与缓存同版本的检查点(编译和 serve 必须用同一 revision,否则缓存键对不上),然后一条命令启动:

hf download zai-org/GLM-5.3-Flash \
  --revision eb9eb208eb0d988989d07a6a12d0fdeb5f52574a --local-dir /models/GLM-5.3-Flash

docker run --rm --privileged --network host --ipc=host \
  -v /data/trnrt/cache:/cache \
  -v /data/trnrt/nki:/var/tmp/nki-intermediate-cache \
  -v /models/GLM-5.3-Flash:/model \
  -e NEURON_LIBTORCH_CACHE_ROOT=/cache \
  trnrt serve --model /model --port 8000

serve(入口在 trnrt/main.py)会依次拉起两个引擎——分别占用逻辑 NeuronCore 0–31 和 32–63,监听 8001/8002 端口——每个引擎加载权重并从缓存预热全部编译图,前一个通过 /health 后下一个才启动;最后会话亲和路由器在 --port(默认 8000)上应答。

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="unused")
reply = client.chat.completions.create(
    model="glm",
    messages=[{"role": "user", "content": "Write a haiku about Trainium."}],
    extra_body={"session_id": "my-session"},  # 会话固定在一个引擎的前缀缓存上
)
print(reply.choices[0].message.content)

为什么 serving 主机能做到零编译?

引擎启动时环境变量 NEURON_LIBTORCH_ASSERT_CACHE_HIT=1 会让 libtorch-neuronx-lite 在缓存未命中时直接报错停机,并明确指出缺失的缓存键——而不是像常规部署那样现场调 neuronx-cc 编译(每张图要几分钟到几小时)。serve 随即停掉所有引擎并以非零状态退出。

这个"失败快"的设计把部署问题压缩成一张排查清单:

症状 原因 处理
启动即报 cache miss 缓存构建时的引擎参数、模型 revision、TrnRT 版本或 Neuron SDK 与本次不一致;或 NEURON_LIBTORCH_CACHE_ROOT 没指对 用相同参数重新 capture;确认挂载路径
确实想现场编译 需要显式开启 加 --allow-compile,并给足 --startup-timeout(默认 3600 s)
引擎拒绝启动,退出码 4 其他进程占用 Neuron 设备,或主机 4 MiB 连续内存块不足(刚下完检查点,页缓存占满) sync; echo 1 > /proc/sys/vm/drop_caches 后重启
超时仍起不来 单引擎启动超过 --startup-timeout 调大超时或检查日志

配置预设(默认 batch 12,--preset batch8,mtp-* 推测解码预设)的完整参数表在 docs/CONFIGURATION.md;API 端点、session_id、工具调用和状态码见 docs/API.md。

快速核对清单

  • ✅ 镜像构建通过 check_image.py 的 Neuron 组件校验
  • ✅ 编译缓存五步全部完成,$OUT/nki 与 $OUT/cache 已拷到 serving 主机
  • ✅ 检查点 revision 与缓存构建时一致
  • ✅ NEURON_LIBTORCH_CACHE_ROOT=/cache 已设置
  • ✅ --ipc=host 保留在 docker run 里(tensor-parallel 通信依赖 64 MiB 共享段)
  • ✅ GET /health 返回 200,随后即可用任意 OpenAI 客户端发请求

从 git clone 到第一个请求,TrnRT 的部署路径只有"镜像 + 缓存 + 一条 serve"三段,而真正耗时的离线编译被彻底移出 serving 主机——这正是大规模 Trainium 集群上可复制的部署方式。深入阅读可参考 docs/DEPLOY.md、docs/ARCHITECTURE.md 与基准测试数据 docs/RESULTS.md。

登录后查看全文
trnrt