runpod/runpod-python

Runpod | Python 库

这是一个轻量且文档完善的 Python SDK，让您可以从自己的代码中与 Runpod 的云平台进行交互（GPU 驱动的“pods”和无服务器端点）。它封装了 Runpod REST v2 API，提供了一个用于构建无服务器 worker（自定义模型推理 API）的小型框架，并包含用于 pod 生命周期管理的辅助工具。

功能介绍

领域	能力
无服务器 worker SDK	编写一个处理任务的 Python 函数，然后使用 `runpod.serverless.start({"handler": my_func})` 启动它。SDK 会处理健康检查、选用的 GPU/卷预热缓存，并可在本地执行以进行调试。
REST v2 封装	`runpod.Endpoint(id)` 提供一个对象，包含 `.run()` (异步) 与 `.run_sync()` (同步) 方法来调用已部署的端点。
Pod 管理	诸如 `runpod.create_pod()`、`runpod.get_pods()`、`runpod.stop_pod()`、`runpod.resume_pod()`、`runpod.terminate_pod()` 等函数，让您能以编程方式启动、查询与控制 GPU 或 CPU pod。
API 密钥处理	通过 `runpod.api_key` 设置全局密钥或针对个别端点设置；优先级已记录且具备线程安全性。
实用辅助工具	`VolumeCache` 用于预热网络挂载的模型缓存；健康检查装饰器可在 worker 启动前验证 GPU、磁盘空间等。

快速入门（无服务器 worker）

# my_worker.py
import runpod

def is_even(job):
    n = job["input"]["number"]
    if not isinstance(n, int):
        return {"error": "need an integer"}
    return n % 2 == 0

runpod.serverless.start({"handler": is_even})

将此脚本作为容器的入口点（Docker CMD 或 Runpod 模板），该函数将被公开为自定义 API 端点。

快速入门（调用现有端点）

import runpod
runpod.api_key = "YOUR_KEY"

ep = runpod.Endpoint("ENDPOINT_ID")
result = ep.run_sync({"text": "hello"})
print(result)   # → 模型输出或状态字典

Pod 生命周期示例

import runpod
runpod.api_key = "YOUR_KEY"

# 创建一个 GPU pod
pod = runpod.create_pod(name="demo", image="runpod/stack", gpu_type="NVIDIA GeForce RTX 4090")
print(pod["id"])

# 稍后…
runpod.stop_pod(pod["id"])   # 暂停
runpod.resume_pod(pod["id"]) # 恢复
runpod.terminate_pod(pod["id"]) # 删除

安装

# 稳定版本
pip install runpod   # 或: uv add runpod

# 最新开发版本
pip install git+https://github.com/runpod/runpod-python.git

需要 Python 3.10+。

重要设计点

健康检查 – 装饰器 (@runpod.serverless.register_fitness_check) 在 worker 启动时执行一次；失败会中止程序，以便编排器重新启动健康的实例。
网络卷预热缓存 – VolumeCache 在冷启动时将远程卷（例如 HuggingFace 模型缓存）复制到本地存储，并在退出时同步回传，将数 GB 的下载量转变为每个端点一次性的成本。
线程安全的端点对象 – 每个 Endpoint 存储其自己的 API 密钥，使来自多个线程的并发请求变得安全。
功能完整的 Pod 创建 – 支持 GPU 与 CPU pod、自定义 Docker 参数、卷挂载、放置限制与扩展参数。

下一步该做什么？

文档 – https://docs.runpod.io/serverless-ai/custom-apis 以及仓库中的 docs/ 文件夹。
示例 – 查看 examples/ 目录以获取现成的 worker 与 pod 脚本。
社区 – 加入 Discord（链接在 README 中）以获取帮助、功能请求与公告。

总结： runpod Python 套件是您的代码与 Runpod GPU 云之间官方的生产级桥梁，让您只需几行 Python 代码即可启动 pod、调用模型端点或发布自定义无服务器推理 API。