autoclip/docs/FAQ.md

常见问题与排错

English · 安装指南 · 返回首页

费用、模型与数据

AutoClip 收费吗？必须有 API Key 吗？

AutoClip 本身仍然免费、开源（MIT）。云端模型调用由你选择的服务商计费，价格、额度和可用模型以服务商为准。Ollama / LM Studio 本地预设无需云端 API Key，但需要下载模型并具备相应硬件；本地 Whisper 也需要单独安装组件和语音模型。

自 v1.3.2 起，海外发布需要你自己的 Upload-Post 账号。免费档、付费档，以及 TikTok、YouTube、Instagram 等平台的每日额度，以 Upload-Post 自己的页面为准，不是 AutoClip 的承诺。

视频会上传吗？可以离线使用吗？

剪辑与渲染留在你的设备上，视频也保存在本机。字幕路线会把相关字幕或文案发给所选云端服务商。启用云端视觉模型时，会发送抽样画面及必要文字，费用取决于该服务商。成片只有在你点「发布」之后才会离开这台机器，发到你已经连接的平台。也可以只下载、不发布。匿名使用统计和错误报告取决于版本、构建配置和设置，详见 隐私说明。发布页自 v1.3.2 起可用。

准备好本地视频、语言模型及语音模型后，核心本地处理无需云端模型服务。视频下载、组件安装、模型下载和更新仍需要网络。不要把“本地处理”理解为所有功能都不联网。

哪些视频比较适合？

默认路线是字幕分析，对白清楚的访谈、播客、课程、口播和直播回放比较合适。自 v1.4.0 起，游戏录屏可另行启用视觉分析：需要多模态模型，并显式启用付费视觉初筛。单一样本不代表所有游戏；输出仍需人工检查边界、裁切和文案，不承诺广告投放效果。音乐或其他主要依赖画面、又未启用视觉分析的内容，单靠字幕可能无法识别精彩点。没有固定出片数量或效果保证。

第一次出片请自备 3–5 分钟、对白清楚的短样片，最好带时间轴准确的 .srt。来源可以是本地文件、B 站或 YouTube，请确认你有权使用。AutoClip 不托管官方样片，Release 里也没有样片压缩包或成片下载。

第一次出片先试这条：Jackie Dowling | Stanford Energy Fellow（Stanford ENERGY）。示例·非托管·自担使用权。

其他示例不必都试。多为英语对白，可开官方字幕或自备 SRT/Whisper。

• The State of Startups in 2026（Y Combinator）。示例·非托管·自担使用权。
• Sam Altman on Astra, AGI, and the future of OpenAI。第三方访谈（Sources Podcast，非 OpenAI 官方频道）。示例·非托管·自担使用权。

准备步骤见 安装指南 · 自备短样片，卡点见 讨论 #128。

安装与启动

应该下载哪个文件？

Releases 中，Apple Silicon Mac 选 aarch64.dmg，Windows x64 选 x64-setup.exe。Intel Mac / Linux 使用 Docker 或 CLI。以每次 Release 的实际资产为准，Source code 不是桌面安装包。Release 不提供官方样片或成片下载。

首次启动的系统提示请参考 安装指南 和对应 Release。Windows 日常运行不需要管理员权限。

空白页、后端未启动或连接失败怎么办？

1. 完全退出后重新启动一次，保留数据目录。
2. 检查磁盘空间，记录界面上的具体错误和发生阶段。
3. 桌面后端端口由启动器管理，查看实际启动日志，不要假设一直是 8000。Docker 默认 Web 端口为 3000、API 端口为 8000。
4. Web 模式下若开启了浏览器网页翻译，先关闭翻译再刷新。
5. Docker 用户执行 docker compose ps 和 docker compose logs --tail=100 autoclip celery-worker，参见 Docker 指南。

模型连接测试失败怎么办？

确认提供商、模型名、API Key、Base URL 与区域设置一致，账号拥有该模型权限。Ollama / LM Studio 要先启动服务并加载模型。本地服务默认地址分别是 http://localhost:11434/v1 和 http://localhost:1234/v1。

Docker 中的 localhost 是容器自己。宿主机模型服务的访问方式见 Docker 指南。若出现代理、TLS 或超时错误，检查具体连接目标和网络配置；不要在反馈中粘贴完整 API Key。

字幕、分析与导出

字幕分析和游戏视觉分析怎么选？

自 v1.4.0 起有两条路线。字幕分析仍是默认，旧配置也默认字幕模式。游戏视觉分析可选：自行配置多模态模型，并显式启用付费视觉初筛。配好模型不等于已经允许每次视觉调用。确认后，视觉路线识别录屏中的独立事件，生成可编辑高光与推广草稿，再在共用编辑器里修改。未确认的导入可恢复；确认后才正式理解和剪辑。

单一样本不代表所有游戏质量。输出仍需人工检查边界、裁切和文案，不承诺广告投放效果。v1.4.0 不含 CTA 动效、生成式品牌尾卡、卡拉 OK / 逐词字幕。

视觉分析怎么计费？会发出画面吗？

剪辑与渲染在本机完成。字幕路线发送相关字幕或文案。使用云端视觉模型会发送抽样画面及必要文字。费用取决于所选服务商，没有统一标价。本地 Ollama / LM Studio 不经过云端计费，但仍需要你自己的模型和硬件。未确认导入不会开始正式理解和剪辑。

没有字幕怎么办？支持什么字幕格式？

首页的本地上传入口支持可选 .srt。没有可用字幕时需要本地语音转写；先在设置中安装 Whisper 组件与模型。CLI 环境可安装 faster-whisper。其他字幕格式建议先转换为带正确时间轴的 SRT，不假设上传入口支持所有格式。

在 Windows 上安装 Whisper 仍提示 mlx-whisper 仅支持 Apple Silicon？

「设置 → 转写」里安装 Whisper 时，若 Windows 或其他非 Mac 仍出现红色错误「mlx-whisper 仅支持 Apple Silicon (macOS)」，请更新到 v1.3.3 或更新（含 #145）。桌面版用「设置 → 应用 → 检查更新」，或到 Releases 下载。旧版会误报并拦住安装；更新后点原来的「安装」即可。见 #141。

为什么没有生成片段？

先看项目错误提示，再按失败阶段排查：

阶段	优先检查
字幕 / SUBTITLE	字幕是否为空、时间轴是否与视频对应、Whisper 是否就绪
分析 / ANALYZE	模型连接是否成功、返回是否可解析、字幕是否有足够内容。时间线为空时，仍需检查字幕内容和模型返回；自 v1.3.5 起，这种情况不再只提示去改模型设置
评分	是否有候选片段、阈值是否过高；可尝试从 0.7 降到 0.5 后重新处理
导出 / EXPORT	FFmpeg 是否可用、磁盘是否充足、输出目录是否可写

CLI 可先检查环境，再用较低阈值验证：

autoclip doctor --provider ollama
autoclip run talk.mp4 --provider ollama --srt talk.srt --min-score 0.5 --json

把示例文件名和模型选项换成实际配置；没有 SRT 时去掉 --srt talk.srt 并确保转写已就绪。降低阈值只影响筛选，不保证一定有片段。第一次验证用自备短片，或先试上文的 Jackie Dowling | Stanford Energy Fellow。不必把示例都跑一遍。用法上仍不清楚时，到 第一次出片问答 讨论。能复现的故障仍开 Issue。

处理慢、内存不足怎么办？

先区分视频下载、转写、模型分析和 FFmpeg 导出哪个阶段慢。用短视频验证；关闭不必要的并发任务，尝试更小的本地模型，并检查可用内存与磁盘。转写模型首次下载可能耗时较长；重试前确认旧任务是否仍在运行。处理时间随硬件、时长、模型和导出设置变化，没有统一的“每小时视频几分钟”承诺。

下载 YouTube / B 站视频失败怎么办？

先确认链接可在浏览器打开、当前账号有权访问，必要时配置该平台的登录凭据。CLI / 源码环境可检查 yt-dlp 版本，桌面用户先检查新版本。也可以使用有权获取的本地文件继续处理。不要在 Issue 或邮件中发送 Cookies。

原始切片和发布导出有什么区别？

切片是根据时间范围从原视频生成的片段；发布导出会按预设进一步渲染，例如竖屏布局、烧录字幕和标题卡。生成切片后仍需执行导出，并播放检查结果。

autoclip export PROJECT_ID --preset shorts

PROJECT_ID 替换为真实项目 ID。其他预设包括 douyin、xiaohongshu、bilibili 和 original，详见 CLI / MCP 指南。

v1.3.2 的发布页怎么用？

自 v1.3.2 起可用。

切片就绪后，在切片上打开发布。海外和 B 站在同一页：

• 海外平台走你自己的 Upload-Post 账号，以及你在那里连接的平台。范围是 TikTok、Instagram、YouTube、Facebook、LinkedIn、X、Threads、Pinterest、Bluesky、Discord、Telegram、Google Business，以该账号实际连接的为准。
• B 站在设置里粘贴一次 Cookie。Cookie 须包含 SESSDATA、bili_jct、DedeUserID。一个 B 站账号。

可以现在发，也可以定时。B 站的定时须晚于现在两小时。标题和描述可以不填，默认用切片标题。字幕烧录默认打开。片头约 4 秒的标题卡默认打开。可见范围在平台支持时默认「仅自己」。AutoClip 对外只对 TikTok、YouTube、B 站承诺仅自己 / private。也可以只下载成片、不发布。

项目页可以查看发布记录和月历，并取消尚未发出的排期。「排这一周」只排海外平台，把还没发的切片填进周一、周三、周五的 09:00，不包含 B 站。

画幅跟着要发的账号：有竖屏账号时渲成 9:16，不按 60 秒截断。只发 B 站时用横屏。只有 LinkedIn、X 这类横屏账号时用原画。竖屏和 B 站放在同一次时，各自单独渲染。

发布时可自动生成封面，避免 B 站空封面被拒。默认封面和标题卡的细节随本版安装包说明。自 v1.3.2 起可用。

更新、备份与反馈

数据存在哪里？如何备份？

桌面默认目录见 安装指南。Docker 使用仓库下的 data/、logs/、uploads/ 绑定目录。退出应用或停止服务后，备份数据库、项目文件与配置，避免运行中只复制 SQLite 主文件。不要依赖未经确认的自动备份，也不要为了排错删除原始数据。

升级后项目列表打不开

桌面端和 Docker 的项目状态、类型存在 SQLite 的文本列里。服务按枚举名字读取（PENDING、KNOWLEDGE）。库里若还有当前版本对不上的值，整页列表会加载失败。已知的一类旧值是已经从代码移除的 cancelled / CANCELLED；写成小写 value（pending）时也会对不上。

自 v1.3.3 起，服务启动时自动改写这两个字段。项目记录保留：

• 能对上的 value 改成枚举名，例如 pending → PENDING
• 无法识别的状态（含 cancelled）改为 FAILED
• 无法识别的项目类型改为 DEFAULT

升级后重新打开应用，项目列表应能打开。被改写的项目会显示为失败或默认类型。升级前若要自己看一眼：

SELECT status, COUNT(*) FROM projects GROUP BY status;
SELECT project_type, COUNT(*) FROM projects GROUP BY project_type;

哪里看已知问题？怎样联系？

先查 已知问题 和 版本记录。希望增加的能力、用法和模型发到 Discussions：欢迎与分类、第一次出片问答、想法。能复现的故障开 Issue。规则见 社区看板。仍需联系时，将以下信息一次性发到 christine_zhouye@163.com：

• 系统和 CPU 架构、AutoClip 版本、桌面 / Docker / CLI 使用方式。
• 模型提供商、模型名、视频来源与大致时长、是否提供字幕。
• 复现步骤、失败阶段、错误截图或最近的相关日志。
• 日志中移除 API Key、Cookies、私人路径和不希望公开的字幕内容。

个人业余维护，回复时间不固定，不提供即时客服或一对一部署服务。