量迹AI · SAM3「分割一切」视觉分割服务
本项目在开源 SAM3（Segment Anything Model 3）能力之上，封装了面向业务的 “分割一切” 推理服务：通过 FastAPI 提供文本提示词驱动的图像分割接口，并扩展了 塔罗牌分割/识别、人脸与头发分割 + 属性分析 等场景能力。
本仓库定位为：模型推理 + API 服务 的可复用工程模板（适合在 MacOS 开发、服务器部署）。
你能用它做什么
- 通用分割：输入图片 + 文本提示词（中文或英文），返回分割可视化结果图 URL
- 分割子图导出：可选返回每个目标的独立裁剪图（支持透明背景抠图）
- 塔罗牌：检测指定数量的塔罗牌 → 透视矫正裁剪 →（可选）调用多模态大模型识别牌名与正逆位
- 人脸分析：分割人脸/头发区域 → 裁剪保存 →（可选）调用多模态大模型预测性别/年龄等属性
对应实现文件：
- API 服务入口：fastAPI_tarot.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) 创建虚拟环境（推荐）
conda create -n sam3 python=3.12
conda deactivate
conda activate sam3
0.1) 安装 PyTorch（按你的设备选择）
GPU（CUDA）环境请安装与你 CUDA 版本匹配的 PyTorch；CPU 环境可直接安装 CPU 版。
pip install torch torchvision torchaudio
1) 安装本仓库与依赖
pip install -e .
pip install -r requirement.txt
如果需要接口用到的第三方库（如 OpenCV、matplotlib、Pillow、requests、dashscope 等），请按你的实际场景安装（仓库中部分功能会依赖它们）。
2) 下载权重模型（必须）
说明：模型文件较大，建议预留充足磁盘空间。
默认将权重保存到
./dir/，可按需修改--local_dir。如需通过 Hugging Face 下载，也可以自行改用
huggingface_hub的下载方式。
1.1 下载权重模型:
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 中将模型构建改为显式传入本地权重路径，例如：
model = build_sam3_image_model(checkpoint_path="./dir/sam3.pt")
启动 API 服务（FastAPI）
服务定义在 fastAPI_tarot.py 中。你可以用 uvicorn 启动（示例命令仅供参考，按需调整 host/port）：
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 中实现，返回体为 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）
通用分割（上传图片）
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）
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，且值与服务端配置一致。
免责声明与致谢
- 本项目为量迹AI内部/业务化工程封装示例，不是官方 SAM3 仓库。
- 模型与核心算法能力来自开源的 SAM3 实现与相关依赖，感谢社区贡献者与原作者团队。