简介面向C#开发者基于OnnxRuntime部署LivePortrait实现快速、高质量人像驱动视频生成的完整资源包。压缩包内共384个文件包含onnx模型文件、dll运行库、C#源码、NuGet依赖配置与mp4效果演示等其中onnx负责模型推理、dll提供运行时支撑、mp4可直观看到生成效果整体体积约882.12MB目录结构清晰便于按模块查找与接入现有项目。目前已有182人学习下载。资源覆盖人像驱动视频生成的关键链路并提供多种格式依赖库与平台运行文件可帮助图形图像、人工智能方向的开发者跳过环境配置与模型转换等繁琐步骤快速验证效果或进行二次开发。无论是研究实时人像驱动算法还是需要将LivePortrait落地到C#生产环境均可获得可运行的参考方案。1. C# OnnxRuntime 部署 LivePortrait为什么放弃 Python 直接推理手里有一张静态人像照片想让它被一段视频驱动着动起来眨眼、转头、口型都跟着驱动视频走。LivePortrait 是当前效果和速度平衡得比较好的开源人像驱动方案但官方示例基本是 Python 写的要接入 C# 上位机或现有 .NET 业务系统就得重新在 OnnxRuntime 上搭推理管线。这条路径解决的是「把模型放进产品里」的问题交付物就是一个带 dll 的文件夹目标机器不用装 Python摄像头采集、视频帧生成、结果落盘可以在同一个进程里闭环。下文按部署顺序展开先拆模型结构再给最小可跑的 C# 代码最后是踩坑记录和调优方向。适合会基础 C#、碰过 OpenCvSharp但第一次做多模型推理管线的人。2. LivePortrait 推理链拆解五个子模型的输入输出与数据流LivePortrait 不是单个 ONNX 文件而是一组子模型拼成的管线。官方导出 ONNX 时会得到 appearance_feature_extractor、motion_extractor、warping_module、spade_generator、stitching_retargeting 五个模型。很多第一次部署的人栽在「我以为一个模型搞定」上实际每一帧要走完五段推理。但换个角度看每个模型职责单一出问题反而好定位。2.1 五个子模型各自干什么我用 CG 里的「绑定 驱动」来类比这套管线。源人像相当于被绑定的角色驱动视频是动作演员五个模型各管一段外观提取、动作提取、形变、生成、贴回。appearance_feature_extractor 只吃源人像图输出外观特征张量。这个输出只和源图有关和驱动帧无关所以整段视频处理中它只需要跑一次结果缓存复用。我实际部署时单独验证过这一点把源特征存下来后续每一帧都少一段推理节省的时间占比不小尤其在高分辨率输入时。motion_extractor 吃的是驱动帧的人脸图输出隐式关键点 kp、旋转 R、平移 t、表情参数 exp。kp 不是传统 2D 人脸关键点而是一个高维隐式表示嘴巴张合、眉毛挑动这类精细表情主要靠 exp 传递。这个模型没有任何缓存空间每一帧都要跑是整个管线的算力大头之一。warping_module 把三样东西揉在一起源图外观特征、源图运动参数、驱动帧运动参数输出一个 warp 后的特征图。spade_generator 再基于这个特征图逐像素生成一张新的人脸图。最后 stitching_retargeting 负责把生成脸贴回原图位置处理边界过渡和颜色一致。最后这个模型很多人忽略直接暴力把脸贴回去结果视频里脸周围一圈硬边效果大打折扣。2.2 输入输出的张量约定先澄清一个基础概念onnx 是模型的文件格式onnxruntime 是加载并执行这种格式的推理引擎两者不是一回事。OnnxRuntime 通过 NuGet 包接入 C# 项目底层带一组原生动态库交付时需要把这些 dll 一并拷贝到运行目录。我导出的模型统一是 NCHW 布局图像输入为 [1,3,256,256]像素归一化到 [-1,1]。OpenCvSharp 读进来的 Mat 是 HWC 且是 BGR必须做一次「转 RGB 高宽展平到通道」的排列。这步是新手必翻的车颜色通道顺序不对生成的脸整体偏色排列顺序不对图像像被撕裂一样。模型主要输入主要输出执行频率appearance_feature_extractor源人脸 [1,3,256,256]外观特征全程 1 次motion_extractor驱动人脸 [1,3,256,256]kp、R、t、exp每帧warping_module源特征 源/驱动运动参数warp 特征每帧spade_generatorwarp 特征生成人脸 [1,3,256,256]每帧stitching_retargeting生成人脸 贴回辅助信息贴回结果每帧上面表格里的 kp 关键点数量、exp 通道数每个导出版本可能不一样。代码里不要硬编码这些数字启动时用 session.OutputMetadata 读真实 shape 并做好断言。模型一换立刻报错比运行时静默算错强得多这是我在交付阶段吃过亏的地方。2.3 为什么 OnnxRuntime 而不是 Python对 C# 上位机场景这个选择基本是必然。一是进程隔离问题Python 推理要么起子进程要么嵌入 Python 运行时C# 和 Python 之间传一帧 1080p 图像要走 IPC带宽和延迟都吃亏。二是交付问题OnnxRuntime 引入的依赖链短一个 NuGet 包加几个原生 dll运行机不需要 Python 解释器和一堆 pip 包。三是性能OnnxRuntime 的图优化做得比较到位CPU 上也有收益接 GPU 的 CUDA provider 也就几行代码。当然模型没定稿之前先在 Python 里验证效果是合理的定稿后再导出 ONNX 进 C#。我把这个流程固定下来之后后面换模型只需要重新导出 ONNXC# 侧代码几乎不动。这个「先 Python 调效果、后 C# 调部署」的节奏比从一开始就在 C# 里折腾模型要省力得多。3. 在 C# 里搭起 OnnxRuntime 推理管线从 NuGet 到第一帧动手写代码之前建议先把五个模型文件和一个人脸检测模型放到独立目录路径统一从配置读不要写死在代码里。这里说的最小可跑管线按「源图 一段驱动视频 → 输出视频」来做实时摄像头模式在这个骨架上再加采集线程即可。3.1 项目依赖与 Session 初始化NuGet 包选择很直接Microsoft.ML.OnnxRuntime 是核心OpenCvSharp4 和 OpenCvSharp4.runtime.win 负责图像读取、变换和视频写出。上 GPU 就换成 Microsoft.ML.OnnxRuntime.Gpu注意这个包带的是 CUDA 的原生库驱动和 CUDA 版本不对会直接加载失败日志里能看到明显的 DllNotFound 异常。using Microsoft.ML.OnnxRuntime; using Microsoft.ML.OnnxRuntime.Tensors; using OpenCvSharp; var options new SessionOptions { GraphOptimizationLevel GraphOptimizationLevel.ORT_ENABLE_ALL, ExecutionMode ExecutionMode.ORT_SEQUENTIAL }; // 有 NVIDIA GPU 时追加 CUDA provider纯 CPU 部署就留空 // options.AppendExecutionProvider_CUDA(0); var appSession new InferenceSession(appearance_feature_extractor.onnx, options); var motionSession new InferenceSession(motion_extractor.onnx, options); var warpSession new InferenceSession(warping_module.onnx, options); var spadeSession new InferenceSession(spade_generator.onnx, options); var stitchSession new InferenceSession(stitching_retargeting.onnx, options);五个 Session 在程序启动时一次性创建全程复用。Session 创建要做模型加载和图优化开销不小每一帧重建 Session 是典型的性能自杀。GraphOptimizationLevel 用默认的 ORT_ENABLE_ALL 就够除非你在排查某个算子的数值异常才需要调低。ExecutionMode 默认 SEQUENTIAL多核机器可以试 ORT_PARALLEL但算子级并行对这条管线收益有限帧级并行才是大头。3.2 人脸检测用 YuNet 拿 bbox 与五点模型真正吃的不是整帧画面而是「对齐后的人脸图」。所以管线里必须有人脸检测和对齐。我用的检测器是 OpenCV Zoo 里的 YuNet单个 ONNX 文件同时输出 bbox 和五个关键点正好拿来算相似变换。using var detector FaceDetectorYN.Create( face_detection_yunet.onnx, , new Size(320, 240), 0.6f, 0.3f); detector.SetInputSize(new Size(640, 480)); using var frame Cv2.ImRead(driving_frame.jpg); using var faces new Mat(); detector.Detect(frame, faces); if (faces.Rows 0) continue; // 没检测到人脸就跳帧 // faces 每行 15 个 floatx, y, w, h, 五个关键点的 x/y最后是置信度 float x faces.Atfloat(0, 0); float y faces.Atfloat(0, 1); float w faces.Atfloat(0, 2); float h faces.Atfloat(0, 3); float score faces.Atfloat(0, 14); var bbox new Rect((int)x, (int)y, (int)w, (int)h);YuNet 的三个构造参数分别是输入尺寸、置信度阈值和 NMS 阈值。输入尺寸我建议设到 640×480 以上320×240 对远距离小脸会漏检。阈值 0.6 在正常角度下够用如果驱动视频有大量侧面或低头降到 0.5 能减少漏检但也会带进一些误检后端过滤逻辑要跟上。上面拿到的是第一张脸的 bbox。实际部署时驱动画面里可能有多个无关人脸我只取置信度最高且面积最大的那个避免模型被旁边的人干扰了驱动参数。3.3 相似变换对齐与张量转换bbox 只能告诉我脸在哪但脸在框里的角度和大小可能差很多直接 Resize 到 256×256 会让模型效果非常不稳定。正确做法是用五点做相似变换把眼睛鼻子摆到标准位置这步对最终生成质量的影响很多时候比换模型还大。static Mat AlignFace(Mat frame, Point2f[] landmarks, int size 256) { // 三点法右眼、左眼、鼻尖映射到标准构图 var src new Point2f[] { landmarks[0], landmarks[1], landmarks[2] }; var dst new Point2f[] { new Point2f(0.35f * size, 0.35f * size), new Point2f(0.65f * size, 0.35f * size), new Point2f(0.50f * size, 0.55f * size) }; var m Cv2.EstimateAffinePartial2D(src, dst); Mat aligned new Mat(); Cv2.WarpAffine(frame, aligned, m, new Size(size, size), InterpolationFlags.Linear, BorderTypes.Replicate); return aligned; }EstimateAffinePartial2D 只允许旋转、平移和等比缩放不允许单独拉长压扁这对人脸是合理的约束。dst 的三个点是经验值双眼在 35% 高度鼻尖在 55% 高度横向上双眼分别偏宽度的 35% 和 65%。这个构图接近 LivePortrait 官方效果图的取景习惯。张量转换有个性能要点别用 At 逐像素读。Mat 内存连续时直接把数据指针转成 byte* 遍历配合通道序排列一帧 256×256 的转换能压到三毫秒以内。static Tensorfloat FaceToTensor(Mat bgr, int size 256) { Cv2.CvtColor(bgr, bgr, ColorConversionCodes.BGR2RGB); var data new float[1 * 3 * size * size]; unsafe { byte* p (byte*)bgr.DataPointer; for (int h 0; h size; h) { for (int w 0; w size; w) { int idx h * size w; data[idx] p[2] / 127.5f - 1f; // R data[size * size idx] p[1] / 127.5f - 1f; // G data[2 * size * size idx] p[0] / 127.5f - 1f; // B p 3; } } } return new DenseTensorfloat(data, new[] { 1, 3, size, size }); }注意 Mat 如果不是连续内存DataPointer 直接踩会串行。稳妥做法是进入函数后先判断 bgr.IsContinuous()不连续就先 Clone 一次。从视频解码出来的帧通常是连续的做了 WarpAffine 之后是否连续要确认AlignFace 返回的 Mat 往往不连续这个细节我在调用处统一修复。3.4 推理主循环五段式调用的顺序与缓存主循环的骨架如下源特征只算一次驱动帧逐段跑完五段推理// 源特征只算一次 var srcTensor FaceToTensor(alignFaceSource); using (var r appSession.Run(new[] { NamedOnnxValue.CreateFromTensor(input, srcTensor) })) { srcFeature r.First().AsTensorfloat(); } foreach (Mat driveFrame in ReadFrames(driveVideoPath)) { // 1. 检测并对齐驱动人脸 // 2. motion_extractor 提取 kp/r/t/exp using var motionOut motionSession.Run(MotionInput(driveFaceTensor)); var kp motionOut[0].AsTensorfloat(); var rRot motionOut[1].AsTensorfloat(); var tVec motionOut[2].AsTensorfloat(); var exp motionOut[3].AsTensorfloat(); // 3. warping using var warpOut warpSession.Run(BuildWarpInputs(srcFeature, srcKp, srcR, srcT, srcExp, kp, rRot, tVec, exp)); // 4. spade 生成 using var spadeOut spadeSession.Run(BuildSpadeInput(warpOut[0])); // 5. stitching 贴回 using var stitchOut stitchSession.Run(BuildStitchInputs(spadeOut[0], motionOut[0], rRot, tVec, srcKp, srcR, srcT)); var result MatFromTensor(stitchOut[0].AsTensorfloat()); PasteBack(driveFrame, result, bbox, transform); }这里 input 是占位名称真实名称要从 session.InputMetadata 读。输出顺序也不一定严格是 kp、R、t、exp我吃过一次亏以为顺序固定换了个导出版本R 和 t 拿反生成出来的人像整个歪掉。后来改成按输出名字取值而不是按下标取。warp 和 spade 的输入张量数量多其中源侧运动参数全程不变每帧只需要换驱动侧我一般维护一个模板字典每帧只替换驱动侧张量源侧复用同一引用。4. 帧率与视频输出视频帧生成后的编码与落盘推理管线跑通之后下一件事是把生成帧变成可以交付的视频文件。这一步看起来简单实际坑不少尤其是编码器选型和帧率同步。4.1 VideoWriter 编码器选型OpenCvSharp 的 VideoWriter 是最直接的出片方式但它底层依赖本机已安装的编码器。用 FourCC.MP4V 在 Windows 上经常打开失败而且失败往往是静默的不抛异常你写完所有帧才发现文件是空的或者只有 0 字节。using var writer new VideoWriter(output.mp4, FourCC.MP4V, 25, new Size(1920, 1080)); if (!writer.IsOpened()) { // 回退方案MJPG AVI保底能出片 writer.Open(output.avi, FourCC.MJPG, 25, new Size(1920, 1080)); } foreach (var frame in resultFrames) { writer.Write(frame); }我的习惯是 Create 之后立刻检查 IsOpened()拿不到编码器就回退到 MJPG 再后期转码。如果你对交付格式有硬性要求比如必须是 H.264 的 mp4更稳的做法是上面这样先出 MJPG AVI再用 FFmpeg 转一次码转码命令大概长这样ffmpeg -i output.avi -c:v libx264 -crf 18 -preset medium output.mp4crf 18 接近视觉无损交付用够了preset 按机器性能选slow 出片质量略好但时间翻倍。这个方法看着绕了一圈但比起纠结系统里到底有没有 H.264 编码器要确定得多。我在连续交付几台不同配置的 Windows 机器后就把 VideoWriter 直接出 mp4 这条路彻底放弃了。4.2 帧率同步与丢帧策略视频帧生成节奏和驱动视频帧率大概率对不上。驱动是 25fps但推理可能只有 12fps这里有两个选择放慢输出到 12fps或者保持 25fps 但每帧插值一下。对 LivePortrait 这种人像驱动场景我建议「丢帧不拖帧」。// 输入帧按时间戳进队处理完一帧就消费一帧 // 如果队里积压超过 3 帧说明推理跟不上直接丢最老的一帧 if (frameQueue.Count 3) { frameQueue.TryDequeue(out _); }这背后的逻辑很简单人像驱动的效果连续性靠的是表情变化而不是运动模糊。丢帧时表情变化会显得跳但整体时间轴是对齐的拖帧则会让嘴型和动作整体滞后看起来像音画不同步更难受。如果你要接音频同理音频时间轴不动视频按时间戳对齐最后 FFmpeg 合成时用 -shortest 截齐。实时摄像头模式也是同一套逻辑只是帧来源从视频文件变成摄像头的 UVC 回调。回调里把 Mat 扔进并发队列推理线程消费队列长度就是背压信号。这里要注意 OpenCvSharp 的 Mat 在跨线程传的时候要 Clone 一份摄像头回调里的 Mat 生命周期短不 Clone 会出现偶发的黑帧。5. LivePortrait 部署避坑指南onnx 转换、显存与推理抖动的排查记录这一章写我实际踩过的四个坑按「现象 → 原因 → 解决」记录。每条都是交付过程中真实出现过的不保证覆盖所有环境但能帮你省下不少排查时间。5.1 输入名称对不上推理直接抛异常现象session.Run 时 OnnxRuntime 报 InvalidArgument说找不到名为 input 的输入。原因模型导出时的输入张量名不是 input而且不同版本的 LivePortrait 导出脚本命名可能不同用占位名去跑必然炸。解决启动时把五个模型的 InputMetadata 和 OutputMetadata 全部打印出来和模型脚本对一遍代码里统一从元数据取名字。下面这段是我放在程序启动时的检查逻辑。static void DumpIO(InferenceSession session, string tag) { foreach (var kv in session.InputMetadata) Console.WriteLine($[{tag}] input: {kv.Key} - {string.Join(,, kv.Value.Dimensions)}); foreach (var kv in session.OutputMetadata) Console.WriteLine($[{tag}] output: {kv.Key}); }输出名称的顺序问题也一样。我一开始按下标取输出的张量后来换模型版本发现 R 和 t 顺序反了生成效果彻底崩掉。改成按名字取值之后再没出过这类问题。这个坑本质上是「把内部实现当成接口来依赖」模型文件换了就爆。5.2 显存与内存双爆跑几分钟就退出现象程序能启动也出了几帧但几秒后进程直接崩掉或显卡显存报 OutOfMemory。原因主要有两类。一类是 session.Run 的返回结果没有及时 DisposeOnnxRuntime 在 GPU 上跑的中间结果会占显存using 没写全就累积。另一类是那个 ComfyUI 生成视频时爆内存的通病——中间张量被无意识地复制累积尤其是源特征图每帧都去重新推理或 Clone内存越堆越高。解决代码里所有 Run 的返回值都用 using 包裹确认在下一个 Run 之前已经释放源侧张量全部复用同一实例不做每帧 Clone如果显存还是紧张把 five 个 Session 的 CUDA provider 显存限制设一下比如每个 Session 限量 2GB别让它默认吃满。我实际部署时用 NVIDIA 显卡跑 1080p五个 Session 常驻显存大约 3GB 左右超出这个量级就要检查是不是有张量在泄漏。5.3 生成的人像是抖的运动参数需要平滑现象生成的视频五官位置正确但面部整体有高频抖动像隔着一层水看脸。原因不是模型 bug而是 motion_extractor 提取出的 kp 和 R 在相邻帧之间有小幅度的数值波动叠加到生成阶段被放大了。驱动视频本身如果来自手持拍摄或者运动幅度大的片段抖动更明显。解决对运动参数做一阶互补滤波或简单滑动平均。我用的是一阶低通当前帧的 R 和 t 与上一帧加权融合权重取 0.3 到 0.5效果明显但不至于让表情变迟钝。exp 表情参数不要做过强的平滑会把细微表情磨平只对 R 和 t 做就很够。此外快速甩头的片段会导致人脸检测 bbox 跳变这属于前端问题在检测阶段做一次 bbox 的平滑也可以缓解但根治手段是裁剪驱动视频时尽量避免快速镜头切换。5.4 首帧延迟特别大模型加载和图优化现象程序启动后第一帧要等两三秒甚至更久之后就好了。原因Session 创建时要做模型读取、图优化、算子内核选择五个 Session 串行初始化这个时间叠加起来很可观。解决把 Session 初始化放到后台线程做UI 或主流程先响应初始化完成后才开始取流。另外可以显式设置 SessionOptions 里的 IntraOpNumThreads 和 GraphOptimizationLevel有时候默认线程数过多初始化竞争反而更慢。最终极的办法是把五个模型合并成一个大的 ONNX 图但不是所有算子都支持跨模型融合这个工作量的性价比不高我一般不做。6. 从能跑到跑快性能量化与四个优化抓手6.1 先量化再优化别凭感觉调参用 Stopwatch 把「人脸检测、对齐、张量转换、五个推理段、贴回、编码」六段分别计时先知道瓶颈在哪。我遇到的情况通常是 motion_extractor 和 spade_generator 两段占了总耗时的大半人脸检测反而很便宜。没有这一步优化就是玄学改了也不知道有没有用。6.2 源特征缓存与张量复用这是性价比最高的一项优化。源图在整个处理过程中不变appearance_feature_extractor 的输出和源侧运动参数全部缓存复用。另外每帧重建 Tensor 数组会触发多次 GC维护一个固定的 NamedOnnxValue 列表每帧只更新驱动侧张量的值我实测可以将 GC 压力降一半以上。6.3 FP16 的收益和代价OnnxRuntime 支持 FP16 推理显存占用减半部分算子速度明显提升。但 LivePortrait 这类生成模型对数值精度敏感FP16 直接套上去极端光照下可能出现色带或细微伪影。我的习惯是先 FP32 跑通全流程再导出 FP16 版本做 A/B 对比重点看眼睛和嘴唇边缘肉眼无差异才切换。6.4 多路并行的线程配置如果你要同时驱动多路视频比如监控墙的多路画面每路一个线程各自持有自己的 Session 实例互不共享。线程数别开满我踩过的坑是 8 核机器上开 8 个线程CPU 上下文切换开销反而让总吞吐下降最终稳定在 4 到 6 个线程。这里用到了 C# 的 ThreadPool 上限控制记得用 SetMinThreads 调一下默认值在线程密集场景下不够用。这套部署方案我从项目启动到第一版交付用了不到一周后面维护模型版本更新只动了导出脚本C# 侧基本没碰。最大的感受是LivePortrait 本身的模型结构并不复杂难的是把它周围那一圈工程问题——人脸对齐、张量布局、编码器、内存管理——一次想清楚。希望帮到你。本文还有配套的精品资源点击获取
