OpenBMB/MiniCPM-V-Apps

OpenBMB/MiniCPM-V-Apps

Description: MiniCPM-V apps — fully offline multimodal chat on iOS / Android / HarmonyOS

Language: Swift

Stars: 304

Forks: 43

Open issues: 13

Created: 2025-08-05T15:20:30Z

Pushed: 2026-06-05T21:35:48Z

Default branch: main

Fork: no

Archived: no

README:

MiniCPM-V Demo — iOS, Android & HarmonyOS

English | [中文](README_zh.md)

This demo runs the MiniCPM-V family of multimodal models fully on-device on iOS, Android, and HarmonyOS NEXT. Currently supported:

• MiniCPM-V 2.6
• MiniCPM-V 4.0
• MiniCPM-V 4.6
• MiniCPM5-1B (text-only)
• VoxCPM2 (text-to-speech, TTS)

This repository contains three on-device demos for MiniCPM-V (multimodal LLM) running fully locally via llama.cpp:

• MiniCPM-V-demo/ — iOS demo (Xcode project)
• MiniCPM-V-demo-Android/ — Android demo (Gradle / Kotlin)
• MiniCPM-V-demo-HarmonyOS/ — HarmonyOS NEXT demo (DevEco Studio / ArkTS)

All three demos share the same llama.cpp-omni submodule (branch master) at the repo root.

> NOTE: This project bundles llama.cpp as a git submodule. The upstream fork tc-mb/llama.cpp-omni carries a dozen unrelated branches and a full clone weighs ~350 MB, so shallow = true is set in .gitmodules by default. The recommended shallow + single-branch clone is: > > ``bash > # one-shot (parent repo + submodules, all shallow) > git clone --recurse-submodules --shallow-submodules \ > https://github.com/OpenBMB/MiniCPM-V-Apps.git > cd MiniCPM-V-Apps > > > Or, if you've already cloned the parent repo and want to init the submodule afterwards: > > bash > git submodule update --init --recursive --depth 1 --single-branch > > > This only pulls a single commit of the MiniCPM-V branch (~tens of MB) instead of the full llama.cpp-omni fork history. Developers who need to push to tc-mb/llama.cpp-omni:master can run git fetch --unshallow` inside the submodule to lift the shallow restriction.

The README is organised in two parts:

• Part 1 — Platform setup: how to build and run the demo on iOS, Android and HarmonyOS.
• Part 2 — GGUF model files: where to get the model weights for each MiniCPM-V version, and the minimum on-device hardware needed to run them.

---

> Just want to install the app? Pre-built TestFlight (iOS) / APK (Android) / HAP (HarmonyOS) packages and step-by-step install instructions are in [DOWNLOAD.md](DOWNLOAD.md). The rest of this README is only needed if you want to build from source.

---

Part 1. Platform Setup

1.1 iOS Demo

NOTE: To deploy and test the app on an iOS device, you may need an Apple Developer account.

1.1.1 Install Xcode & command-line tools

• Download Xcode from the App Store (verified on Xcode 26.1; project deployment target = iOS 16.4)
• Install the Command Line Tools:

xcode-select --install

• Agree to the software license agreement:

sudo xcodebuild -license

• CMake ≥ 3.28 (needed by the xcframework build in the next step):

brew install cmake

1.1.2 Build llama.xcframework (required on first build)

This repo does not track any compiled artefacts, so the prebuilt llama.xcframework (~189 MB) needs to be produced locally from the llama.cpp-omni submodule and dropped into MiniCPM-V-demo/thirdparty/ for Xcode to link against. A one-shot script is provided — by default it only builds the two slices the demo actually links (real device + simulator), which takes ~2-3 min on a modern M-series Mac:

./scripts/build_xcframework.sh

The output is installed at MiniCPM-V-demo/thirdparty/llama.xcframework/.

If you need a different build scope (simulator-only, full multi-platform, …), the script forwards MINIMAL_MODE:

MINIMAL_MODE=ios-sim ./scripts/build_xcframework.sh # simulator only (~3 min)
MINIMAL_MODE=ios-device ./scripts/build_xcframework.sh # device only (~3 min)
MINIMAL_MODE=ios ./scripts/build_xcframework.sh # device + simulator (default, ~3 min)
MINIMAL_MODE=all ./scripts/build_xcframework.sh # iOS + macOS + tvOS + xrOS (~25 min)

The equivalent manual commands, if you'd rather not use the script:

cd llama.cpp-omni
MINIMAL_MODE=ios ./build-xcframework.sh
cp -r ./build-apple/llama.xcframework ../MiniCPM-V-demo/thirdparty/

During the build you will see warnings like ignoring duplicate libraries and skipping debug map object with duplicate name and timestamp — these come from llama.cpp's mtmd module having identically-named .o files across different model architectures. They are harmless and the resulting framework works correctly.

> When do I need to rebuild? > - The parent repo bumped the llama.cpp-omni submodule pointer (git submodule status shows a commit different from your last local build). > - You edited any source under llama.cpp-omni/ that affects the framework.

1.1.3 Open in Xcode and run

Open MiniCPM-V-demo/MiniCPM-V-demo.xcodeproj with Xcode. It may take a moment for Xcode to automatically download the required dependencies. Select the target device at the top, then click the "Run" (triangle) button to launch the demo.

If Xcode fails with There is no XCFramework found at '.../llama.xcframework', you skipped §1.1.2 — go back and run the build.

1.2 Android Demo

Requirements:

• Android Studio (Giraffe or newer)
• Android SDK + NDK (the project pins NDK 27.0.12077973 and CMake 3.22.1)
• A physical device with a 64-bit ARM SoC (arm64-v8a)
• Device RAM: see the per-model requirements in [Part 2](#part-2-gguf-model-files)

Build & run:

cd MiniCPM-V-demo-Android
./gradlew assembleDebug

Or open MiniCPM-V-demo-Android/ directly in Android Studio and click Run.

The first launch will download the GGUF model files into the app's external storage. You can also sideload model files manually via adb push — see in-app Model Manager for the expected directory layout.

1.3 HarmonyOS Demo

Requirements:

• DevEco Studio 5.0 or newer (with the HarmonyOS Native SDK / NDK)
• A real device or emulator running HarmonyOS API 12+ (e.g. nova 14 vitality / Mate 60 / Pura 70)
• 64-bit ARM architecture (arm64-v8a)
• Device RAM: see the per-model requirements in [Part 2](#part-2-gguf-model-files)

Build & run:

1. Open MiniCPM-V-demo-HarmonyOS/ in DevEco Studio. 2. File → Project Structure → Signing Configs and tick Automatically generate signature (requires a Huawei developer account; this only needs to be done once).…