简介这是一款用C#编写的本地照片与视频管理工具面向需要按人物整理个人影像资料的普通用户与开发者。它支持jpg、jpeg、png、bmp等图片格式以及avi、mp4、mpg、mpeg等视频格式核心能力包括人脸库录入、照片视频人脸自动识别以及按人脸名称检索最多可同时指定三个人物作为组合条件并附带视频播放与照片浏览功能。资源包共646个文件以410个dll动态库为主另有mo语言包、luac脚本、png图标、html页面、json与xml配置、exe可执行程序等压缩包约248.56MB目录中可见OpenCvSharp、paddle_fluid、opencv_world等视觉与推理相关组件说明其识别链路依赖本地模型与百度离线SDK。使用前需安装.NET Framework 5.0运行环境并在license目录写入百度人脸识别离线版序列号。目前已有527人学习下载适合想研究人脸检索与本地媒体库整合方案的读者参考。1. 基于人脸识别的照片视频管理器从“翻相册翻到崩溃”到“按脸找人”我本地存了大概四万张照片和两千多条视频横跨七八年早期靠文件夹按日期分后来发现根本找不到人。想找某位家人三年前在某个场景下的照片只能一张张翻翻到怀疑人生。基于人脸识别的照片视频管理器解决的就是这件事把本地媒体库扫一遍自动检测人脸、聚类成“人”之后按人浏览、按人筛选甚至按“某个人某段时间”组合检索。标题里点明了“稳定版64位”和“c#编写”意味着它面向的是 Windows 桌面、大内存、长时间运行不崩的场景而不是跑一次就扔的脚本。适合谁适合本地媒体库过万、又不想把照片传到云端、还希望自己能改两行代码的从业者。这一章先把“它到底在做什么”讲清楚后面再拆实现。2. 人脸识别照片管理器的技术选型为什么是 C# 本地推理2.1 桌面端做媒体管理C# 的甜区和边界先说为什么是 C#。照片视频管理器本质是一个“重 IO 重计算 重 UI”的桌面程序要遍历磁盘、读缩略图、跑人脸检测、维护数据库、还要实时渲染几千张缩略图不卡。C# 在 Windows 上的优势很直接.NET 的异步 IO 和SpanT、MemoryT对大批量图像缓冲友好WPF/WinUI 做虚拟化列表成熟P/Invoke 调本地推理库也顺。边界也要说清楚C# 不是做模型训练的首选但做“推理编排 媒体管理”非常合适。常见做法是模型用 Python 侧训练或直接拿现成的 ONNX 模型C# 侧只负责推理和业务。64 位这件事不是噱头。32 位进程用户态地址空间通常只有 2GB 左右加载一个人脸检测模型加上几百张缩略图缓存就可能触顶表现为“扫到一半 OutOfMemoryException”。稳定版 64 位意味着进程能吃到几 GB 甚至更多内存长时间批量扫描不容易崩。我一般会在项目文件里显式锁定平台!-- 在 .csproj 中锁定 64 位避免 AnyCPU 在 32 位宿主下跑 -- PropertyGroup PlatformTargetx64/PlatformTarget !-- 关闭 32 位首选防止在某些宿主里被降级 -- Prefer32Bitfalse/Prefer32Bit Nullableenable/Nullable /PropertyGroup逻辑说明PlatformTarget设为x64保证生成的是 64 位程序Prefer32Bit关掉避免 AnyCPU 在特定宿主下被当成 32 位跑。参数上如果你的推理库只有 x64 原生 DLL这一步是必须的否则运行时会报BadImageFormatException。2.2 人脸检测、特征提取、聚类三段式管线人脸识别在工程上要拆成三段混在一起讲最容易翻车第一段是人脸检测输入一张图输出若干人脸框和关键点。常用模型有基于 RetinaFace 思路的或轻量级 YOLO 人脸变体导出成 ONNX。第二段是特征提取把对齐后的人脸裁剪切成一个固定维度的向量常见 128 维或 512 维同一个人的向量余弦距离小不同人大。第三段是聚类把全库向量聚成若干簇每簇对应一个“人”。为什么强调“对齐”检测框往往带角度直接裁剪再提特征同一个人侧脸和正脸的特征距离会拉大聚类就会把一个人拆成两簇。常见做法是用检测出的 5 个关键点双眼、鼻尖、双嘴角做仿射变换把人脸摆正到 112×112 或 160×160 再送特征模型。选型理由检测模型要快因为要跑几万张特征模型要稳因为聚类质量全靠它聚类算法要能增量因为用户会不断加新照片。我一般检测用轻量模型特征用稍重的模型聚类用层次聚类或 DBSCAN 的增量变体。2.3 用 ONNX Runtime 在 C# 里跑推理的最小闭环C# 侧跑 ONNX 最省心的方案是 ONNX Runtime。下面是一个最小可复现的推理封装假设你已经有detect.onnx和embed.onnx两个模型文件。using Microsoft.ML.OnnxRuntime; using Microsoft.ML.OnnxRuntime.Tensors; public sealed class FaceOnnx : IDisposable { private readonly InferenceSession _detect; private readonly InferenceSession _embed; public FaceOnnx(string detectPath, string embedPath) { // 64 位下建议开启全部 CPU 线程IO 密集时再考虑限制 var opts new SessionOptions { IntraOpNumThreads Environment.ProcessorCount }; _detect new InferenceSession(detectPath, opts); _embed new InferenceSession(embedPath, opts); } // 输入归一化后的 NCHW 张量输出人脸框 5 关键点 public float[] Detect(float[] nchw, int w, int h) { var input new DenseTensorfloat(nchw, new[] { 1, 3, h, w }); var inputs new ListNamedOnnxValue { NamedOnnxValue.CreateFromTensor(input, input) }; using var results _detect.Run(inputs); // 具体输出名以模型为准这里取第一个输出展平 return results.First().AsEnumerablefloat().ToArray(); } // 输入对齐后的 112x112 人脸输出512 维特征向量 public float[] Embed(float[] aligned) { var input new DenseTensorfloat(aligned, new[] { 1, 3, 112, 112 }); var inputs new ListNamedOnnxValue { NamedOnnxValue.CreateFromTensor(input, input) }; using var results _embed.Run(inputs); return results.First().AsEnumerablefloat().ToArray(); } public void Dispose() { _detect.Dispose(); _embed.Dispose(); } }逻辑说明InferenceSession是线程安全的可以全局复用一个实例不要每张图 new 一个否则加载模型的开销会拖垮扫描速度。IntraOpNumThreads设成 CPU 核数在批量扫描时吞吐更好但如果你的程序同时要渲染 UI建议留一两个核否则界面会卡。参数上输入张量的名字input和输出顺序必须和模型导出时一致用 Netron 打开 ONNX 看一眼最稳。特征向量记得做 L2 归一化后面算余弦距离才方便。3. 把四万张照片扫进库目录遍历、缩略图与人脸入库3.1 媒体库遍历与去重别让同一张图进两次扫描第一步是遍历。坑在于同一张照片可能同时存在于“相机导入”和“手机备份”两个目录哈希一样但路径不同。我一般用“文件大小 前 64KB 的 SHA256”做轻量指纹避免全文件哈希拖慢速度。using System.Security.Cryptography; public static string QuickFingerprint(string path) { var fi new FileInfo(path); using var fs File.OpenRead(path); // 只读前 64KB兼顾速度和碰撞率 var buf new byte[Math.Min(65536, fi.Length)]; int read fs.Read(buf, 0, buf.Length); using var sha SHA256.Create(); var head sha.ComputeHash(buf, 0, read); // 大小 头部哈希组合降低不同文件头部相同的概率 return ${fi.Length}_{Convert.ToHexString(head)}; }逻辑说明只读头部是为了速度四万张图全量哈希可能要几十分钟。参数上 64KB 是个经验值太小碰撞率高太大收益递减。指纹存进数据库加唯一索引重复文件直接跳过省下的是后面检测和特征提取的时间。3.2 缩略图生成与 EXIF 时间提取人脸检测不需要原图长边缩到 640 或 960 就够既快又省内存。同时要把 EXIF 的拍摄时间读出来因为聚类展示时按时间排序体验最好。using System.Drawing; using System.Drawing.Imaging; public static (Bitmap thumb, DateTime taken) LoadForDetect(string path) { using var origin new Bitmap(path); // 按长边缩放保持比例 int longSide Math.Max(origin.Width, origin.Height); double scale longSide 960 ? 960.0 / longSide : 1.0; int w (int)(origin.Width * scale); int h (int)(origin.Height * scale); var thumb new Bitmap(origin, w, h); // EXIF 36867 是拍摄时间取不到就退回文件修改时间 DateTime taken origin.PropertyIdList.Contains(36867) ? DateTime.ParseExact(origin.GetPropertyItem(36867).Value .ToString().Trim(\0), yyyy:MM:dd HH:mm:ss, null) : File.GetLastWriteTime(path); return (thumb, taken); }逻辑说明System.Drawing.Common在 .NET 6 之后对非 Windows 平台支持有限但本项目是 Windows 桌面没问题。参数上 960 是检测精度和速度的折中太小远处人脸会漏检。EXIF 时间解析要 try-catch因为有些图的时间字段格式不规范直接崩掉整个扫描不值得。3.3 人脸入库表结构向量怎么存、怎么查向量存储是这类项目的核心。四万张照片假设平均每张 1.5 张脸就是六万条向量512 维 float 大约 120MB放内存完全够。数据库里存 BLOB启动时加载进内存做距离计算。CREATE TABLE Faces ( Id INTEGER PRIMARY KEY AUTOINCREMENT, MediaId INTEGER NOT NULL, BoxX INTEGER, BoxY INTEGER, BoxW INTEGER, BoxH INTEGER, Embedding BLOB NOT NULL, -- 512 维 float32L2 归一化后 ClusterId INTEGER, -- 聚类后回填NULL 表示未归类 Quality REAL, -- 检测置信度低质量脸不参与聚类 FOREIGN KEY(MediaId) REFERENCES Media(Id) ); CREATE INDEX idx_faces_cluster ON Faces(ClusterId); CREATE INDEX idx_faces_media ON Faces(MediaId);逻辑说明Embedding存归一化后的 float32 数组读取时用Buffer.BlockCopy还原成float[]。Quality字段很关键模糊、遮挡、侧脸过大的检测结果如果参与聚类会把不同人粘在一起。我一般把置信度低于 0.6 或人脸框小于 40px 的标记为低质量聚类时跳过但保留在库里供人工确认。4. 聚类与“按人浏览”让机器把脸分堆再让人来命名4.1 余弦距离阈值怎么定0.4 还是 0.6聚类质量几乎全看阈值。特征向量 L2 归一化后余弦相似度等于点积距离用1 - dot。同一个人的两张脸距离通常在 0.2~0.5不同人通常在 0.7 以上。阈值定在 0.5 左右比较稳但这不是绝对的取决于你的特征模型。我一般会先跑一个小规模验证手动挑 20 个人、每人 5 张算类内和类间距离分布看两条分布曲线的交叉点在哪。这个动作花半小时能省掉后面反复调参的几天。别信“某个模型固定阈值 0.6”这种说法模型换了阈值就得重定。4.2 增量聚类新照片进来怎么不重跑全库全库重聚类在六万条向量上还能接受但用户每天加几十张每次都全跑就浪费。常见做法是维护每个簇的“中心向量”新脸来了先和所有簇中心比距离小于阈值就归入最近的簇否则新建一个簇。public int AssignCluster(float[] emb, Listfloat[] centers, float threshold 0.5f) { int best -1; float bestDist float.MaxValue; for (int i 0; i centers.Count; i) { float dot 0; for (int j 0; j emb.Length; j) dot emb[j] * centers[i][j]; float dist 1 - dot; // 余弦距离 if (dist bestDist) { bestDist dist; best i; } } if (bestDist threshold) return best; centers.Add(emb); // 新簇中心就是它自己 return centers.Count - 1; }逻辑说明簇中心用成员向量的均值再归一化定期更新否则中心会漂移。参数上threshold是核心调大召回高但容易合并不同人调小则一个人被拆成多簇。实际项目里我会给用户一个“合并/拆分”的手动入口因为再好的自动聚类也需要人工兜底。4.3 按人浏览的 UI 组织虚拟化列表不能省展示层最容易翻车的是性能。几千个簇、每个簇几十张缩略图如果一次性创建所有 Image 控件内存直接爆。WPF 的VirtualizingStackPanel是标配配合缩略图懒加载列表只加载可见区域的图滚动时异步补。// 伪代码虚拟化 异步缩略图 protected override void OnScrollChanged(ScrollChangedEventArgs e) { // 只对进入视口的项请求缩略图 foreach (var item in GetVisibleItems()) { if (item.Thumb null !item.Loading) { item.Loading true; _ Task.Run(() item.Thumb LoadThumb(item.Path)); } } }逻辑说明缩略图缓存要有上限比如最多缓存 2000 张超出按 LRU 淘汰。参数上缩略图尺寸建议 160px 左右太大内存涨得快太小看不清脸。这一步的“玄学”在于 GC 时机建议用ArrayPoolbyte复用缓冲减少大对象堆压力。5. 避坑与排查那些让扫描崩掉、聚类糊掉的真实问题5.1 扫描到一半内存暴涨然后崩现象扫描进行到一两万张时进程内存持续上涨最后OutOfMemoryException。原因通常是Bitmap没释放或者把所有缩略图都留在内存里。Bitmap实现了IDisposable但很多人忘了using。解决所有图像对象用using包住缩略图只保留当前视口需要的其余落盘或丢弃。另外把进程锁定 64 位给 GC 留足空间。5.2 同一个人被聚成好几个簇现象某位家人的照片被分成三四个簇每个簇都是他。原因通常是侧脸、戴帽子、光线差异导致特征距离变大或者阈值定得太小。解决先确认对齐步骤有没有做没对齐的话侧脸特征会偏得离谱其次把阈值适当调大但别一次调太多否则会合并不同人。我一般会引入“簇间合并”的半自动流程把中心距离很近的簇提示给用户一键合并。5.3 不同的人被合并成一个簇现象两个长得有点像的人被聚到一起。原因通常是阈值太大或者低质量脸模糊、遮挡参与了聚类把两个簇“桥接”了。解决聚类前过滤低质量脸Quality低于阈值的先不参与同时检查特征模型是不是被量化得太狠量化模型精度下降会明显拉高误合并率。5.4 视频里的人脸怎么处理现象照片扫得好好的一加视频就卡死或漏检。原因视频不能按帧全跑几十分钟的视频几十万帧跑不完。常见做法是按时间间隔抽帧比如每 2 秒抽一帧再对抽出的帧做人脸检测。参数上抽帧间隔取决于视频内容访谈类可以稀一点运动类要密一点。抽出的帧同样走检测、对齐、特征提取、入库只是MediaId指向视频并记录时间戳方便跳转。5.5 数据库写入成为瓶颈现象扫描速度前期很快后期越来越慢。原因每张脸一条INSERT没有事务SQLite 每次写都刷盘。解决批量写入几百条一个事务开启 WAL 模式把Embedding的写入放在事务里。参数上PRAGMA journal_modeWAL;和PRAGMA synchronousNORMAL;能明显提升写入吞吐代价是极端断电时可能丢最后几条对照片管理场景可以接受。6. 进阶技巧把识别质量再往上抬一档到这一步基本功能已经能跑了。但如果你想让“按脸找人”真正好用还有几个技巧值得投入。第一个是人脸质量分。不是所有检测到的人脸都值得入库。除了置信度还可以算模糊度拉普拉斯方差、遮挡比例、人脸框占图比例。我一般把质量分做成 0~1 的连续值聚类时按质量加权高质量脸对簇中心的贡献更大。这样即使有几张低质量脸混进来也不会把簇带偏。第二个是跨年龄段处理。同一个人十年前和现在的脸特征距离可能比不同人还大。常见做法是聚类时对时间跨度大的簇做二次校验或者干脆按“人年代”分簇展示时再合并。这个没有银弹我的经验是给用户一个“这是同一个人”的确认入口确认后把两个簇的中心做加权融合后续新脸就能正确归入。第三个是特征索引加速。六万条向量暴力算还能忍但如果你的库到几十万条每次新脸都和所有簇中心比就会慢。可以用 HNSW 或 IVF 这类近似最近邻索引C# 侧有对应的封装库。参数上HNSW 的M和efConstruction影响召回和内存一般M16、efConstruction200起步再根据召回率调。第四个是验证方法。怎么知道你的聚类好不好我会留一个手工标注的小验证集挑 50 个人、每人 10 张人工标好然后算聚类的准确率和召回率。每次调阈值或换模型都跑一遍这个验证集看指标是涨是跌。这个习惯帮我避免了很多“感觉变好了”的错觉。最后一个技巧是别把模型当黑匣子。ONNX 模型导出后用 Netron 看一眼输入输出确认预处理归一化均值方差、通道顺序和训练时一致。我踩过最冤的坑就是模型没错、代码没错但预处理用了[0,1]而训练用的是[-1,1]特征全乱聚类自然一塌糊涂。后来我养成了一个习惯任何新模型接入先用一张已知人脸跑两遍看同一张图的特征余弦相似度是不是接近 1不是就先查预处理。希望帮到你。本文还有配套的精品资源点击获取