你要的不是“看懂文档”，而是一次性跑通闭环：本地能测、镜像能推、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 / Linux
source venv/bin/activate
# Windows
# venv\Scripts\activate

pip install runpod

---

3) 写 Worker：handler.py（最小可用模板）

Runpod 的核心就是一个 handler(event)：从 event["input"] 取参数，处理完返回结果。(Runpod)

工程建议（很重要）：如果你要跑 LLM/扩散模型，模型加载放在文件顶部（进程启动时加载），不要写进 handler()，否则每个请求都重复加载，冷启动直接爆炸。(Runpod)

handler.py：

import time
import runpod

def handler(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 / 前端更稳（可扩展错误字段、元数据字段）。

---

4) 本地测试：先把“逻辑”跑通再上云

官方也强调：先本地测，省时间省钱。(Runpod)

创建 test_input.json：

{
  "input": {
    "prompt": "Hey there!",
    "seconds": 1
  }
}

运行：

python handler.py

你应该能看到控制台打印（Worker Start / Received prompt…），并在本地完成一次 job。

---

5) Docker 镜像：最小 Dockerfile（能跑就行）

Dockerfile：

FROM python:3.10-slim

WORKDIR /app

RUN pip install --no-cache-dir runpod

COPY handler.py /app/handler.py

CMD ["python3", "-u", "handler.py"]

这就是 Runpod 官方范式：基础镜像 + 安装 runpod SDK + 拷贝 handler + CMD 启动。(Runpod)

关键：构建必须指定 linux/amd64

docker build --platform linux/amd64 -t YOUR_USERNAME/serverless-test:latest .

这条不是“建议”，是硬要求，尤其你在 ARM 机器上构建时。(Runpod)

推送到 Docker Hub：

docker login
docker push YOUR_USERNAME/serverless-test:latest

---

6) 控制台部署：New Endpoint → Import from Docker Registry

在 Serverless 控制台创建 Endpoint：(Runpod)

• New Endpoint
• Import from Docker Registry
• Container Image：docker.io/YOUR_USERNAME/serverless-test:latest
• Endpoint Type：建议按你业务选择（多数场景用 Queue 更稳，便于削峰）
• GPU：按模型需求选（纯 CPU 也可以先跑通）

点击 Deploy 完成。

---

7) 在线测试：控制台直接发请求（注意冷启动）

部署后在 Endpoint 详情页：

• 找到 Requests
• 输入 JSON：{"input": {"prompt": "Hello World"}}
• 点击 Run

第一次可能要等一会儿（冷启动 + 拉镜像 + 启 worker），完成后状态会变成 COMPLETED 并返回 output。(Runpod)

---

8) 一张图看懂全流程（建议收藏）

---

9) 高频踩坑清单（你大概率会遇到）

1. 忘了 --platform linux/amd64

• 表现：Endpoint 拉起来但 worker 崩 / 拉镜像失败 / 运行异常
• 解决：重新 build + push（尤其 ARM 设备）(Runpod)

2. 把模型加载写进 handler()

• 表现：每个请求都超慢，冷启动极长，甚至超时
• 解决：模型加载移到全局（脚本启动时加载一次）(Runpod)

3. 镜像太大 / 依赖乱装

• 表现：冷启动时间离谱、拉取慢、成本上升
• 解决：精简依赖、加 .dockerignore、依赖尽量 pin 版本（工程常识）

---

10) 进阶路线（不从 0 写更快）

• 不想手搓？可以直接用官方模板/示例仓库改造，然后从“构建镜像 → 部署 Endpoint”开始走。(Runpod)
• 想更省事：也可以走 GitHub 集成，让 Runpod 自动拉代码、构建镜像、存入其 registry，再部署。(Runpod)