# 量迹AI · SAM3「分割一切」视觉分割服务 本项目在开源 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: " \ -F "prompt=猫" \ -F "file=@/path/to/image.jpg" ``` ### 通用分割（图片 URL） ```bash curl -X POST "http://127.0.0.1:55600/segment" \ -H "X-API-Key: " \ -F "prompt=person" \ -F "image_url=https://example.com/image.jpg" ``` --- ## 结果输出与落盘 - 结果图会写入：`static/results/` - 接口返回的 URL 形如：`/static/results/` 或 `/static/results//` - 服务可选开启后台清理任务，定期删除过期结果文件（见 `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 实现与相关依赖，感谢社区贡献者与原作者团队。