VideoLingo：AI 视频字幕翻译与多语言配音本地化流水线｜部署与使用全指南

项目仓库： https://github.com/Huanshere/VideoLingo

开源协议：Apache License 2.0 · 运行语言：Python（脚本标记 requires-python = "==3.12.*"；界面基于 Streamlit，本地接口基于 FastAPI） · 交付形态：本地 / 云 GPU 上运行的 Streamlit 网页流水线与本地 HTTP API · 默认端口：Streamlit 8501，本地 HTTP API 8000 · 官方文档：开始使用（中文）、HTTP API 指南、Docker 说明

非官方声明：本文是基于官方 README、docs/pages/docs/start.zh-CN.md、docs/api.md、docs/pages/docs/docker.en-US.md、docs/pages/docs/whisperx-manual.en-US.md、config.yaml、requirements.txt、Dockerfile 与 start.py 整理的部署使用指南，不代表项目官方立场。VideoLingo 名称归项目权利人所有；Qwen3-ASR、MLX Audio、WhisperX、yt-dlp、BELLE、Edge TTS、OpenAI TTS、Fish Audio、SiliconFlow、GPT-SoVITS、F5-TTS、ElevenLabs、MAI-Transcribe-2 等名称与服务归各自权利人所有，其许可证、服务条款与计费规则由对应发布方规定。本文不构成对翻译质量、配音效果、商用授权或第三方 API 安全的任何担保。

1 项目简介

VideoLingo 是 Huanshere 维护的开源视频本地化流水线，README 自述定位为 “combines speech recognition, subtitle translation, segmentation and dubbing in a Streamlit interface. It produces subtitle files and optionally subtitled or dubbed videos”：用户在网页侧栏配置大模型 API、识别语言、目标语言与 TTS 方案后，流水线依次完成视频输入、词级语音识别与对齐、NLP/AI 分句、术语提取、多步翻译、长字幕切割对齐、配音时长校准与语音合成，最终输出字幕文件以及（可选）烧录字幕的双语视频、配音视频。

项目同时提供与 Streamlit 共用同一套处理流程的本地 HTTP API，供脚本与 AI Agent 串行批处理；旧版 Excel 批处理模式已由该本地 API 替代。README 明确 “Translation quality depends on the source audio, language and chosen models”，流水线只负责流程串联，翻译与识别质量由所选模型、源音频质量与语言组合共同决定。

1.1 核心信息一览

1.2 适用场景

• 把外语教学视频、技术教程、播客剪辑、影视片段等素材翻译为目标语言字幕：先完成词级转写与时间轴对齐，再做术语统一、多步翻译与字幕重排，产出 .srt 字幕文件。
• 在字幕翻译基础上完成视频配音：选择 Edge TTS、OpenAI TTS、Fish Audio、SiliconFlow FishTTS/CosyVoice2、GPT-SoVITS、F5-TTS 等后端，按字幕时长做语速校准与音频合并，生成配音版视频。
• 对 YouTube 视频通过 yt-dlp 直接下载（可配置分辨率与 cookies），或上传本地 MP4/MOV/AVI/MKV/FLV/WMV/WEBM 与 WAV/MP3/FLAC/M4A 音频文件进入流水线。
• 为批量脚本与 AI Agent 提供本地 HTTP API：POST /input 提交素材、POST /run 分阶段处理、GET /status 轮询进度、GET /files/<name> 取结果、POST /archive 归档，串行完成一批视频。
• 借助术语表人工校对：开启 pause_before_translate 在术语提取后暂停、编辑 output/log/terminology.json；开启 pause_after_translate 在翻译后暂停、编辑 output/log/translation_results.xlsx 后继续。
• 在 Apple Silicon Mac 上用 MLX 本地识别，在 Windows/Linux NVIDIA 主机上用 CUDA 本地识别；无 NVIDIA 显卡时可走 CPU 或云端识别服务，但速度明显受限。

1.3 能力边界（官方口径）

README “Current Limitations” 小节列出五条官方边界，使用前应逐条知悉：

1. 识别与对齐受噪声和语言模型影响：背景噪声与特定语言的对齐模型会影响识别结果与词级时间戳；人声分离可能有帮助。数字与符号可能缺少可靠词级时间，产出字幕需要人工检查。
2. LLM 输出必须满足流水线 JSON 结构：失败时查看 output/gpt_log/error.json；已成功的响应缓存与已完成输出可在重试时复用；仅更换模型不会让每个已完成阶段重新生成；排障第一步不应是删除全部 output/。
3. 配音质量与时长取决于翻译、TTS 服务与语速：调速不保证自然语气，也不保证完美口型同步。
4. 本地识别按音频片段使用一种主识别/对齐语言：混说语言无法保证每种语言都保留准确文字与时间。
5. 配音流水线不会自动为每个说话人分配独立音色。

其他官方口径边界：

• 平台支持 Windows、macOS（Apple Silicon / Intel）与 Linux；Apple Silicon 自动使用 MLX，Intel Mac 使用 CPU 识别，默认 Intel Mac 配音只保留新生成语音、不混入原始背景音。
• 输入语言支持 README 列出的英语、俄语、法语、德语、意大利语、西班牙语、日语、中文等；Qwen3-ASR 共支持 30 种语言；配音可用语言取决于所选 TTS 方案。
• 本地识别模型（1.7B/0.6B Qwen3-ASR 与对齐模型，数 GB）首次使用时从 Hugging Face 下载，不随安装包分发；Docker 镜像同样不内置模型权重。
• WhisperX 不是安装器选项，也不在镜像内；需要自行按 whisperx-manual.en-US.md 安装，Apple Silicon 上必须使用独立环境。
• 本地 HTTP API 是受信任的本地服务，无认证，只应绑定 127.0.0.1，不要直接暴露到公网；同一时刻只处理一个任务，无队列、无数据库。
• 在线 SaaS 站点 videolingo.io 的服务条款、计费与隐私政策与本仓库本地部署相互独立。

2 功能特性

以下条目整理自官方 README、config.yaml、docs/pages/docs/start.zh-CN.md 与 docs/api.md；具体侧栏标签与参数名称以安装版本界面为准。

2.1 视频输入与下载

• yt-dlp YouTube 下载：侧栏输入 YouTube 链接，按 ytb_resolution（360 / 1080 / best，默认 1080）下载；youtube.cookies_path 可配置 cookies 文件路径用于需要登录的视频。
• 本地上传：支持视频格式 mp4、mov、avi、mkv、flv、wmv、webm；音频格式 wav、mp3、flac、m4a；API 模式下本地文件复制进 output/，源文件不被改动；HTTP(S) 视频 URL 同样可作为输入。
• 人声分离（可选）：demucs: true 在转写前用 Demucs 分离人声；开启后转写使用原始音频、对齐使用分离出的人声；Intel Mac 不会自动安装 Demucs。

2.2 语音识别与词级对齐

• 默认本地 Qwen3-ASR + ForcedAligner：whisper.backend: qwen；whisper.qwen_model 可选 1.7b（默认，更准确）或 0.6b（更快、更省显存）；对齐模型固定为 Qwen3-ForcedAligner-0.6B；whisper.qwen_engine: auto 时按平台自动选择 MLX 或 transformers。
• 平台引擎矩阵（start.zh-CN.md 口径）：

• 语言检测：whisper.language 填 ISO 639-1 或 auto；Auto 模式每个约 3 分钟窗口先取最多 3 段 20 秒片段检测语言并投票，再以投票结果强制整窗转写（识别时间约增加三分之一）；中英混说以第一语言为准；检测出侧栏以外语言（韩语、越南语、泰语等）时自动选择空格或无空格拼接并匹配对应 spaCy 模型。
• 异常输出检测：同一短语循环重复、内容明显过少时先切成 60 秒小窗重试；仍异常则直接报错并提示明确选择识别语言；手动指定语言时若文字书写系统与所选语言明显不符（如选英文却输出韩文）会在第一个窗口即停止报错；静音与纯音乐不触发报错。
• 可选云端识别：侧栏 ASR Runtime 选 elevenlabs（whisper.elevenlabs_api_key，实验性）或 mai（MAI-Transcribe-2）；MAI 服务商 whisper.mai_provider 为 azure（whisper.mai_api_key、whisper.mai_region，区域留空自动检测）或 openrouter（whisper.mai_openrouter_api_key，模型 microsoft/mai-transcribe-2，音频按约两分钟分片上传）；音频会发送到所选云服务商并可能产生费用。
• WhisperX 手动后端：whisper.backend: whisperx，模型 large-v3（名称含 turbo 会被改写为 large-v3）；中文强制 Huan69/Belle-whisper-large-v3-zh-punct-fasterwhisper；安装命令与 CUDA 12 cuBLAS / cuDNN 9 要求见第 7.6 节。
• 识别缓存：缓存区分后端、模型大小与引擎，切换任一项都会重新识别；MAI 缓存区分服务商与 API 版本，不包含密钥或区域。

2.3 分句、术语与翻译

• NLP + AI 分句：先按 max_split_length（默认 20 词）做第一次粗切，再由 NLP 与 LLM 完成句子分段；spacy_model_map 为各语言映射 spaCy 模型（en_core_web_md、zh_core_web_md、ja_core_news_md 等）；language_split_with_space / language_split_without_space 控制词间空格规则。
• 术语表：提取自定义术语与 AI 生成术语，保证翻译一致性；pause_before_translate: true 时在术语提取后暂停，人工校对 output/log/terminology.json 后通过界面继续。
• 多步翻译：先做摘要（summary_length 默认 8000，本地 LLM 可调低到 2k），再分步翻译；reflect_translate: true 用原文回查翻译结果；translation_style 可用自然语言指定译文风格（如 “口语化、短句”），留空表示不附加额外要求。
• 翻译后人工校对：pause_after_translate: true 在翻译完成、字幕生成前暂停，编辑 output/log/translation_results.xlsx 的 Translation 列（保持 Source 列与行顺序不变）后继续。
• LLM 配置：api.key、api.base_url、api.model；api.llm_support_json 仅在服务支持时开启 JSON 模式；max_workers 为 LLM 多线程并发数，本地 LLM 建议设为 1。

2.4 字幕切割、时间轴与视频封装

• 字幕长度控制：subtitle.max_length 默认 75 字符；subtitle.target_multiplier 默认 1.2（译文比原文略长，作为分句参考长度放大系数）。
• 时长合并与裁剪：min_subtitle_duration: 2.5 秒（最短字幕时长，强制延长）；min_trim_duration: 3.5 秒（短于该值不再拆分）；tolerance: 1.5 秒（允许向后一条字幕借用的延长时间）。
• 烧录字幕：burn_subtitles: true；sub_video_subtitles 可选 bilingual / translation / source（字幕视频），dub_video_subtitles 对应配音视频字幕；subtitle.style 分别配置原文与译文的字体、字号、颜色（&HBBGGRR / &HAABBGGRR / #RRGGBB）、描边颜色与宽度、底边颜色与垂直边距；ffmpeg_gpu 可开启 h264_nvenc GPU 加速（需显卡支持）。
• 音频质量：audio.raw_sample_rate: 32000、audio.raw_bitrate: 128k；Demucs 人声与语音克隆参考片段继承该带宽；已存在的 output/audio/raw.mp3 不会被重新提取。

2.5 配音合成与时长校准

• TTS 方案选择：tts_method 取值 edge_tts、openai_tts、fish_audio、f5tts、sf_fish_tts、sf_cosyvoice2、gpt_sovits、custom_tts。
• 语速范围：speed_factor.min: 1、accept: 1.2（最大可接受语速）、max: 1.4；配音句段在该范围内校准时长以贴合字幕时间轴。
• 各后端要点（start.zh-CN.md 对比口径）：

• Fish Audio 模式：fish_audio.mode: clone 取视频开头 15–30 秒人声作为所有句子参考，不在账户保存；preset 使用 voice_id 指定的固定音色；fish_audio.voices 可在配置中追加名字与 ID；模型 fish_audio.model 默认 s2.1-pro（可选 s2-pro、s1）。
• SiliconFlow FishTTS 模式：preset 固定音色（默认 anna）；clone(stable) 对应 API custom，从任务列表选择合适参考片段合并上传为可复用音色；clone(dynamic) 对应 API dynamic，使用当前句子参考片段。
• GPT-SoVITS：gpt_sovits.character 指定角色名（必须英文命名），refer_mode 为参考音频模式；角色 yaml 与参考音频按官方目录结构并列放置，配音时流水线自动在命令行拉起 GPT-SoVITS 推理 API 端口，完成后手动关闭。
• OpenAI TTS：openai_tts.voice 默认 alloy，模型默认 gpt-4o-mini-tts；base_url 与 model 可在 config.yaml 改为其他兼容 OpenAI 语音接口的服务。
• Edge TTS：edge_tts.voice 默认 zh-CN-XiaoxiaoNeural；运行 edge-tts --list-voices 可列出全部声音，需选择目标语言对应音色。

2.6 界面、日志与任务控制

• 一键启动与处理：Streamlit 侧栏完成 LLM、字幕、配音三组配置后，按阶段按钮启动；界面多语言（display_language 默认 zh-CN）。
• 模型搜索框：侧栏模型选择带搜索框，可自动拉取服务商完整模型列表进行筛选。
• 任务控制：处理过程中可随时暂停、恢复或停止；API 状态机包含 idle、running、paused、stopping、stopped、completed、error。
• 日志与断点续跑：详细日志写入 output/；成功响应缓存与中间产物在重试时复用；术语表、翻译表、识别结果、字幕文件等保留在 output/log/ 与 output/ 顶层目录。
• 历史记录：history/ 目录保存归档；POST /archive 在后台归档，同名历史可能被覆盖，保留多个版本需先把结果移走。

3 官方界面预览

图1 为仓库 docs/logo.png 官方品牌标识。经核验，官方仓库 docs/pages/docs/ 下的 zh_page.png、en_page.png 两张界面截图侧栏均含可见 API 密钥，且界面标签为旧版本（旧侧栏显示 “WhisperX 运行环境”、deepseek-chat、https://api.302.ai，与当前 README 默认 Qwen3-ASR、OpenLux 配置口径不一致），按凭据安全与版本一致性规程不予上传。README “Demo” 小节提供三段演示视频（双语字幕、Cosy2 音色克隆、GPT-SoVITS 本人音色），为 GitHub 仓库附件视频，本文不提取帧上传；实际界面效果可在本地启动后查看，或直接打开官方 README 的 Demo 链接对照。

4 官方跳转链接汇总

5 前置要求与服务器配置

5.1 软件前提

• Python 3.12：start.py 脚本头 requires-python = "==3.12.*"；安装器会在 .venv（项目目录）或 ~/.venvs/videolingo（共享环境）中创建 Python 3.12 环境，不要求系统预装 Python 3.12，但 Windows 一键脚本会自动安装 uv、Python 3.12、应用依赖与 FFmpeg。
• uv：Windows 一键脚本首次运行自动安装；源码方式要求本机具备 uv（uv run start.py 自动解析脚本环境）。
• FFmpeg / ffprobe：安装器通过 static-ffmpeg==3.0 自动下载托管的 FFmpeg 与 ffprobe，不需要系统单独安装；自定义代码直接调用 FFmpeg 共享库时另需按 WhisperX 文档处理。
• GPU 驱动（NVIDIA 场景）：安装与显卡兼容的 NVIDIA 驱动；nvidia-smi 显示的是驱动支持的 CUDA 版本，不等于已安装的 Toolkit 版本。主机安装器在驱动报告 ≥12.8 时选择 PyTorch cu128，否则检测到 NVIDIA 时选择 cu126；无法读取支持版本时回退 cu126，不保证旧驱动兼容；无 NVIDIA 则选择 CPU 包。安装器只选择 Python 包，不安装系统 CUDA Toolkit。
• macOS 版本：Apple Silicon 使用 MLX，需要 macOS 14 或更高（mlx 仅提供 macOS ≥14 的 arm64 包）；低于 14 时安装器直接报错退出。
• 网络与账号：翻译需要一个兼容 OpenAI Chat Completions 的大模型 API（URL、密钥、模型 ID 由用户自备）；Edge TTS 需要联网；Fish Audio、SiliconFlow、OpenAI、302AI、ElevenLabs、MAI 等云端服务按各自规则计费；首次本地识别需联网从 Hugging Face 下载 Qwen3-ASR 与对齐模型（可用 HF_ENDPOINT 指定镜像）。
• 可选系统依赖：Docker 场景由镜像内置 Noto CJK 字体、libgl1、libglib2.0-0 等；本地 Windows 无需额外系统库，Linux 发行版基础库以安装器报错提示为准。

5.2 硬件建议

5.3 端口、目录与环境变量

注意：本地 HTTP API 绑定 127.0.0.1、无认证；需要远程访问时应在反向代理层加访问控制与鉴权，不要把 0.0.0.0:8000 直接暴露到公网。Docker 文档示例端口绑定为 127.0.0.1:8501:8501，远程访问需显式配置监听地址与访问控制。

6 方式一：Linux NVIDIA Docker 部署（官方容器路径）

官方提供 Dockerfile（无 docker-compose.yaml，也不提供 .env.example），面向 Linux NVIDIA GPU 主机；镜像构建时执行与主机一致的共享安装检查与 pip check，WhisperX 不预装，模型权重不内置。

6.1 前置准备

1. Linux 主机安装 NVIDIA 驱动、Docker 与 NVIDIA Container Toolkit；主机无需单独安装 CUDA Toolkit，但驱动必须支持所选镜像运行时与 GPU 本身。
2. 克隆仓库并在干净检出状态下构建（先不要把 API 密钥等写进 config.yaml）：

git clone https://github.com/Huanshere/VideoLingo.git
cd VideoLingo

6.2 默认镜像构建（CUDA 12.8.1 / cu128）

docker build -t videolingo .

Dockerfile 口径：基础镜像 nvidia/cuda:12.8.1-cudnn-runtime-ubuntu24.04，系统 Python 仅引导 setup_env.py，应用使用 Python 3.12 虚拟环境；构建期按 --torch-backend cu128 调用 installer.py 安装依赖并执行 pip check；EXPOSE 8501；启动命令 python -m streamlit run st.py --server.address=0.0.0.0 --server.headless=true。

6.3 CUDA 12.6.3 变体（匹配旧驱动）

docker build --build-arg CUDA_VERSION=12.6.3 -t videolingo:cu126 .

该变体选择 12.6.3-cudnn-runtime-ubuntu24.04 与 cu126；两个变体均使用 Torch/torchaudio 2.8.0、torchvision 0.23.0 与同一 requirements.txt 边界；其他 CUDA_VERSION 值会被构建脚本拒绝。构建时不需要 GPU；setup_env.py 把显式构建选择传给主机同款 installer.py。

6.4 启动与数据持久化

docker run -d --name videolingo --gpus all \
  -p 127.0.0.1:8501:8501 \
  -v videolingo-output:/app/output \
  -v videolingo-history:/app/history \
  -v videolingo-models:/app/_model_cache \
  -v videolingo-cache:/app/.cache \
  -v videolingo-hf:/root/.cache/huggingface \
  videolingo

• 浏览器打开 http://localhost:8501 进入界面；命名卷在容器替换时保留输出、历史与模型/ASR 缓存。
• 需要持久化 config.yaml 与 custom_terms.xlsx 时单独挂载本地文件；挂载前文件必须已存在，且配置需要写权限以支持侧栏修改。
• cu126 变体把镜像名替换为 videolingo:cu126。
• 首次使用时 Qwen3-ASR 1.7B/0.6B 与对齐模型（数 GB）下载到 Hugging Face 缓存卷，不在构建期打包。
• 停止容器：

docker stop videolingo

6.5 构建与验证边界

• Dockerfile 在构建期运行共享安装检查与 pip check；源码级检查不能证明镜像构建成功或 GPU 处理一定可用。
• 第三方预构建镜像不保证与当前检出的依赖一致，不建议直接引用未核验的公开镜像。
• 镜像内不包含 WhisperX；如需该后端，需基于本镜像自行派生安装，参考 whisperx-manual.en-US.md。

7 方式二：Windows 一键脚本与源码本地安装

7.1 Windows：一键脚本安装

1. 从 最新 Release 页面 下载 Source code (zip)，解压到桌面等方便找到的位置并打开文件夹。
2. 双击 OneKeyStart.bat，保持窗口打开；首次运行自动安装 uv、Python 3.12、应用依赖与 FFmpeg，需要联网。
3. 安装完成后浏览器自动打开 VideoLingo；在侧栏填写 LLM API 地址、密钥与模型即可开始使用。
4. 配备 NVIDIA 显卡时先安装兼容驱动（见 5.1 节 GPU 运行库口径）。

7.2 源码安装（Windows、macOS、Linux）

git clone https://github.com/Huanshere/VideoLingo.git
cd VideoLingo
uv run start.py

以后在 VideoLingo 目录中再次运行 uv run start.py 即可启动；start.py 会先查找 ~/.venvs/videolingo 与项目 .venv 中的 Python 3.12 环境，环境缺失或健康检查失败时自动调用 setup_env.py --yes 安装或修复依赖。

7.3 启动参数

# 启动 Streamlit 网页界面（默认）
uv run start.py

# 启动本地 HTTP API（替代旧 Excel 批处理）
uv run start.py --api

# 只检查环境，不安装、不启动
uv run start.py --check

7.4 平台差异说明

• Apple Silicon：默认依赖安装 mlx-audio（Transformers 5、huggingface-hub>=1）；手动把 whisper.qwen_engine 设为 transformers 需要另建环境；重跑 installer.py 会先卸载旧环境中冲突的 WhisperX 整套依赖（whisperx、torchcodec、faster-whisper、ctranslate2、pyannote-*）。
• Intel Mac：使用官方 qwen-asr CPU 路径，自动安装 PyTorch 2.2.2；配音默认只保留新生成语音，不混入原始背景音；Demucs 不自动安装。
• Windows / Linux：默认 qwen-asr（Transformers 4.57、hub <1）；Torch/torchaudio 2.8.0、torchvision 0.23.0，三者版本必须匹配。

7.5 GPT-SoVITS 本地配音环境（可选）

1. 按 GPT-SoVITS 官方语雀文档下载整合包，把 GPT-SoVITS-v2-xxx 与 VideoLingo 放在同一目录下并列（两文件夹同级，不要套进 VideoLingo 内部）。
2. 自训练模型：把 GPT_SoVITS/configs/tts_infer.yaml 复制并改名为 角色名.yaml（角色名必须英文）；同目录放入参考音频，命名为 角色名_参考音频文字内容.wav 或 .mp3。
3. 在 VideoLingo 侧栏 GPT-SoVITS 角色 填英文角色名，选择参考音频模式；配音步骤时流水线自动在命令行拉起 GPT-SoVITS 推理 API 端口，配音完成后手动关闭。
4. 期望目录结构（官方文档口径）：

.
├── VideoLingo
│   └── ...
└── GPT-SoVITS-v2-xxx
    ├── GPT_SoVITS
    │   └── configs
    │       ├── tts_infer.yaml
    │       ├── 角色名.yaml
    │       └── 角色名_参考音频的文字内容.wav
    ├── GPT_weights_v2
    └── SoVITS_weights_v2

7.6 WhisperX 手动后端（可选，安装器不提供）

Windows / Linux 在 VideoLingo 目录中针对项目 .venv 安装（共享环境把 .venv 替换为对应路径；不要在 Apple Silicon 默认环境中执行）：

uv pip install --python .venv "whisperx>=3.8.6,<3.9" "ctranslate2>=4.5,<5" "pyannote-audio>=4.0.4,<5" "torchcodec>=0.7,<0.8"

然后在侧栏 ASR Runtime: Local → Local ASR Backend: WhisperX (manual install) 选择，或在 config.yaml 设置：

whisper:
  runtime: 'local'
  backend: 'whisperx'
  model: 'large-v3'
  language: 'en'

• WhisperX GPU 执行需要 CUDA 12 cuBLAS 与 cuDNN 9；缺失时按 faster-whisper 与 CTranslate2 4.5 文档配置库搜索路径。
• Apple Silicon 因 huggingface-hub 版本约束冲突，必须使用独立虚拟环境，仓库不提供该环境的安装器，组合未经验证。
• 启用后端后运行 uv run start.py --check 验证环境、FFmpeg 解码与 pyannote 内存音频路径。

7.7 HTTP API 使用要点

uv run start.py --api

• 服务监听 127.0.0.1:8000；交互式文档 http://127.0.0.1:8000/docs，OpenAPI 规范 http://127.0.0.1:8000/openapi.json；只启动一个服务进程，不要多 worker。
• 提交素材：POST /input，JSON {"source": "/absolute/path/video.mp4"}；Windows 使用 C:/Videos/video.mp4 路径；也可传 HTTP(S) 视频 URL；202 表示已接受而非完成。
• 启动处理：POST /run，{"stage": "all", "target_language": "zh", "dubbing": true}；stage 可选 transcribe、subtitles、dubbing、all；dubbing 默认 false；dubbing 阶段要求已有字幕；transcribe 只产出 src.srt。
• 轮询 GET /status：返回 state、active、step、step_index、total_steps、progress、error 与顶层输出 files；进度按已完成步骤组计数，不等于经过时间。
• 暂停点：pause_before_translate 后状态为 paused，编辑 output/log/terminology.json 后 POST /resume；pause_after_translate 后编辑 output/log/translation_results.xlsx 再 POST /resume。
• 取文件 GET /files/trans.srt；归档 POST /archive（后台执行，等完成再准备下一个视频）；忙碌时 /input、/run、/archive 返回 409。
• /input 默认拒绝非空 output/；显式传 "existing": "archive" 或 "existing": "replace" 归档或删除旧输出后再准备下一个。
• 已有字幕翻译：POST /input 同时传 "subtitles": "/absolute/path/video.srt"（UTF-8）；source 直接传 SRT 时只产出字幕文件，需通过 source_language 或 whisper.language 指定源语言，不要用 auto。
• 状态保存在内存，服务重启后为 idle；文件保留，可重新 POST /run 复用中间产物。

8 配置项说明

config.yaml 中 * 标记为高级设置，不显示在 Streamlit 页面，只能手动编辑；其余项优先在侧栏修改。以下分组整理自仓库当前 config.yaml，字段以安装版本为准。

8.1 基础设置

8.2 识别（whisper）

8.3 字幕与翻译高级项

8.4 配音设置

8.5 附加设置

密钥填写注意：api.key、各 TTS 密钥、MAI/ElevenLabs 密钥属于敏感信息，不要提交到公开仓库、不要写入截图或文章；配置 config.yaml 被 Docker 拷贝进镜像，构建前应先排除凭据。

9 常用运维命令

9.1 启动、停止与环境检查

# 源码方式启动网页界面
uv run start.py

# 启动本地 HTTP API
uv run start.py --api

# 环境检查（不安装、不启动）
uv run start.py --check

• 停止：Streamlit 窗口按 Ctrl+C；API 进程同样 Ctrl+C 终止；Docker 场景 docker stop videolingo。
• 修改 config.yaml 后需重启进程生效；API 运行期间不要编辑配置（官方 API 文档口径）。

9.2 更新与重装

# 拉取最新源码后重跑启动脚本，自动修复/补充依赖
git pull
uv run start.py

• Docker 场景：在干净检出状态重新 docker build -t videolingo .，再用 6.4 节命令启动新容器；命名卷中的 output/、history/、模型缓存不会因替换容器丢失。
• 旧环境残留 WhisperX 依赖与 MLX 冲突时，重跑 installer.py 会先卸载冲突栈；Apple Silicon 上 WhisperX 需保留在独立环境。

9.3 日志、缓存与产物定位

9.4 备份与恢复

建议定期备份：

Docker 持久化已通过命名卷覆盖 output/、history/、_model_cache、.cache 与 Hugging Face 缓存；config.yaml 与 custom_terms.xlsx 需单独挂载才能跨容器替换保留。

9.5 测试与排障辅助

# API 测试（不下载模型），使用项目 .venv
uv pip install --python .venv pytest httpx
uv run --python .venv pytest tests/test_api.py

• 查看 Streamlit 端口占用：本机 8501 被占用时停止旧实例，或修改 Streamlit 启动参数后重启；API 端口 8000 冲突时同理先释放端口。
• 模型下载受限时先设置 HF_ENDPOINT 镜像，确认 _model_cache 与 HF 缓存目录可写。
• 排障顺序（官方 README 限制第 2 条口径）：先看 output/gpt_log/error.json 确定失败步骤 → 复用成功缓存与中间产物重试 → 仅清除出错步骤缓存 → 不要第一步删除全部 output/。

10 常见故障排查

以下问题整理自 docs/pages/docs/start.zh-CN.md “常见报错与踩坑”、docs/api.md 与 whisperx-manual.en-US.md；排查时先用短素材、默认参数复现，再逐项加回变量定位。

10.1 翻译阶段 “All array must be of the same length” 或 “Key Error”

• 原因 1：弱模型遵循 JSON 格式能力较弱，响应解析错误。
• 原因 2：敏感内容导致 LLM 拒绝翻译。
• 处理：查看 output/gpt_log/error.json 中的 resp_content、resp、message；校验失败记录与成功响应缓存分开保存，先确定出错步骤，再考虑清除该步骤缓存；换用 JSON 遵循能力更强的模型或在服务支持时开启 llm_support_json。

10.2 “Retry Failed”、“SSL”、“Connection”、“Timeout”

• 通常为网络问题：检查大模型 API、云端 TTS/ASR 与 Hugging Face 连通性；中国大陆用户按文档建议切换网络节点后重试；确认 api.base_url 可从本机访问，DNS 与代理配置正确。

10.3 缺少 qwen-asr 或 mlx-audio 包

• 现象：提示 Qwen ASR engine '...' needs the 'qwen-asr' package（或 mlx-audio）。
• 处理：关闭 VideoLingo 后重新启动——Windows 双击 OneKeyStart.bat，源码方式运行 uv run start.py，由 start.py 自动修复依赖；Apple Silicon 上若手动设置了 whisper.qwen_engine: transformers，改回 auto。

10.4 识别语言检测失败或结果退化

• 现象：Qwen3-ASR could not detect the language，或 ... is still degenerate after retrying。
• 处理：Auto 模式未识别出语言，或识别结果循环重复、内容过少；在侧栏明确选择识别语言后重试，也可以切换另一个模型大小（1.7b ↔︎ 0.6b）。
• 同为拉丁字母的语言之间选错（如英文视频选了西班牙语）无法自动检测；模型可能把部分窗口直接翻译成所选语言，造成半原文半译文，应优先使用 Auto 或在处理前核对语言设置。

10.5 显存不足（CUDA out of memory）

• 在 config.yaml 把 whisper.qwen_model 改为 0.6b；关闭其他占用显卡的程序；确认未同时运行第二个占用显存的识别任务。
• 云端识别（ElevenLabs / MAI）可作为无本地显存条件下的备选路径，音频会上传到服务商并可能计费。

10.6 macOS 安装报 mlx 无法解析 / 没有可用安装包

• mlx 仅提供 macOS 14 及以上的 Apple Silicon 安装包；先升级系统，再重跑 uv run start.py；低于 macOS 14 时安装器会直接报错退出。

10.7 WhisperX 相关报错

• cublas64_12.dll not found：进程找不到 CUDA 12 cuBLAS；检查所选环境、Torch CUDA 构建与库搜索路径，新驱动本身不提供该 DLL。
• 模型加载段错误静默退出：ctranslate2 版本与 cuDNN 版本不匹配；确保 ctranslate2>=4.5.0（对应 cuDNN 9）。
• Weights only load failed：PyTorch ≥2.6 的 torch.load 默认行为导致；官方 whisperX_local.py 已做补丁，若仍出现说明代码不是最新版本。
• Streamlit 中 WhisperX 识别挂起（CPU/GPU 空闲）：librosa.load() 在非主线程死锁；官方已替换为 whisperx.audio.load_audio()（FFmpeg 子进程），出现该现象说明代码未更新。
• TorchCodec could not load 警告本身不阻断 VideoLingo 的 WhisperX 流水线（波形以内存方式传给 pyannote）；运行 uv run start.py --check 验证音频路径。
• WhisperX is not installed：whisper.backend 为 whisperx 但包未安装；按 7.6 节安装依赖，或把后端改回 qwen；安装器不会替用户安装 WhisperX。

10.8 spaCy 模型缺失

• 首次用到对应语言模型时通常自动下载；检查网络连接后重试该步骤；无对应 spaCy 流水线的语言（阿拉伯语、泰语、越南语等）按标点仅做句子切分。

10.9 Torch 组件版本不一致

• 关闭 VideoLingo 后重新启动修复：Windows 双击 OneKeyStart.bat，源码方式运行 uv run start.py。Intel Mac 使用 Torch/torchaudio 2.2.2、torchvision 0.17.2；其他平台使用 2.8.0、0.23.0，三者必须匹配。

10.10 Docker 与目录挂载问题

• 容器内 config.yaml、custom_terms.xlsx 挂载前文件必须已存在，且配置需要写权限以支持侧栏修改。
• 模型首次下载到 Hugging Face 缓存卷时确认命名卷挂载路径为 /root/.cache/huggingface；换主机或清理卷后需要重新下载模型。
• 端口绑定示例为 127.0.0.1:8501:8501；需要远程访问时显式配置监听地址并加访问控制，不要裸暴露。

10.11 HTTP API 排错

• 409：上一个 /input、/run 或 /archive 仍在忙碌，等待后再提交下一个操作。
• /input 拒绝非空 output/：传 "existing": "archive" 或 "existing": "replace" 先归档或删除旧输出。
• 失败后修改参数不会让中间产物失效；要按新设置重新生成，需先重新 /input（existing: archive / replace）再 /run。
• POST /stop 为协作式取消，可能等待当前模型/网络调用结束；等待 active: false 后再重试或替换输入。
• 服务重启后状态回到 idle，但文件保留，可直接 /run 复用中间产物。
• 状态异常时先查 GET /status 的 error 字段与 output/gpt_log/error.json，修复原因后重复 /run，不添加整步骤自动重试。

10.12 常见报错快速对照

11 风险与合规说明

11.1 开源许可与组件边界

• VideoLingo 代码本体采用 Apache License 2.0；二次修改与分发需保留版权声明与许可证副本，并按 Apache 2.0 要求标注变更。
• 底层与依赖组件各自遵循上游许可证：Qwen3-ASR、MLX Audio、WhisperX、yt-dlp、json_repair、BELLE、spaCy、PyTorch、Streamlit、FastAPI、Demucs、silero-vad、Edge TTS 适配器等，商用前应逐项核对其上游许可与限制。
• 官方仓库不内置识别模型权重、TTS 音色包与视频素材；首次下载的模型、克隆音色与参考音频受对应发布方许可约束。

11.2 源视频版权与素材授权

• 待翻译、配音的视频与音频可能涉及影视、课程、音乐、图片、字幕等著作权；未经授权对受版权保护的视频进行翻译、配音、二次剪辑并公开传播，可能构成侵权。
• YouTube 等平台的下载行为除受著作权约束外，还受平台服务条款与 robots/下载规则限制；yt-dlp 下载应仅用于本人拥有权利或已获得明确授权的素材。
• 公开分发双语字幕、配音版视频时，应在产物中注明原始作者、来源与授权范围；不得抹去版权声明与水印。

11.3 语音克隆与人格权益

• Fish Audio、SiliconFlow FishTTS、CosyVoice2、GPT-SoVITS、F5-TTS 等克隆方案以视频参考人声生成新配音；克隆他人声音可能涉及肖像权、声音权益与人格权，应仅克隆自己有权使用的声音（本人声音或已获授权的声音）。
• 不得把克隆音色用于冒充他人、伪造采访、深度伪造、诈骗、诽谤或误导第三方；正式发布的克隆语音应在产物说明中披露 AI 合成属性。
• 官方文档同样提示：Fish Audio 克隆模式 “请只克隆你有权使用的声音”。

11.4 云端服务与数据隐私

• 使用 OpenAI 兼容 LLM、ElevenLabs、MAI-Transcribe-2（Azure / OpenRouter）、Fish Audio、SiliconFlow、302AI 等云端服务时，视频转录文本、字幕、参考音频片段会上传到对应服务商；涉密、内部、含个人隐私的素材应优先选择本地可部署方案或取得服务商书面隐私承诺。
• 本地 HTTP API 无认证且绑定本机，暴露到局域网或公网前必须加反向代理鉴权；不要在 config.yaml 中留存真实密钥后提交公开仓库或打包进第三方镜像。
• 训练 / 参考素材、字幕成品与日志中可能包含个人信息、联系方式与内部资料，发布模型缓存、日志与归档前应做脱敏检查。

11.5 内容责任与免责声明

• 流水线不内置内容审核；翻译错误、术语错配、配音情绪不当、时长偏移与语音克隆瑕疵由使用者在发布前人工校对；字幕质量受源音频噪声、语言组合与所选模型限制（见 1.3 节官方边界）。
• 产物用途（商业广告、教学公开、影视发行、有声书、直播配音等）须遵守目标平台规则、广告法与生成内容标识要求。
• 本文依据当前版本官方资料整理，接口字段、模型清单、TTS 方案与端口口径会随版本演进变化；命令、路径与配置以安装版本仓库 docs/、侧栏提示与官方最新文档为准。本文按现状（AS-IS）提供，不构成对翻译质量、配音效果、商用授权、账号安全或第三方服务可用性的任何担保。