👁️ 视觉引擎

视觉引擎的可信 .NET 技术组件名为 Microi.Vision。它接收 JPEG、PNG、WebP 图片或已经取出的连续视频帧，使用受控 ONNX 模型生成视觉特征；接口引擎再优先与当前租户的样本库匹配，未命中时立即返回“未匹配 / AI 识别中”，并按租户策略异步调用平台 AI 引擎。后台应用、菜单和工作台统一显示中性名称“视觉引擎”，不会强制显示 Microi 或吾码品牌。

📸 预览图

识别工作台：支持图片上传、摄像头取帧、样本匹配、AI 回退与结果追踪。

先看结论

商品、鱼类、蔬菜、建筑和经合法授权的人脸都使用同一条“样本录入 → 特征提取 → 数据库匹配 → 可选 AI 回退”链路。默认内置模型只是零部署近似图片指纹，适合联调和相同/近似样图；生产语义识别或人脸比对应安装经过许可证与数据集评估的 ONNX 模型包。

用户名称与技术组件

“视觉引擎”覆盖物体、商品、人员、建筑和以后扩展的工业缺陷等视觉任务，不只限定某个零售领域；Microi.Vision 只作为程序集、命名空间与开发 API 名称。职责分层如下：

层	负责	不负责
Microi.Vision .NET 类库	有界图片解码、ONNX Runtime、检测/分割、人脸对齐、特征向量、HNSW、IoU 跟踪与连续帧投票	业务表、商品名称、人员身份、日志与 AI 提示词
V8.Vision	把最小原子能力安全暴露给当前租户接口引擎	允许脚本指定模型文件路径、执行提供程序或其它租户
platform-vision-runtime	样本库优先匹配、状态机、私有文件、后台任务、业务 Hook	训练模型或把密钥交给前端
platform-vision-ai-worker	对未命中图片调用 Microi.AI，回写最终结果并清理敏感输入	把人脸模型猜测当成真实身份
platform-vision-custom-hook	留给租户追加日志、写业务表、触发通知等低敏元数据逻辑	接收图片、向量、AI 提示词或身份敏感信息
microi-vision 前端微服务	图片上传、摄像头取帧、连续识别、分阶段来源、最近记录、纠错与样本录入	在浏览器内持有模型或伪造最终匹配结论

识别状态机

图片 / 摄像头帧
        │
        ▼
Microi.Vision 检测/分割并提取目标特征
        │
        ▼
当前租户 Ready 样本 HNSW Top-K 比对
   ┌────┴──────────────┐
   │达到阈值           │未达到阈值
   ▼                   ▼
LocalMatched      AiPending / Unmatched
   │                   │ AI 开关开启
   │                   ▼
   │          持久后台任务调用 Microi.AI
   │                   │
   └──────────────► AiMatched / Failed

前端必须展示 MatchSource，不能把数据库相似度和 AI 置信度混成一个分数。HTTP 200 也不代表业务命中，必须同时判断 Code、Status 和 MatchSource。

Status	MatchSource	含义
Received	None	连续帧已分析，但投票尚未形成稳定结论
LocalMatched	Database	当前租户样本库达到阈值
AiPending	None	数据库未命中，AI 后台任务已受理
Unmatched	None	数据库未命中且 AI 回退已关闭
AiMatched	AI	AI 返回一般物体/商品语义结果
Corrected	Manual	用户已把历史识别修正为当前租户中的可信对象
Failed	None	流水线或 AI 调用失败，可按业务规则复核或重试
LowQuality	None	图片质量未达到策略下限，未进入判断

安装后的后台资源

官方“视觉引擎”应用安装到租户后，在“系统引擎”下创建一个父菜单“视觉引擎”和六个子菜单：

菜单	资源	用途
识别工作台	新前端微服务 microi-vision/workbench	上传、摄像头、连续帧、结果和样本录入
识别对象	mci_vision_subject	商品、鱼类、人员、建筑等可识别业务对象
视觉样本库	mci_vision_sample	对象图片、模型版本、受保护特征和质量状态
对象分类	mci_vision_category	商品、生鲜水产、蔬菜、肉类、人员、建筑等分类树
识别记录	mci_vision_request	数据库命中、AI 处理中、AI 结果、耗时和清理状态
识别配置	mci_vision_profile	模型 Key、阈值、Top-K、视频间隔、AI 回退和保留策略

核心接口引擎为 platform-vision-runtime，动作包含 Bootstrap、Capabilities、Dashboard、Subjects、Recognize、Enroll、Result、Recent 和 Correct；视频人脸图库另使用受保护的 CaptureFaces 与管理员 SaveCaptureSettings。核心引擎由商城应用以 Managed 策略维护；platform-vision-custom-hook 必须声明为 CreateIfMissing，升级不能覆盖租户自己的业务代码。

快速使用

视频巡检工作台

工作台的“视频巡检”模式支持私有录像上传、浏览器摄像头和已登记监控源。 海康等设备先由受信网关把 RTSP 转成浏览器可播放的 HLS；摄像头密码留在节点端。 手机摄像头需要 HTTPS、浏览器授权和能访问的视觉节点。录像的扩展名不代表实际编码， MPEG-PS/HEVC 等监控导出文件会先转为 H.264 播放副本，客户原件保持不变。

视频与六项实时指标采用一体深色面板，图片采集和结果分析使用相同设计，外壳和设置支持明暗主题； 手机支持竖屏和横屏布局，装饰不使用持续扫描动画。 默认使用当前租户已登记并通过 Bootstrap 校验的视觉服务地址；未登记时使用平台中继，用户仍可显式选择中继。 “行为已配置”仅表示配置存在，模型联通、实际候选结果及准确率须分别以运行和现场验收回执确认。

操作	结果与判定边界
在画面上绘制工位区域	按人员脚点判断是否在区内，框与区域适配视频黑边和缩放
不绑定员工	统计工位占用率；有人不等于指定员工在岗
绑定登记员工	经授权的人脸核验后统计该员工在岗率；身份不明时间单列
设置离岗宽限	短暂遮挡不计离岗；返回后保留每次开始、结束与持续时间
设置限制进入区域	核验员工/受邀访客的区域和有效期；未匹配登记人员进入复核时间线
设置安全帽/禁拍区域	对可见头部、手机使用和疑似拍摄进行异步行为复核
设置录像开始时间	历史录像按发生时间核验当时的邀请，不按观看录像的时间核验
录像库和历史会话	重新播放媒体、恢复区域与结果，按本人权限读取与导出报告

在岗率为 有效在岗时长 /（有效在岗时长 + 有效离岗时长）。 跳播、暂停后恢复、断流、低质量和身份未知时间不推算为离岗；录像覆盖率按全片时长单独显示；摄像头显示采样连续性。倒退后重新识别会保存旧会话并开始新会话，避免把同一段录像的离岗重复计数。 后台用签名帧、帧序号、版本条件更新保存结果，浏览器不能直接提交考勤数字。

人员检测与行为复核分别运行。录像检测框只显示与当前播放时刻相符的结果；迟到的检测和复核结果保留原采样时刻， 行为提醒可从记录回看原画面，不把旧框盖到当前帧。手机出现在画面中不等于正在使用， 手持手机不等于正在拍照；模型未就绪、目标太小或遮挡时返回未知。

模型验收

安装应用、接口测试通过和浏览器能播放都不能证明识别率达到 90%。 必须按人员、手机使用、安全帽、疑似拍摄和人员核验分别建立独立标注集， 报告 Precision、Recall、F1、误接受/误拒绝、未知占比、统计误差和目标硬件延迟。 缺少正例或人脸像素不足的类别应标为未验收，不能用“没有告警”算成识别正确。

视频模式新增 mci_vision_monitor_session、mci_vision_person 和 platform-vision-monitor。原有图片/样本识别入口继续保留。 视觉节点的安装、固定模型校验和监控网关配置见应用源码内 edge/README.md； 它只承担媒体协议与推理，人员准入、离岗统计和报告仍由当前租户的 Managed 接口引擎处理。

录入识别对象

先在“识别对象”录入业务事实，例如：

• 对象编号：FISH-CARP-001
• 对象名称：鲤鱼
• 所属分类：生鲜水产
• 对象类型：Product
• 识别模式：General
• 默认价格下限/上限、计价单位与币种：例如 18、35、斤、CNY

人员对象应使用 ObjectType=Person，保存事件会强制切换到 RecognitionMode=Face。人员分类只能选择 Face 或 All 识别域。

录入样本

不要直接在“视觉样本库”表单中粘贴向量。进入“识别工作台”，选择对象并上传清晰、来源合法、角度有代表性的图片，调用 Enroll：

var result = await V8.ApiEngine.Run('platform-vision-runtime', {
  Action: 'Enroll',
  SubjectId: '对象Id',
  FileName: 'carp-side.jpg',
  FileByteBase64: V8.FilesByteBase64['sample']
});
return result;

样本目标由 V8.Vision.Analyze 检测/对齐后生成对象级向量，再使用绑定当前租户和当前接口引擎的保护能力保存；旧宿主在升级窗口内才兼容回退到 V8.Vision.Extract。生鲜样本还可录入是否冰冻、新鲜度、预估价格、单位与币种，数据库命中时这些字段连同 Database 来源一起返回。公开结果、Hook 和列表默认都不返回向量正文。

单图识别

var result = await V8.ApiEngine.Run('platform-vision-runtime', {
  Action: 'Recognize',
  RequestId: V8.Method.NewUlid(),
  Mode: 'General',
  FileName: 'scale-camera.jpg',
  FileByteBase64: V8.FilesByteBase64['frame']
});

if (result.Code !== 1) return result;

if (result.Data.Status === 'AiPending') {
  // 先把“样本库未命中，AI 识别中”展示给用户，再按 RequestNo 轮询 Result。
}
return result;

同一个 RequestId 重试会读取原请求，不重复入队。AI 任务使用共享数据库后台任务，不依赖单机内存队列。

工作台把识别过程明确拆成两段：先显示“数据库正在匹配”；命中时显示“数据库已命中，无需 AI 回退”，未命中时显示“数据库未命中，正在由 AI 模型识别”。最终对象、新鲜度、冰冻状态和预估价格分别保留 Database、AI 或 Manual 来源，不把不同来源伪装成同一个可信度。预估价格仅作参考，收银仍应以门店商品主数据和实际称重为准。

连续视频帧

浏览器使用 getUserMedia 打开前置或后置摄像头，按 FrameIntervalMs 将画面压缩成 JPEG 帧后调用 Recognize。工作台提供开启、暂停、继续、立即识别当前帧和关闭；每次开启建立新的 StreamSessionId，每帧递增 FrameSequence，自动连续模式会跳过静止画面，人工点击“立即识别”则强制提交当前帧。服务端按 TrackId 做连续帧投票。手机浏览器必须使用 HTTPS（localhost 调试除外）。可信 .NET 宿主也可把 RTSP/WebRTC 解码后的帧流传给：

IAsyncEnumerable<DosResult<MicroiVisionExtractResult>> results =
    vision.RecognizeFramesAsync(frames, "general-dinov2-v1", "General", cancellationToken);

IAsyncEnumerable<DosResult<MicroiVisionAnalyzeResult>> detectedResults =
    vision.AnalyzeFramesAsync(pipelineFrames, "retail-yolox-siglip2-v1", "General", cancellationToken);

Microi.Vision 不直接接受调用方传入的任意 RTSP URL、摄像头账号或网络 Header。摄像头协议、断线重连和取帧留在可信宿主或边缘网关，可避免 SSRF、凭据泄漏和 API 进程长期持有视频连接。

工作台布局、最近识别与纠错

桌面工作台占满宿主可用宽度，把“采集与识别、识别结果、最近识别”放在同一行；上传竖图或打开摄像头后，画面使用有界 object-fit: contain，不会把页面向下撑高。手机竖屏在一个宿主可用高度内紧凑显示三块内容，短横屏切换为三列；页面本身不产生纵向滚动，最近记录列表只在自己的区域内滚动，并避开平台底部菜单和安全区。

“最近识别”中的缩略图来自 Recent/Result 返回的临时授权私有文件 URL，前端永远不读取或拼接原始 HDFS 路径。点击缩略图可查看当时画面；点击“修正”可选择当前租户中的正确对象、填写原因，并决定是否把该画面加入样本库。Correct 会把记录改为 Corrected/Manual、保存原始识别来源和审计信息；选择“同时存入样本库”时按来源请求幂等录入，避免重复样本。AI 结果不会未经人工确认自动进入可信样本库。

摄像头关闭必须先同步切换界面状态并使本次打开操作失效，再停止轨道、清空 srcObject。打开摄像头、video.play()、关闭和组件卸载之间使用操作令牌防止旧异步流程把已经关闭的摄像头重新置为开启。

V8.Vision 原子能力

V8.Vision 只允许选择宿主已经安装并完成 SHA-256 校验的 ModelKey：

var analyzed = await V8.Vision.Analyze({
  FileByteBase64: V8.FilesByteBase64['image'],
  FileName: 'fish.jpg',
  PipelineKey: 'general-yolox-dinov2-v1',
  Mode: 'General',
  FrameId: 'camera-01-000123',
  StreamSessionId: 'scale-01-session-42',
  FrameSequence: 123
});

var ranked = await V8.Vision.Search({
  QueryEmbeddingBase64: analyzed.Data.Detections[0].EmbeddingBase64,
  Candidates: candidateVectors,
  Threshold: 0.82,
  TopK: 5,
  EfSearch: 80,
  IndexKey: 'ready-general-samples'
});

var stable = await V8.Vision.Stabilize({
  Observations: recentTrackObservations,
  MinimumVotes: 3,
  WindowSize: 5,
  MinimumAverageConfidence: 0.55
});

方法	作用	硬边界
Analyze	检测/分割、多目标特征、人脸对齐与跟踪	只允许宿主安装且 SHA-256 通过的 PipelineKey
Search	HNSW 近邻检索	有界候选、TopK、EfSearch；小集合自动精确回退
Stabilize	连续帧多数投票	按租户、会话与 TrackId 隔离，窗口和 TTL 有界
Extract	单图提取特征	JPEG/PNG/WebP，默认解码前 16 MB
ExtractBatch	一次提取有界帧批次	默认最多 12 帧；仍逐帧取消检查
Compare	比较两个同维向量	余弦相似度，阈值必须在 0～1
CompareBatch	对候选集排序	默认最多 2,000 个候选、TopK 最多 50
GetCapabilities	返回模型、任务类型、许可证和就绪状态	不返回模型目录或宿主路径

完整签名见 V8 函数－后端。一般业务优先调用 platform-vision-runtime，只有编写自定义接口引擎时才直接组合原子函数。

模型与准确率

类库使用 ONNX Runtime C# 和图优化执行推理。模型包目录必须包含 model.json 和同目录 .onnx 文件，描述输入尺寸、RGB/BGR、均值、标准差、池化方式、来源、许可证和不可变 SHA-256。

当前内核已实现主流工程链路：YOLOv8/YOLOX/RT-DETR/SCRFD 常见检测输出、对象裁剪与人脸五点对齐、DINOv2/DINOv3/SigLIP2 类嵌入、ArcFace 类人脸嵌入、HNSW、IoU TrackId、连续帧投票，以及 CPU/CUDA/TensorRT/OpenVINO/DirectML 执行提供程序选择。它属于第一梯队常见的架构方向，但“架构已实现”不等于“任意模型与任意门店都达到第一梯队准确率”。

2026-09-03 的可复现鱼类负面基准使用 10 种鱼、每类 1 张独立样本和 1 张不同测试图：DINOv2-S INT8 为 Top-1 3/10、Top-3 7/10，CPU 热态端到端均值 98.8 ms、P95 115 ms；SigLIP2-B/16 INT8 为 Top-1 4/10、Top-3 4/10，CPU 热态均值 92.2 ms、P95 103 ms。因此，通用预训练向量 + 单样本不满足商超投产门禁；必须增加真实秤台多角度样本，微调鱼类/包装数据，并在目标硬件重新标定。完整素材、许可、逐项结果和失败项见仓库 AI-Project/microi/vision/TEST-REPORT.md。

生产建议建立独立模型基线：

场景	建议路线	注意事项
通用商品/物体	DINOv3/DINOv2、SigLIP2 等视觉嵌入模型导出 ONNX，使用真实门店样本做近邻匹配	模型代码、权重、训练数据和商用许可证分别审核；DINOv3 不能沿用 DINOv2 的许可证结论
多物体与秤面分离	安装经业务数据微调的 YOLO/RT-DETR 检测或分割模型，内核逐目标生成特征	COCO 通用权重没有鱼种细分类，不能直接当商超成品
人脸	安装 SCRFD/同级检测与 ArcFace embedding，并启用活体检测	InsightFace 代码与其官方预训练权重许可不是同一件事；商用权重必须单独审核
未知物体语义	Microi.AI 视觉模型异步回退	AI 标签是模型输出，不会自动写成可信商品主数据

模型名称不能代替验收。每个门店/摄像头应使用独立标注集测量 Top-1、Top-K、误接受率、误拒绝率、P50/P95 延迟和人工复核率；阈值按模型版本、镜头、光照和业务风险校准。内置 builtin-visual-fingerprint-v1 只适合同图/近似图联调，不得对外宣称为跨角度商品识别或生产人脸识别。YOLOX + DINOv2 的真实 ONNX 流水线已用官方示例图跑通多框、对象级特征和 TrackId，但该回归只验证解析/推理链路，不是鱼种准确率证明。

闭源源码与 NuGet 边界

Microi.Server/Microi.Vision/ 与 Microi.AI、Microi.WorkFlow 一样是独立闭源仓，只允许推送到公司内部 GitLab。创建人使用 Microi.Anderson.sln 时由 ProjectReference 加载源码；普通用户使用公开 Microi.net.sln 时只解析同版本 Microi.Vision NuGet 包。

根目录 Microi一键编译发布.sh 已把 Microi.Vision 纳入与 AI/Workflow 相同的 Obfuscar 清单：发布目录先混淆 DLL，再替换 nupkg 内原 DLL；缺少 .microi-encrypted 记录、混淆前后哈希不变或包内 DLL 哈希不一致都会阻止发布。模型权重独立部署，不进入源码仓和 NuGet。

五个闭源项目（Microi.net、Microi.AI、Microi.MCP、Microi.WorkFlow、Microi.Vision）必须完整进入同一加密链。闭源源码存在而加密脚本缺失时直接停止，不能按开源模式跳过。一键脚本记录实际 DLL 加密前后的 SHA-256，上传前读取真实 NuGet ZIP 和实际 Docker 镜像中的 DLL，与已验证加密产物核对；明文或旧文件、缺失回执、加密后重编译覆盖都会阻止发布。正式渠道的包与镜像还要另行回读验证。

人脸与关注人员边界

人脸模板属于高敏感生物特征：

• 录入前必须有合法处理依据、告知/同意、用途限制、访问控制和删除流程；
• 手工图片人脸模式要求本次明确同意；视频自动采集只在管理员已授权的当前租户开启，界面默认开关不能代替后端授权；
• 样本、特征、请求记录严格绑定当前租户，普通响应不返回受保护向量；
• 默认不保留人脸识别输入，AI Worker 完成或失败后都清理临时图片；
• 未命中人脸时，Microi.AI 只允许返回可见的中性描述，不得猜测真实姓名、罪犯身份、族群、健康、政治等敏感属性；
• “关注人员/涉案人员”命中只能作为人工复核线索，不能单独作为处罚、抓捕、解雇或身份认证依据；
• 高风险动作仍需菜单/表/行权限、状态机、人工复核、幂等与不可篡改审计。

AI 回退与数据保留

AiFallbackEnabled 默认开启，FaceAiFallbackEnabled 可单独关闭。数据库未命中时先返回 AiPending，让收银或监控页面保持响应；后台任务把私有临时图片交给当前租户配置的 Microi.AI 模型，完成后更新同一识别记录。对于水产、生鲜、蔬菜等普通物体，Worker 可一并返回冰冻状态、新鲜度百分比和价格区间/单位/币种，并把这些字段的来源标为 AI；这类模型估计不得冒充食品安全检测、检疫结论或门店正式售价。

AI 回退关闭时返回 Unmatched，不产生外部模型调用。调用失败返回 Failed，不能把网络错误改写成“未识别到商品”。通用图片按 RetainInputDays 清理；人脸模式默认立即删除输入。样本原图的长期保留需由业务管理员另行制定权限和期限。

应用商城交付

“视觉引擎”官方应用包包含5张基础图片表、2张巡检/人员表、1张中继技术槽位表及相应字段/索引，保留7个父子菜单与默认分类；接口为7个Managed核心和1个CreateIfMissing个性化Hook，并绑定 microi-vision 微服务版本。只分发分类种子，不导出客户识别配置、自动采集授权、示例录像列表、人脸回执、样本、会话或节点凭据。新租户由管理员首次保存采集设置时幂等创建默认策略；已有配置保持，不能靠安装包覆盖。安装后仍需要平台运行时包含 Microi.Vision 与 V8.Vision；只安装应用包不能替代 .NET/NuGet/Docker 升级。

应用包必须声明：

{
  "ResourcePolicies": {
    "ApiEngines": {
      "platform-vision-runtime": "Managed",
      "platform-vision-ai-worker": "Managed",
      "platform-vision-category-options": "Managed",
      "platform-vision-subject-options": "Managed",
      "platform-vision-monitor": "Managed",
      "platform-vision-edge-relay": "Managed",
      "platform-vision-edge-media": "Managed",
      "platform-vision-custom-hook": "CreateIfMissing"
    }
  }
}

上线验收清单

视频节点提供包含 vision + media + behavior 的 Compose：RF-DETR Large/ONNX Runtime 检测、 YuNet/SFace 人脸、本地 Qwen3-VL 行为候选复核和 MediaMTX 媒体网关。通用安装默认启动 vision + media， behavior 为可选 profile。API、DiyToken、租户和数据库复用吾码。 模型与节点是额外部署资源，应用发布不会自动安装；也允许复用已有本地Ollama/MediaMTX。 当前锁定的是 legacy RF-DETR Large 560 ONNX；模型卡与当时官方 COCO 权重声明 Apache-2.0。tile-small-v2 是小目标分块算法，不是 Small 权重标识。每个版本仍分别核验许可、来源和 SHA，不能将其它规格或代次自动视为同一授权，也不使用非商用人脸权重。 部署后能推理不代表达到客户90%；行为复核不能替代专用PPE/动作模型验收。 GPU精度转换必须经过数值和真实图片回归，出现漏检不得只因速度提高而启用；显存容量须同时覆盖检测与行为模型。

直接开始与实时看板

上传录像后点击“开启识别”即可，默认使用全画面工位；打开手机摄像头后自动开启。 指定工位属于可选设置：点击“设置工位”，拖动矩形或点选两个对角，再点画面上的 “应用工位”。“设置 → 恢复全画面”可取消自定义工位。无需先画区，录像发生时间 也不再是普通巡检的必填项；仅历史访客授权时段核验需要准确的发生时间，缺失时 该项保持待核验，不能使用观看时间判断违规。

主界面持续展示工位状态、工位占用率/绑定员工在岗率、手机行为、安全帽、离岗次数、 离岗总时长及逐次区间；拍摄行为和提醒在同页展示。未绑定员工时不能称为个人员工考勤。 手机、安全帽和拍摄通过异步任务返回候选结果，并标注原录像时刻；未配置、排队、复核中、失败与未知分别显示，不能当成“无违规”。

自 v1.9.9 起，旧节点本地录像与中继路径默认连续播放；需要逐帧核对时，可在设置中开启 跟随分析播放，采样期间保留当前帧，等待识别结果与统计保存完成后继续。此模式的播放速度受服务器和网络影响；用户暂停、拖动或换源后，迟到请求不会自动恢复旧录像。

旧节点录像与中继单帧路径的框仅在原采样时刻±120毫秒显示；慢结果不会覆盖当前画面。v1.9.11 增加下述可信录像时间轴路径，须同时更新应用接口与节点。已有页面或节点未升级时仍使用原路径，不能把连续播放本身当作稳定跟框验收。

右上角 服务设置 可检测连接，分别查看人员、行为、人脸模型状态。未配置表示节点没有连接行为模型，不是录像里“没有违规”；复核失败可在设置中查看原因。模型缺失时不反复提交无效请求，人员检测仍可独立使用。完整服务器编排和 NAS 配置见视觉引擎第三方服务。

人员与人脸神经网络推理由本地服务器承担，巡检浏览器不下载 MediaPipe/EfficientDet 或模型/WASM。 手机默认选择摄像头、优先后置镜头，可切换前后；采集上限720p/15fps，提交帧长边不超过1280像素。 页面复用抽帧画布，检测请求串行且完成后至少间隔500ms，失败自动退避，暂停或后台中止请求， 后台和离开页面释放摄像头。此修复降低已发现的端侧负载，实际温度仍需真机持续运行验收。 人数和统计以节点签名观测为准；过期或无效画面显示待判断，不能把断流当无人。 远景录像采用重叠分区提高小目标可见度；单凭一个手机目标仍不能认定正在使用或拍照。 手持手机大幅移动时继续标人，工位计时暂记未知，避免移动镜头制造离岗。

架构源码分工：Microi.Server/Microi.Vision 是闭源.NET内核； OfficialApplications/Vision/src 是Vue微服务，engines 是V8业务接口； edge 是另需部署的Python视频推理节点。发布前端应用或API镜像不等于安装了该节点。 该工程由 OfficialApplications/Resource/vision-release.json 锁定，不存在第二份嵌套的 OfficialApplications/OfficialApplications 源码根。

v1.9.5 的巡检页以视频主画面、紧凑工具栏和六项核心指标组成监控台，支持明暗主题。 手机竖屏、短横屏与桌面优先同屏展示画面和核心操作；离岗记录、候选行为与设置按需展开，避免长页堆叠。 暂停、切换录像和离开页面导致的正常播放取消不显示故障；自动播放受限时提示点击播放， 真实格式或播放错误仍给出中文提示。

可信录像时间轴与正式媒体存储

v1.9.11 的新录像路径通过已登记 HTTPS 节点直连。正式示例的 H264 播放文件存放在租户明确授权的 FileServerBak 公开对象中，浏览器直接播放；节点只按需 Range 解码，使用有界临时计算缓存，不长期复制全片。H265 原片可下载与浏览器可播放是两项验收。

可信公开对象登记需要 API 8.8.8 的已完成上传证明、节点 1.9.8 以及本版应用接口和表字段。当前商城发布链没有投影 ServerMinVersion 安装门禁，须由运维核验实际 API 版本和能力；本文的最低要求不等于安装器已强制阻止旧版。

环节	行为与边界
对象登记	管理员从已完成、公有回读通过的上传回执登记；对象、完整摘要、分块摘要和地址来自后端权威事实
连续分析	默认单帧、单请求；从 0 秒起每秒采样，慢推理不跳到播放前方。服务端取原帧并保存实际 PTS，手机不运行第二个解码器或人员模型
画面与统计	应用 1.9.14 默认静音连续播放，原时刻识别在后台进行；显示真实分析进度，可点击“看识别画面”核对已分析原帧。同步等待仍可手动选择，未覆盖时段未知，不延长旧框
暂停与历史	暂停、切源撤销本人的旧任务；历史只读查看，恢复识别另开会话，报告区分有效观测、分析范围与覆盖率
行为复核	已接受原帧按低频旁路复核，同图同 PTS；候选单独追加，不改考勤或正式违规数量

应用 1.9.13 会在暂停等待期间，将已回读窗口投影到仍停留在原时刻的解码画面，先建立同帧纹理锚点再继续播放。原帧短窗口内直接显示可信人员或人脸框，之后由当前纹理支持跟随；这项显示修复不会扩大有效统计范围，也不代表检测准确率已经达标。

应用 1.9.14 将默认播放和后台分析分开，避免慢节点把视频长期停在零秒；仍使用相同的可信模型与阈值。首帧已验收即可单独查看，不必等到第二帧才看得到原框。后台分析落后于播放时，不把过期框贴到当前人物上，也不把未分析时段计入考勤。示例清单只登记已完成公开校验且可播放的 H264 副本；H265 原片已经入桶，不等于相应示例已经可播放。

应用 1.9.15 修复播放过程中拖动进度条被播放时钟改回的问题：鼠标或触摸拖动保留所选位置，松开后跳转，取消拖动不跳转；键盘操作继续支持。录像里的清晰人脸可使用既有快脸通道独立定位和跟随，拖动后清除旧框再重新采样。远处看不清脸的全身人员仍依赖人员模型，不能用人脸定位通过来宣称全身实时跟随或90%准确率已经达标。

拖动只改变观看位置，连续分析仍按固定媒体秒推进；回放按原会话读取已分析区段。等待不是用户暂停，主动暂停后新结果不会自动重开。每秒采样不保证覆盖短于一秒的事件，无效画面和末尾未覆盖区间仍明确未知。

分析窗口失败不撤销已经保存的可信帧；页面可从平台按原会话、代次和时刻回读。新路径只支持平台登记的规范 H264 MP4 与可信 HTTPS 直连；旧节点本地 HLS、平台中继和摄像头采样保留兼容。当前部署包与正式运行是否支持新路径，应以节点 capabilities 和对应应用版本为准。

同一帧的身份核验与自动归档继续遵守现有租户授权。姓名在后台修改后，回读显示当前名称；原始帧与统计封存不变。只有已授权的私有后端可接收模板和裁剪，公开播放文件不开放人脸样本。

人脸框、持续跟随与统计边界

v1.9.5 节点默认用 YuNet 定位可见人脸，返回真实 faceBox；画面优先显示脸框，没有合格脸框时回退真实人体框。仅检测到脸时不会补画不存在的全身框，也不因此进行身份比对或存档。

摄像头与直播在两次服务端结果之间使用小尺寸灰度纹理跟随。迟到结果必须从该请求的原帧初始化，再有界重放到当前帧；只有纹理、正反向校验和运动连续性通过才继续绘制。遮挡、离开、低纹理、超时或切源会清框，不能无限保留旧框。它不在手机运行神经网络，也不新增考勤证据；连续跟随可见时，统计仍可能因缺少新签名观测显示“待判断”。

节点 v1.9.8 增加独立 YuNet 快脸定位：当前 DiyToken 授权，最多长边 640 像素、一个在途请求，独立于慢人员推理；只回真实脸框和原采样绑定，不提取身份向量或归档。相机页面以及应用1.9.15的录像页面可单独显示“人脸”框，它不直接增加人员数量或考勤，没有脸也不能宣布无人。鉴权网络、模型并发及手机编码耗时需另测，不能把模型单次耗时当端到端时延。

原正式人员观测中，仅有脸框可证明全画面内有人，指定工位仍需要人体脚点；不能用脸框下缘冒充脚点。占用率旁须同时看有效观测与覆盖范围，历史有效片段的 100% 不表示当前一定在岗，也不代表整段录像全部已分析。低负载跟随测试和模拟手机布局不能代替物理手机持续温控验收。

授权人脸图库与租户示例监控

管理员在“服务设置”查看自动采集授权与开关。只有当前租户明确启用 AutoCaptureFaces、当前用户具备管理员权限且后端返回 CanCaptureFaces=true 时，视频采集才生效；新租户默认关闭。普通租户安装包不携带其它租户的授权与录像配置。

合格人脸按私有签名帧进入“识别对象”和“视觉样本库”：未知对象先命名为“未命名人员”，后台改名后，后续匹配从当前对象记录读取名称并显示。图库使用独立 opencv-sface-2021dec-gallery-v1 模型空间；gallerySubjectName 仅为图库名称，不等于员工登记、邀请授权或登录身份。

采集受质量、模糊、大小、相似度与数量限制；模糊匹配暂不新建，每帧最多新增一张，每人最多三张并间隔至少 30 秒。帧回执和参数化当前读防止并发重试重复建档；当前自动建档事务已按 MySQL 验证，其它提供商失败关闭。图片私有保存，模板由当前租户的 runtime 保护，不进入浏览器或普通日志。

v1.9.6 的直连与中继均仅对权威后端明确分类的存储/建档运行故障降级：显示归档失败，保留当前真实人员、人脸检测结果，新增样本数为 0。签名、租户或权限失败，以及网络超时、无分类或畸形回执仍失败关闭；不能将所有后端异常都描述为“不影响识别”。

v1.9.7 的“示例监控”仅共享当前租户唯一启用默认策略 ExampleVideosJson 中登记的 Ready 录像。已登录用户可以播放和识别这些示例，即使原上传者是另一位管理员；桌面可从该入口选择示例，手机首次进入仍默认摄像头。节点直连通过当前用户 DiyToken 核验权威设置，中继从服务器策略生成只读授权；请求自行传入的授权名单无效。签名中的 owner/session 仍属于当前查看者，撤销后新请求拒绝。

这种共享不开放其它用户的普通录像列表、删除、上传或人脸样本，也不把全部租户录像变成示例，配置不随官方种子包导出。另行明确授权的 FileServerBak BackupPublic 原片匿名下载，和此处需登录的播放/识别权限分别验收；匿名下载不等于匿名识别。图库图片与人脸模板仍保持私有。

异步候选行为复核

安全帽、手机使用与可见拍摄动作通过单并发行为任务处理，状态包括排队、执行、完成、失败、取消与过期。页面不长时间等待同步复核；暂停、换源或离开时取消本次任务。完成结果保留原帧时间、模型摘要和“疑似／需复核”提示，不替换当前人员框，也不重新累计在岗时间。

当前三类输出进入候选记录，不计正式违规告警。没有发现候选也不等于该能力已超过 90%；模型未配置时不提交无效任务。通用安装默认关闭行为服务；显式评估可使用本地候选模式，正式业务启用仍须逐项独立验收。部署、JSON 有效、少量样图或模型自己的置信度都不能代替验收。

Python 不是模型的必需语言：Microi.Vision 已具备 ONNX Runtime，可继续承接视频 取帧、相同模型推理与媒体管理。当前版本尚未迁移，Windows 可原生运行节点，无需额外 Docker。 迁移目标可以是随吾码 API 部署，但 FFmpeg 原生编解码、模型权重/GPU 和行为模型运行资源 仍需提供；相同权重的预处理、后处理、身份特征和连续时间线必须逐项回归后才能称效果一致。

手机 HTTPS 连接与私有录像播放

视频巡检的“服务设置 → 连接方式”可选择“平台 HTTPS 中继”。手机在可信 HTTPS 的吾码页面中打开摄像头；节点通过出站 HTTPS 领取请求，浏览器无需访问电脑的 127.0.0.1，也无需给本机开放公网端口。页面本身仍须满足浏览器的安全上下文和摄像头授权要求。已有反向代理或已登记的可信 HTTPS 节点可继续直连。

使用 NAS 中继时，在服务器部署步骤中填写当前吾码平台地址与租户，不在浏览器填写 NAS 内网地址。直连时，管理员先在“系统设置 → 开发配置 → 视觉服务地址”字段（sys_config.VisionEdgePublicBase）登记 HTTPS 公开地址；工作台通过 Bootstrap 校验后默认使用该地址，不要求用户重复填写，仍可在服务设置显式选择平台中继。签名密钥 Vision.Edge.SigningKey 继续保存在“安全与服务接入”；不要重新生成或覆盖正在使用的密钥，也不要把它填到浏览器。

群晖专用 1.9.7 方案使用 /volume1/docker/microi-vision/deployment，固定 CPU 节点、Ollama Instruct 与 MediaMTX 三服务，行为开启为异步候选；通用安装仍默认两个基础服务。兼容编排以 cpu_shares 替代该 NAS 不支持的 CFS 硬配额，保留内存上限和模型只读挂载。CPU shares 是相对权重，不是硬上限；该 DSM 已报告 PIDs limit discarded，所以 YAML 的 pids_limit 并未实际强制生效。初始化、受控断点恢复和最终固定镜像回执已在该 NAS 实际读回；基础节点与 HTTPS 反代已经运行。新版本升级、行为输出和各项准确率仍需各自验收。

现场 DSM 已验证 https://hub.microi.net:1806/health 返回 ready=true，HTTPS 证书有效；反代链为 1806 → 127.0.0.1:1807 → 容器61502，匿名 capabilities 被拒绝，平台页面来源 CORS 已回读。当前现场已运行节点为 1.9.7，行为为 candidate、中继关闭，未由健康状态推断全部能力通过。新 1.9.8 CPU/CUDA 镜像已经正式发布并独立回读，固定摘要见DSM 离线三服务部署；镜像发布不等于 NAS 已更新，须与 1.9.11 应用按原安装标识升级后另验。

该 NAS 的 6 张诊断图、18 次逐模型实测中：YuNet 63–70 ms，YOLOX-S 589–1024 ms，RF 单全幅 9.89–15.61 s（ORT 4 线程、OpenCV 1 线程）。YOLOX 存在机械误框和真人漏检，不能作为默认人员替代；RF 也存在远景漏检。逐模型依次加载的进程峰值约 1.25 GiB，不是三模型并发预算。这组诊断不是独立准确率集，也不包含网络、人脸比对、行为模型和完整分块开销；不能宣称 90% 或实时。

中继复用 DiyToken、platform-vision-edge-relay 和 platform-vision-edge-media，不建立第二套身份。节点使用可吊销、有到期日、仅允许中继接口的用户访问密钥，兑换受限 DiyToken；Windows 原生节点将凭据存为当前安装用户的 DPAPI 密文 private/relay.key.dpapi。访问密钥须包含运行时要求的 page:open 以及 api-engine:run，不授予表单读写范围。密钥失效或节点离线时请求明确失败，不能回退为匿名识别。

mci_vision_edge_job 只保存16个固定技术槽位和版本围栏，不保存图片或人脸特征；私有帧与结果存于短期加密缓存。视频按512KiB分片上传，每段校验SHA-256；节点保留原始视频，生成私有H.264播放副本。跨平台播放采用带短期票据的HLS，720p播放分段和原分辨率识别帧分开处理。检测从节点提取录像原始帧，异步行为复核引用同用户的短期内存帧，不重复上传原图。

手机采用页面内播放与大画面模式，使SVG区域及识别框继续覆盖视频；iOS原生视频全屏不能承载页面叠加。开始画区会收起规则面板并定位画面，完成/撤销/取消控件保持可触达；竖屏、横屏和小屏控件至少44px。自动播放被浏览器阻止时，用户可点击“播放”继续。人员录入照片先在浏览器内缩放，原图不进入中继持久存储。

以上中继依赖视觉应用 v1.6.0 资源和支持受控HTTP响应、受保护秘密与受限DiyToken的后端；发布、目标安装、节点连接和物理手机/海康设备验收分别记录。

v1.6.1补齐上传取消与回收：传输中可取消，失去浏览器的未完成上传也可从录像库取消；节点在15分钟无分片进展后回收临时分片并释放名额。合并/转码已经接管时继续处理，用户可在录像库查询结果。原始复核帧在110秒到期后按15秒周期主动移出内存缓存；到期回收不依赖下一次识别。

90%以上的验收口径

scripts/evaluate-accuracy.mjs 对独立留出集按 person / phoneUse / noHelmet / photography / unauthorizedEntry / workstationPresence 分项验收。每项至少30个正例、30个反例和3组独立场景；准确率、精确率、召回率、特异度与有效输出覆盖率均须超过90%。未知输出仍在分母中，缺少拍摄正例、身份真值或某一类别时不得给出整体达标结论。该样本下限是验收门禁，不是统计充分性的保证；正式验收还应报告样本构成、置信区间与客户独立复核。

输入标签格式为 {protocol:"VisionAccuracy/1", split:"holdout", independentLabels:true, cases:[{id, capability, sourceSha256, group, expected:true, predicted:true}]}；predicted:null 表示未知。人工必须真实确认独立标注，不能只填写布尔标记即称有了真值。离岗次数、区间与在岗率另外对照连续标注时间线验证误差，不能用单帧准确率替代时序统计验收。

• [ ] 当前租户8张基础/巡检/技术表、全部声明字段/索引和7个父子菜单均远端回读通过；
• [ ] microi-vision/workbench 的私有源码清单、公开构建清单、路由和哈希一致；
• [ ] V8.Vision.GetCapabilities() 明确区分内置指纹和生产模型包；
• [ ] 同一图片录入后再识别返回 LocalMatched/Database，相似度达到配置阈值；
• [ ] 未知图片先返回 AiPending，随后同一 RequestNo 收敛为 AiMatched 或 Failed；
• [ ] 数据库匹配中、数据库命中/失败、AI 识别中和最终来源在界面上分阶段可见；
• [ ] 摄像头可暂停、继续、强制识别当前帧和关闭，StreamSessionId/FrameSequence 连续且自动模式不会反复提交静止帧；
• [ ] 关闭 AI 后未知图片直接返回 Unmatched，没有后台任务；
• [ ] 摄像头单帧与连续帧能停止、恢复，不会无限并发或重复入队；
• [ ] 桌面采集/结果/最近识别同屏且占满宿主可用宽度；390×844 竖屏和短横屏均无页面级滚动、无底部菜单遮挡；
• [ ] 最近记录可通过授权 URL 查看原画，可人工纠错，并可选择幂等保存为样本；历史响应不泄漏原始文件路径；
• [ ] 生鲜的冰冻状态、新鲜度和预估价格分别显示值与来源，数据库字段优先、AI 仅在未命中后回退；
• [ ] 工作台跟随宿主租户主题色、浅色/深色即时切换，且至少通过一个非默认主题色的真实浏览器视觉验收；
• [ ] 人脸未明确同意时前端阻止提交，后端也执行独立校验；
• [ ] 向量、图片 Base64、模型路径、AI 密钥和敏感身份不出现在公开响应或普通日志；
• [ ] 真实标注集记录准确率、误接受/误拒绝、P95 延迟和人工复核率；
• [ ] 源码测试、商城发布、平台制品发布、目标节点升级和真实浏览器验收分别留证。

相关文档

• V8.Vision 后端 API
• AI 引擎
• 前端微服务
• 应用商城
• 任务调度
• 分布式存储
• 平台安全与兼容基线