# LLM On-Device

**Repository Path**: licq_workspace/smart-memory---dual-realm

## Basic Information

- **Project Name**: LLM On-Device
- **Description**: PocketLLM 口袋大模型 — Android 端侧大模型部署与开发套件：MNN 推理引擎、流式生成、模型市场、Compose 参考实现 | Run on-device LLMs in your Android app. MNN + Qwen, streaming, offline.
- **Primary Language**: Android
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 1
- **Forks**: 0
- **Created**: 2026-04-26
- **Last Updated**: 2026-09-17

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PocketLLM · 口袋大模型 🐳

**Android 端侧大模型部署与开发套件** —— 几分钟内，在你的 App 里跑通离线大模型推理。

![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)
![Platform](https://img.shields.io/badge/platform-Android-green.svg)
![minSdk](https://img.shields.io/badge/minSdk-24-orange.svg)
![Engine](https://img.shields.io/badge/engine-MNN--LLM-9cf.svg)
![Kotlin](https://img.shields.io/badge/Kotlin-1.9+-7f52ff.svg)

**MNN 推理引擎** · **Token 级流式生成** · **Kotlin 优先 SDK** · **模型市场** · **Jetpack Compose 参考实现**

## 为什么是 PocketLLM

在 Android 上跑通一个端侧大模型，你要自己解决一整套工程问题：

- MNN 交叉编译（arm64、Android 15+ 16KB Page Size）
- JNI 封装与线程模型
- Token 级流式回调与生成中断
- 模型选型、量化版本、下载与放置
- 会话生命周期与内存管理

PocketLLM 把这些全部封装成一个可复用的 Kotlin SDK 模块（`llm`），并附带一个展示生产级用法的完整参考 App。**引入一个模块、三行代码，你的 App 就有了离线 AI 能力。**

## ✨ 核心特性

- 🧩 **Kotlin SDK（`llm` 模块）**：`MnnLlmSession` 提供完整会话 API —— `load / submit / stop / reset / restoreHistory / release`；线程数、mmap、system prompt、最大 token 等经 `LlmConfig` 配置
- ⚡ **流式生成**：token 级进度回调（`GenerateProgressListener`），打字机效果开箱即得，返回 `false` 即可中断；`GenerateResult` 直接输出生成速度、prefill / decode 耗时
- 📦 **模型市场**：接入 MNN 官方模型目录（Qwen / Llama / Gemma / SmolLM2 / LFM2 全系列 4-bit 量化模型），浏览与选型开箱即用
- 📱 **参考 App**：Jetpack Compose 流式聊天界面 + Room 对话持久化 + 会话历史恢复，演示完整生产级接入
- 🔧 **工程细节就绪**：arm64-v8a、Android 15+ 16KB Page Size 合规、minSdk 24

## 🚀 三行代码接入

```kotlin
val session = MnnLlmSession(LlmConfig(configPath = "$modelDir/config.json", modelDir = modelDir))
session.load()
session.submit("你好") { token ->
    append(token)   // 流式更新 UI
    true            // 返回 false 中断生成
}
```

### SDK API 一览

| API | 说明 |
|-----|------|
| `load()` | 加载模型（阻塞，建议在 IO 线程调用） |
| `submit(prompt, listener)` | 提交对话，token 级流式回调 |
| `stop()` | 中断当前生成 |
| `reset()` / `restoreHistory(role, content)` | 会话重置 / 逐条恢复历史 |
| `release()` | 释放模型与内存 |

## 快速开始

```bash
git clone https://gitee.com/licq_workspace/smart-memory---dual-realm.git
```

1. 编译 MNN 推理库（一次性）→ 见 [构建指南](docs/BUILD.md)
2. Android Studio 打开工程，连接 arm64 真机，Run ▶️
3. 启动后进入模型市场选择模型，或按 [MNN 模型选型目录](docs/MNN_MODELS.md) 手动下载放置

## 📱 支持的模型

基于 [MNN-LLM](https://github.com/alibaba/MNN) 预转换模型（4-bit 量化，ModelScope 发布）：

| 模型 | 参数量 | 体积 | 适用场景 |
|------|-------|------|---------|
| Qwen2.5-0.5B-Instruct | 0.5B | ~531 MB | 低端设备 / 中文对话 |
| Qwen3-0.6B | 0.6B | ~433 MB | 小型端侧 |
| **Qwen2.5-1.5B-Instruct** ⭐ | 1.5B | ~839 MB | 推荐主力，性能与体积平衡 |
| Llama-3.2-1B / 3B-Instruct | 1–3B | 1.1–2.4 GB | 英文场景 |
| Qwen3-4B | 4B | ~2.5 GB | 旗舰设备 |

完整目录（含 Gemma、SmolLM2、LFM2 多模态等 20+ 模型）→ [docs/MNN_MODELS.md](docs/MNN_MODELS.md)

## 🏗 架构

```
┌─────────────────────────────────────────────┐
│  app    参考应用：聊天 Demo + Room 会话持久化    │
├─────────────────────────────────────────────┤
│  main   组件层：模型市场 / 流式聊天 UI            │
├─────────────────────────────────────────────┤
│  llm    SDK 层：MNN-LLM JNI 封装（Kotlin API） │
├─────────────────────────────────────────────┤
│  core   设计系统：Compose 主题与组件库           │
└─────────────────────────────────────────────┘
```

## ⚡ 性能基准

> 数据持续收集中，欢迎提交 PR 补充你的设备数据（参考 App 基于 `GenerateResult` 的 speed / prefill / decode 指标即可测得）。

| 设备 | 模型 | 解码速度 (token/s) | 内存占用 |
|------|------|------------------|---------|
| *你的设备* | — | — | — |

## 🗺 Roadmap

- [ ] 应用内模型下载实装（ModelScope 直连 + 断点续传）
- [ ] 多引擎支持：llama.cpp / Google AI Edge / MLC-LLM
- [ ] Function Calling 与结构化输出
- [ ] 端侧 RAG 模块（文档导入 + 本地向量检索）
- [ ] `llm` 模块发布 Maven Central
- [ ] 多模态（LFM2-VL 视觉理解）

## 📚 文档

- [构建指南](docs/BUILD.md) —— MNN 交叉编译与工程配置
- [MNN 端侧模型选型目录](docs/MNN_MODELS.md) —— 20+ 预转换模型对比
- [MNN-LLM 调研笔记](docs/mnn-llm-research.md)
- [ModelScope API 参考](docs/modelscope-api.md)

## 🤝 贡献

欢迎 Issue 与 PR。提交性能数据、接入新模型、支持新引擎，都是高价值的贡献方向。

## 📄 许可

[Apache License 2.0](LICENSE)

## 🙏 致谢

- [Alibaba MNN](https://github.com/alibaba/MNN) —— 高性能端侧推理引擎
- [Qwen](https://github.com/QwenLM) —— 开源大模型
- [ModelScope 魔搭社区](https://modelscope.cn) —— 预转换模型分发