feat: search image by tencent tiia

api_v1/utils/tencentcloud_tiia.py

@@ -45,6 +45,90 @@ class SimpleRateLimiter:
             time.sleep(self._min_interval - elapsed)
         self._last_ts = time.monotonic()
 
+def search_image_url_in_tencent_tiia(
+    *,
+    image_url: str,
+    limit: int | None = 10,
+    offset: int | None = 0,
+    match_threshold: int | None = None,
+    rate_limiter: SimpleRateLimiter | None = None,
+) -> dict:
+    """
+    Search an image by URL in Tencent Cloud TIIA gallery using SearchImage.
+
+    This is the counterpart of CreateImage (upload) and is typically used for "similar image search".
+
+    Required settings:
+    - TENCENTCLOUD_SECRET_ID
+    - TENCENTCLOUD_SECRET_KEY
+    - TENCENTCLOUD_TIIA_GROUP_ID
+
+    Optional settings:
+    - TENCENTCLOUD_TOKEN                      (STS token, if applicable)
+    - TENCENTCLOUD_TIIA_REGION                (default: ap-guangzhou)
+    - TENCENTCLOUD_TIIA_ENDPOINT              (default: tiia.tencentcloudapi.com)
+
+    Args:
+        image_url: Absolute URL to search.
+        limit/offset/match_threshold: Optional SearchImage request parameters.
+        rate_limiter: Optional in-process limiter to keep requests under QPS.
+
+    Returns:
+        Parsed JSON response dict from TencentCloud SDK.
+    """
+    image_url = (image_url or '').strip()
+    if not image_url:
+        raise ValueError('image_url 不能为空')
+
+    parsed = urlparse(image_url)
+    if not (parsed.scheme and parsed.netloc):
+        raise ValueError('image_url 必须为绝对 URL（包含 scheme 与 host）')
+
+    group_id = (getattr(settings, 'TENCENTCLOUD_TIIA_GROUP_ID', '') or '').strip()
+    if not group_id:
+        raise ValueError('缺少 settings: TENCENTCLOUD_TIIA_GROUP_ID')
+
+    secret_id = (getattr(settings, 'TENCENTCLOUD_SECRET_ID', '') or '').strip()
+    secret_key = (getattr(settings, 'TENCENTCLOUD_SECRET_KEY', '') or '').strip()
+    token = (getattr(settings, 'TENCENTCLOUD_TOKEN', '') or '').strip() or None
+    if not secret_id or not secret_key:
+        raise ValueError('缺少 settings: TENCENTCLOUD_SECRET_ID / TENCENTCLOUD_SECRET_KEY')
+
+    region = (getattr(settings, 'TENCENTCLOUD_TIIA_REGION', None) or 'ap-guangzhou').strip()
+    endpoint = (getattr(settings, 'TENCENTCLOUD_TIIA_ENDPOINT', None) or 'tiia.tencentcloudapi.com').strip()
+
+    try:
+        from tencentcloud.common import credential
+        from tencentcloud.common.profile.client_profile import ClientProfile
+        from tencentcloud.common.profile.http_profile import HttpProfile
+        from tencentcloud.tiia.v20190529 import tiia_client, models
+    except Exception as e:  # pragma: no cover
+        raise RuntimeError(
+            "TencentCloud SDK 未安装或不可用，请先安装依赖：tencentcloud-sdk-python"
+        ) from e
+
+    if rate_limiter is not None:
+        rate_limiter.wait()
+
+    cred = credential.Credential(secret_id, secret_key, token)
+    http_profile = HttpProfile(endpoint=endpoint, reqTimeout=30)
+    client_profile = ClientProfile(httpProfile=http_profile)
+    client = tiia_client.TiiaClient(cred, region, client_profile)
+
+    req = models.SearchImageRequest()
+    req.GroupId = str(group_id)
+    req.ImageUrl = str(image_url)
+
+    if limit is not None:
+        req.Limit = int(limit)
+    if offset is not None:
+        req.Offset = int(offset)
+    if match_threshold is not None:
+        req.MatchThreshold = int(match_threshold)
+
+    resp = client.SearchImage(req)
+    return json.loads(resp.to_json_string())
+
 
 def upload_image_url_to_tencent_tiia(*, image_url: str, entity_id: str) -> dict:
     """
@@ -239,6 +323,7 @@ def upload_plate_order_images_to_tencent_tiia(*, plate_order_id: int, rate_limit
 __all__ = [
     'SimpleRateLimiter',
     'upload_image_url_to_tencent_tiia',
+    'search_image_url_in_tencent_tiia',
     'upload_plate_order_images_to_tencent_tiia',
 ]