Pixelle-Video 详细部署教程

Pixelle-Video 是一款 AI 全自动短视频引擎，只需输入一个主题，即可自动完成文案撰写、AI 配图生成、语音解说合成和视频合成。本教程将指导你完成从安装到生成第一个视频的全过程。

一、系统要求与准备工作

1.1 硬件要求

  • 操作系统：Windows 10/11、macOS 或 Linux (Ubuntu/Debian 推荐)
  • CPU：最低 2 核，推荐 4 核以上
  • 内存：最低 4 GB，推荐 8 GB 以上
  • 显卡 (可选)：有 NVIDIA GPU (4GB+ 显存) 可本地运行 ComfyUI 图像生成，实现完全免费。无显卡亦可，但需使用云端 API 服务。

1.2 必要的软件依赖

无论哪种安装方式，都需要先安装以下工具：

  1. Python 包管理器 uv：访问 uv 官方文档 安装。完成后在终端运行 uv --version 验证。
  2. 视频处理工具 ffmpeg：
    • macOS: brew install ffmpeg
    • Ubuntu/Debian: sudo apt update && sudo apt install ffmpeg
    • Windows: 从 ffmpeg.org 下载，解压后将 bin 目录添加到系统环境变量 PATH 中。
      完成后运行 ffmpeg -version 验证。

二、安装 Pixelle-Video

根据你的操作系统，有两种主要安装方式。

2.1 Windows 用户：一键整合包（最推荐）

这是为 Windows 用户准备的最便捷方式，无需安装 Python、uv 或 ffmpeg，解压即用。

  1. 访问项目 Release 页面或官方渠道，下载最新的 Windows 一键整合包。
  2. 将压缩包解压到本地文件夹（建议路径不含中文和空格）。
  3. 双击运行 start.bat 脚本。
  4. 浏览器会自动打开 http://localhost:8501，看到 Web 界面即表示启动成功。

2.2 macOS / Linux 用户：从源码安装

适合需要自定义或进行二次开发的用户。

  1. 克隆项目

    1
    2
    git clone https://github.com/ATH-MaaS/Pixelle-Video.git
    cd Pixelle-Video

  2. 启动 Web 界面（使用 uv，它会自动安装所有 Python 依赖）

    1
    uv run streamlit run web/app.py

    等待几秒后，浏览器会自动打开 http://localhost:8501。

三、首次使用配置

打开 Web 界面后，首次使用必须配置 AI 服务。点击左侧边栏的「⚙️ 系统配置」展开面板。

3.1 配置 LLM（大语言模型）

用于生成视频文案。

  • 方案一：使用免费/低成本云服务（推荐新手）
    1. 在 LLM 配置 区域的预设模型下拉菜单中，选择 “通义千问 (DashScope)”。
    2. 点击旁边的「🔑 获取 API Key」链接，注册并获取你的 API Key。
    3. 将 API Key 粘贴到对应输入框，Base URL 和 Model 会自动填充。
  • 方案二：使用本地 Ollama（完全免费，需自己部署 Ollama）
    1. 选择预设模型中的 “Ollama”。
    2. 确保本地 Ollama 服务已启动，并已下载好模型（如 qwen2.5）。
    3. Base URL 填写 http://localhost:11434，Model 填写你的模型名。

3.2 配置图像/视频生成服务（二选一）

选项 A：配置 ComfyUI 本地工作流（免费，推荐有显卡用户）

这是完全免费的方式，但需要你本地部署 ComfyUI。

  1. 在 ComfyUI / RunningHub 配置 中，将 ComfyUI URL 设置为你的本地地址，例如 http://127.0.0.1:8188。
  2. 点击「测试连接」确认服务可用。
  3. 项目 workflows/ 文件夹中已预置了 image_flux.json 等工作流，可以直接使用。

选项 B：配置直连 API 媒体模型（无需本地显卡）

如果你没有本地显卡，或希望使用效果更好的云端模型。

  1. 在 API 媒体模型配置 区域，选择你拥有的图像/视频生成服务供应商，例如 DashScope (通义万象)、OpenAI、Kling (可灵) 等。
  2. 填入对应的 API Key（或 Access Key/Secret Key）。
  3. Base URL 通常使用 WebUI 提供的默认地址即可。
  4. 启用代理：如果你需要使用本地代理（如 http://127.0.0.1:9090），可以在此处单独为每个供应商开启。
  5. 配置好后，在后续生成时，图像工作流选择 api/... 开头的选项（如 api/dashscope_image）。

说明：如果你配置了 ComfyUI，同时又配置了直连 API，在生成视频时的【视觉设置】→【图像生成】下拉菜单中，可以按需切换使用哪种方式。

3.3 保存配置

所有配置填写完毕后，务必点击「保存配置」按钮，使设置生效。

四、生成你的第一个视频

配置完成后，就可以开始生成了。界面采用三栏布局，按从左到右的顺序设置。

4.1 左侧栏：内容输入

  1. 生成模式：选择 “AI 生成内容”。
  2. 主题输入：在文本框中输入一个主题，例如 “为什么要养成阅读习惯”。
  3. 背景音乐 (BGM)：可选择“无 BGM”，或从内置音乐中选一个。

4.2 中间栏：语音与视觉设置

  1. 语音设置：
    • TTS 工作流：从下拉菜单选择一个语音合成工作流，例如 edge-tts（免费，需联网）或 index-tts（支持声音克隆）。
    • 参考音频（可选）：如果你选择了支持克隆的 TTS，可以上传一段参考音频。
    • 点击「预览语音」可测试效果。
  2. 视觉设置：
    • 图像生成：选择你配置好的图像工作流。如果使用 ComfyUI，选 image_flux.json；如果使用直连 API，选 api/dashscope_image 等。
    • 图像尺寸：保持默认 1024x1024 或根据需要调整。
    • 提示词前缀 (Prompt Prefix)：用英文描述你想要的图片风格，例如 Minimalist black-and-white illustration, simple sketch style。点击「预览风格」可测试。

4.3 右侧栏：生成与预览

  1. 点击 「🎬 生成视频」 按钮。
  2. 界面会显示实时进度：文案生成 → 配图生成 → 语音合成 → 视频合成。
  3. 生成完成后，右侧区域会自动播放视频预览，并显示文件大小、分镜数等信息。
  4. 生成的视频文件默认保存在项目目录的 output/ 文件夹中。

五、Docker 部署方式（可选）

对于熟悉 Docker 的用户，也可以使用 Docker Compose 快速启动。

  1. 确保系统已安装 Docker 和 Docker Compose。

  2. 在项目根目录下运行：

    1
    docker-compose up -d

  3. 首次启动会构建镜像，完成后访问 http://localhost:8501 即可。

注意：Docker 方式同样需要在 Web 界面中配置 LLM 和图像生成服务。

六、常见问题排查

问题 可能原因与解决方案
启动后无法访问 localhost:8501 检查防火墙是否放行 8501 端口。Windows 用户确保以管理员身份运行 start.bat。
LLM 配置后测试失败 1. 确认 API Key 正确且未过期。 2. 检查 Base URL 是否填写正确（注意有无 /v1 后缀）。 3. 确认网络能正常访问该 API 服务。
图像生成失败 1. 若使用 ComfyUI：确认 ComfyUI 服务已启动，且在「系统配置」中测试连接成功。 2. 若使用直连 API：确认 API Key 无误，并检查该供应商账户余额是否充足。 3. 查看终端运行日志中的详细错误信息。
视频合成后无声音 1. 确认 TTS 工作流配置正确且「预览语音」有声音。 2. 检查系统音量设置。 3. 尝试更换其他 TTS 工作流（如从 edge-tts 换成 index-tts）。
提示 ffmpeg not found 系统未正确安装 ffmpeg 或未将其添加到 PATH 环境变量。请重新安装并确认终端能执行 ffmpeg -version。

七、高级：自定义模板与工作流

Pixelle-Video 支持高度的自定义：

  • 视频模板：你可以在 templates/ 文件夹中创建自己的 HTML 模板，命名遵循 static_*.html（纯文字）、image_*.html（图片背景）、video_*.html（视频背景）的规范，即可在下拉菜单中看到。
  • AI 工作流：你可以将自定义的 ComfyUI 工作流（.json 文件）放入 workflows/ 文件夹，并在界面中选择使用。

至此，你已经完成了 Pixelle-Video 的部署并成功生成了第一个 AI 视频。