深入解析 retail-virtual-tryon 技能基于 Gemini 图像模型与 Veo 3.1 的虚拟试穿架构【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples虚拟试穿Virtual Try-OnVTO是零售电商场景中让用户先试后买的核心能力。本指南以当前仓库中 retail-virtual-tryon 技能的架构文档 tryon-architecture.md 为骨架完整拆解其双模态架构如何用 Gemini 图像生成模型完成图片试穿Image VTO又如何用 Veo 3.1 的 Reference-to-VideoR2V能力把试穿结果变成走秀视频Video VTO。读完本文你将掌握tryon_agent.py与tryon_processor.py的分层设计、两套官方 SDK 调用范式、参考帧预处理细节以及如何把该技能接入 ADK Agent 并部署到 Google Cloud。架构总览一条流水线两种输出tryon-architecture.md 用一个简洁的流程图概括了 VTO 的核心数据流用户照片与商品图进入系统后先经过 Gemini 图像模型生成合成试穿图若开启视频模式再基于这张合成图生成走秀视频。User Photo Product Image | |-- VTO Image Generation (generate_tryon_image) | |-- Route to gemini-2.5-flash-image (default) / gemini-2.5-pro-image | v | [Composite Try-On Image] | -- IF Video Mode Enabled (generate_tryon_video): |-- Split composite into framings: Lower Body, Upper Body, Face |-- Pad each framing onto a 16:9 canvas |-- Invoke Veo 3.1 R2V model (veo-3.1-generate-001) v [Catwalk Video mp4]关键设计要点在于两个阶段强依赖视频生成必须以上一阶段的合成试穿图为输入参考帧而不是直接以用户照片为参考——这样能保证视频中的人物身份、服装与图片试穿结果严格一致。这一调用链在 tryon_agent.py 的try_on_product_video函数中有明确体现先调用generate_tryon_image且此时output_bucketNone结果暂存磁盘再把返回的image_bytes作为generate_tryon_video的输入。模型选型上架构文档明确了两种能力的分工能力默认模型备选模型输出Image VTOgemini-2.5-flash-imagegemini-2.5-pro-image合成试穿图JPEGVideo VTOveo-3.1-generate-001Veo 3.1 R2V—走秀视频MP4从 config.py 可以看到默认值与模型别名的对应关系而 tryon_processor.py 中定义了完整的模型映射表flash/pro分别是两个完整模型 ID 的短别名IMAGE_MODELS.get(effective_model, IMAGE_MODELS[flash])提供了别名到正式模型 ID 的兜底解析。关键组件Agent 层与 Processor 层的职责分离架构文档将核心代码划分为两个文件这种分层设计值得借鉴tryon_agent.py —— ADK 工具包装层该文件负责把底层处理能力包装成 ADKAgent Development Kit工具供大模型调用。它承担了三件事暴露 ADK 工具try_on_product_image与try_on_product_video两个函数即 ADK 工具本体它们被挂载到root_agent的tools列表中见 tryon_agent.py。从环境读取配置通过from scripts.config import config统一读取GOOGLE_CLOUD_PROJECT、TRYON_OUTPUT_BUCKET、GEMINI_IMAGE_MODEL等项目级配置。异常收敛每个工具函数用 try/except 包裹底层调用失败时返回{status: error, error: str(e)}的结构化错误字典而不是让异常直接冒泡到模型层。两个工具的函数签名如下源码定义def try_on_product_image( product_id: str, user_photo_path: str, # 本地路径或 gs:// URI product_image_path: str, # 本地路径或 gs:// URI product_category: str clothing, # clothing / eyewear / jewelry / shoes ... product_description: str , # 颜色、款式等简短描述 ) - dict: def try_on_product_video( product_id: str, user_photo_path: str, product_image_path: str, product_category: str clothing, product_description: str , scene_description: str a minimalist fashion studio catwalk setting, ) - dict:返回字典统一包含statussuccess/error、product_id以及output_uri配置了 GCS bucket 时或output_path本地保存时外加model_used标注实际使用的模型。Agent 的系统指令INSTRUCTION约束了模型的行为用户想要静态图时调用 image 工具想要走秀动画时调用 video 工具并且必须先向用户索要人像照片、确认目标商品后再调用工具——这是避免盲目调用、浪费生成成本的关键提示词设计。值得注意的一个实现细节ADK 的adk web会根据 agent 模块所在目录自动命名应用而该模块位于scripts/目录下因此 apps.App 的 name 必须显式设为 scripts否则会话创建会因名字不匹配而失败。tryon_processor.py —— 生成引擎层该文件是真正的发动机实现了两个核心函数分别对应架构图的两条路径generate_tryon_image()通过client.models.generate_contentGemini 路径执行图片试穿内置高质量的系统提示词与用户提示词generate_tryon_video()把试穿输出裁剪为三个参考帧、填充到 16:9 画布然后调用 Veo 3.1 的generate_videosR2V API。test_runnability.py中的 test_agent_runnability 验证了scripts.tryon_agent可正常导入且root_agent存在是整个链路可运行性的最小保障。Image VTOGemini 图像生成调用范式架构文档给出了 Image VTO 的 SDK 调用骨架这里结合 tryon_processor.py 的完整实现做深入展开。官方 SDK 调用形态response client.models.generate_content( modelgemini-2.5-flash-image, contents[ types.Part.from_bytes(dataperson_bytes, mime_typeimage/jpeg), types.Part.from_bytes(dataproduct_bytes, mime_typeimage/jpeg), user_task ], configtypes.GenerateContentConfig( response_modalities[IMAGE], system_instructionsystem_prompt, temperature0.1 ) )几个关键参数的实际作用contents 的多模态输入types.Part.from_bytes把用户照片与商品图转为二进制 Part与文本任务指令user_task并列传入实现两张图 一段话的输入结构。_load_image_bytestryon_processor.py负责把本地路径、gs://URI 甚至 base64 字符串统一解析为字节流。response_modalities[IMAGE]显式要求模型返回图像而非文本。temperature0.1极低的温度保证每次生成的构图、姿态与人物一致性减少随机漂移。system_instruction注入时尚摄影师 高级修图师 虚拟试穿专家的身份与硬性规则。高保真提示词的工程细节generate_tryon_image内部构建了两段提示词这是图片质量的关键系统提示词源码要求模型保持人物身份与姿态、必须显示从头到脚的完整身体包括脚与鞋、修复输入噪点与遮罩伪影、统一光照方向/强度/色温、在脚下添加自然柔和阴影最终输出必须像一张单一连贯的照片而非贴图。用户任务提示词源码用编号清单细化了 8 条约束其中特别值得关注的是PRESERVE IDENTITY ANATOMY保持姿势、体型、面部特征与肤色不得改变人物身材比例REPLACE THE CLOTHES服装必须适配这个人而不是把人改造成适配服装COMPLETE THE OUTFIT若未提供全部服装由模型补充风格一致的配套衣物如裤子、鞋UNIFORM LIGHTING / NATURAL SHADOWS / PHOTOREALISTIC RESULT三者共同保证合成图的光影一致性。输出处理与落盘生成后代码会从response.candidates[0].content.parts中筛选出mime_type以image/开头的 inline 图像 Parttryon_processor.py若没有任何图像数据则抛出RuntimeError。随后根据是否配置了output_bucket二选一配置了 bucket通过_upload_to_gcs以vto-images/{uuid4}.jpg的命名上传返回gs://URI未配置保存到本地tmp/vto-outputs/目录返回绝对路径。两种路径都会同时返回image_bytes这正是视频阶段所需的中间产物。Video VTOVeo 3.1 Reference-to-Video 的调用范式架构文档给出了 R2V 的 SDK 调用骨架。与 Image VTO 相比Video VTO 的难点不在 API 本身而在参考帧的预处理——这是 tryon_processor.py 中最具实操价值的部分。SDK 调用形态from google.genai.types import Image, VideoGenerationReferenceImage ref_images_list [] for img_bytes in [lower_body_png, upper_body_png, face_png]: ref_image VideoGenerationReferenceImage( imageImage(imageBytesimg_bytes, mime_typeimage/png), reference_typeasset ) ref_images_list.append(ref_image) operation client.models.generate_videos( modelveo-3.1-generate-001, promptcatwalk animation prompt, configtypes.GenerateVideosConfig( aspect_ratio16:9, number_of_videos1, duration_seconds5, reference_imagesref_images_list, person_generationallow_adult ) )参考帧拆分三个视角喂给 VeoR2V 模式下 Veo 需要参考图像来锁定人物身份与服装细节。实现中把合成试穿图按身体区域拆成三个独立参考帧tryon_processor.pyLower Body下半身裁剪图片底部 60% 区域img.crop((0, int(height * 0.4), width, height))Upper Body上半身裁剪图片顶部 40% 区域Face面部调用crop_face_simple兜底函数取图片顶部 35%、水平居中的区域left0.2*width, right0.8*width这是代码注释中通常承载脸/头部的启发式裁剪。每个参考帧都转成 PNG 字节并以reference_typeasset构建VideoGenerationReferenceImage。三个帧全部显式传入让 Veo 同时掌握全身姿态 服装细节 面部身份三层信息。16:9 画布填充每个裁剪帧随后通过_create_canvas_16_9tryon_processor.py被居中填充到 16:9 画布上比较当前宽高比与目标比16/9过宽则补高、过高则补宽背景色为中性灰(240, 240, 240)。这一步是为满足 Veo 对输入画布比例的约束。走秀提示词与长轮询视频提示词tryon_processor.py把 8 秒动画拆成四个时间序列逐帧规划站立起步 → 向前行走低机位只拍腰部以下→ 镜头缓慢上摇到肩部 → 停步正面直视镜头。全程强调与参考图像中完全相同的人、完全相同的着装并约束头部始终朝前、表情稳定、至多一次自然眨眼。调用完成后代码进入轮询循环每 2 秒调用一次client.operations.get(operation)直到operation.done随后检查operation.error与result.generated_videos[0].video.video_bytes最终把 MP4 上传到vto-videos/{uuid4}.mp4或落盘到本地。需要特别留意的是实现中的两处实际参数与架构文档示例的差异duration_seconds源码中固定为8注释明确写着Veo R2V strictly requires exactly 8 seconds即 R2V 模式严格要求 8 秒架构文档示例中的5是简化示意实际部署应以源码为准aspect_ratio源码使用9:16竖屏走秀与电商手机端展示场景匹配而架构文档示例为16:9同时源码还设置了generate_audioFalse。若你需要横屏输出可依据 Veo 在该区域的可用比例调整。配置项与运行环境整个技能的所有可配置值集中在 config.py 的config对象中采用惰性读取设计——每次属性访问都实时调用os.getenv()因此脚本运行时修改环境变量能立即生效。核心变量如下环境变量默认值说明GOOGLE_CLOUD_PROJECT空GCP 项目 ID未设置时两个工具函数都会返回错误GCP_REGIONus-west1Gemini 图像 / Veo 部署区域GEMINI_MODEL_LOCATIONglobalVertex AI 调用位置Gemini 系模型通常走globalGEMINI_IMAGE_MODELgemini-2.5-flash-image图片试穿模型支持flash/pro别名GEMINI_MODELgemini-3.5-flashADK Agent 自身的对话模型TRYON_OUTPUT_BUCKET空生成结果图/视频上传的 GCS bucketTRYON_UPLOAD_BUCKET空用户照片临时上传的 bucket默认 24 小时自动删除TRYON_CATALOG_PATHcatalog_images商品目录路径本地文件夹、demo或gs://URIPORT8080本地沙箱服务端口模型访问前置条件依据 README.md需要gemini-2.5-flash-image试穿、gemini-3.5-flashAgent 与目录分类器的模型访问权限若启用走秀视频还需要 Veoveo-3.1-generate-001访问权限。scripts/setup_tryon.py会帮你自动启用 Gemini Enterprise Agent Platform 与 Cloud Storage API并为默认 Compute 服务账号授予roles/aiplatform.user与roles/storage.objectAdmin两个角色。从架构到落地ADK 运行、测试与部署通过 ADK Web 交互测试按 SKILL.md 的指引先设置环境变量export GOOGLE_CLOUD_PROJECTyour-project-id export TRYON_OUTPUT_BUCKETyour-project-id-tryon-output export TRYON_UPLOAD_BUCKETyour-project-id-tryon-uploads export GEMINI_IMAGE_MODELflash # 或 pro / gemini-2.5-flash-image / gemini-2.5-pro-image然后启动 ADK Web UI务必使用.venv/bin/adk而非裸adk否则可能解析到全局 Python 导致/list-apps返回空列表.venv/bin/adk web .在聊天会话中提供商品 ID如shirt_001或sunglasses_001、上传catalog_images/sample_user.jpg或任意人像照片即可下达帮我试穿这件衬衫或生成一段戴着这副墨镜走秀的视频等指令。直接 Python 冒烟测试不启动 UI直接调用 ADK 工具函数验证链路# 测试图片试穿 .venv/bin/python -c from scripts.tryon_agent import try_on_product_image res try_on_product_image(shirt_001, catalog_images/sample_user.jpg, catalog_images/shirt_001.jpg, clothing, red shirt) print(res) # 测试视频试穿Veo .venv/bin/python -c from scripts.tryon_agent import try_on_product_video res try_on_product_video(sunglasses_001, catalog_images/sample_user.jpg, catalog_images/sunglasses_001.jpg, eyewear, sunglasses) print(res) 部署为 Cloud Run Web 应用仓库通过 export_app.py 生成独立容器化代码库再部署到 Cloud Run.venv/bin/python $SKILL_DIR/scripts/export_app.py --config ./design-spec.md --skill-dir $SKILL_DIR gcloud run deploy vto-retail-app --source ./vto-retail-app/ --region us-west1 --project {gcp_project_id} --allow-unauthenticated部署后可通过gcloud run services describe获取服务 URL并支持gsutil -m rsync同步商品目录、curl https://{cloud_run_url}/api/catalog?forcetrue强制刷新索引还可以用 iframe 把试穿组件直接嵌入电商商品详情页。常见问题排查依据 SKILL.md 的 Troubleshooting 表与 README.md 的失败模式说明错误现象可能原因修复方式BILLING_DISABLEDGCP 项目未绑定结算账号在 Cloud Console 关联结算账号API has not been used/disabled所需 API 未启用运行gcloud services enable aiplatform.googleapis.com storage.googleapis.comGCS 上PermissionDenied服务账号权限不足授予roles/storage.adminMethodNotImplemented: 501/Model not found所选模型在当前区域不可用检查项目区域的模型可用性404 NOT_FOUND: Publisher model ... was not found模型名在 Gemini Enterprise Agent Platform 中不存在目前仅有gemini-2.5-flash-image与gemini-2.5-pro-image检查GEMINI_IMAGE_MODEL环境变量图像渲染正常但脸部变形Veo 参考帧的面部裁剪不干净换用更高分辨率的人像照片重试视频生成卡在 Generating catwalk... 超过 90 秒Veo 3.1 配额耗尽或模型过载查看沙箱日志中的503/429错误此外视频生成耗时约 30-60 秒属正常现象Veo 长轮询需要耐心等待用户照片默认上传到带24 小时自动删除生命周期规则的 uploads bucket由setup_tryon.py自动配置这既满足隐私合规要求也是生产环境应保留的默认行为。小结retail-virtual-tryon 的架构本质是一条**图片生成为视频生成奠基的两级流水线**tryon_agent.py负责把底层能力暴露为 ADK 工具并收敛异常tryon_processor.py负责 Gemini 图像合成、参考帧拆分、16:9 画布填充与 Veo 长轮询。理解 tryon-architecture.md 中的两张 SDK 调用范式再对照 tryon_processor.py 的完整实现你就能在自己的项目中复刻这套图片 走秀视频双模态虚拟试穿能力并将其无缝嵌入 ADK Agent 驱动的零售电商应用。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 深入解析 retail-virtual-tryon 技能：基于 Gemini 图像模型与 Veo 3.1 的虚拟试穿架构
深入解析 retail-virtual-tryon 技能基于 Gemini 图像模型与 Veo 3.1 的虚拟试穿架构【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples虚拟试穿Virtual Try-OnVTO是零售电商场景中让用户先试后买的核心能力。本指南以当前仓库中 retail-virtual-tryon 技能的架构文档 tryon-architecture.md 为骨架完整拆解其双模态架构如何用 Gemini 图像生成模型完成图片试穿Image VTO又如何用 Veo 3.1 的 Reference-to-VideoR2V能力把试穿结果变成走秀视频Video VTO。读完本文你将掌握tryon_agent.py与tryon_processor.py的分层设计、两套官方 SDK 调用范式、参考帧预处理细节以及如何把该技能接入 ADK Agent 并部署到 Google Cloud。架构总览一条流水线两种输出tryon-architecture.md 用一个简洁的流程图概括了 VTO 的核心数据流用户照片与商品图进入系统后先经过 Gemini 图像模型生成合成试穿图若开启视频模式再基于这张合成图生成走秀视频。User Photo Product Image | |-- VTO Image Generation (generate_tryon_image) | |-- Route to gemini-2.5-flash-image (default) / gemini-2.5-pro-image | v | [Composite Try-On Image] | -- IF Video Mode Enabled (generate_tryon_video): |-- Split composite into framings: Lower Body, Upper Body, Face |-- Pad each framing onto a 16:9 canvas |-- Invoke Veo 3.1 R2V model (veo-3.1-generate-001) v [Catwalk Video mp4]关键设计要点在于两个阶段强依赖视频生成必须以上一阶段的合成试穿图为输入参考帧而不是直接以用户照片为参考——这样能保证视频中的人物身份、服装与图片试穿结果严格一致。这一调用链在 tryon_agent.py 的try_on_product_video函数中有明确体现先调用generate_tryon_image且此时output_bucketNone结果暂存磁盘再把返回的image_bytes作为generate_tryon_video的输入。模型选型上架构文档明确了两种能力的分工能力默认模型备选模型输出Image VTOgemini-2.5-flash-imagegemini-2.5-pro-image合成试穿图JPEGVideo VTOveo-3.1-generate-001Veo 3.1 R2V—走秀视频MP4从 config.py 可以看到默认值与模型别名的对应关系而 tryon_processor.py 中定义了完整的模型映射表flash/pro分别是两个完整模型 ID 的短别名IMAGE_MODELS.get(effective_model, IMAGE_MODELS[flash])提供了别名到正式模型 ID 的兜底解析。关键组件Agent 层与 Processor 层的职责分离架构文档将核心代码划分为两个文件这种分层设计值得借鉴tryon_agent.py —— ADK 工具包装层该文件负责把底层处理能力包装成 ADKAgent Development Kit工具供大模型调用。它承担了三件事暴露 ADK 工具try_on_product_image与try_on_product_video两个函数即 ADK 工具本体它们被挂载到root_agent的tools列表中见 tryon_agent.py。从环境读取配置通过from scripts.config import config统一读取GOOGLE_CLOUD_PROJECT、TRYON_OUTPUT_BUCKET、GEMINI_IMAGE_MODEL等项目级配置。异常收敛每个工具函数用 try/except 包裹底层调用失败时返回{status: error, error: str(e)}的结构化错误字典而不是让异常直接冒泡到模型层。两个工具的函数签名如下源码定义def try_on_product_image( product_id: str, user_photo_path: str, # 本地路径或 gs:// URI product_image_path: str, # 本地路径或 gs:// URI product_category: str clothing, # clothing / eyewear / jewelry / shoes ... product_description: str , # 颜色、款式等简短描述 ) - dict: def try_on_product_video( product_id: str, user_photo_path: str, product_image_path: str, product_category: str clothing, product_description: str , scene_description: str a minimalist fashion studio catwalk setting, ) - dict:返回字典统一包含statussuccess/error、product_id以及output_uri配置了 GCS bucket 时或output_path本地保存时外加model_used标注实际使用的模型。Agent 的系统指令INSTRUCTION约束了模型的行为用户想要静态图时调用 image 工具想要走秀动画时调用 video 工具并且必须先向用户索要人像照片、确认目标商品后再调用工具——这是避免盲目调用、浪费生成成本的关键提示词设计。值得注意的一个实现细节ADK 的adk web会根据 agent 模块所在目录自动命名应用而该模块位于scripts/目录下因此 apps.App 的 name 必须显式设为 scripts否则会话创建会因名字不匹配而失败。tryon_processor.py —— 生成引擎层该文件是真正的发动机实现了两个核心函数分别对应架构图的两条路径generate_tryon_image()通过client.models.generate_contentGemini 路径执行图片试穿内置高质量的系统提示词与用户提示词generate_tryon_video()把试穿输出裁剪为三个参考帧、填充到 16:9 画布然后调用 Veo 3.1 的generate_videosR2V API。test_runnability.py中的 test_agent_runnability 验证了scripts.tryon_agent可正常导入且root_agent存在是整个链路可运行性的最小保障。Image VTOGemini 图像生成调用范式架构文档给出了 Image VTO 的 SDK 调用骨架这里结合 tryon_processor.py 的完整实现做深入展开。官方 SDK 调用形态response client.models.generate_content( modelgemini-2.5-flash-image, contents[ types.Part.from_bytes(dataperson_bytes, mime_typeimage/jpeg), types.Part.from_bytes(dataproduct_bytes, mime_typeimage/jpeg), user_task ], configtypes.GenerateContentConfig( response_modalities[IMAGE], system_instructionsystem_prompt, temperature0.1 ) )几个关键参数的实际作用contents 的多模态输入types.Part.from_bytes把用户照片与商品图转为二进制 Part与文本任务指令user_task并列传入实现两张图 一段话的输入结构。_load_image_bytestryon_processor.py负责把本地路径、gs://URI 甚至 base64 字符串统一解析为字节流。response_modalities[IMAGE]显式要求模型返回图像而非文本。temperature0.1极低的温度保证每次生成的构图、姿态与人物一致性减少随机漂移。system_instruction注入时尚摄影师 高级修图师 虚拟试穿专家的身份与硬性规则。高保真提示词的工程细节generate_tryon_image内部构建了两段提示词这是图片质量的关键系统提示词源码要求模型保持人物身份与姿态、必须显示从头到脚的完整身体包括脚与鞋、修复输入噪点与遮罩伪影、统一光照方向/强度/色温、在脚下添加自然柔和阴影最终输出必须像一张单一连贯的照片而非贴图。用户任务提示词源码用编号清单细化了 8 条约束其中特别值得关注的是PRESERVE IDENTITY ANATOMY保持姿势、体型、面部特征与肤色不得改变人物身材比例REPLACE THE CLOTHES服装必须适配这个人而不是把人改造成适配服装COMPLETE THE OUTFIT若未提供全部服装由模型补充风格一致的配套衣物如裤子、鞋UNIFORM LIGHTING / NATURAL SHADOWS / PHOTOREALISTIC RESULT三者共同保证合成图的光影一致性。输出处理与落盘生成后代码会从response.candidates[0].content.parts中筛选出mime_type以image/开头的 inline 图像 Parttryon_processor.py若没有任何图像数据则抛出RuntimeError。随后根据是否配置了output_bucket二选一配置了 bucket通过_upload_to_gcs以vto-images/{uuid4}.jpg的命名上传返回gs://URI未配置保存到本地tmp/vto-outputs/目录返回绝对路径。两种路径都会同时返回image_bytes这正是视频阶段所需的中间产物。Video VTOVeo 3.1 Reference-to-Video 的调用范式架构文档给出了 R2V 的 SDK 调用骨架。与 Image VTO 相比Video VTO 的难点不在 API 本身而在参考帧的预处理——这是 tryon_processor.py 中最具实操价值的部分。SDK 调用形态from google.genai.types import Image, VideoGenerationReferenceImage ref_images_list [] for img_bytes in [lower_body_png, upper_body_png, face_png]: ref_image VideoGenerationReferenceImage( imageImage(imageBytesimg_bytes, mime_typeimage/png), reference_typeasset ) ref_images_list.append(ref_image) operation client.models.generate_videos( modelveo-3.1-generate-001, promptcatwalk animation prompt, configtypes.GenerateVideosConfig( aspect_ratio16:9, number_of_videos1, duration_seconds5, reference_imagesref_images_list, person_generationallow_adult ) )参考帧拆分三个视角喂给 VeoR2V 模式下 Veo 需要参考图像来锁定人物身份与服装细节。实现中把合成试穿图按身体区域拆成三个独立参考帧tryon_processor.pyLower Body下半身裁剪图片底部 60% 区域img.crop((0, int(height * 0.4), width, height))Upper Body上半身裁剪图片顶部 40% 区域Face面部调用crop_face_simple兜底函数取图片顶部 35%、水平居中的区域left0.2*width, right0.8*width这是代码注释中通常承载脸/头部的启发式裁剪。每个参考帧都转成 PNG 字节并以reference_typeasset构建VideoGenerationReferenceImage。三个帧全部显式传入让 Veo 同时掌握全身姿态 服装细节 面部身份三层信息。16:9 画布填充每个裁剪帧随后通过_create_canvas_16_9tryon_processor.py被居中填充到 16:9 画布上比较当前宽高比与目标比16/9过宽则补高、过高则补宽背景色为中性灰(240, 240, 240)。这一步是为满足 Veo 对输入画布比例的约束。走秀提示词与长轮询视频提示词tryon_processor.py把 8 秒动画拆成四个时间序列逐帧规划站立起步 → 向前行走低机位只拍腰部以下→ 镜头缓慢上摇到肩部 → 停步正面直视镜头。全程强调与参考图像中完全相同的人、完全相同的着装并约束头部始终朝前、表情稳定、至多一次自然眨眼。调用完成后代码进入轮询循环每 2 秒调用一次client.operations.get(operation)直到operation.done随后检查operation.error与result.generated_videos[0].video.video_bytes最终把 MP4 上传到vto-videos/{uuid4}.mp4或落盘到本地。需要特别留意的是实现中的两处实际参数与架构文档示例的差异duration_seconds源码中固定为8注释明确写着Veo R2V strictly requires exactly 8 seconds即 R2V 模式严格要求 8 秒架构文档示例中的5是简化示意实际部署应以源码为准aspect_ratio源码使用9:16竖屏走秀与电商手机端展示场景匹配而架构文档示例为16:9同时源码还设置了generate_audioFalse。若你需要横屏输出可依据 Veo 在该区域的可用比例调整。配置项与运行环境整个技能的所有可配置值集中在 config.py 的config对象中采用惰性读取设计——每次属性访问都实时调用os.getenv()因此脚本运行时修改环境变量能立即生效。核心变量如下环境变量默认值说明GOOGLE_CLOUD_PROJECT空GCP 项目 ID未设置时两个工具函数都会返回错误GCP_REGIONus-west1Gemini 图像 / Veo 部署区域GEMINI_MODEL_LOCATIONglobalVertex AI 调用位置Gemini 系模型通常走globalGEMINI_IMAGE_MODELgemini-2.5-flash-image图片试穿模型支持flash/pro别名GEMINI_MODELgemini-3.5-flashADK Agent 自身的对话模型TRYON_OUTPUT_BUCKET空生成结果图/视频上传的 GCS bucketTRYON_UPLOAD_BUCKET空用户照片临时上传的 bucket默认 24 小时自动删除TRYON_CATALOG_PATHcatalog_images商品目录路径本地文件夹、demo或gs://URIPORT8080本地沙箱服务端口模型访问前置条件依据 README.md需要gemini-2.5-flash-image试穿、gemini-3.5-flashAgent 与目录分类器的模型访问权限若启用走秀视频还需要 Veoveo-3.1-generate-001访问权限。scripts/setup_tryon.py会帮你自动启用 Gemini Enterprise Agent Platform 与 Cloud Storage API并为默认 Compute 服务账号授予roles/aiplatform.user与roles/storage.objectAdmin两个角色。从架构到落地ADK 运行、测试与部署通过 ADK Web 交互测试按 SKILL.md 的指引先设置环境变量export GOOGLE_CLOUD_PROJECTyour-project-id export TRYON_OUTPUT_BUCKETyour-project-id-tryon-output export TRYON_UPLOAD_BUCKETyour-project-id-tryon-uploads export GEMINI_IMAGE_MODELflash # 或 pro / gemini-2.5-flash-image / gemini-2.5-pro-image然后启动 ADK Web UI务必使用.venv/bin/adk而非裸adk否则可能解析到全局 Python 导致/list-apps返回空列表.venv/bin/adk web .在聊天会话中提供商品 ID如shirt_001或sunglasses_001、上传catalog_images/sample_user.jpg或任意人像照片即可下达帮我试穿这件衬衫或生成一段戴着这副墨镜走秀的视频等指令。直接 Python 冒烟测试不启动 UI直接调用 ADK 工具函数验证链路# 测试图片试穿 .venv/bin/python -c from scripts.tryon_agent import try_on_product_image res try_on_product_image(shirt_001, catalog_images/sample_user.jpg, catalog_images/shirt_001.jpg, clothing, red shirt) print(res) # 测试视频试穿Veo .venv/bin/python -c from scripts.tryon_agent import try_on_product_video res try_on_product_video(sunglasses_001, catalog_images/sample_user.jpg, catalog_images/sunglasses_001.jpg, eyewear, sunglasses) print(res) 部署为 Cloud Run Web 应用仓库通过 export_app.py 生成独立容器化代码库再部署到 Cloud Run.venv/bin/python $SKILL_DIR/scripts/export_app.py --config ./design-spec.md --skill-dir $SKILL_DIR gcloud run deploy vto-retail-app --source ./vto-retail-app/ --region us-west1 --project {gcp_project_id} --allow-unauthenticated部署后可通过gcloud run services describe获取服务 URL并支持gsutil -m rsync同步商品目录、curl https://{cloud_run_url}/api/catalog?forcetrue强制刷新索引还可以用 iframe 把试穿组件直接嵌入电商商品详情页。常见问题排查依据 SKILL.md 的 Troubleshooting 表与 README.md 的失败模式说明错误现象可能原因修复方式BILLING_DISABLEDGCP 项目未绑定结算账号在 Cloud Console 关联结算账号API has not been used/disabled所需 API 未启用运行gcloud services enable aiplatform.googleapis.com storage.googleapis.comGCS 上PermissionDenied服务账号权限不足授予roles/storage.adminMethodNotImplemented: 501/Model not found所选模型在当前区域不可用检查项目区域的模型可用性404 NOT_FOUND: Publisher model ... was not found模型名在 Gemini Enterprise Agent Platform 中不存在目前仅有gemini-2.5-flash-image与gemini-2.5-pro-image检查GEMINI_IMAGE_MODEL环境变量图像渲染正常但脸部变形Veo 参考帧的面部裁剪不干净换用更高分辨率的人像照片重试视频生成卡在 Generating catwalk... 超过 90 秒Veo 3.1 配额耗尽或模型过载查看沙箱日志中的503/429错误此外视频生成耗时约 30-60 秒属正常现象Veo 长轮询需要耐心等待用户照片默认上传到带24 小时自动删除生命周期规则的 uploads bucket由setup_tryon.py自动配置这既满足隐私合规要求也是生产环境应保留的默认行为。小结retail-virtual-tryon 的架构本质是一条**图片生成为视频生成奠基的两级流水线**tryon_agent.py负责把底层能力暴露为 ADK 工具并收敛异常tryon_processor.py负责 Gemini 图像合成、参考帧拆分、16:9 画布填充与 Veo 长轮询。理解 tryon-architecture.md 中的两张 SDK 调用范式再对照 tryon_processor.py 的完整实现你就能在自己的项目中复刻这套图片 走秀视频双模态虚拟试穿能力并将其无缝嵌入 ADK Agent 驱动的零售电商应用。【免费下载链接】adk-samplesA collection of sample agents built with Agent Development Kit (ADK)项目地址: https://gitcode.com/GitHub_Trending/ad/adk-samples创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考