# gt-model

**Repository Path**: handsomepj/gt-model

## Basic Information

- **Project Name**: gt-model
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-11-24
- **Last Updated**: 2025-11-25

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# SAM3 视频目标检测服务

基于 Meta SAM3 的视频目标检测 API 服务，支持混合提示（文本+图片）流式检测。

## 特性

- 🎯 混合提示检测 - 灵活组合文本和图片提示
- 📡 流式返回 - 实时显示检测进度和结果
- 🚀 高速处理 - ffmpeg 加速视频处理 + 批量处理优化
- 📊 详细结果 - 返回每帧的置信度和目标数量
- 🎨 支持多图片+多框 - 基于SAM3的多框提示能力

## 快速开始

### 环境要求

- Python 3.12+
- CUDA 12.6+
- ffmpeg

### 安装

```bash
# 安装系统依赖
sudo apt install ffmpeg

# 安装 Python 依赖
uv sync

# 准备 SAM3 模型（.pt/.pth 文件）
# 默认模型路径: ../sam3-model/
```

### 配置

修改 `config/config.yaml` 设置模型路径、端口、帧率等参数。

### 启动

```bash
./start_service.sh

# 或
uv run app.py
```

访问 http://localhost:8000/docs 查看 API 文档。

## API 使用

详细的 API 文档请访问 `/docs` 端点。

### 混合提示检测（流式）

支持多种组合模式：
1. **纯文本模式** - 只提供 text_prompt
2. **纯视觉模式** - 只提供 reference_image（可选 reference_box）
3. **混合模式** - 同时提供文本和图片

```bash
POST /detect
{
  "video_url": "http://example.com/video.mp4",
  "text_prompt": "person",  // 可选
  "reference_image": {  // 可选，支持URL或Base64
    "type": "url",  // 或 "base64"
    "data": "http://example.com/reference.jpg"  // URL地址或Base64编码字符串
  },
  "reference_box": [0.1, 0.1, 0.8, 0.8],  // 可选，[x, y, width, height]
  "target_fps": 1,  // 可选
  "confidence_threshold": 0.0  // 可选
}
```

### 流式响应示例

使用 Server-Sent Events (SSE) 格式返回：

```
data: {"type": "progress", "message": "视频处理完成", "current_batch": 0, "total_batches": 10}

data: {"type": "batch_result", "current_batch": 1, "batch_detections": [...]}

data: {"type": "complete", "message": "检测完成", "total_detected_count": 25}
```

## 配置说明

编辑 `config/config.yaml` 可配置：

- **模型路径** - SAM3 模型文件位置
- **服务端口** - API 服务监听端口
- **工作进程** - 并发处理能力（注意显存消耗）
- **默认帧率** - 视频采样频率
- **置信度阈值** - 检测结果过滤

## 常见问题

**显存不足？** 减少 workers 数量或降低采样帧率

**处理速度慢？** 降低 target_fps 或使用更小的视频

**结果不准？** 调整置信度阈值或使用更精确的提示