endpoint-ops

端点运维

你负责运维一个已存在的无服务器端点。在说明任何情况或进行任何更改之前，都要先读取其当前状态（端点配置、健康状况、工作进程和日志）。诊断始终为只读。只有在用户要求更改时才修改设置，并且只修改双方确认的确切设置。

Runpod 更新路径的一项属性决定了这里的核心规则：端点更新采用 PATCH。只有请求正文中包含的字段会更改，省略的字段保持不变，因此只发送用户要求更改的设置，不发送其他内容。唯一的例外是 GPU 选择：gpu.pools 和 gpu.excludedTypes 属于同一项选择，因此，PATCH 如果发送了 pools 却没有发送 excludedTypes，就会清除排除项。修改其中任一项时，都要同时发送两者。PATCH 本身无法提供更改已生效的证明：它的响应并不算读取。先读取配置以获取更改前的值，再在更改后重新读取以获取更改后的值。

所需能力

以下列出所需能力；在此服务器上，提供每项能力的工具见下方的工具绑定。此技能会先读取，再进行更改，而且只修改用户授权的内容。

• 列出并检查端点：确定“哪个端点”并读取完整的当前配置。
• 读取端点健康状况并列出工作进程：获取队列卡住／工作进程退出的证据。
• 读取工作进程日志：查找崩溃／模型加载失败的日志行。
• 按数据中心读取 GPU 库存及有容量的 CUDA 版本：判断队列卡住是否由容量不足导致。
• 更新端点（工作进程最小值／最大值、空闲超时、扩缩容器、FlashBoot、磁盘、环境变量）：经过授权后调整。
• 固定 GPU／设置 GPU 数量：配置资源池与 excludedTypes 选择及 gpu.count；set-endpoint-gpus 会构建该配置并保留其他设置。
• 读取发布历史：确认工作进程正在运行哪个构建版本。
• 取消一个作业；清空队列。这些队列管理操作都需要经过授权。
• 提交并轮询作业，以便在更改后重新验证。

阶段 1 — 诊断（始终执行，只读）

解析端点（列出端点，并在需要时按名称匹配），读取其配置，然后读取健康状态和工作器，再得出结论。根据症状进行分类：

• 作业卡在 IN_QUEUE。 读取健康状态和工作器列表。如果最大工作器数为 0，或者所有工作器都被限流或不健康，队列就没有可运行作业的工作器。闲置 3 天的端点会将 workers.max 降至 2，闲置 7 天后会降至 0，并且会一直维持该值，直到手动调高。因此，长期闲置的端点在首个作业上“卡住”，通常就是这个原因。区分不同成因：工作器数量限制（最大工作器数过低或因闲置而降低，或者最小值为 0 且自动扩缩容器尚未启动）与容量不足（工作器无法获取所选 GPU：throttled 大于 0；使用 product:["SERVERLESS"] 交叉核对该 GPU 类型的可用性；如果端点指定了 CUDA 最低版本，还要核对该 GPU 的 CUDA 版本与可用容量）与崩溃循环（工作器不断重启：使用 source=system 读取其日志；容器可能在处理程序运行前就退出，但作业仍会排队，而工作器状态仍显示为 RUNNING 或 INITIALIZING，因此应以日志为准，而不是工作器状态）。明确指出是哪一种，并引用读取到的健康状态和工作器数值。
• 工作器陷入崩溃循环。 列出工作器，找出发生故障的工作器，读取其日志，并引用决定性的一行：缺少模型文件、403 访问受限、OOM 或处理程序导入错误。报告日志中的内容，不要猜测。OOM → GPU 无法满足实际内存需求；加载／导入错误 → 镜像或环境配置有误。
• 冷启动影响体验。 读取配置。按以下顺序考虑调整项：启用 FlashBoot；延长闲置超时时间，让热工作器在请求突发之间保持运行；设置非零的最小工作器数，以保持容量预热（说明最小工作器会全天候计费，因为它是始终运行的工作器）；使用模型缓存，将模型加载移出启动流程（通过网络卷、Runpod 的模型仓库，或将权重打包进镜像；对于使用卷的端点，如果运行的是用户自己的处理程序，VolumeCache 会在加载前将权重复制到本地磁盘）；并确保自动扩缩容器不会在每次请求之间都缩容至零。说明这些调整项及其成本，然后再进行任何更改。
• 负载均衡器端点，工作器始终无法就绪。 对于负载均衡器（自定义 HTTP）端点，负载均衡器通过轮询工作器的健康检查端点来判断其是否就绪：在 PORT_HEALTH（默认 80）上检查 HEALTH_CHECK_PATH（默认 /ping），该端口与提供服务的 PORT（默认 80）分开。请求到达时，工作器仍未就绪，通常意味着该端口上没有任何服务响应此路径；读取端点信息即可获取正在轮询的确切健康检查 URL。解决方法是重新部署，开放相应端口并提供健康检查路径（参见 serverless-deploy），而不是调整自动扩缩容器。

阶段 1 结束时，给出诊断结论和建议采取的更改；除非提示明确授权更改，否则不要应用更改。如果用户只问“为什么／哪里有问题”，到此即可结束。

阶段 2 — 安全调优（仅在用户授权更改时）

只有当提示要求更改某个指定端点的设置时，才继续操作。

• 回读不变式。 首先读取端点的完整配置，以掌握更改前的值。仅将用户授权的字段放入 PATCH 请求中应用更改。发送用户未要求更改的字段，可能会覆盖他们手动调好的设置。然后再次读取配置，确认目标字段已更新为新值，且你提及的相邻字段保持不变。
• 突发流量的自动扩缩容调优。 对于流量突发的工作负载，调优扩缩容器和工作进程范围：提高工作进程上限以满足突发峰值；将队列延迟或请求数扩缩容目标设为你希望吸收突发流量的速度；并设置空闲超时时长，以确定两波流量之间保留预热工作进程的时间（按请求数扩缩容的队列端点不接受 workers.idleTimeout；账户的工作进程配额也可能不允许提高 workers.max）。只更改用户同意更改的字段；说明提高最小工作进程数的成本。
• 固定为一种 GPU 类型。 如果用户希望端点固定使用某一种确切的显卡，请选择包含该显卡的池，并在 gpu.excludedTypes 中列出该池的其他 GPU 类型（至少要保留一种类型），如果用户提供了 CUDA 下限，也要一并设置。set-endpoint-gpus 会为你构建此排除列表，并在重新发送时保持端点的其他设置不变；update-endpoint 也可以携带相同的 gpu 对象，但在该操作中，pools 和 excludedTypes 属于同一选择，因此必须一起发送。allowedCudaVersions 和 minCudaVersion 互斥（同时发送时会返回 400）。更改 CUDA 约束或池不会清退正在运行的工作进程；如果必须立即应用更改，请先将 workers.max 设为 0，再恢复原值。固定 GPU 后，重新读取端点并确认扩缩容设置仍然保留。

阶段 3 — 管理队列（需满足条件的操作）

• 取消一个任务。 用户指定要取消的任务时，按 ID 取消该任务。取消操作仅影响排队中或正在处理的任务。取消后，使用新的 get-job-status 读取结果进行验证。取消调用本身的响应不算验证（未读取结果的写入就是未经验证的写入）；最终答复应报告重新读取到的状态。如果重新读取显示任务在取消前已进入终态，请如实说明；这是完整且诚实的处理结果。
• 清空队列。 用户希望清除所有待处理任务时，清空队列。此操作会移除所有待处理任务；正在处理的任务会继续运行。明确说明这会清空整个待处理队列，而不只是有问题的任务，并且只有在用户明确要求“清空队列”时才执行。之后重新读取健康状态，确认队列已清空。

硬性规则

• 每次更改设置都必须执行“读取 → 更新 → 读取”：(1) 读取当前配置，(2) 应用更新，(3) 更新后重新调用 get-endpoint 读取一次。最终答复中引用的更改前后值必须分别来自读取 (1) 和 (3)。更新调用本身的响应不算读取；绝不要声称执行了实际上没有进行的回读。
• 只更改用户授权的设置，且只针对用户指定的端点。绝不要调整、固定或清除用户未指定的端点。
• 诊断只能读取数据，且只读操作包括零次作业提交。诊断时绝不要通过 run/runsync 提交“测试探针”：提交的作业会产生计算费用并改变队列，因此属于变更操作；对于故障端点，这只是在花钱重现工作器状态中已经显示的问题。只能根据端点、健康状况、工作器和日志的读取结果进行诊断；可以提出修复建议，但除非提示明确授权，否则不得应用。
• 清空队列会清除整个待处理队列。执行前必须说明这一点；对于含糊的“清理一下”，绝不要清空队列。
• 应用任何会持续计费的设置之前，必须说明其成本（非零的最小工作器数量会使工作器保持热备并持续计费）。
• 必须引用所读取的健康状况、工作器或日志字段。对于工具返回的数值，绝不要使用“可能”之类的说法。
• 绝不要取消或清除用户未要求处理的作业；诊断期间不要“好心地”清空队列。
• 如果读取（健康状况、工作器、日志）失败，报告失败并停止；不要猜测原因。

错误处理

• 未触及的设置却返回了更改后的值 → 这不是 PATCH 导致的，因为 PATCH 会保持未包含的字段不变（但发送 gpu.pools 而不发送 excludedTypes 除外，此时会清除排除项）。检查其他写入路径：重新发送了整个配置的 GPU 固定操作、模板保存、重新部署，或其他人的并发更改。重新读取后再考虑重新应用任何设置。
• 存在就绪工作器且没有正在处理的作业，但状态为 IN_QUEUE → 不要继续等待：读取工作器日志（source=system）；在处理程序运行前退出的容器会呈现出完全相同的状态，这指向有问题的镜像，而不是自动扩缩器。
• 工作器日志显示 OOM → GPU 规格不足；解决方法是换用更大的 GPU（通过 serverless-deploy 重新部署），而不是调整自动扩缩器。
• 取消或清除操作返回成功，但健康状况仍显示有排队作业 → 稍等片刻后重新读取；操作完成后，队列计数会有短暂延迟才稳定。
• get-job-status 对有效的作业 ID 返回 404 → 作业的 TTL（默认自提交起 24 h）已过期，作业已被移除；这不是 ID 错误。
• 会话中缺少 set-endpoint-gpus 时发起 GPU 固定请求 → 通过 update-endpoint 执行相同选择，同时发送 gpu.pools 和 gpu.excludedTypes。

工具对应关系

功能	工具
列出／检查端点	list-endpoints、get-endpoint
端点健康状况	endpoint-health
列出工作器（每个工作器的详细信息）	list-endpoint-workers
读取工作器日志	stream-worker-logs（容器生命周期使用 source=system）
按数据中心查询 GPU 库存	list-gpu-types / get-gpu-type（include:["AVAILABILITY"]、product:["SERVERLESS"]）
按 GPU 类型查询有可用容量的 CUDA 版本	同一读取操作（cudaVersions）；矩阵视图使用 get-capacity
更新端点设置	update-endpoint（PATCH；同时发送 gpu.pools 和 gpu.excludedTypes）
固定 GPU／设置 GPU 数量	set-endpoint-gpus
发布历史	list-endpoint-releases
取消单个作业	cancel-job
清空队列	purge-endpoint-queue
提交／轮询作业	run-endpoint、get-job-status、runsync-endpoint

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

约定

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