NarratoAI 完整实操指南：一段视频素材，三步出成片解说
【免费下载链接】NarratoAI利用 AI 大模型，一键解说并剪辑视频项目地址: https://gitcode.com/gh_mirrors/na/NarratoAI
你有没有过这样的经历：手里有一段 20 分钟的原片，想做成竖屏解说视频，结果光是对着素材写文案、卡时间点、配字幕就耗掉一个下午。NarratoAI 就是冲着这个痛点来的：一款基于 LLM 的开源 AI 视频解说工具，你上传视频、给一句主题，它自动完成文案撰写、画面匹配、配音、字幕烧录和成片导出，支持本地部署，也提供云端托管版。本文按"先跑起来，再调好参数"的顺序，带你从零上手到进阶。
🎬 先搞清它是什么：一条自动化解说流水线
可以把 NarratoAI 理解成一条"素材进、成片出"的流水线，中间四个环节全部由大模型驱动：
- 理解画面：按固定间隔从视频里抽关键帧，交给视觉模型描述每个镜头的内容；
- 写解说词：文本模型基于画面描述 + 你给的主题/剧情，逐段生成与时间点对齐的解说脚本；
- 配音与配乐：TTS 引擎把脚本读成语音，再叠加背景音乐（可选 AI 生成的配乐）；
- 剪辑合成：按脚本切割素材、拼接片段、烧录字幕，输出 MP4，还能导出剪映草稿。
整个过程在浏览器里完成，主界面由"视频脚本配置、视频设置、字幕设置、音频设置"等面板组成，界面见下图：
读完这一节你只需要记住一件事：它替你干的活是"看懂画面 → 写词 → 配音 → 剪辑"，你负责的是给方向、做审核。
⏱️ 5 分钟首跑：三种部署方式任选
硬件门槛不高：CPU 4 核、内存 8GB 起步即可，显卡非必须。系统要求 Windows 10/11 或 macOS 11.0 以上。当前版本为 0.8.7（见仓库根目录 project_version）。
方式一：Docker（推荐，macOS 尤其适合）
git clone https://gitcode.com/gh_mirrors/na/NarratoAI cd NarratoAI cp config.example.toml config.toml # 编辑 config.toml 填入你的 API 密钥 docker compose up -d # 浏览器打开 http://localhost:8501镜像基于 Python 3.12 多阶段构建，Dockerfile 里已装好 ffmpeg 等依赖，容器默认把 storage/、resource/、config.toml挂载到宿主机，产物和配置都不会丢在容器里。
方式二：本地源码运行（需要 Python 3.12+）
git clone https://gitcode.com/gh_mirrors/na/NarratoAI cd NarratoAI uv sync cp config.example.toml config.toml # 编辑 config.toml 填入你的 API 密钥 uv run streamlit run webui.py --server.maxUploadSize=2048没有uv也可以用pip install -r requirements.txt装依赖，--server.maxUploadSize=2048单位是 MB，保证大视频文件能传上去。
方式三：官方整合包（不想碰命令行）
官网提供 Windows x64 与 macOS arm64 的整合包，完整解压后先双击update-xxx更新，再双击start-xxx启动，访问http://127.0.0.1:8501即可。
跑通后的验收标准很简单：能打开 8501 端口的界面、填进 API Key 后"保存配置"不报错。到这一步，你已经有了一个可用的本地 AI 解说工厂。
🧠 接上 AI 大脑：核心只有两组模型
所有模型调用都走 OpenAI 兼容协议（/v1/chat/completions），所以一份配置可以接入 OpenAI、DeepSeek、Gemini 兼容网关、Qwen、SiliconFlow 等。config.toml 里你至少需要填两组：
[app] # 视觉模型：负责"看懂"视频画面 vision_llm_provider = "openai" vision_openai_model_name = "Qwen/Qwen3.5-122B-A10B" vision_openai_api_key = "你的API密钥" vision_openai_base_url = "https://api.siliconflow.cn/v1" # 文本模型：负责剧情分析、文案生成、脚本匹配 text_llm_provider = "openai" text_openai_model_name = "Pro/zai-org/GLM-5" text_openai_api_key = "你的API密钥" text_openai_base_url = "https://api.siliconflow.cn/v1"选型上可以照抄社区常用的组合：
| 用途 | 推荐模型 | 特点 |
|---|---|---|
| 视觉（抽帧理解） | gemini/gemini-2.0-flash-lite | 速度快、成本低 |
| 视觉（高精度） | gemini/gemini-1.5-pro、gpt-4o | 描述更细致 |
| 视觉（开源） | qwen/qwen2.5-vl-32b-instruct | 国内网关即可用 |
| 文本（文案） | deepseek/deepseek-chat | 性价比高 |
| 文本（推理） | deepseek/deepseek-reasoner | 长视频剧情梳理 |
两个可选增强，按需开启：
- TwelveLabs Pegasus：把
vision_llm_provider改成"twelvelabs"，它原生理解整段画面而非零散关键帧，更适合挑高光、把握镜头内动作与时序； - Tavily 联网搜索：填
tavily_api_key后，短剧解说前会自动检索该剧的公开剧情与人物信息，长视频配剧情描述效果更好。
另外注意两组超时默认值：视觉 120 秒、文本 180 秒，llm_max_retries = 3。文案生成这类复杂任务本来就慢，超时被打断时先检查网络和 base_url 是否填对。
📽️ 全流程拆解：一次"上传到成片"都发生了什么
上传视频后，四个环节依次执行，每一环你都能插手。
第一步：抽帧 + 画面理解。核心逻辑在 app/services/documentary/frame_analysis_service.py，analyze_video会按frame_interval_input（默认 3 秒）抽帧，再按vision_batch_size（默认 10 帧/批）并发调用视觉模型，得到"时间戳 → 画面描述"的清单。
第二步：文案生成与人工审核。文本模型把画面描述 + 你的主题转成逐段解说词。审核界面会左右对照展示每个片段的视频、画面描述和解说文案，觉得某段不对就点 Rebuild 单独重生成，全部满意后再点 Generate Video：
这是整个流程里最值得花时间的环节——审核 5 分钟，省掉返工半小时。
第三步：配音与配乐。在"音频设置"里选 TTS 引擎和音色（界面支持试听），背景音乐可以是资源库随机、自定义上传，或者启用 Sonilo 让 AI 按画面节奏生成配乐（成片上限 6 分钟，失败自动回退随机 BGM）。
第四步：剪辑与合成。app/services/video.py 的generate_video_v3负责按脚本切素材、拼接（支持随机/顺序两种拼接模式）、对齐配音长度、烧字幕，输出 MP4；如果你想在专业软件里二次编辑，可以直接导出剪映草稿（app/services/jianying_draft_builder.py）。
🧩 三个容易被忽略的能力
多引擎 TTS，含本地语音克隆。[ui]段的tts_engine可选edge_tts、qwen3_tts、tencent_tts、doubaotts、azure_speech等云端引擎，也支持indextts、indextts2、omnivoice、voxcpm等本地部署的克隆引擎——上传一段参考音频，就能用"你自己的声音"做解说。Apple Silicon 用户可直接用 IndexTTS-1.5 的 MLX 部署包。
字幕不只是烧上去。字幕链路包含四件事：Fun-ASR 一键转录（[fun_asr]段，支持本地 Pack 或百炼在线）、AI 辅助纠错（app/services/subtitle_corrector.py 把 SRT 拆块后批量让 LLM 修订再渲染回文件）、多语言翻译、样式定制。如果你拿到的素材自带硬字幕，可以开启subtitle_mask_enabled = true，烧录前先用模糊遮罩盖掉原字幕区域。
安全区预览。横竖屏的字幕位置以"距画面顶部百分比"表示（横屏默认 85%、竖屏 82%），设置里有实时安全区预览，参考仓库自带示意图：
🔧 参数调优与避坑
进阶玩家最常动的几个开关，都在 config.example.toml 的[frames]段和字幕设置里：
| 参数 | 默认值 | 什么时候调 |
|---|---|---|
frame_interval_input | 3 秒 | 画面变化快就调小（2s），素材长且慢镜头多就调大（5s），直接影响视觉 API 调用量 |
vision_batch_size | 10 帧 | 显存/网关压力大就调小 |
vision_max_concurrency | 2 | 网关限流就调小，富余则调大加速 |
text_openai_fast_model_name | 空 | 给字幕翻译/校准单独指一个便宜快的模型，留空则复用主力模型 |
subtitle_mask_* | 关闭 | 素材带硬字幕时开启，按横屏/竖屏分别设百分比与模糊半径 |
hide_config | true | 设为 false 可在 WebUI 里直接改配置，省去重启 |
几条高频坑位：
- 上传失败：多半是没加
--server.maxUploadSize=2048，Streamlit 默认上传上限很小； - Docker 里找不到产物：成片在宿主机的 storage/ 目录（compose 已挂载）；
- API 连接失败：按"key 是否正确 → base_url 是否带
/v1→ 是否要开[proxy]代理"的顺序排查； - 生成的解说质量一般：先补一段剧情描述（长视频效果提升明显），再考虑换更强的文本模型或调高
vision_batch_size。
🧭 看懂架构，然后开始用
想改点什么的，源码位置大致是：
- 业务核心在 app/services/：
documentary/（画面分析）、llm/（多模型接入与 provider 管理）、prompts/（分场景提示词模板）； - 界面逻辑在 webui/：六个
components/面板对应界面的六个配置区； - 依赖与版本管理用
pyproject.toml+uv.lock，配置以 TOML 为单一事实来源。
项目更新比较活跃：近期版本陆续加入了 Fun-ASR 一键转录、纪录片逐帧分析链路重构、Sonilo AI 配乐、IndexTTS-1.5/2 语音克隆支持等；路线图上还有主角人脸匹配、口播文案自动匹配素材等方向。遇到问题可以提 issue 或 PR，也可以进官方开源社群交流。
现在就可以动手了：5 分钟把服务跑起来，填上两组模型配置，上传你手里最久没处理的那段素材——先出一版 3 分钟的竖屏解说，再按上面"避坑"一节微调，就是你对这个工具最直接的评估。
【免费下载链接】NarratoAI利用 AI 大模型，一键解说并剪辑视频项目地址: https://gitcode.com/gh_mirrors/na/NarratoAI
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
