standalone架构设计：ttm-r3-npu如何做到整体拷贝到任意主机即可运行-育师

standalone架构设计：ttm-r3-npu如何做到整体拷贝到任意主机即可运行

【免费下载链接】ttm-r3-npu项目地址: https://ai.gitcode.com/atlasleong/ttm-r3-npu

ttm-r3-npu 是一个采用 standalone 架构交付的开源项目，它将 IBM 的 TTM-R3 时序预测模型（TinyTimeMixer 系列第 3 代）完整适配到华为昇腾 NPU 上。项目最亮眼的设计是：整个delivery/目录自包含全部模型权重、建模代码与运行时辅助模块，整体拷贝到任意一台具备昇腾 NPU 运行环境的主机后，无需联网、无需重配路径，直接执行python3 inference.py即可完成推理。本文将从架构设计角度，拆解 ttm-r3-npu 如何实现"拷贝即用"的 standalone 交付。

什么是 standalone 架构：一次拷贝、处处运行的模型交付思路

传统的模型交付往往"散落一地"：模型权重放在模型仓库，建模代码靠pip install现场安装，辅助脚本散落在任务目录里。换一台机器就要重新下载权重、重新装包、重新对齐路径，任何一步断网或版本漂移都会让推理直接失败。

standalone 架构的核心思路是自包含（self-contained）：把运行所需的一切——权重、代码、配置、依赖清单——全部装进同一个目录。ttm-r3-npu 正是按这个思路组织交付物的：

delivery/ ├── inference.py # 最终推理入口（torch_npu 在 npu:0 执行） ├── _ttm_common.py # delivery 本地辅助模块（路径全部相对 delivery/ 解析） ├── requirements.txt # 非平台依赖锁定（torch/torch_npu 由昇腾镜像提供） ├── README.md # 交付说明 ├── model/ # 固定 revision 模型快照（config.json + model.safetensors） ├── vendor/tinytimemixer/ # granite-tsfm 0.3.8 抽取的配置 + 建模模块 └── assets/ # 推理产物（.npy）与工作流示意图

delivery/inference.py不读取、不 import、也不解析父级任务目录中的任何文件，这是 standalone 架构最关键的约定——只要这个目录是完整的，它就一定能在目标主机上独立运行。

上图记录了 Model Agent 从目录审计、模型解析到验收的完整适配工作流，体现了 standalone 交付在端到端链路中的自洽性。

三大支柱：ttm-r3-npu 实现"拷贝即用"的架构秘诀

支柱一：自带固定版本模型快照，运行期零联网

模型以快照形式固定在本仓库中，绝不依赖运行时联网下载：

快照位于delivery/model/，包含config.json与model.safetensors（5,729,424 字节，sha256 已固定），以及offline_dependencies.json；
源模型 revision 被不可变地锁定为aca5d4956c59726b320c1562a6eaebb7fd7ec9b9，记录在model/offline_dependencies.json中；
加载时使用local_files_only=True，只从本地delivery/model/读取权重，运行期零网络访问，天然适配离线与内网环境。

model.safetensors内保存了 468 个 tensor、约 141 万个 float32 参数，且同时包含trend_forecaster.*与residual_forecaster.*权重，因此加载器类为分解预测变体TinyTimeMixerForDecomposedPrediction，输入形状(batch, 512, 1)、输出点预测形状(batch, 30, 1)。

支柱二：vendored 建模代码，仓库即依赖

很多项目"换机器跑不起来"，都是栽在建模代码安装这一步。ttm-r3-npu 的解法是vendoring（代码内置）：从 granite-tsfm v0.3.8（commitd473fc3d800c400230a3d8f5192fbdc6255a02f5）中抽取配置与建模模块，vendor 到delivery/vendor/tinytimemixer/，并固定导入路径：

from vendor.tinytimemixer import TinyTimeMixerForDecomposedPrediction

这样目标主机上不再需要pip install granite-tsfm，也不会因装到不同版本导致行为漂移。配合delivery/requirements.txt中锁定的 transformers、numpy、safetensors 等非平台依赖，整个运行环境是可复现的。

支柱三：路径相对 delivery/ 解析，与工作目录彻底解耦

拷贝迁移最大的隐形杀手是路径假设——很多脚本写死了"从当前目录找模型"或"从上级目录找配置"，一旦换了目录立刻崩溃。ttm-r3-npu 的做法是：所有路径都基于脚本自身所在目录解析。

在delivery/_ttm_common.py中：

DELIVERY_DIR = os.path.dirname(os.path.abspath(__file__)) MODEL_DIR = os.path.join(DELIVERY_DIR, "model")

模型快照model/、辅助模块_ttm_common.py、资源目录assets/全部由DELIVERY_DIR推导，与进程工作目录（cwd）完全无关。因此无论在哪个目录下执行python3 inference.py，路径都不会"迷路"——这正是"整体拷贝到任意主机即可运行"的技术根基。

整体拷贝到任意主机的快速运行步骤

第一步：准备昇腾 NPU 运行环境

目标主机需已安装 CANN 与平台固定的 torch / torch_npu（二者由昇腾 worker 镜像提供，不在delivery/requirements.txt中列出）：

source /usr/local/Ascend/ascend-toolkit/set_env.sh python3 -m venv .ttm-r3-venv . .ttm-r3-venv/bin/activate pip install --ignore-installed --no-deps -r delivery/requirements.txt

第二步：整体拷贝 delivery/ 目录

把delivery/目录原样复制到目标主机的任意位置即可。standalone 结构保证目录内没有任何指向外部任务目录的引用。

第三步：一键执行推理入口

方式 A（任务根目录，与执行计划一致）：

python3 delivery/inference.py

方式 B（standalone 风格，拷贝后在目标目录内执行）：

cd delivery python3 inference.py

两种方式殊途同归，这正是 standalone 架构的验收标准。

强制 NPU 推理：禁止 CPU 回退的架构约束

"拷贝到任意主机就能跑"不等于"随便跑"。ttm-r3-npu 面向昇腾 NPU 设计，对设备有硬性约束：

入口显式定位逻辑设备npu:0，通过import torch_npu注册 NPU 后端；
若torch.npu.is_available()为假，脚本打印CPU_FALLBACK=true并以非零码退出，禁止 CPU 回退冒充 NPU 结果；
前向调用纯 torch 原生算子（conv1d reflect-pad、median/Tukey 重加权、mixer 等），无任何torch.cuda/.cuda()硬编码，按x.device/pred.device传递设备。

上图为真实运行时的npu-smi设备快照：910B4-1芯片健康状态 OK，推理进程（python3.11）稳定绑定在 NPU 上运行。

真实运行证据：拷贝迁移后的完整推理输出

任何"拷贝即用"的架构都要用真实运行来证明。ttm-r3-npu 在 2026-08-15 的最终交付运行（exit_code=0，总耗时 23.48 秒）中，记录了完整的机器契约标记：

INPUT_DEVICE=npu:0 MODEL_DEVICE=npu:0 OUTPUT_DEVICE=npu:0 CPU_FALLBACK=false OUTPUT_FINITE=true FORECAST=[-1.1438840627670288, -1.3002103567123413, ...] forecast_shape=(1, 30, 1) INFER_MEDIAN_MS=31.364211 EXIT_CODE=0

关键实测数据：

精度：NPU 对比 CPU 的max_abs_error≈5e-4、mean_abs_error≈2.2e-4，远低于 0.01 阈值，离散输出完全一致；
确定性：固定种子 42 下重复两次前向，max_abs_diff_across_forwards=0.0；
性能：同步计时中位数约 31~32ms，10 次重复的 p90 约 33.8ms；
无 NaN/Inf：OUTPUT_FINITE=true，落盘回读RELOAD_*校验全部通过。

上图是模型最终适配验收结果：输入(1, 512, 1)、输出点预测(1, 30, 1)、设备全部落在npu:0，完整验证了 standalone 交付在真实 NPU 上的闭环。