5 分钟快速开始 ​

不必读完所有文档。先回答一个问题：你现在要解决的是什么？

你要解决的问题从这里开始5 分钟后你能看到
微服务里缺工具类、HTTP、Redis、分布式锁路径 A · 微服务底座一个能发 HTTP 请求的 Java 类
证件 / 票据 / 文字识别，不想再维护 Python 服务路径 B · 本地化 AI一张图片进去，结构化字段出来
语音识别 / 合成 / 声纹，且不能联网路径 C · 语音能力一段 wav 进去，文字出来
自建 TCP / MQTT 设备接入路径 D · 网络与 MQTT一个能连上并订阅主题的客户端

环境要求 ​

组件版本说明
☕ JDK8+全部项目最低 JDK 8；推荐 Temurin / Azul Zulu 8、11、17
📦 Maven3.6+或 Gradle 6+
🧠 ONNX Runtime1.18.0AI 相关模块由 Maven 自动拉取，CPU / GPU 可选
🖼️ OpenCV4.9 ~ 4.10（openpnp）由 Maven 自动拉取对应系统 / 架构的原生库

Spring Boot 2.7 ~ 4.x 均可；Solon 由 mica-voice-solon-plugin 等独立插件支持。

路径 A · 微服务底座 ​

1. 加依赖（子模块按需引，版本号建议用 property 统一管理）

xml
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-core</artifactId>
    <version>${mica.version}</version>
</dependency>

2. 直接用

java
// mica HTTP 请求
String html = HttpRequest.get("https://www.dreamlu.net/")
    .useSlf4jLog(LogLevel.BODY)
    .execute()
    .asString();

3. 往下走

  • 全部子模块（18 个：HTTP / Redis / 分布式锁 / IP 归属地 / 节假日 / 验证码 …）→ mica 文档
  • 样板代码自动生成（spring.factories / FeignClient 元数据）→ mica-auto 文档

路径 B · 本地化 AI ​

1. 加依赖

xml
<!-- Spring Boot Starter：自动注入 Bean -->
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-ai-face-spring-boot-starter</artifactId>
    <version>${mica-ai.version}</version>
</dependency>

2. 一行配置

yaml
mica:
  ai:
    face:
      enabled: true
      model:
        detection:
          path: classpath:models/face_detection_yunet_2023mar.onnx
        recognition:
          path: classpath:models/face_recognition_sface_2021dec.onnx

3. 一行调用（以离线 OCR 的证件结构化为例）

java
@Autowired
private PPOcrTemplate ppocr;

@PostMapping("/ocr/vehicle")
public VehicleLicenseResult vehicle(@RequestParam MultipartFile file) throws IOException {
    return ppocr.vehicleLicense().parse(file.getBytes());
}

4. 往下走

  • 人脸 / 活体 / 128d 特征 / 车牌 / 文档版面 / 文件类型 → mica-ai 文档
  • 行驶证 / 身份证 / 银行卡 / 驾驶证 / 营业执照 / 增值税发票 等 10 类结构化解析 → mica-ppocr 文档

路径 C · 语音能力 ​

1. 加依赖

xml
<dependency>
    <groupId>net.dreamlu</groupId>
    <artifactId>mica-voice-spring-boot-starter</artifactId>
    <version>${mica-voice.version}</version>
</dependency>

2. 配置

yaml
mica:
  voice:
    models-dir: ./models
    asr:
      offline:
        enabled: true
        model-dir-name: sherpa-onnx-paraformer-zh-small-2024-03-09
        model-type: PARAFORMER

3. 注入即用

java
@RestController
public class AsrController {
    private final OfflineAsrService offlineAsrService;

    public AsrController(OfflineAsrService offlineAsrService) {
        this.offlineAsrService = offlineAsrService;
    }

    @PostMapping("/asr")
    public String asr(@RequestParam("file") MultipartFile file) throws IOException {
        File tmp = File.createTempFile("asr", ".wav");
        file.transferTo(tmp);
        try {
            return offlineAsrService.recognize(tmp).getText();
        } finally {
            tmp.delete();
        }
    }
}

4. 往下走 → mica-voice 文档（含 Solon 接入、9 个 Service Bean、模型下载脚本）

路径 D · 网络与 MQTT ​

mica-net：TCP / UDP / HTTP / WebSocket / MCP 服务端的底层网络框架。

java
// mica-mqtt 客户端：连接 + 订阅（底层即 mica-net）
MqttClient client = MqttClient.create()
    .ip("127.0.0.1")
    .port(1883)
    .username("mica")
    .password("mica")
    .connectSync();
client.subQos0("/test/#", (context, topic, message, payload) -> {
    logger.info(topic + '\t' + new String(payload, StandardCharsets.UTF_8));
});

常见问题 ​

模型要自己下载吗？ 要。模型体积大，不随 jar 分发。mica-voice 提供下载脚本 （models/scripts/download-models.sh asr，Windows 有 .bat / .ps1）， mica-ai / mica-ppocr 需按文档把 ONNX 放到指定目录。

能跑 GPU 吗？ 可以。把 onnxruntime 换成 onnxruntime_gpu，并开启 prefer-accelerator: true，此时 intra-op-num-threads 建议设为 1， 把并行让给 GPU（需 CUDA Toolkit + 驱动）。

为什么长时间跑内存一直涨、最后 OOM？ 大概率是 ONNX Runtime 的 CPU arena / memory pattern 在动态分辨率下不把内存归还给 OS。 mica-ppocr 自 v1.2.0 起默认关闭这两项（代价约 10% 吞吐）。 只有当输入分辨率固定、且追求极致吞吐时才成对开启。

不联网能用吗？ AI 与语音模块都是本地 ONNX 推理，启动后不需要公网。仅首次下载模型需要网络。

商用有协议风险吗？ 没有。项目为 Apache 2.0 / LGPL-3.0；所依赖模型均已确认可商用， 详见各模块文档的 License 章节。

遇到问题？提 Issue 或联系我们。 需要企业级支持、私有化交付、行业模型定制，见服务与合作。