Home › 快速开始

MER-Factory 入门指南

只需几分钟，即可启动并运行 MER-Factory。本指南将引导您完成安装过程和您的第一个情绪识别管道。

系统概要

先决条件

在安装 MER-Factory 之前，请确保您的系统上已安装以下依赖项：

1. FFmpeg 安装

视频和音频处理需要 FFmpeg。

macOS

brew install ffmpeg

Ubuntu/Debian

sudo apt update && sudo apt install ffmpeg

Windows

从 ffmpeg.org 下载

验证安装：

ffmpeg -version
ffprobe -version

2. OpenFace 安装

面部动作单元提取需要 OpenFace。

# 克隆 OpenFace 仓库
git clone https://github.com/TadasBaltrusaitis/OpenFace.git
cd OpenFace

# 遵循特定平台的构建说明
# Windows 平台下载好以后需要运行 download_models.ps1 来自动下载需要的模型
# 参见: https://github.com/TadasBaltrusaitis/OpenFace/wiki
注意： 构建 OpenFace 后，请记下 FeatureExtraction 可执行文件的路径（通常在 build/bin/FeatureExtraction）。您将在配置时需要它。

安装

1. 克隆仓库

git clone https://github.com/Lum1104/MER-Factory.git
cd MER-Factory

2. 设置 Python 环境

# 创建一个新的 conda 环境
conda create -n mer-factory python=3.12
conda activate mer-factory

# 安装依赖
pip install -r requirements.txt

3. 配置环境

# 复制环境文件示例
cp .env.example .env

编辑 .env 文件并填入您的设置：

# API 密钥 (可选 - 根据您偏好的模型选择)
GOOGLE_API_KEY=your_google_api_key_here
OPENAI_API_KEY=your_openai_api_key_here

# OpenFace 配置 (AU 和 MER 管道必需)
OPENFACE_EXECUTABLE=/absolute/path/to/OpenFace/build/bin/FeatureExtraction

# 可选: Ollama 本地模型配置
# OLLAMA_HOST=http://localhost:11434
重要提示： OPENFACE_EXECUTABLE 路径必须是绝对路径，并指向实际的可执行文件。

您的第一个管道

让我们运行您的第一个情绪识别管道！

1. 准备您的媒体文件

创建一个包含视频文件的测试目录：

mkdir test_input
# 将您的视频文件复制到 test_input/your_video.mp4

2. 运行 MER 管道

# 使用默认 Gemini 模型的基本 MER 管道
python main.py test_input/ output/ --type MER --silent

# 调整阈值
python main.py test_input/ output/ --type MER --threshold 0.8 --silent

3. 检查结果

# 查看生成的文件
ls output/
# your_video_merr_data.json - 包含完整的分析
# your_video_au_data.csv - 面部动作单元数据
# your_video.wav - 提取的音频
# your_video_peak_frame.jpg - 关键情绪时刻的帧

导出数据集

要导出数据集以进行整理或训练，请使用以下命令：

用于数据集整理

python export.py --output_folder "{output_folder}" --file_type {file_type.lower()} --export_path "{export_path}" --export_csv

用于训练

python export.py --input_csv path/to/csv_file.csv --export_format sharegpt

模型选项

MER-Factory 支持多种 AI 模型。根据您的需求进行选择：

Google Gemini (默认)

python main.py input/ output/ --type MER
  • 最适用于： 高质量的多模态分析
  • 需要： 在 .env 文件中配置 GOOGLE_API_KEY

OpenAI ChatGPT

python main.py input/ output/ --type MER --chatgpt-model gpt-4o
  • 最适用于： 先进的推理和视频分析
  • 需要： 在 .env 文件中配置 OPENAI_API_KEY

Ollama (本地模型)

# 首先，拉取模型
ollama pull llava-llama3:latest
ollama pull llama3.2

# 使用 Ollama 运行
python main.py input/ output/ --type MER \
  --ollama-vision-model llava-llama3:latest \
  --ollama-text-model llama3.2
  • 最适用于： 隐私保护、无 API 费用、异步处理
  • 需要： 本地安装 Ollama

Hugging Face 模型

python main.py input/ output/ --type MER --huggingface-model google/gemma-3n-E4B-it
  • 最适用于： 最新的研究模型、自定义实现
  • 注意： 自动单线程处理

管道类型

快速管道比较

管道 输入 输出 用例
MER 视频/图像 完整的情绪分析 完整的多模态数据集
AU 视频 面部动作单元 面部表情研究
Audio 视频 语音 + 音调分析 音频情绪识别
Video 视频 视觉描述 视频理解
Image 图像 图像情绪分析 静态情绪识别

命令示例

# 仅提取动作单元
python main.py video.mp4 output/ --type AU

# 仅进行音频分析
python main.py video.mp4 output/ --type audio

# 仅进行视频描述
python main.py video.mp4 output/ --type video

# 图像分析 (对于图像输入会自动检测)
python main.py ./images/ output/ --type image

# 使用自定义设置的完整 MER
python main.py videos/ output/ \
  --type MER \
  --threshold 0.9 \
  --peak-dis 20 \
  --concurrency 8 \
  --silent

测试您的安装

运行内置测试以验证一切正常：

# 测试 FFmpeg 集成
python test/test_ffmpeg.py your_video.mp4 test_output/

# 测试 OpenFace 集成
python test/test_openface.py your_video.mp4 test_output/

常见问题与解决方案

找不到 FFmpeg

症状： 与 ffmpeg 相关的 FileNotFoundError

解决方案：

  1. 验证 FFmpeg 是否已安装：ffmpeg -version
  2. 检查它是否在您的系统 PATH 中
  3. 在 Windows 上，将 FFmpeg 添加到系统 PATH

找不到 OpenFace 可执行文件

症状： 找不到 FeatureExtraction 可执行文件

解决方案：

  1. 验证 .env 中的路径是否为绝对路径
  2. 检查文件权限：chmod +x FeatureExtraction
  3. 手动测试：/path/to/FeatureExtraction -help

API 密钥错误

症状： 401 Unauthorized 错误

解决方案：

  1. 验证 .env 中的 API 密钥是否正确
  2. 检查是否有额外的空格或字符
  3. 确保您的 API 账户已启用计费

内存问题

症状： 处理大文件时出现内存不足错误

解决方案：

  1. 减少并发数：--concurrency 1
  2. 使用较小的视频文件进行测试
  3. 关闭其他占用大量内存的应用程序

后续步骤

现在您已经成功运行 MER-Factory，可以探索这些高级功能：

需要帮助？