# sam2.0

**Repository Path**: shih945/sam

## Basic Information

- **Project Name**: sam2.0
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-15
- **Last Updated**: 2026-06-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Sam — Smart Autonomous Monitor

**代号 Sam**，致敬《疑犯追踪》的 Samaritan。一个运行在本地 K3s 集群上的视频 AI 分析系统。

## 核心能力

- **视频入库**：上传视频文件或录制 RTSP/EZVIZ 摄像头流，统一存储到 MinIO
- **离线 AI 分析**：自动提取关键帧 → YOLOv8 目标检测 → VLM 场景描述 → 向量嵌入 → 结构化存储
- **回放查看**：播放视频时，时间轴标注事件点和 AI 描述
- **摄像头管理**：支持 RTSP 直连 + EZVIZ（萤石云）设备同步，持续分段录制，自动入队分析
- **实时预览**：摄像头 HLS 直播预览
- **智能查询**：自然语言搜索历史事件——"昨天下午谁在门口出现过""有没有人摔倒"

**纯 CPU 运行**，无需 GPU。默认使用 moondream:1.8b (VLM) + Qwen2.5:1.5b (LLM)，也可切换到云端 OpenAI 兼容 API。

## 架构

```
                         ┌───────────────────┐
                         │   Traefik Ingress  │
                         │   (sam.local)      │
                         └──────┬─────┬──────┘
                                │     │
                    ┌───────────┘     └──────────────┐
                    ▼                                 ▼
          ┌─────────────────┐              ┌──────────────────┐
          │    sam-ui       │              │    sam-api       │
          │  React + nginx  │── proxy ────│   FastAPI :8080   │
          │     :80         │   /api/*    │                   │
          └─────────────────┘              └──┬────┬────┬─────┘
                                              │    │    │
                          ┌───────────────────┘    │    └──────────┐
                          ▼                        ▼                ▼
                   ┌─────────────┐         ┌─────────────┐   ┌──────────┐
                   │    Redis    │         │    MinIO     │   │  Ollama  │
                   │  可靠任务队列 │         │ 视频+帧存储   │   │  VLM/LLM │
                   │   :6379     │         │   :9000      │   │  :11434  │
                   └──────▲──────┘         └──────▲───────┘   └────▲─────┘
                          │                       │                │
                   ┌──────┴───────────────────────┴────────────────┴──┐
                   │                  sam-worker                       │
                   │  取任务 → 抽帧 → YOLOv8 → VLM描述 → 向量存储      │
                   └──────────────────────────────────────────────────┘
                          │                       │
                   ┌──────┴──────┐         ┌──────┴──────┐
                   │   SQLite    │         │  ChromaDB   │
                   │   (PVC)     │         │   (PVC)     │
                   └─────────────┘         └─────────────┘

                   ┌──────────────────────────────────────────────────┐
                   │              sam-camera-worker                   │
                   │  EZVIZ/RTSP取流 → ffmpeg分段录制 → MinIO上传     │
                   │  → webhook通知API → API入队分析任务              │
                   └──────────────────────────────────────────────────┘
```

**7 个 Pod，职责清晰：**

| Pod | 镜像 | 职责 |
|-----|------|------|
| sam-ui | 自构建 (React + nginx) | Web 前端：视频列表、播放器、事件时间线、搜索、摄像头管理、实时预览 |
| sam-api | 自构建 (FastAPI) | REST API：上传、录制管理、摄像头 CRUD、EZVIZ 同步、搜索、HLS 代理 |
| sam-worker | 自构建 (Python) | 后台分析：取任务→抽关键帧→YOLOv8 检测→VLM 描述→ChromaDB 嵌入 |
| sam-camera-worker | 自构建 (Python) | 摄像头录制引擎：RTSP/EZVIZ 取流→ffmpeg 分段录制→MinIO 上传→webhook 通知 |
| redis | redis:7-alpine | 可靠任务队列（Sorted Set + Lua 原子操作）、分布式锁 |
| minio | minio/minio | 对象存储：原始视频 + 标注帧图片 |
| ollama | ollama/ollama | 模型推理（可选，可替换为云端 API） |

## 快速开始

### 本地开发

```bash
# 安装依赖
pip install -r services/base/requirements.txt

# 启动基础设施（Redis、MinIO、Ollama）
# 然后分别启动各服务：

# API
cd services/api && uvicorn src.main:app --host 0.0.0.0 --port 8080

# Worker
python services/worker/src/main.py

# Camera Worker
python services/camera-worker/src/main.py

# UI
cd services/ui && npm install && npm run dev
# 浏览器打开 http://localhost:3000
```

首次启动后拉取模型：

```bash
curl http://localhost:11434/api/pull -d '{"name":"moondream:1.8b"}'
curl http://localhost:11434/api/pull -d '{"name":"qwen2.5:1.5b"}'
```

### K3s 部署（无 Docker，纯 containerd + nerdctl）

```bash
# 0. 安装 nerdctl（仅一次，静态二进制，无依赖）
curl -sSL https://github.com/containerd/nerdctl/releases/download/v1.7.6/nerdctl-1.7.6-linux-amd64.tar.gz | sudo tar xz -C /usr/local/bin nerdctl

# 1. 一键部署（构建 + 部署 + 拉模型）
bash scripts/deploy-all.sh

# 2. 访问
# 先配置 hosts: <node-ip> sam.local
# 浏览器打开 http://sam.local
# 或端口转发: kubectl port-forward -n sam svc/sam-ui 3000:80
```

详见 [DEPLOY.md](DEPLOY.md)。

## 项目结构

```
sam2.0/
├── k8s/                       Kubernetes manifests（16 个 YAML）
├── services/
│   ├── api/                   FastAPI 后端（8 个路由模块）
│   ├── worker/                视频分析 Worker
│   ├── camera-worker/         摄像头录制引擎
│   ├── ui/                    React 前端（SPA）
│   └── base/                  共享基础 Docker 镜像
├── shared/                    共享 Python 库（config、Redis 队列、AI 提供商、EZVIZ 客户端、数据模型）
├── scripts/                   运维脚本（构建、部署、演示数据）
├── DEPLOY.md                  K3s 部署指南
├── LOCAL_DEV.md               本地开发指南
├── PLAN.md                    详细架构计划书
└── README.md                  本文件
```

## 数据流

### 视频上传分析

```
上传视频 → API 转码 H.264 → MinIO → Redis 入队
→ Worker 领取任务 → 下载视频 → 场景变化检测提取关键帧
→ YOLOv8 目标检测 → VLM 场景描述 → 文本向量化
→ ChromaDB 存储 + SQLite 事件记录 → 更新状态为 done
```

### 摄像头录制分析

```
添加摄像头（EZVIZ/RTSP）→ 启用录制
→ camera-worker 轮询 → 解析流地址 → ffmpeg 分段录制
→ 分段上传 MinIO → webhook 通知 API
→ API 创建视频记录 → 入队分析任务 → Worker 分析
```

### 智能搜索

```
用户输入查询 → LLM 意图解析（动作/目标/时间/问题类型）
→ ChromaDB 向量相似度搜索 → SQLite 获取事件详情
→ LLM 结果汇总 → 返回事件列表 + AI 摘要
```

## API 概览

### 视频管理
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/videos/upload` | 上传视频 |
| GET | `/api/videos` | 视频列表 |
| GET | `/api/videos/{id}` | 视频详情 |
| DELETE | `/api/videos/{id}` | 删除视频 |
| POST | `/api/videos/{id}/reanalyze` | 重新分析 |
| GET | `/api/videos/{id}/events` | 视频分析事件 |
| GET | `/api/videos/{id}/stream` | 视频流播放 |

### 事件
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/events/{id}` | 事件详情 |
| GET | `/api/events/{id}/frame` | 获取标注帧图片 |

### 搜索
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/search` | 自然语言搜索 |
| GET | `/api/search/suggestions` | 查询建议 |

### 摄像头
| 方法 | 路径 | 说明 |
|------|------|------|
| POST | `/api/cameras` | 添加摄像头 |
| GET | `/api/cameras` | 摄像头列表 |
| GET | `/api/cameras/{id}` | 摄像头详情 |
| PUT | `/api/cameras/{id}` | 更新摄像头 |
| DELETE | `/api/cameras/{id}` | 删除摄像头 |
| POST | `/api/cameras/{id}/recording/start` | 启用录制 |
| POST | `/api/cameras/{id}/recording/stop` | 停止录制 |
| GET | `/api/cameras/{id}/live-url` | 获取直播地址 |
| GET | `/api/cameras/{id}/segments` | 录制分段列表 |

### EZVIZ 萤石云
| 方法 | 路径 | 说明 |
|------|------|------|
| GET | `/api/ezviz/devices` | 获取萤石云设备列表 |
| POST | `/api/cameras/batch` | 批量导入设备 |

### 流媒体
| 方法 | 路径 | 说明 |
|------|------|------|
| GET/HEAD | `/api/hls-proxy/{path}` | HLS 代理 |

## 技术栈

| 层次 | 技术 |
|------|------|
| **容器编排** | K3s + Traefik Ingress |
| **对象存储** | MinIO (S3 兼容) |
| **任务队列** | Redis（Sorted Set 可靠队列 + Lua 原子操作 + 分布式锁） |
| **目标检测** | YOLOv8n/s (ultralytics, CPU 推理) |
| **视觉语言模型** | 可配置：Ollama (moondream:1.8b) 或 OpenAI 兼容 API (GLM-4V-Plus) |
| **大语言模型** | 可配置：Ollama (Qwen2.5:1.5b) 或 OpenAI 兼容 API (DeepSeek-V4) |
| **文本嵌入** | sentence-transformers (all-MiniLM-L6-v2, 384 维) |
| **向量检索** | ChromaDB（持久化，余弦相似度） |
| **结构化存储** | SQLite (WAL 模式, PVC 持久化) |
| **视频处理** | OpenCV（场景检测）+ ffmpeg（转码/录制） |
| **后端框架** | FastAPI (Python 3.11+) |
| **前端框架** | React 18 + Vite 6 + Ant Design 6 + TailwindCSS 3 |
| **视频播放** | HLS.js（前端直播）+ HTML5 Video（回放） |
| **RTSP 中继** | MediaMTX（可选，手机推流到 RTSP） |
| **摄像头集成** | EZVIZ（萤石云）API + 直连 RTSP |
| **容器构建** | nerdctl（节点构建）或 Kaniko（集群内构建） |
| **AI 提供商** | 共享抽象层，VLM/LLM 独立切换 Ollama / OpenAI 兼容 API |

## 关键设计

- **可靠任务队列**：基于 Redis Sorted Set + Hash + Lua 脚本，支持原子领取、锁续期、孤儿任务恢复、最多 3 次重试
- **AI 提供商抽象**：`shared/ai_provider.py` 提供统一接口，VLM 和 LLM 各自独立配置，可分别选择 Ollama 或 OpenAI 兼容 API
- **分析管道可恢复**：已处理的时间戳跳过，worker 重启后不重复工作
- **纯 CPU 运行**：所有模型均可在 CPU 上运行，Ollama Pod 建议 4GB+ 内存。有 GPU 后切换 GPU 节点即可无缝加速

## 性能说明（纯 CPU）

- 1 小时视频分析约需 **20-35 分钟**
- 单次自然语言查询约 **5-10 秒**
- Ollama Pod 建议分配 **4GB+ 内存**