gshield-pic-sdk 0.3.0

Unified SDK for Face detection, Faiss vector match, and Triton gRPC inference

GshieldPicSDK

统一调用 Face 检测、Faiss 向量匹配、Triton gRPC 推理 的 Python SDK。所有服务地址由用户提供，SDK 内不写死默认 URL。

安装

从 PyPI 安装（发布后）：

pip install gshield-pic-sdk

从本地源码安装（开发或未发布时）：

pip install -e api_server/GshieldPicSDK

依赖：requests, numpy, Pillow, opencv-python-headless, grpcio>=1.63.0, tritonclient[grpc]。

依赖冲突处理：若安装时出现 grpcio 版本冲突（如 grpcio-status 1.71.2 要求 grpcio>=1.71.2 而 tritonclient 要求 grpcio<1.68），这是 tritonclient 的限制。解决方案：

1. 推荐：使用虚拟环境隔离（避免影响全局环境）

   python -m venv venv
   source venv/bin/activate  # Linux/Mac
   # 或 venv\Scripts\activate  # Windows
   pip install gshield-pic-sdk
   

2. 临时方案：降级 grpcio-status（若不需要其新特性）

   pip install grpcio-status==1.67.1  # 或兼容 grpcio<1.68 的版本
   pip install gshield-pic-sdk
   

3. 或先安装兼容的 grpcio，再安装 SDK

   pip install "grpcio>=1.63.0,<1.68"
   pip install gshield-pic-sdk
   

发布到 PyPI：参见 docs/PYPI_PUBLISHING.md。

配置说明

• 所有 URL 由用户提供：face_base_url、faiss_base_url、triton_url 仅通过构造函数传入，或通过环境变量 GSHIELD_FACE_URL、GSHIELD_FAISS_URL、GSHIELD_TRITON_URL 指定；构造函数参数优先。
• gRPC 标签：SDK 已随包分发默认标签文件（与 grpc_config 中各 mode 对应的 .txt）。不传 label_dir 时使用包内标签；若需自定义标签，可传入 label_dir 或环境变量 GSHIELD_LABEL_DIR 指向自有目录。
• mode 快速配置：gRPC 支持的模型列表（mode）、标签文件映射、精度配置集中在 gshield_pic_sdk.grpc_config 中；新增/修改 mode 时只需改该模块或通过 get_grpc_config(custom_label_map=..., custom_data_types=..., custom_modes_list=...) 覆盖。

使用示例

from gshield_pic_sdk import GshieldPicClient

# 按需传入各服务地址；不传 label_dir 时使用 SDK 自带的标签
client = GshieldPicClient(
    face_base_url="http://localhost:8001",
    faiss_base_url="http://localhost:8000",
    triton_url="localhost:8501",
    # label_dir 可选：不传则用包内标签；传则用自定义目录
    # label_dir="/path/to/your/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_*) 覆盖。