FramePack | Image to Video 项目需求设计实现分析

1. 项目概述

1.1 项目背景

FramePack 是一个基于图像到视频（I2V）生成的AI项目，实现了"下一帧预测模型"的视频生成架构。该项目由 Lvmin Zhang 开发，能够从单张图片生成高质量的长视频，支持长达60秒的视频生成。

1.2 项目定位

• 技术方向：深度学习视频生成
• 应用场景：内容创作、视频编辑、艺术生成
• 目标用户：创作者、研究人员、AI爱好者
• 核心价值：低显存、高质量、可配置的视频生成

1.3 核心特性

特性	描述
基于下一帧预测	采用渐进式生成策略，逐帧或逐段生成视频
上下文压缩	将输入上下文压缩到固定长度，使生成工作量与视频长度无关
内存优化	仅需6GB显存即可使用13B模型生成1分钟视频
TeaCache支持	可选的缓存加速机制，可提升约1.5-2倍速度
多种采样器	支持UniPC等先进采样器
Web UI界面	基于Gradio的友好的用户界面
实时预览	生成过程中可实时查看潜在空间预览

---

2. 系统架构设计

2.1 整体架构图

┌─────────────────────────────────────────────────────────────────┐
│                        用户交互层                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐  │
│  │  图像上传    │  │  提示词输入  │  │   参数配置面板       │  │
│  └──────────────┘  └──────────────┘  └──────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                        Web UI 层                                  │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │               demo_gradio.py (Gradio 应用)                │  │
│  │  - 用户输入验证  - 异步任务调度  - 进度实时反馈             │  │
│  └───────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                        业务逻辑层                                  │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌─────────────┐  │
│  │ 图像处理  │  │ 文本编码  │  │ 采样生成  │  │ 视频拼接    │  │
│  └───────────┘  └───────────┘  └───────────┘  └─────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                        核心模型层                                  │
│  ┌───────────────┐  ┌──────────────┐  ┌─────────────────────┐  │
│  │ HunyuanVideo  │  │   FramePack  │  │    CLIP Vision       │  │
│  │  Transformer  │  │   I2V Model  │  │    Encoder           │  │
│  └───────────────┘  └──────────────┘  └─────────────────────┘  │
│  ┌──────────────────┐  ┌──────────────────┐  ┌───────────────┐  │
│  │ Llama Text Encoder│  │ CLIP Text Encoder│  │ VAE          │  │
│  └──────────────────┘  └──────────────────┘  └───────────────┘  │
└─────────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────────┐
│                        支撑服务层                                  │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐  ┌─────────────┐  │
│  │ 内存管理  │  │ 设备管理  │  │ 缓存加速  │  │ 进度管理    │  │
│  │ memory.py │  │  CUDA     │  │ TeaCache  │  │ AsyncStream │  │
│  └───────────┘  └───────────┘  └───────────┘  └─────────────┘  │
└─────────────────────────────────────────────────────────────────┘

2.2 目录结构设计

d:/MyDrivers/update/framepack_cu126_torch26/
├── environment.bat              # 环境配置脚本
├── run.bat                      # 启动脚本
├── update.bat                   # 更新脚本
│
├── system/                      # 系统依赖目录
│   ├── git/                     # Git版本控制工具
│   └── python/                  # Python 3.10 环境
│       ├── Lib/                 # Python标准库
│       └── site-packages/       # 第三方库
│
└── webui/                       # Web UI主目录
    ├── demo_gradio.py           # 主Web UI程序（FramePack版本）
    ├── demo_gradio_f1.py        # F1版本的Web UI程序
    ├── requirements.txt         # Python依赖列表
    ├── README.md                # 项目文档
    ├── .gitignore              # Git忽略配置
    │
    ├── outputs/                # 输出视频存储
    ├── hf_download/            # Hugging Face模型缓存
    │   └── hub/                # 下载的模型仓库
    │       ├── models--hunyuanvideo-community--HunyuanVideo/
    │       ├── models--lllyasviel--flux_redux_bfl/
    │       └── models--lllyasviel--FramePackI2V_HY/
    │
    └── diffusers_helper/       # 辅助模块
        ├── hunyuan.py          # 混元模型相关函数
        ├── memory.py           # 内存管理工具
        ├── utils.py            # 通用工具函数
        ├── clip_vision.py      # CLIP视觉编码
        ├── bucket_tools.py     # 分辨率桶工具
        ├── thread_utils.py     # 线程工具
        ├── hf_login.py         # Hugging Face登录
        ├── dit_common.py       # DiT通用组件
        │
        ├── models/             # 模型定义
        │   └── hunyuan_video_packed.py
        │
        ├── pipelines/          # 采样管道
        │   └── k_diffusion_hunyuan.py
        │
        ├── k_diffusion/        # K-Diffusion采样器
        │   └── uni_pc_fm.py    # UniPC流匹配采样器
        │
        └── gradio/             # Gradio UI组件
            └── progress_bar.py

---

3. 功能需求分析

3.1 核心功能模块

3.1.1 图像到视频生成

功能描述：从单张静态图像生成动态视频

输入参数：

• 输入图像：支持 PNG、JPG、JPEG 等常见图像格式
• 提示词：文本描述，指导视频生成方向
• 负提示词：需要避免的内容
• 随机种子：控制生成结果的随机性
• 视频时长：1-60秒可调
• 采样步数：1-50步，影响质量和速度
• 潜在窗口大小：控制生成策略
• CFG Scale：分类器自由引导强度
• GS (Distilled CFG Scale)：蒸馏引导比例
• Rescale：重新缩放参数
• GPU内存保留：低显存模式下预留显存大小
• TeaCache开关：启用/禁用加速缓存
• MP4 CRF：输出视频质量参数

输出：

• MP4格式的视频文件
• 实时潜在空间预览
• 生成进度和描述

实现要点：

1. 图像预处理：调整尺寸、中心裁剪到标准分辨率桶
2. VAE编码：将图像编码到潜在空间
3. 文本编码：使用Llama和CLIP双编码器
4. 图像特征提取：使用CLIP Vision提取视觉特征
5. 渐进式生成：逐段生成潜在帧
6. VAE解码：将潜在空间解码为像素
7. 视频拼接：使用软连接平滑过渡

3.1.2 实时进度预览

功能描述：在生成过程中实时显示进度和预览

功能点：

• 潜在空间预览：显示当前生成的潜在帧（快速解码）
• 进度条：百分比可视化
• 进度描述：文本形式的当前状态
• 支持用户中断：随时停止生成

实现方式：

• 使用 AsyncStream 实现异步通信
• 快速解码使用 vae_decode_fake() 跳过完整VAE
• Gradio 组件实时更新

3.1.3 内存优化管理

功能描述：根据显卡显存自动优化模型加载策略

策略：

• 高显存模式（>60GB）：

  • 所有模型常驻GPU
  • 最快速度
  • 无需模型卸载

• 低显存模式（6-60GB）：

  • 使用 DynamicSwapInstaller 动态加载
  • 按需加载和卸载模型
  • 保持指定的预留显存
  • VAE启用分片和瓦片处理

实现技术：

1. 动态交换：比Hugging Face官方实现快3倍
2. VAE分片：大特征图分块处理
3. VAE瓦片：空间分块减少峰值显存
4. 模型卸载：及时释放不需要的模型

3.1.4 加速优化

功能描述：提供多种加速策略提升生成速度

技术方案：

1. TeaCache加速：

   • 原理：跳过变化小的采样步骤
   • 加速比：1.5x-2.1x
   • 配置：rel_l1_thresh=0.15
   • 权衡：轻微质量损失

2. 注意力优化：

   • Flash Attention：快速注意力实现
   • Memory Efficient SDP：内存高效SDP
   • cuDNN SDP：NVIDIA优化实现
   • Xformers：第三方加速库

3. 采样器优化：

   • UniPC：自研流匹配采样器
   • 支持多阶预测和校正
   • 比传统采样器更高效

3.1.5 分辨率自适应

功能描述：自动调整输入图像到最接近的标准分辨率

分辨率桶（640基准）：

• (416, 960), (448, 864), (480, 832), (512, 768)
• (544, 704), (576, 672), (608, 640), (640, 608)
• (672, 576), (704, 544), (768, 512), (832, 480)
• (864, 448), (960, 416)

实现：

• find_nearest_bucket() 函数计算最近距离
• 保持宽高比或调整到标准比例
• 避免非标准分辨率导致的效率问题

3.2 Web界面功能

3.2.1 图像上传组件

• 支持拖拽上传
• 图像预览
• 自动格式验证

3.2.2 文本输入组件

• 提示词输入框（多行）
• 负提示词输入框
• 快速提示词示例数据集

3.2.3 参数配置面板

• 滑块：连续参数调整
• 数字框：精确数值输入
• 复选框：开关选项
• 下拉框：离散选项

3.2.4 输出展示区

• 视频播放器：MP4播放
• 图像预览：潜在空间可视化
• 进度条：HTML渲染的进度条
• 状态描述：Markdown格式文本

3.2.5 控制按钮

• Start Generation：开始生成
• End Generation：中断生成

---

4. 技术栈设计

4.1 深度学习框架

库	版本	用途
PyTorch	2.7.1+cu126	核心深度学习框架
torchvision	0.22.1+cu126	图像处理工具
torchaudio	2.7.1+cu126	音频处理工具
diffusers	0.33.1	扩散模型库
transformers	4.46.2	Transformer模型库
accelerate	1.6.0	分布式训练和推理加速

4.2 模型架构

文本编码：

• LlamaModel：主文本编码器（HunyuanVideo）
• CLIPTextModel：辅助文本编码器

图像编码：

• SiglipVisionModel：CLIP Vision编码器
• SiglipImageProcessor：图像预处理

视频生成：

• HunyuanVideoTransformer3DModelPacked：3D变换器
• AutoencoderKLHunyuanVideo：混元视频VAE

4.3 Web UI技术

• Gradio 5.23.0：Web界面框架
• HTML/CSS：自定义样式
• JavaScript：动态更新

4.4 图像视频处理

库	版本	用途
Pillow	11.1.0	图像处理
opencv-contrib-python	最新	计算机视觉
av	12.1.0	音视频编解码
ffmpy	-	FFmpeg封装

4.5 数值计算

库	版本	用途
NumPy	1.26.2	数值计算
SciPy	1.12.0	科学计算
einops	-	张量操作
torchsde	0.2.6	随机微分方程

4.6 其他依赖

• safetensors：安全张量存储
• sentencepiece 0.2.0：分词工具
• requests 2.31.0：HTTP请求

---

5. 数据流设计

5.1 生成流程数据流

┌─────────────┐
│ 输入图像    │ (H×W×3 numpy数组)
└──────┬──────┘
       ↓
┌─────────────────────────────┐
│ resize_and_center_crop      │ → 调整到标准分辨率桶
└──────┬──────────────────────┘
       ↓
┌─────────────────────────────┐
│ VAE Encode                  │ → 潜在空间 (C×T×H/8×W/8)
└──────┬──────────────────────┘
       ↓
┌─────────────────────────────┐
│ CLIP Vision Encode          │ → 图像视觉特征
└──────┬──────────────────────┘
       ↓
┌─────────────────────────────┐
│ Llama Encode (提示词)       │ → 文本向量 (512)
└──────┬──────────────────────┘
       ↓
┌─────────────────────────────┐
│ CLIP Encode (提示词)        │ → 池化向量
└──────┬──────────────────────┘
       ↓
┌─────────────────────────────┐
│ Transformer采样             │ → 逐段生成潜在帧
│  (UniPC采样器)              │
└──────┬──────────────────────┘
       ↓
┌─────────────────────────────┐
│ VAE Decode                  │ → 像素帧
└──────┬──────────────────────┘
       ↓
┌─────────────────────────────┐
│ soft_append_bcthw           │ → 视频拼接（平滑过渡）
└──────┬──────────────────────┘
       ↓
┌─────────────────────────────┐
│ save_bcthw_as_mp4           │ → MP4输出文件
└─────────────────────────────┘

5.2 渐进式生成策略

分段生成：

# 示例：24段生成
total_latent_sections = 24
latent_paddings = [3] + [2] * 21 + [1, 0]

# 含义：
# 第1段：padding=3  (跳过前3段)
# 第2-22段：padding=2 (跳过前2段)
# 第23段：padding=1 (跳过前1段)
# 第24段：padding=0 (不跳过)

历史管理：

• history_latents：存储已生成的潜在帧
• history_pixels：存储已解码的像素帧
• 重叠区域：使用软连接实现平滑过渡

5.3 异步通信数据流

Worker线程                    UI主线程
    │                            │
    │──('progress', data)──────→│ 更新进度条和预览
    │                            │
    │──('file', filename)───────→│ 显示输出视频
    │                            │
    │──('end', None)────────────→│ 重置界面状态
    │                            │
    │←──────────────────────────│
    │ 检查中断信号              │
    │                            │

---

6. 核心算法设计

6.1 FramePack架构原理

核心思想：压缩上下文到固定长度

传统方法问题：

• 计算量随视频长度线性增长
• 长视频需要极大显存
• 生成速度随长度下降

FramePack解决方案：

1. 上下文压缩：将历史帧压缩到固定长度
2. 滑动窗口：只关注近期上下文
3. 渐进式生成：逐段生成，实时输出

优势：

• 计算量与视频长度无关
• 支持任意长度视频
• 内存需求恒定

6.2 TeaCache加速算法

原理：

# 跟踪相邻步骤的潜在空间变化
rel_l1_dist = norm(x_t - x_{t-1}) / norm(x_{t-1})

# 如果变化小于阈值，跳过计算
if accumulated_rel_l1 < rel_l1_thresh:
    skip = True
else:
    accumulated_rel_l1 = 0
    skip = False

阈值函数：

# 多项式拟合的阈值
rel_l1_thresh = 0.15  # 提供2.1x加速
# 可调节：0.1-0.2范围

效果：

• 速度提升：1.5x-2.1x
• 质量影响：细节可能略有损失
• 适用场景：快速预览

6.3 UniPC采样器

全称：Unified Predictor-Corrector

算法特点：

1. 流匹配：基于Flow Matching的扩散采样
2. 多阶预测：使用历史预测提高精度
3. 校正步骤：对预测结果进行校正
4. 变体支持：bh1, bh2 两种模式

核心代码：

class FlowMatchUniPC:
    def __init__(self, order=3, variant='bh1'):
        self.order = order      # 预测阶数
        self.variant = variant  # 变体类型
    
    def step(self, x, t, model):
        # 预测步骤
        x_pred = self.predict(x, t, model)
        
        # 校正步骤
        x_corrected = self.correct(x_pred, t, model)
        
        return x_corrected

6.4 动态交换算法

问题：Hugging Face的sequential offload太慢

解决方案：DynamicSwapInstaller

原理：

# 修改模块的__getattr__方法
def __getattr__(self, name):
    # 按需加载模块
    if not loaded:
        load_to_gpu()
    
    # 正常访问
    return super().__getattr__(name)

优势：

• 速度快3倍
• 无需预定义卸载策略
• 自动管理

---

7. 接口设计

7.1 Web UI接口

7.1.1 启动参数

python demo_gradio.py [OPTIONS]

选项:
  --share              创建公网链接
  --server IP          监听地址 (默认: 0.0.0.0)
  --port PORT          监听端口
  --inbrowser          自动打开浏览器

常用启动方式：

# Windows桌面
python demo_gradio.py --server 127.0.0.1 --inbrowser

# Linux服务器
python demo_gradio.py --server 0.0.0.0

# 公网访问
python demo_gradio.py --share

7.1.2 Gradio界面组件

# 输入组件
input_image = gr.Image(label="Input Image", type="numpy")
prompt = gr.Textbox(label="Prompt", lines=3)
n_prompt = gr.Textbox(label="Negative Prompt", lines=2)

# 参数组件
use_teacache = gr.Checkbox(label="Use TeaCache", value=True)
seed = gr.Number(label="Seed", value=0, precision=0)
total_second_length = gr.Slider(1, 60, value=4, label="Video Length (s)")
steps = gr.Slider(1, 50, value=15, step=1, label="Sampling Steps")
gs = gr.Slider(1, 30, value=10, label="Distilled CFG Scale")
gpu_memory_preservation = gr.Slider(0, 48, value=6, label="GPU Memory (GB)")
mp4_crf = gr.Slider(0, 51, value=18, label="MP4 CRF (Quality)")

# 输出组件
preview_image = gr.Image(label="Preview", visible=False)
result_video = gr.Video(label="Result")
progress_bar = gr.HTML("")
progress_desc = gr.Markdown("")

# 按钮组件
start_button = gr.Button("Start Generation", variant="primary")
end_button = gr.Button("End Generation", variant="stop")

7.2 内部API

7.2.1 worker函数

def worker(
    input_image: np.ndarray,      # 输入图像 (H×W×3)
    prompt: str,                  # 提示词
    n_prompt: str,                # 负提示词
    seed: int,                    # 随机种子
    total_second_length: int,     # 视频长度(秒)
    latent_window_size: int,      # 潜在窗口大小
    steps: int,                   # 采样步数
    cfg: float,                   # CFG Scale
    gs: float,                    # Distilled CFG Scale
    rs: float,                    # Rescale参数
    gpu_memory_preservation: int, # GPU内存保留(GB)
    use_teacache: bool,           # TeaCache开关
    mp4_crf: int,                 # MP4质量参数
) -> None:
    """
    执行视频生成任务
    通过stream.output_queue推送进度
    """

7.2.2 通信协议

# 进度更新消息
stream.output_queue.push((
    'progress',
    (preview_image, description, progress_html)
))

# 文件完成消息
stream.output_queue.push((
    'file',
    output_filename
))

# 结束消息
stream.output_queue.push((
    'end',
    None
))

7.3 模型接口

7.3.1 文本编码

def encode_prompt_conds(
    text: str,
    text_encoder: LlamaModel,
    tokenizer: LlamaTokenizerFast,
    text_encoder_2: CLIPTextModel,
    tokenizer_2: CLIPTokenizer,
    device: torch.device,
) -> tuple:
    """
    编码提示词
    
    返回:
        prompt_embeds: Llama编码的向量 (1×512×4096)
        pooled_prompt_embeds: CLIP池化向量 (1×768)
    """

7.3.2 VAE编码/解码

def vae_encode(
    image: torch.Tensor,
    vae: AutoencoderKLHunyuanVideo,
    device: torch.device,
) -> torch.Tensor:
    """
    编码图像到潜在空间
    """

def vae_decode(
    latents: torch.Tensor,
    vae: AutoencoderKLHunyuanVideo,
    device: torch.device,
) -> torch.Tensor:
    """
    解码潜在空间到像素
    """

7.3.3 CLIP Vision编码

def hf_clip_vision_encode(
    image: torch.Tensor,
    feature_extractor: SiglipImageProcessor,
    image_encoder: SiglipVisionModel,
    device: torch.device,
) -> torch.Tensor:
    """
    编码图像视觉特征
    
    返回:
        img_features: 图像特征向量
    """

---

8. 配置设计

8.1 环境配置

environment.bat：

set DIR=%~dp0system
set PATH=%DIR%\git\bin;%DIR%\python;%DIR%\python\Scripts;%PATH%
set PY_LIBS=%DIR%\python\Scripts\Lib;%DIR%\python\Scripts\Lib\site-packages
set PY_PIP=%DIR%\python\Scripts
set SKIP_VENV=1
set PIP_INSTALLER_LOCATION=%DIR%\python\get-pip.py

8.2 模型配置

模型路径：

os.environ['HF_HOME'] = './hf_download'

# 文本编码器
text_encoder = LlamaModel.from_pretrained(
    "hunyuanvideo-community/HunyuanVideo",
    subfolder='text_encoder'
)

# VAE
vae = AutoencoderKLHunyuanVideo.from_pretrained(
    "hunyuanvideo-community/HunyuanVideo",
    subfolder='vae'
)

# Transformer
transformer = HunyuanVideoTransformer3DModelPacked.from_pretrained(
    'lllyasviel/FramePackI2V_HY'
)

8.3 精度配置

transformer.to(dtype=torch.bfloat16)      # 主模型
vae.to(dtype=torch.float16)              # VAE
text_encoder.to(dtype=torch.float16)     # 文本编码器
text_encoder_2.to(dtype=torch.float16)   # CLIP编码器
image_encoder.to(dtype=torch.float16)    # 图像编码器

# 高质量输出
transformer.high_quality_fp32_output_for_inference = True

8.4 显存配置

自动检测：

free_mem_gb = get_cuda_free_memory_gb(gpu)
high_vram = free_mem_gb > 60

低显存模式：

# VAE优化
vae.enable_slicing()   # 分片处理
vae.enable_tiling()    # 瓦片处理

# 动态交换
DynamicSwapInstaller.install_model(transformer, device=gpu)
DynamicSwapInstaller.install_model(text_encoder, device=gpu)

高显存模式：

# 所有模型常驻GPU
text_encoder.to(gpu)
text_encoder_2.to(gpu)
image_encoder.to(gpu)
vae.to(gpu)
transformer.to(gpu)

8.5 TeaCache配置

# 初始化
transformer.initialize_teacache(
    num_steps=steps,
    rel_l1_thresh=0.15,  # 阈值
    reset_step_num_along=True,
)

# 启用/禁用
if use_teacache:
    transformer.enable_teacache()
else:
    transformer.disable_teacache()

---

9. 性能优化设计

9.1 内存优化

技术	效果	实现
DynamicSwap	减少3倍交换时间	memory.py
VAE分片	降低峰值显存	vae.enable_slicing()
VAE瓦片	降低峰值显存	vae.enable_tiling()
bfloat16	减少显存占用	transformer.to(bfloat16)
TeaCache	跳过重复计算	initialize_teacache()

9.2 速度优化

技术	加速比	适用场景
TeaCache	1.5x-2.1x	快速预览
Flash Attention	1.5x-2x	现代GPU
UniPC采样器	比DDIM快	推荐使用
GPU自动检测	最优配置	自动适应

9.3 质量优化

技术	效果	配置
高质量输出	减少量化误差	high_quality_fp32_output
更多采样步数	提升细节	steps=15-25
合适的CFG	平衡引导	cfg=4-8
分辨率桶	避免缩放损失	find_nearest_bucket()

---

10. 部署设计

10.1 系统要求

硬件要求：

• GPU：NVIDIA GPU (支持CUDA 12.6)
• 显存：最低6GB，推荐12GB+
• 内存：16GB+
• 硬盘：50GB+ (含模型和缓存)

软件要求：

• 操作系统：Windows 10/11, Linux
• Python：3.10 (内置)
• Git (内置)
• CUDA：12.6 (PyTorch包中)

10.2 本地部署

# 1. 启动环境
call environment.bat

# 2. 进入webui目录
cd webui

# 3. 启动服务
python demo_gradio.py --server 127.0.0.1 --inbrowser

10.3 服务器部署

# 1. 配置环境
source environment.sh  # 或环境配置

# 2. 启动服务（后台运行）
nohup python demo_gradio.py --server 0.0.0.0 --port 7860 > server.log 2>&1 &

# 3. 查看日志
tail -f server.log

10.4 更新流程

# 执行更新脚本
update.bat

# 或手动更新
call environment.bat
cd webui
git pull

---

11. 扩展性设计

11.1 模块化架构

核心模块：

• diffusers_helper/：独立的辅助工具
• models/：模型定义，可替换
• pipelines/：采样管道，可扩展
• k_diffusion/：采样器，可添加新采样器

11.2 模型扩展

添加新模型：

# 在 models/ 目录创建新文件
# 继承基类并实现forward方法

from diffusers_helper.models.base import BaseModel

class NewModel(BaseModel):
    def __init__(self, config):
        super().__init__(config)
        # 初始化模型
    
    def forward(self, x, t, context):
        # 实现前向传播
        return output

11.3 采样器扩展

添加新采样器：

# 在 k_diffusion/ 目录创建新文件
# 实现采样器类

class NewSampler:
    def __init__(self, **kwargs):
        self.config = kwargs
    
    def step(self, model, x, t):
        # 实现采样步骤
        return x_next

11.4 Web UI扩展

添加新组件：

# 在 demo_gradio.py 中添加新组件
with gr.Blocks() as demo:
    # 新增输入组件
    new_input = gr.Textbox(label="New Input")
    
    # 修改处理函数
    def process_with_new(input_image, prompt, new_input, ...):
        # 处理新输入
        ...

---

12. 测试设计

12.1 功能测试

测试项	测试方法	预期结果
图像上传	上传不同格式图片	正确加载和预览
视频生成	生成1分钟视频	成功输出MP4
参数调整	调整各种参数	生成立即生效
中断功能	点击停止按钮	及时停止生成
内存模式	切换显存模式	自动适应配置

12.2 性能测试

指标	测试方法	目标值
生成速度	1分钟视频	<5分钟 (TeaCache)
显存占用	监控nvidia-smi	<指定预留值
TeaCache加速	对比开关速度	>1.5x
模型加载	首次加载时间	<1分钟

12.3 兼容性测试

测试环境	测试项
Windows 10	完整流程
Windows 11	完整流程
Linux (Ubuntu)	完整流程
不同GPU	RTX 3060, 4090等

---

13. 维护设计

13.1 日志管理

日志位置：

• 控制台输出：实时信息
• 模型下载：Hugging Face缓存
• 生成历史：outputs/目录

13.2 缓存管理

模型缓存：

• 位置：webui/hf_download/hub/
• 清理：删除不用的模型
• 更新：重新下载最新版本

输出缓存：

• 位置：webui/outputs/
• 命名：时间戳格式
• 管理：定期清理旧文件

13.3 错误处理

常见错误：

1. 显存不足

   • 解决：减少gpu_memory_preservation
   • 或使用更小的batch size

2. 模型加载失败

   • 检查网络连接
   • 手动下载模型到hf_download/

3. CUDA错误

   • 检查CUDA版本
   • 更新显卡驱动

---

14. 安全设计

14.1 输入验证

• 图像格式验证
• 文本长度限制
• 参数范围检查
• 防止注入攻击

14.2 资源限制

• 生成队列限制
• 超时机制
• 显存上限保护
• 硬盘空间检查

14.3 隐私保护

• 本地运行，无云传输
• 用户数据不上传
• 模型下载来自可信源
• 无恶意代码

---

15. 未来规划

15.1 短期目标

• 支持更多视频格式输出
• 优化TeaCache阈值自适应
• 添加批量生成功能
• 支持视频到视频生成

15.2 中期目标

• 支持多GPU并行
• 添加视频编辑功能
• 支持音频生成
• 优化Web界面交互

15.3 长期目标

• 实时视频生成
• 支持4K分辨率
• 多模型融合
• 云端API服务

---

16. 附录

16.1 关键文件路径

启动文件：

• d:/framepack_cu126_torch26/run.bat
• d:/framepack_cu126_torch26/environment.bat
• d:/framepack_cu126_torch26/update.bat

主程序：

• d:/framepack_cu126_torch26/webui/demo_gradio.py
• d:/framepack_cu126_torch26/webui/demo_gradio_f1.py

核心模块：

• webui/diffusers_helper/hunyuan.py
• webui/diffusers_helper/memory.py
• webui/diffusers_helper/utils.py
• webui/diffusers_helper/models/hunyuan_video_packed.py
• webui/diffusers_helper/pipelines/k_diffusion_hunyuan.py
• webui/diffusers_helper/k_diffusion/uni_pc_fm.py

16.2 依赖清单

详见 webui/requirements.txt

16.3 参考资料

• HunyuanVideo
• FramePack
• Diffusers
• Gradio

---

目前图生视频功能，虚拟内存需要100GB，动漫类型图片的预测效果好一些，效果图如下：

汽车更换颜色

小女孩表情变化

哪吒表情变化