# 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 标签**：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=...)` 覆盖。

## 使用示例

```python
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_*)` 覆盖。
