WorldMem项目部署记录

一、环境与工具准备#

1. 安装Anaconda/Miniconda：官网下载默认路径安装，自动配置环境变量。
2. 安装Git：下载Git for Windows，勾选「Git Bash Here」选项（确保Git Bash支持wget命令，后续统一用Git Bash操作）。
3. 创建Conda环境：打开Anaconda Prompt，执行以下命令创建专属环境（避免依赖冲突）：

   1
   conda create -n worldmem python=3.10 -y

4. 激活Conda环境（Anaconda Prompt中）：

   1
   conda activate worldmem

5. 安装带CUDA的PyTorch（核心依赖，GPU加速必备）：

   1
   pip uninstall torch torchvision torchaudio -y  # 卸载可能存在的CPU版本
   2
   pip3 install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118

6. 验证CUDA生效：执行以下命令，输出True说明GPU适配成功：

   1
   python -c "import torch; print(torch.cuda.is_available())"

7. Git克隆项目代码：打开Git Bash（右键桌面→「Git Bash Here」），执行克隆命令：

   1
   cd /c/Users/13062/Desktop  # 切换到桌面目录
   2
   git clone https://github.com/zeqixiao/worldmem-video-demo.git  # 克隆项目

   克隆后项目路径：C:\Users\13062\Desktop\worldmem-video-demo\WorldMem（后续所有操作均基于此路径）。

二、Git Bash配置Conda环境（统一终端+激活环境）#

提示：所有后续操作（安装依赖、下载资源、执行脚本）均需在worldmem环境中进行，Git Bash默认不支持Conda激活，必须先配置，否则依赖安装、命令执行都会失效。

1. 配置Git Bash加载Conda脚本：
   • 右键项目文件夹（worldmem-video-demo\WorldMem）→「Git Bash Here」，打开Git Bash终端；
   • 执行以下命令创建并编辑配置文件：

     1
     touch ~/.bashrc  # 创建Conda配置文件
     2
     nano ~/.bashrc    # 打开编辑器

   • 在编辑器中粘贴以下内容（Conda脚本默认路径，若Anaconda安装路径修改需对应调整）：

     1
     source /c/Users/13062/anaconda3/etc/profile.d/conda.sh

   • 保存退出：按Ctrl+O→回车确认文件名→按Ctrl+X退出编辑器。
2. 生效配置并激活worldmem环境：
   • 执行以下命令加载配置：

     1
     source ~/.bashrc

   • 激活worldmem环境（终端开头显示(worldmem)即成功）：

     1
     conda activate worldmem

   • 验证环境：执行python --version，输出Python 3.10.x（与创建环境时指定版本一致），说明环境配置完成。

三、项目依赖安装（Conda环境内统一执行）#

前置条件：已在Git Bash中激活worldmem环境，所有依赖均安装在该环境内，不影响系统Python。

1. 切换到项目根目录：

   1
   cd /c/Users/13062/Desktop/worldmem-video-demo/WorldMem

2. 安装项目依赖：

   • 先安装requirements.txt（若项目包含该文件，一次性安装基础依赖）：

   1
   pip install -r requirements.txt

   • 按报错补充缺失依赖（运行项目时若提示「ModuleNotFoundError」，逐个安装以下核心依赖）：

     1
     pip install hydra-core lpips gradio wandb  # 核心功能依赖
     2
     pip install torchvision pillow numpy scipy opencv-python  # 数据处理依赖

3. 验证依赖安装：执行pip list | grep gradio（或其他依赖名），能看到对应版本即安装成功。

四、本地资源准备+代码修改#

1
# 1. 创建案例文件目录（项目根目录下）
2
mkdir -p assets/examples && cd assets/examples
3
# 2. 镜像站下载
4
wget https://hf-mirror.com/yslan/worldmem/resolve/main/assets/examples/case1.npz
5
wget https://hf-mirror.com/yslan/worldmem/resolve/main/assets/examples/case2.npz
6
wget https://hf-mirror.com/yslan/worldmem/resolve/main/assets/examples/case3.npz
7
wget https://hf-mirror.com/yslan/worldmem/resolve/main/assets/examples/case4.npz

1
import os
2
import requests
3
def download_assets_if_needed():
4
    asset_dir = "assets/examples"
5
    os.makedirs(asset_dir, exist_ok=True)
6
    cases = ["case1.npz", "case2.npz", "case3.npz", "case4.npz"]
7
    for case in cases:
8
        local_path = os.path.join(asset_dir, case)
9
        if os.path.exists(local_path):
10
            print(f"✅ 本地已找到 {case}，跳过下载")
11
            continue
12
        # 注释原下载逻辑（已手动下载，避免超时）
13
        # url = f"https://huggingface.co/spaces/yslan/worldmem/resolve/main/assets/examples/{case}"
14
        # resp = requests.get(url, timeout=30)
15
        # with open(local_path, "wb") as f:
16
        #     f.write(resp.content)

1
# 1. 回到项目根目录，创建权重目录
2
cd /c/Users/13062/Desktop/worldmem-video-demo/WorldMem
3
mkdir -p assets/checkpoints && cd assets/checkpoints
4
# 2. 镜像站下载权重文件
5
wget https://hf-mirror.com/zeqixiao/worldmem_checkpoints/resolve/main/diffusion_only.ckpt
6
wget https://hf-mirror.com/zeqixiao/worldmem_checkpoints/resolve/main/vae_only.ckpt
7
wget https://hf-mirror.com/zeqixiao/worldmem_checkpoints/resolve/main/pose_prediction_model_only.ckpt

1
diffusion_path: assets/checkpoints/diffusion_only.ckpt
2
vae_path: assets/checkpoints/vae_only.ckpt
3
pose_prediction_path: assets/checkpoints/pose_prediction_model_only.ckpt

五、首次启动app.py（界面成功，视频生成功能缺失）#

1. 启动命令（Git Bash中，已激活worldmem环境，项目根目录下）：

   1
   python app.py

2. 运行现象：
   • 终端日志正常输出「✅ 本地已找到 case1.npz」「🚀 初始化设备: cuda」「✅ 所有模型切换到eval模式」；
   • 浏览器自动弹出http://127.0.0.1:7860，成功进入Gradio界面，可选择场景、输入动作序列；
   • 点击「🎬 Generate!」按钮后，界面卡住无视频输出，终端无额外日志（无报错）。
3. 产生问题原因：视频生成依赖ffmpeg工具进行帧序列转MP4格式，本地未安装ffmpeg，项目无法调用该工具，导致视频生成功能加载失败。
4. 关闭项目：按Ctrl+C终止终端进程，关闭浏览器。

六、ffmpeg下载与安装配置（补全视频生成依赖）#

七、重新启动app.py（视频生成加载成功，内存不足失败）#

1. 启动命令（新打开的Git Bash中，项目根目录下）：

   1
   python app.py

2. 运行现象：
   • 终端日志正常初始化，视频生成组件加载成功（终端显示「ffmpeg相关初始化日志」）；
   • 加载diffusion_model权重（3605MB）时，终端卡住，随后输出「Segmentation fault」，进程终止；
   • 任务管理器显示：CPU内存占用飙升至15.0GB+（总物理内存15.22GB），剩余可用内存不足200MB，触发内存溢出。
3. 问题原因：ffmpeg安装后，视频生成组件初始化增加了内存占用，叠加3.6GB的模型权重加载，16GB物理内存不足以承载，导致段错误。

八、训练脚本执行#

1. 补充训练依赖（若之前未安装）：

   1
   pip install wandb  # 训练日志监控依赖

2. 修复训练脚本配置：打开项目根目录下train_stage_1.sh文件，将algorithm.metrics=[lpips,psnr]改为+algorithm.metrics=[lpips,psnr]（适配Hydra配置语法，避免报错）。
3. 执行训练脚本（Git Bash中，项目根目录下）：

   1
   sh train_stage_1.sh

   （注：若内存充足，脚本会正常启动训练；若内存不足，会出现与启动app.py类似的内存溢出报错）

九、Git Bash环境常用命令速查表#

十、核心问题与解决方案汇总（按遇到顺序排列）#

十一、项目核心用途总结#

WorldMem 是一个「基于动作交互的3D世界模拟与长视频生成工具」，核心价值是解决“单张场景图→上下文连贯长视频”的创作痛点，具体功能与场景如下：

1. 核心功能：
   • 6种预设场景（向日葵平原、沙漠、冰原等），支持任意场景作为初始帧；
   • 动作交互（W/A/S/D/Q/E等按键组合），可实现转向、移动、使用物品等操作；
   • 长视频生成：连续点击「Generate」扩展视频长度，自动维护场景3D结构、物体位置的一致性（新帧用红框标记）；
   • 模型训练：通过train_stage_1.sh脚本训练自定义模型，优化生成效果。
2. 应用场景：
   • 游戏开发：快速生成开放世界视频片段，无需手动建模动画；
   • 虚拟模拟：基于简单指令模拟虚拟环境视角移动与交互；
   • 内容创作：为动画、影视领域提供低成本场景扩展工具。

关键注意事项#

1. 流程逻辑优先级：必须先配置Git Bash的Conda环境，再安装依赖、下载资源——无环境则所有依赖安装、命令执行都会失效，这是最关键的前置步骤。
2. ffmpeg安装红线：路径必须无中文、无空格，环境变量必须指向bin目录，否则视频生成功能始终加载失败。
3. 内存是核心瓶颈：16GB物理内存仅能满足基础界面启动，视频生成+模型权重加载需≥32GB物理内存，或扩展20-40GB虚拟内存。
4. 终端统一原则：全程使用Git Bash操作，避免切换Anaconda Prompt/CMD导致环境不一致，减少报错概率。
5. 资源完整性：案例文件（4个.npz）和模型权重（3个.ckpt）必须完整下载，缺失任一文件会导致项目启动失败。