Graphify 音视频转写实战指南用 Whisper 将视频语料接入知识图谱构建流程【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify本文讲解 Graphify 知识图谱流水线中的 Step 2.5 —— 当detect阶段检测到视频或音频文件时如何先把它们转写成文本再作为文档接入后续的图谱抽取。你将掌握GRAPHIFY_WHISPER_PROMPT/GRAPHIFY_WHISPER_MODEL两个环境变量的正确用法、基于 god node 标签生成领域提示词的策略以及底层graphify.transcribe模块的缓存、URL 下载与失败容错机制从而让会议录像、课程讲座、播客等非文本语料真正成为可查询知识图谱的一部分。一、Step 2.5 在整个流水线中的位置Graphify 的核心工作流是把任意语料代码、文档、SQL Schema、配置文件乃至 PDF 与视频转化为可查询的知识图谱。在基于 agent 的 skill 流程中步骤编排大致是Step 1 确保 graphify 已安装写入 graphify-out/.graphify_python Step 2 运行 detect 扫描语料结果写入 graphify-out/.graphify_detect.json Step 2.5 仅当 detect 返回了 video 文件时才执行转写音视频为文本 ← 本文主题 Step 3 结构抽取AST免费、确定性 语义抽取可选 LLM → 生成带 god nodes、社区结构与跨界连接的 graph.jsontranscribereference 文档即本主题的原始依据仓库中对应多平台复本见 opencode 版本其在主 skill 文件中的入口见 skill-opencode.md 的 Step 2.5的开头就明确了一条装载纪律Load this only whendetectreported one or morevideofiles. A corpus with no video never reads this.也就是说这个 reference 是**按需装载conditional load**的detect 返回 0 个 video 文件时这一步整体跳过直接进入 Step 3只有语料中真实存在音视频时才激活。这避免了纯代码仓库在每次运行中做无意义的模型加载。二、为什么视频必须转写detect 如何识别 video 文件视频与音频无法被 AST 或文档解析器直接读取因此必须先转成文本再把转写稿当作 doc 文件喂给 Step 3。这一步的触发信号来自 detect 阶段。在源码层detect 把文件分类为枚举FileType其中显式包含VIDEO video见 graphify/detect.py并在classify_file中根据扩展名落入该类别见 graphify/detect.py。识别出的扩展名集合与转写模块共用同一套约定graphify/transcribe.pyVIDEO_EXTENSIONS { .mp4, .mov, .webm, .mkv, .avi, .m4v, # 视频容器 .mp3, .wav, .m4a, .ogg, # 纯音频 }注意集合中同时包含纯音频扩展名mp3/wav/m4a/ogg所以文档措辞中的 video 实际涵盖音视频两类媒体。detect 的结果会以 JSON 形式落到graphify-out/.graphify_detect.json其中顶层files字段下带一个video列表这是后续 Step 2.5 读取转写对象清单的唯一来源。另外可以留意detect 阶段会在摘要里展示类似video: N files (.mp4 .mp3 ...)的分类统计agent 主流程的展示格式见 graphify/skill-agents.md这个 N 就是判断是否需要装载本文档的依据。三、核心策略用 god node 标签自写领域提示词免去额外 API 调用转写质量直接取决于 Whisper 收到的 initial prompt。reference 文档定义了一个零额外成本的策略从graphify-out/.graphify_detect.json或上一轮运行残留的 analysis 文件读出 god nodes宿主 agent 本身就是语言模型基于这些标签自己手写一句话领域提示domain hint把它作为 Whisper 的 initial prompt 传入——不需要任何额外的一次 API 调用。god nodes 是语料中连接度最高、最能代表核心抽象的真实实体。在源码里它们由 graphify/analyze.py 的god_nodes()计算先按图度数degree降序排列再剔除 file 级枢纽节点、概念节点、JSON key 噪声节点以及内置噪声标签因为它们只是机械累积 import/contains 边的文件外壳不构成有意义的架构抽象。文档给出了两个直观示例帮助 agent 快速把握标签 → 一句话提示的转换手感Labels:transformer, attention, encoder, decoder→Machine learning research on transformer architectures and attention mechanisms. Use proper punctuation and paragraph breaks.Labels:kubernetes, deployment, pod, helm→DevOps discussion about Kubernetes deployments and Helm charts. Use proper punctuation and paragraph breaks.一个重要的例外如果语料只含视频文件没有任何其他 docs/code那么 god nodes 无从谈起此时应使用通用兜底提示词Use proper punctuation and paragraph breaks.这个兜底字符串在源码里被定义为模块级常量_FALLBACK_PROMPTgraphify/transcribe.py它同时是程序化路径无 god nodes、无环境变量覆盖下的最终 fallback。四、Step 1撰写并导出领域提示词动手转写前先完成提示词撰写并把两个环境变量用export导出export GRAPHIFY_WHISPER_MODELbase # 或用户通过 --whisper-model 传入的模型名必须 export export GRAPHIFY_WHISPER_PROMPT你在 Step 1 撰写的那句领域提示这里有两个易踩的坑reference 文档都用粗体做了强调变量名必须精确为GRAPHIFY_WHISPER_PROMPT与GRAPHIFY_WHISPER_MODEL——这是底层 Python 转写模块唯一读取的名字源码见 graphify/transcribe.py 的_model_name()与build_whisper_prompt()中的os.environ.get(GRAPHIFY_WHISPER_PROMPT)必须export不能只是赋值——因为下一段命令会启动一个独立的 Python 子进程只有导出到进程环境里子进程才能通过os.environ读到它们。五、Step 2执行转写命令逐段解析reference 文档给出的核心命令如下这也是 agent 实际执行的模式$(cat graphify-out/.graphify_python) -c import json, os, sys from pathlib import Path from graphify.transcribe import transcribe_all detect json.loads(Path(graphify-out/.graphify_detect.json).read_text(encodingutf-8)) video_files detect.get(files, {}).get(video, []) prompt os.environ.get(GRAPHIFY_WHISPER_PROMPT, Use proper punctuation and paragraph breaks.) transcript_paths transcribe_all(video_files, initial_promptprompt) Path(graphify-out/.graphify_transcripts.json).write_text(json.dumps(transcript_paths, ensure_asciiFalse), encodingutf-8) print(fTranscribed {len(transcript_paths)} file(s), filesys.stderr) 这段脚本里的每个细节都有明确目的片段作用$(cat graphify-out/.graphify_python)读取 Step 1 探测出的正确 Python 解释器路径兼容 uv tool / pipx / venv / 系统安装保证 import 到的是 skill 自己装的 graphify该约定在 graphify/skill-agents.md 有完整说明detect.get(files, {}).get(video, [])从.graphify_detect.json取出上一步分类出的全部视频/音频文件清单os.environ.get(GRAPHIFY_WHISPER_PROMPT, ...)读取第四步导出的领域提示缺省时用通用兜底提示transcribe_all(video_files, initial_promptprompt)核心调用遍历转写全部文件逐文件失败不中断见第七节源码细节Path(graphify-out/.graphify_transcripts.json).write_text(...)必须用 Python 写 JSON而不是 shell 的重定向关于最后一点reference 文档与代码注释特别标注了 issue #1392 的教训transcribe_all内部的 Whisper/faster-whisper 会把进度信息打到 stdout如果此时用 shell重定向这些进度文本会混入 JSON 文件把它写坏。因此结果文件由 Python 进程内直接write_text而进度统计则显式走print(..., filesys.stderr)绕开 stdout。这是一个值得在同类脚本中复用的健壮性惯例。六、转写完成后做什么脚本执行完毕后agent 需要继续把转写产物接入主流程从graphify-out/.graphify_transcripts.json读出所有转写稿路径在 Step 3B 派发语义子代理之前把它们追加进 docs 列表打印一条统计信息向用户汇报格式固定为Transcribed N video file(s) - treating as docs若某个文件转写失败打印 warning 并继续处理剩余文件而不是整体中断。换句话说转写稿从此与 Markdown、文本等普通文档地位等同会进入后续语义抽取、社区发现与知识图谱。七、源码级原理transcribe 模块内部实现reference 文档描述的行为其具体实现集中在 graphify/transcribe.py理解它能帮你排查问题、预估行为1) 依赖与运行时Whisper 后端使用faster-whisperWhisperModel未安装时会抛出明确提示要求pip install graphifyy[video]见 graphify/transcribe.py模型默认base_DEFAULT_MODEL通过GRAPHIFY_WHISPER_MODEL环境变量覆盖见 graphify/transcribe.py 与 L19-L20模型加载参数为devicecpu, compute_typeint8转写参数为beam_size5并透传initial_prompt见 graphify/transcribe.py——即当前实现默认在 CPU 上以 int8 量化运行无需 GPU。2) 缓存与重跑语义转写稿固定输出为graphify-out/transcripts/文件名.txt目录名来自 graphify/transcribe.py 的_out_path(transcripts)若同名.txt已存在则直接返回缓存不重复调用模型graphify/transcribe.py传入forceTrue才强制重转graphify/transcribe.py 的签名说明。这保证了对同一语料的增量重跑是廉价的。3) URL 输入支持transcribe()接受本地路径也接受http(s):///www.前缀的 URL判断见 graphify/transcribe.pyURL 会先经yt-dlp下载纯音频用 URL 的 SHA-1 前 12 位做稳定文件名、支持缓存复用见 graphify/transcribe.py且下载前会调用 graphify/security.py 的validate_url拦截私网 IP 与危险 scheme。4) 提示词的完整优先级build_whisper_prompt()graphify/transcribe.py实现了三层回退环境变量GRAPHIFY_WHISPER_PROMPT优先 → 否则由最多前 10 个 god node 的 label 拼出Technical discussion about 前5个主题. Use proper punctuation and paragraph breaks.→ god nodes 为空或全无 label 时用_FALLBACK_PROMPT。reference 文档中 agent 手工撰写提示的策略正是站在第一优先级之上env 覆盖层。5) 批量失败容错transcribe_all()graphify/transcribe.py逐文件 try/except单个文件转写抛异常只打印warning: could not transcribe file并跳过其余文件照常完成空输入返回空列表。这正是第六节失败继续约定的实现来源。八、测试验证这些行为有据可查上述关键行为均有单元测试覆盖位于 tests/test_transcribe.py可作为你判断该特性是否为稳定契约的证据扩展名集合.mp4 in VIDEO_EXTENSIONS、.py not in VIDEO_EXTENSIONStests/test_transcribe.py提示词空 god nodes 回退、环境变量覆盖优先、无 label 节点安全跳过tests/test_transcribe.py缓存命中已存在的转写稿直接返回、forceTrue强制重转并覆盖旧稿tests/test_transcribe.py依赖缺失未安装 faster-whisper 时抛ImportErrortests/test_transcribe.py批量容错transcribe_all([])返回空列表、单文件失败被跳过且不中断其余文件tests/test_transcribe.py。九、模型选择与适用范围小结模型默认base。只有当用户显式传入--whisper-model name时才切换为其它 Whisper 模型尺寸如small、medium且切换方式是export GRAPHIFY_WHISPER_MODELname后再运行转写命令——只赋值不导出同样无效。切换更大模型会提升转写准确率但相应延长 CPU 转写时间。本步骤的运行前提语料中存在可识别的音视频文件扩展名落在 VIDEO_EXTENSIONS 内、graphify 环境安装了graphifyy[video]可选依赖、且能访问graphify-out/下的中间产物。若语料中没有任何音视频本步骤与整个 reference 文档都不会被装载。结果产物graphify-out/.graphify_transcripts.json转写稿路径清单与graphify-out/transcripts/*.txt转写稿正文后者在 Step 3 中作为普通 doc 参与抽取与建图。至此一个包含演讲录像、技术播客或产品演示的语料就能与代码、文档一样被纳入 Graphify 的知识图谱——而这一切只依赖 Whisper 的一次本地转写与一句由 god node 标签引导的领域提示不引入任何额外的模型 API 调用。【免费下载链接】graphifyTurn any codebase, with its docs, SQL schemas, configs, and PDFs, into a queryable knowledge graph. A /graphify skill for Claude Code, Cursor, Codex, and Gemini CLI: local deterministic AST parsing, every edge explained, no vector store.项目地址: https://gitcode.com/GitHub_Trending/graph/graphify创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考