视频 Agent

一个基于 Whisper 语音识别 + 向量检索 + LLM 摘要的本地视频问答桌面工具。

导入一段视频，系统会自动转写字幕、切分文本块、生成向量索引；之后你可以用自然语言提问， 系统会判断你的意图（找时间点 / 要摘要 / 两者都要），检索相关片段并给出回答与对应的时间戳。 为了让 demo 更适合工程实现型文章演示，当前版本额外加入了轻量会话记忆：会记住最近一轮问题、回答和当前视频，用于处理“继续说”“展开刚才那段”这类追问。

纯 Python 实现，桌面壳使用 pywebview（本地窗口 + 本地 HTTP 服务），不依赖 Node.js / Electron，安装和运行都很轻量。

核心架构

Video → ASR(faster-whisper) → Chunk → Embedding(sentence-transformers) → Vector DB(Chroma)
                                                                              ↓
User Query → Intent 分类 → find_timestamp（检索 docs+时间段） → (需要时) summarize → 响应

目录结构

video-agent/
├── desktop_main.py        # 桌面应用入口：启动 uvicorn 后台线程 + pywebview 窗口
├── requirements.txt
├── config/
│   ├── config.yaml         # 默认配置（ASR/Embedding/向量库/LLM 等）
│   └── local_settings.json # 运行时生成，保存本地设置（模型配置/当前选择等），不提交到版本库
├── data/
│   ├── vector_db/          # Chroma 持久化目录（运行时生成）
│   └── videos.json         # 已处理视频的记录（运行时生成）
├── api/
│   └── server.py           # FastAPI 应用与路由
├── src/
│   ├── models.py            # 数据模型（Transcript/Chunk/TimestampResult/AgentResponse）
│   ├── config.py             # 配置加载 / 本地设置读写
│   ├── video_processor.py    # 视频转写 + 分块
│   ├── embeddings.py         # Embedding 模型封装
│   ├── vector_store.py       # 向量库（Chroma）封装，管理视频记录
│   ├── intent_classifier.py  # 意图分类（find_timestamp / summarize / both）
│   ├── summarizer.py         # LLM 摘要（可退化为抽取式摘要）
│   ├── llm_client.py         # OSCI(OpenAI 兼容) 模型调用封装
│   ├── llm_registry.py       # 模型实例配置/当前模型选择（不落盘明文密钥）
│   ├── secrets.py            # 密钥存取（系统 Keychain/凭据库）
│   ├── tools.py              # find_timestamp / summarize 工具
│   └── agent.py              # VideoAgent 编排（intent → 检索 → 摘要）
├── ui/
│   ├── index.html / app.js / style.css  # 原生 JS 单页应用前端
└── DESIGN.md

安装

需要 Python 3.9–3.12（不支持 3.13）。这是因为 sentence-transformers 依赖 PyTorch， 而 PyTorch 在 Intel Mac (x86_64) 上从未发布过 Python 3.13 的 wheel——如果用 3.13 装依赖， pip 会因为找不到匹配的 torch 版本而报一长串看似版本冲突的 ResolutionImpossible 错误 （并非真的版本冲突，换成 3.9–3.12 即可解决）。

用 python3 --version 确认当前版本；如果是 3.13，建议单独装一个 3.12 并用它建虚拟环境。

方式一：venv

brew install python@3.12   # 如果还没有 python3.12
python3.12 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

方式二：conda

conda create -n video-agent python=3.12 -y
conda activate video-agent
pip install --upgrade pip
pip install -r requirements.txt

运行

python desktop_main.py

程序会在后台线程启动 FastAPI 服务（监听 127.0.0.1:8765），并打开一个本地窗口加载 http://127.0.0.1:8765/。首次启动可能因为需要下载 Whisper / sentence-transformers 模型 而稍慢，请耐心等待。

首次使用

1. 打开「导入视频」标签页，点击「选择视频文件」（或手动粘贴本地视频绝对路径）， 点击「开始处理」。处理过程包括：语音转写 → 文本分块 → 生成向量并入库，可能需要几分钟。
2. 打开「视频库」标签页，可以看到已处理视频的列表，点击「选为当前视频」将其设为问答对象。
3. 打开「问答」标签页，输入问题（例如"这段视频什么时候讲到了 xxx？"或"总结一下这个视频"）， 系统会自动判断意图并返回回答与相关时间戳。
4. 如果继续输入“展开说说”“刚才那部分详细一点”等追问，系统会自动带入最近一轮上下文；也可以点击「清空记忆」重新开始一个演示会话。

关于合规模型与 Key（可选）

• 本项目的 LLM 接入统一采用 OSCI（OpenAI 兼容）标准接口，优先适配国内主流大模型服务的兼容端点。
• 在「设置」页可以新增/编辑/删除多个“模型实例”（base_url / model / temperature / timeout），并选择“当前模型”。切换后立即生效，无需重启。
• 密钥不会写入 config/local_settings.json：优先写入系统 Keychain/凭据库（macOS/Windows 等），若运行环境不支持则自动回退到本地加密文件存储（config/secret_store.json + config/secret_key.bin）。前端只展示掩码与“已配置/未配置”状态。
• 若未配置当前模型或 Key，摘要功能会自动降级为抽取式摘要（直接拼接最相关的片段文本），不影响「找时间点」与基础问答能力。

已适配（模板预置，均可编辑）

• DeepSeek（OSCI/OpenAI 兼容）
• 通义千问 Qwen（OSCI/OpenAI 兼容）
• 智谱 Zhipu（OSCI/OpenAI 兼容）
• Moonshot/Kimi（OSCI/OpenAI 兼容）
• MiniMax（OSCI/OpenAI 兼容）

模板仅用于快速填充字段结构，base_url / model 以厂商最新文档为准。

合规与数据安全说明

• 默认仅在本机处理视频与向量索引；后端服务仅监听 127.0.0.1:8765，不对外网暴露。
• LLM 摘要仅在你显式配置“模型实例”后才会触发外部请求；请求内容为检索到的文本片段与问题，不包含视频文件本体。
• 密钥优先使用系统 Keychain/凭据库保存，不可用时回退本地加密文件；config/local_settings.json 不保存明文密钥；前端仅展示掩码与已配置状态。
• 国内合规落地依赖你选择的模型服务与部署位置；建议优先使用国内厂商的合规 endpoint，并按企业/法规要求配置数据留存与审计策略。

常见问题入口

• No module named 'cryptography'：安装 requirements.txt 或单独安装 cryptography
• Disabling PyTorch because PyTorch >= 2.4 is required but found 2.2.2：将 transformers 保持在 <5
• 删除视频时出现 KeyError: 'data/vector_db'：当前代码已为 Chroma 初始化增加线程锁与删除容错
• 更多问题见 SECURITY_NOTES.md