企业官网建设流程全解析

ADK 通用商品 360° 旋转视频生成：基于 Veo 3.1 R2V 的 Other Products Spinning 流水线深度解析

【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples

导读

本文聚焦 adk-samples 仓库中genmedia-for-commerce示例的Other Products Spinning (R2V)模块：它利用 Google Vertex AI 上的 Gemini、Veo 3.1 R2V（Reference-to-Video）与 Imagen 三大模型，将任意商品（包袋、电子产品、配件、家具等非鞋类商品）的多角度图片自动合成为一段 8 秒的 360° 旋转视频。通过阅读本文，你将掌握该流水线的五阶段处理流程、图片选择与画布布局策略、提示词模板设计、旋转方向与画面瑕疵的双重校验机制，以及如何通过 MCP 工具与 REST API 调用这一能力。

模块定位与整体设计

该模块以 MCP 工具run_spinning_other_r2v对外暴露能力，在 ADK Agent 中经由 Router Agent 路由调用，源码位于 genmedia4commerce/workflows/spinning/r2v/other/。其核心思路是：用多张静态商品图作为参考输入，借助 Veo 3.1 的 R2V 模式生成"相机围绕静止商品匀速旋转一周"的连续视频，替代传统的多图插值（interpolation）方案，得到更流畅、更真实的旋转效果。

从源码结构看，整个模块被拆分为两个子包：

• 工作流实现：workflows/spinning/r2v/other/——包含pipeline.py（Veo 视频生成）、image_selection.py（图片分类与优选）、r2v_utils.py（提示词模板与商品描述生成）；
• 服务封装：mcp_server/spinning/r2v/other/——包含other_mcp.py（MCP 工具）与other_api.py（FastAPI REST 路由）。

五阶段流水线总览

文档给出的完整链路为：

Product Images -> Select Best 4 -> Preprocess -> Stack & Canvas -> Describe Product -> Generate Video -> Validate Direction -> Glitch Check -> Retry if Needed

对应到 other_mcp.py 中的实现，可归纳为五个阶段：

1. 图片选择：当输入超过 4 张图片时，用 Gemini 对每张图片做产品类型与视角分类，选出覆盖度与质量最优的 4 张；
2. 预处理：利用 Gemini 去除背景、Imagen 做 4 倍放大，再按布局策略拼接到参考画布上；
3. 提示词生成：Gemini 分析全部商品图生成简短描述，再渲染进 Veo 提示词模板；
4. 视频生成：以参考图为 asset 资源调用 Veo 3.1 R2V 生成 8 秒旋转视频；
5. 校验与重试：帧级分析旋转方向（逆时针则反转）、Gemini 检测画面瑕疵，失败最多重试 5 次。

整条链路涉及的模型分工非常清晰：Gemini负责商品描述、图片分类与瑕疵检测，Veo 3.1 R2V负责参考图到视频的生成，Imagen负责 4 倍图片放大。

Stage 1：图片选择——一次调用完成分类与优选

当传入图片超过 4 张时，模块会调用 image_selection.py 中的classify_product_images和select_best_images。

一次 Gemini 调用完成双重分类

classify_product_images将全部图片打包进一次Gemini 调用（temperature=0、thinking_budget=0、强制 JSON 输出），要求模型对每张图输出三类信息：

返回结构为{"product_type": "...", "classifications": [{"index": 0, "view": "right", "quality": 8}, ...]}，且classifications数组长度必须与输入图片数一致、按序对应。源码对返回结果做了严格的合法性兜底：非法产品类型回退为other，非法视角回退为other，非数值质量回退为 5，甚至 Gemini 调用整体失败时也会返回全other/5 的默认结果，保证流水线不会因分类异常而中断。

视角布局策略：3D 与平面商品不同

select_best_images的核心逻辑在 image_selection.py：按视角分组、组内按质量降序，再按"槽位优先级"依次为 4 个槽位挑选未被占用且视角匹配的最佳图片。

布局策略取决于商品是"3D 对象"还是"平面对象"：

• 3D 对象（shoes/cars）：侧视图信息量最大，因此右侧视图独占槽位 1、左侧视图独占槽位 2，前视图与后视图在槽位 3、4 上堆叠；
• 平面对象（other）：前/后视图信息量最大，因此前视图独占槽位 1、后视图独占槽位 2，左右侧视图在槽位 3、4 上堆叠。

若某个视角没有可用图片，则按优先级顺序回退到次优视角；若输入不超过 4 张，则直接原样返回、不做选择。这一策略与stack_and_canvas_images的画布拼接规则一一对应，确保进入 Veo 的参考图排列方式符合模型预期。

Stage 2：预处理——背景移除、4 倍放大与画布拼接

预处理阶段由 image_utils.py 中的preprocess_images完成，MCP 调用时参数为num_workers=4、upscale_images=True、create_canva=False：

1. 背景移除与放大（extract_upscale_product）：先用 Gemini 将商品从原始背景中抠出，再用 Imagen 做 4 倍放大，得到更高质量、纯背景的参考帧；
2. 画布拼接（stack_and_canvas_images）：将处理后的图片排列到统一规格的参考画布上。从 image_utils.py 的默认参数可见画布为 4K 规格（canvas_height=2160、canvas_width=3840，含边距）；4 张图时第 3、4 张堆叠在同一画布，最终产出 3 张画布作为 Veo 的参考资源。

这一步的意义在于：统一画布比例与背景，消除不同图片间的尺度、背景差异，让 Veo 更容易理解"同一商品的不同视角"，从而生成连贯的旋转。

Stage 3：提示词生成——描述商品并渲染 Veo 模板

提示词由 r2v_utils.py 负责，分两步：

第一步：生成商品描述

generate_product_description让 Gemini 以temperature=0、max_output_tokens=100分析全部商品图，返回符合固定模板的极短描述：

A [type of product], standing still in a completely white studio void (Hex: #FFFFFF, RGB: 255, 255, 255)

模板刻意只包含产品类型 + 主色，并要求避免描述品牌。文档与源码给出的示例包括："A red ceramic mug standing still…"、"A silver smartwatch standing still…"、"A blue backpack standing still…"、"A white wireless headphones standing still…"。这种约束保证了提示词简洁一致、聚焦于形态与颜色，不引入品牌噪声。

第二步：渲染 Veo 提示词模板

描述随后被 Jinja2 模板引擎渲染进VEO_R2V_PROMPT_TEMPLATE（见 r2v_utils.py）：

**[Subject]:** {{description}} **[Action]:** The camera performs **one continuous, seamless, very fast 360-degree orbit** around the stationary product. The camera movement is perfectly smooth and steady, maintaining a constant distance and speed throughout the entire clip. The product does not move or rotate; only the camera moves. **[Scene]:** A completely white studio void (Hex: #FFFFFF, RGB: 255, 255, 255). The only visible element is the product, nothing else.

模板通过[Subject] / [Action] / [Scene]三段式明确指定：主体是商品、动作是相机围绕静止商品做一次连续无缝的快速 360° 环绕（商品自身不移动、不旋转）、场景为纯白影棚虚空。这种结构化提示词是 Veo 生成高质量旋转视频的关键。

Stage 4：视频生成——Veo 3.1 R2V 调用细节

视频生成封装在 pipeline.py 的generate_video_r2v中，核心 API 调用如下：

def generate_video_r2v(reference_images_bytes, prompt, index): reference_image_sources = [] for img_bytes in reference_images_bytes: ref_image = VideoGenerationReferenceImage( image=Image(imageBytes=img_bytes, mime_type="image/png"), reference_type="asset", ) reference_image_sources.append(ref_image) operation = veo_client.models.generate_videos( model="veo-3.1-generate-001", prompt=prompt, config=types.GenerateVideosConfig( aspect_ratio="16:9", number_of_videos=1, duration_seconds=8, generate_audio=False, reference_images=reference_image_sources, ), ) while not operation.done: time.sleep(2) operation = veo_client.operations.get(operation) ... return video_bytes

值得注意的实现细节：

• 模型固定为veo-3.1-generate-001，每个参考图通过VideoGenerationReferenceImage声明为reference_type="asset"，即把商品参考图作为"资产"约束视频内容；
• 生成参数为16:9 画幅、时长 8 秒、单条视频、不生成音频；
• 调用为阻塞式长任务：每 2 秒轮询一次operation.done，直到获取generated_videos[0].video.video_bytes；
• 若 API 无响应或返回空字节，会抛出异常交由上层重试逻辑处理。

Stage 5：双重校验与重试机制

生成出的视频并不会直接交付，而是经过旋转方向校验与画面瑕疵检测两道关卡，全部通过才标记为有效。

旋转方向校验

check_spin_direction（见 workflows/spinning/eval.py）将视频写入临时文件，调用 V3f 光学流分类器classify_rotation判定方向，返回clockwise/anticlockwise/invalid三态之一。该分类器实现在 rotation_classifier.py，基于稀疏光流分析帧间运动方向，其参数（如 dx_spike=32、dy_spike=35、min_ratio=0.1 等）经网格搜索优化，源码注释声称在 876 个样本上达到 98.3% 的整体准确率。

方向处理策略（对应 other_mcp.py）：

• clockwise（顺时针）：保留原片；
• anticlockwise（逆时针）：调用reverse_video（见 workflows/shared/video_utils.py，按帧抽取后反转顺序，默认 24fps、质量 7）反转视频，使最终成片统一为顺时针旋转；
• invalid（无法判定一致旋转）：计入重试次数，触发重新生成。

画面瑕疵检测

glitch_detection使用 Gemini 视觉模型（默认gemini-3.6-flash，thinking_level="HIGH"，视频以 2fps 的VideoMetadata采样）检查以下四类问题（详见 eval.py）：

1. 方向突变：旋转中途长时间反向（起止处的轻微摆动不算）；
2. 不自然形变：文字/Logo 异常镜像、旋转时手机两侧同时显示屏幕、商品特征错误出现/消失；
3. 脱离旋转轨迹：商品突然缩放、明显倾斜、跳到画面边缘或瞬移；
4. 旋转不连续：大幅跳跃（如从背面直接跳到正面）。

同时明确放行可接受的小瑕疵：商品表面的细微不完美、轻微光照变化、自然反光与阴影、起止处的轻微摆动。返回结构为{"explanation": "...", "is_valid": true/false}。

重试循环

MCP 工具中重试上限为MAX_CONSISTENCY_RETRIES = 5（见 other_mcp.py），流程为：方向invalid或瑕疵检测不通过 → 重新生成 → 再次校验，最多尝试 6 次（初始生成 + 5 次重试）。若全部失败，仍返回最后一次生成的视频，但is_valid标记为false，由上层调用方决定是否使用。

MCP 工具与 REST API 双入口

MCP 工具调用

MCP 工具run_spinning_other_r2v（other_mcp.py）接收一个参数：

空输入或非法 base64 会直接返回错误字典。视频生成、方向校验等耗时操作均通过asyncio.get_event_loop().run_in_executor放入线程池执行，避免阻塞事件循环。成功响应的 JSON 结构如下：

{ "video_base64": "base64-encoded MP4 video", "description": "A red ceramic mug standing still...", "prompt": "Full Veo prompt used for generation", "retries": 1, "is_valid": true }

其中description是 Gemini 生成的商品描述，prompt是渲染后的完整 Veo 提示词，retries是实际重试次数，is_valid表示是否通过全部校验。

REST API 端点

other_api.py 提供了前缀为/api/spinning/r2v/other的 FastAPI 路由，将流水线拆分为可单独调用的步骤，便于前端分步展示或调试：

注意 REST 入口的MAX_CONSISTENCY_RETRIES = 3（other_api.py），与 MCP 入口的 5 次不同——这是两个入口在重试策略上的实现差异，从源码结构可以推断是出于 API 响应时长与成本的权衡。

配置项说明

模块依赖的环境变量与文档略有出入，以仓库实际代码为准。文档中记载的变量名（LOCATION、NANO_LOCATION）与当前源码使用的实际变量名不完全一致，源码（pipeline.py、other_mcp.py、other_api.py）统一通过以下变量配置：

仓库根目录的 config.env.example 提供了更完整的部署级配置参考，其中还包含US_REGION（us-central1）、EUROPE_REGION（europe-west4）、DEFAULT_REGION等区域定义，以及 Cloud Run 部署参数（如MEMORY=32Gi、CPU=8、TIMEOUT=3600），说明该服务在生产环境以较高资源规格运行（长视频任务需要大内存与长超时）。

运行前提：需要具备访问 Vertex AI 上 Gemini、Veo 3.1 与 Imagen 服务的 GCP 凭据（认证信息与 Vertex AI 配额是运行本模块的基础条件，仓库代码不包含配额申请流程）。

故障排查与最佳实践

旋转方向无效

• 流水线会自动反转逆时针视频，因此最终交付片通常统一为顺时针；
• 若方向被判定为invalid（无法识别出一致的旋转），会触发最多 5 次重试；
• 建议提供视角差异明显的图片，避免各图角度过于接近导致模型无法理解旋转意图。

瑕疵检测不通过

• Gemini 会在生成后检查画面瑕疵，未通过的视频自动重新生成；
• 若所有重试均失败，最后一次生成的视频仍会返回，但is_valid: false，调用方需自行决定是否接受或提示用户重试。

视频质量不佳

• 提供高分辨率、多角度的商品图，前、后、左、右四视图全覆盖效果最佳；
• 图片虽然会自动做 4 倍放大，但原始质量仍然重要——放大无法凭空补足严重模糊或过曝；
• 尽量保证每张图只含单一商品、背景简洁，降低背景移除阶段的误差。

小结

Other Products Spinning (R2V) 模块展示了 ADK 生态中"多模型协作"的典型范式：Gemini 承担理解与审核（分类、描述、瑕疵检测），Veo 3.1 R2V 承担生成，Imagen 承担画质增强，再以"校验-重试"循环兜底生成质量。对于希望为电商商品批量产出 360° 展示视频的开发者，该模块既可作为 MCP 工具被 ADK Agent 直接调用，也可通过 REST API 分步集成到自有前端流程中，是理解参考图驱动视频生成（R2V）工程化落地的绝佳样例。与之互补的鞋类专属流程位于 workflows/spinning/r2v/shoes/，可对照阅读以理解两类商品在选图策略上的差异。

【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples