erpnew/docs/tiia_image_gallery.md

腾讯云 TIIA 图库（PlateOrder 图片上传 & 搜图）说明

背景与目标

本项目接入腾讯云 TIIA（Image and Video AI）的“图库”能力，用于：

• 将 printing.PlateOrder 的图片（通过 ImageUrl）上传到 TIIA 图库（CreateImage）
• 通过输入图片（URL 或 Base64）在图库中做相似图检索（SearchImage）

---

一、配置（settings + .env）

配置集中在 flower/settings.py，建议通过 .env 注入：

• TENCENTCLOUD_SECRET_ID
• TENCENTCLOUD_SECRET_KEY
• TENCENTCLOUD_TOKEN（可选，STS）
• TENCENTCLOUD_TIIA_GROUP_ID（当前默认 168）
• TENCENTCLOUD_TIIA_REGION（默认 ap-guangzhou）
• TENCENTCLOUD_TIIA_ENDPOINT（默认 tiia.tencentcloudapi.com）
• TENCENTCLOUD_TIIA_PIC_NAME_PREFIX（默认 plate_order）
• TENCENTCLOUD_TIIA_QPS（默认 10，用于限速）

说明：

• 本项目通过 django-environ 读取 .env（Env.read_env(BASE_DIR / '.env')）
• 本项目依赖 tencentcloud-sdk-python；在容器/服务启动方式不同的情况下，请确保运行使用的是同一套依赖环境（推荐 uv run ...）。

---

二、上传到图库（CreateImage）

2.1 基础上传函数（上传单张 ImageUrl）

位置：api_v1/utils/tencentcloud_tiia.py

• upload_image_url_to_tencent_tiia(image_url, entity_id, tags=None, custom_content=None)

行为（当前约定）：

• GroupId 固定从 settings 读取
• EntityId 由调用方传入（在 PlateOrder 场景中= str(plate_order_id)）
• PicName 自动生成（带 TENCENTCLOUD_TIIA_PIC_NAME_PREFIX）
• ImageUrl 使用传入的 image_url
• CustomContent 默认写入完整 image_url
• Tags 默认不写入（避免触发“标签值长度过长”）

注意：腾讯云 SearchImage 的返回结构默认不包含 ImageUrl；如果你希望在搜图结果里拿到可访问 URL，建议依赖 CustomContent（前提是腾讯云搜图返回里会回传该字段）。

2.2 PlateOrder 批量上传（读取 plate_image）

位置：api_v1/utils/tencentcloud_tiia.py

• upload_plate_order_images_to_tencent_tiia(plate_order_id, rate_limiter=None)

行为：

• 查询 printing.PlateOrder(id=plate_order_id)
• 从 plate_image(JSONField) 提取所有图片 URL/Path（兼容多种字段名与格式），并标准化为公网可访问 URL
• 对每张图片调用 upload_image_url_to_tencent_tiia(...)
• 单张失败不抛出，返回每张图片的结果列表（便于落库/排查）

---

三、定时任务（Celery Beat：每天 03:00 上传“昨天创建的订单”）

3.1 Task 本体

位置：printing/tasks.py

• upload_yesterday_plate_order_images_to_tencent_tiia

行为：

• 计算“昨天”的日期范围 [start, end)
• 遍历 created_at 落在该范围内的所有 PlateOrder
• 逐单上传 plate_image 中所有图片
• 遇错：记录失败并继续处理下一个订单
• 使用 SimpleRateLimiter(qps=TENCENTCLOUD_TIIA_QPS) 控制 QPS（默认 10）

3.2 Beat 调度配置

位置：flower/settings.py

• CELERY_BEAT_SCHEDULE['daily_plate_order_tiia_image_upload']
  • task = 'printing.tasks.upload_yesterday_plate_order_images_to_tencent_tiia'
  • schedule = crontab(hour=3, minute=0)

说明：

• 仅配置 schedule 不代表一定在跑；需要线上同时运行 celery worker + celery beat。

---

四、失败记录（可追踪/可重试）

位置：printing/models.py

• PlateOrderTiiaUploadFailure
  • run_date / plate_order_id / error / details / attempts / last_attempt_at
  • 唯一约束：(run_date, plate_order_id)，同日重复失败会累加 attempts

可在 Django Admin 中查看（printing/admin.py 已注册）。

---

五、手动跑批（推荐：management command）

位置：printing/management/commands/tiia_upload_plate_order_images.py

常用：

• 全量跑批：uv run python manage.py tiia_upload_plate_order_images --all
• 跑昨天：uv run python manage.py tiia_upload_plate_order_images --yesterday
• 跑某天：uv run python manage.py tiia_upload_plate_order_images --date 2026-01-15
• 跑单个：uv run python manage.py tiia_upload_plate_order_images --plate-order-id 123
• 小批量验证：uv run python manage.py tiia_upload_plate_order_images --all --limit 20
• Dry-run：uv run python manage.py tiia_upload_plate_order_images --all --dry-run

说明：

• 同样遵守 TENCENTCLOUD_TIIA_QPS 的限速，并会落库失败记录。

---

六、搜图 API（简化版：SearchImage）

6.1 接口

• POST /api/v1/tiia/search-image/

参数（JSON body）：

• imageUrl：图片 URL（优先）
• imageBase64：Base64（可选，若无 imageUrl）
• limit：可选，1~100（默认腾讯云 10；本项目已透传）
• offset：可选，>=0
• matchThreshold：可选，0~100

6.2 返回

• 直接返回腾讯云 SearchImage 的原始响应 JSON

6.3 已知限制/注意点

• 腾讯云 SearchImage 返回结果通常以 EntityId/PicName/Score/Tags/CustomContent 为主，不一定直接提供可访问 ImageUrl
• 如果期望在搜图结果里拿到可访问 URL，请优先依赖上传时写入的 CustomContent

---

七、排障清单（常见问题）

• SDK 导入失败（No module named 'tencentcloud'）：
  • 确认使用 uv run python ...（确保解释器与依赖一致）
• 腾讯云返回“标签值长度过长”：
  • 不要默认写入 Tags；本项目已改为默认不写 Tags
• 任务未触发：
  • 检查是否同时运行 celery worker + celery beat
  • 检查 CELERY_BROKER_URL / CELERY_RESULT_BACKEND 是否可用