TorchServe是PyTorch官方推荐的生产级模型服务框架，具备模型版本管理、多模型热加载、REST/gRPC双协议、worker自动扩缩容和指标监控等企业级能力，专为高并发、多模型、Kubernetes等真实生产场景设计。
TorchServe 是 PyTorch 官方推荐的生产级模型服务框架，不是“能跑就行”的玩具工具——它默认就带模型版本管理、多模型热加载、REST/gRPC 双协议、worker 自动扩缩容和指标监控。如果你只是想本地快速验证一个 .pt 模型是否能被调用，用 Flask 写三行路由更省事；但只要涉及多模型切换、并发压测、上线后不重启更新、或需要对接 Kubernetes，TorchServe 就是唯一合理选择。
为什么 torch-model-archiver 打包失败？常见报错和修复点
打包阶段出错是最常卡住新手的第一步，错误往往不提示根本原因，只报 ModuleNotFoundError 或 AttributeError: 'NoneType' object has no attribute 'forward'。
-
--model-file必须是可 import 的 Python 模块路径（如models/resnet.py），不能是 Jupyter notebook 或交互式脚本；模块内必须定义一个继承自torch.nn.Module的类，且该类名需与torch.jit.script()或torch.jit.trace()导出时一致 -
--serialized-file必须是state_dict或完整模型对象（torch.save(model, ...)），不能是torch.jit.load()后再保存的.pt文件——后者已脱离 Python 类结构，TorchServehandler 无法重建实例 - 如果模型依赖自定义层（如
DropPath）、非标准 import（如from utils import get_transforms），必须通过--extra-files显式传入，否则运行时报ImportError - handler 选错会静默失败：
image_classifier仅支持单图输入 + 分类输出；若你部署的是检测模型（输出 bbox+score），必须写自定义 handler 并在--handler中指定路径，不能硬套内置 handler
torchserve --start 启动后请求 503 或超时？检查这四件事
服务进程起来了，但 curl http://127.0.0.1:8080/predictions/xxx 返回 503 或 connection refused，问题几乎全出在 worker 初始化环节。
- 确认
--model-store路径下确实存在.mar文件，且文件名与--models参数中等号左侧一致（如mnist=mnist.mar→ 文件必须叫mnist.mar） - GPU 模式下必须加
--gpu参数，否则即使有 CUDA 设备，TorchServe默认只用 CPU worker；同时确保torch和torchvision安装的是cu121版本（不是cpu或rocm） - worker 数量不足：默认只启 1 个 worker，高并发时排队阻塞；用
--number-of-gpu（GPU 模式）或--number-of-cpu（CPU 模式）显式指定，例如--number-of-gpu 2 - 模型首次加载耗时长（尤其 LLM），
TorchServe默认 60 秒超时；启动时加--ts-config config.properties，并在配置里设model_loading_timeout=300
如何让 TorchServe 支持自定义预处理/后处理逻辑？
内置 handler（如 image_classifier）只覆盖基础场景。真实业务中，输入可能是 base64 编码的视频帧、输出要转成 COCO 格式 JSON，这时必须写自定义 handler。
- handler 是一个 Python 文件，必须实现
handle(self, data, context)方法；data是原始 HTTP 请求体（bytes或list[dict]），context包含模型名、请求 ID 等元信息 - 不要在
handle()里重复加载模型——模型已在initialize()中加载并缓存到self.model；预处理逻辑放handle()开头，后处理放结尾 - 返回值必须是
list（每个元素对应一个输入样本的结果），且元素类型只能是str、bytes或dict；返回torch.Tensor会直接报 500 - 调试时把
print()输出重定向到logs/ts_log.log（而非 stdout），否则看不到日志；线上环境建议用logging.getLogger()
模型更新不重启服务？用管理 API 动态注册/卸载
生产环境不可能每次更新都停服。TorchServe 的管理 API（默认 http://127.0.0.1:8081）提供无中断升级能力，但必须注意版本和依赖隔离。
立即学习“Python免费学习笔记（深入）”；
- 新模型打包为
model_v2.mar后，发 POST 到/models?model_name=mnist&url=../model-store/mnist_v2.mar&initial_workers=2，旧版本自动保留，新请求路由到新 worker - 卸载旧版本用 DELETE
/models/mnist?version=1.0，但前提是当前无请求正在使用该版本；否则返回 409，需先用/models/mnist?version=1.0&force=true强制卸载（可能丢请求） - 所有模型共享同一个 Python 进程，若新模型依赖不同版本的
numpy，会和旧模型冲突——TorchServe不做依赖隔离，必须统一所有模型的依赖版本 - 管理 API 默认只监听本地，生产环境务必加
--management-address 0.0.0.0:8081并配反向代理鉴权，否则暴露管理接口等于开放 root 权限
TorchServe 把底层线程池、CUDA 上下文、worker 生命周期都封装了，但 handler 里的每一行 Python 代码仍由你负责——比如用 cv2.imread() 读图不释放句柄，跑一天就会 OOM。 
