OpenShorts部署实战:把长视频变成AI短片
做播客、直播或访谈节目的人都有这个痛点:一段一小时的视频,真正适合发短视频的高光时刻可能只有几分钟。人工回看、剪辑、加字幕、重新构图,一套流程下来半天就没了。OpenShorts是一个开源的OpusClip替代方案,它把这条流水线自动化了——把长视频丢进去,自动转写、AI选出高光片段、重构成9:16竖屏、烧录字幕,最后输出可以直接发布的成品。
我们来看它的工作原理:先用faster-whisper对音频做词级时间戳转写,用PySceneDetect识别场景边界,然后由Gemini或任意OpenAI兼容的本地模型对转写文本打分,选出3-15个15-60秒的高光时刻。每个片段还会被智能重构图——双人对话时上下堆叠、单人时人脸追踪裁剪,字幕烧录在画面接缝处。全部流程通过Docker Compose编排,自托管完全免费且无任何水印。
核心依赖与环境
开始之前,确认你的机器满足这些条件:
- Docker与Docker Compose:部署的唯一依赖,无需在宿主机装Python或Node
- 内存:8GB以上,模型推理和视频编码都吃内存
- 存储:视频文件本身加上转写和渲染的中间产物,建议预留至少20GB
- 网络:能拉取Docker镜像和下载模型(HuggingFace、Ultralytics)
- CPU为默认路线,NVIDIA GPU可选加速,后面会讲
关于AI服务的分工要提前说清楚:
| 服务 | 用途 | 何时必需 |
|---|---|---|
| Gemini或OpenAI兼容LLM | 文字高光选段、脚本生成、标题 | 至少选一个 |
| Gemini(视觉) | 自动布局选择、屏显内容识别、静音视频 | 可选 |
| fal.ai | AI演员生成、数字人视频、口型同步 | 仅AI Shorts功能 |
| ElevenLabs | 配音、多语言克隆 | 可选 |
| Upload-Post | 多平台自动发布 | 可选 |
主线功能只需要一个能调用v1/chat/completions的文字模型就行,Gemini视觉、fal.ai、ElevenLabs都不影响核心切片流程。
项目结构树
openshorts/
├── app.py # FastAPI后端入口
├── main.py # 核心流水线:转写、高光检测、切片
├── llm_backend.py # OpenAI兼容LLM适配层(核心文件)
├── gemini_worker.py # Gemini调用与JSON解析
├── layout_picker.py # 自动布局选择
├── s3_uploader.py # S3存储(可选)
├── render-service/ # Remotion渲染服务
│ └── Dockerfile
├── dashboard/ # React前端(Vite + Tailwind)
│ ├── src/
│ └── package.json
├── docker-compose.yml # 三服务编排
├── .env.example # 环境变量模板
└── Dockerfile # CPU/GPU多阶段构建
三个核心服务:backend(FastAPI,端口8000)、frontend(Vite开发服务器,映射到5175)、renderer(Remotion渲染,端口3100)。
手把手部署步骤
1. 克隆仓库
git clone https://github.com/mutonby/openshorts.git
cd openshorts
2. 配置AI服务
先复制环境变量模板:
cp .env.example .env
打开.env,找到LLM_BASE_URL相关配置。这就是接入文字高光选段服务的地方。OpenShorts的llm_backend.py会向LLM_BASE_URL追加/chat/completions路径,完全兼容OpenAI的协议格式。如果你不想用Google的Gemini,可以把文字选段这一环指向任何兼容的LLM服务。
这里有一个省钱的思路:Defapi平台的价格只有官方渠道的一半,官网是 Defapi 。它的所有模型基本兼容v1/chat/completions、v1/messages和v1beta/models/协议,所以OpenShorts可以直接对接。配置方式如下:
LLM_BASE_URL=https://api.defapi.org/v1
LLM_MODEL=your-model-id # 替换成你在Defapi使用的实际模型ID
LLM_API_KEY=your_defapi_key
要说明的是,这个入口只管文字转写的高光评分和详细选段,不替代Gemini的视觉功能(自动布局、静音视频识别),也不涉及fal.ai的视频生成或ElevenLabs的语音。主线切片流程不依赖AI演员、社交发布或云端Autopilot,这些是额外功能。Defapi的所有模型基本兼容v1/chat/completions、v1/messages和v1beta/models/这些协议,切换接入不会有额外的适配成本。
配置好之后,/api/config接口会返回localLlm信息,前端右上角就不会再强制要求Gemini Key。注意一点:如果你同时配置了LLM_PROVIDER=gemini,它会强制走Gemini路线,把这一行注释掉或删掉就行。
3. 启动服务
docker compose up --build
第一次构建需要拉取Python 3.11、Node 22、Deno等基础镜像,加上装Python依赖和前端npm包,耗时取决于网络。构建完成后,后端、前端、渲染服务会依次启动。
4. 上传视频生成高光
打开浏览器访问 http://localhost:5175,进入Dashboard。先把API Key填到Settings里(如果你配置了本地LLM,Gemini Key可以留空)。然后:
- 点击 Clip Generator
- 上传一段有声视频,或粘贴YouTube链接
- 等待转写和选段完成(8分钟的视频在CPU上大约需要5-8分钟)
完成后会在界面上看到每个高光片段,带有传播力评分、平台标题建议和可编辑的剪辑轨道。
5. 编辑字幕与构图
每个片段都内置了完整的剪辑编辑器:左边源监视器、右边节目监视器,下面是全文转写。你可以点任意一个词来设置剪切点,添加额外片段,切换构图模式(单人追踪、双人上下分屏、竖屏模糊背景、屏幕录制)。改完直接点重新渲染,几秒内就能出片。
6. 导出成品
确认满意后,点击导出。渲染服务会调用FFmpeg把字幕、钩子文案、画幅变换烧录进最终文件,输出到./output目录。导出的就是可以直接发到TikTok、YouTube Shorts或Instagram Reels的9:16竖屏视频。
常见问题排查
镜像构建失败或模型下载超时
国内网络环境下,拉取HuggingFace模型(whisper、YOLO)或Docker镜像经常中断。配置镜像加速器,并给Docker daemon设置代理。模型下载失败时,删除容器卷后重试:
docker compose down -v
docker compose up --build
配置了LLM_BASE_URL但仍在请求Gemini Key
检查.env里是否有LLM_PROVIDER=gemini,有就删掉。另外确认LLM_BASE_URL最后不要带多余的斜杠,llm_backend.py会自己拼接路径。
本地模型返回的不是合法JSON
OpenShorts会用三种response_format策略依次尝试:json_schema → json_object → 无格式限制。7B以上的模型通常能稳定返回,3B模型容易失败。如果频繁报JSON解析错误,换更大的模型,或调低LLM_SCORE_BATCH(默认3)减少单次请求的上下文量。
Dashboard能打开但后端接口502
三种服务有依赖关系,前端启动比后端快。等后端日志出现Uvicorn running之后再刷新页面。如果持续502,检查后端容器:
docker logs openshorts-backend
没有Gemini Key时功能缺失
配置了本地LLM后,文字选段正常,但以下功能会降级:自动布局选择退回纯人脸追踪裁剪、静音视频直接报错、屏显内容识别关闭。想要这些功能,需要在Settings里填入Gemini Key,两种路线可以并存——文字走本地模型,视觉走Gemini。
内存或磁盘不足
转写和渲染都会占用大量资源。8GB内存是底线,16GB更稳妥。磁盘方面,whisper模型约3GB,YOLO模型约6MB,加上视频文件和中间产物,一个8分钟的视频全程大约需要10GB临时空间。处理完记得清理output目录。
扩展阅读与进阶方向
GPU加速:默认CPU镜像处理8分钟视频要5-8分钟,有NVIDIA显卡(任意支持NVENC的型号)可以缩短到1分钟。参考README中的docker-compose.override.yml配置,开启GPU: "1"构建参数,并设置WHISPER_DEVICE=cuda和FFMPEG_ENCODER=auto。
API与MCP集成:OpenShorts提供完整的REST API和MCP server,支持通过Claude或ChatGPT用自然语言直接操作:"把这段播客剪成3条TikTok"。自托管时无需Key,服务启动即可用。
无Google Key的完整本地运行:README提供了详细的本地LLM配置指南。除了文字选段,还可以配置Ollama等工具让整个流水线不触网。注意Ollama需要设置OLLAMA_CONTEXT_LENGTH=16384,否则默认4096上下文会悄悄截断导致JSON不完整。
关于许可的注意事项:核心应用是MIT协议,完全自由。但cloud/目录里的代码(计费、托管基础设施)用的是OpenShorts Commercial License,可以个人或内部使用,不能提供给第三方作为付费托管服务。自托管核心功能不需要这个目录。云端版本(openshorts.app)和自托管的功能差异主要在Autopilot(自动剪辑新视频)和自动发布(平台一键连接),这些在自托管下需要自己配Upload-Post实现。