ericwyuan/sentinel-home-ai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
06e1e5a30720b78cda96415fde61413613f60536
sentinel-home-ai/项目需求文档.md

1288 lines
59 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 家庭多模态智能监控系统 — 软件设计说明书
**版本**: v1.0
**日期**: 2026-08-19
**目标**: 多模型并行 + 交互式命名 + AI 对话的家庭监控系统
---
## 1. 设计目标与范围
### 1.1 首期范围（In Scope）
- FAM-Core 单进程，承载 Task-Scheduler / Dispatcher / Event-Receiver / Chat-Handler / Member-Manager / Video-Server 六个子模块
- FAM-Edge 单进程，承载视频下载 → FFmpeg 抽帧 → 本地 VLM 视觉分析 + Gemini 云端增强 → 本地 VLM 文本融合 → 回调 全链路
- FAM-UI 用 Streamlit 直读 DB，展示事件列表 + compute_provider 占比 + AI 对话页 + 对话历史 + 成员命名页
- 数据库六张表：process_tasks / monitor_events / daily_summaries（预留） / event_details / chat_history / family_members
- 任务状态机：PENDING → PROCESSING → SUCCESS/FAILED，含重试
- AI 对话：用户问"汤圆今天干嘛了"，FAM-Core 查 event_details 拼上下文 → 调 Oracle Ollama 纯文本 → 返回回答并写 chat_history
- 交互式成员命名：VLM 自动按特征提取"人物A/B/C"落库，用户在 FAM-UI 命名为"汤圆/妈妈"后，批量回溯更新历史记录，后续视频分析直接使用真实名字
### 1.2 不在首期范围（Out of Scope，推迟 v1.1+）
- Nginx 静态服务（用 Flask `send_from_directory` 替代）
- 资源保护策略 B（CPU/内存过载返回 503，单并发下不必要）
- 心跳监控（Heartbeat-Monitor，单任务串行下用整体超时兜底）
- 成员特征历史快照（members_snapshot_json 字段）
- API 业务接口鉴权（`/api/edge/*` 和 `/api/core/*` 不加鉴权；仅 Video-Server 的 `/media/*` 加 token，因为视频文件是敏感数据）
- Cron 兜底清理（finally 清理足够，Cron 推后）
### 1.3 仍保留的"非可选"埋点
即使首期也要做的，否则后期回头补很痛：
1. `task_id` 作为 trace_id，NAS 与 Oracle 两端日志必须带
2. 各阶段耗时落日志（download / extract / vlm_visual / vlm_fusion / callback）
3. `failure_stage` 字段落库（原 DDL 已有，保留）
4. Video-Server 路由带 `?token=xxx` 简单鉴权
---
## 2. 系统架构
### 2.1 物理节点与部署
三台物理/虚拟节点，通过 Tailscale 虚拟局域网互联（100.x.x.x/24 网段）。
| 节点 | 角色 | 硬件 | IP 地址 | 部署服务 | 监听端口 |
|------|------|------|---------|---------|---------|
| Synology NAS | FAM-Core + FAM-UI + 数据库 | NAS 自带资源 | Tailscale: 100.x.x.10<br>家庭局域网: 192.168.50.64 | FAM-Core (Flask)、FAM-UI (Streamlit)、MariaDB、Surveillance Station | 8000 (FAM-Core)、8501 (Streamlit)、3306 (MariaDB) |
| Oracle Cloud | FAM-Edge | 2C12G, ARM Ampere A1, 无 GPU | Tailscale: 100.x.x.20<br>公网: 129.146.203.203 | FAM-Edge (Flask)、Ollama、FFmpeg | 5000 (FAM-Edge)、11434 (Ollama) |
| 家庭网络 | 管理员/用户入口 | 普通终端 | 192.168.50.0/24 内 | 浏览器访问 FAM-UI | — |
**IP 访问约束**：
- Oracle ↔ NAS 的服务间通信一律走 Tailscale（100.x.x.10 / 100.x.x.20），不走公网，不走家庭局域网
- Oracle FAM-Edge 监听 `0.0.0.0:5000`，但安全组仅放行 Tailscale 入站；公网 129.146.203.203:5000 由安全组拦截
- NAS FAM-Core 监听 `0.0.0.0:8000`，Video-Server 路由靠 `?token=xxx` 鉴权；Tailscale 入站自由，家庭局域网 192.168.50.64:8000 也可达
- 家庭网络用户访问 FAM-UI 走 `http://192.168.50.64:8501`（局域网直连，不经 Tailscale）
### 2.2 部署拓扑图
```
┌──────────────────────────────────────────────────────────────────────────┐
│ Tailscale 虚拟局域网 (100.x.x.x/24) │
│ │
│ ┌──────────────────────────────────┐ ┌──────────────────────────┐ │
│ │ Synology NAS (FAM-Core) │ │ Oracle Cloud (FAM-Edge)│ │
│ │ 硬件: NAS 自带 │ │ 硬件: 2C12G ARM A1 │ │
│ │ Tailscale: 100.x.x.10 │ │ Tailscale: 100.x.x.20 │ │
│ │ 家庭局域网: 192.168.50.64 │ │ 公网: 129.146.203.203 │ │
│ │ (公网入站: 无, 仅出站) │ │ (公网入站: 仅 Tailscale)│ │
│ │ │ │ │ │
│ │ ┌────────────────────────────┐ │ │ ┌────────────────────┐ │ │
│ │ │ Surveillance Station │ │ │ │ FAM-Edge (Flask) │ │ │
│ │ │ - 录制视频 │ │ │ │ 端口: 5000 │ │ │
│ │ │ - 输出 mp4 至挂载目录 │ │ │ │ - Video-Preprocess │ │ │
│ │ └───────────┬────────────────┘ │ │ │ - AI-Orchestrator │ │ │
│ │ │ │ │ │ - Storage-Cleaner │ │ │
│ │ ▼ │ │ └─────────┬──────────┘ │ │
│ │ ┌────────────────────────────┐ │ │ │ │ │
│ │ │ NAS 挂载目录 │ │ │ ▼ │ │
│ │ │ /volume1/surveillance/ │◄─┼───────┼── HTTP GET /media/*.mp4 │ │
│ │ └───────────┬────────────────┘ │ │ (Tailscale, ?token) │ │
│ │ │ │ │ │ │
│ │ ▼ │ │ ┌────────────────────┐ │ │
│ │ ┌────────────────────────────┐ │ │ │ Ollama (systemd) │ │ │
│ │ │ FAM-Core (Flask) │ │ │ │ 端口: 11434 │ │ │
│ │ │ 端口: 8000 (Tailscale) │ │ │ │ 模型: llava-phi3 │ │ │
│ │ │ - Task-Scheduler │──┼───────┼─► HTTP POST 下发任务 │ │
│ │ │ - Dispatcher │◄─┼───────┼── HTTP POST 回调 │ │
│ │ │ - Event-Receiver │ │ │ │ │
│ │ │ - Video-Server │ │ │ ┌────────────────────┐ │ │
│ │ └───────────┬────────────────┘ │ │ │ FFmpeg + OpenCV │ │ │
│ │ │ │ │ │ (系统级二进制) │ │ │
│ │ ▼ │ │ └────────────────────┘ │ │
│ │ ┌────────────────────────────┐ │ │ ▲ │ │
│ │ │ MariaDB │ │ │ │ │ │
│ │ │ 端口: 3306 (本地) │◄─┼───────┼── HTTP 回调 (POST) │ │
│ │ │ - process_tasks │ │ 写入 │ │ task_id + 结果 JSON │ │
│ │ │ - monitor_events │ │ │ └────────────────────┘ │ │
│ │ │ - daily_summaries │ │ └──────────────────────────┘ │
│ │ └───────────┬────────────────┘ │ │
│ │ │ │ │
│ │ ▼ │ ┌──────────────┐ │
│ │ ┌────────────────────────────┐ │ │ 家庭网络用户 │ │
│ │ │ FAM-UI (Streamlit) │◄─┼───────────│ 浏览器 │ │
│ │ │ 端口: 8501 (局域网) │ │ 192.168. │ 192.168.50.x │ │
│ │ │ - Event-List │ │ 50.64:8501└──────────────┘ │
│ │ │ - Filter-Bar │ │ │
│ │ │ - Stats-Chart │ │ │
│ │ └────────────────────────────┘ │ │
│ └──────────────────────────────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
```
### 2.3 网络流与数据流
| # | 流向 | 协议 | 内容 | 触发方 |
|---|------|------|------|--------|
| 1 | SS → NAS 挂载目录 | 文件系统 | mp4 视频落盘 | Surveillance Station 定时录制 |
| 2 | NAS → NAS | 进程内 | Task-Scheduler 扫描目录，写 process_tasks | FAM-Core 内部 |
| 3 | NAS → Oracle | HTTP POST | Dispatcher 下发任务 (task_id + video_url + webhook) | FAM-Core |
| 4 | Oracle → NAS | HTTP GET | FAM-Edge 拉取 mp4 视频 | FAM-Edge |
| 5 | Oracle → Oracle | HTTP | FAM-Edge 调用 Ollama (视觉分析 + 文本融合) | FAM-Edge |
| 6 | Oracle → NAS | HTTP POST | FAM-Edge 回调 Event-Receiver，写 monitor_events | FAM-Edge |
| 7 | 浏览器 → NAS | HTTP | 访问 Streamlit UI | 家庭网络用户 |
### 2.4 端口与目录清单
**NAS 端**：
| 服务 | 端口 | 数据目录 | 配置文件 |
|------|------|---------|---------|
| FAM-Core | 8000 | — | `config/config.yaml`（成员特征改由 `family_members` 表管理） |
| MariaDB | 3306 | `/volume1/@database/mysql/` | MariaDB 默认配置 |
| FAM-UI | 8501 | — | `config/config.yaml` (复用) |
| Surveillance Station | (SS 默认) | `/volume1/surveillance/` | SS 控制台 |
| Video-Server 路由 | 8000 (复用) | `/volume1/surveillance/` | — |
**Oracle 端**：
| 服务 | 端口 | 工作目录 | 说明 |
|------|------|---------|------|
| FAM-Edge | 5000 | `/opt/fam-edge/` | 应用代码 |
| Ollama | 11434 | `~/.ollama/` | 模型存储 |
| FFmpeg | — | `/tmp/fam_media/task_<id>*/` | 临时帧图片，任务结束清理 |
### 2.5 与原文档的差异
| 章节 | 原设计 | 首期 | 理由 |
|------|-------|-----|------|
| 1.1 架构图 | Nginx 标"可选" | Flask `send_from_directory` 替代 | 首期并发 1，无需 Nginx |
| 1.2 技术选型 | Gemini 1.5 Flash（可选增强） | 首期纳入，与本地 VLM 并行调用 | 云端增强 + 交叉验证 |
| 2.1 FAM-Core | 未列 Video-Server | 加为子模块 | 主链路必需 |
| 2.1 FAM-Core | Heartbeat-Monitor | 首期不做 | 单任务串行，整体超时兜底 |
| 2.2 FAM-Edge | Local-LLM-Runtime 子模块 | 首期不单独管理 Ollama | 靠 systemd 托管 + `/api/tags` 探测，挂了 503 |
| 2.2 FAM-Edge | Storage-Cleaner 子模块 + Cron 兜底 | 仅 `finally` 清理 | 首期任务量小，Cron 推后 |
| 2.3 FAM-UI | 成员管理页（缺失） | 首期纳入，新增 Member-Naming 页 | 交互式命名流程，用户给"人物A/B"赋真名 |
| 2.4 熔断器 | CircuitBreaker | 首期纳入 | Gemini 连续失败跳过调用，冷却后探测恢复 |
| 2.5 资源保护 | 策略 B（503） | 首期不做 | 单并发下无意义 |
| DB | family_members 表（缺失） | 首期新增 | 支持交互式命名，VLM 输出 abstract_label，用户命名后批量回溯更新 |
| API payload | `known_members_context` 字符串 | 改为注入已命名+未命名成员清单 | NAS 端从 `family_members` 表读取后拼接 |
---
## 3. 模块设计
### 3.1 FAM-Core（NAS 端，单进程）
| 模块 | 职责 | 首期简化 |
|------|------|---------|
| Task-Scheduler | 60s 轮询视频目录，创建 PENDING 任务 | `is_complete` 判定简化为"修改时间 > 60s 且文件大小稳定" |
| Dispatcher | 30s 轮询 PENDING 任务，下发至 Edge | 退避重试保留，但所有 stage 一视同仁；payload 注入已命名成员清单 |
| Event-Receiver | Flask 路由，接收 Edge 回调，写库 | 单 worker，不做幂等锁；接收 `frame_details` 数组，逐条插入 `event_details`；对未命名的 abstract_label 自动 upsert 到 `family_members` |
| Chat-Handler | Flask 路由，接收用户问答 | 查 `event_details` 拼上下文 → 调 Oracle Ollama 纯文本 → 写 `chat_history` |
| Member-Manager | Flask 路由，成员命名管理 | 列出未命名人物；接收命名请求；批量 UPDATE `event_details` 回溯历史 |
| Video-Server | Flask `send_from_directory`，提供 mp4 静态下载 | 路由带 `?token=xxx` 鉴权 |
### 3.2 FAM-Edge（Oracle 端，单进程）
| 模块 | 职责 | 首期简化 |
|------|------|---------|
| API-Gateway | 接收任务，并发控制 | 同时只允许 1 个任务在处理；新任务到达时若当前有任务处理中，返回 429 |
| Video-Preprocessor | 下载视频 + FFmpeg 粗抽帧 + OpenCV 关键帧筛选 + 压缩 | 下载超时 60s；粗抽 30 张候选帧；筛 5-8 张关键帧；长边 ≤ 1024px，JPEG 质量 80 |
| AI-Orchestrator | 调用 Ollama 视觉分析 + Gemini 视觉分析 + Ollama 文本融合 | Gemini 异步并行调用，超时 8s 不阻塞；熔断器保护；失败降级 local_only |
| Storage-Cleaner | `finally` 删除下载的视频和帧图片 | 不做 Cron 兜底 |
### 3.3 FAM-UI（NAS 端）
| 模块 | 职责 | 首期简化 |
|------|------|---------|
| Event-List | 分页展示事件 | 按时间倒序，每页 20 条 |
| Filter-Bar | 按日期筛选 | 仅日期，不做事件类型筛选 |
| Stats-Chart | compute_provider 占比 | 用 Streamlit 内置 bar_chart |
| Chat-Page | AI 对话页签 | 输入框 + 调用 `POST /api/chat/ask` + 展示回答；按 `queried_person` 预设快捷提问按钮 |
| Chat-History | 对话历史列表 | 按 `chat_history.created_at` 倒序，每页 20 条 |
| Member-Naming | 成员命名页 | 列出 `family_members` 中 `real_name IS NULL` 的未命名人物，展示特征描述，输入框命名后调 `POST /api/member/name`；命名后展示已命名成员列表 |
---
## 4. 数据流（首期主链路）
### 4.1 时序
1. NAS 发现新视频 → 写入 `process_tasks` (PENDING)
2. Dispatcher 下发任务至 Oracle (`POST /api/edge/video/analyze`)
3. Oracle 返回 202 → NAS 更新状态为 PROCESSING
4. Oracle 内部：
- a. 下载视频（超时 60s）
- b. FFmpeg 粗抽 30 张候选帧 + OpenCV 关键帧筛选（5-8 张）+ 压缩
- c. 并行启动：本地 VLM 多模态视觉分析（5-8 张关键帧，超时 240s）+ Gemini 云端视觉分析（超时 8s，可选）
- d. 等待 Gemini 结果（最多 8s，超时或熔断则 `gemini_output=None`，不阻塞）
- e. 本地 VLM 纯文本融合（VLM_OUTPUT + GEMINI_OUTPUT，超时 120s）
- f. 回调 NAS（超时 30s，失败重试 3 次）
- g. 清理临时文件
5. NAS 收到回调 → 写入 `monitor_events`（含 `compute_provider: hybrid` 或 `local_only`），更新任务 SUCCESS
6. UI 展示
### 4.2 与原文档的差异
- 删除心跳发送步骤
- 整体超时仍为 600s，由 Edge 端内部定时器控制
- 保留并行 Gemini 调用（首期纳入），熔断器保护，失败降级 local_only
---
## 5. 数据库设计
### 5.1 DDL（与原文档一致）
```sql
-- 任务表
CREATE TABLE process_tasks (
task_id INT AUTO_INCREMENT PRIMARY KEY,
video_path VARCHAR(500) NOT NULL,
video_url VARCHAR(500) NOT NULL,
status ENUM('PENDING','PROCESSING','SUCCESS','FAILED') DEFAULT 'PENDING',
retry_count INT DEFAULT 0,
max_retries INT DEFAULT 3,
next_retry_at DATETIME NULL,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
error_message TEXT NULL,
failure_stage ENUM('download','extract','vlm_visual','vlm_fusion','callback') NULL,
heartbeat_at DATETIME NULL,
INDEX idx_status (status),
INDEX idx_created (created_at)
) ENGINE=InnoDB;
-- 事件表
CREATE TABLE monitor_events (
event_id INT AUTO_INCREMENT PRIMARY KEY,
task_id INT NOT NULL,
event_start_time DATETIME NOT NULL,
event_end_time DATETIME NOT NULL,
camera_name VARCHAR(50),
global_summary TEXT,
entities_json JSON NOT NULL,
compute_provider JSON NOT NULL, -- 模型来源数组，如 ["ollama","gemini"]
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
INDEX idx_event_start (event_start_time),
INDEX idx_compute_provider (compute_provider),
FOREIGN KEY (task_id) REFERENCES process_tasks(task_id) ON DELETE CASCADE
) ENGINE=InnoDB;
-- 每日摘要表（预留）
CREATE TABLE daily_summaries (
id INT AUTO_INCREMENT PRIMARY KEY,
target_date DATE NOT NULL UNIQUE,
summary_text TEXT,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP
) ENGINE=InnoDB;
-- 事件明细表（每关键帧一条，由 VLM 输出 frame_details 拆分落库）
CREATE TABLE event_details (
detail_id INT AUTO_INCREMENT PRIMARY KEY,
event_id INT NOT NULL, -- 关联 monitor_events.event_id
task_id INT NOT NULL, -- 冗余，便于查询
frame_index INT NOT NULL, -- 关键帧序号（1-8）
frame_timestamp DATETIME NOT NULL, -- 该帧对应的绝对时间点
camera_name VARCHAR(50), -- 摄像头位置（如"客厅"）
person VARCHAR(50) NOT NULL, -- 成员名或"未知访客"
action VARCHAR(200) NOT NULL, -- 动作描述（AI 自由生成，无枚举）
clothing VARCHAR(100), -- 衣着
is_attention_event BOOLEAN DEFAULT FALSE, -- 由 AI 自行判断是否为关注事件，无固定清单
source_providers JSON NOT NULL, -- 识别到该明细的模型来源数组，如 ["ollama","gemini"]
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
INDEX idx_event_id (event_id),
INDEX idx_frame_timestamp (frame_timestamp),
INDEX idx_person (person),
INDEX idx_queried_date (frame_timestamp),
FOREIGN KEY (event_id) REFERENCES monitor_events(event_id) ON DELETE CASCADE
) ENGINE=InnoDB;
-- 对话记录表（用户与 AI 问答的完整记录）
CREATE TABLE chat_history (
chat_id INT AUTO_INCREMENT PRIMARY KEY,
user_question TEXT NOT NULL, -- 用户问题
ai_answer TEXT NOT NULL, -- AI 回答
context_summary TEXT, -- 问答时使用的上下文摘要（可选）
queried_date DATE, -- 查询的日期范围
queried_person VARCHAR(50), -- 查询的人物
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
INDEX idx_created (created_at),
INDEX idx_queried_date (queried_date)
) ENGINE=InnoDB;
-- 家庭成员表（交互式命名）
CREATE TABLE family_members (
member_id INT AUTO_INCREMENT PRIMARY KEY,
abstract_label VARCHAR(20) NOT NULL UNIQUE, -- VLM 首次提取的抽象标识，如 "人物A"
real_name VARCHAR(50), -- 用户命名的真实名字，如 "汤圆"；NULL 表示未命名
feature_description TEXT, -- VLM 提取的特征描述，如 "短发、黄色T恤、男性"
first_seen_at DATETIME, -- 首次被提取的时间
named_at DATETIME NULL, -- 用户命名的时间
named_by VARCHAR(50), -- 命名人
is_active BOOLEAN DEFAULT TRUE,
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
INDEX idx_real_name (real_name),
INDEX idx_abstract_label (abstract_label)
) ENGINE=InnoDB;
```
### 5.2 表关系
```
process_tasks (1) ─── (N) monitor_events (1) ─── (N) event_details
│
└─ event_id 外键
family_members 独立表
- event_details.person 存 family_members.abstract_label（未命名时）或 real_name（命名后）
- 命名后批量 UPDATE event_details SET person = real_name WHERE person = abstract_label
chat_history 独立表，不与上述表强关联
```
### 5.3 compute_provider 取值（多模型场景）
`monitor_events.compute_provider` 记录本次任务调用了哪些模型，JSON 数组字符串：
| 场景 | 取值示例 | 说明 |
|------|---------|------|
| 仅本地 Ollama 成功 | `["ollama"]` | Gemini 超时/失败/熔断 |
| Ollama + Gemini 均成功 | `["ollama","gemini"]` | 首期典型场景 |
| 加 OpenAI（v1.1） | `["ollama","gemini","openai"]` | 扩展场景 |
| 全部失败 | 任务 FAILED | 不写入 monitor_events |
**字段类型调整**：`compute_provider` 由原 ENUM 改为 JSON 数组，便于动态扩展。原 ENUM('hybrid','local_only') 已不适用多模型场景。
`event_details.source_providers` 与 `monitor_events.compute_provider` 的关系：
- `compute_provider` 记录本次任务级别调用了哪些模型（数组去重）
- `source_providers` 记录该条 frame_detail 被哪些模型识别到（可能少于 compute_provider，例如某帧 Gemini 没识别到人物但 Ollama 识别了）
---
## 6. API 规范
## 6. API 规范
### 6.1 POST /api/edge/video/analyze（Edge 接收任务）
请求体：
```json
{
"task_id": 1001,
"video_url": "http://100.x.x.10:8000/media/video_171500.mp4?token=xxx",
"webhook_url": "http://100.x.x.10:8000/api/core/callback/event",
"known_members_context": "成员A:特征描述; 成员B:特征描述"
}
```
响应：
- 202 Accepted：任务已入队
- 429 Too Many Requests：队列已满（>1 个等待）
- 503 Service Unavailable：Ollama 不可用
### 6.2 POST /api/core/callback/event（NAS 接收回调）
成功请求体：
```json
{
"task_id": 1001,
"status": "success",
"event_start_time": "2026-08-19T14:00:00Z",
"event_end_time": "2026-08-19T14:30:00Z",
"camera_name": "客厅",
"global_summary": "客厅有人员走动，汤圆在玩积木，期间跌倒一次。",
"entities_json": [
{"person": "汤圆", "action": "在地毯上玩积木", "clothing": "黄色T恤"}
],
"frame_details": [
{
"frame_index": 1,
"frame_timestamp": "2026-08-19T14:03:00Z",
"person": "汤圆",
"action": "在地毯上玩积木",
"clothing": "黄色T恤",
"is_attention_event": false
},
{
"frame_index": 5,
"frame_timestamp": "2026-08-19T14:25:00Z",
"person": "汤圆",
"action": "跌倒",
"clothing": "黄色T恤",
"is_attention_event": true
}
],
"compute_provider": "local_only",
"error_message": null
}
```
**Event-Receiver 处理逻辑**：
1. 插入 `monitor_events` 1 条（聚合记录，含 global_summary / entities_json / camera_name）
2. 遍历 `frame_details` 数组，逐条插入 `event_details`（条数无上限，AI 输出多少插多少；`action` 由 AI 自由生成，无枚举过滤）
3. 更新 `process_tasks` 状态为 SUCCESS
失败请求体：
```json
{
"task_id": 1001,
"status": "failed",
"failure_stage": "vlm_visual",
"error_message": "VLM inference timeout"
}
```
响应：200 OK
### 6.3 GET /media/\<path:filename\>（Video-Server 静态服务）
- 带鉴权：`?token=xxx`，token 从 NAS 端配置读取
- 无 token 或 token 错误返回 403
- 文件不存在返回 404
### 6.4 POST /api/chat/ask（NAS 接收用户问答）
请求体：
```json
{
"question": "汤圆今天干嘛了？",
"queried_person": "汤圆",
"queried_date": "2026-08-19"
}
```
响应（200 OK）：
```json
{
"answer": "根据今日监控数据，汤圆主要活动如下：\n14:03 在客厅地毯上玩积木\n14:25 在客厅跌倒一次（关注事件）\n15:10 在客厅看绘本\n...",
"context_summary": "查询 event_details 12 条，时间范围 14:03-18:30",
"chat_id": 5001
}
```
**Chat-Handler 处理逻辑**：
1. 根据 `queried_person` 和 `queried_date` 查询 `event_details`
```sql
SELECT frame_timestamp, camera_name, person, action, clothing,
is_attention_event
FROM event_details
WHERE person = :queried_person
AND DATE(frame_timestamp) = :queried_date
ORDER BY frame_timestamp ASC
```
2. 拼接上下文（每条明细一行：`[14:03 客厅] 汤圆 在地毯上玩积木 (黄色T恤)`）
3. 若明细条数 > 50，按小时聚合成 24 行摘要再喂给 VLM（避免超 llava-phi3 上下文 2000 字）
4. POST Oracle Ollama 纯文本模式，调问答 Prompt
5. 插入 `chat_history`（user_question + ai_answer + context_summary + queried_date + queried_person）
6. 返回回答
**问答 Prompt（中文）**：
```
你是家庭监控助手。根据以下今日监控数据，回答用户问题。
今日数据（按时间顺序，每条一行）：
[14:03 客厅] 汤圆 在地毯上玩积木 (黄色T恤)
[14:25 客厅] 汤圆 跌倒 (黄色T恤) [关注事件]
[15:10 客厅] 汤圆 看绘本 (黄色T恤)
...
已知家庭成员: 汤圆（特征描述）
用户问题: {question}
要求:
- 只基于上述数据回答，不要编造
- 按时间顺序总结
- 若有关注事件（跌倒、哭闹等），重点提示
- 若当天没有该人员的数据，明确说"今天没有观察到{person}"
- 用自然语言回答，不要输出 JSON
```
### 6.5 GET /api/chat/history（获取对话历史，可选）
查询参数：`?date=2026-08-19` 或 `?person=汤圆&limit=20`
响应：按 `chat_history.created_at` 倒序返回对话列表。
### 6.6 GET /api/member/unnamed（列出未命名人物）
响应（200 OK）：
```json
{
"unnamed_members": [
{
"abstract_label": "人物A",
"feature_description": "短发、黄色T恤、男性",
"first_seen_at": "2026-08-19T14:03:00Z",
"event_count": 15
},
{
"abstract_label": "人物B",
"feature_description": "长发、红色裙子、女性",
"first_seen_at": "2026-08-19T15:10:00Z",
"event_count": 8
}
]
}
```
### 6.7 POST /api/member/name（命名人物）
请求体：
```json
{
"abstract_label": "人物A",
"real_name": "汤圆",
"named_by": "管理员"
}
```
**Member-Manager 处理逻辑**：
1. 校验 `abstract_label` 存在于 `family_members` 且 `real_name IS NULL`
2. UPDATE `family_members` SET `real_name=:real_name, named_at=NOW(), named_by=:named_by` WHERE `abstract_label=:abstract_label`
3. 批量回溯更新历史记录：
```sql
UPDATE event_details SET person = :real_name
WHERE person = :abstract_label;
UPDATE monitor_events
SET entities_json = JSON_REPLACE(entities_json, '$[*].person', :real_name)
WHERE entities_json LIKE :abstract_label_pattern;
```
4. 响应（200 OK）：
```json
{
"abstract_label": "人物A",
"real_name": "汤圆",
"updated_event_details_count": 15,
"updated_monitor_events_count": 8
}
```
### 6.8 GET /api/member/list（列出所有成员）
查询参数：`?include_named=true&include_unnamed=true`
响应：返回 `family_members` 全表，按 `first_seen_at` 升序。
---
## 7. 关键技术
### 7.1 视频预处理（关键帧筛选）
不再使用等距抽 30 帧的方案，改为关键帧筛选，将 VLM 输入图片数量从 30 降到 5-8 张。
**两步流程**：
**步骤 1：等距粗抽帧**
- `ffprobe` 获取视频时长（秒）
- 计算 `interval = duration / 30`
- `ffmpeg -vf fps=1/{interval}` 抽出 30 张候选帧
**步骤 2：帧差分析筛选关键帧**
- 用 OpenCV 对 30 张候选帧两两计算 MSE（均方误差）或 SSIM（结构相似性）
- 筛选规则（按优先级）：
1. **首帧必选**（保留时间起点）
2. **末帧必选**（保留时间终点）
3. **差异最大的 N 帧**：遍历 30 张，保留与上一关键帧 MSE > 阈值（默认 500）的帧
4. 若筛选结果 < 5 帧，从剩余候选中按时间均匀补足到 5 帧
5. 若筛选结果 > 8 帧，按差异值降序取前 8 帧
- 最终输出 5-8 张关键帧
**步骤 3：压缩**
- OpenCV 缩放（长边 > 1024 才缩）+ JPEG 质量 80 保存
**MSE 阈值参数**：
- 默认 `MSE_THRESHOLD = 500`（对应像素差异约 22，可调）
- 配置项放 `config.yaml`，便于现场调优
**异常兜底**：
- ffprobe 失败 → 退化为按 60s 间隔抽帧
- 帧差分析异常 → 退化为等距抽 5 帧
- OpenCV 压缩失败 → 跳过该帧，记录 WARN
### 7.2 本地 VLM 两阶段调用
#### 7.2.1 视觉分析阶段（多模态输入，并行调用）
本地 VLM 和 Gemini 云端并行调用，两个结果都送入文本融合阶段做交叉验证。
**本地 VLM 调用**：
- **模型**：`llava-phi3`（Ollama）
- **输入**：5-8 张关键帧（Base64 编码）+ 中文 Prompt
- **调用方式**：一次性输入所有关键帧（数量已降到 5-8，上下文压力可控）
- **参数**：`temperature=0.2, top_p=0.8`
- **超时**：240s（5-8 张 × 单张 ≤ 8s ≈ 40-64s，有充足余量）
- **输出**：VLM_OUTPUT，自然语言描述，按帧顺序逐段输出
**Gemini 云端调用**（详见 7.6）：
- **模型**：`gemini-1.5-flash`（Google AI Studio API）
- **输入**：同批 5-8 张关键帧（inline_data Base64）+ 英文 Prompt
- **调用方式**：`ThreadPoolExecutor` 异步并行，与本地 VLM 同时启动
- **参数**：`temperature=0.2, top_p=0.8`
- **超时**：8s（`future.result(timeout=8)`，超时或异常返回 None，不阻塞主链路）
- **熔断保护**：连续 5 次失败 → OPEN 状态 15 分钟内跳过调用（详见 7.6.4）
- **输出**：GEMINI_OUTPUT，自然语言描述；失败/超时/熔断时为 None
**视觉分析 Prompt（中文，含时间戳注入 + 交互式命名）**：
Oracle 抽帧时记录每帧在视频中的时间偏移（秒），加上视频开始时间（event_start_time），得到绝对时间。注入 Prompt 时按帧序号列出。
NAS 端 Dispatcher 下发任务时，从 `family_members` 表读取已命名成员清单，注入 Prompt。未命名成员（`real_name IS NULL`）的特征描述也注入，提示 VLM 用其 `abstract_label`（如"人物A"）标识。
```
你是家庭监控视频分析助手。请按时间顺序描述下列 {N} 张图片中可见的内容，只描述客观画面，不要猜测或推测。
每张图片对应的时间戳如下：
[图片1] 时间: {frame_timestamp_1} # 例: 2026-08-19 14:03:00
[图片2] 时间: {frame_timestamp_2}
...
[图片N] 时间: {frame_timestamp_N}
每张图片需报告：
1. 人物：数量、衣着（颜色+类型）、可见动作
2. 物品：玩具、奶瓶、家具等显眼物品
3. 互动：人与人、人与物品之间的互动
已知家庭成员清单（按特征匹配，匹配成功用 real_name，未匹配用"人物X"标识）：
{known_members_context}
# 注入示例：
# 汤圆: 短发、黄色T恤、男性（real_name=汤圆）
# 人物A: 长发、红色裙子、女性（abstract_label=人物A，未命名）
# 若画面人物与上述特征匹配，使用对应的名字或 abstract_label；
# 若画面人物与上述都不匹配，按出现顺序赋予新标识"人物B"、"人物C"...
输出格式（纯文本，每张图片一段，保留时间戳标记）：
[图片1] 时间: {frame_timestamp_1}
内容: ...
[图片2] 时间: {frame_timestamp_2}
内容: ...
...
要求简洁、客观。不要输出 JSON，不要输出 markdown。
```
#### 7.2.2 文本融合阶段（纯文本输入，多模型平等交叉验证）
- **模型**：`llava-phi3`（同一模型，纯文本模式）
- **输入**：所有启用模型的视觉分析输出（键值对，provider → 输出文本）+ 已知成员清单
- **参数**：`temperature=0.0, format="json"`
- **超时**：120s
- **输出**：JSON 结构（global_summary / entities_json / frame_details / compute_provider）
**文本融合 System Prompt（中文，多模型平等交叉验证）**：
```
你是一个无情的数据提取器。不要输出任何思考过程，只输出合法 JSON。
输入参数:
- 多模型视觉分析日志（每个模型独立输出，平等对待，交叉验证）:
- <PROVIDER_1> 输出: <OUTPUT_1> # 例: ollama 输出
- <PROVIDER_2> 输出: <OUTPUT_2> # 例: gemini 输出
- ...（数量可变，由实际调用的模型决定）
- 已知成员清单: <KNOWN_MEMBERS>
执行规则:
1. 多个模型的输出平等对待，交叉验证：
- 多个模型一致描述的内容 → 可信度高，必须纳入 frame_details，source_providers 列出所有一致的模型
- 仅单一模型描述的内容 → 纳入 frame_details，source_providers 仅含该模型
- 多个模型冲突时（如人物动作描述不一致）→ 以多数模型一致为准，source_providers 列出多数派模型
2. 画面人物按特征匹配已知成员清单：
- 匹配到已命名成员（real_name 非空）→ person 字段填 real_name（如"汤圆"）
- 匹配到未命名成员（real_name 为空）→ person 字段填 abstract_label（如"人物A"）
- 都不匹配 → 按出现顺序赋予新标识"人物B"、"人物C"...
3. 提取每张关键帧对应的时间点、人物、动作、衣着，输出到 frame_details 数组。
4. frame_details 每条必须包含 source_providers 数组，列出识别到该条内容的模型来源。
5. compute_provider 字段填入本次实际成功调用的所有模型标识数组（去重）。
6. 仅输出合法 JSON，不输出任何思考过程、markdown 标记或注释。
输出 JSON 结构:
{
"global_summary": "字符串，整个时段的整体摘要，简体中文",
"entities_json": [
{
"person": "字符串，已命名成员的 real_name，或未命名成员的 abstract_label（人物A/B/C...）",
"action": "字符串，简体中文动作描述",
"clothing": "字符串，简体中文衣着描述，可为空字符串"
}
],
"frame_details": [
{
"frame_index": "数字，关键帧序号（1-8）",
"frame_timestamp": "字符串，ISO 8601 格式时间戳，与视觉日志中的时间戳一致",
"person": "字符串，已命名成员的 real_name，或未命名成员的 abstract_label",
"action": "字符串，简体中文动作描述，由 AI 自由生成，无枚举限制",
"clothing": "字符串，简体中文衣着描述，可为空字符串",
"is_attention_event": "布尔值，由 AI 自行判断该动作是否属于需要关注的异常行为（如跌倒、哭闹、玩危险物品等），无需匹配固定清单",
"source_providers": "数组，识别到该条内容的模型标识，如 [\"ollama\",\"gemini\"]"
}
],
"compute_provider": "数组，本次实际成功调用的所有模型标识，如 [\"ollama\",\"gemini\"]"
}
```
**Event-Receiver 对未命名 abstract_label 的处理**：
- 收到回调后，对 frame_details 中每个 person 字段值
- 若该值形如 `人物X`（正则 `^人物[A-Z]$`）且不在 `family_members` 表中：
- INSERT INTO family_members (abstract_label, feature_description, first_seen_at) VALUES (...)
- feature_description 从该帧的 clothing + action 推断拼接
- 若已存在，跳过（不更新 feature_description，保留首次提取的描述）
**frame_details 字段说明**：
- 数组长度等于关键帧数量（5-8 条）
- `frame_timestamp` 必须与视觉分析阶段 Prompt 注入的时间戳一致
- `frame_index` 从 1 开始，与图片序号对应
- `action` 由 AI 自由生成，无枚举过滤
- `is_attention_event` 由 AI 自行判断，不预设事件清单
- `source_providers` 必填，数组，列出识别到该条内容的模型标识
- 条数无上限，AI 输出多少条就插多少条到 `event_details`
#### 7.2.3 JSON 解析容错与 Schema 校验
三层容错策略，从最稳到最不稳依次尝试：
```python
def parse_vlm_json(raw: str) -> dict:
# 第 1 层：直接 json.loads
try:
return validate_schema(json.loads(raw.strip()))
except json.JSONDecodeError:
pass
# 第 2 层：提取 markdown fence 内容（llava 经常会加 ```json ... ```）
fence_match = re.search(r'```(?:json)?\s*(\{.*?\})\s*```', raw, re.DOTALL)
if fence_match:
try:
return validate_schema(json.loads(fence_match.group(1)))
except json.JSONDecodeError:
pass
# 第 3 层：贪婪匹配最大的 {...}
brace_match = re.search(r'\{.*\}', raw, re.DOTALL)
if brace_match:
try:
return validate_schema(json.loads(brace_match.group(0)))
except json.JSONDecodeError:
pass
raise VLMOutputInvalidError(f"无法从 VLM 输出中解析 JSON: {raw[:200]}")
def validate_schema(data: dict) -> dict:
"""Schema 校验 + 脏数据清洗"""
required = ["global_summary", "entities_json", "frame_details", "compute_provider"]
for k in required:
if k not in data:
raise VLMOutputInvalidError(f"缺失字段: {k}")
# entities_json 结构校验
if not isinstance(data["entities_json"], list):
raise VLMOutputInvalidError("entities_json 必须为数组")
cleaned_entities = []
for ent in data["entities_json"]:
if not isinstance(ent, dict):
continue
if "person" not in ent or "action" not in ent:
raise VLMOutputInvalidError("entity 缺少 person 或 action 字段")
cleaned_entities.append({
"person": str(ent["person"]),
"action": str(ent["action"]),
"clothing": str(ent.get("clothing", ""))
})
data["entities_json"] = cleaned_entities
# frame_details 结构校验（无枚举过滤，AI 自由生成）
if "frame_details" not in data:
data["frame_details"] = []
if not isinstance(data["frame_details"], list):
raise VLMOutputInvalidError("frame_details 必须为数组")
cleaned_frames = []
for frame in data["frame_details"]:
if not isinstance(frame, dict):
continue
# 必填字段：frame_index, frame_timestamp, person, action, source_providers
for k in ["frame_index", "frame_timestamp", "person", "action", "source_providers"]:
if k not in frame:
raise VLMOutputInvalidError(f"frame_details 缺少字段: {k}")
# source_providers 必须是非空数组
sp = frame["source_providers"]
if not isinstance(sp, list) or len(sp) == 0:
raise VLMOutputInvalidError("frame_details.source_providers 必须为非空数组")
cleaned_frames.append({
"frame_index": int(frame["frame_index"]),
"frame_timestamp": str(frame["frame_timestamp"]),
"person": str(frame["person"]),
"action": str(frame["action"]), # 由 AI 自由生成，无枚举过滤
"clothing": str(frame.get("clothing", "")),
"is_attention_event": bool(frame.get("is_attention_event", False)),
"source_providers": [str(p) for p in sp] # 模型标识数组，如 ["ollama","gemini"]
})
data["frame_details"] = cleaned_frames
# compute_provider 校验为数组（多模型场景）
if not isinstance(data["compute_provider"], list):
raise VLMOutputInvalidError("compute_provider 必须为数组")
if len(data["compute_provider"]) == 0:
raise VLMOutputInvalidError("compute_provider 不能为空数组")
data["compute_provider"] = [str(p) for p in data["compute_provider"]]
return data
```
**容错层级说明**：
- 第 1 层：最理想情况，模型直接输出合法 JSON
- 第 2 层：模型加了 markdown fence 包裹
- 第 3 层：模型输出有前后缀文字，但 JSON 片段完整
- 三层全部失败 → 抛 `VLMOutputInvalidError`，任务进入 FAILED 状态，由 Dispatcher 退避重试
**`validate_schema` 的脏数据清洗**：
- entities_json 中非 dict 元素被过滤
- frame_details 中非 dict 元素被过滤
- frame_details 的 `action` 字段由 AI 自由生成，**不做枚举过滤**
- frame_details 的 `is_attention_event` 由 AI 自行判断，不预设事件清单
- frame_details 的 `source_providers` 必须为非空数组
- compute_provider 必须为非空数组，由融合阶段根据实际成功调用的模型动态填入
### 7.3 模型健康探测
接收任务前，AI-Orchestrator 遍历 `config.yaml` 中所有 `enabled: true` 的模型，逐个调用其适配器的 `health_check()` 方法：
| 适配器 | 健康检查方法 | 判定条件 |
|--------|------------|---------|
| OllamaAdapter | `GET /api/tags` | HTTP 200 且响应含配置的模型名（如 `llava-phi3`） |
| GeminiAdapter | `GET https://generativelanguage.googleapis.com/v1/models?key=API_KEY` | HTTP 200 且响应含 `gemini-1.5-flash` |
| OpenAIAdapter (v1.1) | `GET /v1/models` 带鉴权头 | HTTP 200 |
| NvidiaAdapter (v1.1) | `GET /v1/models` 带鉴权头 | HTTP 200 |
- 至少一个模型健康 → 接收任务，进入 202
- 全部模型不健康 → 返回 503，NAS 端 Dispatcher 退避重试
- 任务执行时，单个模型不健康跳过该模型，其他模型照常调用（动态降级）
- Ollama 由 systemd 托管，FAM-Edge 不管理进程
### 7.4 任务超时与重试
- 整体超时 600s（Edge 端内部定时器）
- 失败后由 NAS 端 Dispatcher 退避重试：`min(60 * (retry_count + 1) * 2, 600)` 秒
- 超过 max_retries=3 置为 FAILED
### 7.5 日志与可观测性（首期最小集）
- 所有日志带 `task_id` 作为 trace_id
- 各阶段打 INFO 日志，格式：`[task_id={id}] {stage} done in {ms}ms`
- 模型调用日志：`[task_id={id}] model {provider} done in {ms}ms, success={bool}`
- 失败打 ERROR 日志，带 failure_stage 和 error_message
- 不做指标聚合和告警，v1.1 再说
### 7.6 模型适配器架构（可扩展多模型）
#### 7.6.1 抽象基类
```python
from abc import ABC, abstractmethod
from typing import List, Optional
class BaseModelAdapter(ABC):
"""所有模型适配器的抽象基类。新增模型只需继承此类并实现 4 个方法。"""
def __init__(self, provider_name: str, config: dict):
self.provider_name = provider_name # 如 "ollama", "gemini", "openai"
self.config = config # 从 config.yaml 读到的该模型配置
@abstractmethod
def health_check(self) -> bool:
"""健康检查，返回 True/False"""
pass
@abstractmethod
def analyze_frames(self, frame_paths: List[str],
frame_timestamps: List[str],
known_members_context: str) -> Optional[str]:
"""视觉分析：输入帧图片路径 + 时间戳 + 成员清单，输出自然语言描述。
失败/超时返回 None。"""
pass
@abstractmethod
def get_timeout(self) -> int:
"""该模型的调用超时秒数"""
pass
@abstractmethod
def get_circuit_breaker(self):
"""返回该模型专属的熔断器实例"""
pass
```
#### 7.6.2 首期实现的适配器
**OllamaAdapter**（本地模型）：
- `provider_name = "ollama"`
- 健康检查：`GET http://localhost:11434/api/tags`
- `analyze_frames`：调用 `ollama.generate(model="llava-phi3", prompt=..., images=[base64...], options={"temperature":0.2,"top_p":0.8})`
- 超时：240s
- 熔断器：不启用（本地模型，挂了靠健康检查拦截）
**GeminiAdapter**（云端）：
- `provider_name = "gemini"`
- 健康检查：`GET https://generativelanguage.googleapis.com/v1/models?key=API_KEY`
- `analyze_frames`：调用 `google-generativeai` SDK，`GenerativeModel("gemini-1.5-flash").generate_content(prompt, [PIL.Image, ...])`
- 超时：8s
- 熔断器：启用，连续 5 次失败 → OPEN 15 分钟，HALF_OPEN 允许一次探测
#### 7.6.3 v1.1 扩展适配器（接口位预留）
- **OpenAIAdapter**：`provider_name="openai"`，调 `openai.ChatCompletion` 或 `gpt-4o` 视觉接口
- **NvidiaAdapter**：`provider_name="nvidia"`，调 NVIDIA NIM API
- 新增模型只需：继承 `BaseModelAdapter` + 在 `config.yaml` 的 `models` 数组加一项 + 在适配器工厂注册
#### 7.6.4 熔断器（CircuitBreaker，每个云端模型独立实例）
```python
from collections import deque
import time
class CircuitBreaker:
def __init__(self, threshold: int = 5, cooldown: int = 900):
self.failures = deque(maxlen=threshold)
self.state = 'CLOSED' # CLOSED / OPEN / HALF_OPEN
self.cooldown = cooldown
self.last_failure = None
def record_failure(self):
self.failures.append(time.time())
if len(self.failures) >= self.failures.maxlen:
self.state = 'OPEN'
self.last_failure = time.time()
def record_success(self):
self.failures.clear()
self.state = 'CLOSED'
def is_open(self):
if self.state == 'OPEN' and time.time() - self.last_failure > self.cooldown:
self.state = 'HALF_OPEN'
return self.state == 'OPEN'
```
- 阈值：连续 5 次失败触发 OPEN
- 冷却：15 分钟后转 HALF_OPEN，允许一次探测
- 探测成功 → CLOSED；探测失败 → 重新 OPEN 计时
- OPEN 状态直接跳过该模型调用，`analyze_frames` 返回 None
### 7.7 AI-Orchestrator 调用流程（多模型并行）
```python
def process_task_worker(task_data):
# 1. 加载所有启用的模型适配器
adapters = [build_adapter(cfg) for cfg in config["models"] if cfg["enabled"]]
# 2. 健康检查
healthy_adapters = [a for a in adapters if a.health_check()]
if not healthy_adapters:
return 503 # NAS 退避重试
# 3. 抽帧
frame_paths = extract_frames(video_path, task_id)
frame_timestamps = compute_timestamps(video_path, task_data["event_start_time"])
# 4. 并行调用所有健康模型（ThreadPoolExecutor）
from concurrent.futures import ThreadPoolExecutor, as_completed
model_outputs = {}
with ThreadPoolExecutor(max_workers=len(healthy_adapters)) as pool:
futures = {
pool.submit(a.analyze_frames, frame_paths, frame_timestamps, known_members): a.provider_name
for a in healthy_adapters
if not a.get_circuit_breaker().is_open() # 熔断的跳过
}
for fut in as_completed(futures, timeout=240):
provider = futures[fut]
try:
output = fut.result(timeout=a.get_timeout())
if output:
model_outputs[provider] = output
a.get_circuit_breaker().record_success()
else:
a.get_circuit_breaker().record_failure()
except Exception:
a.get_circuit_breaker().record_failure()
# 5. 至少一个模型成功才继续
if not model_outputs:
raise TaskFailedError('vlm_visual', 'All models failed')
# 6. 文本融合（多模型输出平等交叉验证）
fusion_result = run_vlm_fusion(model_outputs, task_data["known_members_context"])
# fusion_result.compute_provider = list(model_outputs.keys())
# fusion_result.frame_details[*].source_providers 由 VLM 在融合时填入
# 7. 回调
send_callback(task_data["webhook_url"], task_id, fusion_result)
```
**关键设计**：
- 模型清单由 `config.yaml` 的 `models` 数组动态决定，AI-Orchestrator 不硬编码任何模型
- 新增模型只改 config.yaml + 加适配器类，主流程不动
- 熔断器每模型独立，互不影响
- `model_outputs` 是 dict，键是 provider_name，值是输出文本，送入融合 Prompt
---
## 8. 部署说明
### 8.0 代码仓库（部署前必读）
- 仓库地址：`http://192.168.50.64:3000/ericwyuan/sentinel-home-ai`
- 仓库类型：Gitea（自建，仅内网访问）
- 克隆：`git clone http://192.168.50.64:3000/ericwyuan/sentinel-home-ai.git`
- 详细的 AI Agent 提交规范见 10.1.1 节
### 8.1 NAS 端
1. Python 3.10+，Flask，Gunicorn（1 worker），mysql-connector-python，PyYAML
2. 配置 MariaDB，执行 DDL（含 `family_members` 表）
3. 配置 `config/config.yaml`（Oracle 地址、token、NAS 端口等；成员不再走 YAML，由 `family_members` 表管理）
4. `gunicorn -w 1 -b 0.0.0.0:8000 app:app` 启动
### 8.2 Oracle 端
1. FFmpeg、OpenCV、Ollama
2. `ollama pull llava-phi3`
3. 安装 Python 依赖：`pip install google-generativeai openai`（openai 为 v1.1 预留）
4. 配置 `config/config.yaml`（含 models 数组，见 8.4）
5. 配置 Gemini API Key：在 `config/config.yaml` 的 `models` 中填入 `api_key`，或通过环境变量 `GEMINI_API_KEY` 注入
6. `gunicorn -w 1 -b 0.0.0.0:5000 app:app` 启动（或 Flask 内置线程池）
### 8.3 FAM-UI
1. Streamlit
2. 连接 MariaDB
3. `streamlit run app.py`
### 8.4 config.yaml 结构（多模型可配置）
Oracle 端 `config/config.yaml` 示例：
```yaml
# NAS 端回调地址
nas:
webhook_url: "http://100.x.x.10:8000/api/core/callback/event"
media_base_url: "http://100.x.x.10:8000/media"
media_token: "xxx"
# Oracle 端服务
server:
host: "0.0.0.0"
port: 5000
max_concurrent_tasks: 1
# 关键帧筛选参数
video:
candidate_frames: 30 # 粗抽候选帧数
min_key_frames: 5 # 最少关键帧
max_key_frames: 8 # 最多关键帧
mse_threshold: 500 # 帧差阈值
jpeg_quality: 80
max_long_edge: 1024
# 超时（秒）
timeout:
download: 60
vlm_visual: 240 # 单模型视觉分析超时
vlm_fusion: 120
callback: 30
overall: 600
# 模型清单（可扩展，新增模型只需在此数组加一项 + 实现适配器）
models:
- provider: "ollama"
enabled: true
model_name: "llava-phi3"
base_url: "http://localhost:11434"
timeout: 240
circuit_breaker:
enabled: false # 本地模型不启用熔断
threshold: 5
cooldown: 900
- provider: "gemini"
enabled: true
model_name: "gemini-1.5-flash"
api_key: "${GEMINI_API_KEY}" # 从环境变量读取，避免硬编码
timeout: 8
circuit_breaker:
enabled: true
threshold: 5
cooldown: 900
# v1.1 扩展示例（取消注释并填入 API Key 即启用）
# - provider: "openai"
# enabled: false
# model_name: "gpt-4o"
# api_key: "${OPENAI_API_KEY}"
# timeout: 30
# circuit_breaker:
# enabled: true
# threshold: 5
# cooldown: 900
# - provider: "nvidia"
# enabled: false
# model_name: "nvidia/llama-3.1-nemotron-70b-instruct"
# api_key: "${NVIDIA_API_KEY}"
# base_url: "https://integrate.api.nvidia.com/v1"
# timeout: 30
# circuit_breaker:
# enabled: true
# threshold: 5
# cooldown: 900
```
**配置说明**：
- `models` 是数组，每个元素是一个模型的完整配置
- `provider` 字段决定使用哪个适配器（OllamaAdapter / GeminiAdapter / ...）
- `enabled: false` 的模型被跳过，不调用
- `api_key` 支持 `${ENV_VAR}` 语法从环境变量读取，避免硬编码到配置文件
- 新增模型只需：实现适配器类 + 在此数组加一项，主流程不动
### 8.3 FAM-UI
1. Streamlit
2. 连接 MariaDB
3. `streamlit run app.py`
---
## 9. 前置风险（必须在阶段一验证）
### 9.1 llava-phi3 在 Oracle 2C12G 无 GPU 上的可行性
Oracle 免费 2C12G 实例（Ampere A1，ARM）无 GPU，走 CPU 推理。llava-phi3（基于 Phi-2，约 2.7B 参数 + CLIP 视觉编码器）即使 4-bit 量化也需约 2-2.5GB 内存。单张 1024px 图像推理可能数十秒级。
**验证方法**：
1. `ollama pull llava-phi3`
2. 喂单张 1024px JPEG，问"描述画面"，记录耗时
3. 喂 5 张、10 张、30 张，记录耗时和是否报错
**判定标准**（关键帧筛选后 VLM 输入为 5-8 张，与视觉分析 240s 超时对齐）：
- 单张 ≤ 8 秒 → 可行，5-8 张预计 40-64s，远低于 240s 超时
- 单张 ≤ 30 秒 → 可接受，5-8 张预计 150-240s，刚好卡超时边界
- 单张 > 30 秒 → 不可行，5-8 张 > 240s，需减帧或换更小模型
- 多张图触上下文截断或报错 → 需调整关键帧数量上限（默认 8 张往下调）
**若不可行的备选方向**：
1. 换更小模型（如 Moondream 或 Qwen-VL 0.5B 级别）
2. 减少抽帧数量（30 → 10 → 5）
3. 加 swap（不推荐，性能更差）
4. 改用 Gemini 作为主链路（与首期"先跑通本地链路"目标冲突，需重新讨论）
---
## 10. 验收标准（首期版）
### 10.1 执行主体说明
- 🤖 **AI Agent 自动执行**：编码、脚本配置、单元/集成测试、Bug 修复迭代，可连续执行，不受人类工作时间限制
- 👤 **需人工介入**：账号开通、密钥提供、真实录像、硬件操作、最终效果确认
### 10.1.1 代码仓库与提交规范（AI Agent 必读）
**仓库地址**：
- `http://192.168.50.64:3000/ericwyuan/sentinel-home-ai`
- 仓库类型：Gitea（自建，仅内网访问）
**克隆方式**：
```bash
git clone http://192.168.50.64:3000/ericwyuan/sentinel-home-ai.git
```
**AI Agent 工作流程（强制）**：
1. **开工前**：在仓库根目录执行 `git pull --rebase`，确保本地与远端同步
2. **每完成一项验收标准子任务后**（即 10.2 中表格的每一行）：
- 🤖 必须执行 `git add` + `git commit` + `git push`
- commit message 格式：`[阶段X.Y子任务号] 子任务名称 - 完成内容简述`
- 例：`[2.1] Task-Scheduler - 实现 60s 轮询 + 持久化 known_files`
- 例：`[3.3] 文本融合调用 - 三层 JSON 容错 + validate_schema`
- 一项任务一个 commit，不批量合并多任务到单 commit
3. **遇到阻塞时**（如外网不可达、API 失败）：
- 先 commit 当前可工作的部分，commit message 标注 `[WIP]` 前缀
- 例：`[WIP][3.2] 视觉分析调用 - Prompt 注入时间戳，待真实视频测试`
- 不要等所有问题解决再提交
4. **修复 Bug 后**：单独 commit，message 格式 `fix(模块): 问题简述`
- 例：`fix(Event-Receiver): frame_details 逐条插入时 abstract_label 未 upsert`
5. **禁止**：
- ❌ 不 commit 直接继续下一项任务
- ❌ 一次 commit 包含多个子任务
- ❌ 使用 `git push --force`（除非明确授权）
- ❌ 跳过 hooks（`--no-verify`）
**commit message 语言**：中文为主，技术术语可保留英文
**示例（一天的工作流）**：
```
git pull --rebase
# 完成 2.1 Task-Scheduler
git add src/fam_core/scheduler.py
git commit -m "[2.1] Task-Scheduler - 60s 轮询 + known_files 持久化到 DB"
git push
# 完成 2.2 Event-Receiver
git add src/fam_core/event_receiver.py src/fam_core/db_layer.py
git commit -m "[2.2] Event-Receiver - frame_details 逐条插入 + abstract_label upsert"
git push
# 发现 Bug 修复
git add src/fam_core/event_receiver.py
git commit -m "fix(Event-Receiver): abstract_label 正则匹配漏了小写字母"
git push
```
**AI Agent 自检清单**（每完成一项任务前自问）：
- [ ] 这项任务对应 10.2 表格的哪一行？验收标准是否达到？
- [ ] 是否已 commit + push？
- [ ] commit message 是否符合格式？
- [ ] 是否在开始下一项前 `git pull --rebase`？
### 10.2 详细任务分解与验收标准
#### 阶段一：环境准备与基础设施
| 子任务 | 执行主体 | 验收标准 |
|-------|---------|---------|
| 1.1 Tailscale 组网 | 👤+🤖 | 两端可 ping 通，curl 可访问端口 |
| 1.2 MariaDB 部署 | 🤖 | 建表成功（含 `family_members` / `event_details` / `chat_history` 六张表），字段类型符合 Schema |
| 1.3 Oracle 基础环境 | 👤+🤖 | FFmpeg、Ollama 正常，`llava-phi3` 模型加载成功 |
| 1.4 **模型可行性压测** | 🤖 | **单张 1024px 图推理 ≤ 8 秒（关键帧 5-8 张，与视觉分析 240s 超时对齐，首期阻塞项）** |
#### 阶段二：FAM-Core 基础链路（NAS 端）
| 子任务 | 执行主体 | 验收标准 |
|-------|---------|---------|
| 2.1 Task-Scheduler | 🤖 | 新视频 60s 内被扫描，无重复插入；重启后 `known_files` 不丢失（持久化到 DB 或文件） |
| 2.2 Event-Receiver | 🤖 | 回调返回 200；`monitor_events` 插 1 条聚合记录；`frame_details` 数组逐条插入 `event_details`（条数无上限）；未命名 abstract_label 自动 upsert 到 `family_members` |
| 2.3 状态机流转 | 🤖 | 失败自动重试，超 3 次置为 FAILED；`failure_stage` 字段正确记录失败阶段 |
| 2.4 任务下发客户端 | 🤖 | 收到 202 后状态切换为 PROCESSING；payload 注入 `family_members` 表的已命名+未命名成员清单 |
| 2.5 Member-Manager | 🤖 | `GET /api/member/unnamed` 返回未命名人物列表；`POST /api/member/name` 命名后批量 UPDATE `event_details` 回溯历史，返回更新条数 |
#### 阶段三：FAM-Edge 本地推理链路（Oracle 端）
| 子任务 | 执行主体 | 验收标准 |
|-------|---------|---------|
| 3.1 Video-Preprocessor | 🤖 | 等距粗抽 30 张候选帧；OpenCV MSE 帧差分析筛 5-8 张关键帧（首末帧必选）；长边 ≤ 1024px，JPEG 质量 80 |
| 3.2 视觉分析调用 | 🤖 | 10 次测试无空输出、无崩溃；Prompt 注入每帧时间戳（Oracle 计算 = 视频开始时间 + 帧偏移）；输出按帧顺序逐段 |
| 3.3 文本融合调用 | 🤖 | 20 次测试 JSON 解析成功率 ≥ 90%（三层容错：直接解析 → markdown fence → 贪婪 brace 匹配）；`validate_schema` 通过；`action` 由 AI 自由生成，无枚举过滤；`is_attention_event` 由 AI 自行判断 |
| 3.4 成员标识提取 | 🤖 | 已命名成员用 `real_name`；未命名成员用 `abstract_label`（人物A/B/C...）；新人物按出现顺序赋予新标识；特征描述落 `family_members.feature_description` |
| 3.5 AI-Orchestrator 串联 | 🤖 | 端到端全自动完成（下载 → 抽帧 → VLM 视觉 → VLM 融合 → 回调 → 清理）；各阶段耗时打 INFO 日志（带 task_id） |
#### 阶段四：AI 对话与成员命名（NAS 端）
| 子任务 | 执行主体 | 验收标准 |
|-------|---------|---------|
| 4.1 Chat-Handler | 🤖 | `POST /api/chat/ask` 接收问题；查 `event_details` 拼上下文；调 Oracle Ollama 纯文本返回自然语言回答；写 `chat_history`；明细 > 50 条时按小时聚合 |
| 4.2 成员命名流程 | 👤+🤖 | FAM-UI 展示未命名人物列表 + 特征描述；用户输入真名 → 批量回溯更新 `event_details`；命名后后续视频分析直接用 real_name |
| 4.3 对话准确率验证 | 👤+🤖 | 问"汤圆今天干嘛了"，回答包含主要活动时段 + 关注事件提示；当天无数据时明确说"今天没有观察到汤圆" |
#### 阶段五：FAM-UI + 联调 + 验收
| 子任务 | 执行主体 | 验收标准 |
|-------|---------|---------|
| 5.1 Streamlit 基础页面 | 🤖 | 事件列表分页加载、按日期筛选可用 |
| 5.2 成员命名页 | 🤖 | 展示未命名人物 + 命名输入框；命名后刷新已命名列表 |
| 5.3 AI 对话页 | 🤖 | 输入框 + 调 `/api/chat/ask` + 展示回答；按 `queried_person` 预设快捷提问按钮 |
| 5.4 compute_provider 可视化 | 🤖 | 图表与数据库统计一致（首期阶段全为 `local_only`） |
| 5.5 真实素材端到端联调 | 👤+🤖 | 至少 3 个真实切片跑通，VLM 输出 frame_details 落库正确，AI 对话能回答当日活动，结果经人工确认 |
阶段四（原 v1.0 的 Gemini 增强）和阶段五的长稳测试（24-48h）推到 v1.1+。
---
文档结束
Reference in New Issue View Git Blame Copy Permalink