MiniCPM-V 多模态模型 Android APP 集成指南

nameNotNull

墨衍会员 · AI 创作全网分发码龄2年

关注

原创最新推荐文章于 2026-09-08 12:23:32 发布 649 阅读 AI 写同款· GEO 优化 ›

MiniCPM-V 多模态模型 Android APP 集成指南

本教程主要讲述的是如何将 MiniCPM-V 系列多模态模型（图文/视频理解）集成到你自己的 Android App，原始项目地址：https://github.com/OpenBMB/MiniCPM-V-Apps

1. 前置条件

为了避免出现其他兼容性问题建议与原始项目MiniCPM-V-demo-Android中的版本保持一致

项目	要求
Android Studio	2024.1+（支持 AGP 8.9）
AGP	8.9.1
Gradle	8.11.1
NDK	27.0.12077973
CMake	3.22.1
Kotlin	2.0.21
minSdk	24
目标 ABI	arm64-v8a（仅支持 64 位 ARM）
磁盘空间	≥ 10GB（llama.cpp 编译 + 模型文件）
Java	11

2. 文件清单

必须复制

Kotlin层

LlamaEngine.kt：引擎单例，封装全部 JNI 调用
ModelInfo.kt：模型元数据（下载源、文件名、MD5校验等）
ModelDownloadService.kt：模型下载服务
CpuFeatures.kt：CPU 特性检测（选优化的 .so）

JNI层

CMakeLists.txt：CMake 配置
llama_jni.cpp：JNI 桥接
logging.h：日志

可选文件

MarkdownEscape.kt：V4.6 输出的 \n 转真换行（显示优化）
VideoFrameExtractor.kt：视频理解功能，只有MiniCPM-V 4.6模型支持

3. 步骤一：搭建 Native 层

3.1 添加 llama.cpp 子模块

在项目根目录：

cd /path/to/your/project
git submodule add -b Support-iOS-Demo https://github.com/tc-mb/llama.cpp.git llama.cpp
cd llama.cpp

⚠️ 重要：必须使用 Support-iOS-Demo 分支，它包含 MiniCPM-V 的 clip.cpp 兼容代码，主线分支的 mmproj 转换格式不兼容。

3.2 复制 C++ 文件

把 llama_jni.cpp、logging.h、CMakeLists.txt 复制到你项目的 app/src/main/cpp/ 下。

3.3 修改 CMakeLists.txt 中的 llama.cpp 路径

打开 CMakeLists.txt，修改第 38-39 行的 LLAMA_SRC 路径：

# 默认在项目4级目录上找 llama.cpp
if(NOT DEFINED LLAMA_SRC)
    set(LLAMA_SRC ${CMAKE_CURRENT_LIST_DIR}/../../../../../llama.cpp)
endif()

# 如果你的llama.cpp 在项目根目录下，改成：
if(NOT DEFINED LLAMA_SRC)
    set(LLAMA_SRC ${CMAKE_CURRENT_LIST_DIR}/../../../../llama.cpp)
endif()

路径关系：app/src/main/cpp/ → 上 4 级到项目根 → llama.cpp/

3.4 修改 JNI 函数名

llama_jni.cpp 中的 JNI 函数名基于包名 com.example.minicpm_v_demo，格式为：

Java_包名_类名_方法名（. → _，_ → _1）

当前函数名示例：

Java_com_example_minicpm_1v_1demo_LlamaEngine_load

如果你的包名是 com.yourapp.ai，需要把所有 JNI 函数前缀改为：

Java_com_yourapp_ai_LlamaEngine_load

完整替换列表（在 llama_jni.cpp 中搜索替换）：

原始前缀	新前缀
`Java_com_example_minicpm_1v_1demo_LlamaEngine_`	`Java_com_yourapp_ai_LlamaEngine_`

4. 步骤二：配置 Gradle 构建

4.1 `gradle/libs.versions.toml`

[versions]
agp = "8.9.0"
kotlin = "2.0.21"
coreKtx = "1.10.1"
appcompat = "1.6.1"
material = "1.10.0"
constraintlayout = "2.1.4"
lifecycleRuntimeKtx = "2.6.2"
activityKtx = "1.8.0"

[libraries]
androidx-core-ktx = { group = "androidx.core", name = "core-ktx", version.ref = "coreKtx" }
androidx-appcompat = { group = "androidx.appcompat", name = "appcompat", version.ref = "appcompat" }
material = { group = "com.google.android.material", name = "material", version.ref = "material" }
androidx-constraintlayout = { group = "androidx.constraintlayout", name = "constraintlayout", version.ref = "constraintlayout" }
androidx-lifecycle-runtime-ktx = { group = "androidx.lifecycle", name = "lifecycle-runtime-ktx", version.ref = "lifecycleRuntimeKtx" }
androidx-activity-ktx = { group = "androidx.activity", name = "activity-ktx", version.ref = "activityKtx" }

[plugins]
android-application = { id = "com.android.application", version.ref = "agp" }
kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }

4.2 `gradle/wrapper/gradle-wrapper.properties`

distributionUrl=https\://services.gradle.org/distributions/gradle-8.11.1-bin.zip

4.3 `app/build.gradle.kts`

plugins {
    alias(libs.plugins.android.application)
    alias(libs.plugins.kotlin.android)
    alias(libs.plugins.kotlin.compose)
}

android {
    namespace = "com.xxx.xxx" //改为自己的项目包路径
    compileSdk = 36
    ndkVersion = "27.0.12077973"

    defaultConfig {
        applicationId = "com.xxx.xxx"
        minSdk = 24
        targetSdk = 36
        versionCode = 1
        versionName = "1.0"
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
        ndk {
            abiFilters.add("arm64-v8a")   // 只构建 ARM64
        }

        //cmake相关的配置
        externalNativeBuild {
            cmake {
                arguments += "-DCMAKE_BUILD_TYPE=Release"
                arguments += "-DBUILD_SHARED_LIBS=ON"
                arguments += "-DLLAMA_BUILD_COMMON=ON"
                arguments += "-DLLAMA_OPENSSL=OFF"
                arguments += "-DGGML_NATIVE=OFF"
                arguments += "-DGGML_LLAMAFILE=ON"
                arguments += "-DGGML_CPU_ARM_ARCH=armv8.2-a+dotprod+fp16"
            }
        }

    }

    buildTypes {
        release {
            isMinifyEnabled = false
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
    
    compileOptions {
        sourceCompatibility = JavaVersion.VERSION_11
        targetCompatibility = JavaVersion.VERSION_11
    }

    kotlinOptions {
        jvmTarget = "11"
    }

    externalNativeBuild {
        cmake {
            path = file("src/main/cpp/CMakeLists.txt")
            version = "3.22.1"
        }
    }

    buildFeatures {
        compose = true
    }
}

dependencies {

    implementation(libs.androidx.core.ktx)
    implementation(libs.androidx.lifecycle.runtime.ktx)
    implementation(libs.androidx.activity.compose)
    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.ui)
    implementation(libs.androidx.ui.graphics)
    implementation(libs.androidx.ui.tooling.preview)
    implementation(libs.androidx.material3)
    implementation(libs.androidx.material.icons.extended)
    testImplementation(libs.junit)
    androidTestImplementation(libs.androidx.junit)
    androidTestImplementation(libs.androidx.espresso.core)
    androidTestImplementation(platform(libs.androidx.compose.bom))
    androidTestImplementation(libs.androidx.ui.test.junit4)
    debugImplementation(libs.androidx.ui.tooling)
    debugImplementation(libs.androidx.ui.test.manifest)
    
}

5. 步骤三：复制 Kotlin 核心文件

5.1 必须文件

把以上提到的必须复制文件，复制到你的包名目录下，并修改 package 声明。

5.2 LlamaEngine.kt 的 JNI 声明

如果你的包名改变了，需要同步修改 LlamaEngine.kt 中的 external 函数声明。Kotlin 的 external 函数名必须和 C++ 端一致，不改 Kotlin 声明，改 C++ 端的函数名来匹配。

6. 步骤四：配置 AndroidManifest

<manifest ...>
    <!-- 网络权限（下载模型必须） -->
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />

    <!-- 以下权限仅在集成 ModelDownloadService 时需要 -->
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_DATA_SYNC" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

    <application
        android:networkSecurityConfig="@xml/network_security_config"
        ...>
        
        <!-- 如果使用 ModelDownloadService -->
        <service
            android:name=".ModelDownloadService"
            android:exported="false"
            android:foregroundServiceType="dataSync" />
    </application>
    
</manifest>

network_security_config.xml

<?xml version="1.0" encoding="utf-8"?>

<network-security-config>
    <base-config cleartextTrafficPermitted="true" />
</network-security-config>

7. 步骤五：模型文件管理

7.1 模型存储结构

/data/data/com.yourapp.ai/files/models/
├── minicpm-v-4/                        # ModelInfo.id
│   ├── ggml-model-Q4_K_M.gguf         # LLM 主模型
│   └── mmproj-model-f16.gguf           # 视觉投影模型
└── minicpm-v-4_6-instruct/            # 另一个模型
    ├── MiniCPM-V-4_6-Q4_K_M.gguf
    └── mmproj-model-merger-f16.gguf

7.2 下载源

模型	大小	下载策略
MiniCPM-V-4 (Q4_K_M)	~4.1B	HuggingFace → ModelScope 回退
MiniCPM-V-4.6 (Q4_K_M)	~1.2B	华为云 OBS 直链

7.3 下载方式

方式 A：App 内下载（推荐）

集成 ModelDownloadService.kt，用户点击下载按钮即可，支持断点续传和 MD5 校验。

//启动下载
ModelDownloadService.start(context)

//下载状态
lifecycleScope.launch {
    ModelDownloadController.status.collect { status ->
        when (status) {
            is ModelDownloadController.Status.Running -> showProgress(status.message)
            is ModelDownloadController.Status.Completed -> onDownloadComplete()
            is ModelDownloadController.Status.Failed -> showError(status.message)
            else -> {}
        }
    }
}

方式 B：adb 侧载

#推送模型文件到设备 测试时可以这样
adb push ggml-model-Q4_K_M.gguf /data/data/com.yourapp.ai/files/models/minicpm-v-4/
adb push mmproj-model-f16.gguf /data/data/com.yourapp.ai/files/models/minicpm-v-4/

8. 步骤六：在 App 中使用

// 初始化引擎 条件加载模型 这里建议放到MainActivity的onCreate中 在启动的时候自动加载模型
val engine = LlamaEngine.getInstance(this)

if (LlamaEngine.modelsExist(this)) {
    lifecycleScope.launch {
        engine.state.collect { state ->
                              if (state is LlamaState.Initialized) {
                                  Log.i("ModelLoad", "模型文件已就绪，开始加载...")
                                  try {

                                      engine.loadModel(
                                          LlamaEngine.modelPath(this@MainActivity),
                                          LlamaEngine.mmprojPath(this@MainActivity)
                                      )

                                      Log.i("ModelLoad", "模型加载成功！")

                                  } catch (e: Exception) {
                                      Log.e("ModelLoad", "模型加载失败", e)
                                  }
                                  return@collect  // 只触发一次
                              }
                             }
    }
}

9. API 表

LlamaEngine 公开 API

方法	简要说明
`getInstance(context)`	获取单例
`loadModel(path, mmprojPath?)`	加载模型+视觉模型
`setSystemPrompt(prompt)`	设置系统提示词
`sendUserPrompt(msg, predictLen)`	发送用户消息
`prefillImage(imageData)`	预填充图片
`prefillVideoFrames(frames, onProgress)`	预填充视频帧
`clearContext()`	清空上下文
`unloadModel()`	卸载模型
`cancelGeneration()`	取消当前生成
`destroy()`	销毁引擎
`setImageMaxSliceNums(n)`	设置图片切片数
`state`	引擎状态流
`isVisionSupported`	是否支持图片
`isVideoUnderstandingSupported`	是否支持视频

LlamaEngine 静态 API

方法	简要说明
`getSelectedModel(context)`	获取当前选择的模型
`setSelectedModel(context, id)`	选择模型
`modelPath(context)`	GGUF 文件路径
`mmprojPath(context)`	mmproj 文件路径
`modelsExist(context)`	模型文件是否都在
`modelDir(context)`	模型根目录
`modelDirFor(context, model)`	某模型目录
`getImageMaxSliceNums(context)`	图片切片数
`setImageMaxSliceNumsPref(context, n)`	持久化切片数
`downloadModels(context, onProgress)`	下载模型文件
`migrateLegacyLayoutIfNeeded(context)`	迁移旧文件布局

9.1 自定义推理参数

在 llama_jni.cpp 中修改

constexpr int   N_THREADS            = 4;    // 推理 线程数影响推理速度 亲测 这里可以稍微调大
constexpr int   DEFAULT_CONTEXT_SIZE = 4096; // KV cache 大小
constexpr int   V46_CONTEXT_SIZE     = 8192; // V4.6 的 KV cache
constexpr int   BATCH_SIZE           = 2048; // 批处理大小 这里也可以稍微调大一些 
constexpr float DEFAULT_SAMPLER_TEMP = 0.7f; // 温度