简介这份资源面向希望将LivePortrait人像动画生成能力落地到本地工程的开发者提供基于onnxruntime推理的完整部署程序同时给出C与Python两套实现路径适合具备一定深度学习推理与工程集成经验、需要脱离原始框架依赖进行二次开发的技术人员。压缩包共14个文件约459KB包含4个cpp与3个h源文件构成C推理主流程2个py脚本负责Python侧调用与裁剪工具另附txt说明、md文档及mp4、jpg、png等示例素材便于对照验证效果。目录按cpp与python分模块组织涵盖人脸分析、裁剪与动画生成等关键环节可帮助读者快速理解模型加载、输入预处理与推理输出的完整链路。目前已有204人学习下载可作为人像动画项目集成与跨语言部署的参考起点。1. 拿到 liveportrait-onnxrun-main 之后先搞清楚它到底能跑出什么很多人第一次看到「使用 onnxruntime 部署 LivePortrait 人像动画生成C 和 Python程序」这个包第一反应是「又一个套壳 demo」。实际拆开看它给的是两套完整推理入口Python 侧用main.py串起裁剪、特征提取、动画生成C 侧用liveportrait.cppfaceanalysis.cpp把同一套 ONNX 模型跑在原生环境里。核心价值在于把 LivePortrait 原本偏研究向的 PyTorch 推理链路压成了 onnxruntime 能直接加载的图省掉了装 torch、配 CUDA 版本、处理算子不兼容这一整条血泪链。它适合两类人一类是想在 C 工程里嵌人像动画能力、又不想拖一个 PyTorch 运行时的嵌入式或桌面端开发者另一类是想拿 Python 快速验证效果、再决定要不要迁到 C 的算法落地人员。包里utils_crop.py、mask_template.png、d0.mp4、0.jpg这些文件说明作者已经把「输入一张图 一段驱动视频 → 输出动画」的最小闭环跑通了不是只丢几个模型文件让你自己猜。下面按「资源结构 → Python 跑通 → C 编译 → 避坑 → 进阶」的顺序拆。2. 资源结构与 onnxruntime 推理链路先看懂文件再动手2.1 目录里每个文件在推理链路里的位置拿到包先别急着pip install把目录树看一遍能省掉后面很多「文件找不到」的玄学问题。从项目正文给出的文件清单看结构大致是 Python 脚本和 C 源码平铺在根目录模型文件按 onnxruntime 惯例单独放。下面这张表是我按实际推理顺序整理的不是按字母序文件所属阶段作用utils_crop.py/utils_crop.cpp预处理人脸检测 对齐裁剪把任意输入图裁成模型要的尺寸faceanalysis.cpp/.h预处理C 侧的人脸分析对应 Python 的检测逻辑mask_template.png预处理裁剪时用的掩码模板保证不同图对齐一致0.jpg输入源人像提供外观和身份d0.mp4输入驱动视频提供表情和头部姿态liveportrait.cpp/.h推理C 主推理逻辑加载 ONNX 并串联各子模型main.py/main.cpp入口分别对应 Python 和 C 的调用入口CMakeLists.txt构建C 侧编译配置指定 onnxruntime 链接路径关键点utils_crop在两个语言里各有一份说明作者没有用 pybind 把 Python 逻辑暴露给 C而是各写各的。好处是 C 侧不依赖 Python 解释器坏处是两边预处理参数必须手动保持一致否则同一张图两边裁出来的脸不一样后面推理结果对不上。2.2 onnxruntime 和 onnx 的区别以及为什么这里选 onnxruntime热搜里常有人问「onnxruntime 和 onnx 区别」这个问题不搞清楚后面配环境必翻车。onnx 是模型格式标准只定义「图长什么样」onnxruntime 是执行引擎负责把这张图真正跑起来管内存分配、算子调度、后端选择CPU / GPU / 其他加速器。你手里.onnx文件是格式onnxruntime是跑它的库两者缺一不可。这个包选 onnxruntime 而不是直接上 PyTorch理由很实际LivePortrait 原版依赖一堆 torch 算子和特定版本换台机器就报undefined symbol转成 ONNX 后只要 onnxruntime 版本对得上Windows、Linux、甚至鲲鹏 920 这类 ARM 平台都能加载同一份模型。常见做法是先用onnxruntime的 Python 包验证模型能跑通再换 C API 做部署这样出问题能快速定位是模型问题还是编译问题。2.3 Python 侧最小验证三步跑通 main.py在动 C 之前先用 Python 确认模型和输入没问题这是最省时间的顺序。假设你已经装好 onnxruntime 和 opencv# 1. 安装最小依赖onnxruntime 选 CPU 版先验证逻辑 pip install onnxruntime opencv-python numpy # 2. 先单独跑裁剪确认人脸能检测到 python utils_crop.py 0.jpg mask_template.png # 3. 跑主流程源图 0.jpg 驱动视频 d0.mp4 python main.py 0.jpg d0.mp4utils_crop.py接收三个位置参数源图、掩码模板、输出路径具体参数名以脚本内argparse为准跑-h能看到。单独跑它的意义在于如果人脸检测这步就失败main.py报的错会很靠后你容易误以为是模型问题。main.py内部一般会依次调用裁剪、加载 ONNX session、逐帧推理、写视频。第一次跑建议把驱动视频换成很短的片段比如 2 秒先看输出有没有画面再上长视频。提示onnxruntime 首次加载模型会做图优化耗时明显比后续推理长别把第一次的慢当成卡死。3. C 侧编译与推理CMakeLists 和 onnxruntime 链接怎么配3.1 CMakeLists.txt 里必须盯死的三个变量C 侧翻车九成出在链接阶段而链接问题的根在CMakeLists.txt。这个包的 CMake 配置核心就三件事找到 onnxruntime 头文件、链接 onnxruntime 库、把liveportrait.cpp、faceanalysis.cpp、utils_crop.cpp、main.cpp一起编进可执行文件。典型配置长这样cmake_minimum_required(VERSION 3.10) project(liveportrait_onnx) set(CMAKE_CXX_STANDARD 17) # onnxruntime 根目录按你实际解压路径改 set(ONNXRUNTIME_DIR /path/to/onnxruntime) include_directories(${ONNXRUNTIME_DIR}/include) link_directories(${ONNXRUNTIME_DIR}/lib) add_executable(liveportrait main.cpp liveportrait.cpp faceanalysis.cpp utils_crop.cpp ) # Linux 下链接 onnxruntimeWindows 下是 onnxruntime.lib target_link_libraries(liveportrait onnxruntime)三个必须改对的地方ONNXRUNTIME_DIR指向你下载的 onnxruntime 发行包解压目录不是 pip 装的那个include_directories要能摸到onnxruntime_cxx_api.htarget_link_libraries的库名在 Linux 是libonnxruntime.so、Windows 是onnxruntime.lib写错就是cannot find -lonnxruntime。另外 C17 是硬要求onnxruntime 的 C API 用了不少现代特性降到 C11 会编译报错。3.2 编译命令与运行时动态库路径配好 CMake 后标准流程是mkdir build cd build cmake .. make -j4 # Linux 下运行时要把 so 路径加进去否则报找不到库 export LD_LIBRARY_PATH/path/to/onnxruntime/lib:$LD_LIBRARY_PATH ./liveportrait 0.jpg d0.mp4make -j4的-j4是按 CPU 核数并行编译核多可以调大。最后那句export LD_LIBRARY_PATH是 Linux 下的高频坑编译过了不代表能跑运行时动态链接器找不到libonnxruntime.so就直接退出。Windows 下对应的是把onnxruntime.dll放到 exe 同目录或者加进PATH。main.cpp的入参和 Python 侧保持一致都是源图加驱动视频这样两边结果能直接对比。3.3 两边结果对不上时先查预处理Python 和 C 跑同一组输入输出如果明显不一样先别怀疑模型九成是预处理差异。utils_crop.py和utils_crop.cpp是两份独立实现缩放插值方式、归一化均值方差、裁剪框取整规则只要有一处不同裁出来的脸就有像素级偏移后面动画自然对不上。排查方法是把两边裁剪后的中间图都存下来肉眼比一下或者算个像素差。常见做法是在 C 侧临时加一段写图代码把裁剪结果 dump 成 png和 Python 的输出并排看。4. 避坑与常见问题这几处我踩过4.1 现象ImportError: DLL load failed或libonnxruntime.so not found原因onnxruntime 的 Python 包和 C 库是两套东西pip 装的成功不代表 C 能链接反过来 C 配好了Python 环境里可能根本没装 onnxruntime。另外 Windows 上缺 Visual C Redistributable 也会导致 DLL 加载失败。解决Python 侧pip install onnxruntime单独装C 侧从官方发行包解压别指望 pip 的包能直接给 CMake 用。Windows 上先装一遍 Microsoft Visual C Redistributable这是很多 DLL 问题的后悔药。4.2 现象推理结果人脸错位或动画抖动严重原因mask_template.png没跟着源图一起传或者裁剪尺寸和模型输入尺寸不匹配。LivePortrait 对输入对齐很敏感模板掩码的作用就是固定对齐基准。解决确认utils_crop调用时掩码模板路径正确且模板尺寸和模型期望的输入分辨率一致。换源图时不要换模板模板是通用的对齐基准。4.3 现象C 编译报undefined reference to Ort::...原因target_link_libraries里库名写错或者link_directories路径不对链接器根本没找到 onnxruntime 库。解决确认ONNXRUNTIME_DIR/lib下确实有libonnxruntime.soLinux或onnxruntime.libWindows库名大小写和平台对应。用ldd ./liveportrait看运行时到底缺哪个库。4.4 现象驱动视频长一点就内存暴涨原因逐帧推理时没有及时释放中间张量或者一次性把整个视频读进内存。ONNX session 本身会占固定内存但每帧的输入输出张量如果不复用会累积。解决常见做法是复用输入输出 tensor别每帧新建视频用流式读取处理完一帧写一帧。长视频先切段跑确认内存稳定再上完整流程。4.5 现象换机器后同样的代码报算子不支持原因不同 onnxruntime 版本支持的算子集不同模型导出时用的 opset 版本如果高于运行时的支持上限加载就失败。解决统一 onnxruntime 版本Python 和 C 用同一个发行版本号。报错信息里一般会带不支持的算子名对着版本发布说明查。5. 进阶把单张图推理改成批量与自定义输出跑通最小闭环之后真正提效的是批量和输出控制。Python 侧改main.py时我一般会把推理循环抽出来让源图可以传一个目录驱动视频固定批量出结果。核心改动是别在循环里反复创建InferenceSessionsession 创建一次复用import onnxruntime as ort import os # session 只建一次这是批量提速的关键 sess ort.InferenceSession(liveportrait.onnx, providers[CPUExecutionProvider]) def run_one(src_path, drv_path, out_path): # 预处理、推理、后处理按原 main.py 逻辑走 ... return out_path src_dir portraits for name in os.listdir(src_dir): if name.lower().endswith((.jpg, .png)): run_one(os.path.join(src_dir, name), d0.mp4, fout_{name}.mp4)providers参数决定后端CPU 版写CPUExecutionProvider有对应加速环境再换。session 复用能省掉每次加载模型做图优化的开销批量场景下提速很明显。C 侧同理Ort::Session在liveportrait.cpp里创建一次main.cpp循环调用推理函数即可。输出控制上d0.mp4的帧率和输出帧率要对齐否则动画速度会变。常见做法是读驱动视频的CAP_PROP_FPS写输出时用同一个值。另外mask_template.png如果要做多套风格可以准备多个模板但每个模板都要和模型输入尺寸对齐别混用。验证是否真的跑对我的习惯是固定一组输入Python 和 C 各跑一遍把输出视频抽同一帧做像素对比差异在可接受范围内才算两边一致。从那以后我每次换 onnxruntime 版本或者换机器都强制走一遍这个对比流程省得后面在业务代码里查半天。希望帮到你。本文还有配套的精品资源点击获取 onnxruntime部署LivePortrait人像动画：C++与Python双语言实战
简介这份资源面向希望将LivePortrait人像动画生成能力落地到本地工程的开发者提供基于onnxruntime推理的完整部署程序同时给出C与Python两套实现路径适合具备一定深度学习推理与工程集成经验、需要脱离原始框架依赖进行二次开发的技术人员。压缩包共14个文件约459KB包含4个cpp与3个h源文件构成C推理主流程2个py脚本负责Python侧调用与裁剪工具另附txt说明、md文档及mp4、jpg、png等示例素材便于对照验证效果。目录按cpp与python分模块组织涵盖人脸分析、裁剪与动画生成等关键环节可帮助读者快速理解模型加载、输入预处理与推理输出的完整链路。目前已有204人学习下载可作为人像动画项目集成与跨语言部署的参考起点。1. 拿到 liveportrait-onnxrun-main 之后先搞清楚它到底能跑出什么很多人第一次看到「使用 onnxruntime 部署 LivePortrait 人像动画生成C 和 Python程序」这个包第一反应是「又一个套壳 demo」。实际拆开看它给的是两套完整推理入口Python 侧用main.py串起裁剪、特征提取、动画生成C 侧用liveportrait.cppfaceanalysis.cpp把同一套 ONNX 模型跑在原生环境里。核心价值在于把 LivePortrait 原本偏研究向的 PyTorch 推理链路压成了 onnxruntime 能直接加载的图省掉了装 torch、配 CUDA 版本、处理算子不兼容这一整条血泪链。它适合两类人一类是想在 C 工程里嵌人像动画能力、又不想拖一个 PyTorch 运行时的嵌入式或桌面端开发者另一类是想拿 Python 快速验证效果、再决定要不要迁到 C 的算法落地人员。包里utils_crop.py、mask_template.png、d0.mp4、0.jpg这些文件说明作者已经把「输入一张图 一段驱动视频 → 输出动画」的最小闭环跑通了不是只丢几个模型文件让你自己猜。下面按「资源结构 → Python 跑通 → C 编译 → 避坑 → 进阶」的顺序拆。2. 资源结构与 onnxruntime 推理链路先看懂文件再动手2.1 目录里每个文件在推理链路里的位置拿到包先别急着pip install把目录树看一遍能省掉后面很多「文件找不到」的玄学问题。从项目正文给出的文件清单看结构大致是 Python 脚本和 C 源码平铺在根目录模型文件按 onnxruntime 惯例单独放。下面这张表是我按实际推理顺序整理的不是按字母序文件所属阶段作用utils_crop.py/utils_crop.cpp预处理人脸检测 对齐裁剪把任意输入图裁成模型要的尺寸faceanalysis.cpp/.h预处理C 侧的人脸分析对应 Python 的检测逻辑mask_template.png预处理裁剪时用的掩码模板保证不同图对齐一致0.jpg输入源人像提供外观和身份d0.mp4输入驱动视频提供表情和头部姿态liveportrait.cpp/.h推理C 主推理逻辑加载 ONNX 并串联各子模型main.py/main.cpp入口分别对应 Python 和 C 的调用入口CMakeLists.txt构建C 侧编译配置指定 onnxruntime 链接路径关键点utils_crop在两个语言里各有一份说明作者没有用 pybind 把 Python 逻辑暴露给 C而是各写各的。好处是 C 侧不依赖 Python 解释器坏处是两边预处理参数必须手动保持一致否则同一张图两边裁出来的脸不一样后面推理结果对不上。2.2 onnxruntime 和 onnx 的区别以及为什么这里选 onnxruntime热搜里常有人问「onnxruntime 和 onnx 区别」这个问题不搞清楚后面配环境必翻车。onnx 是模型格式标准只定义「图长什么样」onnxruntime 是执行引擎负责把这张图真正跑起来管内存分配、算子调度、后端选择CPU / GPU / 其他加速器。你手里.onnx文件是格式onnxruntime是跑它的库两者缺一不可。这个包选 onnxruntime 而不是直接上 PyTorch理由很实际LivePortrait 原版依赖一堆 torch 算子和特定版本换台机器就报undefined symbol转成 ONNX 后只要 onnxruntime 版本对得上Windows、Linux、甚至鲲鹏 920 这类 ARM 平台都能加载同一份模型。常见做法是先用onnxruntime的 Python 包验证模型能跑通再换 C API 做部署这样出问题能快速定位是模型问题还是编译问题。2.3 Python 侧最小验证三步跑通 main.py在动 C 之前先用 Python 确认模型和输入没问题这是最省时间的顺序。假设你已经装好 onnxruntime 和 opencv# 1. 安装最小依赖onnxruntime 选 CPU 版先验证逻辑 pip install onnxruntime opencv-python numpy # 2. 先单独跑裁剪确认人脸能检测到 python utils_crop.py 0.jpg mask_template.png # 3. 跑主流程源图 0.jpg 驱动视频 d0.mp4 python main.py 0.jpg d0.mp4utils_crop.py接收三个位置参数源图、掩码模板、输出路径具体参数名以脚本内argparse为准跑-h能看到。单独跑它的意义在于如果人脸检测这步就失败main.py报的错会很靠后你容易误以为是模型问题。main.py内部一般会依次调用裁剪、加载 ONNX session、逐帧推理、写视频。第一次跑建议把驱动视频换成很短的片段比如 2 秒先看输出有没有画面再上长视频。提示onnxruntime 首次加载模型会做图优化耗时明显比后续推理长别把第一次的慢当成卡死。3. C 侧编译与推理CMakeLists 和 onnxruntime 链接怎么配3.1 CMakeLists.txt 里必须盯死的三个变量C 侧翻车九成出在链接阶段而链接问题的根在CMakeLists.txt。这个包的 CMake 配置核心就三件事找到 onnxruntime 头文件、链接 onnxruntime 库、把liveportrait.cpp、faceanalysis.cpp、utils_crop.cpp、main.cpp一起编进可执行文件。典型配置长这样cmake_minimum_required(VERSION 3.10) project(liveportrait_onnx) set(CMAKE_CXX_STANDARD 17) # onnxruntime 根目录按你实际解压路径改 set(ONNXRUNTIME_DIR /path/to/onnxruntime) include_directories(${ONNXRUNTIME_DIR}/include) link_directories(${ONNXRUNTIME_DIR}/lib) add_executable(liveportrait main.cpp liveportrait.cpp faceanalysis.cpp utils_crop.cpp ) # Linux 下链接 onnxruntimeWindows 下是 onnxruntime.lib target_link_libraries(liveportrait onnxruntime)三个必须改对的地方ONNXRUNTIME_DIR指向你下载的 onnxruntime 发行包解压目录不是 pip 装的那个include_directories要能摸到onnxruntime_cxx_api.htarget_link_libraries的库名在 Linux 是libonnxruntime.so、Windows 是onnxruntime.lib写错就是cannot find -lonnxruntime。另外 C17 是硬要求onnxruntime 的 C API 用了不少现代特性降到 C11 会编译报错。3.2 编译命令与运行时动态库路径配好 CMake 后标准流程是mkdir build cd build cmake .. make -j4 # Linux 下运行时要把 so 路径加进去否则报找不到库 export LD_LIBRARY_PATH/path/to/onnxruntime/lib:$LD_LIBRARY_PATH ./liveportrait 0.jpg d0.mp4make -j4的-j4是按 CPU 核数并行编译核多可以调大。最后那句export LD_LIBRARY_PATH是 Linux 下的高频坑编译过了不代表能跑运行时动态链接器找不到libonnxruntime.so就直接退出。Windows 下对应的是把onnxruntime.dll放到 exe 同目录或者加进PATH。main.cpp的入参和 Python 侧保持一致都是源图加驱动视频这样两边结果能直接对比。3.3 两边结果对不上时先查预处理Python 和 C 跑同一组输入输出如果明显不一样先别怀疑模型九成是预处理差异。utils_crop.py和utils_crop.cpp是两份独立实现缩放插值方式、归一化均值方差、裁剪框取整规则只要有一处不同裁出来的脸就有像素级偏移后面动画自然对不上。排查方法是把两边裁剪后的中间图都存下来肉眼比一下或者算个像素差。常见做法是在 C 侧临时加一段写图代码把裁剪结果 dump 成 png和 Python 的输出并排看。4. 避坑与常见问题这几处我踩过4.1 现象ImportError: DLL load failed或libonnxruntime.so not found原因onnxruntime 的 Python 包和 C 库是两套东西pip 装的成功不代表 C 能链接反过来 C 配好了Python 环境里可能根本没装 onnxruntime。另外 Windows 上缺 Visual C Redistributable 也会导致 DLL 加载失败。解决Python 侧pip install onnxruntime单独装C 侧从官方发行包解压别指望 pip 的包能直接给 CMake 用。Windows 上先装一遍 Microsoft Visual C Redistributable这是很多 DLL 问题的后悔药。4.2 现象推理结果人脸错位或动画抖动严重原因mask_template.png没跟着源图一起传或者裁剪尺寸和模型输入尺寸不匹配。LivePortrait 对输入对齐很敏感模板掩码的作用就是固定对齐基准。解决确认utils_crop调用时掩码模板路径正确且模板尺寸和模型期望的输入分辨率一致。换源图时不要换模板模板是通用的对齐基准。4.3 现象C 编译报undefined reference to Ort::...原因target_link_libraries里库名写错或者link_directories路径不对链接器根本没找到 onnxruntime 库。解决确认ONNXRUNTIME_DIR/lib下确实有libonnxruntime.soLinux或onnxruntime.libWindows库名大小写和平台对应。用ldd ./liveportrait看运行时到底缺哪个库。4.4 现象驱动视频长一点就内存暴涨原因逐帧推理时没有及时释放中间张量或者一次性把整个视频读进内存。ONNX session 本身会占固定内存但每帧的输入输出张量如果不复用会累积。解决常见做法是复用输入输出 tensor别每帧新建视频用流式读取处理完一帧写一帧。长视频先切段跑确认内存稳定再上完整流程。4.5 现象换机器后同样的代码报算子不支持原因不同 onnxruntime 版本支持的算子集不同模型导出时用的 opset 版本如果高于运行时的支持上限加载就失败。解决统一 onnxruntime 版本Python 和 C 用同一个发行版本号。报错信息里一般会带不支持的算子名对着版本发布说明查。5. 进阶把单张图推理改成批量与自定义输出跑通最小闭环之后真正提效的是批量和输出控制。Python 侧改main.py时我一般会把推理循环抽出来让源图可以传一个目录驱动视频固定批量出结果。核心改动是别在循环里反复创建InferenceSessionsession 创建一次复用import onnxruntime as ort import os # session 只建一次这是批量提速的关键 sess ort.InferenceSession(liveportrait.onnx, providers[CPUExecutionProvider]) def run_one(src_path, drv_path, out_path): # 预处理、推理、后处理按原 main.py 逻辑走 ... return out_path src_dir portraits for name in os.listdir(src_dir): if name.lower().endswith((.jpg, .png)): run_one(os.path.join(src_dir, name), d0.mp4, fout_{name}.mp4)providers参数决定后端CPU 版写CPUExecutionProvider有对应加速环境再换。session 复用能省掉每次加载模型做图优化的开销批量场景下提速很明显。C 侧同理Ort::Session在liveportrait.cpp里创建一次main.cpp循环调用推理函数即可。输出控制上d0.mp4的帧率和输出帧率要对齐否则动画速度会变。常见做法是读驱动视频的CAP_PROP_FPS写输出时用同一个值。另外mask_template.png如果要做多套风格可以准备多个模板但每个模板都要和模型输入尺寸对齐别混用。验证是否真的跑对我的习惯是固定一组输入Python 和 C 各跑一遍把输出视频抽同一帧做像素对比差异在可接受范围内才算两边一致。从那以后我每次换 onnxruntime 版本或者换机器都强制走一遍这个对比流程省得后面在业务代码里查半天。希望帮到你。本文还有配套的精品资源点击获取