gshield-pic-sdk 0.1.0__tar.gz

gshield_pic_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gshield_pic_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: gshield-pic-sdk
+Version: 0.1.0
+Summary: Unified SDK for Face detection, Faiss vector match, and Triton gRPC inference
+Author-email: Gentel <jiaweiye@gentel.com>
+License: MIT
+Project-URL: Homepage, https://github.com/your-org/your-repo
+Project-URL: Repository, https://github.com/your-org/your-repo
+Project-URL: Documentation, https://github.com/your-org/your-repo#readme
+Keywords: face-detection,faiss,triton,inference,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Requires-Dist: numpy>=1.20.0
+Requires-Dist: Pillow>=9.0.0
+Requires-Dist: opencv-python-headless>=4.5.0
+Requires-Dist: tritonclient[grpc]>=2.30.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# GshieldPicSDK
+
+统一调用 **Face 检测**、**Faiss 向量匹配**、**Triton gRPC 推理** 的 Python SDK。所有服务地址由用户提供，SDK 内不写死默认 URL。
+
+## 安装
+
+**从 PyPI 安装（发布后）：**
+
+```bash
+pip install gshield-pic-sdk
+```
+
+**从本地源码安装（开发或未发布时）：**
+
+```bash
+pip install -e api_server/GshieldPicSDK
+```
+
+依赖：`requests`, `numpy`, `Pillow`, `opencv-python-headless`, `tritonclient[grpc]`。
+
+**发布到 PyPI**：参见 [docs/PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md)。
+
+## 配置说明
+
+- **所有 URL 由用户提供**：`face_base_url`、`faiss_base_url`、`triton_url` 仅通过构造函数传入，或通过环境变量 `GSHIELD_FACE_URL`、`GSHIELD_FAISS_URL`、`GSHIELD_TRITON_URL` 指定；构造函数参数优先。
+- **gRPC 标签目录**：调用 Triton 推理时必须提供 `label_dir`（存放各模型对应的 `.txt` 标签文件），也可通过环境变量 `GSHIELD_LABEL_DIR` 指定。
+- **mode 快速配置**：gRPC 支持的模型列表（mode）、标签文件映射、精度配置集中在 `gshield_pic_sdk.grpc_config` 中；新增/修改 mode 时只需改该模块或通过 `get_grpc_config(custom_label_map=..., custom_data_types=..., custom_modes_list=...)` 覆盖。
+
+## 使用示例
+
+```python
+from gshield_pic_sdk import GshieldPicClient
+
+# 按需传入各服务地址与标签目录（无默认写死地址）
+client = GshieldPicClient(
+    face_base_url="http://localhost:8001",
+    faiss_base_url="http://localhost:8000",
+    triton_url="localhost:8501",
+    label_dir="/path/to/model_inference/labels",
+)
+
+# 图片支持：文件路径(str)、bytes、numpy ndarray (BGR/RGB 均可，SDK 内部统一处理)
+image_path = "/path/to/photo.jpg"
+
+# 人脸检测
+resp = client.face.detect(image_path)
+print(resp["faces"], resp["count"])
+
+# Faiss 向量匹配
+match_result = client.faiss.match(image_path)
+print(match_result["allowed"], match_result["in_blacklist"], match_result["in_whitelist"])
+
+# 黑名单/白名单 增删
+# client.faiss.blacklist_add(image_path, description="样例")
+# client.faiss.whitelist_add(image_path, description="允许")
+
+# Triton 单模型推理
+label = client.grpc.infer("fire", image_path)
+print(label)
+
+# 全量 mode 推理
+all_labels = client.grpc.infer_all(image_path)
+print(all_labels)
+```
+
+仅使用部分能力时，只传对应 URL 即可；未配置的客户端在访问时会抛出 `GshieldValueError`（如 `face_base_url not configured`）。
+
+## 图片输入
+
+- 支持 **str**（文件路径）、**bytes**、**numpy ndarray**（HWC，BGR 或 RGB 均可，SDK 内部会统一为 Triton 所需格式）。
+
+## 异常
+
+- `GshieldConnectionError`：网络或服务连接失败（HTTP 4xx/5xx、Triton 不可用等）。
+- `GshieldValueError`：参数错误（未配置 URL、mode 不存在、图片格式无效等）。
+- `GshieldInferError`：推理过程失败。
+
+## gRPC mode 列表与配置
+
+与现有 `client_test_grpc` 行为一致，支持的 mode 包括：fire, politics, qrcode, prohibitlogo, chinamap, discomfort, discomfort_excrement, gamble, tattoo, tiananmen, trypophobia, blood, military, flag_detect, flag_classification, porn_classification, nsfw, emblem, religion_symbol, religion_activity, religion_clothes, media1, media2, porn, flag 等。完整列表与标签/精度配置见 `gshield_pic_sdk.grpc_config`；后续更新 mode 只需改该处或通过 `get_grpc_config(custom_*)` 覆盖。

gshield_pic_sdk-0.1.0/README.md

@@ -0,0 +1,80 @@
+# GshieldPicSDK
+
+统一调用 **Face 检测**、**Faiss 向量匹配**、**Triton gRPC 推理** 的 Python SDK。所有服务地址由用户提供，SDK 内不写死默认 URL。
+
+## 安装
+
+**从 PyPI 安装（发布后）：**
+
+```bash
+pip install gshield-pic-sdk
+```
+
+**从本地源码安装（开发或未发布时）：**
+
+```bash
+pip install -e api_server/GshieldPicSDK
+```
+
+依赖：`requests`, `numpy`, `Pillow`, `opencv-python-headless`, `tritonclient[grpc]`。
+
+**发布到 PyPI**：参见 [docs/PYPI_PUBLISHING.md](docs/PYPI_PUBLISHING.md)。
+
+## 配置说明
+
+- **所有 URL 由用户提供**：`face_base_url`、`faiss_base_url`、`triton_url` 仅通过构造函数传入，或通过环境变量 `GSHIELD_FACE_URL`、`GSHIELD_FAISS_URL`、`GSHIELD_TRITON_URL` 指定；构造函数参数优先。
+- **gRPC 标签目录**：调用 Triton 推理时必须提供 `label_dir`（存放各模型对应的 `.txt` 标签文件），也可通过环境变量 `GSHIELD_LABEL_DIR` 指定。
+- **mode 快速配置**：gRPC 支持的模型列表（mode）、标签文件映射、精度配置集中在 `gshield_pic_sdk.grpc_config` 中；新增/修改 mode 时只需改该模块或通过 `get_grpc_config(custom_label_map=..., custom_data_types=..., custom_modes_list=...)` 覆盖。
+
+## 使用示例
+
+```python
+from gshield_pic_sdk import GshieldPicClient
+
+# 按需传入各服务地址与标签目录（无默认写死地址）
+client = GshieldPicClient(
+    face_base_url="http://localhost:8001",
+    faiss_base_url="http://localhost:8000",
+    triton_url="localhost:8501",
+    label_dir="/path/to/model_inference/labels",
+)
+
+# 图片支持：文件路径(str)、bytes、numpy ndarray (BGR/RGB 均可，SDK 内部统一处理)
+image_path = "/path/to/photo.jpg"
+
+# 人脸检测
+resp = client.face.detect(image_path)
+print(resp["faces"], resp["count"])
+
+# Faiss 向量匹配
+match_result = client.faiss.match(image_path)
+print(match_result["allowed"], match_result["in_blacklist"], match_result["in_whitelist"])
+
+# 黑名单/白名单 增删
+# client.faiss.blacklist_add(image_path, description="样例")
+# client.faiss.whitelist_add(image_path, description="允许")
+
+# Triton 单模型推理
+label = client.grpc.infer("fire", image_path)
+print(label)
+
+# 全量 mode 推理
+all_labels = client.grpc.infer_all(image_path)
+print(all_labels)
+```
+
+仅使用部分能力时，只传对应 URL 即可；未配置的客户端在访问时会抛出 `GshieldValueError`（如 `face_base_url not configured`）。
+
+## 图片输入
+
+- 支持 **str**（文件路径）、**bytes**、**numpy ndarray**（HWC，BGR 或 RGB 均可，SDK 内部会统一为 Triton 所需格式）。
+
+## 异常
+
+- `GshieldConnectionError`：网络或服务连接失败（HTTP 4xx/5xx、Triton 不可用等）。
+- `GshieldValueError`：参数错误（未配置 URL、mode 不存在、图片格式无效等）。
+- `GshieldInferError`：推理过程失败。
+
+## gRPC mode 列表与配置
+
+与现有 `client_test_grpc` 行为一致，支持的 mode 包括：fire, politics, qrcode, prohibitlogo, chinamap, discomfort, discomfort_excrement, gamble, tattoo, tiananmen, trypophobia, blood, military, flag_detect, flag_classification, porn_classification, nsfw, emblem, religion_symbol, religion_activity, religion_clothes, media1, media2, porn, flag 等。完整列表与标签/精度配置见 `gshield_pic_sdk.grpc_config`；后续更新 mode 只需改该处或通过 `get_grpc_config(custom_*)` 覆盖。

gshield_pic_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "gshield-pic-sdk"
+version = "0.1.0"
+description = "Unified SDK for Face detection, Faiss vector match, and Triton gRPC inference"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "Gentel", email = "jiaweiye@gentel.com"}
+]
+keywords = ["face-detection", "faiss", "triton", "inference", "sdk"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+]
+dependencies = [
+    "requests>=2.28.0",
+    "numpy>=1.20.0",
+    "Pillow>=9.0.0",
+    "opencv-python-headless>=4.5.0",
+    "tritonclient[grpc]>=2.30.0",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "responses>=0.23.0"]
+
+[project.urls]
+Homepage = "https://github.com/your-org/your-repo"
+Repository = "https://github.com/your-org/your-repo"
+Documentation = "https://github.com/your-org/your-repo#readme"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]

gshield_pic_sdk-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

gshield_pic_sdk-0.1.0/src/gshield_pic_sdk/__init__.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+"""GshieldPicSDK: 统一调用 Face、Faiss、Triton gRPC 的 Python SDK。"""
+
+from gshield_pic_sdk.client import GshieldPicClient
+from gshield_pic_sdk.face_client import FaceClient
+from gshield_pic_sdk.faiss_client import FaissClient
+from gshield_pic_sdk.grpc_client import GrpcInferClient
+from gshield_pic_sdk.exceptions import (
+    GshieldError,
+    GshieldConnectionError,
+    GshieldValueError,
+    GshieldInferError,
+)
+
+__all__ = [
+    "GshieldPicClient",
+    "FaceClient",
+    "FaissClient",
+    "GrpcInferClient",
+    "GshieldError",
+    "GshieldConnectionError",
+    "GshieldValueError",
+    "GshieldInferError",
+]

gshield_pic_sdk-0.1.0/src/gshield_pic_sdk/_image.py

@@ -0,0 +1,85 @@
+# -*- coding: utf-8 -*-
+"""图片入参统一：path/bytes/ndarray 转为 HTTP 上传用 bytes 或 gRPC 用 RGB ndarray。"""
+import os
+from typing import Union
+
+import cv2
+import numpy as np
+
+ImageInput = Union[str, bytes, np.ndarray]
+
+
+def to_bytes(image: ImageInput) -> bytes:
+    """
+    将图片转为 HTTP 上传用的 bytes。
+    :param image: 文件路径(str)、bytes、或 HWC BGR/RGB ndarray (uint8)
+    :return: JPEG 编码的 bytes
+    """
+    if isinstance(image, str):
+        if not os.path.isfile(image):
+            raise ValueError(f"image path not found: {image}")
+        with open(image, "rb") as f:
+            data = f.read()
+        if not data:
+            raise ValueError("image file is empty")
+        return data
+    if isinstance(image, bytes):
+        if not image:
+            raise ValueError("image bytes is empty")
+        return image
+    if isinstance(image, np.ndarray):
+        if image.size == 0:
+            raise ValueError("image ndarray is empty")
+        if image.ndim != 3 or image.shape[-1] != 3:
+            raise ValueError("image ndarray must be HWC with 3 channels")
+        # cv2.imencode 期望 BGR；若已是 RGB 则先转 BGR 再编码
+        if _is_likely_rgb(image):
+            image = cv2.cvtColor(image, cv2.COLOR_RGB2BGR)
+        ok, buf = cv2.imencode(".jpg", image)
+        if not ok:
+            raise ValueError("failed to encode ndarray as jpeg")
+        return buf.tobytes()
+    raise ValueError(f"image must be str, bytes or ndarray, got {type(image)}")
+
+
+def _is_likely_rgb(arr: np.ndarray) -> bool:
+    """启发式：若均值 R > B 则视为 RGB（通常自然图 R>=B）。"""
+    if arr.shape[-1] != 3:
+        return False
+    r, g, b = arr[..., 0].mean(), arr[..., 1].mean(), arr[..., 2].mean()
+    return r >= b
+
+
+def to_rgb_ndarray(image: ImageInput) -> np.ndarray:
+    """
+    将图片转为 HWC RGB uint8 ndarray，供 gRPC 预处理使用。
+    :param image: 文件路径(str)、bytes、或 HWC BGR/RGB ndarray
+    :return: HWC RGB uint8, contiguous
+    """
+    if isinstance(image, str):
+        if not os.path.isfile(image):
+            raise ValueError(f"image path not found: {image}")
+        img = cv2.imread(image)
+        if img is None:
+            raise ValueError(f"failed to read image: {image}")
+        img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+        return np.ascontiguousarray(img)
+    if isinstance(image, bytes):
+        if not image:
+            raise ValueError("image bytes is empty")
+        buf = np.frombuffer(image, dtype=np.uint8)
+        img = cv2.imdecode(buf, cv2.IMREAD_COLOR)
+        if img is None:
+            raise ValueError("failed to decode image bytes")
+        img = cv2.cvtColor(img, cv2.COLOR_BGR2RGB)
+        return np.ascontiguousarray(img)
+    if isinstance(image, np.ndarray):
+        if image.size == 0 or image.ndim != 3 or image.shape[-1] != 3:
+            raise ValueError("image ndarray must be HWC with 3 channels")
+        # 约定：ndarray 按 OpenCV 惯例视为 BGR，统一转为 RGB
+        out = cv2.cvtColor(image, cv2.COLOR_BGR2RGB)
+        out = np.ascontiguousarray(out)
+        if out.dtype != np.uint8:
+            out = out.astype(np.uint8)
+        return out
+    raise ValueError(f"image must be str, bytes or ndarray, got {type(image)}")

gshield_pic_sdk-0.1.0/src/gshield_pic_sdk/client.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+"""统一入口：Face、Faiss、gRPC 子客户端组装。"""
+import os
+from typing import Optional
+
+from gshield_pic_sdk.exceptions import GshieldValueError
+from gshield_pic_sdk.face_client import FaceClient
+from gshield_pic_sdk.faiss_client import FaissClient
+from gshield_pic_sdk.grpc_client import GrpcInferClient
+from gshield_pic_sdk.grpc_config import get_grpc_config
+
+
+def _env(key: str) -> Optional[str]:
+    v = os.environ.get(key, "").strip()
+    return v or None
+
+
+class GshieldPicClient:
+    """
+    统一客户端：所有 URL 由用户传入（或从环境变量读取），不写死默认地址。
+    仅配置了的服务才有对应子客户端，未配置时访问会报错。
+    """
+
+    def __init__(
+        self,
+        face_base_url: Optional[str] = None,
+        faiss_base_url: Optional[str] = None,
+        triton_url: Optional[str] = None,
+        label_dir: Optional[str] = None,
+        grpc_config: Optional[dict] = None,
+    ):
+        face_base_url = face_base_url or _env("GSHIELD_FACE_URL")
+        faiss_base_url = faiss_base_url or _env("GSHIELD_FAISS_URL")
+        triton_url = triton_url or _env("GSHIELD_TRITON_URL")
+        label_dir = label_dir or _env("GSHIELD_LABEL_DIR")
+
+        self._face = FaceClient(face_base_url) if face_base_url else None
+        self._faiss = FaissClient(faiss_base_url) if faiss_base_url else None
+        self._grpc = None
+        if triton_url and label_dir:
+            self._grpc = GrpcInferClient(
+                triton_url,
+                label_dir=label_dir,
+                grpc_config=grpc_config or get_grpc_config(),
+            )
+
+    @property
+    def face(self) -> FaceClient:
+        if self._face is None:
+            raise GshieldValueError("face_base_url not configured")
+        return self._face
+
+    @property
+    def faiss(self) -> FaissClient:
+        if self._faiss is None:
+            raise GshieldValueError("faiss_base_url not configured")
+        return self._faiss
+
+    @property
+    def grpc(self) -> GrpcInferClient:
+        if self._grpc is None:
+            raise GshieldValueError("triton_url or label_dir not configured")
+        return self._grpc

gshield_pic_sdk-0.1.0/src/gshield_pic_sdk/exceptions.py

@@ -0,0 +1,18 @@
+# -*- coding: utf-8 -*-
+"""SDK 自定义异常。"""
+
+
+class GshieldError(Exception):
+    """Base exception for GshieldPicSDK."""
+
+
+class GshieldConnectionError(GshieldError):
+    """网络或服务连接失败（HTTP 4xx/5xx、gRPC 连接失败等）。"""
+
+
+class GshieldValueError(GshieldError, ValueError):
+    """参数错误（如未配置 URL、mode 不存在、图片格式无效）。"""
+
+
+class GshieldInferError(GshieldError):
+    """推理失败（Triton 推理异常等）。"""

gshield_pic_sdk-0.1.0/src/gshield_pic_sdk/face_client.py

@@ -0,0 +1,43 @@
+# -*- coding: utf-8 -*-
+"""Face 检测 HTTP 客户端。"""
+from typing import Union
+
+import requests
+
+from gshield_pic_sdk._image import to_bytes
+from gshield_pic_sdk.exceptions import GshieldConnectionError
+
+ImageInput = Union[str, bytes, "np.ndarray"]
+
+
+class FaceClient:
+    """人脸检测服务客户端，调用 face 服务的 POST /detect。"""
+
+    def __init__(self, face_base_url: str, timeout: int = 30):
+        self.base_url = face_base_url.rstrip("/")
+        self.timeout = timeout
+
+    def detect(self, image: ImageInput) -> dict:
+        """
+        上传图片做人脸检测与识别。
+        :param image: 图片路径(str)、bytes 或 ndarray
+        :return: {"faces": [...], "count": N}
+        """
+        data = to_bytes(image)
+        url = f"{self.base_url}/detect"
+        try:
+            r = requests.post(
+                url,
+                files={"image": ("image.jpg", data, "image/jpeg")},
+                timeout=self.timeout,
+            )
+        except requests.RequestException as e:
+            raise GshieldConnectionError(f"face detect request failed: {e}") from e
+        if r.status_code >= 400:
+            raise GshieldConnectionError(
+                f"face detect returned {r.status_code}: {r.text}"
+            )
+        out = r.json()
+        if "faces" not in out or "count" not in out:
+            raise GshieldConnectionError(f"unexpected face response: {out}")
+        return out

gshield_pic_sdk-0.1.0/src/gshield_pic_sdk/faiss_client.py

@@ -0,0 +1,81 @@
+# -*- coding: utf-8 -*-
+"""Faiss 向量匹配 HTTP 客户端。"""
+from typing import Union
+
+import requests
+
+from gshield_pic_sdk._image import to_bytes
+from gshield_pic_sdk.exceptions import GshieldConnectionError
+
+ImageInput = Union[str, bytes, "np.ndarray"]
+
+
+class FaissClient:
+    """Faiss 向量库匹配服务客户端。"""
+
+    def __init__(self, faiss_base_url: str, timeout: int = 30):
+        self.base_url = faiss_base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _post_image(self, path: str, image: ImageInput, description: str = "") -> dict:
+        data = to_bytes(image)
+        files = {"image": ("image.jpg", data, "image/jpeg")}
+        payload = {"description": description} if description else {}
+        try:
+            r = requests.post(
+                f"{self.base_url}{path}",
+                files=files,
+                data=payload,
+                timeout=self.timeout,
+            )
+        except requests.RequestException as e:
+            raise GshieldConnectionError(f"faiss request failed: {e}") from e
+        if r.status_code >= 400:
+            raise GshieldConnectionError(f"faiss returned {r.status_code}: {r.text}")
+        return r.json()
+
+    def _get(self, path: str) -> dict:
+        try:
+            r = requests.get(f"{self.base_url}{path}", timeout=self.timeout)
+        except requests.RequestException as e:
+            raise GshieldConnectionError(f"faiss request failed: {e}") from e
+        if r.status_code >= 400:
+            raise GshieldConnectionError(f"faiss returned {r.status_code}: {r.text}")
+        return r.json()
+
+    def _delete(self, path: str) -> dict:
+        try:
+            r = requests.delete(f"{self.base_url}{path}", timeout=self.timeout)
+        except requests.RequestException as e:
+            raise GshieldConnectionError(f"faiss request failed: {e}") from e
+        if r.status_code >= 400:
+            raise GshieldConnectionError(f"faiss returned {r.status_code}: {r.text}")
+        return r.json() if r.content else {}
+
+    def match(self, image: ImageInput) -> dict:
+        """向量匹配，返回 allowed / in_whitelist / in_blacklist 等。"""
+        return self._post_image("/match", image)
+
+    def blacklist_add(self, image: ImageInput, description: str = "") -> dict:
+        """添加黑名单，返回 {id, message}。"""
+        return self._post_image("/blacklist/add", image, description)
+
+    def blacklist_remove(self, image_id: int) -> dict:
+        """删除黑名单条目。"""
+        return self._delete(f"/blacklist/{image_id}")
+
+    def blacklist_list(self) -> dict:
+        """列出黑名单。"""
+        return self._get("/blacklist")
+
+    def whitelist_add(self, image: ImageInput, description: str = "") -> dict:
+        """添加白名单。"""
+        return self._post_image("/whitelist/add", image, description)
+
+    def whitelist_remove(self, image_id: int) -> dict:
+        """删除白名单条目。"""
+        return self._delete(f"/whitelist/{image_id}")
+
+    def whitelist_list(self) -> dict:
+        """列出白名单。"""
+        return self._get("/whitelist")

gshield_pic_sdk-0.1.0/src/gshield_pic_sdk/grpc/__init__.py

@@ -0,0 +1,24 @@
+# -*- coding: utf-8 -*-
+from gshield_pic_sdk.grpc.inference import (
+    load_labels,
+    preprocess_image_raw,
+    preprocess_numpy,
+    infer_classification,
+    infer_yolo,
+    infer_trt_nms_yolo,
+    infer_porn,
+    infer_flag,
+    run_task_with_client,
+)
+
+__all__ = [
+    "load_labels",
+    "preprocess_image_raw",
+    "preprocess_numpy",
+    "infer_classification",
+    "infer_yolo",
+    "infer_trt_nms_yolo",
+    "infer_porn",
+    "infer_flag",
+    "run_task_with_client",
+]