VideoAgent 一体化视频智能框架详细部署教程

VideoAgent 是一个集视频理解、编辑与生成于一体的智能体框架。您只需通过自然语言描述需求，它就能自动解析意图、规划工作流并调用相应工具，完成从视频摘要、智能剪辑到创意改编（如生成梗视频、音乐视频）的复杂任务。

📋 目录

  1. VideoAgent 是什么
  2. 系统要求与硬件准备
  3. 环境安装
  4. 模型下载与配置
  5. LLM API 配置
  6. 运行 VideoAgent
  7. 使用示例与功能展示
  8. 更新与卸载
  9. 常见问题排查

VideoAgent 是什么

VideoAgent 是一个基于多智能体协作的视频处理框架。它就像一个由 AI 驱动的导演团队，能够理解您的创作意图，并自动调度“编剧”、“剪辑”、“配音”等不同角色的 AI 来完成工作。

核心能力：

  • 视频理解与问答：能分析视频内容，回答相关问题并生成摘要。
  • 视频剪辑：支持电影片段剪辑、解说视频生成、视频概览制作。
  • 创意视频重制：能将素材重制为梗视频、音乐视频、跨文化喜剧等。
  • 自然语言交互：您只需用日常语言描述需求，无需学习复杂软件。

系统要求与硬件准备

基本要求

  • 操作系统：Linux 或 Windows
  • GPU 显存：至少 8GB（推荐，用于流畅运行本地模型）
  • Python 版本：3.10
  • 硬盘空间：至少 50GB（用于存放多个模型文件）
  • 网络：需访问 Hugging Face 下载模型，以及调用外部 LLM API

关键依赖

  • 核心 LLM：Claude 是必须的，用于驱动核心的“智能体图路由器”。同时可配置 DeepSeek、GPT、Gemini 等作为不同任务的后备模型。
  • 语音模型：根据您的需求，可能需要下载 CosyVoice、Fish-Speech、Seed-VC 等 TTS/VC 模型。
  • 视频/音频处理：FFmpeg、Whisper、ImageBind 等。

环境安装

1. 克隆仓库

1
2
git clone https://github.com/HKUDS/VideoAgent.git
cd VideoAgent

2. 创建并激活 Conda 环境

1
2
conda create --name videoagent python=3.10
conda activate videoagent

3. 安装系统级依赖 (FFmpeg 和 Pynini)

1
conda install -y -c conda-forge pynini==2.1.5 ffmpeg

如果在 Windows 上遇到问题，可尝试单独安装 FFmpeg 并添加到系统 PATH。

4. 安装 Python 依赖包

1
pip install -r requirements.txt

模型下载与配置

VideoAgent 的强大功能依赖于多个外部模型。您可以根据需要选择性下载。

1. 安装 Git LFS（用于下载大文件）

1
git lfs install

2. 进入工具目录并下载对应模型

基础语音与合成模型 (推荐，支持多数视频创作功能):

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
# CosyVoice - 用于语音合成
cd tools/CosyVoice
huggingface-cli download PillowTa1k/CosyVoice --local-dir pretrained_models

# Fish-Speech - 用于TTS（如小明剑魔风格）
cd ../fish-speech
huggingface-cli download fishaudio/fish-speech-1.5 --local-dir checkpoints/fish-speech-1.5

# Seed-VC - 用于声音转换
cd ../seed-vc
huggingface-cli download PillowTa1k/seed-vc --local-dir checkpoints

# DiffSinger - 用于AI音乐视频
cd ../DiffSinger
huggingface-cli download PillowTa1k/DiffSinger --local-dir checkpoints

# Whisper - 用于语音识别（字幕/转录）
cd ..
huggingface-cli download openai/whisper-large-v3-turbo --local-dir whisper-large-v3-turbo

3. 下载多模态理解模型 ImageBind

1
2
3
4
# 回到 tools 目录
mkdir -p .checkpoints
cd .checkpoints
wget https://dl.fbaipublicfiles.com/imagebind/imagebind_huge.pth

按需下载指引：下表列出了部分功能与其所需模型，您可以根据自己的项目需求选择下载。

功能类别 示例任务 所需模型
相声/脱口秀 英文脱口秀→中文相声 CosyVoice, Whisper, ImageBind
MAD TTS 小明剑魔风格梗视频 Fish-Speech
AI 音乐视频 音乐视频 (MAD SVC) DiffSinger, Seed-VC, Whisper, ImageBind
解说/新闻视频 科技新闻解说 CosyVoice, Whisper, ImageBind
视频问答/摘要 电影预告片分析 Whisper

LLM API 配置

VideoAgent 使用多个 LLM 处理不同环节，您需要配置 API 密钥。

1. 编辑配置文件
打开 VideoAgent/environment/config/config.yml 文件。

2. 填写 API 密钥和 Base URL

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
llm:
  # DeepSeek - 用于视频重制/TTS/脱口秀等
  deepseek_api_key: "your-deepseek-api-key"  
  deepseek_base_url: "https://api.deepseek.com/v1"

  # Claude - 必须，用于核心的 Agentic Graph Router
  claude_api_key: "your-claude-api-key"  
  claude_base_url: "https://api.anthropic.com/v1"

  # GPT - 用于视频编辑/概述/摘要/解说视频
  gpt_api_key: "your-openai-api-key"  
  gpt_base_url: "https://api.openai.com/v1"

  # Gemini - 用于生成视频字幕和细粒度理解
  gemini_api_key: "your-gemini-api-key"  
  gemini_base_url: "https://generativelanguage.googleapis.com/v1beta"

重要提示：

  • Claude API 是必须的，因为它是“智能体图路由器”的核心。
  • 您也可以在 VideoAgent/environment/config/llm.py 中调整具体使用的模型名称。

运行 VideoAgent

完成所有配置后，即可启动 VideoAgent。

1. 在终端中执行主程序

1
2
# 确保您在 VideoAgent 根目录下，且 conda 环境已激活
python main.py

2. 输入您的需求
程序启动后，控制台会提示：

1
User Requirement:

此时，您可以输入自然语言指令，例如：

示例需求 1 (视频编辑与配音)：

1
我需要基于一个现有视频，用原说话人的声音，但对话内容改为我指定的新台词，重新生成一个视频。视频画面保持不变。

示例需求 2 (创意视频生成)：

1
我有一个脱口秀脚本，想把它制作成专业视频。需要有好的喜剧节奏和观众反应效果，并用相关视频素材匹配，制作一个完整的脱口秀特辑。

3. 等待处理并查看结果
VideoAgent 会解析需求，自动规划工作流并调用相应模型。处理完成后，生成的视频文件会保存在项目指定目录中。

使用示例与功能展示

VideoAgent 支持多种视频创作模式，下表简要总结：

功能 描述 示例场景
电影剪辑 根据描述剪辑电影片段，调整节奏。 制作电影高光时刻混剪。
梗视频 (Meme) 结合流行文化与模板生成幽默短剧。 将一段演讲视频重制成网络梗。
音乐视频 (MV) 根据音乐生成或重制视频画面。 为歌曲生成AI MV或换声视频。
脱口秀/相声 跨语言、跨文化喜剧改编。 英文脱口秀转中文相声。
解说/新闻视频 根据文本或新闻生成带旁白的视频。 自动生成科技新闻简讯视频。
视频概述 生成电影或长视频的概要介绍。 为电影预告片生成看点总结。

更新与卸载

更新 VideoAgent

  1. 进入项目目录：cd VideoAgent
  2. 拉取最新代码：git pull
  3. 如有依赖更新，重新执行：pip install -r requirements.txt

卸载 VideoAgent

  1. （可选）删除整个项目目录：rm -rf VideoAgent
  2. 删除 Conda 环境（可选）：conda remove --name videoagent --all

常见问题排查

问题：运行 main.py 时报错缺少某个模型文件。

  • 解决：检查该功能对应的模型是否已按文档下载，并放置在正确的目录下。

问题：提示 API 密钥无效或连接失败。

  • 解决：确认 config.yml 中的 API 密钥正确且有效，并检查网络连接。

问题：显存不足 (CUDA Out of Memory)。

  • 解决：
    1. 确保 GPU 显存 ≥ 8GB。
    2. 关闭其他占用显存的程序。
    3. 尝试在配置中调整模型加载策略，或分步运行不同模块。

问题：FFmpeg 相关错误。

  • 解决：确认 FFmpeg 已正确安装，并已添加到系统 PATH 环境变量中。