8.0
热点
AI SCORE
技术实践2026-08-04 00:47
调试 Vertex AI 图像生成管道的实战指南
dev.to · AI#Vertex AI#调试#基础设施
Editor brief · 编辑速览
分析了 AI 工作流中常见的基础设施故障（认证、权限、配额），而非模型失败，提出了系统化的调试策略和排查优先级。
上周，我耗在 AI 基础设施上的时间，比真正用于创作的时间还要多。
任务听起来很简单：通过 Vertex AI 为内容流水线生成图片。
但实际发生的情况是：
invalid_grantpermission denied这正是 AI 工作流中没人告诉你的部分：大多数故障并不是模型故障，而是凭证、项目和策略出了问题。
下面是我最终如何排查完整条链路，并让图片生成路径重新恢复工作的。
起初，这些故障看起来彼此毫无关联。
我遇到了三类不同的错误：
invalid_grant: account not found
403 Permission denied
429 RESOURCE_EXHAUSTED
这通常意味着以下两种情况之一：
我的情况属于第二种。
第一个真正有用的动作简单得近乎粗暴：找到团队实际信任的那一个脚本。
~/clawd/ops/production/scripts/generate_panels.py
它由此成为唯一可信来源。
不是旧代码片段，不是勉强能运行的 notebook，也不是凭记忆判断。
检查实际使用的脚本后，我立刻发现了一个隐藏问题：
PROJECT = "old-project-id"
流水线里仍然硬编码着旧项目。
因此，即使我更新了凭证，请求依然会被发送到错误的地方。
仅这一点就解释了很多问题。
我们把两条不同的路径混在了一起：
这听起来没什么大不了，却会造成极其糟糕的调试环境。
因为它们的故障模式并不相同：
如果把它们混为一谈，你就会开始解决错误的问题。
例如，下面这个错误最初看起来像是模型问题：
429 RESOURCE_EXHAUSTED
但最后发现，它只是由一个配额已经耗尽的 free-tier key 导致的。
与此同时，付费路径却因为完全不同的原因而失败。
经验是：即使 free tier 和付费路径使用的是同一个模型，也要把它们当作两个独立的系统。
拿到新的 Vertex JSON 后，我并没有立即开始生成图片，而是先检查该凭证能否签发 token。
这种测试可以节省大量时间，因为它能告诉你问题究竟出在哪里：
在 Python 中，其逻辑基本如下：
from google.oauth2 import service_account
from google.auth.transport.requests import Request
creds = service_account.Credentials.from_service_account_file(
"vertex_ai_key.json",
scopes=["https://www.googleapis.com/auth/cloud-platform"],
)
creds.refresh(Request())
print(creds.token[:40])
如果这一步失败，就不要修改 prompt，不要更换模型，也不要碰渲染代码。
因为你现在遇到的还不是图片问题，而是身份认证问题。
这个问题耗费了我最多时间。
我创建了一个新的 service account，一切看起来都没有问题，但 Google Cloud 却拒绝创建 JSON key。
最终发现，错误是由以下策略引起的：
iam.disableServiceAccountKeyCreation
从最初的界面上根本看不出这一点。UI 显示某项策略“未强制执行”，但某个上层位置仍然启用了旧版约束。
正是这种不一致，让云端调试像中了诅咒一样令人抓狂。
实际可行的解决方案并不是继续与同一个项目死磕，而是创建一个干净的个人项目，避免继承组织策略遗留下来的包袱。
事实证明，这比尝试理清管理员策略的状态更快。
最终能够正常工作的配置如下：
只有完成这些之后，我才认为这条路径真正修好了。
不是在 key 创建成功时，不是在策略页面全部显示绿色时，也不是在脚本不再崩溃时。
而是直到它真正生成了这个文件：
outputs/nanobanana_vertex_test.png
这是唯一重要的结果。
现在，当 AI 图片流水线出现故障时，我会按照以下顺序进行检查：
与随机更换 key、反复运行 prompt 相比，这样的排查顺序快得多。
对我们来说，最终解决问题的并不是“更好的 prompt”，而是：
这些事情并不光鲜，但它们决定了你拥有的是一条值得信赖的流水线，还是一条只能靠运气才能工作的流水线。
围绕 AI 工具的许多讨论，至今仍然过度聚焦于模型。
但当你真正把这些系统用于生产环境后，就会发现真正的瓶颈往往无聊得多：身份、权限、配额，以及项目管理是否规范。
模型可以是最先进的，但如果你的项目关系图一团糟，你仍然无法交付。
这也正是我想转化为 Terminal Skill 的工作流。
并不是因为 skill 应该用魔法把云端配置隐藏起来，而是因为调试顺序不应该只存在于某个人的记忆中。
一个实用的 vertex-ai-image-pipeline skill 应该为 Agent 提供一份可重复执行的检查清单：
这正是 Terminal Skills 背后更广泛的理念：把混乱而真实的运维工作流，转化为可复用的 Agent skill。
接下来，我可能会把这篇文章整理成一个完整的 Terminal Skills 用例，因为相比又一个 prompt 模板，Agent 更需要这种枯燥但实际的生产工作流。
如果你最近也排查过发生故障的 AI 流水线，我非常想知道，你最先遇到问题的是哪个环节。
如需采取进一步措施，你可以考虑屏蔽此人和／或举报滥用行为。