---
url: https://www.dreamlu.net/mica-ai.md
---

# 🚀 mica-ai

> 让 Java 工程师也能玩转主流 AI 模型 —— **零 Python · 零 PyTorch · 纯 ONNX Runtime**

[![Java](https://img.shields.io/badge/JDK-8%2B-orange?style=flat-square\&logo=openjdk)](https://openjdk.org/)
[![Spring Boot](https://img.shields.io/badge/Spring%20Boot-2.7.x~4.x-brightgreen?style=flat-square\&logo=springboot)](https://spring.io/projects/spring-boot)
[![ONNX Runtime](https://img.shields.io/badge/ONNX%20Runtime-1.18.0-blue?style=flat-square\&logo=onnx)](https://onnxruntime.ai/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=flat-square)](https://github.com/lets-mica/mica-ai/blob/main/LICENSE)

`mica-ai` 给 Java 生态造的「AI 积木」：把主流 ONNX 模型封装成 `@Autowired` 就能用的 Bean，从此告别在 Java 里调 Python 微服务。

一行依赖，人脸检测 + 128d Embedding + 活体 + 头像 / 证件卡片提取 + 文件类型识别 + 中国车牌识别 + 文档版面分析开箱即用。

## 🎯 能力一览

| 能力 | 模块 | 核心模型 | 输出 | 商用 |
| ---- | ---- | -------- | ---- | ---- |
| 🎭 人脸检测 | [mica-ai-face](/mica-ai/core/mica-ai-face/) | YuNet | 人脸框 + 5 关键点 | ✅ |
| 🧬 人脸特征 | [mica-ai-face](/mica-ai/core/mica-ai-face/) | SFace | **128d** L2 归一化向量 | ✅ |
| 🛡️ 活体检测 | [mica-ai-face](/mica-ai/core/mica-ai-face/) | MiniFASNetV2 | real / replay / print | ✅ |
| 🖼️ 头像 / 证件卡片提取 | [mica-ai-face](/mica-ai/core/mica-ai-face/) | 几何变换 + USM/CLAHE | 正方形头像 / 矫正卡面 | ✅ |
| 📄 文件类型识别 | [mica-ai-filetype](/mica-ai/core/mica-ai-filetype/) | Google Magika `standard_v3_3` | **214 类** + mime / group | ✅ |
| 🚗 中国车牌识别 | [mica-ai-plate](/mica-ai/core/mica-ai-plate/) | HyperLPR3 v20230229 | 车牌号 + 10 类判型 + 颜色 | ✅ |
| 📐 文档版面分析 | [mica-ai-layout](/mica-ai/core/mica-ai-layout/) | PP-DocLayoutV3 | **25 类版面** + V3 阅读顺序 | ✅ |

## 📦 模块导航

解析完仓库结构后，按「核心引擎 / Spring Boot 接入 / 示例」三层组织：

### core —— 核心引擎（零 Spring，纯 Java）

| 模块 | 说明 |
| ---- | ---- |
| [mica-ai-core](/mica-ai/core/) | 聚合模块，本文档分组的入口 |
| [mica-ai-common](/mica-ai/core/mica-ai-common/) | 公共基础设施：ONNX 会话工厂、统一异常 |
| [mica-ai-face](/mica-ai/core/mica-ai-face/) | 人脸检测 / 对齐 / 128d 特征 / 活体 / 头像 / 证件卡片 |
| [mica-ai-filetype](/mica-ai/core/mica-ai-filetype/) | Google Magika 文件类型识别，214 类 |
| [mica-ai-plate](/mica-ai/core/mica-ai-plate/) | HyperLPR3 中国车牌识别 |
| [mica-ai-layout](/mica-ai/core/mica-ai-layout/) | PP-DocLayoutV3 文档版面分析 |

### starters —— Spring Boot 自动装配

| Starter | 配置前缀 |
| ------- | -------- |
| [mica-ai-starters](/mica-ai/starters/) | 聚合模块，统一设计说明 |
| [face-spring-boot-starter](/mica-ai/starters/mica-ai-face-spring-boot-starter/) | `mica.ai.face` |
| [filetype-spring-boot-starter](/mica-ai/starters/mica-ai-filetype-spring-boot-starter/) | `mica.ai.filetype` |
| [plate-spring-boot-starter](/mica-ai/starters/mica-ai-plate-spring-boot-starter/) | `mica.ai.plate` |
| [layout-spring-boot-starter](/mica-ai/starters/mica-ai-layout-spring-boot-starter/) | `mica.ai.layout` |

### 其他

* [mica-ai-example](/mica-ai/example/) — 可运行的 Spring Boot 集成示例与自动装配测试

## 🚀 快速开始

### 1️⃣ 添加依赖

```xml
<!-- ① 直接用核心引擎（零 Spring） -->
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-ai-face</artifactId>
    <version>${mica-ai.version}</version>
</dependency>

<!-- ② 或使用 Spring Boot Starter（自动注入 Bean） -->
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-ai-face-spring-boot-starter</artifactId>
    <version>${mica-ai.version}</version>
</dependency>
```

### 2️⃣ 30 秒跑通一个人脸识别（纯 Java）

```java
ModelConfig config = ModelConfig.builder()
    .detectionModelPath(Path.of("models/face_detection_yunet_2023mar.onnx"))
    .recognitionModelPath(Path.of("models/face_recognition_sface_2021dec.onnx"))
    .build();

try (ModelManager manager = ModelManager.create(config)) {
    FaceDetector detector = new FaceDetector(manager);
    FaceAligner aligner   = new FaceAligner();
    FeatureExtractor extractor = new FeatureExtractor(manager);

    BufferedImage img = ImageIO.read(new File("group.jpg"));
    List<FaceBox> boxes = detector.detect(img);
    for (FaceBox box : boxes) {
        try (Mat aligned = aligner.align(img, box)) {
            float[] feature = extractor.extract(aligned);   // 128d L2 归一化
            // 入库 / 检索交给你自己的向量库（Milvus / pgvector）
        }
    }
}
```

### 3️⃣ 一行配置开启 Spring Boot Starter

```yaml
mica:
  ai:
    face:
      enabled: true
      model:                              # ⚠️ 模型路径统一挂在 model 下
        detection:
          path: classpath:models/face_detection_yunet_2023mar.onnx
        recognition:
          path: classpath:models/face_recognition_sface_2021dec.onnx
```

```java
@Service
@RequiredArgsConstructor
public class FaceEnrollService {
    private final FaceDetector detector;            // ← 直接注入
    private final FaceAligner aligner;
    private final FeatureExtractor extractor;       // 128d
    private final FaceVerifier verifier;            // 1:1 比对
}
```

> 完整配置项、各能力 API 与调参见对应子模块文档。

## 🛠️ 环境要求

| 组件 | 版本 | 说明 |
| ---- | ---- | ---- |
| ☕ JDK | **8+** | 推荐 Temurin / Azul Zulu 8、11、17 |
| 📦 Maven | 3.6+ | 构建 / 打包 |
| 🧠 ONNX Runtime | 1.18.0 | Maven 自动拉取，CPU/GPU 可选 |
| 🖼️ OpenCV | 4.9.0（openpnp） | Maven 自动拉取对应系统 / 架构的原生库 |

> GPU 加速：把 `onnxruntime` 替换为 `onnxruntime_gpu`，并配置 `device` 为 `gpu`（需 CUDA Toolkit + 驱动）。

## 🔗 相关项目

* [mica-ppocr](/mica-ppocr/) — PaddleOCR / PP-OCRv6 的 Java 推理
* [mica-voice](/mica-voice/) — ASR / TTS / 声纹 / VAD / 说话人分离
* 上游：[OpenCV Zoo](https://github.com/opencv/opencv_zoo) · [Google Magika](https://github.com/google/magika) · [HyperLPR3](https://github.com/szad670401/HyperLPR) · [PaddleOCR](https://github.com/PaddlePaddle/PaddleOCR)

## 📄 License

Apache License 2.0，可放心用于商业项目；当前所有依赖模型均确认可商用（详见各模块 README 的 License 章节）。