ViMax 新手部署与使用图文笔记

1. ViMax 是什么

ViMax 是一个面向 AI 视频创作的 Agentic Video Generation 项目。它把一个视频创作任务拆成多个环节，让大语言模型、图像生成模型、视频生成模型一起协作，完成从创意到视频产物的流程。

简单说，你可以给它一个想法、一段剧本，或者一段小说文本，让它帮助你完成：

• 故事扩写
• 角色设定
• 剧本规划
• 场景拆分
• 分镜设计
• 镜头描述
• 图像生成
• 视频片段生成
• 最终视频整理

2. 适合谁使用

ViMax 适合这些场景：

• 想把短创意扩展成视频脚本的人
• 想把剧本拆成镜头和分镜的人
• 想做 AI 短片、预告片、概念片的人
• 想研究多 Agent 视频生成流程的人
• 想搭建本地 AI 视频创作工作台的人

它不适合期待“输入一句话立刻稳定生成完整大片”的用户。它更像一个视频创作工作流框架，需要你配置模型服务，并对中间产物进行检查和调整。

3. 核心功能

3.1 Idea2Video

Idea2Video 用来把一个短想法扩展成视频。

例如输入：

一个宇航员在废弃月球基地里发现一封来自地球未来的信。

ViMax 会尝试生成故事、角色、脚本、场景、分镜、镜头描述，并继续衔接图像和视频生成。

3.2 Script2Video

Script2Video 用来处理已经写好的剧本。

它会尽量保留原剧本的结构和意图，把剧本拆成适合生成视频的镜头、角色、场景和素材任务。

3.3 Novel2Video

Novel2Video 用来处理更长的小说或章节文本。

它会先压缩长文本，再提取事件、角色和场景，适合把长叙事整理成可视化视频规划。

3.4 Web UI

Web UI 是最适合新手使用的入口。它可以：

• 新建和管理项目
• 与 ViMax Agent 对话
• 上传参考文件
• 查看中间产物
• 查看分镜和渲染状态
• 配置模型服务

3.5 TUI

TUI 是终端交互界面，适合熟悉命令行的用户。

4. 部署前准备

建议准备：

• Python 3.12 或更新版本
• Node.js 18 或更新版本
• npm
• Git
• 可用的大语言模型 API
• 可用的图像生成 API
• 可用的视频生成 API

推荐使用虚拟环境或 uv 管理依赖，避免影响系统里其他 Python 项目。

5. 推荐部署方式

项目官方推荐使用 uv 管理 Python 环境。下面是适合新手的通用部署流程。

5.1 获取源码

<code class="language-bash"># 从 GitHub 克隆 ViMax 项目源码。
git clone https://github.com/HKUDS/ViMax.git
# 进入 ViMax 项目目录。
cd ViMax
</code>

5.2 安装 Python 依赖

<code class="language-bash"># 使用 uv 按项目锁文件同步 Python 依赖。
uv sync
</code>

如果你还没有安装 uv，可以先查看 uv 官方安装文档，或使用 Python 虚拟环境手动安装依赖。新手更推荐 uv sync，因为它更容易复现项目锁定版本。

5.3 创建本地配置文件

<code class="language-bash"># 复制示例配置文件，生成只在本地使用的私有配置。
cp configs/agent.example.yaml configs/agent.local.yaml
</code>

Windows PowerShell 可以使用：

<code class="language-powershell"># 复制示例配置文件，生成只在本地使用的私有配置。
Copy-Item -LiteralPath "configsagent.example.yaml" -Destination "configsagent.local.yaml"
</code>

5.4 安装 Web UI 依赖

<code class="language-bash"># 进入 Web UI 子目录。
cd web
# 安装前端依赖。
npm install
</code>

5.5 启动 Web UI

<code class="language-bash"># 启动 ViMax Web UI。
npm run dev
</code>

启动后打开：

• http://127.0.0.1:4173

如果端口被占用，可以换一个端口：

<code class="language-bash"># 使用 4174 端口启动 Web UI。
VIMAX_WEB_PORT=4174 npm run dev
</code>

Windows PowerShell 可以使用：

<code class="language-powershell"># 设置 Web UI 端口为 4174。
$env:VIMAX_WEB_PORT = "4174"
# 启动 ViMax Web UI。
npm run dev
</code>

6. 模型配置方法

打开：

• configs/agent.local.yaml

通常需要配置三类模型服务。

示例结构：

<code class="language-yaml"># 配置大语言模型服务。
llm:
  # 填写模型服务提供商，例如 openai 或兼容 OpenAI 协议的服务。
  model_provider: openai
  # 填写你要使用的大语言模型名称。
  model: <YOUR_LLM_MODEL>
  # 填写模型服务的 API 地址。
  base_url: <YOUR_LLM_BASE_URL>
  # 填写大语言模型 API Key。
  api_key: <YOUR_API_KEY>

# 配置图像生成模型服务。
image:
  # 填写图像生成模型名称。
  model: <YOUR_IMAGE_MODEL>
  # 填写图像生成 API 地址。
  base_url: <YOUR_IMAGE_BASE_URL>
  # 填写图像生成 API Key。
  api_key: <YOUR_API_KEY>

# 配置视频生成模型服务。
video:
  # 填写视频生成模型名称。
  model: <YOUR_VIDEO_MODEL>
  # 填写视频生成 API 地址。
  base_url: <YOUR_VIDEO_BASE_URL>
  # 填写视频生成 API Key。
  api_key: <YOUR_API_KEY>
</code>

不要把真实 API Key 分享到公开笔记、截图、仓库或聊天记录里。

7. 新手使用流程

7.1 启动项目

先进入项目的 web 目录，然后运行：

<code class="language-bash"># 启动 Web UI。
npm run dev
</code>

浏览器打开：

• http://127.0.0.1:4173

7.2 创建项目

进入 Web UI 后，新建一个项目。项目名建议写清楚，例如：

• 月球基地短片
• 茶馆悬疑片
• 产品发布会广告
• 小说第一章可视化

7.3 输入创作需求

你可以输入一段自然语言描述，例如：

我想做一支 30 秒的科幻短片。主角是一名独自巡检的宇航员，他在月球基地发现一台仍在工作的旧通讯机，里面传来未来地球的求救信号。整体风格冷峻、孤独、电影感强。

7.4 检查中间产物

生成过程中不要只等最终视频，建议检查这些内容：

• 故事是否合理
• 角色是否一致
• 场景是否清楚
• 分镜是否可拍
• 镜头描述是否足够具体
• 参考图是否符合风格
• 视频片段是否需要重试

7.5 再执行渲染

当文本规划基本满意后，再继续生成图像和视频。这样可以减少无效 API 调用，也更容易控制成本。

8. 常见问题

8.1 页面打不开

先确认 Web 服务是否启动成功。

<code class="language-bash"># 在 web 目录下启动 Web UI。
npm run dev
</code>

如果默认端口被占用，换一个端口再启动。

8.2 Agent 没有反应

常见原因：

• 没有配置 configs/agent.local.yaml
• API Key 无效
• base URL 填错
• 模型名称填错
• 当前模型服务网络不可达
• 模型额度不足

8.3 图像或视频生成失败

常见原因：

• 图像或视频模型配置缺失
• API Key 没有对应权限
• 提示词触发服务限制
• 视频模型生成时间较长
• 当前服务限流或排队

8.4 生成结果不稳定

AI 视频生成通常需要多轮调整。建议：

• 先确认故事和脚本
• 再确认角色设定
• 再确认分镜
• 最后生成图像和视频
• 对不满意的镜头单独重试

9. 推荐提示词写法

尽量写清楚：

• 视频时长
• 风格
• 主角
• 场景
• 情绪
• 镜头节奏
• 画幅比例
• 是否需要旁白
• 是否需要字幕

示例：

请帮我制作一支 45 秒的赛博朋克风格短片。主角是一名夜班快递员，场景是雨夜高架桥和霓虹街区。故事要有明确起承转合，画面风格偏电影感，镜头节奏前慢后快，不要出现夸张卡通风。

10. 升级和维护建议

10.1 不要随便全局安装依赖

推荐把依赖放在项目自己的环境里，避免影响其他项目。

10.2 不要随便升级锁文件

如果项目提供了锁文件，优先按锁文件安装。直接安装最新版依赖可能导致导入路径、API 行为或测试结果变化。

10.3 定期备份配置

建议备份：

• configs/agent.local.yaml
• .vimax
• .working_dir

其中 .working_dir 通常保存项目生成的中间产物和视频结果。

10.4 不要公开 API Key

分享截图、笔记或仓库前，检查是否包含：

• API Key
• 私有 base URL
• 账号信息
• 本地路径
• 生成任务中的敏感素材

11. 一句话总结

ViMax 更像一个 AI 视频创作工作台，而不是一个简单的视频生成按钮。新手最推荐的使用方式是：先用 Web UI 让 Agent 规划故事、角色和分镜，确认中间产物后，再调用图像和视频模型生成最终素材。