Snet.Yolo.Server 26.236.1

<h1 align="center">🔍 Snet.VisualIdentity</h1>

<p align="center"> <img width="120" height="120" src="https://api.snet.cn/pic/nuget.png" alt="Snet Logo"/><br/> </p>

<p align="center"> <b>基于 .NET 10 的 YOLO 多模型智能视觉识别平台</b> </p>

<p align="center"> <img src="https://img.shields.io/badge/.NET-8.0-blue?logo=dotnet"/> <img src="https://img.shields.io/badge/.NET-10.0-blue?logo=dotnet"/> <img src="https://img.shields.io/badge/license-MIT-green"/> <img src="https://img.shields.io/nuget/v/Snet.Yolo.Server?color=blue"/> <img src="https://img.shields.io/github/stars/shunnet/VisualIdentity?style=social"/> </p>

<p align="center"> 🚀 高效 · 🧩 灵活 · 📦 易部署 · 🔒 安全 </p>

<p align="center"> <a href="https://snet.cn"><b>🌐 官方网站</b></a> · <a href="https://github.com/shunnet/VisualIdentity"><b>📦 GitHub</b></a> · <a href="https://snet.cn/EaiUj"><b>🎬 演示视频</b></a> · <a href="https://www.nuget.org/packages/Snet.Yolo.Server"><b>📦 NuGet</b></a> </p>

<p align="center"> 📖 <a href="README.en.md"><b>English</b></a> | 简体中文 </p>

🌟 项目简介

VisualIdentity 是一个开箱即用的智能识别平台：结合 .NET 的现代化能力、YoloDotNet 高性能推理引擎与 SQLite 轻量数据管理，解决「多模型部署 + 多任务识别」的落地痛点——检测、分类、分割、姿态估计、定向检测 五种任务统一管理、按需切换。

💡 .NET badge：核心库 Snet.Yolo.Server 多目标 net8.0 / net10.0；API 服务与工具均基于 .NET 10。

✨ 核心特性

🎯 应用场景

🏗️ 项目架构

VisualIdentity/
├── Snet.Yolo.Server/              # 🧠 核心推理引擎 + 数据模型（net8.0/net10.0 双目标）
├── Snet.Yolo.Api.Shared/          # 🔗 共享 API 层（Shared Project：控制器 / 安全 / 图片处理）
├── Snet.Yolo.Api.Cpu/             # 🖥️ CPU API（HTTP 5157 · HTTPS 7257）
├── Snet.Yolo.Api.Cuda/            # 🎮 CUDA / TensorRT API（HTTP 5158 · HTTPS 7258）
├── Snet.Yolo.Api.OpenVino/        # 🔌 OpenVINO API（HTTP 5159 · HTTPS 7259）
├── Snet.Yolo.Api.CoreML/          # 🍎 CoreML API（HTTP 5160 · HTTPS 7260）
├── Snet.Yolo.Api.DirectML/        # 🪟 DirectML API（HTTP 5161 · HTTPS 7261）
├── Snet.Yolo.Tool/                # 🛠️ WPF 桌面调试工具
├── Snet.Yolo.Test/                # 🧪 集成测试（控制台）
├── Snet.Py/                       # 🐍 Python 模型导出脚本
└── appsettings.json               # ⚙️ 全局配置

🔄 数据流

客户端上传图片 → API 控制器（参数验证 + CSRF 检查）→ 速率限制中间件
→ ManageOperate（数据库查询模型路径）→ IdentityOperate（加载模型 + 硬件加速）
→ YoloDotNet 推理（GPU / CPU）→ ResultHandler（结果转换）
→ ImageHandler（标注绘制 + 磁盘存储）→ 返回 JSON + 图片 URL

⚡ 快速开始

前置要求

• .NET 10 SDK
• 至少一个 ONNX 格式的 YOLO 模型（导出方法）

1️⃣ 克隆仓库

git clone https://github.com/shunnet/VisualIdentity.git
cd VisualIdentity

2️⃣ 运行 CPU 版本 API

cd Snet.Yolo.Api.Cpu
dotnet run

浏览器访问 http://localhost:5157/swagger 查看 Swagger UI（仅 Development 环境）。

3️⃣ 上传模型并推理

# 1. 上传 ONNX 模型
curl -X POST http://localhost:5157/Operate/AddAsync \
  -F "file=@your_model.onnx" \
  -F "describe=我的检测模型" \
  -F "onnxType=ObjectDetection"

# 2. 快速推理（仅坐标 / 标签 / 置信度）
curl -X POST http://localhost:5157/Operate/IdentityAsync \
  -F "onnxIndex=1" -F "file=@test.jpg" \
  -F 'paramJson={"Confidence":0.2,"Iou":0.7}'

# 3. 完整推理（标注图 + 坐标 + 图片 URL）
curl -X POST http://localhost:5157/Operate/IdentityDrawAsync \
  -F "onnxIndex=1" -F "file=@test.jpg" \
  -F 'paramJson={"Confidence":0.2,"Iou":0.7}'

📦 NuGet 安装

在您自己的 .NET 项目中使用 VisualIdentity 核心库：

# 核心推理库（必装）
dotnet add package Snet.Yolo.Server

# 根据硬件任选其一（⚠️ 只能选一个）
dotnet add package YoloDotNet.ExecutionProvider.Cpu      # 🖥️ 通用 CPU
dotnet add package YoloDotNet.ExecutionProvider.Cuda     # 🎮 NVIDIA GPU + TensorRT
dotnet add package YoloDotNet.ExecutionProvider.OpenVino # 🔌 Intel OpenVINO
dotnet add package YoloDotNet.ExecutionProvider.CoreML   # 🍎 Apple Silicon
dotnet add package YoloDotNet.ExecutionProvider.DirectML # 🪟 Windows GPU

💡 C# 调用示例

using SkiaSharp;
using Snet.Model.data;
using Snet.Yolo.Server;
using Snet.Yolo.Server.handler;
using Snet.Yolo.Server.models.data;
using Snet.Yolo.Server.models.@enum;
using YoloDotNet.ExecutionProvider.Cpu;
using YoloDotNet.Extensions;
using YoloDotNet.Models;

// 创建推理实例（自动缓存，配置不变时复用）
var identity = IdentityOperate.Instance(new IdentityData
{
    Hardware = new CpuExecutionProvider("/path/to/model.onnx"),
    IdentifyType = OnnxType.ObjectDetection,
    SN = "my-detector"
});

using SKImage image = SKImage.FromEncodedData("/path/to/image.jpg");

// 执行推理
OperateResult result = await identity.RunAsync(new ObjectDetectionData
{
    Confidence = 0.23,  // 置信度阈值
    Iou = 0.7,          // 交并比阈值
    File = image.Encode().ToArray()
});

// 获取结果并绘制标注框
var detections = result.GetObjectDetectionResult()?.ToObjectDetection();
if (detections is { Count: > 0 })
{
    foreach (var d in detections)
        Console.WriteLine($"{d.Label.Name}: {d.Confidence:P1} @ {d.BoundingBox}");

    using SKBitmap annotated = image.Draw(detections);
    // 保存或显示 annotated...
}

identity.Dispose(); // 释放 GPU 资源

🔌 API 接口文档

📋 模型管理

🧠 推理接口

📌 推理接口为 POST multipart/form-data 提交（onnxIndex、file、paramJson 均为表单字段），以下额外参数同样以表单字段传入：

🖼️ 历史图片

🏥 健康检查

paramJson 参数格式

⚙️ 配置文件

appsettings.json

{
  "AllowedOrigins": [],           // 🔒 CORS 白名单，空数组 = 拒绝所有跨域
  "RateLimit": {
    "PermitLimit": 120,           // ⏱️ 每分钟允许的请求数
    "WindowMinutes": 1,           // ⏱️ 时间窗口（分钟）
    "QueueLimit": 20              // ⏱️ 超出后的最大排队数
  },
  "ConfigModel": {
    "NameFormat": "yyyyMMddHHmmssffffff",              // 🏷️ 文件名时间格式
    "OriginalImageNamingFormat": "{0}-Original.jpeg",  // 🖼️ 原图命名
    "ResultImageNamingFormat": "{0}-Result.jpeg",      // 🎨 标注图命名
    "DetailsNamingFormat": "{0}-Details.ini",          // 📄 详情文件命名
    "RetentionDays": 30                                // 🗑️ 历史数据保留天数
  }
}

环境变量支持

⚠️ Swagger UI 仅在 Development 环境下启用，生产环境自动关闭。

🧠 支持的任务

🦴 姿态估计 — 内置跌倒检测

YoloPoseViewModel 集成实时跌倒检测算法（FallDetector），基于 17 个人体关键点进行多维度分析：

✅ 已验证的 YOLO 模型

以下 YOLO 模型已经过 YoloDotNet 与 Snet.Yolo.Server 的完整推理测试与验证：

🖥️ 执行提供者

⚠️ 每个项目 / 进程只能引用一个执行提供程序包。混合使用会导致运行时冲突（DLL 重复加载、符号冲突）。

💡 ONNX 模型导出

使用 Python (Ultralytics)

pip install ultralytics
python Snet.Py/Snet.Py.py

手动导出

# YOLOv5u–YOLOv12 (opset 17)
yolo export model=yolov8n.pt format=onnx opset=17

# YOLOv26 (opset 18)
yolo export model=yolo26n.pt format=onnx opset=18

📌 使用正确的 opset 版本可确保与 ONNX Runtime 的最佳兼容性与推理性能。

🐳 Docker 部署

构建镜像

# CPU 版本
docker build -t snet-yolo-cpu -f Snet.Yolo.Api.Cpu/Dockerfile .

# CUDA 版本（需要 NVIDIA Container Toolkit）
docker build -t snet-yolo-cuda -f Snet.Yolo.Api.Cuda/Dockerfile .

# OpenVINO 版本
docker build -t snet-yolo-openvino -f Snet.Yolo.Api.OpenVino/Dockerfile .

运行容器

docker run -d -p 8080:8080 \
  -v /path/to/models:/app/wwwroot/onnxs \
  -v /path/to/data:/app/wwwroot \
  snet-yolo-cpu

curl http://localhost:8080/health   # 健康检查

📝 容器内部暴露 8080（及 8081）；CoreML（仅 macOS）与 DirectML（仅 Windows）不支持 Docker，应直接在目标系统上运行。

🧪 测试

cd Snet.Yolo.Test
# 设置环境变量后运行控制台集成测试
export YOLO_IMAGE_PATH="/path/to/test.jpg"
export YOLO_MODEL_PATH="/path/to/model.onnx"
export YOLO_TYPE="ObjectDetection"
dotnet run

🔒 安全特性

📈 性能优化

推理耗时构成（参考值，CPU 模式）

HTTP 接收        ~   5ms
图片解码         ~  20ms
ONNX 推理        ~ 150ms（取决于模型大小和硬件）
结果转换         ~   5ms
标注绘制         ~  30ms（仅 IdentityDraw 模式）
磁盘写入         ~  10ms（并行，不阻塞响应）
────────────────────────
总耗时 (快速)    ~ 180ms
总耗时 (完整)    ~ 220ms

📚 依赖组件

🙏 致谢

📜 License

本项目基于 MIT 开源协议 —— 自由使用、修改、分发。

📄 完整条款请阅读 LICENSE 文件。

⚠️ 软件按「原样」提供，作者不对使用后果承担责任。

📈 Star History

<a href="https://www.star-history.com/?repos=shunnet%2FVisualIdentity&type=date&legend=bottom-right"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=shunnet/VisualIdentity&type=date&theme=dark&legend=bottom-right&sealed_token=jvjH1AZFSXflOGVE7gveyIW2Bq008loM9hOu9VceYDivd2bPkD0fEyfe8zFiqRkP-XIlgwg-b5OQTyLQq9rBBx_ERIk7NBQmgWubF8Akb13yd8u0s1ZBLA"/> <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=shunnet/VisualIdentity&type=date&legend=bottom-right&sealed_token=jvjH1AZFSXflOGVE7gveyIW2Bq008loM9hOu9VceYDivd2bPkD0fEyfe8zFiqRkP-XIlgwg-b5OQTyLQq9rBBx_ERIk7NBQmgWubF8Akb13yd8u0s1ZBLA"/> <img alt="Star History Chart" src="https://api.star-history.com/chart?repos=shunnet/VisualIdentity&type=date&legend=bottom-right&sealed_token=jvjH1AZFSXflOGVE7gveyIW2Bq008loM9hOu9VceYDivd2bPkD0fEyfe8zFiqRkP-XIlgwg-b5OQTyLQq9rBBx_ERIk7NBQmgWubF8Akb13yd8u0s1ZBLA"/> </picture> </a>