mcpField
R
runpod

runpod

github.com/digitalsamba云与 DevOps2.4k901 次安装1 天前更新
代码仓库

关于 runpod

runpod 介绍如何通过 RunPod Serverless 在云端 GPU 上运行开源 AI 模型，并设置和管理相关端点。它面向使用 video_toolkit 云端工具的用户，涵盖部署、作业状态、GPU 配置和故障排查。

主要功能

  1. 01为工具创建 RunPod 模板和端点
  2. 02通过 API 提交并监控作业
  3. 03管理端点、GPU 和工作进程
  4. 04配置文件传输与 Cloudflare R2
  5. 05提供成本控制和故障排查说明

适用场景

  1. 01部署图像编辑或放大端点
  2. 02查看云 GPU 作业状态
  3. 03为端点调整 GPU 与并发设置
  4. 04排查冷启动、队列和显存错误

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/digitalsamba/claude-code-video-toolkit --skill runpod

安装后在 Claude Code 中输入/runpod确认已加载。

详细介绍

RunPod 云 GPU

通过 RunPod 无服务器服务在云 GPU 上运行开源 AI 模型。按秒计费，无最低消费。

设置

# 1. Create account at https://runpod.io
# 2. Add API key to .env
echo "RUNPOD_API_KEY=your_key_here" >> .env

# 3. Deploy any tool with --setup
uv run tools/image_edit.py --setup
uv run tools/upscale.py --setup
uv run tools/dewatermark.py --setup
uv run tools/sadtalker.py --setup
uv run tools/qwen3_tts.py --setup

每条 --setup 命令都会：

  1. 根据 Docker 镜像创建 RunPod 模板
  2. 创建配备合适 GPU 的无服务器 端点
  3. 将端点 ID 保存到 .env（例如 RUNPOD_QWEN_EDIT_ENDPOINT_ID）

可用镜像

所有镜像均在 GHCR 上公开，无需身份验证。

工具Docker 镜像GPU显存典型费用
image_editghcr.io/conalmullan/video-toolkit-qwen-edit:latestA6000/L40S48GB+~$0.05-0.15/任务
upscaleghcr.io/conalmullan/video-toolkit-realesrgan:latestRTX 3090/409024GB~$0.01-0.05/任务
dewatermarkghcr.io/conalmullan/video-toolkit-propainter:latestRTX 3090/409024GB~$0.05-0.30/任务
sadtalkerghcr.io/conalmullan/video-toolkit-sadtalker:latestRTX 409024GB~$0.05-0.15/任务
qwen3_ttsghcr.io/conalmullan/video-toolkit-qwen3-tts:latestADA 24GB24GB~$0.01-0.05/任务

每月总费用： 即使大量使用，也很少超过 $10。

工作原理

所有工具都遵循相同的模式：

Local CLI → Upload input to cloud storage → RunPod API → Poll for result → Download output
  1. 文件传输： 配置 Cloudflare R2 后，工具会使用它（R2_ACCOUNT_ID、R2_ACCESS_KEY_ID、R2_SECRET_ACCESS_KEY、R2_BUCKET_NAME）；否则会改用免费的上传服务
  2. RunPod API： 工具会调用 /run 端点，然后轮询 /status/{job_id}，直到任务完成
  3. 冷启动与热启动： 空闲后收到的第一个请求会启动工作器（约 30-90 秒）。后续请求会更快（约 5-15 秒）

端点管理

工作器
workersMin: 0    — Scale to zero when idle (no cost)
workersMax: 1    — Max concurrent jobs (increase for throughput)
idleTimeout: 5   — Seconds before worker scales down

所有端点共用的工作器总数取决于你的 RunPod 套餐。如果达到限制，请调低当前未使用端点的 workersMax。

检查端点状态

每个工具都会将其端点 ID 保存到 .env：

工具环境变量
image_editRUNPOD_QWEN_EDIT_ENDPOINT_ID
upscaleRUNPOD_UPSCALE_ENDPOINT_ID
dewatermarkRUNPOD_DEWATERMARK_ENDPOINT_ID
sadtalkerRUNPOD_SADTALKER_ENDPOINT_ID
qwen3_ttsRUNPOD_QWEN3_TTS_ENDPOINT_ID
禁用端点

如需释放工作器槽位但不删除端点，可通过 RunPod 控制面板或 GraphQL API 将 workersMax 设为 0。

RunPod API 参考

可使用以下接口以编程方式查询和管理端点。RunPod 禁用了 GraphQL 内省，因此这些字段名已经过验证，必须完全准确。

身份验证

所有 API 调用都需要 Authorization: Bearer $RUNPOD_API_KEY。

  • GraphQL： POST https://api.runpod.io/graphql
  • REST（无服务器）： https://api.runpod.ai/v2/{endpoint_id}/...
GraphQL 查询

列出所有端点：

query { myself { endpoints { id name gpuIds templateId workersMax workersMin } } }

当前支出速率：

query { myself { currentSpendPerHr spendDetails { localStoragePerHour networkStoragePerHour gpuComputePerHour } } }

列出 Pods：

query { myself { pods { id name runtime { uptimeInSeconds } machine { gpuDisplayName } desiredStatus } } }

常见错误： 字段名采用 camelCase，且必须使用完整单词——localStoragePerHour，而不是 localStoragePerHr。端点字段是 endpoints，而不是 serverlessWorkers。spending 不是字段——请使用 currentSpendPerHr 和 spendDetails。

GraphQL 修改操作

更新端点 GPU 或配置：

mutation { saveEndpoint(input: {
  id: "endpoint_id",
  name: "endpoint-name",
  templateId: "template_id",
  gpuIds: "AMPERE_24",
  workersMin: 0,
  workersMax: 1
}) { id gpuIds } }

即使只是更新，saveEndpoint 也要求提供 name 和 templateId——请先查询以获取当前值。

REST API（无服务器）
操作方法URL
提交任务POST/v2/{id}/run
检查状态GET/v2/{id}/status/{job_id}
取消任务POST/v2/{id}/cancel/{job_id}
列出待处理任务GET/v2/{id}/requests
健康状态/统计信息GET/v2/{id}/health

健康状态响应包含任务数量和工作器状态：

{
  "jobs": { "completed": 16, "failed": 1, "inProgress": 0, "inQueue": 2, "retried": 0 },
  "workers": { "idle": 0, "initializing": 1, "ready": 0, "running": 0, "throttled": 0 }
}

注意： /requests 只会返回待处理/排队中的任务。API 不提供已完成任务的历史记录——请在 RunPod Web 控制台中查看日志。

GPU 类型 ID
IDGPU显存典型费用
AMPERE_24RTX 309024GB约 $0.34/小时
ADA_24RTX 409024GB约 $0.69/小时
AMPERE_48A600048GB约 $0.76/小时
AMPERE_80A10080GB约 $1.99/小时

可用性说明： ADA_24（4090）在 RunPod 上经常受到限流或不可用。请始终为端点配置多个备用 GPU 类型（以逗号分隔），以免作业无限期卡在队列中：

gpuIds: "AMPERE_24,ADA_24"   # Try 3090 first, fall back to 4090

所有工具包工具还会强制执行 5 分钟的队列超时：如果 300 秒内没有可用 GPU，作业将自动取消，避免初始化失败循环造成持续计费。

通过 AWS CLI 使用 Cloudflare R2

R2 使用兼容 S3 的 API，但要求指定 --region auto：

AWS_ACCESS_KEY_ID="$R2_ACCESS_KEY_ID" \
AWS_SECRET_ACCESS_KEY="$R2_SECRET_ACCESS_KEY" \
aws s3api list-objects-v2 \
  --bucket "$R2_BUCKET_NAME" \
  --endpoint-url "https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com" \
  --region auto

常见错误： 忽略 --region auto 会导致 InvalidRegionName 错误。R2 有效区域：wnam、enam、weur、eeur、apac、oc、auto。

故障排查

强制拉取镜像

推送新的 Docker 镜像版本后，RunPod 可能仍会使用缓存的旧版本。要强制拉取：

  1. 将模板的 imageName 更新为使用 @sha256:DIGEST 格式
  2. 等待工作器重启
  3. 确认后恢复为 :latest 标签
冷启动过慢
  • qwen3-tts： 冷启动约 70 秒，预热后约 7 秒
  • sadtalker： 冷启动约 60 秒，预热后约 10 秒
  • image_edit： 冷启动约 90 秒，预热后约 15 秒

如果冷启动造成问题，请设置 workersMin: 1（空闲时也会产生费用）。

作业因 OOM 失败

模型需要的显存超过了 GPU 提供的容量。可选方案：

  • 使用更高规格的 GPU
  • 对于 dewatermark：调低 --resize-ratio（出于安全考虑，默认值为 0.5）
  • 对于 image_edit：调低 --steps
“No workers available”

你已达到套餐的并发工作器上限。可以：

  • 等待正在运行的作业完成
  • 对不使用的端点设置 workersMax=0
  • 升级 RunPod 套餐

Docker 镜像

所有 Dockerfile 都位于 docker/runpod-*/。镜像以 runpod/pytorch 为基础镜像，以便在不同工具之间共享镜像层。

在 RunPod 上构建（从 Apple Silicon Mac）：

docker buildx build --platform linux/amd64 -t ghcr.io/conalmullan/video-toolkit-<name>:latest docker/runpod-<name>/
docker push ghcr.io/conalmullan/video-toolkit-<name>:latest

GHCR 软件包默认设为私有，你必须手动将其设为公开，RunPod 才能拉取。前往 GitHub > Packages > Package Settings > Change Visibility。

成本优化

  • 将所有端点的 workersMin: 0（缩减至零）
  • 只部署当前需要的端点
  • 使用 workersMax=0 停用空闲端点，无需删除
  • 用 Qwen3-TTS 制作配音，成本远低于 ElevenLabs
  • 在 RunPod 控制面板查看用量和账单

评论

支持 Markdown