Triton不支持直接加载.pth或nn.Module，必须将模型转为TorchScript并严格按model_repository结构组织：模型名目录（小写无下划线）、纯数字版本子目录、固定名model.pt；同时需配置config.pbtxt声明输入输出shape/dtype，并挂载仓库、启用GPU、指定--model-repository路径后才能成功加载。
直接用 torch.jit.script 或 torch.jit.trace 导出的 .pt 模型，不能直接扔进 Triton 启动服务——必须按 Triton 的模型仓库（model repository）结构组织，并配好 config.pbtxt，否则会报 Model 'xxx' is not found 或 failed to load model。
模型必须转成 TorchScript 且存放在标准目录结构里
Triton 的 PyTorch backend 只认 torch.jit.ScriptModule，不支持原始 .pth 权重文件或 nn.Module 实例。你得先确保模型已调用 .eval() 和 .to("cuda")（如需 GPU），再导出：
import torch
model = MyModel().load_state_dict(torch.load("best.pth")).eval().to("cuda")
example_input = torch.randn(1, 3, 224, 224).to("cuda")
traced_model = torch.jit.trace(model, example_input)
torch.jit.save(traced_model, "model_repository/mymodel/1/model.pt")
- 目录名
mymodel是模型名，不能含下划线或大写字母（Triton 严格校验） - 子目录
1是版本号，必须是纯数字，且至少存在一个版本目录 -
model.pt必须在版本目录下，文件名固定，不可改 - 若模型含自定义算子或依赖外部 Python 逻辑（如 tokenizer），得换用
pythonbackend，而非pytorch
config.pbtxt 必须显式声明输入输出 shape 和 dtype
缺配置或写错字段，Triton 启动时不会报错，但请求一发就崩在 INVALID_ARGUMENT 或 UNKNOWN_ERROR。常见漏项：
-
max_batch_size：设为0表示禁用动态批处理；设为N则输入 tensor 第一维必须 ≤ N，且 Triton 会自动合并请求 -
dims必须和 traced 模型实际接受的输入尺寸一致，例如 ResNet50 是[3, 224, 224]，不是[1, 3, 224, 224]（batch 维由 Triton 管理） -
data_type要匹配，PyTorch 默认 float32 →TYPE_FP32，别错写成TYPE_FP64 - 若模型有多个输入，
input块要一一对应，name 必须和 traced 模型的forward参数名或torch.jit.script的签名一致
最小可用配置示例：
立即学习“Python免费学习笔记（深入）”；
name: "mymodel"
backend: "pytorch"
max_batch_size: 8
input [
{
name: "INPUT__0"
data_type: TYPE_FP32
dims: [3, 224, 224]
}
]
output [
{
name: "OUTPUT__0"
data_type: TYPE_FP32
dims: [1000]
}
]
Docker 启动 Triton 时必须挂载模型仓库且启用 GPU
只跑 docker run -it --rm nvcr.io/nvidia/tritonserver 是起不来任何模型的——它默认找 /models，但没挂载、没 GPU、没指定模型路径：
- 用
-v $(pwd)/model_repository:/models把本地模型仓库映射进去 - 加
--gpus=1（或--gpus=all），否则即使镜像带 CUDA，Triton 也会 fallback 到 CPU 模式，且 PyTorch backend 可能加载失败 - 必须加
--model-repository=/models，显式告诉 Triton 去哪读模型（哪怕路径和默认值一样） - 启动后立刻查日志：
docker logs <container_id> | grep "mymodel"</container_id>，看到successfully loaded才算真正就绪
完整命令示例：
docker run --gpus=1 --rm -p8000:8000 -p8001:8001 -p8002:8002 \ -v $(pwd)/model_repository:/models \ nvcr.io/nvidia/tritonserver:22.12-py3 \ --model-repository=/models
客户端请求必须走 Triton 的 gRPC/HTTP 协议，不能直接 torch.load
很多人卡在这步：本地用 curl http://localhost:8000/v2/health/ready 能通，但发推理请求就返回 400 Bad Request 或空响应。核心原因是：
- Triton 不暴露原始 PyTorch 接口，所有请求必须经由其定义的 API，比如 HTTP 的
/v2/models/{model_name}/infer - 输入 tensor 必须序列化为
bytes并按binary_data或fp32格式编码，不能直接传 NumPy array 字典 - 推荐用官方
tritonclient库，避免手写 JSON 出错：
import tritonclient.http as httpclient
client = httpclient.InferenceServerClient(url="localhost:8000")
inputs = httpclient.InferInput("INPUT__0", [1, 3, 224, 224], "FP32")
inputs.set_data_from_numpy(x_np.astype(np.float32), binary_data=True)
outputs = httpclient.InferRequestedOutput("OUTPUT__0", binary_data=True)
result = client.infer("mymodel", [inputs], outputs=[outputs])
注意 INPUT__0 名字必须和 config.pbtxt 里声明的一致，大小写、下划线都不能错。
最容易被忽略的是：Triton 对模型输入的内存布局（channel-first vs channel-last）、归一化方式（是否已除以 255、是否减均值除方差）完全不做预处理——这些都得在客户端做完，或在模型内部固化（比如把 transforms 写进 forward）。一旦预处理不一致，结果就全偏了，而错误日志里根本不会提示。
