基于 ADK 的鞋子 360° 旋转视频生成实战genmedia-for-commerce R2V Spinning 流水线解析【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本文基于 adk-samples 仓库中 shoes/README.md 及对应源码系统讲解如何用 Google Vertex AIGemini Imagen Veo将多角度商品照片合成为专业的 360° 鞋子旋转视频。读者将掌握从图像分类、多鞋拆分、背景抠除、4x 放大、参考图堆叠到 Veo 参考图生视频R2V与质量校验重试的完整实现链路并能直接调用 FastAPI 端点或通过 ADK Router Agent 集成该能力。模块定位与整体架构Shoes Spinning 是 genmedia4commerce 工作流套件中的一个子模块位于genmedia4commerce/workflows/spinning/r2v/shoes/其核心思路是reference-to-videoR2V不再依赖传统的首帧/尾帧插值而是直接把多张不同视角的参考图喂给 Veo让它生成一只鞋子绕轴匀速旋转的 8 秒视频。模块对外暴露三层入口见 README.md 开头声明MCP Toolspinning_shoes_r2vREST API/api/shoes/spinning/*由 shoes_api.py 中的APIRouter实现路由前缀为/api/shoes/spinningADK Agent通过 Router Agent 路由调用适合在对话式电商场景中由用户上传图片触发。流水线依赖 Google Vertex AI 完成五类核心工作按视角分类鞋子图片front/back/left/right/top/bottom 等、拆分含多只鞋的图片、抠图与 4x 放大、用 Veo 的参考图生视频能力生成旋转视频、校验视频质量与产品一致性。目录结构与模块清单genmedia4commerce/workflows/spinning/r2v/shoes/ ├── main.py # FastAPI 入口装配路由 ├── pipeline.py # 主 R2V 流水线编排 ├── classify_shoes.py # 鞋子视角分类远程端点在时 ├── classify_shoes_local.py # 本地嵌入式分类器V1/V2 numpy 模型 ├── split_multiple_shoes.py # 多鞋图片拆分 ├── shoe_images_selection.py # 图片排序与选择 ├── prompt_generation_r2v.py # Veo 提示词生成 ├── video_validation_r2v.py # 旋转一致性校验 ├── product_consistency_validation.py # 产品同一性校验 ├── images_utils.py # 帧采样与图像处理工具 ├── evaluation_app/ # 视频评估工具evaluation_viewer 网页查看器 ├── images/products/ # 示例产品图 └── notebooks/ # 分类器训练 notebook frontend_dev/spinning/r2v/shoes/ ├── ShoesSpinning.tsx # 前端主组件 └── InteractiveViewer.tsx # 视频查看器组件仓库实际源码与 README 目录结构一致并在classify_shoes.py之外补充了classify_shoes_local.py本地分类器实现用于在未配置远程分类端点时开箱即用。前端调用代码位于 frontend/src/spinning/r2v/shoes/ShoesSpinning.tsx。四阶段流水线详解Stage 1图像分类与预处理Input Images → Classification → Split Multi-Shoe → Upscale → Extract Product分类Classification每张图片通过自定义 Vertex AI 端点按视角分类。分类标签共 12 类front、back、left、right、top、bottom、front_left、front_right、back_left、back_right、multiple含多只鞋、invalid无效图。在 pipeline.py 的preprocess_classify_images中这一步通过predict_parallel默认 32 个 worker并行执行classify_shoe并对分类失败的图片直接抛出异常终止。多鞋拆分Multi-Shoe Splitting被判定为multiple的图片交由divide_duplicate_image见 split_multiple_shoes.py用 AI 分割成单只鞋拆分结果会再次进入分类流程确认标签。4x 放大Upscaling使用 Imagen 对图片做 4 倍超分提升参考帧清晰度。流水线会先调用classify_video_gen_status预判状态若为exclude则跳过放大以节省成本同时还会用classify_shoe_closure检测鞋面是否带魔术贴velcro——带魔术贴的商品会直接跳过放大并返回has_velcroTrue原因在 Stage 3 说明。产品提取Product Extraction通过extract_product_from_background移除背景、隔离鞋子主体。值得注意的是R2V 模式默认create_canvaFalse即不会把多张图拼到同一画布这与首尾帧模式需要画布不同。Stage 2图片选择与排序Classified Images → Select Best Angles → Order for Rotation → Stack to 3 References选择Selectionpick_images_by_ordered_best_sideshoe_images_selection.py依据视角覆盖与图像质量挑选最优图片排序Ordering按旋转次序排列例如 right → front → left → back保证相邻参考图在空间上连续堆叠Stacking通过stack_and_canvas_images把图片合并成最多 3 张参考图Veo API 允许的上限供 Stage 3 使用。classify_video_gen_status(labels)返回三种状态决定后续是否继续状态含义full_rotation图片覆盖全部主要视角正、背、侧面partial_rotation缺少部分角度但仍可生成视频exclude图片不足或存在无效角度直接终止Stage 3视频生成Reference Images → Generate Prompt → Veo R2V → Validate → Retry if Needed核心实现是 pipeline.py 中的generate_single_clip_r2v提示词生成若未显式提供veo_prompt调用generate_veo_prompt_r2vprompt_generation_r2v.py让 Gemini 描述鞋子并生成优化后的 Veo 提示词生成失败会抛出“Gemini service may be temporarily unavailable”异常。视频生成调用generate_veo_r2vR2V 模式固定输出8 秒视频duration_seconds恒为 8。旋转校验Spin Validationvalidate_and_fix_product_spin_consistency_r2vvideo_validation_r2v.py抽取视频帧、逐帧分类验证是否呈现一致的旋转动作该校验同时会返回frame_classifications、采样帧索引、总帧数与处理后的帧列表供后续使用。产品一致性校验Product Consistencyvalidate_product_consistencyproduct_consistency_validation.py确认视频中的鞋与输入参考图是同一只鞋默认模型取自环境变量MODEL_NAME_GENERATED_4。可通过validate_product_consistency_flagFalse关闭API 的/generate-video-r2v端点即默认关闭。重试逻辑Retry Logic旋转校验或一致性校验任一失败都会递增retry_count并重新生成直到达到max_retries校验过程本身抛出的瞬时异常如 SSL、网络错误也会触发重试。超过上限后抛出明确错误信息。此重试循环在while retry_count max_retries中实现见 pipeline.py。另外若 Stage 1 检测到鞋子带魔术贴velcro流水线会直接抛出ValueError(Cannot generate video for products with velcro closures)——从源码看这类闭合结构在旋转中容易造成时序不一致属于刻意排除的场景。Stage 4输出处理Video → Sample Frames → Resize → Upload to GCS (optional)帧抽取从视频中采样 50 帧sample_and_process_frames目标帧数target_num_frames50缩放统一缩放到1000x1000保证输出一致性GCS 上传可选若传入gcs_bucket则经save_and_upload_to_gcs把视频与帧上传到gs://bucket/prefix/product_id/并返回 GCS URI 元数据此时product_id为必填。REST API 端点REST 端点全部位于core/python/genmedia-for-commerce/genmedia4commerce/mcp_server/spinning/r2v/shoes/shoes_api.py路由前缀/api/shoes/spinning。以下请求/响应与 README 中一致并结合源码补充参数默认值说明。POST /preprocess-images-r2v对图片做预处理分类、拆分、放大、排序、堆叠返回有序参考图。输入multipart/form-dataimages产品图片文件列表输出JSON{ results: [ { index: 0, prediction: front, image_size: 123456, image_base64: ... } ], video_gen_status: full_rotation, num_images: 3 }源码中该端点会以max(1, cpu_count - 1)个 worker 并行处理若video_gen_status exclude返回 400若检测到魔术贴也返回 400 并携带has_velcro: true。POST /generate-prompt-r2v基于预处理后的图片生成 Veo 提示词。输入all_images预处理后的图片文件列表输出JSON{ prompt: A pristine white running shoe rotates slowly..., reference_images: [...], num_reference_images: 3 }POST /generate-video-r2v生成单个视频片段。输入multipart/form-datareference_images参考图文件列表必填index片段索引默认 0prompt视频提示词可选缺省自动生成reference_typeVeo 参考类型默认assetmax_retries最大校验重试次数源码默认 5输出video/mp4响应头携带X-Video-Filename。注意该端点默认使用快速模型veo-3.1-fast-generate-001并关闭产品一致性校验validate_product_consistency_flagFalse适合快速预览。POST /run-pipeline-r2v端到端执行完整流水线分类 → 预处理 → 生成 → 校验 → 输出。输入JSON{ images_base64: [base64_image_1, base64_image_2, ...], max_retries: 4, veo_model: veo-3.1-generate-001, reference_type: asset, upscale_images: true, product_id: shoe_123, gcs_bucket: my-bucket, gcs_destination_prefix: shoe_spinning_outputs }各字段源码默认值max_retries5、veo_modelveo-3.1-generate-001、reference_typeasset、upscale_imagesTrue、gcs_destination_prefixshoe_spinning_outputs另支持可选字段product_consistency_model、gcs_project_id、disable_logging。带 GCS 输出JSON{ video_gen_status: full_rotation, num_clips: 1, clips: [...], gcs_uris: [gs://bucket/path/video.mp4, ...], gcs_base_uri: gs://bucket/prefix/product_id/ }不带 GCS 输出JSON{ video_base64: ..., frames_base64: [frame1, frame2, ...], num_frames: 50, retry_count: 1 }POST /merge-videos以指定倍速合并多个视频片段。输入multipart/form-datavideos视频文件列表、speedsJSON 数组如[1.0, 0.5, 1.0]输出video/mp4响应头Content-Disposition: attachment; filenamemerged_video.mp4实现上调用共享工具merge_videos_from_bytes见workflows/shared/video_utils.pyR2V 单片段场景通常不需要合并。关键组件与源码对照视角分类classify_shoes.py核心函数与 README 签名一致def classify_shoe(image, client, model, modenormal) - str: Returns: front, back, left, right, top, bottom, front_left, front_right, back_left, back_right, multiple, invalid源码行为见 classify_shoes.py若SHOE_CLASSIFICATION_ENDPOINT未配置或为None自动回退到本地分类器classify_shoe_local否则调用远程 Vertex AI 端点temperature0以保证输出确定性。modevalidation时使用不含sole/multiple的校验版提示词。同文件还实现了classify_shoe_closure用 JSON SchemaVelcroDetectionResult约束输出检测魔术贴。本地分类器classify_shoes_local.pyREADME 提到“Baseline local classifier无需配置”源码实现位于 classify_shoes_local.py基于 Gemini 多模态嵌入 numpy 神经网络包含V2 主模型5 视图 27 特征与V1 回退模型4 视图。当 V2 判为invalid而 V1 以 ≥99% 置信度给出其他类别时采用 V1 结果_V1_OVERRIDE_CONF 0.99用于抑制 OOD分布外图片上的误判。权重文件shoe_classifier_numpy_v2.npz/shoe_classifier_numpy.npz在首次导入时以模块级单例加载。多鞋拆分split_multiple_shoes.pydef divide_duplicate_image(image_bytes, client, return_masksFalse) - list[bytes]: Returns list of individual shoe image bytes图片选择排序shoe_images_selection.pydef pick_images_by_ordered_best_side(images_classified) - list[tuple[bytes, str]]: Returns ordered list of (image_bytes, classification) tuples def classify_video_gen_status(labels) - str: Returns: full_rotation, partial_rotation, exclude旋转一致性校验video_validation_r2v.pydef validate_and_fix_product_spin_consistency_r2v(video_bytes, client, shoe_classifier_model): Returns: (is_valid, reason, fixed_video_bytes, frame_classifications, ...)产品一致性校验product_consistency_validation.pydef validate_product_consistency(video_bytes, frame_classifications, reference_images_bytes, ...): Returns: (is_valid, message, details)配置项说明环境变量定义在 config.env.exampleREADME 中的三要素如下另有若干相关变量变量说明备注PROJECT_IDGoogle Cloud 项目 IDshoes_api.py中默认my_projectREGION/GLOBAL_REGIONAPI 调用区域如europe-west4示例中GLOBAL_REGIONglobal另有US_REGION、EUROPE_REGION、DEFAULT_REGIONSHOE_CLASSIFICATION_ENDPOINTVertex AI 分类端点 ID设为None时启用本地嵌入分类器MULTIMODAL_EMBEDDING_MODEL本地分类器所用嵌入模型示例gemini-embedding-2-previewMODEL_NAME_GENERATED_1Gemini 提示词生成模型用于generate_veo_prompt_r2vMODEL_NAME_GENERATED_4产品一致性校验模型源码默认gemini-3.6-flashshoes_api.py初始化两个 Vertex AI 客户端client与veo_client均使用PROJECT_ID与GLOBAL_REGION。调用示例直接调用端到端流水线README 完整示例含保存视频import base64 import requests # Load images images [] for path in [front.jpg, back.jpg, left.jpg, right.jpg]: with open(path, rb) as f: images.append(base64.b64encode(f.read()).decode()) # Run pipeline response requests.post( http://localhost:8000/api/shoes/spinning/run-pipeline-r2v, json{ images_base64: images, max_retries: 4, upscale_images: True } ) result response.json() video_bytes base64.b64decode(result[video_base64]) with open(spinning_video.mp4, wb) as f: f.write(video_bytes)也可以在 ADK Agent 场景中通过 MCP Toolspinning_shoes_r2v或 Router Agent 路由触发同一能力服务端需要先启动装配了shoes_api路由的 FastAPI 应用。评估工具evaluation_app/目录提供视频质量评估工具evaluation_viewer是一个基于 Web 的查看器可回放生成的视频并展示其校验结果旋转分类、产品一致性等便于人工审查批量生成效果。依赖包用途google-genaiVertex AI 客户端Gemini/Imagen/Veoopencv-python视频/图像处理Pillow图像操作numpy数组运算本地分类器核心fastapiAPI 框架鞋子分类器训练视角分类器本质是一个按视角对鞋子图片分类的微调 Gemini 模型README 提供两种方案本地基线分类器零配置SHOE_CLASSIFICATION_ENDPOINTNone时直接可用基于 Gemini 多模态嵌入 numpy 神经网络前述 V1/V2 双模型集成微调 Gemini LoRA精度更高按下列命令训练自定义分类器。训练概览分类器识别 12 种位置front、back、left、right基本方向front_left、front_right、back_left、back_right对角视角top_front俯视正面、sole鞋底、multiple多只鞋、invalid无效图。注意 README 训练章节的 12 类与 Stage 1 分类标签略有差异top_front/sole取代top/bottom训练与推理以各自维护的标签体系为准。训练 Notebook见 notebooks/train_shoe_classifier.ipynb完整流程加载训练数据从 Parquet 文件读取列包括uri_pathGCS 图片 URI、soft_label分类标签、product_id产品标识用于分层切分训练/验证切分使用 stratified group k-fold保持类别均衡并防止数据泄漏同一产品不会同时出现在训练集与验证集微调 Gemini通过 Vertex AI 配置 epochs默认 10、LoRA rank2/4/8、学习率倍率模型评估输出 accuracy、precision、recall、F1混淆矩阵原始计数与百分比以及错误分析 HTML 报告自动选优基于 F1 分数自动选择最佳模型可配置。快速开始# Fine-tune Gemini with LoRA make train-shoe-model # Evaluate all endpoints and auto-update config.env with the best one make eval-set-shoe-model训练参数通过config.env环境变量配置FINETUNE_EPOCHS默认 10FINETUNE_LORA_RANK默认 2可选 2/4/8FINETUNE_LR_MULTIPLIER默认 0.5FINETUNE_VERSION默认 1FINETUNE_BASE_MODEL默认 gemini-3.6-flash训练数据要求列类型说明uri_pathstring图片的 GCS URI如gs://bucket/image.jpgsoft_labelstring分类标签12 类之一product_idstring用于分组的商品标识notebooks 目录附带一个包含 1000 条分层抽样样本的数据集shoes_classifier_dataset_sample.parquet供测试。推荐每类至少 100 张图片以获得良好效果。超参建议参数推荐值说明epochs10-20从 10 开始欠拟合再增加lora_rank2越低越快越高容量越大lr_multiplier0.5训练不稳定时调低故障排查“Cannot generate video with these images”确保图片至少覆盖 2 个不同视角源码在 pipeline.py 中要求选中图片数 ≥ 2否则抛出Insufficient images for video generation检查图片未被分类为invalid或multiple拆分后仍无效的会被过滤。重试上限后校验仍失败鞋子可能具有导致旋转不一致的特征如魔术贴流水线会直接拒绝尝试提供更清晰、更高分辨率的输入图片测试阶段可关闭产品一致性校验/generate-video-r2v端点默认关闭。性能缓慢图片放大是最慢的步骤测试时设置upscale_images: false可显著加速校验耗时可调小max_retries。分类器不工作确保config.env中设置了SHOE_CLASSIFICATION_ENDPOINT确认端点已在 Vertex AI 中创建并部署检查端点区域与REGION设置一致或参考“鞋子分类器训练”一节训练新模型。小结该模块展示了电商场景中“多角度商品图 → 360° 旋转视频”的完整工业化路径用微调分类器理解视角、用 Imagen 放大抠图、用 Veo R2V 生成旋转视频再以双通道校验旋转一致性 产品同一性配合重试机制保证输出质量最后通过 REST API、MCP Tool 与 ADK Agent 三种形态对外提供服务。对于希望将静态商品照片自动转化为高质感动态展示的电商与广告业务本仓库的 shoes 模块 是一份可直接参考与二次开发的实现范本。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 基于 ADK 的鞋子 360° 旋转视频生成实战：genmedia-for-commerce R2V Spinning 流水线解析
基于 ADK 的鞋子 360° 旋转视频生成实战genmedia-for-commerce R2V Spinning 流水线解析【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples本文基于 adk-samples 仓库中 shoes/README.md 及对应源码系统讲解如何用 Google Vertex AIGemini Imagen Veo将多角度商品照片合成为专业的 360° 鞋子旋转视频。读者将掌握从图像分类、多鞋拆分、背景抠除、4x 放大、参考图堆叠到 Veo 参考图生视频R2V与质量校验重试的完整实现链路并能直接调用 FastAPI 端点或通过 ADK Router Agent 集成该能力。模块定位与整体架构Shoes Spinning 是 genmedia4commerce 工作流套件中的一个子模块位于genmedia4commerce/workflows/spinning/r2v/shoes/其核心思路是reference-to-videoR2V不再依赖传统的首帧/尾帧插值而是直接把多张不同视角的参考图喂给 Veo让它生成一只鞋子绕轴匀速旋转的 8 秒视频。模块对外暴露三层入口见 README.md 开头声明MCP Toolspinning_shoes_r2vREST API/api/shoes/spinning/*由 shoes_api.py 中的APIRouter实现路由前缀为/api/shoes/spinningADK Agent通过 Router Agent 路由调用适合在对话式电商场景中由用户上传图片触发。流水线依赖 Google Vertex AI 完成五类核心工作按视角分类鞋子图片front/back/left/right/top/bottom 等、拆分含多只鞋的图片、抠图与 4x 放大、用 Veo 的参考图生视频能力生成旋转视频、校验视频质量与产品一致性。目录结构与模块清单genmedia4commerce/workflows/spinning/r2v/shoes/ ├── main.py # FastAPI 入口装配路由 ├── pipeline.py # 主 R2V 流水线编排 ├── classify_shoes.py # 鞋子视角分类远程端点在时 ├── classify_shoes_local.py # 本地嵌入式分类器V1/V2 numpy 模型 ├── split_multiple_shoes.py # 多鞋图片拆分 ├── shoe_images_selection.py # 图片排序与选择 ├── prompt_generation_r2v.py # Veo 提示词生成 ├── video_validation_r2v.py # 旋转一致性校验 ├── product_consistency_validation.py # 产品同一性校验 ├── images_utils.py # 帧采样与图像处理工具 ├── evaluation_app/ # 视频评估工具evaluation_viewer 网页查看器 ├── images/products/ # 示例产品图 └── notebooks/ # 分类器训练 notebook frontend_dev/spinning/r2v/shoes/ ├── ShoesSpinning.tsx # 前端主组件 └── InteractiveViewer.tsx # 视频查看器组件仓库实际源码与 README 目录结构一致并在classify_shoes.py之外补充了classify_shoes_local.py本地分类器实现用于在未配置远程分类端点时开箱即用。前端调用代码位于 frontend/src/spinning/r2v/shoes/ShoesSpinning.tsx。四阶段流水线详解Stage 1图像分类与预处理Input Images → Classification → Split Multi-Shoe → Upscale → Extract Product分类Classification每张图片通过自定义 Vertex AI 端点按视角分类。分类标签共 12 类front、back、left、right、top、bottom、front_left、front_right、back_left、back_right、multiple含多只鞋、invalid无效图。在 pipeline.py 的preprocess_classify_images中这一步通过predict_parallel默认 32 个 worker并行执行classify_shoe并对分类失败的图片直接抛出异常终止。多鞋拆分Multi-Shoe Splitting被判定为multiple的图片交由divide_duplicate_image见 split_multiple_shoes.py用 AI 分割成单只鞋拆分结果会再次进入分类流程确认标签。4x 放大Upscaling使用 Imagen 对图片做 4 倍超分提升参考帧清晰度。流水线会先调用classify_video_gen_status预判状态若为exclude则跳过放大以节省成本同时还会用classify_shoe_closure检测鞋面是否带魔术贴velcro——带魔术贴的商品会直接跳过放大并返回has_velcroTrue原因在 Stage 3 说明。产品提取Product Extraction通过extract_product_from_background移除背景、隔离鞋子主体。值得注意的是R2V 模式默认create_canvaFalse即不会把多张图拼到同一画布这与首尾帧模式需要画布不同。Stage 2图片选择与排序Classified Images → Select Best Angles → Order for Rotation → Stack to 3 References选择Selectionpick_images_by_ordered_best_sideshoe_images_selection.py依据视角覆盖与图像质量挑选最优图片排序Ordering按旋转次序排列例如 right → front → left → back保证相邻参考图在空间上连续堆叠Stacking通过stack_and_canvas_images把图片合并成最多 3 张参考图Veo API 允许的上限供 Stage 3 使用。classify_video_gen_status(labels)返回三种状态决定后续是否继续状态含义full_rotation图片覆盖全部主要视角正、背、侧面partial_rotation缺少部分角度但仍可生成视频exclude图片不足或存在无效角度直接终止Stage 3视频生成Reference Images → Generate Prompt → Veo R2V → Validate → Retry if Needed核心实现是 pipeline.py 中的generate_single_clip_r2v提示词生成若未显式提供veo_prompt调用generate_veo_prompt_r2vprompt_generation_r2v.py让 Gemini 描述鞋子并生成优化后的 Veo 提示词生成失败会抛出“Gemini service may be temporarily unavailable”异常。视频生成调用generate_veo_r2vR2V 模式固定输出8 秒视频duration_seconds恒为 8。旋转校验Spin Validationvalidate_and_fix_product_spin_consistency_r2vvideo_validation_r2v.py抽取视频帧、逐帧分类验证是否呈现一致的旋转动作该校验同时会返回frame_classifications、采样帧索引、总帧数与处理后的帧列表供后续使用。产品一致性校验Product Consistencyvalidate_product_consistencyproduct_consistency_validation.py确认视频中的鞋与输入参考图是同一只鞋默认模型取自环境变量MODEL_NAME_GENERATED_4。可通过validate_product_consistency_flagFalse关闭API 的/generate-video-r2v端点即默认关闭。重试逻辑Retry Logic旋转校验或一致性校验任一失败都会递增retry_count并重新生成直到达到max_retries校验过程本身抛出的瞬时异常如 SSL、网络错误也会触发重试。超过上限后抛出明确错误信息。此重试循环在while retry_count max_retries中实现见 pipeline.py。另外若 Stage 1 检测到鞋子带魔术贴velcro流水线会直接抛出ValueError(Cannot generate video for products with velcro closures)——从源码看这类闭合结构在旋转中容易造成时序不一致属于刻意排除的场景。Stage 4输出处理Video → Sample Frames → Resize → Upload to GCS (optional)帧抽取从视频中采样 50 帧sample_and_process_frames目标帧数target_num_frames50缩放统一缩放到1000x1000保证输出一致性GCS 上传可选若传入gcs_bucket则经save_and_upload_to_gcs把视频与帧上传到gs://bucket/prefix/product_id/并返回 GCS URI 元数据此时product_id为必填。REST API 端点REST 端点全部位于core/python/genmedia-for-commerce/genmedia4commerce/mcp_server/spinning/r2v/shoes/shoes_api.py路由前缀/api/shoes/spinning。以下请求/响应与 README 中一致并结合源码补充参数默认值说明。POST /preprocess-images-r2v对图片做预处理分类、拆分、放大、排序、堆叠返回有序参考图。输入multipart/form-dataimages产品图片文件列表输出JSON{ results: [ { index: 0, prediction: front, image_size: 123456, image_base64: ... } ], video_gen_status: full_rotation, num_images: 3 }源码中该端点会以max(1, cpu_count - 1)个 worker 并行处理若video_gen_status exclude返回 400若检测到魔术贴也返回 400 并携带has_velcro: true。POST /generate-prompt-r2v基于预处理后的图片生成 Veo 提示词。输入all_images预处理后的图片文件列表输出JSON{ prompt: A pristine white running shoe rotates slowly..., reference_images: [...], num_reference_images: 3 }POST /generate-video-r2v生成单个视频片段。输入multipart/form-datareference_images参考图文件列表必填index片段索引默认 0prompt视频提示词可选缺省自动生成reference_typeVeo 参考类型默认assetmax_retries最大校验重试次数源码默认 5输出video/mp4响应头携带X-Video-Filename。注意该端点默认使用快速模型veo-3.1-fast-generate-001并关闭产品一致性校验validate_product_consistency_flagFalse适合快速预览。POST /run-pipeline-r2v端到端执行完整流水线分类 → 预处理 → 生成 → 校验 → 输出。输入JSON{ images_base64: [base64_image_1, base64_image_2, ...], max_retries: 4, veo_model: veo-3.1-generate-001, reference_type: asset, upscale_images: true, product_id: shoe_123, gcs_bucket: my-bucket, gcs_destination_prefix: shoe_spinning_outputs }各字段源码默认值max_retries5、veo_modelveo-3.1-generate-001、reference_typeasset、upscale_imagesTrue、gcs_destination_prefixshoe_spinning_outputs另支持可选字段product_consistency_model、gcs_project_id、disable_logging。带 GCS 输出JSON{ video_gen_status: full_rotation, num_clips: 1, clips: [...], gcs_uris: [gs://bucket/path/video.mp4, ...], gcs_base_uri: gs://bucket/prefix/product_id/ }不带 GCS 输出JSON{ video_base64: ..., frames_base64: [frame1, frame2, ...], num_frames: 50, retry_count: 1 }POST /merge-videos以指定倍速合并多个视频片段。输入multipart/form-datavideos视频文件列表、speedsJSON 数组如[1.0, 0.5, 1.0]输出video/mp4响应头Content-Disposition: attachment; filenamemerged_video.mp4实现上调用共享工具merge_videos_from_bytes见workflows/shared/video_utils.pyR2V 单片段场景通常不需要合并。关键组件与源码对照视角分类classify_shoes.py核心函数与 README 签名一致def classify_shoe(image, client, model, modenormal) - str: Returns: front, back, left, right, top, bottom, front_left, front_right, back_left, back_right, multiple, invalid源码行为见 classify_shoes.py若SHOE_CLASSIFICATION_ENDPOINT未配置或为None自动回退到本地分类器classify_shoe_local否则调用远程 Vertex AI 端点temperature0以保证输出确定性。modevalidation时使用不含sole/multiple的校验版提示词。同文件还实现了classify_shoe_closure用 JSON SchemaVelcroDetectionResult约束输出检测魔术贴。本地分类器classify_shoes_local.pyREADME 提到“Baseline local classifier无需配置”源码实现位于 classify_shoes_local.py基于 Gemini 多模态嵌入 numpy 神经网络包含V2 主模型5 视图 27 特征与V1 回退模型4 视图。当 V2 判为invalid而 V1 以 ≥99% 置信度给出其他类别时采用 V1 结果_V1_OVERRIDE_CONF 0.99用于抑制 OOD分布外图片上的误判。权重文件shoe_classifier_numpy_v2.npz/shoe_classifier_numpy.npz在首次导入时以模块级单例加载。多鞋拆分split_multiple_shoes.pydef divide_duplicate_image(image_bytes, client, return_masksFalse) - list[bytes]: Returns list of individual shoe image bytes图片选择排序shoe_images_selection.pydef pick_images_by_ordered_best_side(images_classified) - list[tuple[bytes, str]]: Returns ordered list of (image_bytes, classification) tuples def classify_video_gen_status(labels) - str: Returns: full_rotation, partial_rotation, exclude旋转一致性校验video_validation_r2v.pydef validate_and_fix_product_spin_consistency_r2v(video_bytes, client, shoe_classifier_model): Returns: (is_valid, reason, fixed_video_bytes, frame_classifications, ...)产品一致性校验product_consistency_validation.pydef validate_product_consistency(video_bytes, frame_classifications, reference_images_bytes, ...): Returns: (is_valid, message, details)配置项说明环境变量定义在 config.env.exampleREADME 中的三要素如下另有若干相关变量变量说明备注PROJECT_IDGoogle Cloud 项目 IDshoes_api.py中默认my_projectREGION/GLOBAL_REGIONAPI 调用区域如europe-west4示例中GLOBAL_REGIONglobal另有US_REGION、EUROPE_REGION、DEFAULT_REGIONSHOE_CLASSIFICATION_ENDPOINTVertex AI 分类端点 ID设为None时启用本地嵌入分类器MULTIMODAL_EMBEDDING_MODEL本地分类器所用嵌入模型示例gemini-embedding-2-previewMODEL_NAME_GENERATED_1Gemini 提示词生成模型用于generate_veo_prompt_r2vMODEL_NAME_GENERATED_4产品一致性校验模型源码默认gemini-3.6-flashshoes_api.py初始化两个 Vertex AI 客户端client与veo_client均使用PROJECT_ID与GLOBAL_REGION。调用示例直接调用端到端流水线README 完整示例含保存视频import base64 import requests # Load images images [] for path in [front.jpg, back.jpg, left.jpg, right.jpg]: with open(path, rb) as f: images.append(base64.b64encode(f.read()).decode()) # Run pipeline response requests.post( http://localhost:8000/api/shoes/spinning/run-pipeline-r2v, json{ images_base64: images, max_retries: 4, upscale_images: True } ) result response.json() video_bytes base64.b64decode(result[video_base64]) with open(spinning_video.mp4, wb) as f: f.write(video_bytes)也可以在 ADK Agent 场景中通过 MCP Toolspinning_shoes_r2v或 Router Agent 路由触发同一能力服务端需要先启动装配了shoes_api路由的 FastAPI 应用。评估工具evaluation_app/目录提供视频质量评估工具evaluation_viewer是一个基于 Web 的查看器可回放生成的视频并展示其校验结果旋转分类、产品一致性等便于人工审查批量生成效果。依赖包用途google-genaiVertex AI 客户端Gemini/Imagen/Veoopencv-python视频/图像处理Pillow图像操作numpy数组运算本地分类器核心fastapiAPI 框架鞋子分类器训练视角分类器本质是一个按视角对鞋子图片分类的微调 Gemini 模型README 提供两种方案本地基线分类器零配置SHOE_CLASSIFICATION_ENDPOINTNone时直接可用基于 Gemini 多模态嵌入 numpy 神经网络前述 V1/V2 双模型集成微调 Gemini LoRA精度更高按下列命令训练自定义分类器。训练概览分类器识别 12 种位置front、back、left、right基本方向front_left、front_right、back_left、back_right对角视角top_front俯视正面、sole鞋底、multiple多只鞋、invalid无效图。注意 README 训练章节的 12 类与 Stage 1 分类标签略有差异top_front/sole取代top/bottom训练与推理以各自维护的标签体系为准。训练 Notebook见 notebooks/train_shoe_classifier.ipynb完整流程加载训练数据从 Parquet 文件读取列包括uri_pathGCS 图片 URI、soft_label分类标签、product_id产品标识用于分层切分训练/验证切分使用 stratified group k-fold保持类别均衡并防止数据泄漏同一产品不会同时出现在训练集与验证集微调 Gemini通过 Vertex AI 配置 epochs默认 10、LoRA rank2/4/8、学习率倍率模型评估输出 accuracy、precision、recall、F1混淆矩阵原始计数与百分比以及错误分析 HTML 报告自动选优基于 F1 分数自动选择最佳模型可配置。快速开始# Fine-tune Gemini with LoRA make train-shoe-model # Evaluate all endpoints and auto-update config.env with the best one make eval-set-shoe-model训练参数通过config.env环境变量配置FINETUNE_EPOCHS默认 10FINETUNE_LORA_RANK默认 2可选 2/4/8FINETUNE_LR_MULTIPLIER默认 0.5FINETUNE_VERSION默认 1FINETUNE_BASE_MODEL默认 gemini-3.6-flash训练数据要求列类型说明uri_pathstring图片的 GCS URI如gs://bucket/image.jpgsoft_labelstring分类标签12 类之一product_idstring用于分组的商品标识notebooks 目录附带一个包含 1000 条分层抽样样本的数据集shoes_classifier_dataset_sample.parquet供测试。推荐每类至少 100 张图片以获得良好效果。超参建议参数推荐值说明epochs10-20从 10 开始欠拟合再增加lora_rank2越低越快越高容量越大lr_multiplier0.5训练不稳定时调低故障排查“Cannot generate video with these images”确保图片至少覆盖 2 个不同视角源码在 pipeline.py 中要求选中图片数 ≥ 2否则抛出Insufficient images for video generation检查图片未被分类为invalid或multiple拆分后仍无效的会被过滤。重试上限后校验仍失败鞋子可能具有导致旋转不一致的特征如魔术贴流水线会直接拒绝尝试提供更清晰、更高分辨率的输入图片测试阶段可关闭产品一致性校验/generate-video-r2v端点默认关闭。性能缓慢图片放大是最慢的步骤测试时设置upscale_images: false可显著加速校验耗时可调小max_retries。分类器不工作确保config.env中设置了SHOE_CLASSIFICATION_ENDPOINT确认端点已在 Vertex AI 中创建并部署检查端点区域与REGION设置一致或参考“鞋子分类器训练”一节训练新模型。小结该模块展示了电商场景中“多角度商品图 → 360° 旋转视频”的完整工业化路径用微调分类器理解视角、用 Imagen 放大抠图、用 Veo R2V 生成旋转视频再以双通道校验旋转一致性 产品同一性配合重试机制保证输出质量最后通过 REST API、MCP Tool 与 ADK Agent 三种形态对外提供服务。对于希望将静态商品照片自动转化为高质感动态展示的电商与广告业务本仓库的 shoes 模块 是一份可直接参考与二次开发的实现范本。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考