runpod-flash

Runpod SDK 应用（Flash）

对于明确要求 Dockerfile/模板项目的请求，请使用 runpod-build-template。除非用户选择代码优先工作流，否则不要用 Flash 替代该交付内容。

在本地编写 Python，使用 rp flash dev 在远程 Runpod GPU/CPU 上运行，然后 使用 rp flash deploy 发布。Flash 是 runpod 软件包（2.0）的一部分：一套 SDK、一个 rp CLI、一次登录。独立的 runpod-flash 软件包已弃用，并且在 2026 年 10 月 29 日之后不再修复。

rp --help 和 rp flash <command> --help 是命令范围的权威依据。 本技能介绍心智模型、决策规则，以及帮助输出中未提及的注意事项。认定某条命令或参数不可用之前，请先通过 pip show runpod 确认已安装的版本。

这个项目使用的是哪个 SDK？

编写代码前先检查。两种 API 不能混用。

你看到的内容	项目使用的是	操作
import runpod、runpod.App(...)、@app.queue、rp flash ...	Runpod SDK 2.0	本文件 + reference/
from runpod_flash import Endpoint、@Endpoint(...)、flash dev、依赖项中的 runpod-flash	旧版 runpod-flash	要维护它，请参阅 reference/runpod-flash-legacy.md；要迁移它，请参阅 reference/migrate-from-runpod-flash.md
新项目	Runpod SDK 2.0	从下文开始

新代码请使用 SDK。对于现有的 runpod-flash 项目，请提出迁移建议，并先检查其已知差异；不要静默迁移。

如果 SDK 路径因 SDK 错误而失败，runpod-flash 是备用方案：例如，回溯信息指向 runpod/apps/ 内部、工作进程在你的函数运行前就崩溃，或者相同代码在 runpod-flash 上可以正常工作。先升级 runpod；检查修复并切换备用方案的步骤见 reference/runpod-flash-legacy.md。

任何多步骤操作都应先查看完整示例。 Flash 已用于端到端流程： 03 variant B (whisper endpoint)、 07 (network-volume handoff) 和 08 (fine-tune → serve)；完整索引见 runpod/golden-paths/README.md。可运行的单文件应用位于 examples/。

按需阅读：

需求	阅读内容
安装、rp login、rp flash init、所有 rp 命令	reference/setup-and-cli.md
装饰器参数、调用方式、Queue/Api/Endpoint 客户端、卷、Model、Secret、GPU 和 CPU 名称	reference/api.md
实践模式：选择模型、预热模型加载、CPU→GPU 流水线、扇出、任务、原始 HTTP	reference/patterns.md
将 runpod-flash 项目迁移到 SDK	reference/migrate-from-runpod-flash.md
按原样维护 runpod-flash 项目	reference/runpod-flash-legacy.md

快速开始：uv add "runpod>=2.0.0"（或 pip install "runpod>=2.0.0"）→ rp login（或 export RUNPOD_API_KEY=...） → rp flash init my-app → cd my-app && rp flash dev main.py。

应用模型

import runpod

app = runpod.App("my-app")                     # names the group of resources

@app.queue(gpu="4090", dependencies=["torch"]) # queue-based serverless endpoint
def infer(x: list[float]):
    import torch
    return {"sum": torch.tensor(x, device="cuda").sum().item()}

@runpod.local_entrypoint                       # runs on YOUR machine
def main():
    print(infer.remote([1.0, 2.0, 3.0]))       # runs on a Runpod worker

装饰器	创建	适用场景
函数上的 @app.queue(...)	自动扩缩容的队列型端点	请求/响应推理、批处理任务
类上的 @app.api(...)	负载均衡端点，提供路由（@runpod.get/@runpod.post，在 @runpod.init 中设置）	HTTP 服务、多路由 API、仅加载一次的模型状态
函数上的 @app.task(...)	每次调用创建一个临时 Pod，函数返回时终止	训练、微调、长时间运行的任务

队列或任务句柄的调用方式：fn.remote(...)（阻塞）、await fn.remote.aio(...)、 fn.spawn(...)（返回 Job；对于任务则返回 TaskJob）、fn.stream(...)（仅适用于队列生成器函数）、fn.local(...)（在你的机器上运行）。API 类按路由调用：MyApi.post("/path", body)。

开发与部署

• rp flash dev main.py — 迭代开发。 创建临时端点（dev-<app>-<resource>-<hash>）， 在你的机器上运行 @runpod.local_entrypoint，将工作器的 print 输出流式传输到 终端，并在每次保存文件后重新运行。按 Ctrl-C 会删除端点。没有本地 HTTP 服务；你需要通过入口点运行代码。
• rp flash dev main.py --once — 运行一次入口点，然后清理并退出；失败时返回非零退出码。 这是 CI 的冒烟测试，也是用于验证“迁移后的代码是否可运行”的测试。
• rp flash deploy — 发布。 构建构件（≤1,500 MB；内置 GPU 镜像不包含 torch），并在 default 环境中创建持久端点（其他环境使用 --env NAME）。重新运行即可更新。--build-only 仅打包而不部署，是一种低成本的离线检查，可验证发现和依赖解析是否正常。

开发和部署运行的是同一份模块源代码，因此模块级导入、常量和辅助函数在两者中的 行为相同。部署会打包项目目录，但开发会话只会传送模块源代码，因此使用 rp flash dev 时，请将应用放在一个文件中。

自主开发循环

开发会话会长时间运行。请遵循三条规则：

• 在后台运行，并关闭 stdin（< /dev/null）。没有 stdin 时，每次保存文件都会重新运行入口点，因此无需按 Enter。
• 将输出保存到日志文件并查看。工作器的 print 输出、回溯、✗ remote execution failed: ... 以及每次运行的 ✓ done in ... / ✗ failed in ... 行都会写入日志。
• 使用 kill（SIGTERM）或 SIGINT 停止会话，以便删除端点，并确认日志以 cleaning up N deleted 结尾。第二次发送信号会停止等待正在运行的入口点，并直接开始清理。kill -9 会跳过清理。如果只需运行一次，请优先使用 --once；它会自行清理。

rp flash dev main.py < /dev/null > /tmp/rp-dev.log 2>&1 &
DEV=$!
# poll the log (bounded) for the run result: "✓ done in ..." or "✗ failed in ..."
for i in $(seq 1 120); do grep -qE "✓ done in|✗ failed in" /tmp/rp-dev.log && break; sleep 3; done
tail -40 /tmp/rp-dev.log
# edit main.py and save -> the session re-scans, refreshes endpoints, re-runs main()
# (each run appends a new result line; read the last one)
kill $DEV; wait $DEV; tail -3 /tmp/rp-dev.log   # expect "cleaning up N deleted"

如果只需检查一次，rp flash dev main.py --once 更简单，也会自行清理。如果会话退出时未清理，请使用 runpodctl serverless list 列出遗留端点，并按 ID 删除本次会话创建的 dev-<app>-... 端点。

选择资源类型

默认使用 Runpod 运行时镜像上的纯 Python：dependencies=[...] 和 system_dependencies=[...] 会在工作器上安装依赖，因此无需 Dockerfile，而且大型 HuggingFace 模型也可以直接放在代码中（参见 reference/patterns.md）。

• 任意装饰器上的 image="org/image:tag" 都会让你的函数在该镜像上运行；镜像需要 Python 3，而不需要 Serverless 处理程序。可用于系统库或特定 CUDA 栈。 registry_auth= 用于指定已保存的私有镜像凭据（rp registry add）。
• 预构建的推理服务镜像（vLLM、worker-comfyui）已实现 Serverless 处理程序，不属于 SDK 应用。请使用 runpodctl 或 runpod-mcp 部署，并通过 runpod.Endpoint("ENDPOINT_ID") 调用。
• 按 ID 指定现有端点：runpod.Endpoint("ENDPOINT_ID").run_sync({...})。
• 另一个已部署应用中的资源：runpod.Queue(app="media", name="transcribe") / runpod.Api(app="media", name="inference")。

注意事项

1. 队列参数和结果必须可序列化为 JSON。 开发和部署中的队列作业都是纯 JSON。非 JSON 参数在开发环境中会报错 arguments must be json-serializable，在已部署的端点上则会触发 Python 自身的 JSON TypeError。传递 URL 或 base64，而不是对象。整数值的浮点数可能会变成整数（1.0 → 1），因此请显式转换数值输入（torch.tensor(x, dtype=torch.float32)）。
2. 开发环境中每个应用只能有一个文件。 开发会话只会发送模块的源代码，因此，同级本地模块的导入在部署环境中可以成功，在开发环境中却会失败。对于开发会话，请将辅助代码放在同一个文件中，或放入可安装的包中。
3. 不要在模块作用域中执行阻塞操作。 SDK 会在本地以及每个工作进程上导入你的模块，以发现资源。请将重量级导入（torch）和操作放在函数内；使用 runpod.is_local() 保护仅在本地运行的代码。
4. gpu= 和 cpu= 不能同时指定（gpu and cpu are mutually exclusive）。GPU 字符串可以简写（"4090"、"H100"），也可以传入可接受 GPU 的列表。
5. 默认值为 workers=(0, 3)（runpod-flash 曾为 (0, 1)）。当成本或并发很重要时，请显式设置。idle_timeout 的单位是秒（默认值为 60）。
6. 传入 GPU 列表时，自动切换 GPU 要求 workers 的最大值 ≥ 5。
7. 请求载荷上限为 10 MB。 大型输出请通过卷或对象存储 URL 返回。
8. 卷的生命周期长于其他所有资源。 开发会话和 rp flash undeploy 会删除端点，而不会删除它们创建的 NetworkVolume，因此卷仍会产生费用。队列和 API 资源会将一个卷挂载到 /runpod-volume；请在远程函数内读取 vol.path，不要在导入时读取。请通过 VolumeCache 加载模型权重，而不要直接从挂载点加载 （reference/patterns.md）。
9. 任务会持续计费，直到返回。 .spawn() 启动的任务如果从未调用 wait() 或 cancel()，即使脚本退出，也会继续运行其 Pod。
10. 原生 CUDA 库也要放入 dependencies，例如 faster-whisper 需要 nvidia-cublas-cu12 和 nvidia-cudnn-cu12，否则会静默回退到 CPU。
11. 开发会话和任务要求本地 Python 版本为 3.10–3.14。 它们会发送由你的解释器 pickle 的代码，因此工作进程会使用与你本地相同的版本。其他版本在部署时会回退到 3.12，并发出警告；rp flash deploy --python-version 可显式设置版本。
12. 设置了 RUNPOD_API_KEY 时，它优先于 rp login。 过期的已导出密钥会导致 401 错误，即使保存的登录凭据有效。使用 runpodctl user 检查，然后执行 unset RUNPOD_API_KEY 或导出有效密钥。
13. torch 系列软件包由 GPU 镜像提供；切勿锁定其版本。 无论你是否将 torch、torchvision、torchaudio 和 triton 列出，或由依赖项（peft、accelerate、sentence-transformers）引入，构建都会将它们排除在制品之外，也会排除 torch 唯一需要的 wheel。GPU 工作进程使用镜像中的构建版本（torch 2.9.1+cu128），因此这些软件包的版本锁定会被忽略。在混合使用 CPU 和 GPU 资源的应用中，如果 CPU 资源的依赖项需要 torch，冷启动时会安装它；请为此预留足够的 container_disk_gb 空间（适用时构建会发出警告）。
14. 开发会话运行时镜像自带的 runpod。 部署会将你本地的软件包打包进去，但 rp flash dev 工作进程会导入内置镜像中预装的 runpod。如果开发工作进程的回溯中，某个 runpod. 名称触发 AttributeError，说明镜像版本落后于你的 SDK；rp flash deploy 会运行你安装的版本。
15. 按应用和环境进行清理： rp flash undeploy --app APP --env default -y 会删除一个环境的端点；rp flash app delete APP --yes 会删除所有环境（不带 --yes 时会提示确认，没有终端时则会中止）。然后删除不再需要的卷。
16. 队列和 API 名称至少需要 3 个字符才能部署。 默认名称是函数名或类名，而且开发会话不会检查名称，因此 class SD 可以通过 rp flash dev，却会在 rp flash deploy 时失败。请重命名，或传入 name=。
17. 每个端点都会获得你的账户 API 密钥。 部署和开发都会将 RUNPOD_API_KEY 放入每个端点的模板环境变量中，无论其代码是否会调用其他资源，因此任何能够读取该模板的人都能读取密钥。

资源

• 设置与 CLI：reference/setup-and-cli.md · API：reference/api.md · 模式：reference/patterns.md · 示例：examples/
• SDK 源码和上游示例：https://github.com/runpod/runpod-python（`examples/apps/`）
• 文档：https://docs.runpod.io/sdk/overview · CLI：https://docs.runpod.io/sdk/cli · 迁移：https://docs.runpod.io/sdk/migrate-from-flash