SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场retail-virtual-tryon

retail-virtual-tryon

智能体与模型

查看项目

更新于 10-16 06:00

技能介绍

用途

retail-virtual-tryon 用于在 Google Cloud 上创建虚拟试穿（Virtual Try-On，VTO）智能体，支持两种试穿模式：图片试穿与视频（走秀动画）试穿。它面向电商场景，可用于搭建虚拟试衣间、生成走秀风格的视频动画以展示服装穿着效果，也支持配饰、珠宝、眼镜、服装等一般零售品类的试穿。

该技能明确不适用于家具/家居布置（应使用房间摆放类工具），也不适用于复杂 3D 虚拟形象创建。

主要能力

  • 图片试穿：基于 Gemini 图像模型生成静态试穿图。
  • 视频试穿：通过 Veo 生成走秀（catwalk）动画视频。
  • 目录管理：支持使用内置演示目录、本地文件夹或 gs:// URI 作为商品目录；可将本地目录上传同步到 GCS。
  • 本地沙盒：提供 FastAPI 本地服务器与沙盒仪表盘，可上传自拍、选择商品卡片并生成试穿图；支持扫描自定义本地图片文件夹（使用 Gemini 自动编目与描述）。
  • 导出与部署：可导出独立容器化代码库，并部署到 Google Cloud Run，提供可嵌入网站的 iframe 组件。

使用方式

技能有两种运行模式，首次调用时须先输出 Q-MODE 选择菜单并等待用户选择：

  • 模式 1：快速开始（Quick start）——本地测试沙盒，交互式 6 问配置，约 90 秒，适合演示。
  • 模式 2：导出 Web 应用并同步 GCS 目录（Export Web App & GCS Catalog Sync）——生成独立容器化代码库、GCS 目录同步与 Cloud Run 配置，约 3 分钟。

工作区准备（须作为一条 shell 命令执行）：

SKILL_DIR=$(for d in ~/.claude/skills ~/.agents/skills ~/.gemini/skills ~/.cursor/skills; do
  [ -f "$d/retail-virtual-tryon/SKILL.md" ] && echo "$d/retail-virtual-tryon" && break
done)
bash "$SKILL_DIR/scripts/bootstrap.sh"

bootstrap.sh 会查找 Python 3.11+ 解释器、创建 .venv、以可编辑方式安装技能，并将 design-spec.md 复制到工作区。所有脚本从安装目录运行、针对工作区配置，须使用 .venv/bin/python 而非裸 python。

资源设置：

.venv/bin/python "$SKILL_DIR/scripts/setup.py" --config ./design-spec.md

成功后会在 ./catalog_images/ 下生成本地示例目录图片（若指定了 GCS 存储桶或自定义目录路径，则改为验证存储桶访问）。

模式 1 收集的问题包括：GCP 项目 ID、试穿模式（默认 2，即图片+Veo 视频）、GCP 区域（默认 us-west1）、目录路径（demo / 本地文件夹 / gs:// URI）、是否将本地目录上传到 GCS。随后写入 ./design-spec.md 并运行 setup.py，再后台启动本地沙盒服务器：

.venv/bin/python "$SKILL_DIR/scripts/start_sandbox.py" --config ./design-spec.md

浏览器打开 http://localhost:8080 即可测试。

模式 2 收集的问题包括：GCP 项目 ID、试穿模式、GCS 目录存储桶名称（默认 {project_id}-tryon-catalog）、导出目标目录（默认 ./vto-retail-app）。随后运行：

.venv/bin/python "$SKILL_DIR/scripts/export_app.py" --config ./design-spec.md --skill-dir "$SKILL_DIR"
.venv/bin/python "$SKILL_DIR/scripts/setup_tryon.py" --config ./design-spec.md
gcloud run deploy vto-retail-app --source ./vto-retail-app/ --region us-west1 --project {gcp_project_id} --allow-unauthenticated
gcloud run services describe vto-retail-app --region us-west1 --project {gcp_project_id} --format="value(status.url)"

目录同步与索引刷新：

gsutil -m rsync -r ./my_clothes/ gs://{gcs_catalog_bucket}/
curl -X GET "https://{cloud_run_url}/api/catalog?force=true"

嵌入网站：

<iframe src="https://{cloud_run_url}" width="100%" height="800px" style="border:none; border-radius:12px; box-shadow: 0 4px 20px rgba(0,0,0,0.15);"></iframe>

测试与验证：需在运行智能体的 shell 中设置环境变量：

export GOOGLE_CLOUD_PROJECT="<your-project-id>"
export TRYON_OUTPUT_BUCKET="<your-project-id>-tryon-output"
export TRYON_UPLOAD_BUCKET="<your-project-id>-tryon-uploads"
export GEMINI_IMAGE_MODEL="flash"  # 或 pro / gemini-2.5-flash-image / gemini-2.5-pro-image

使用 adk web 启动交互式 Web UI（须用 .venv/bin/adk）：

.venv/bin/adk web .

可在聊天会话中提供商品 ID（如 shirt_001 或 sunglasses_001）、用户照片（如 catalog_images/sample_user.jpg）以及请求（如“Try on this shirt for me”）。

直接 Python 冒烟测试：

.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)
"

.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)
"

评估：使用本地评估 YAML 验证输出，确保图像一致性、服装位置正确且无视觉失真。

沙盒可视化测试：启动 FastAPI 本地服务器后打开 http://localhost:8080，上传自拍、选择商品卡片并点击 Generate Try-On Image；在搜索栏输入自定义本地文件夹路径并点击 Scan 可索引该文件夹（使用 Gemini 自动编目与描述）。

适用场景

  • 为电商搭建虚拟试穿试衣间。
  • 创建交互式走秀风格视频动画，展示服装穿着行走时的效果。
  • 为配饰、珠宝、眼镜或服装提供一般零售试穿。

限制与注意事项

  • 不适用于家具/家居布置，也不适用于复杂 3D 虚拟形象创建。
  • Veo 视频生成约需 30–60 秒，需耐心等待。
  • 图像模型建议使用 flash（推荐）或 pro。
  • 隐私合规：用户照片会临时上传到 uploads 存储桶，并配置 24 小时生命周期自动删除规则（由 setup_tryon.py 自动配置）。
  • 收到“我想在 GCP 上创建/部署 VTO 应用”这类一般请求时，不得自动运行 setup_tryon.py、export_app.py、deploy_cloudrun.sh 等脚本，必须先展示 Q-MODE 菜单并等待用户选择。
  • 在快速开始启动 setup 之前，用户可说 export、webapp 或 deploy 切换到模式 2，已给出的项目、模式、区域答案会沿用；一旦 setup.py 已开始创建存储桶/API，流程即已确定，若要改用模式 2 需新建工作区。

故障排查

  • BILLING_DISABLED：GCP 项目未启用结算，需在 Cloud Console 关联结算账户。
  • API has not been used / disabled：所需 API 未启用，运行 gcloud services enable aiplatform.googleapis.com storage.googleapis.com。
  • PermissionDenied on GCS：服务账号权限不足，授予 roles/storage.admin。
  • MethodNotImplemented: 501 / Model not found：所选模型在该区域不可用，检查 GCP 项目区域可用性。

完成检查清单

  • GCP 项目 ID 与试穿模式已配置。
  • GCP 资源已配置并验证（存储桶、Gemini Enterprise Agent Platform API）。
  • 示例目录已生成。
  • 图片试穿冒烟测试通过。
  • 使用 Veo 的走秀视频生成已验证。