AutoClip 详细部署教程：AI 智能视频高光切片系统

AutoClip 是一个基于 AI 的智能视频处理系统，能够自动从 YouTube、B 站等平台下载视频，通过通义千问等大语言模型分析内容，智能识别并提取精彩片段，自动生成切片和合集。本教程将详细介绍其两种主要部署方式。

1. 系统概述与准备工作

1.1 核心特性

多平台支持：支持 YouTube、B 站视频下载及本地文件上传。
AI 智能分析：基于大语言模型（默认通义千问）进行视频内容理解、精彩度评分和标题生成。
自动切片与合集：智能识别精彩片段，AI 推荐或手动创建视频合集。
现代化架构：基于 FastAPI (后端) + React (前端) + Celery (任务队列) 构建，提供 Web 界面和实时进度反馈。
扩展能力：开发中的功能包括 B 站自动上传、可视化字幕编辑等。

1.2 环境要求

操作系统：macOS / Linux / Windows (推荐使用 WSL)。
核心依赖：
- Python：3.8+ (推荐 3.9+)
- Node.js：16+ (推荐 18+)
- Redis：6.0+ (用作消息代理和缓存)
- FFmpeg：用于视频处理
硬件：最少 4GB 内存，推荐 8GB+；可用存储空间至少 10GB。
API 密钥：需要通义千问 (DashScope) 的 API Key 才能使用 AI 分析功能。

2. 部署方式一：Docker 部署（推荐）

Docker 方式最为便捷，可以一键启动所有依赖服务。

克隆项目：

1 2	git clone https://github.com/zhouxiaoka/autoclip.git cd autoclip

配置环境变量：
复制示例环境变量文件并进行编辑，必须填入你的通义千问 API Key。

1
2
3

cp env.example .env
# 使用文本编辑器打开 .env 文件，至少修改以下行：
# API_DASHSCOPE_API_KEY=你的通义千问API密钥

一键启动：
项目提供了便捷的 shell 脚本。

# 给予脚本执行权限 (首次运行)
chmod +x *.sh

# 启动所有服务 (生产模式)
./docker-start.sh

# 或使用开发模式启动 (支持热重载)
./docker-start.sh dev

验证与访问：
- 检查服务状态：./docker-status.sh
- 停止服务：./docker-stop.sh
- 访问服务：
  - 前端界面：http://localhost:3000
  - 后端 API 文档：http://localhost:8000/docs

3. 部署方式二：本地手动部署

如果你想更深入地控制各组件，或在没有 Docker 的环境下运行，可以按照以下步骤手动部署。

3.1 安装系统依赖

安装 Redis：

# macOS
brew install redis && brew services start redis

# Ubuntu/Debian
sudo apt update && sudo apt install redis-server && sudo systemctl start redis-server

# CentOS/RHEL
sudo yum install redis && sudo systemctl start redis

安装 FFmpeg：

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# CentOS/RHEL
sudo yum install ffmpeg

3.2 安装后端 (Python)

进入项目根目录，创建并激活 Python 虚拟环境：

1
2
3

python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或 .\venv\Scripts\activate  # Windows

安装 Python 依赖：
1
pip install -r requirements.txt
配置环境变量：
同上，复制 env.example 为 .env 并填入你的 API_DASHSCOPE_API_KEY。

3.3 安装前端 (Node.js)

进入前端目录并安装依赖：
1
2
3
cd frontend
npm install
cd ..

3.4 启动各服务组件

你需要分别在三个终端窗口中启动后端 API 服务、Celery Worker 和前端开发服务器。

终端 1：启动后端 API 服务

1 2	source venv/bin/activate # 激活虚拟环境 python -m uvicorn backend.main:app --reload --port 8000

终端 2：启动 Celery Worker (处理任务)

1 2	source venv/bin/activate celery -A backend.core.celery_app worker --loglevel=info

终端 3：启动前端开发服务器
1
2
cd frontend
npm run dev
前端服务默认运行在 http://localhost:5173 (Vite 默认端口)。

4. 使用指南

4.1 创建和处理视频项目

访问前端界面 (http://localhost:3000 或 5173)。
点击 “新建项目”。
选择视频来源：
- YouTube / B 站链接：粘贴视频 URL，可选择使用浏览器 Cookie 以获取更高画质或会员视频。
- 本地文件上传：上传视频文件，并可选择配套的字幕文件。
点击 “开始下载” 或 “开始处理”，项目将进入任务队列。
在项目详情页，你可以通过 WebSocket 实时查看处理进度（如“下载中”、“AI 分析中”、“生成切片”等）。

4.2 管理结果

查看切片：处理完成后，项目详情页会列出所有 AI 生成的精彩视频片段。
编辑信息：你可以修改片段的标题、描述等信息。
创建合集：基于 AI 推荐或手动选择多个片段，生成一个合集视频。
下载：支持下载单个片段或整个合集。

5. 配置详解与故障排查

5.1 关键环境变量

在 .env 文件中，你可以配置以下关键项：

变量名	说明	示例
`API_DASHSCOPE_API_KEY`	必填。通义千问 API 密钥	`sk-...`
`API_MODEL_NAME`	使用的 AI 模型	`qwen-plus` (推荐) 或 `qwen-max`
`DATABASE_URL`	数据库连接字符串	`sqlite:///./data/autoclip.db`
`REDIS_URL`	Redis 连接地址	`redis://localhost:6379/0`
`LOG_LEVEL`	日志级别	`INFO` 或 `DEBUG`

5.2 常见问题解决

端口占用：使用 lsof -i :端口号 查找并 kill -9 PID 停止占用进程。
Redis 连接失败：确保 Redis 服务已启动 (redis-cli ping 应返回 PONG)。
YouTube 下载失败：尝试更新 yt-dlp (pip install --upgrade yt-dlp)，或为项目配置浏览器 Cookie (在创建项目时上传)。
AI 分析慢：检查网络连接，或在 .env 中更换为响应更快的模型（如 qwen-turbo）。
查看详细日志：所有日志位于 logs/ 目录下，分别是 backend.log, celery.log, frontend.log。

6. 生产环境部署建议

使用更健壮的数据库：将 DATABASE_URL 从 sqlite:///... 改为 PostgreSQL (如 postgresql://user:pass@localhost/autoclip)。
配置进程管理器：使用 systemd (Linux) 或 supervisor 来守护后端、Celery 和 Redis 进程，确保崩溃后自动重启。
反向代理：在生产环境中，建议使用 Nginx 作为反向代理，处理 HTTPS 并代理前端静态文件和后端 API 请求。

重要提醒：AutoClip 依赖于第三方 AI 服务（通义千问）和视频平台。使用时请遵守相关平台的服务条款，并合理配置 API 密钥以防止超额使用。本工具仅供学习和合法内容创作使用。