Android 適用的 LLM 推論指南

LLM 推論 API 可讓您在 Android 應用程式上完全執行大型語言模型 (LLM)，用於執行各種工作，例如產生文字、以自然語言形式擷取資訊，以及摘要文件。這項工作內建多種文字對文字大型語言模型的支援功能，因此您可以將最新的裝置端生成式 AI 模型套用至 Android 應用程式。

如要快速將 LLM Inference API 新增至 Android 應用程式，請按照快速入門操作。如需執行 LLM Inference API 的 Android 應用程式基本範例，請參閱範例應用程式。如要進一步瞭解 LLM Inference API 的運作方式，請參閱「設定選項」、「模型轉換」和「LoRA 調整」一節。

您可以透過 MediaPipe Studio 示範，瞭解如何執行此工作。如要進一步瞭解這項工作的功能、模型和設定選項，請參閱總覽。

快速入門導覽課程

請按照下列步驟，將 LLM Inference API 新增至 Android 應用程式。LLM Inference API 是針對高階 Android 裝置 (例如 Pixel 8 和 Samsung S23 以上機型) 進行最佳化，不支援裝置模擬器。

新增依附元件

LLM 推論 API 會使用 com.google.mediapipe:tasks-genai 程式庫。請將這個依附元件新增至 Android 應用程式的 build.gradle 檔案：

dependencies {
    implementation 'com.google.mediapipe:tasks-genai:0.10.22'
}

如果是搭載 Android 12 (API 31) 以上版本的裝置，請新增原生 OpenCL 程式庫依附元件。詳情請參閱 uses-native-library 標記的說明文件。

將下列 uses-native-library 標記新增至 AndroidManifest.xml 檔案：

<uses-native-library android:name="libOpenCL.so" android:required="false"/>
<uses-native-library android:name="libOpenCL-car.so" android:required="false"/>
<uses-native-library android:name="libOpenCL-pixel.so" android:required="false"/>

下載模型

從 Hugging Face 下載 Gemma-3 1B 的 4 位元量化格式。如要進一步瞭解可用模型，請參閱模型說明文件。

將 output_path 資料夾的內容推送至 Android 裝置。

$ adb shell rm -r /data/local/tmp/llm/ # Remove any previously loaded models
$ adb shell mkdir -p /data/local/tmp/llm/
$ adb push output_path /data/local/tmp/llm/model_version.task

初始化工作

使用基本設定選項初始化工作：

// Set the configuration options for the LLM Inference task
val taskOptions = LlmInferenceOptions.builder()
        .setModelPath('/data/local/tmp/llm/model_version.task')
        .setMaxTopK(64)
        .build()

// Create an instance of the LLM Inference task
llmInference = LlmInference.createFromOptions(context, taskOptions)

執行工作

使用 generateResponse() 方法產生文字回覆。這會產生單一產生的回覆。

val result = llmInference.generateResponse(inputPrompt)
logger.atInfo().log("result: $result")

如要串流傳輸回應，請使用 generateResponseAsync() 方法。

val options = LlmInference.LlmInferenceOptions.builder()
  ...
  .setResultListener { partialResult, done ->
    logger.atInfo().log("partial result: $partialResult")
  }
  .build()

llmInference.generateResponseAsync(inputPrompt)

應用程式範例

範例應用程式是 Android 版基本文字產生應用程式，使用 LLM 推論 API。您可以使用這個應用程式做為自有 Android 應用程式的起點，或是在修改現有應用程式時參考。程式碼範例託管於 GitHub。

使用下列指令複製 Git 存放區：

git clone https://github.com/google-ai-edge/mediapipe-samples

建立範例程式碼的本機版本後，您可以將專案匯入 Android Studio 並執行應用程式。詳情請參閱 Android 設定指南。

設定選項

請使用下列設定選項設定 Android 應用程式：

選項名稱 說明 值範圍 預設值
modelPath 模型在專案目錄中的儲存路徑。 路徑 無
maxTokens 模型可處理的符記數量上限 (輸入符記 + 輸出符記)。 整數 512
topK 模型在產生過程的每個步驟中會考慮的符記數量。將預測結果限制在機率最高的 K 個符記。 整數 40
temperature 產生期間引入的隨機程度。溫度越高，生成的文字就越有創意；溫度越低，生成的內容就越容易預測。 浮點值 0.8
randomSeed 文字產生期間使用的隨機種子。 整數 0
loraPath 裝置本機上 LoRA 模型的絕對路徑。注意：這項功能僅適用於 GPU 型號。 路徑 無
resultListener 將結果事件監聽器設為以非同步方式接收結果。僅適用於使用非同步產生方法時。 無 無
errorListener 設定選用的錯誤監聽器。 無 無

模型轉換

LLM 推論 API 與下列模型類型相容，其中部分模型需要轉換。請參閱下表，找出模型所需的步驟方法。

模型 轉換方法 相容的平台 檔案類型
Gemma-3 1B 不需要轉換 Android、網頁 .task
Gemma 2B、Gemma 7B、Gemma-2 2B 不需要轉換 Android、iOS、網頁 .bin
Phi-2、StableLM、Falcon MediaPipe 轉換指令碼 Android、iOS、網頁 .bin
所有 PyTorch LLM 模型 AI Edge Torch 生成式程式庫 Android、iOS 裝置 .task

如要瞭解如何轉換其他模型，請參閱「模型轉換」一節。

LoRA 自訂

LLM 推論 API 支援使用 PEFT (參數高效率微調) 程式庫進行 LoRA (低秩調整) 調整。LoRA 調整功能會透過經濟實惠的訓練程序，自訂 LLM 的行為，並根據新的訓練資料建立一小組可訓練權重，而非重新訓練整個模型。

LLM 推論 API 可在 Gemma-2 2B、Gemma 2B 和 Phi-2 模型的注意力層中新增 LoRA 權重。以 safetensors 格式下載模型。

基礎模型必須採用 safetensors 格式，才能建立 LoRA 權重。完成 LoRA 訓練後，您可以將模型轉換為 FlatBuffers 格式，以便在 MediaPipe 上執行。

準備 LoRA 權重

請參閱 PEFT 的 LoRA 方法指南，根據自己的資料集訓練經過微調的 LoRA 模型。

LLM Inference API 僅支援注意力圖層的 LoRA，因此請只在 LoraConfig 中指定注意力圖層：

# For Gemma
from peft import LoraConfig
config = LoraConfig(
    r=LORA_RANK,
    target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
)

# For Phi-2
config = LoraConfig(
    r=LORA_RANK,
    target_modules=["q_proj", "v_proj", "k_proj", "dense"],
)

在準備資料集並儲存模型後，精細調校的 LoRA 模型權重會顯示在 adapter_model.safetensors 中。safetensors 檔案是模型轉換期間使用的 LoRA 查核點。

模型轉換

使用 MediaPipe Python 套件，將模型權重轉換為 Flatbuffer 格式。ConversionConfig 會指定基礎模型選項，以及其他 LoRA 選項。

import mediapipe as mp
from mediapipe.tasks.python.genai import converter

config = converter.ConversionConfig(
  # Other params related to base model
  ...
  # Must use gpu backend for LoRA conversion
  backend='gpu',
  # LoRA related params
  lora_ckpt=LORA_CKPT,
  lora_rank=LORA_RANK,
  lora_output_tflite_file=LORA_OUTPUT_FILE,
)

converter.convert_checkpoint(config)

轉換器會產生兩個 Flatbuffer 檔案，一個用於基礎模型，另一個用於 LoRA 模型。

LoRA 模型推論

Android 在初始化期間支援靜態 LoRA。如要載入 LoRA 模型，請指定 LoRA 模型路徑和基礎 LLM。

// Set the configuration options for the LLM Inference task
val options = LlmInferenceOptions.builder()
        .setModelPath(BASE_MODEL_PATH)
        .setMaxTokens(1000)
        .setTopK(40)
        .setTemperature(0.8)
        .setRandomSeed(101)
        .setLoraPath(LORA_MODEL_PATH)
        .build()

// Create an instance of the LLM Inference task
llmInference = LlmInference.createFromOptions(context, options)

如要使用 LoRA 執行 LLM 推論，請使用與基礎模型相同的 generateResponse() 或 generateResponseAsync() 方法。