# SAMJS-SAM-Service

**Repository Path**: wangzuquan/samjs-sam-service

## Basic Information

- **Project Name**: SAMJS-SAM-Service
- **Description**: 一个基于Segment Anything Model (SAM) 的图像嵌入服务，支持GPU加速，可根据用户上传的图片动态生成embedding、可搭配SAMJS进行交互式图像分割任务。
- **Primary Language**: Python
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-15
- **Last Updated**: 2025-09-15

## Categories & Tags

**Categories**: Uncategorized

**Tags**: sam, SAMJS, 遥感分割

## README

# SAM Embedding Service

一个基于Segment Anything Model (SAM) 的图像嵌入服务，支持GPU加速，可根据用户上传的图片动态生成embedding。

## 功能特点

- ✅ 支持图像上传，动态生成embedding
- ✅ GPU加速 (自动检测并使用可用的GPU)
- ✅ 支持两种部署模式：
  - FastAPI + Uvicorn (简单快速部署)
  - Ray Serve (支持GPU集群、自动扩展)
- ✅ 支持图像缓存，提高性能
- ✅ 提供健康检查、统计信息等API
- ✅ 支持通过文件上传或base64编码方式提交图像
- ✅ 支持Windows环境一键运行

## 技术栈

- Python 3.8+
- FastAPI (Web框架)
- PyTorch (深度学习框架)
- Segment Anything Model (SAM)
- Ray Serve (分布式模型服务)
- Uvicorn (ASGI服务器)

## 安装指南

### 1. 克隆项目

```bash
# 克隆项目代码
git clone <repository-url>
cd SAMJS-Service
```

### 2. 安装依赖

#### Windows环境

```bash
# 安装Python依赖（使用国内镜像源加速）
pip install -r requirements.txt --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/

# 安装Python-multipart依赖（FastAPI处理表单数据所需）
pip install python-multipart --no-cache-dir -i https://mirrors.aliyun.com/pypi/simple/
```

#### Linux/Mac环境

```bash
# 安装Python依赖
pip install -r requirements.txt
```

### 3. 下载SAM模型

服务需要SAM模型文件才能运行。可以使用提供的脚本自动下载：

```bash
# 下载默认的vit_h模型（最大，精度最高）
python run_server.py --download-model vit_h

# 或下载其他型号的模型
python run_server.py --download-model vit_l
python run_server.py --download-model vit_b
```

模型会默认下载到 `./models/` 目录。

## 一键运行（Windows环境）

我们提供了Windows环境下的一键运行批处理文件，可自动完成环境配置、依赖安装、模型下载和服务启动：

1. 双击运行 `run_sam_service.bat` 文件
2. 首次运行时，脚本会自动执行以下操作：
   - 检查Python是否已安装
   - 创建并激活Python虚拟环境
   - 安装项目依赖
   - 下载SAM模型（如未找到）
   - 启动服务
3. 后续运行时，脚本会跳过已完成的步骤

详细说明请参考 `README_ONE_CLICK.md` 文件。

## 配置说明

可以通过环境变量或修改 `config.py` 文件来配置服务：

| 环境变量 | 描述 | 默认值 |
|---------|------|-------|
| SAM_MODEL_PATH | SAM模型文件路径 | ./models/sam_vit_h_4b8939.pth |
| SAM_MODEL_TYPE | 模型类型 (vit_h/vit_l/vit_b) | vit_h |
| GPU_INDEX | GPU索引 (如果有多个GPU) | 0 |
| HOST | 服务监听地址 | 0.0.0.0 |
| PORT | 服务监听端口 | 8000 |
| SERVE_NUM_REPLICAS | Ray Serve副本数量 | 1 |
| SERVE_GPUS_PER_REPLICA | 每个Ray Serve副本使用的GPU数量 | 1.0 |
| ENABLE_CACHE | 是否启用缓存 | True |
| CACHE_SIZE | 缓存大小 | 100 |
| IMAGE_RESIZE | 图像调整大小 | 1024 |
| LOG_LEVEL | 日志级别 | INFO |

## 运行服务

### 模式1: FastAPI + Uvicorn (简单部署)

适合单节点部署，简单快速：

```bash
python run_server.py --mode http
```

### 模式2: Ray Serve (支持GPU集群)

适合大规模部署，支持GPU集群和自动扩展：

```bash
python run_server.py --mode ray
```

### 选择建议

- 开发和测试环境：推荐使用FastAPI + Uvicorn模式
- 生产环境：推荐使用Ray Serve模式，可提供更好的扩展性和容错能力

## API接口文档

服务启动后，可以访问以下URL查看API文档：
- Swagger UI: http://localhost:8000/docs
- Redoc: http://localhost:8000/redoc

### 主要API接口

1. **根路径** - `GET /`
   - 返回服务基本信息

2. **健康检查** - `GET /health`
   - 检查服务和模型状态

3. **图像嵌入生成** - `POST /embedding`
   - 通过文件上传方式生成图像嵌入
   - 参数：`file` (图像文件)
   - 返回：embedding数据、形状、图像ID等

4. **图像嵌入生成(Base64)** - `POST /embedding/base64`
   - 通过base64编码方式生成图像嵌入
   - 参数：`image_base64` (base64编码的图像数据)
   - 返回：embedding数据、形状、图像ID等

5. **清除缓存** - `DELETE /cache`
   - 清除图像嵌入缓存

6. **统计信息** - `GET /stats`
   - 获取服务统计信息

7. **Ray集群信息** (仅Ray模式) - `GET /ray/cluster`
   - 获取Ray集群资源和状态信息

## GPU加速说明

服务会自动检测并使用可用的GPU加速。如果要指定使用特定的GPU，可以设置 `GPU_INDEX` 环境变量：

```bash
# 在Windows上
set GPU_INDEX=1

# 在Linux/Mac上
export GPU_INDEX=1

# 然后启动服务
python run_server.py --mode http
```

## 性能优化

- 使用较大的GPU内存可以显著提高处理速度
- 对于高并发场景，建议使用Ray Serve模式并配置多个副本
- 启用缓存可以提高重复图像的处理速度

## 注意事项

- SAM模型文件较大（vit_h约2.5GB），请确保有足够的磁盘空间
- 首次加载模型可能需要较长时间，请耐心等待
- 处理大图像时，内存使用量会增加，请确保服务器有足够的内存
- 使用GPU时，确保已正确安装CUDA和PyTorch的GPU版本

## 运行测试

项目提供了测试脚本，可以验证服务的各项功能是否正常工作。

### 测试前准备
1. 确保服务已启动
2. 确保测试文件中的服务URL与配置一致

### 运行测试

```bash
# 在项目根目录下运行
python test_sam_service.py
```

### 测试内容
测试脚本会自动测试以下功能：
1. **健康检查接口** - 检查服务和模型状态
2. **统计信息接口** - 获取服务统计信息
3. **图像嵌入生成接口（文件上传）** - 通过文件上传方式生成图像嵌入
4. **图像嵌入生成接口（base64）** - 通过base64编码方式生成图像嵌入
5. **清除缓存接口** - 清除图像嵌入缓存

### 测试配置
测试脚本中的配置项位于文件顶部：
```python
# 服务URL
sERVICE_URL = "http://localhost:8000"
# 测试图片路径
IMAGE_PATH = "E:\\AI\\Heilongjiang_cropped_image_3072_3584.tif"
```

如果服务端口不是8000（例如修改了`config.py`中的PORT配置），需要更新`sERVICE_URL`中的端口号。
如果需要测试其他图片，可以修改`IMAGE_PATH`。

## 常见问题

1. **Python依赖安装失败**
   - 尝试使用国内镜像源：`pip install -r requirements.txt -i https://mirrors.aliyun.com/pypi/simple/`
   - 确保使用的是Python 3.8+版本
   - 对于Windows用户，可尝试使用一键运行脚本

2. **模型下载缓慢或失败**
   - 确保网络连接正常
   - 可以手动下载模型并放入 `models` 目录
     - vit_h: https://dl.fbaipublicfiles.com/segment_anything/sam_vit_h_4b8939.pth
     - vit_l: https://dl.fbaipublicfiles.com/segment_anything/sam_vit_l_0b3195.pth
     - vit_b: https://dl.fbaipublicfiles.com/segment_anything/sam_vit_b_01ec64.pth

3. **GPU加速未启用**
   - 确保已安装CUDA和PyTorch的GPU版本
   - 检查GPU驱动是否正常
   - 尝试设置 `GPU_INDEX` 环境变量指定GPU

4. **服务无法访问**
   - 确保服务已成功启动
   - 检查防火墙设置，确保端口已开放
   - 尝试访问 `http://localhost:8000/health` 进行健康检查