serverless-deploy

Serverless 部署

你可以将任意可部署的源转化为可正常工作的、由队列支持的 Serverless 端点，并通过一个真实任务验证其可用性，同时让用户清楚了解现在创建了什么以及会产生哪些费用。步骤始终不变：读取源，确定引擎和硬件，进行配置，预热，使用一个真实任务进行冒烟测试，交付 URL 和 curl，并说明哪些内容会产生费用。只有当用户明确表示这是一次性测试，或要求清理时，才进行拆除。

有两个决定由你自行作出，无需用户告知：引擎系列（适用于此模态和模型格式的工作器镜像）和配置路径（将权重烘焙进镜像、启动时下载，或暂存到网络卷；每种方式的冷启动成本都不同）。根据模型的真实元数据选择硬件规格，绝不猜测。当此模态存在多个合适的工作器时，优先选择体积最小、经过最多验证，且适合进行冒烟测试的镜像。庞大的镜像会让首个任务经历数分钟的冷启动，而冒烟测试的目的是验证整个流程，不是追求最高质量。如果用户的需求意味着要使用更重型的引擎，请说明其中的权衡。创建端点会产生费用：创建之前说明 GPU 类型的每小时费用，并记住冒烟测试任务也会产生费用。

对于代码优先的 Python 方案（在项目中编写端点函数，并使用 Runpod 的 Python 开发循环 runpod-flash 进行迭代），此 MCP 专用工具包没有相应路径。请如实说明，不要临时拼凑方案。此技能通过 MCP 工具，将现有源（Hub 仓库、容器镜像、ComfyUI 工作流、Hub 发布版本）部署到端点。

必备能力

以下能力均已命名；此服务器上提供各项能力的工具见下方工具绑定。此技能会在创建之前读取目录，并且只创建用户要求部署的内容。

• 读取 GPU 目录、价格、实时库存、各数据中心的可用性，以及有可用容量的 CUDA 版本：用于规格选择和库存查询（将规格计算委托给 discovery）。
• 浏览 Hub 工作器目录及其发布配置，以查找预构建工作器或社区模板，并读取其硬件和环境变量架构。
• 直接将 Hub 发布版本部署为端点：单次调用的 Hub 路径。
• 创建模板（镜像、磁盘、端口、环境变量、注册表、挂载）：可复用的工作器预设。
• 创建 Serverless 端点（GPU 池、工作器最小/最大数量、自动扩缩器、数据中心、网络卷）。
• 固定 GPU 类型／设置每个工作器的 GPU 数量：使用 gpu.count 和池及 excludedTypes 进行选择；set-endpoint-gpus 会构建排除列表并保留其他设置。
• 读取端点健康状态并列出工作器：用于预热和就绪状态检查，同时结合工作器日志判断冷启动与崩溃循环（陷入崩溃循环的容器仍可能报告 RUNNING 或 INITIALIZING）。
• 提交任务并等待完成：冒烟测试（先调用 run-endpoint，然后针对任务 ID 调用 get-job-status wait:300000，直到任务进入终态；仅在端点已预热且任务快速时使用 runsync-endpoint，因为其结果只保留一分钟）。
• 在可使用相应工具时读取工作器日志：用于查找模型加载／崩溃证据。若无法使用该工具，endpoint-health 和 list-endpoint-workers 可提供工作器健康状态计数，帮助缩小原因范围，但仅凭这些信息无法确认是否陷入崩溃循环。
• 删除端点、模板和任何网络卷：拆除所有创建的内容。

阶段 0 — 识别来源并选择引擎（主动判断）

阅读用户提供的来源并进行分类。引擎系列取决于模态和模型格式，而非默认选项。绝不要在 vLLM 或 ComfyUI worker 上处理非文本生成任务。

来源 / 模态	正确的引擎系列	Worker 镜像类型
文本生成 LLM，权重为 safetensors 格式	vLLM 或 SGLang	runpod/worker-v1-vllm（或 SGLang worker）
文本生成 LLM，权重为 GGUF 量化格式	llama.cpp / Ollama	支持 GGUF 的 worker — 不是 vLLM
图像/扩散 workflow.json	ComfyUI	runpod/worker-comfyui (reference/comfyui-serverless.md)
语音转文本（转录）	Whisper 系列模型	语音转文本 worker，而非 LLM worker
文本转语音 / 声音克隆	TTS 模型	TTS worker
说话人分离	说话人分离流水线	来自 Hub 或公共目录的说话人分离 worker
OCR / 文档提取	经典 OCR 引擎	OCR worker，而非 VLM 聊天 worker
文本嵌入	嵌入服务（例如 text-embeddings-inference）	嵌入 worker
提供给你的自定义处理程序	你自己的镜像	自定义容器镜像

• 格式检测。 选择前先检查仓库中的文件。*.safetensors / *.bin → vLLM/SGLang。*.gguf → llama.cpp/Ollama worker。在 worker-vllm 上部署 GGUF 仓库是常见的引擎选择错误：vLLM 无法加载它。在最终回复中说明你检测到的格式及其对应的引擎；检测结果本身就是答案的一部分，而不只是选择依据。
• OCR 资源配置。 对 OCR/文档提取的冒烟测试部署，默认使用经典轻量级 OCR worker（16–24 GB）。基于 VLM 的 OCR（7B+ 参数）属于大型模型部署：按大型模型配置资源（48 GB 级别），否则不要将其用于冒烟测试。
• 社区模板来源。 如果某种模态没有 Runpod 官方 worker，请在 Hub / 公共目录中查找可处理该模态的**社区（非 Runpod）**模板。根据列表写出仓库和所有者的名称，绝不要凭记忆断言仓库名称。找到合适的 worker 后，部署它并运行一个实际作业。不要止步于“我找到了 X”，也不要因配置中为可选项的凭据而停下（参见阶段 2 中的运行时可选令牌规则）；应通过 worker 配置文档所述的作业输入请求所需功能。只有在目录中找不到合适选项时，才说明“未找到”并停止；绝不要编造仓库名称或 Docker 镜像。
• 自定义镜像。 用户提供自己的处理程序镜像时，该镜像就是引擎。务必部署指定的镜像，绝不要用替代品。缺少必需环境变量时，按阶段 2 中的模型默认值规则处理，而不是提问；观测到的 worker 状态就是报告内容，而不是要反问用户的问题。部署后，读取 worker 状态（list-endpoint-workers 或 endpoint-health）并报告观测结果。对于自定义镜像，worker 的实际健康状况就是交付结果：一次已完成的作业无法证明其他 worker 没有崩溃循环，因此必须将处于崩溃循环状态的自定义镜像报告为失败。如果镜像位于私有注册表中，端点需要注册表凭据（创建或引用凭据；参见 lifecycle-crud）；绝不要泄露注册表密码。对于负载均衡器（custom-HTTP、direct-routing）端点，而非队列端点，首要原则是 worker 必须在 PORT（默认 80）上提供 HTTP 服务，并且在 PORT 上通过 HEALTH_CHECK_PATH（默认 /ping）响应健康检查。两者缺一不可，否则 worker 永远无法通过健康检查，端点会显示为卡在零个就绪 worker；端点读取结果会返回正在轮询的确切健康检查 URL。创建后也无法更改端点类型，而且负载均衡器端点没有队列：所有 worker 都忙时，请求会失败而非等待，因此应根据峰值配置 workers.max。

第 1 阶段 — 评估硬件规格（读取目录，并引用 discovery）

将参数量 × 精度及 KV／开销显存计算委派给 discovery；此技能会将其结果用于实际 GPU 选择。

• 读取模型的真实元数据（参数量、精度；对于扩散模型，还要读取 checkpoint／LoRA／VAE 资产大小）。如果配置可读，不要仅根据仓库名称估算规格。
• 固定使用一张指定显卡。 如果用户要求端点固定到某张确切的 GPU，请选择包含该卡的池，并在 gpu.excludedTypes 中列出池内的其他 GPU 类型（gpu.pools 接受池 ID，而非 GPU 类型 ID，并且至少要保留一种类型）；可以在创建时设置，也可以之后使用 set-endpoint-gpus 设置。回读结果会列出池和排除项，以证明固定设置生效；并确认其他设置均未偏离回读结果。
• 选择显存足够的最小 GPU 规格，然后通过 GPU 可用性回读确认实时库存。include:["AVAILABILITY"] 和 product:["SERVERLESS"] 要配合使用（库存因产品而异）；如果端点需要特定数据中心，这样也能查看各数据中心的情况。同一次回读中的 cudaVersions 会显示 CUDA 版本对应的可用容量（适用于需要设置 CUDA 最低版本的情况）。创建时固定该最低版本：gpu.minCudaVersion 应设为镜像所用的 CUDA 版本（CUDA 12 镜像设为 12.8；只有基于 CUDA 13 构建的镜像才设为 13.0），或者使用 gpu.allowedCudaVersions 指定确切版本集合；两者不能同时使用（同时提交会返回 400），且最低版本必须在 cudaVersions 中有库存。绝不要在没有库存的 GPU 规格上创建：无法获取工作进程的缩容至零端点看起来已部署，却永远无法运行。
• 单卡放不下模型时使用多 GPU。 当所需显存超过当前有库存的最大单卡显存时，将每个工作进程的 GPU 数设为大于 1，并在工作进程环境变量中启用张量并行（例如，vLLM 工作进程的张量并行设置值等于 GPU 数量）。说明将使用多 GPU 及其原因（模型无法装入单卡），并说明多 GPU 工作进程的每小时费用会按比例增加。提交前，在答复中列出替代方案价格：将有库存的最大单卡（显存、实时库存、每小时价格）与多 GPU 方案对比。
• Hub 部署时固定 GPU 池。 如果省略 gpuIds，deploy-hub-repo 会继承发布配置中的 GPU 池列表，因此可能会悄悄申请顶级显卡，即使 24 GB 显卡已足以处理任务，且每小时费用会高出数倍。除非发布配置固定的正是规格选择所用的池，否则每次 Hub 部署都要传入根据你的规格选择得出的 gpuIds。
• CPU 无服务器。 create-endpoint 只接受一种硬件选项：gpu 对象（池和数量），或根据 CPU 目录回读（list-cpu-types）选择的 CPU 规格配置 cpu 数组。对于 CPU 工作负载，只发送 cpu，不要发送 gpu（切勿将 GPU 池强加给 CPU 工作负载），并在创建前列出该 CPU 规格的每小时价格。
• 明确设置所需默认值。 REST 创建默认将 FlashBoot 设为 OFF、workers.max 设为 3、workers.idleTimeout 设为 10 s、timeout 设为 300 s；请明确设置 flashboot 和工作进程上下限，不要沿用默认值。账号所有端点的 workers.max 总和受按余额分级的配额限制（初始为 5），并会在创建时检查，因此第二个端点若采用默认值 3，可能会被拒绝。
• 说明费用。 创建前，根据目录回读列出所选 GPU 的每小时费率（×GPU 数量）。创建端点和运行冒烟测试都会产生费用。

阶段 2 — 配置资源

有两种配置路径；请根据来源选择。

• Hub 发布版本。 如果来源是 Hub 仓库，请直接部署其列出的发布版本（一次调用）。先读取发布配置（硬件要求 + 环境变量架构），以便只传入该发布版本接受的环境变量键，并了解其 GPU／磁盘默认值。要复现已知可用的构建，请固定到确切的发布版本，而不是使用“latest”。
• 其他所有情况。 创建一个模板，指定引擎镜像、磁盘大小、工作进程公开的端口以及环境变量（模型 ID、引擎设置、令牌）；然后创建引用该模板的端点。除非用户要求预热容量，否则从缩容至零开始（最小工作进程数为 0）；非零最小值意味着始终运行并产生费用的工作进程。托管在 registry.runpod.net 上的镜像属于 Hub 构建：请通过 deploy-hub-repo 部署（发布版本包含注册表身份验证）；如果使用包含该镜像的普通模板，会因注册表身份验证失败而陷入循环。
• 配置路径与冷启动。 将内容烘焙进镜像 = 冷启动最快、镜像最大；启动时下载 = 镜像较小、新工作进程的首次请求较慢；网络卷 = 在与 GPU 同处一个数据中心的卷中暂存一次权重，并由每个工作进程挂载（可写，因此要协调并发写入），这样新工作进程便可跳过下载。随后，预构建的工作进程镜像会从挂载卷加载权重。你编写的处理程序可以使用 VolumeCache（Runpod Python SDK runpod>=1.12.0）封装加载过程，让每次冷启动都先将权重复制到本地磁盘；请参阅 runpodctl/reference/model-caching.md。权重较大（约超过 30 GB）或需要在多个工作进程间共享时，请选择网络卷。根据实际资源总量并留出余量来确定卷大小；在创建端点所在的同一数据中心创建卷（请参阅 lifecycle-crud），并说明选择了哪种路径及其对冷启动的影响。
• 多区域／高可用（不会自动同步）。 多区域端点需要在每个数据中心挂载一个网络卷。这些数据中心各自的卷不会自动同步：你必须自行在它们之间复制数据（例如，在这些卷的 S3 端点之间执行 aws s3 同步），否则每个区域提供的权重会过期或缺失。
• 必需的环境变量、受限权重与运行时可选令牌。 读取发布版本／工作进程配置（includeConfig: true），并在部署前设置所有没有默认值的必需环境变量键（例如嵌入工作进程的模型 ID 环境变量，如 MODEL_NAMES）。如果部署时没有设置模型环境变量，工作进程将不会加载任何内容，并会对每个任务返回 400。文本生成工作进程未指定模型时（使用没有 MODEL_NAME 的 vLLM 镜像），如果配置中有该工作进程的文档默认模型，就选择该模型；否则选择适合显卡的最小指令模型（对于 16 GB 显存级别的显卡，选择 1–2B 指令模型），说明所选模型并部署。不要询问用户要哪个模型。对于在下载时若没有令牌便会因权限受限而返回 403 的 HuggingFace 仓库，请在环境变量中传入令牌；如果用户没有提供令牌，请说明下载会返回 403 并向用户索取。不要部署无法获取权重的构建。仅在可选运行时功能需要令牌（其配置默认值为空的工作进程，其可选功能需要令牌）时，才先执行以下一项检查：用户是否提供了令牌（在请求中粘贴、设置在环境中，或明确表示可用）？
  • 已提供令牌 → 使用令牌是任务的一部分。 创建时将其设置为工作进程环境变量（使用工作进程文档中说明的令牌环境变量），并说明已完成配置（只提及环境变量名称，绝不透露令牌值），且预期受限功能可以正常使用。绝不要在未接入用户提供的凭据时部署。
  • 未提供令牌 → 仍然部署。 部署不取决于是否提供令牌：不要因缺少可选凭据而搁置整个部署。完成部署、运行任务、报告端点返回的结果，然后说明该功能需要令牌才能启用。 绝不输出令牌值；请用环境变量引用它。

阶段 3 — 预热并对一个真实任务进行冒烟测试

在宣布端点已部署前，先验证它：通过服务端保持机制阻塞等待冒烟测试任务，而不是让用户反复轮询；工具可以负责等待。任务进入终态后，报告你观察到的情况；如果等待不再有意义，就报告有证据支持的状态。

• 提交后在服务器端等待——不要紧密循环轮询。 使用 run-endpoint 提交一个小型任务（该模态下最小的真实输入），然后使用 get-job-status 并设置 wait: 300000 等待，这是服务器端允许的最长等待时间。首次冷启动任务会超过 runsync 的等待时限，而且其结果只保留一分钟，因此 runsync-endpoint 适用于已预热的端点和快速任务。这样做是为了验证工作进程能否使用真实资产集启动并返回正确格式的输出，而不只是确认端点存在。
• 首次任务的冷启动可能需要 1–5 分钟甚至更久——全新的工作进程需要拉取映像并加载模型。这是正常情况，并非故障。如果任务超过一次等待时限，请继续使用 get-job-status 并设置 wait: 300000 阻塞等待（一次服务器端等待，不要快速重复轮询）。轮询已有的任务 ID；不要重新提交，否则会启动新任务。在两次等待之间检查 list-endpoint-workers：如果有 unhealthy 工作进程、有任务仍在排队但旁边已有就绪工作进程，或容量为零，就停止等待并查看日志（见下文）。**每个冒烟测试任务最多进行三次服务器端等待，计数如下：**对同一任务 ID，最多调用三次设置了 wait: 300000 的 get-job-status。第三次等待后，以已掌握的证据报告结果：不进行第四次等待，也不要紧密轮询。超过三次等待仍未完成的任务应如实报告，而不是继续等待。当继续等待已无法提供有用信息时，就停止并根据工作进程状态证据报告情况：端点已正确创建，任务已提交，但工作进程始终未就绪，以下是工作进程状态所显示的内容。这样的证据报告已经完整；无休止地反复尝试不是。
• 使用始终可用的读取结果诊断卡住的任务：endpoint-health、list-endpoint-workers，以及 get-job-status 在 IN_QUEUE 时附带的 workerHealth 区块。 首个任务的工作进程处于 initializing 状态 = 冷启动可能仍在进行 → 继续等待，但在下一次等待前先查看工作进程日志（source=system）：映像拉取失败或 CUDA 不匹配导致容器反复崩溃重启时，即使任务仍处于 IN_QUEUE，状态也可能显示为 INITIALIZING 或 RUNNING。工作进程处于 unhealthy 状态，或日志中反复出现容器启动但没有处理程序输出 = 崩溃循环（是真正的工作进程故障，不是预热缓慢）→ 更换工作进程映像或 GPU 池，不要继续干等。total: 0 持续超过几分钟，或 throttled 大于 0 = 所选池和数据中心没有可用容量 → 扩大选择范围。任务如果始终没有离开 IN_QUEUE，就从未被解析：任何工作进程都没有读取其负载，因此绝不要根据队列卡住的证据推测输入格式错误。应如实报告队列或冷启动情况，并引用工作进程状态。同样的原则适用于所有队列卡住异常：如果自己的读取结果与某个原因矛盾，或并未显示该原因，就绝不要把它说成“确凿”原因（任务排队时旁边已有就绪工作进程，且没有任务正在处理，说明映像可能有问题；应根据日志说明，而不是仅凭状态判断）。优先选择货源充足的通用 GPU 池，而不是稀缺的高显存级别（例如 48 GB 显卡），以便端点能获取工作进程。
• 使用获准使用的工具。 在仅能使用 MCP 的会话中，不要为了查找工作进程的输入架构或阅读其 README 而尝试调用你并不具备的网页抓取工具、Shell 或浏览器。无法调用你没有的工具，部署也会因此卡住，任务无法完成。通过 list-hub-repos 并设置 includeConfig: true 获取输入格式，并参考端点返回的错误，然后修正负载并重新运行。如果同样无法使用 stream-worker-logs，就根据 endpoint-health / list-endpoint-workers 进行诊断；绝不要让未完成的任务取决于你可能并不具备的工具。
• 对于最终状态为 FAILED 的任务，应报告结果中给出的关键细节（缺少文件、403 权限限制、OOM、格式错误的加载错误）：照实说明，不要猜测其可能的含义。OOM → GPU 无法满足真实内存模式的需求；升级到更高一级。GGUF 仓库出现格式错误的加载错误 → 引擎选择错误（阶段 0）。负载返回 400 → 输入格式错误；根据发布配置修正后重新运行，不要放弃。

阶段 4 — 交接

• 交接内容是一份完整的最终摘要，用户无需向上滚动查找：端点 ID；工作器镜像或 Hub 仓库（以及它来自哪次读取）；GPU 池及其每小时价格；冒烟测试作业的 ID 和最终结果，并附上证明（输出引用、引用的失败信息或有证据支持的超时报告）；同步和异步 URL；端点是否保留（以及当前哪些项目正在计费）或已删除（已通过回读确认）；以及一条可直接运行、引用 $RUNPOD_API_KEY（绝不能填写实际密钥）的 curl 命令。还要包含容量计算、格式发现以及任何缓存／放置事实。
• 清理。 默认保留用户要求的资源：明确告知用户当前哪些项目正在计费（端点、任何最小工作器、任何网络卷），以及之后如何删除。只有当用户将整个流程说明为一次性测试或要求清理时，才拆除资源（端点、其模板、任何网络卷，并逐一通过回读确认已删除）。

硬性规则

• 只部署用户指定的源。绝不创建用户未要求的端点，也绝不触碰或删除其他端点、模板或卷。
• 根据模态和模型格式选择引擎，绝不使用默认值。GGUF 仓库不是 vLLM 任务；转录、TTS、OCR、嵌入任务不是聊天工作进程任务。
• 创建计费端点前，说明 GPU 每小时费用，并记住，冒烟测试任务也会产生费用。
• 绝不编造模型 URL、社区模板仓库或 Docker 镜像。如果无法根据用户提供的信息和目录解析来源，就询问一次，或说明“未找到”并停止。
• 至少用一个真实任务验证端点后，才能称其已部署。创建调用返回了 ID，并不代表端点可用。
• 通过服务端等待让冒烟测试任务进入终态（对任务 ID 先运行 run-endpoint，再运行 get-job-status wait:300000），并预期首次任务的冷启动需要 1–5 分钟以上。应在服务端等待，而不是让用户自行轮询，因为工具可以代为等待。如果继续等待已无法提供有用信息，就以已有证据报告工作进程状态和任务状态。这样的答复是完整的；不要在等待过程中悄然停止。
• 使用已授予你的工具。绝不要依赖你没有的网页抓取或 Shell 工具来查询工作进程的架构。根据 list-hub-repos includeConfig 和端点自身的错误推断输入格式，并就地修正载荷。
• 部署时设置所有必需的环境变量（没有配置默认值的变量）：嵌入工作进程若未设置 MODEL_NAMES，就不会加载模型，所有任务都会失败。对于可选能力令牌（例如文档中提及、默认值为空的令牌环境变量）：如果用户提供了令牌，就在创建时设置（绝不忽略用户交给你的凭据）；如果未提供，仍然部署并运行，然后报告实际结果，并说明提供该令牌即可解锁相应能力。
• 除非用户要求预热容量，否则从缩容至零开始；绝不悄然设置非零的工作进程最小数量，因为这会全天候计费。
• 大模型的容量估算必须展示算式，不能只给出总数：说明参数量及其来源、所选精度下每个参数占用的字节数、权重总量、KV 缓存和额外开销的预留空间，以及由此得出的 GPU 选择。
• 如果用户要求了特定的行为设置（预热／最小工作进程、空闲超时、FlashBoot、指定 GPU），请在创建／更新后读取端点，并确认这些确切字段已生效。未经回读的写入无法验证，因为写入调用本身的响应不算回读。REST PATCH 是稀疏更新（未提供的字段保持不变），但 GPU 选择除外：发送 gpu.pools 时，如果未同时发送 gpu.excludedTypes，排除项就会被清除；因此两者都要发送，并在指定 GPU 后确认扩缩容字段也正确。最终答复必须包含回读结果。
• 部署新端点时，降低冷启动影响有四种方式；如果端点已存在，则转到 endpoint-ops，不要在此处做任何更改。说明这四种方式及其成本权衡：FlashBoot（加快工作进程启动速度，无持续费用，尽力提供）；最小／预热工作进程数（无冷启动；该工作进程持续计费，因此应根据读取的价格报出每小时费用 × 730 小时／月）；空闲超时（延长时间可让工作进程在请求突发间保持预热：冷启动更少，计费的空闲秒数更多）；模型缓存（将模型文件放在网络卷中、Runpod 的模型仓库中（通过 runpodctl model add），或烘焙进镜像；对于大模型，冷启动耗时主要取决于加载模型，而非启动容器）（端点的模型引用需在控制台或通过 runpodctl 设置；将这一步交给用户）。然后使用不会产生持续费用的方式创建端点（启用 FlashBoot、延长空闲超时），回读端点，并报告预热工作进程是唯一剩余的方案及其每月价格。只有当用户要求设置最小工作进程数或接受相应价格时，才设置该数量。用户只是询问该选哪种方案，而你什么都没创建，这并不能满足其设置请求。
• 当权重文件过大而无法烘焙进镜像时，将其暂存到网络卷。在与目标 GPU 相同的数据中心创建网络卷，将其挂载到端点，并将工作进程的模型路径环境变量指向卷挂载点；保持最小工作进程数为 0，并通过回读端点和卷确认配置已接通。如果用户要的是存储配置而非已提供服务的模型，回读结果就是证明；大型模型任务既要花钱又要花时间下载，因此应等用户提出要求后再运行。第一个工作进程的下载会填充缓存。不要创建用户未要求的暂存 Pod；如果用户希望在首次请求前预热缓存，可以将其作为选项提出。明确说明你所搭建架构的两点，不要使用含糊措辞：第一个工作进程会将权重下载到卷中一次，之后每次冷启动都会挂载缓存而非重新下载；卷必须与 GPU 位于同一数据中心，否则无法挂载。如果工作进程使用的是用户自己的处理程序代码，而非预构建镜像，则应将模型缓存保留在容器磁盘上，并用 VolumeCache 封装加载过程，而不是将模型路径指向挂载点（runpodctl/reference/model-caching.md）。（卷的 CRUD 操作规范见 lifecycle-crud；这里讨论的是服务端接线配置。）
• 绝不回显 HF/Civitai／镜像仓库令牌。请用环境变量名称指代。
• 冒烟测试失败时，读取日志并引用日志内容；不要盲目重试，也不要断言未从日志中读到的原因。
• 终态任务的 output／error 字段就是工作进程级证据：解释失败时应逐字引用（例如模型访问受限拒绝、加载错误）。如果你持有终态任务结果，就绝不能告诉用户你无法引用证据；缺少日志流工具，不是忽略任务本身返回的证据的理由。对于能力受限工作进程，COMPLETED 任务的 output 为空或缺失，本身就是可引用的证据：如实报告，并结合配置事实说明未设置该工作进程文档所列的令牌环境变量，然后说明该限制。

错误处理

• Smoke 任务返回 FAILED，且消息中包含 gated / 403 → 该资源受访问限制，且未提供令牌。说明这一点并索要令牌；不要自动重新创建。
• Smoke 任务返回 FAILED，且消息中包含 out of memory → GPU 无法满足实际模式的需求；升级到高一档的 GPU，并说明新的每小时费用。如果升级一档后仍然失败，就重新评估工作器的选择本身。对于任务来说，所选引擎系列过大（例如，本可使用传统 OCR 工作器，却用了 7B VLM），应在当前轮次切换工作器镜像来解决，而不是换更大的 GPU 或继续等待。
• 任务在超过等待时限后仍处于 IN_QUEUE / IN_PROGRESS → 通常是冷启动；对该任务 ID 执行 get-job-status wait:300000 并继续等待，然后报告终态结果或有证据支持的状态。在服务端等待，不要把原始轮询循环交给用户。
• Smoke 任务返回 400 / 负载格式错误 → 输入有误，或者未设置必需的模型环境变量；重新读取发布配置，设置缺失的环境变量，或按照工作器配置文档修正负载格式，然后重新运行。不要停下来询问用户。
• 具备令牌访问限制能力的工作器上的任务几乎立即进入终态，且输出为空或质量下降 → 首先应怀疑访问限制，而不是负载：逐字读取任务的 output / error 字段，并检查是否已在模板/端点上设置令牌环境变量，再推测输入格式问题。根据已有证据作答（任务结果和配置读取足以得出结论），不要把问题推给用户。
• Create 返回 409（名称冲突）→ 添加一个新的简短后缀并重试一次；如果仍然冲突，就说明情况并停止。
• GGUF 仓库无法在 vLLM 工作器上加载 → 这是引擎不匹配，而不是库存或尺寸问题；改用支持 GGUF 的工作器重新配置。
• Hub / 社区目录中找不到该模态的内容 → 报告“目录中未找到”，然后停止；不要捏造仓库。
• Delete 返回 204 且没有响应正文 → 这是成功，不是错误；通过回读确认。

工具绑定

能力	工具
GPU 目录 + 价格 + 库存	list-gpu-types / get-gpu-type（include:["AVAILABILITY"]，product:["SERVERLESS"]）
按数据中心查看 GPU 可用性	同一读取（dataCenters[]）；list-data-centers（include:["GPU_AVAILABILITY"]）
按 GPU 类型查看具备容量的 CUDA 版本	同一读取（cudaVersions）；使用 get-capacity 查看矩阵
数据中心	list-data-centers，get-data-center
浏览 Hub / 社区目录	list-hub-repos（includeConfig:true）
直接部署 Hub 发布版本	deploy-hub-repo
固定 Hub 发布版本 / 读取历史记录	list-endpoint-releases
创建模板	create-template
创建端点	create-endpoint
创建网络卷	create-network-volume
多 GPU / 固定到一张卡	set-endpoint-gpus（gpuCount、pools、排除项）；或同时使用 gpu.pools 和 gpu.excludedTypes 调用 update-endpoint
端点运行状况 / 预热	endpoint-health
列出工作器（每个工作器的详细信息）	list-endpoint-workers
Smoke 测试（阻塞直到进入终态）	run-endpoint，然后调用 get-job-status（wait:300000）；对于已预热且任务执行较快的端点，使用 runsync-endpoint
读取工作器日志	stream-worker-logs（容器生命周期日志使用 source=system）
注册表凭证（私有镜像）	create-registry，get-registry
检查端点 / 模板	get-endpoint，get-template
拆除	delete-endpoint，delete-template，delete-network-volume

如果会话的工具列表中缺少此处列出的工具，请如实说明，并使用最接近的读取工具，而不要捏造结果。

报告模板 — 部署摘要

一份好的部署摘要会告知用户：选择了哪个 worker/引擎，以及选择原因； 端点的名称和 ID；从读取的目录中获取的 GPU 池及其每小时价格； 冒烟任务的证明（引用或提及任务返回的输出）；当前 worker 状态； 端点的持续运行成本（缩容至零或每小时价格）；以及之后如何删除端点。 如果等待结束时任务仍未进入终态，则应以相关证据代替证明：任务 ID、提交的负载、观察到的 worker 状态，以及建议的下一步。

合约

跨流程回答合约（读取所得的确定事实、提交操作不含糊、变更仅针对本次对话创建的对象、独立完整的最终消息、如实说明失败、仅使用已授权的工具）在 runpod-mcp 技能中定义，并适用于此流程中的每条回复。如果此对话尚未加载 runpod-mcp 技能，请在下一次调用工具之前立即加载：其中关于可以更改哪些资源、何时可以按请求执行操作，以及何时应停止并询问用户的规则，此处不再重复。