用HeyGem生成的视频保存在哪？outputs目录详解-开发者社区

用HeyGem生成的视频保存在哪？outputs目录详解

HeyGem数字人视频生成系统批量版WebUI，是很多内容创作者、企业培训师和AI应用开发者日常高频使用的工具。但一个看似简单却常被忽略的问题反复出现：我点下“开始生成”后，视频到底存在服务器哪个角落？为什么在Web界面能下载，但在文件系统里却找不到？更进一步——如果我想批量处理、自动归档、对接其他系统，或者排查生成失败的原因，就必须真正理解它的输出路径结构。

这篇文章不讲原理、不堆参数，只聚焦一个最务实的问题：HeyGem生成的视频，究竟存放在哪里？outputs/目录里每个子文件夹、每类文件的作用是什么？如何快速定位、安全清理、高效复用？全程基于你正在运行的这台服务器（如/root/workspace）的真实环境展开，所有路径均可直接ls验证，所有操作都经实测可执行。

1. 核心结论：默认输出路径与结构总览

HeyGem 的视频输出并非随意写入，而是遵循一套清晰、可预测、便于工程化管理的目录规则。所有成功生成的数字人视频，默认保存在项目根目录下的outputs/文件夹中，完整路径为：

/root/workspace/outputs/

注意：该路径与镜像文档中提到的运行日志路径/root/workspace/运行实时日志.log处于同一级目录，说明整个 HeyGem 实例是以/root/workspace为工作空间（workspace）启动的。这是理解所有路径关系的起点。

进入outputs/后，你会看到类似这样的结构：

$ ls -l /root/workspace/outputs/ total 12 drwxr-xr-x 3 root root 4096 Apr 5 14:22 batch_20250405_142217 drwxr-xr-x 3 root root 4096 Apr 5 15:33 batch_20250405_153302 drwxr-xr-x 2 root root 4096 Apr 5 16:01 single_20250405_160144

这里没有杂乱的.mp4文件平铺，也没有隐藏的临时目录——每一个以batch_或single_开头的文件夹，都对应一次完整的生成任务。命名中的时间戳（如20250405_142217）精确到秒，格式为YYYYMMDD_HHMMSS，让你一眼就能判断任务发生顺序和大致耗时。

这个设计有三个关键好处：

隔离性：不同任务的输出互不干扰，避免文件覆盖或命名冲突；
可追溯性：通过文件夹名即可反推操作时间，结合日志可精准定位问题；
可自动化：脚本可通过时间戳或前缀轻松筛选、移动、压缩特定批次。

2. outputs目录深度解析：每个子文件夹里有什么？

2.1 批量处理任务目录（batch_XXXXXX）

当你在 WebUI 中选择“批量处理模式”，上传多个视频并点击“开始批量生成”后，系统会创建一个batch_开头的文件夹。例如：

/root/workspace/outputs/batch_20250405_142217/

进入该目录，典型结构如下：

$ ls -l /root/workspace/outputs/batch_20250405_142217/ total 184520 -rw-r--r-- 1 root root 1234 Apr 5 14:22 audio_info.json -rw-r--r-- 1 root root 94371840 Apr 5 14:22 input_audio.mp3 drwxr-xr-x 2 root root 4096 Apr 5 14:22 input_videos/ drwxr-xr-x 2 root root 4096 Apr 5 14:22 output_videos/ -rw-r--r-- 1 root root 10240 Apr 5 14:22 processing_log.txt

2.1.1 关键子目录与文件说明

文件/目录	类型	说明	是否必需
`audio_info.json`	JSON 文件	记录音频元信息：采样率、声道数、时长（秒）、文件哈希值。用于校验音频一致性，防止中途替换。	是
`input_audio.mp3`	音频文件	你上传的原始音频副本（格式可能被转码为`.mp3`）。注意：它不是你上传的原文件名，而是统一重命名为`input_audio.xxx`。	是
`input_videos/`	目录	存放你上传的所有原始视频文件。文件名保留原始名称（如`teacher_front.mp4`,`product_demo.mov`），便于人工核对。	是
`output_videos/`	目录	核心产出目录：所有生成完成的数字人视频均存放于此。文件名格式为`<原始视频名>_heygem.mp4`（如`teacher_front.mp4_heygem.mp4`）。	是
`processing_log.txt`	文本文件	本次批量任务的详细处理日志：每条视频的开始/结束时间、处理耗时、是否成功、错误信息（如有）。比全局日志更聚焦，排错首选。	是

小技巧：若某段视频生成失败，先打开processing_log.txt，搜索其原始文件名，立刻看到报错详情（如“视频分辨率不支持”、“音频时长超限”），无需翻查全局日志。

2.2 单个处理任务目录（single_XXXXXX）

当你切换到“单个处理模式”，上传一个音频+一个视频并点击“开始生成”，系统会创建single_开头的文件夹。例如：

/root/workspace/outputs/single_20250405_160144/

其内部结构更简洁，但逻辑一致：

$ ls -l /root/workspace/outputs/single_20250405_160144/ total 92200 -rw-r--r-- 1 root root 1234 Apr 5 16:01 audio_info.json -rw-r--r-- 1 root root 47185920 Apr 5 16:01 input_audio.wav -rw-r--r-- 1 root root 47185920 Apr 5 16:01 input_video.mp4 -rw-r--r-- 1 root root 47185920 Apr 5 16:01 output_video.mp4 -rw-r--r-- 1 root root 2048 Apr 5 16:01 processing_log.txt

input_audio.wav和input_video.mp4：分别是你上传的音频和视频，文件名被标准化为固定名称，方便程序识别。
output_video.mp4：最终生成的数字人视频，无后缀_heygem，直接命名为output_video.mp4，这是与批量模式的关键区别。
其他文件作用同批量模式。

重要提醒：WebUI 界面中“生成结果”区域显示的缩略图和播放器，其数据源正是这些output_video.mp4或output_videos/*.mp4文件。UI 不是“虚拟渲染”，而是真实读取磁盘文件。这意味着——只要你不删文件，即使重启服务，历史记录依然可预览、可下载。

3. WebUI下载行为与文件系统的关系

很多用户疑惑：“我在界面上点了‘下载’，文件是从哪来的？为什么有时下载慢？” 这直接关联到outputs/目录的访问机制。

3.1 单个视频下载：直连文件系统

当你在“生成结果历史”中点击某个缩略图，再点击旁边的下载按钮（⬇），浏览器发起的请求路径实际是：

http://localhost:7860/file=/root/workspace/outputs/batch_20250405_142217/output_videos/teacher_front.mp4_heygem.mp4

Gradio 框架（HeyGem WebUI 底层）会将/file=后的绝对路径映射为可下载资源。整个过程不经过 Python 代码中转，不重新编码，就是纯粹的文件流传输。因此：

下载速度 = 你的服务器磁盘 I/O 速度 + 网络带宽；
若下载中断，重试即可，不影响源文件；
你可以直接用curl或wget模拟此请求，实现自动化下载。

3.2 批量打包下载：临时 ZIP 生成

点击“📦 一键打包下载”时，系统会执行以下动作：

扫描当前页所有已选中的output_videos/*.mp4文件；
在内存中构建 ZIP 流（不写入磁盘）；
将 ZIP 流直接返回给浏览器。

验证方法：执行打包后，立即运行ls -lt /root/workspace/outputs/，你会发现没有任何新的.zip文件出现在目录中。这证明 ZIP 是纯内存操作，安全且节省空间。

3.3 历史记录分页：文件系统即数据库

“生成结果历史”的分页功能（◀ 上一页 / 下一页 ▶）并非查询数据库，而是：

扫描/root/workspace/outputs/下所有batch_*和single_*文件夹；
按文件夹名中的时间戳倒序排列；
每页展示固定数量（如 10 个）文件夹的output_videos/内容。

这意味着：

清空outputs/目录 = 彻底清空 WebUI 历史记录；
手动移动某个batch_文件夹到其他位置 = 该任务从历史列表中消失；
你想永久保留某次任务？只需将其batch_文件夹复制到/backup/等安全路径。

4. 工程化实践：如何高效管理 outputs 目录？

理解结构只是第一步。作为部署者或运维人员，你需要一套可持续的管理策略。

4.1 安全清理：定期归档，避免磁盘爆满

HeyGem 生成的视频体积大（单个 1080p 视频常达 50–100MB），长期积累极易占满磁盘。推荐使用以下脚本自动清理：

#!/bin/bash # save as: /root/workspace/clean_outputs.sh OUTPUT_DIR="/root/workspace/outputs" # 保留最近7天的生成记录，其余全部移动到 backup find "$OUTPUT_DIR" -maxdepth 1 -type d -name "batch_*" -o -name "single_*" \ -mtime +7 -exec mv {} /root/workspace/backup/ \; # 可选：删除超过30天的 backup 内容 find "/root/workspace/backup/" -maxdepth 1 -type d -mtime +30 -exec rm -rf {} \;

赋予执行权限并加入定时任务：

chmod +x /root/workspace/clean_outputs.sh # 每天凌晨2点执行 echo "0 2 * * * /root/workspace/clean_outputs.sh" | crontab -

4.2 自动归档：按业务场景分类存储

若你为不同客户生成视频，可改造 HeyGem 启动脚本，在生成前自动创建带业务标签的子目录：

# 修改 start_app.sh 中的启动命令 # 原始：python launch.py # 改为： mkdir -p /root/workspace/outputs/client_a && \ PYTHONPATH=/root/workspace python launch.py --outputs-dir /root/workspace/outputs/client_a

这样所有输出将进入/root/workspace/outputs/client_a/batch_...，天然隔离。

4.3 故障排查：三步定位生成失败原因

当 WebUI 显示“生成失败”但无明确提示时，按此顺序检查：

看 WebUI 日志面板：底部滚动日志常有ffmpeg error或CUDA out of memory等关键线索；
查任务专属日志：进入对应batch_*/processing_log.txt，搜索ERROR或Traceback；
验输入文件：ls -lh batch_*/input_videos/确认视频是否存在；ffprobe batch_*/input_videos/*.mp4检查编码格式是否合规（如是否为 H.264）。

实战案例：某次批量任务中 3 个视频失败，processing_log.txt显示Error: video duration exceeds 300s。检查发现其中两个视频长达 8 分钟——这印证了文档中“建议单个视频不超过 5 分钟”的提示，问题根源一目了然。

5. 进阶思考：outputs 目录之外的关联路径

outputs/是主战场，但还有几个关联路径值得掌握，它们共同构成 HeyGem 的完整文件生态：

路径	用途	关联性
`/root/workspace/运行实时日志.log`	全局运行日志，记录服务启动、模型加载、HTTP 请求等。宏观状态看这里。	与`outputs/`并列，是诊断系统级问题的第一入口。
`/root/workspace/models/`	存放 HeyGem 使用的 AI 模型权重（如 Wav2Lip、GFPGAN）。模型更新、显存优化在此操作。	模型文件大小直接影响首次生成速度，与`outputs/`的 IO 性能形成资源竞争。
`/root/workspace/webui/`	Gradio WebUI 前端静态资源（HTML/CSS/JS）。自定义 UI、添加水印按钮在此修改。	若你想在下载前自动加水印，修改此处的前端逻辑，再调用后端 Python 脚本处理`outputs/`中的文件。
`/root/workspace/config.yaml`	系统配置文件，可设置默认输出路径、并发数、GPU 设备号等。高级定制的入口。	通过修改`output_dir: /data/heygem_outputs`，可将所有输出重定向到大容量挂载盘，彻底解决空间焦虑。