开源实战:从零实现「视频→知识库」全流程(下载/转写/向量检索/时间戳问答)

本文你能学到什么
- yt-dlp 处理 B 站视频的工业级用法(格式回退、字幕探测、断点续传)
- ASR 三级降级架构:平台字幕 → 云端 SenseVoice → 本地 Whisper,链路永不断
- pgvector「向量 + 全文」混合检索的表设计与 SQL 细节
- 答案强制带时间戳引用的 RAG prompt 设计(含「无据不编造」的兜底)
- MCP Server 开发:让 Claude Code / Codex / OpenClaw 直接调用你的服务
- 不依赖 Docker 的 Windows 离线安装器方案(Inno Setup + 嵌入式 PostgreSQL)
项目全程开源,今天把这些实战经验一次性拆给你。
项目简介
知映 zhiying:丢一个视频链接(B站 / YouTube / 本地文件),自动完成 下载 → 语音转写 → 画面识别 → 多模态文案对齐 → 结构化摘要 → 向量入库,之后直接对知识库提问,答案附带时间戳的引用卡片——点击跳回原视频对应秒数。
(提问 → 答案 + 时间戳引用)
项目地址:zhiying-platform/zhiying(觉得有用点个 Star ⭐)整体架构
Web / Agent(MCP) / CLI
↓ REST API (FastAPI :8600)
download(yt-dlp) → transcribe(字幕→SenseVoice→Whisper)
→ frames(PySceneDetect) → vlm(LongCat-2.5 适配器)
→ assemble(A1 双形态) → summarize(A3) → kb(pgvector 入库)
↓
检索(向量+全文混合) → RAG 问答(引用深链)
这条流水线实际操作起来是这样的——粘贴链接提交任务,四个阶段自动推进:

核心实现拆解
1. 多源下载层(yt-dlp)
- 格式回退链:B 站 4K/1080P 需大会员,无 cookie 时自动降级到可拉取的最高画质
- 字幕探测:B 站字幕必须登录 cookie 才能拉取,探测失败自动进入下一级转写
- 断点续传 + 片段级重跑:失败只重跑失败阶段,产物全缓存
2. ASR 三级降级(保底可用)
平台字幕(免费)→ SenseVoiceSmall(云端,实测 118s 视频 8s 音频计费)
→ 本地 Whisper(离线兜底)
每级失败自动降级,transcribe_origin 字段记录实际来源——排查质量问题时先看这个字段。
3. pgvector 混合检索(向量 + 全文)
纯向量检索对专有名词容易飘,方案是双路召回合并排序:
- 向量路:bge-m3 embedding(冻结 1024 维,维度写进 DDL 契约,换模型需迁移表结构)
- 全文路:jieba 应用侧分词 → tsvector 列 + GIN 索引(migration 002)
- 两路结果按分数归一化合并,专有名词靠全文路兜住,语义问题靠向量路兜住
4. 时间戳溯源的 RAG 设计
segments 表从第一天就带 start_ts / end_ts,这是整个产品的灵魂:
- 检索命中后引用卡片直接生成深链 URL(
?t=秒数),B 站前端原生支持跳转 - 答案 prompt 强制模型引用检索片段原文,无据可答时明确说「知识库中无依据」而不是编造
5. MCP Server:Agent 原生接入
暴露 5 个工具(入库/检索/问答/文档/状态):
claude mcp add zhiying -- <仓库路径>\scripts\zhiying-mcp.cmd
接入后对话里说「帮我把这个视频入库:<链接>」,Agent 自己调工具。
踩坑实录(重点避坑)
1. Windows 后台进程整树回收:Start-Process 拉起的常驻服务随父会话退出被杀,app.log 无 shutdown 记录但进程消失。解法:WMI Win32_Process.Create 启动才跨会话存活;嵌入式 PG 的 pg_ctl start 必须 DEVNULL 重定向(capture_output 等 EOF 会等到超时)。
2. 全新安装入库必败:schema_v1 建表缺后来加的 content_hash 列(migration 只写了文件没接进 init 流程),fresh install 知识库入库 100% 报 column does not exist。教训:init 必须连 migrations 目录一起执行 + verify 检查关键列,只跑 base schema 的 init 是半个 init。
3. 问答缓存投毒:入库前问过的问题会把「无依据」缓存进内存(key=问题文本),入库后同题命中缓存依旧「无依据」。缓存 key 应含知识库水位,或提供主动失效手段。
快速开始
普通用户:Releases 下载 zhiying-setup.exe(144MB),双击安装即用。嵌入式 PostgreSQL 随包,零环境依赖,完全离线。
开发者:
git clone https://github.com/zhiying-platform/zhiying
git clone https://github.com/zhiying-platform/zhiying-web
# cp .env.example .env(填 2 个模型 Key)→ docker compose up -d
系列预告
下一篇拆 pgvector 混合检索的 SQL 细节:两路召回的分数归一化、tsvector 与 jieba 的配合、维度冻结契约的迁移策略——关注不迷路。
开源信息
- 协议 Apache-2.0(NOTICE 要求衍生作品注明基于知映二次开发)
- 后端:zhiying-platform/zhiying — Python / FastAPI / PostgreSQL + pgvector
- 前端:zhiying-platform/zhiying-web — Vue 3 / Vite / Naive UI
觉得有用点个 Star ⭐;问题直接开 Issue。
