Runpod Serverless 从 0 到 1：本地跑通 → 镜像构建 → Endpoint 部署 → 在线压测（保姆级踩坑版）
- 0. 你最终会得到什么
- 1) 准备工作（别跳过这一步）
- 2) 建开发环境：虚拟环境 + 安装 runpod SDK
- 3) 写 Worker：handler.py（最小可用模板）
- 4) 本地测试：先把“逻辑”跑通再上云
- 5) Docker 镜像：最小 Dockerfile（能跑就行）
- 关键：构建必须指定 linux/amd64
- 6) 控制台部署：New Endpoint → Import from Docker Registry
- 7) 在线测试：控制台直接发请求（注意冷启动）
- 8) 一张图看懂全流程（建议收藏）
- 9) 高频踩坑清单（你大概率会遇到）
- 10) 进阶路线（不从 0 写更快）
你要的不是“看懂文档”，而是一次性跑通闭环：本地能测、镜像能推、Endpoint 能跑、请求能回。本文把 Runpod 的 Serverless Worker 流程按「最短可交付路径」重写一遍，并把新手最容易踩的坑提前标红。(Runpod)
0. 你最终会得到什么
- 一个可运行的
handler.py（Serverless Worker 入口）(Runpod) - 一个最小可用的
Dockerfile（可在 Runpod 上启动）(Runpod) - 一个已部署的 Serverless Endpoint（Queue 模式），可在控制台直接发 JSON 请求返回结果(Runpod)
1) 准备工作（别跳过这一步）
你需要：
- Runpod 账号（能进 Serverless 控制台）
- 本机：Python 3.x + Docker（能
docker build&docker push）
✅ 强烈建议：如果你是Apple Silicon（M1/M2/M3/M4）或其它 ARM 机器，后面构建镜像必须加
--platform linux/amd64，否则上云直接翻车。(Runpod)
2) 建开发环境：虚拟环境 + 安装 runpod SDK
python3 -m venv venv# macOS / Linuxsourcevenv/bin/activate# Windows# venv\Scripts\activatepipinstallrunpod3) 写 Worker：handler.py（最小可用模板）
Runpod 的核心就是一个handler(event)：从event["input"]取参数，处理完返回结果。(Runpod)
工程建议（很重要）：如果你要跑 LLM/扩散模型，模型加载放在文件顶部（进程启动时加载），不要写进
handler()，否则每个请求都重复加载，冷启动直接爆炸。(Runpod)
handler.py：
importtimeimportrunpoddefhandler(event):""" event: dict event["input"]: 你的请求体 input """print("Worker Start")input_data=event.get("input",{})prompt=input_data.get("prompt","")seconds=int(input_data.get("seconds",0))print(f"Received prompt:{prompt}")print(f"Sleeping for{seconds}seconds...")time.sleep(seconds)return{"output":prompt}if__name__=="__main__":runpod.serverless.start({"handler":handler})我这里把返回值改成
{"output": ...}这种结构，后续接 API / 前端更稳（可扩展错误字段、元数据字段）。
)
