Initial video AI analysis project
This commit is contained in:
yangyl
250
agent.md
Normal file
250
agent.md
Normal file
@@ -0,0 +1,250 @@
|
||||
# Video AI Analysis PoC Agent Instructions
|
||||
|
||||
本文件约束后续 AI 在 `/Users/yoilun/AI-train/video-ai-analysis-poc` 中的开发、审查、测试和文档维护行为。任何业务代码修改前必须先阅读并遵守本文件。
|
||||
|
||||
## Repository Snapshot
|
||||
|
||||
- 项目名称：`video-ai-analysis-poc`。
|
||||
- 项目目录：`/Users/yoilun/AI-train/video-ai-analysis-poc`。
|
||||
- 项目目标：实现本地视频文件夹离线批处理分析 PoC。
|
||||
- 外部模型/参考实现目录：`/Users/yoilun/AI-train/zhengxin-vlm-0413`。
|
||||
- 参考 VLM 模型：`/Users/yoilun/AI-train/zhengxin-vlm-0413/models/memai-zhengxin-v3-20260413`。
|
||||
- 测试环境：`ssh xiaozheng@192.168.5.100`，用户说明该环境已有模型。
|
||||
- 运行目标：Ubuntu 24，单机 NVIDIA RTX 3080 20GB，离线批处理优先吞吐而非低延迟。
|
||||
|
||||
## Hard Directory Boundary
|
||||
|
||||
`video-ai-analysis-poc` 是本次项目目录。后续代码、配置、计划、文档、测试和输出模板都必须放在这里。
|
||||
|
||||
`zhengxin-vlm-0413` 不是本次项目目录，只能作为：
|
||||
|
||||
- 已有模型目录。
|
||||
- 参考实现目录。
|
||||
- VLM API、prompt、输出解析、部署方式的参考。
|
||||
|
||||
默认禁止在 `zhengxin-vlm-0413` 中创建本项目文件或修改业务代码。特别禁止改动、移动、删除或复制：
|
||||
|
||||
- `zhengxin-vlm-0413/models/**`
|
||||
- `zhengxin-vlm-0413/service/config.yaml`
|
||||
- `zhengxin-vlm-0413/service/config.yaml-bk`
|
||||
- `zhengxin-vlm-0413/docker/.env`
|
||||
|
||||
如果后续确实需要从参考项目复制逻辑，必须复制到本项目目录内，并注明来源和差异。
|
||||
|
||||
## Repository Map
|
||||
|
||||
当前项目文件：
|
||||
|
||||
- `video_ai_analysis_system_plan.md`：前期系统实施方案。
|
||||
- `agent.md`：本文件，约束后续 AI 工作。
|
||||
- `task_plan.md`：本次 goal 的阶段计划。
|
||||
- `findings.md`：代码阅读、约束、关键发现。
|
||||
- `progress.md`：执行记录、测试结果、bug 循环。
|
||||
- `docs/project.md`：项目目标、架构、配置、运行方式和风险。
|
||||
- `memories.md`：主 agent 对用户要求和关键决策的长期记忆。
|
||||
|
||||
参考目录关键文件：
|
||||
|
||||
- `/Users/yoilun/AI-train/zhengxin-vlm-0413/service/rtsp_service.py`：实时 RTSP 服务入口。
|
||||
- `/Users/yoilun/AI-train/zhengxin-vlm-0413/service/config.yaml`：现有推理、摄像头、prompt、服务、YOLO 配置，包含敏感信息。
|
||||
- `/Users/yoilun/AI-train/zhengxin-vlm-0413/shared/vlm_client.py`：VLM 请求构建、OpenAI-compatible API 调用、Action 解析。
|
||||
- `/Users/yoilun/AI-train/zhengxin-vlm-0413/shared/frame_utils.py`：已有本地视频抽帧辅助函数，但不满足本次完整离线批处理需求。
|
||||
- `/Users/yoilun/AI-train/zhengxin-vlm-0413/docker/docker-compose.yml`：vLLM 与 RTSP 服务容器编排。
|
||||
|
||||
## Current Workflow Batch
|
||||
|
||||
```text
|
||||
[项目: /Users/yoilun/AI-train/video-ai-analysis-poc]
|
||||
[工作流批次: v1.0 本地视频批处理PoC]
|
||||
```
|
||||
|
||||
派发任何子 agent 时，任务首段必须包含：
|
||||
|
||||
```text
|
||||
[项目: /Users/yoilun/AI-train/video-ai-analysis-poc]
|
||||
[工作流批次: v1.0 本地视频批处理PoC]
|
||||
[阶段: 阶段 x <阶段名>]
|
||||
[角色: <角色名>]
|
||||
[子agent名称: <从指定名单中选择>]
|
||||
```
|
||||
|
||||
子 agent 名称必须从以下列表选择：
|
||||
|
||||
```text
|
||||
huzenan, jiangzhiyou, linjiayu, hujiarui, wangchiheng, niwenhao,
|
||||
caiziquan, yepeijun, lizheng, zhengchenda, chenruihao, yangyilun, donglele
|
||||
```
|
||||
|
||||
## Required Workflow
|
||||
|
||||
### 1. Agent Rules Before Code
|
||||
|
||||
在 `agent.md` 未确定前，不允许修改业务代码。
|
||||
|
||||
阶段 0 允许修改：
|
||||
|
||||
- `agent.md`
|
||||
- `task_plan.md`
|
||||
- `findings.md`
|
||||
- `progress.md`
|
||||
- `docs/project.md`
|
||||
- `memories.md`
|
||||
|
||||
### 2. File-Based Planning Is Mandatory
|
||||
|
||||
非简单任务必须维护：
|
||||
|
||||
- `task_plan.md`
|
||||
- `findings.md`
|
||||
- `progress.md`
|
||||
- `docs/project.md`
|
||||
- `memories.md`
|
||||
|
||||
每个阶段开始前，主 agent 必须读取这些文件，确认当前目标和下一步。每个阶段完成后，必须更新阶段状态、验证记录、关键文件和剩余风险。
|
||||
|
||||
### 3. Sub Agent Workflow
|
||||
|
||||
每个实现阶段至少使用：
|
||||
|
||||
- coding agent：只实现当前阶段，不处理未来阶段，不做无关重构。
|
||||
- testing/review agent：只测试、审查、复现问题和报告 bug，不直接修改代码。
|
||||
|
||||
如果 testing/review agent 发现 bug：
|
||||
|
||||
1. 主 agent 将 bug report 记录到 `progress.md`。
|
||||
2. 主 agent 将 bug report 转发给当前阶段 coding agent。
|
||||
3. coding agent 只修复报告中的问题。
|
||||
4. testing/review agent 复测。
|
||||
5. 同一问题最多 3 轮，仍失败则暂停并向用户报告。
|
||||
|
||||
### 4. TDD And Verification
|
||||
|
||||
新增功能或 bugfix 必须优先写测试或最小可复现验证，再写实现。无法自动化测试的 GPU/视频/环境行为，必须写清楚 smoke test 命令、输入样例和人工判定标准。
|
||||
|
||||
完成任何阶段前，必须有新鲜验证证据：
|
||||
|
||||
- 单元测试。
|
||||
- CLI smoke test。
|
||||
- FFmpeg 命令检查。
|
||||
- vLLM health check。
|
||||
- 输出 JSON schema/字段检查。
|
||||
|
||||
不能只根据代码阅读声称完成。
|
||||
|
||||
## Local Batch PoC Requirements
|
||||
|
||||
### 1. Input
|
||||
|
||||
本次 PoC 优先支持本地视频文件夹：
|
||||
|
||||
- 通过 CLI 参数或 config 选择输入目录。
|
||||
- 递归或非递归行为必须可配置。
|
||||
- 支持常见视频格式，例如 `.mp4`、`.mov`、`.mkv`、`.avi`、`.flv`、`.ts`、`.m4v`。
|
||||
- 不支持或损坏的视频要记录失败原因，不能阻塞整个文件夹。
|
||||
|
||||
### 2. Video Processing
|
||||
|
||||
- 必须优先使用 FFmpeg + NVDEC GPU 解码。
|
||||
- 默认 1 FPS 抽帧。
|
||||
- 默认 clip 长度 10 秒，允许配置 10-20 秒。
|
||||
- 禁止逐帧 LLM 推理，必须 clip 级推理。
|
||||
- Clip 输入帧数要小，默认 8-10 帧，避免 RTX 3080 20GB OOM。
|
||||
- 输出目录保存 manifest、抽帧中间结果、clip 结果和汇总 JSON。
|
||||
|
||||
### 3. Prompt Configuration
|
||||
|
||||
- prompt 必须从 config 读取，不能硬编码在业务逻辑中。
|
||||
- 支持 `prompt.system` 和 `prompt.user`。
|
||||
- Prompt 必须要求模型输出严格 JSON。
|
||||
- Prompt 必须要求输出画面时间字段；如果画面时间不可读，要保留 clip 的视频相对时间。
|
||||
|
||||
### 4. Timeline Output
|
||||
|
||||
输出结果必须包含监控画面的时间轴。至少包含：
|
||||
|
||||
- `video_id` 或视频文件路径。
|
||||
- `video_start_time`：如果文件或画面可识别则填写，否则为 `null`。
|
||||
- `clip_start_seconds`。
|
||||
- `clip_end_seconds`。
|
||||
- `clip_start_timecode`，格式如 `HH:MM:SS`。
|
||||
- `clip_end_timecode`，格式如 `HH:MM:SS`。
|
||||
- `frame_times`：clip 内参与推理帧的相对秒数或 timecode。
|
||||
- `screen_time` 或 `画面时间`：模型从监控画面 OCR 到的时间，无法读取则为空。
|
||||
- 事件级 `start_time` / `end_time` 或对应 clip 范围。
|
||||
|
||||
不能只输出 `datetime.now()` 这种服务处理时间。
|
||||
|
||||
### 5. Model Inference
|
||||
|
||||
- 优先兼容 OpenAI-compatible `/v1/chat/completions`。
|
||||
- 默认模型名：`memai-zhengxin-v3-20260413`。
|
||||
- 默认配置使用 `api_base_url: http://localhost:8679` 和 `chat_completions_path: /v1/chat/completions`，由代码拼接为完整请求 URL。
|
||||
- RTX 3080 20GB 上 batch 保守起步，先 batch size 1，再逐步尝试 2-4。
|
||||
- vLLM dtype 和显存参数要在测试环境验证；如 BF16 不稳定，优先 FP16。
|
||||
|
||||
## Security And Data Rules
|
||||
|
||||
- 不要在新文档、测试夹具或输出示例中复制真实 RTSP 密码、token、Webhook 密钥、Cookie。
|
||||
- 参考项目 `service/config.yaml` 包含真实内网 RTSP URL 和密码，阅读可以，传播要脱敏。
|
||||
- 本地视频、抽帧图片、模型输出可能包含门店画面，默认视为敏感数据。
|
||||
- 不要把视频帧、日志、输出样例批量复制到仓库外部。
|
||||
- 不要删除用户已有视频或模型文件。
|
||||
|
||||
## Implementation Rules
|
||||
|
||||
- 所有新增代码放在本项目目录内。
|
||||
- 不修改参考项目实时 RTSP 主链路。
|
||||
- 可参考 `shared/vlm_client.py` 的接口设计，但新实现应位于本项目。
|
||||
- 不引入不必要的分布式系统。
|
||||
- 不引入大型依赖解决小问题。
|
||||
- 保持配置、运行命令、文档一致。
|
||||
- 所有输出文件命名要稳定，支持断点续跑。
|
||||
- JSON 输出必须可被机器解析；模型 raw response 可以保留，但不能作为唯一结构化结果。
|
||||
|
||||
## Validation Matrix
|
||||
|
||||
阶段 0 文档/agent 规则：
|
||||
|
||||
- 检查文件存在：
|
||||
- `agent.md`
|
||||
- `task_plan.md`
|
||||
- `findings.md`
|
||||
- `progress.md`
|
||||
- `docs/project.md`
|
||||
- `memories.md`
|
||||
- 检查 `zhengxin-vlm-0413` 下没有本次误放的工作流文件。
|
||||
|
||||
本地批处理代码变更后：
|
||||
|
||||
- Python 语法检查：
|
||||
- `python3 -m py_compile <changed python files>`
|
||||
- 单元测试：
|
||||
- 如新增 tests，运行对应 `python3 -m unittest ...` 或 `pytest ...`
|
||||
- FFmpeg/NVDEC 检查：
|
||||
- `ffmpeg -hwaccels`
|
||||
- `ffmpeg -decoders | grep cuvid`
|
||||
- vLLM health check：
|
||||
- `curl http://localhost:8679/v1/models`
|
||||
- 最小视频 smoke test：
|
||||
- 使用一个短视频目录运行本地批处理入口。
|
||||
- 检查输出包含 clip 级时间轴和汇总 JSON。
|
||||
|
||||
测试环境验证：
|
||||
|
||||
- 通过 `ssh xiaozheng@192.168.5.100` 执行前，先确认路径、依赖和 GPU 状态。
|
||||
- 远端命令要尽量只读或写入明确输出目录。
|
||||
- 不要覆盖远端已有模型和配置。
|
||||
|
||||
## Definition Of Done
|
||||
|
||||
本次 PoC 完成必须满足：
|
||||
|
||||
1. 支持本地文件夹所有视频分析。
|
||||
2. 不依赖海康云眸云存储。
|
||||
3. 模型提示词可通过 config 调整。
|
||||
4. 输出包含视频、clip、事件的监控时间轴。
|
||||
5. 4B VLM 使用现有模型路径或测试环境已有模型。
|
||||
6. 断点续跑和失败记录有基本支持。
|
||||
7. 文档更新，包含运行命令、配置项和输出结构。
|
||||
8. 必要验证命令已运行并记录。
|
||||
9. 每个阶段的子 agent 审查结论记录在 `progress.md`。
|
||||
Reference in New Issue
Block a user