230 lines
7.3 KiB
Markdown
230 lines
7.3 KiB
Markdown
# 量迹AI · SAM3「分割一切」视觉分割服务
|
||
|
||
|
||
# Admin Config
|
||
ADMIN_PASSWORD = "admin_secure_password" # 可以根据需求修改
|
||
HISTORY_FILE = "history.json"
|
||
|
||
|
||
本项目在开源 SAM3（Segment Anything Model 3）能力之上，封装了面向业务的 **“分割一切”** 推理服务：通过 **FastAPI** 提供文本提示词驱动的图像分割接口，并扩展了 **塔罗牌分割/识别**、**人脸与头发分割 + 属性分析** 等场景能力。
|
||
|
||
本仓库定位为：**模型推理 + API 服务** 的可复用工程模板（适合在 MacOS 开发、服务器部署）。
|
||
|
||
---
|
||
|
||
## 你能用它做什么
|
||
|
||
- 通用分割：输入图片 + 文本提示词（中文或英文），返回分割可视化结果图 URL
|
||
- 分割子图导出：可选返回每个目标的独立裁剪图（支持透明背景抠图）
|
||
- 塔罗牌：检测指定数量的塔罗牌 → 透视矫正裁剪 →（可选）调用多模态大模型识别牌名与正逆位
|
||
- 人脸分析：分割人脸/头发区域 → 裁剪保存 →（可选）调用多模态大模型预测性别/年龄等属性
|
||
|
||
对应实现文件：
|
||
- API 服务入口：[fastAPI_tarot.py](fastAPI_tarot.py)
|
||
- 人脸分析流程：[human_analysis_service.py](human_analysis_service.py)
|
||
|
||
---
|
||
|
||
## 项目结构（关键目录）
|
||
|
||
- sam3/：SAM3 模型核心代码（本仓库已内置，不依赖外部子模块）
|
||
- static/results/：推理结果落盘目录（接口返回的 URL 指向这里）
|
||
- assets/：示例素材、演示图片/视频
|
||
- fastAPI_tarot.py：主要 API 服务（含鉴权、模型加载、推理、可视化与落盘）
|
||
|
||
---
|
||
|
||
## 环境要求
|
||
|
||
- Python：建议 3.10+（SAM3 作为库最低 3.8+）
|
||
- PyTorch：建议按你的设备（CPU/CUDA）安装匹配版本
|
||
- 依赖：FastAPI/uvicorn 等（见 requirement.txt，另有 sam3 依赖见 pyproject.toml）
|
||
|
||
---
|
||
|
||
## 安装与准备
|
||
|
||
### 0) 创建虚拟环境（推荐）
|
||
|
||
```bash
|
||
conda create -n sam3 python=3.12
|
||
conda deactivate
|
||
conda activate sam3
|
||
```
|
||
|
||
### 0.1) 安装 PyTorch（按你的设备选择）
|
||
|
||
GPU（CUDA）环境请安装与你 CUDA 版本匹配的 PyTorch；CPU 环境可直接安装 CPU 版。
|
||
|
||
```bash
|
||
pip install torch torchvision torchaudio
|
||
```
|
||
|
||
### 1) 安装本仓库与依赖
|
||
|
||
```bash
|
||
pip install -e .
|
||
pip install -r requirement.txt
|
||
```
|
||
|
||
如果需要接口用到的第三方库（如 OpenCV、matplotlib、Pillow、requests、dashscope 等），请按你的实际场景安装（仓库中部分功能会依赖它们）。
|
||
|
||
### 2) 下载权重模型（必须）
|
||
|
||
> 说明：模型文件较大，建议预留充足磁盘空间。
|
||
>
|
||
> 默认将权重保存到 `./dir/`，可按需修改 `--local_dir`。
|
||
>
|
||
> 如需通过 Hugging Face 下载，也可以自行改用 `huggingface_hub` 的下载方式。
|
||
|
||
1.1 **下载权重模型:**
|
||
|
||
```bash
|
||
pip install modelscope
|
||
modelscope download --model facebook/sam3 sam3.pt --local_dir ./dir
|
||
```
|
||
|
||
下载后会得到 `./dir/sam3.pt`。
|
||
|
||
### 3) 配置 SAM3 权重路径（必须）
|
||
|
||
当前 API 服务会在启动时加载 SAM3 权重。你需要确保 `fastAPI_tarot.py` 里构建模型时使用了正确的 `checkpoint_path`。
|
||
|
||
推荐做法：在 [fastAPI_tarot.py](fastAPI_tarot.py) 中将模型构建改为显式传入本地权重路径，例如：
|
||
|
||
```python
|
||
model = build_sam3_image_model(checkpoint_path="./dir/sam3.pt")
|
||
```
|
||
|
||
---
|
||
|
||
## 启动 API 服务（FastAPI）
|
||
|
||
服务定义在 [fastAPI_tarot.py](fastAPI_tarot.py) 中。你可以用 uvicorn 启动（示例命令仅供参考，按需调整 host/port）：
|
||
|
||
```bash
|
||
uvicorn fastAPI_tarot:app --host 127.0.0.1 --port 55600
|
||
```
|
||
|
||
启动后：
|
||
- OpenAPI 文档：`http://127.0.0.1:55600/docs`
|
||
- 静态结果目录：`http://127.0.0.1:55600/static/results/...`
|
||
|
||
---
|
||
|
||
## 鉴权说明（API Key）
|
||
|
||
所有接口都要求在请求 Header 中携带 API Key：
|
||
|
||
- Header 名：`X-API-Key`
|
||
- 值：请使用你服务端配置的 Key（建议用环境变量或配置文件管理，不要在代码里硬编码）
|
||
|
||
---
|
||
|
||
## API 接口一览
|
||
|
||
以下接口均在 [fastAPI_tarot.py](fastAPI_tarot.py) 中实现，返回体为 JSON，并通过静态文件服务输出结果图片 URL。
|
||
|
||
### 1) POST /segment（通用分割）
|
||
|
||
功能：对图片做文本提示词分割（中文会自动翻译为英文提示词）。
|
||
|
||
参数（表单）：
|
||
- prompt：提示词（必填，例：`cat` / `人` / `白色连衣裙`）
|
||
- file：上传图片（二选一）
|
||
- image_url：图片 URL（二选一）
|
||
- save_segment_images：是否保存并返回每个目标的独立图片（默认 false）
|
||
- cutout：导出子图时是否透明背景抠图（默认 false）
|
||
- highlight：是否启用“周边变黑突出主体”的效果（默认 false）
|
||
- confidence：置信度阈值（0.0-1.0，默认 0.7）
|
||
|
||
返回（示例字段）：
|
||
- result_image_url：分割可视化结果图
|
||
- detected_count：检测到的目标数量
|
||
- segmented_images：可选的分割子图 URL 列表
|
||
|
||
### 2) POST /segment_tarot（塔罗牌分割）
|
||
|
||
功能：检测塔罗牌并对每张牌做透视矫正与裁剪。
|
||
|
||
参数（表单）：
|
||
- file / image_url（二选一）
|
||
- expected_count：期望严格检测到的塔罗牌数量（默认 3）
|
||
|
||
返回：
|
||
- tarot_cards：每张牌的裁剪图 URL、是否被算法旋转矫正等信息
|
||
- full_visualization：整体分割可视化图 URL（可选）
|
||
|
||
### 3) POST /recognize_tarot（塔罗牌全流程：分割 + 识别）
|
||
|
||
功能：在 `/segment_tarot` 基础上，进一步调用多模态大模型识别每张牌的名称与正逆位，并尝试识别牌阵。
|
||
|
||
说明：
|
||
- 该流程依赖多模态大模型服务（例如 Qwen-VL / DashScope），请自行配置密钥与可用模型
|
||
- 强烈建议将密钥通过环境变量注入，避免写入仓库
|
||
|
||
### 4) POST /segment_face（人脸/头发分割 + 属性分析）
|
||
|
||
功能：分割“face and hair”等区域，并可选调用多模态大模型进行性别/年龄等属性识别。
|
||
|
||
参数（表单）：
|
||
- file / image_url（二选一）
|
||
- prompt：默认 `face and hair`（中文会尝试翻译）
|
||
|
||
---
|
||
|
||
## 请求示例（curl）
|
||
|
||
### 通用分割（上传图片）
|
||
|
||
```bash
|
||
curl -X POST "http://127.0.0.1:55600/segment" \
|
||
-H "X-API-Key: <YOUR_API_KEY>" \
|
||
-F "prompt=猫" \
|
||
-F "file=@/path/to/image.jpg"
|
||
```
|
||
|
||
### 通用分割（图片 URL）
|
||
|
||
```bash
|
||
curl -X POST "http://127.0.0.1:55600/segment" \
|
||
-H "X-API-Key: <YOUR_API_KEY>" \
|
||
-F "prompt=person" \
|
||
-F "image_url=https://example.com/image.jpg"
|
||
```
|
||
|
||
---
|
||
|
||
## 结果输出与落盘
|
||
|
||
- 结果图会写入：`static/results/`
|
||
- 接口返回的 URL 形如：`/static/results/<filename>` 或 `/static/results/<request_id>/<filename>`
|
||
- 服务可选开启后台清理任务，定期删除过期结果文件（见 `fastAPI_tarot.py` 末尾的环境变量配置逻辑）
|
||
|
||
---
|
||
|
||
## 常见问题
|
||
|
||
### 1) 启动时报找不到权重文件？
|
||
|
||
请确认：
|
||
- 已按“下载权重模型”得到 `sam3.pt`
|
||
- `fastAPI_tarot.py` 中 `build_sam3_image_model(checkpoint_path=...)` 指向正确路径
|
||
|
||
### 2) 返回 401/403？
|
||
|
||
请确认请求头是否带了 `X-API-Key`，且值与服务端配置一致。
|
||
|
||
---
|
||
|
||
# Admin Config
|
||
ADMIN_PASSWORD = "admin_secure_password" # 可以根据需求修改
|
||
HISTORY_FILE = "history.json"
|
||
|
||
API_KEY = "123quant-speed" # 可以根据需求修改
|
||
|
||
## 免责声明与致谢
|
||
|
||
- 本项目为量迹AI内部/业务化工程封装示例，**不是官方 SAM3 仓库**。
|
||
- 模型与核心算法能力来自开源的 SAM3 实现与相关依赖，感谢社区贡献者与原作者团队。
|