把 Gemini 3 Pro、Gemini 3 Flash、Veo 3.1 这三个模型接到 GCP Vertex AI 上听起来就是把 Key 配好、发个请求、拿回结果的三步走但实际操作下来我在认证方式、区域开关、异步任务这四处来回折腾尤其在 Veo 3.1 视频生成上它和聊天模型完全是两套工作方式不能拿“发消息等回复”的直觉去写代码。这篇文章把我从环境准备到视频生成跑通的完整过程写清楚适合正准备在 Vertex AI 上接入多模态和视频生成能力的开发者也适合那些已经接好但被 403、404、429 这类状态码卡住的同学。1. 模型接入前必须想清楚的三件事1.1 先给“接入”定个边界我理解的“模型接入”不是拿到一个能调通的 Demo而是从身份认证、资源路径、模型版本、配额约束到结果回收形成一条完整的、可交给业务方使用的工作链。很多人直接把 Postman 里的一段 curl 丢给后端这是测试不是接入。动手前先回答三个问题谁来调用调用哪个模型期望拿到什么格式的输出。谁来调用决定了你用个人的登录凭证还是服务账号调用哪个模型决定了你要申请哪一类的配额期望的输出格式则牵扯到结构化输出、JSON 模式和内容审核的配置。拿标题里的三个模型举例我在这个项目里的分法是Gemini 3 Pro 承接长文档理解和复杂推理Gemini 3 Flash 扛住高并发的简短问答Veo 3.1 负责把创意文案批量变成短视频素材。三者服务的场景完全不同接入时也要分别设计调用逻辑和容错策略。1.2 Vertex AI 相比“裸 API”多了什么如果你只用过直接调用大模型接口的简单方式会觉得 Vertex AI 这套东西绕要建项目、要开服务、要配 IAM、还要区分区域。但真正进入生产环境后这些“绕”恰恰是价值所在。在 Vertex AI 下模型不是拿着一把全局密钥到处用而是挂在你自己的项目资源下通过资源路径projects/项目ID/locations/区域/models/模型ID来定位。所有调用记录会进入云审计日志额度消耗会汇总到项目账单服务账号的权限可以用 IAM 角色精细控制模型发版升级也可以靠版本别名来管理。这意味着你的模型调用不再是黑盒谁在什么时候调用了什么模型、花了多少 token、视频任务生成了多少条都有迹可循。对需要过合规或内部审计的业务来说这比裸接口靠谱得多。1.3 认清模型 ID 和版本关系接入时最容易被轻视的是模型 ID。Gemini 3 系列在控制台里会有带版本后缀的 ID比如带-001这种固定版本号也有-latest这种跟随最新发布的别名。生产环境我建议锁定某个固定版本因为你不知道-latest什么时候会静默升级一旦模型行为变了线上效果会莫名抖动。模型典型模型 ID建议用途备注Gemini 3 Progemini-3-pro-001长文档分析、复杂推理、代码生成上下文窗口大成本较高Gemini 3 Flashgemini-3-flash-001客服问答、摘要、分类、实时交互低延迟、高吞吐适合高频场景Veo 3.1veo-3.1-generate文生视频、首帧图生视频异步任务模式耗时以秒到分钟计这个表里的具体命名以你控制台 Model Garden 里实际能看到的为准但不妨先记住一件事不要硬编码一个你从别处抄来的 ID先在控制台确认目标区域开通了哪个版本。因为同一个模型在不同区域的上线状态可能不一样这是后面最常见的一个报错根源。2. 环境与凭证配置接入成败的隐形分水岭2.1 认证把“人和机器身份”分开第一次接入时我图省事直接在代码里用个人账号的访问令牌做认证请求倒是通了但问题不少令牌会过期权限范围过大而且无法准确知道是哪条业务在消耗配额。后来全部改成了服务账号加 IAM 角色的方式。机器身份用服务账号服务账号只授予它需要的权限例如roles/aiplatform.user这个角色可以调用 Vertex AI 模型接口又不会把整个项目的管理权交出去。本地开发时用gcloud auth application-default login生成应用默认凭证部署到服务器时则把服务账号的 JSON 密钥文件通过环境变量GOOGLE_APPLICATION_CREDENTIALS指给 SDK。记住一点凭证文件是敏感信息不要提交进 Git 仓库也不要复制到共享目录。我见过有人把服务账号 JSON 放到项目代码库里几周后发现被爬虫扫走好在及时发现才没有酿成资损。2.2 一套可以直接用的本地环境准备这里给一份我在新机器上快速跑通 Gemini 接入的步骤照着操作基本不会卡# 1. 安装 gcloud CLI并登录 gcloud init # 2. 切换到目标项目 gcloud config set project YOUR_PROJECT_ID # 3. 本地开发时使用应用默认凭证 gcloud auth application-default login # 4. 安装 Python SDK pip install google-cloud-aiplatform # 5. 如果使用服务账号文件设置环境变量 export GOOGLE_APPLICATION_CREDENTIALS/path/to/service-account.json看到这里你可能会问为什么本地要用“应用默认凭证”因为 SDK 在读取凭证时有一个默认的查找顺序先看GOOGLE_APPLICATION_CREDENTIALS指向的服务账号文件再看本地由 gcloud 生成的应用默认凭证。开发阶段两者都不需要写死在代码里运行时由环境提供这样同一个仓库可以在不同环境直接部署。2.3 区域与 API 启用先看一眼再动手很多人拿到项目 ID 就直接写代码结果调用时报错说模型不可用。这个问题的根子往往不是模型本身而是目标项目里根本没启用 Vertex AI API或者你选的区域没有部署你需要的模型。在进入代码环节前先去控制台确认三件事项目 ID 是否正确aiplatform.googleapis.comAPI 是否已启用目标区域是否提供你要的模型版本。Gemini 类和 Veo 类模型通常在某些固定区域提供不在所有区域都有。写代码时初始化客户端用到LOCATION us-central1这类区域代码就必须和你在控制台开通的区域保持一致。我踩过的坑是在代码里全局写了一个区域后来测试 Veo 时换到另一个区域想试试结果那个区域根本没上线该模型。返回的错误还是 404 不带太多细节排查了半天才意识到是区域问题。所以我的习惯是在代码里把项目和区域抽成配置项切换环境时不用改代码。3. Gemini 3 Pro / Flash 接入从文本到多模态的调用实践3.1 为什么把 Pro 和 Flash 分开接同一个 Gemini 3 系列Pro 和 Flash 的定位差异很大。Pro 更擅长需要深度推理的任务适合处理大段上下文、代码分析、结构化输出这类重活但成本和延迟都更高Flash 则强调速度和吞吐适合客服、标签抽取、标题生成这类短平快任务。实际项目里我不会只挑一个模型全包。一种常见的做法是先用 Flash 做预筛和快速响应遇到置信度低或需要深入分析的请求再升级到 Pro也就是“模型路由”。这种分流能把整体成本压下来同时保证用户体验。接入端不支持动态路由也没关系先在后端各配一个客户端用接口层做分发。不要图省事把复杂逻辑一股脑全塞给 Flash。Flash 快是快但面对需要多步推理的长文本时输出质量会明显打折。把 Flash 当“前台”把 Pro 当“大脑”这是我跑完一轮业务之后比较认可的搭配。3.2 一段可以抄的 Python 调用代码先看一段最基础的 Gemini 3 Flash 调用代码我加了系统指令和常用生成参数from vertexai import init from vertexai.generative_models import GenerativeModel PROJECT_ID your-project-id LOCATION us-central1 init(projectPROJECT_ID, locationLOCATION) model GenerativeModel( gemini-3-flash-001, system_instruction[你是产品信息助手回答要简洁、准确不要编造数据。], ) response model.generate_content( 请用三句话向新用户介绍这个产品的主要功能。, generation_config{ temperature: 0.2, max_output_tokens: 1024, }, ) print(response.text)先解释一下init的作用它告诉 SDK 你要连接哪个项目、哪个区域。这个配置在整个进程内只需要执行一次。GenerativeModel的system_instruction用来给模型设定角色和行为边界是控制输出风格最直接的手段。temperature决定随机性事实类问答我压到 0.2 以下创意文案可以到 0.7 以上。max_output_tokens限制回复长度给 Flash 设 1024 已经能覆盖大多数短回复场景设太大反而拖慢响应。3.3 多模态输入与流式输出Gemini 系列的优势是原生多模态。接入时不需要走两套接口图片、文字、视频这些素材统一封装成Part再传给模型即可。看一个图片输入的简例from vertexai.generative_models import Part image_part Part.from_uri( urigs://your-bucket/sample.png, mime_typeimage/png, ) response model.generate_content([image_part, 这张图里的问题是什么请给出解决方案。])如果你的图片在本地用Part.from_data(datafile_bytes, mime_typeimage/png)也很方便。流式输出则适合长回答场景模型会边推理边吐字首字延迟更低体验更像真人对话。只要把generate_content加一个streamTrue参数再迭代结果块即可responses model.generate_content( 给我讲讲这个产品架构的优缺点, streamTrue, ) for chunk in responses: print(chunk.text, end)多轮对话就用model.start_chat()开启会话上下文后续用send_message追加对话。注意会话上下文会占用 token 预算长聊之后如果发现输入 token 接近上限不要硬塞要主动做摘要压缩或开启新会话。3.4 实测参数经验跑了几轮之后有三条经验值得记下来。第一system_instruction不要写得又长又空例如“你是一个聪明的助手”这种废话对输出影响很小不如直接写“如果数据不足明确说不知道”。第二对输出格式有要求时与其在自然语言里反复叮嘱不如直接要求模型输出 JSON 并给一个字段结构示例实体抽取类任务用这种方法效果提升非常明显。第三别忘了对结果做基本校验。模型完全有可能输出一个格式合法但内容错误的 JSON代码里要有字段校验和兜底默认值。我见过同事因为没校验返回结构结果模型某天抽风返回了空数组整个下游逻辑全部崩溃。任何模型接入都应该默认“输出是不可靠的”在业务逻辑层把校验做厚。4. Veo 3.1 视频生成异步任务模型的接入逻辑完全不同4.1 核心差异Chat 是同步视频生成是异步Gemini 系列的调用是典型的同步低延迟模型请求发出去几秒内返回文本。但 Veo 3.1 不一样视频生成在云端要跑一堆调度和推理流程快的也要几十秒慢的可能几分钟不可能让你一个 HTTP 请求在那里干等。刚开始我不习惯用着聊天模型的思路去等同步结果超时后被迫重试结果任务被重复提交了白烧了配额。后来才意识到接入视频生成的第一课是接受“提交-轮询-取结果”这个异步模型把任务 ID 当一等公民来管理。异步接入的粗粒度流程是先提交生成请求拿到任务 ID 并持久化然后按一定时间间隔查询任务状态状态变为成功后再从输出地址拉取视频。整个过程要设计成可恢复的程序重启后也能根据任务 ID 继续查状态而不是直接丢弃。4.2 文本生成视频的完整请求样例我用官方 SDK 跑通的一段代码大致是这个样子不同版本的手感略有差异但核心流程一致from vertexai import init from vertexai.preview.vision_models import VideoGenerationModel init(projectyour-project-id, locationus-central1) model VideoGenerationModel.from_pretrained(veo-3.1-generate) prompt ( 一只橘猫在雨天窗台上伸懒腰 镜头缓慢推近电影感光线柔和背景虚化 ) response model.generate_videos( promptprompt, number_of_videos1, duration_seconds8, aspect_ratio16:9, fps24, seed1, ) # 拿到任务信息后进入轮询阶段 task_id response.id print(task_id:, task_id)生成请求提交后立刻返回的不是视频文件而是包含任务 ID 的响应对象。接下来要做的是轮询。这里有一个容易被忽略的细节不同版本的 SDK 查询任务状态的方法名可能不一样我在项目里封装了一个函数固定接收任务 ID内部再根据 SDK 版本适配上层业务完全不用关心。视频生成完成后文件通常会写入指定的 GCS 存储桶返回结果里带着一个gs://地址。你需要用存储客户端去下载或者直接给前端一个短期可访问的签名链接。不要把视频文件塞进数据库只存地址和任务元数据就够了。4.3 用首帧做图生视频以及控制生成效果Veo 3.1 不只是能凭一句提示词生生视频也支持拿一张图作为开头帧继续生成。这个能力在做品牌素材时非常实用给一张产品图再写一句“产品在桌面缓慢旋转背景是清晨的实验室”就能得到一条动态短片。图生视频的写法其实就是在请求里多带一个图像Part然后让提示词描述后续画面运动。我的经验是提示词里动词要具体“旋转”“推进”“拉远”都比“展示产品”要可控得多。另外seed参数可以让相同输入的重复调用更稳定方便你做 A/B 对比但不要以为同一 seed 会百分之百生成相同帧它对相似度有帮助不是精确复现。视频生成带有内容审核机制如果提示词可能包含不安全内容请求会直接拒绝。这里没有模板提示词的余地老老实实写正面的、清晰的描述生成成功率会高很多。4.4 失败重试与任务队列异步最怕的是什么是发了任务后没保存任务 ID要么就是报错后盲目的重试。我建议在业务数据表里为视频生成任务单独建一张表字段至少包括任务 ID、请求参数摘要、状态、创建时间、完成时间、输出地址、错误信息。这样做的价值体现在两个场景一是生成失败时你可以拿着错误信息定位具体是哪一步出了问题而不是对着控制台干瞪眼二是程序重启后可以扫描表中“处理中”的任务恢复轮询。否则一旦服务重启你连哪些视频生成了都不知道钱却已经扣了。遇到 429 或瞬时的平台错误可以指数退避后重新查询但前提是原来的请求提交并没有成功。如果任务已经入队就不要再用相同 prompt 再次提交否则同一段视频生成两遍的账单会让你印象深刻。5. 配额、计费和频控很多项目从这里开始翻车5.1 配额是“项目区域模型”的三维约束在 Vertex AI 上配额不是全局的。它是按项目、区域、模型三个维度分别统计的。也就是说同一个模型 ID你在 A 区域有配额不代表 B 区域也能用文本模型有配额视频生成任务又是另一套配额。控制台的配额页面可以看到四项典型的指标每分钟请求数、每分钟 Token 数、正在处理的视频任务数、每天的生成视频条数。如果你的业务预期超过默认值要提前在控制台提交配额提升申请这类审批通常需要时间不要等到上线前才去申请。我在做视频生成时就吃了这个亏Demo 阶段一天生成十几条没问题等要批量生成素材时被当日上限直接卡住。申请提额之后还要等邮件通知整个排期因此延误了两天。5.2 控制成本的关键是“模型分流”在成本这件事上模型选型的差距比代码优化大得多。Gemini 3 Flash 的成本远低于 ProVeo 3.1 的单次生成成本又远高于文本推理。所以合理的结构是让 Flash 承接 80% 以上的简单请求把 Pro 用在真正需要深度推理的场景视频生成则提前和业务方确认好数量预算。项目上可以给每个模型分别建一个监控面板看每日调用量、Token 消耗和费用趋势。一旦发现异常突增立刻查日志。不要等服务商发来高额账单才反应我在项目里设置过每日预算提醒费用一到阈值邮件通知这招能避免不少“测试忘了关”的意外开销。另外如果可以接受文本生成延后处理可以考虑在低峰时段批量跑任务费用会平滑一些。视频生成因为单价高更应该在发起前先经过业务参数校验避免一条有瑕疵的 prompt 反复触发。5.3 频控异常与退避策略文本模型被频控时最常见的是 429。遇到 429 不能硬闯要用指数退避。参考实现import time import random def call_with_retry(call_func, max_retries5): for attempt in range(max_retries): try: return call_func() except Exception as e: if 429 in str(e) and attempt max_retries - 1: sleep_time 2 ** attempt random.uniform(0, 1) time.sleep(sleep_time) continue raise e重试只对“请求没成功”的情况有意义。上面提到过视频生成任务一旦提交成功并拿到了任务 ID就不要再去重发请求了你要重试的是“查询任务状态”。这两个概念的区分是接入异步任务最关键的工程认知。5.4 一张状态码速查表接入过程中状态码的含义值得做成一张表直接贴在团队文档里。状态码常见原因处理办法400请求参数非法、提示词触发安全策略检查参数类型简化提示词401凭证失效刷新应用默认凭证或服务账号密钥403缺少模型调用权限为服务账号绑定roles/aiplatform.user404模型 ID 不存在或当前区域未上线到控制台确认模型 ID 与区域406请求无法按指定格式返回检查响应格式参数和版本兼容性429QPS 超限或配额不足退避重试申请提额500/503平台服务暂时不可用结合日志观察做指数退避重试遇到 404 先别怀疑模型不存在先去确认区域这个错误里有相当一部分是区域和模型版本不匹配造成的。6. 常见问题排查手记三段式定位法6.1 定位框架我在接这几个模型时总结了一个三段式排查框架先看“环境与凭证层”再看“调用参数层”最后看“配额与平台层”。报错出现时不要第一时间翻代码先对号入座。举个例子403 几乎都在第一层要么凭证过期要么 IAM 角色没绑定400 和 406 多半在第二层是 prompt、参数或格式兼容性的问题429 和 503 属于第三层涉及配额和平台状态。把错误归类之后排查效率能提高一倍。6.2 三个我真实遇到的典型问题第一个是 403用服务账号调用 Gemini 时服务账号只有默认角色没有加roles/aiplatform.user。报错信息不会提示你“缺哪个角色”只会说没有权限。解决办法是在 IAM 面板中找到该服务账号绑定角色后等一两分钟生效再重新调用。第二个是 404在某区域调用 Veo 3.1控制台能搜到模型但代码总是 404。后来在控制台查看该模型支持的区域列表才发现目标区域没有正式开放这个新模型换个支持区域后立即恢复正常。这个坑特别隐蔽因为控制台搜索模型是全局能力并不代表所有区域都能调用。第三个是 406用旧版本 SDK 调用新模型接口请求体里带了一些旧版的字段服务端无法识别直接拒绝。升级到新版本 SDK 后问题消失。所以接入新模型时看一眼 SDK 版本是很有必要的。6.3 日志审计与我的工程习惯最后说说日志。Vertex AI 的调用记录会进入云日志平台你可以按请求 ID 去精确检索一次调用的完整生命周期包括输入输出 Token 数、延迟、错误信息。请求 ID 在上层异常里就能拿到接入日志时要记得打印。我给自己定的工程习惯是三条所有调用统一走一个封装好的客户端客户端里统一处理凭证、重试、日志每次调用都打印请求 ID、模型 ID、Token 消耗视频生成任务单独持久化状态。做到这三点就算线下出问题也能根据日志反推当时发生了什么而不是靠猜。接入模型的代码本身不难真正耗时间的反而是这些“看不见”的环节凭证、区域、配额、异步状态管理。我建议你在第一个项目里就把这些琐碎问题一起处理掉哪怕慢一点也比上线后被人从睡梦中叫起来去查 403 要舒服得多。