---
url: https://www.dreamlu.net/start.md
---

# 5 分钟快速开始

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

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

## 环境要求

| 组件 | 版本 | 说明 |
| ---- | ---- | ---- |
| ☕ JDK | **8+** | 全部项目最低 JDK 8；推荐 Temurin / Azul Zulu 8、11、17 |
| 📦 Maven | 3.6+ | 或 Gradle 6+ |
| 🧠 ONNX Runtime | 1.18.0 | AI 相关模块由 Maven 自动拉取，CPU / GPU 可选 |
| 🖼️ OpenCV | 4.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 文档](/mica/)
* 样板代码自动生成（`spring.factories` / `FeignClient` 元数据）→ [mica-auto 文档](/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 文档](/mica-ai/)
* 行驶证 / 身份证 / 银行卡 / 驾驶证 / 营业执照 / 增值税发票 等 10 类结构化解析 → [mica-ppocr 文档](/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 文档](/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));
});
```

* 自建网络服务 → [mica-net 文档](/mica-net/)
* MQTT Broker / Client 双端（依赖坐标与集群章节）→ [mica-mqtt 文档站](https://mica-mqtt.dreamlu.net)

## 常见问题

**模型要自己下载吗？**
要。模型体积大，不随 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](https://github.com/lets-mica/dreamlu-website/issues/new) 或[联系我们](/contact.html)。
需要企业级支持、私有化交付、行业模型定制，见[服务与合作](/services.html)。