# sam2-springboot

**Repository Path**: wuyuan/sam2-springboot

## Basic Information

- **Project Name**: sam2-springboot
- **Description**: SAM2 ONNX 分割服务（Spring Boot 4.1.1 + ONNX Runtime）
- **Primary Language**: Unknown
- **License**: AGPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-06
- **Last Updated**: 2026-09-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# sam2-springboot：SAM2 分割 Web 服务（Spring Boot 4.1.1）

基于 go-vision 仓库导出的 SAM2 ONNX 模型，提供 REST 分割接口 + 可视化前端页面。

- 后端：Spring Boot **4.1.1** + ONNX Runtime Java **1.22.0**（Java 17+，已在 Java 25 验证）
- 前端：`src/main/resources/static/index.html`，支持上传图片、点选/框选提示、实时展示分割效果

## 快速开始

```bash
# 1. 准备模型（.onnx 与 .onnx_data 共 4 个文件放入 models/ 目录）
#    https://hf-mirror.com/GetcharZp/go-vision/tree/main/sam2_weights
#    （国内直连 huggingface.co 慢时用 hf-mirror.com）

# 2. 启动
mvn spring-boot:run

# 3. 浏览器打开
#    http://localhost:8080/
```

模型路径可在 `src/main/resources/application.yml` 中修改（`sam2.encoder-model-path` /
`sam2.decoder-model-path`）。模型在**首次请求时懒加载**（约 6 秒），启动本身只需 3 秒。

## 接口文档

### POST /api/sam2/segment

`multipart/form-data`：

| 字段 | 说明 |
|---|---|
| `image` | 图片文件（jpg/png） |
| `prompts` | JSON 字符串，如 `[{"x":367,"y":168,"label":2},{"x":441,"y":349,"label":3}]` |

label 含义：`0` 背景点击 · `1` 前景点击 · `2` 框左上角 · `3` 框右下角（坐标均为原图像素）

返回：

```json
{
  "score": 0.9689,
  "foregroundRatio": 0.0272,
  "width": 800,
  "height": 534,
  "encodeMs": 4477,
  "decodeMs": 355,
  "maskImage": "data:image/png;base64,...",
  "overlayImage": "data:image/png;base64,..."
}
```

curl 示例：

```bash
curl -X POST http://localhost:8080/api/sam2/segment \
  -F "image=@test.png" \
  -F "prompts=[{\"x\":367,\"y\":168,\"label\":2},{\"x\":441,\"y\":349,\"label\":3}]"
```

## 前端页面

`http://localhost:8080/` 打开后：

1. **上传图片**（点击按钮或拖拽到画布）
2. 切到「点选」模式：单击目标加**前景点**（绿），可切换**背景点**（红）做负样本
3. 切到「框选」模式：拖拽画出目标范围
4. 支持多提示组合、撤销、清空；点击「开始分割」查看叠加效果与掩码
5. 可反复调整提示后重新分割（每次独立前向，无需刷新）

## 工程结构

```
sam2-springboot/
├── pom.xml                              # Spring Boot 4.1.1 + onnxruntime 1.22.0
├── models/                              # 模型目录（.onnx + .onnx_data）
└── src/main/
    ├── java/com/example/sam2/
    │   ├── Sam2Application.java         # 启动类
    │   ├── Sam2Engine.java              # ONNX 推理引擎（编码器 + 解码器）
    │   ├── Sam2Settings.java            # 模型常量（归一化参数等）
    │   ├── ImageUtils.java              # 缩放 / 归一化 / 填充
    │   ├── Point.java                   # 提示点
    │   ├── MaskResult.java              # 分割结果
    │   └── web/
    │       ├── Sam2Controller.java      # POST /api/sam2/segment
    │       └── Sam2Service.java         # 服务层：懒加载引擎 + 分割编排
    └── resources/
        ├── application.yml              # 端口 / 模型路径 / 上传限制
        └── static/index.html            # 前端页面
```

## Spring Boot 4 集成注意点

1. **Jackson 3**：Spring Boot 4.1 使用 Jackson 3.x，包名从 `com.fasterxml.jackson.*` 改为
   `tools.jackson.*`（如 `tools.jackson.databind.ObjectMapper`）。
2. **web starter 自带 JSON**：`spring-boot-starter-web` 已传递引入
   `spring-boot-starter-jackson`，无需额外加 JSON 依赖。
3. **懒加载**：182MB 模型放到首次请求加载（`Sam2Service` 双重检查锁），避免拖慢启动；
   也可在 `application.yml` 中调整。
4. **并发**：`Sam2Engine` 可被多请求共享（ONNX Runtime `Session.run` 线程安全），
   每个请求独立做 encode→decode，无共享可变状态。
5. **CUDA**：依赖换成 `com.microsoft.onnxruntime:onnxruntime-gpu:1.22.0` 并把
   `sam2.use-cuda` 置为 true。
6. **JVM 提示**：Java 25 下 ONNX Runtime 会输出 native-access 警告（无害），
   可加 `--enable-native-access=ALL-UNNAMED` 消除。

## 模型规格速查

- `vision_encoder.onnx`：`pixel_values[1,3,1024,1024]` → `image_embeddings.0[1,32,256,256]`
  / `.1[1,64,128,128]` / `.2[1,256,64,64]`
- `prompt_encoder_mask_decoder.onnx`：`input_points[1,1,N,2]`、`input_labels[1,1,N]`(int64)、
  `input_boxes[1,0,4]`（空）+ 3 层特征 → `iou_scores[1,1,3]`、`pred_masks[1,1,3,256,256]`
- 预处理：长边等比缩放到 1024、ImageNet 归一化、CHW、零填充
- 后处理：按 iou 选最优掩码，阈值 0 二值化，最近邻放大回原图