用 React Native 在手機上本地執行 LLM 的入門指南
LLM Inference on Edge: A Fun and Easy Guide to run LLMs via React Native on your Phone!
Hugging Face Blog 的教程示範以 React Native 建立手機應用,在裝置本地執行 LLM 聊天。應用從 Hugging Face Hub 下載 GGUF 模型,並以 llama.rn(llama.cpp 的 binding)載入,教程涵蓋 Android 和 iOS。文章亦介紹 GGUF 量化格式、手機選模取捨,以及逐 token 生成與推理速度追蹤等功能。
文章按模型選擇、GGUF 下載與載入、聊天介面逐步拆解 React Native 實作,並説明量化格式與設備能力的取捨,可作為端側 LLM 應用的開發參考。
隨着 LLM 不斷演進,它們變得更小巧、更聰明,現在甚至可以直接在手機上執行。例如,擁有 1.5 billion 個參數的 DeepSeek R1 Distil Qwen 2.5,正好展示了先進 AI 如何放進掌心之中!
本文會帶你建立一款流動應用程式,讓你可以在本機與這些強大模型聊天。本教學的完整程式碼可在我們的 EdgeLLM repository 找到。如果你曾覺得開源專案太複雜,別擔心!我們參考了 Pocket Pal app,協助你建立一款簡單直接的 React Native 應用程式,從 Hugging Face hub 下載 LLM,確保所有資料都留在你的裝置上並維持私隱。我們會使用 llama.rn,這是 llama.cpp 的綁定程式,可高效載入 GGUF 檔案!
為甚麼你應該跟隨本教學?
本教學適合以下人士:
- 有興趣把 AI 整合至流動應用程式
- 想用 React Native 建立兼容 Android 和 iOS 的對話式 app
- 希望開發完全離線運作、重視私隱的 AI 應用程式
完成本指南後,你將擁有一款功能完整的 app,可以與你喜愛的模型互動。
0. 選擇合適的模型
開始建立 app 之前,先談談哪些模型適合流動裝置,以及選擇模型時要考慮甚麼。
模型大小考量
在流動裝置上執行 LLM 時,模型大小相當重要:
- 小型模型(1-3B 參數):適合大部分流動裝置,效能良好而延遲低
- 中型模型(4-7B 參數):較新的高階裝置可以流暢執行,但舊手機可能會變慢
- 大型模型(8B 以上參數):通常對大部分流動裝置而言太耗資源,但若量化至 Q2_K 或 Q4_K_M 等低精度格式,仍可使用
GGUF 量化格式
下載 GGUF 模型時,你會遇到不同的量化格式。瞭解這些格式有助你在模型大小與效能之間作出合適取捨:
舊式量化格式(Q4_0、Q4_1、Q8_0)
- 基本而直接的量化方法
- 每個區塊會儲存:
• 量化值(壓縮後的權重)。
• 一個(_0)或兩個(_1)縮放常數。 - 速度快,但不及較新的方法有效率 => 現在已不常用
K-Quants(Q3_K_S、Q5_K_M、...)
- 於這個 PR 引入
- 比舊式量化格式更聰明地分配位元
- 「K-quants」中的 K 代表混合量化格式,意思是部分層會使用更多位元以提高準確度。
- _XS、_S 或 _M 等後綴代表不同的量化組合(越小表示壓縮越多),例如:
• Q3_K_S 對所有張量使用 Q3_K
• Q3_K_M 對 attention.wv、attention.wo 和 feed_forward.w2 張量使用 Q4_K,其餘使用 Q3_K。
• Q3_K_L 對 attention.wv、attention.wo 和 feed_forward.w2 張量使用 Q5_K,其餘使用 Q5_K。
I-Quants(IQ2_XXS、IQ3_S、...)
- 仍然採用區塊式量化,但加入了一些受 QuIP 啟發的新功能
- 檔案較小,但在某些硬件上可能較慢
- 最適合運算能力強但記憶體有限的裝置
建議試用的模型
以下模型在流動裝置上表現良好:
尋找更多模型
如要在 Hugging Face 尋找其他 GGUF 模型:
- 瀏覽 huggingface.co/models
- 使用搜尋篩選條件:
- 瀏覽 GGUF models page
- 在搜尋欄指定模型大小
- 對話式模型可在名稱中尋找「chat」或「instruct」
選擇模型時,應同時考慮參數數量和量化等級。例如,採用 Q2_K 量化的 7B 模型,可能比採用 Q8_0 量化的 2B 模型執行得更好。因此,如果較小的模型能在裝置上流暢運行,不妨改用較大的量化模型,效能可能更佳。
1. 設定開發環境
React Native 是一個使用 JavaScript 和 React 建立流動應用程式的熱門框架。它讓開發者可以建立同時在 Android 和 iOS 平台運行的 app,並共用大部分程式碼,從而加快開發並減少維護工作。
開始用 React Native 編碼之前,你需要先妥善設定開發環境。
所需工具
Node.js:Node.js 是 JavaScript 執行環境,讓你可以執行 JavaScript 程式碼。它是管理 React Native 專案套件和相依項目的必要工具。你可以從 Node.js downloads 安裝。
react-native-community/cli:這個指令會安裝 React Native 命令列介面(CLI),提供建立、建置和管理 React Native 專案的工具。執行以下指令安裝:
npm i @react-native-community/cli
虛擬裝置設定
開發期間要執行 app,你需要模擬器:
如果你使用 macOS:
如果你使用 Windows 或 Linux:
- iOS:需要使用雲端模擬器,例如 LambdaTest 和 BrowserStack
- Android:安裝 Java Runtime 和 Android Studio -> 前往 Device Manager 並建立模擬器
如果你想了解模擬器和仿真器的分別,可以閲讀這篇文章:Difference between Emulator and Simulator。簡單來説,仿真器會模擬硬件和軟件,而模擬器只模擬軟件。
設定 Android Studio 時,可參考 Expo 提供的這份優質教學:Android Studio Emulator Guide
2. 建立 app
現在開始這個專案吧!
你可以在 EdgeLLM repo 此處找到專案完整程式碼,內有兩個資料夾:
EdgeLLMBasic:採用簡單聊天介面的基本實作EdgeLLMPlus:聊天介面較複雜並包含額外功能的強化版本
首先,我們要使用 @react-native-community/cli 初始化 app:
npx @react-native-community/cli@latest init <ProjectName>
專案結構
app 資料夾的組織方式如下:
預設檔案/資料夾
android/- 包含 Android 原生專案檔案
- 用途:建置並在 Android 裝置上執行 app
ios/- 包含 iOS 原生專案檔案
- 用途:建置並在 iOS 裝置上執行 app
node_modules/- 用途:存放專案使用的所有 npm 相依套件
App.tsx- 以 TypeScript 編寫的 app 主要根元件
- 用途:app UI 和邏輯的進入點
index.js- 註冊根元件(
App) - 用途:React Native 執行環境的進入點。你不需要修改這個檔案。
- 註冊根元件(
其他設定檔
tsconfig.json:設定 TypeScript 選項babel.config.js:設定 Babel 轉譯現代 JavaScript/TypeScript,也就是把新式 JS/TS 程式碼轉換成兼容舊版瀏覽器或裝置的較舊程式碼。jest.config.js:設定 Jest,以測試 React Native 元件和邏輯。metro.config.js:自訂 Metro bundler 設定。Metro 是專為 React Native 設計的 JavaScript bundler,會把專案的 JavaScript 和資產打包成一個(或多個)檔案,供 app 高效載入,並在開發期間提供給 app。Metro 針對快速增量建置作了最佳化,支援 hot reload,也能處理平台專用檔案(.ios.js 或 .android.js)。.watchmanconfig:設定 Watchman;這是 React Native 使用的檔案監視服務,可支援 hot reload。
3. 執行示範與專案
執行示範
要在自己的虛擬裝置上執行專案並查看效果,請依照以下步驟:
複製儲存庫:
git clone https://github.com/MekkCyber/EdgeLLM.git前往專案目錄:
cd EdgeLLMPlus #or cd EdgeLLMBasic安裝相依套件:
npm install前往 iOS 資料夾並安裝:
cd ios pod install啟動 Metro Bundler: 在專案資料夾(EdgeLLMPlus 或 EdgeLLMBasic)執行以下指令:
npm start在 iOS 或 Android 模擬器啟動 app: 開啟另一個終端機並執行:
# For iOS npm run ios # For Android npm run android
這會在你的仿真器/模擬器上建置並啟動 app,讓你在開始編碼前測試專案。
執行專案
執行 React Native 應用程式需要仿真器/模擬器或實體裝置。我們會使用仿真器,因為它能讓你在程式碼編輯器旁並排使用除錯工具,開發體驗更順暢。
首先要確保開發環境已準備就緒:進入專案資料夾,然後執行以下指令:
# Install dependencies
npm install
# Start the Metro bundler
npm start
在新的終端機中,於所選平台啟動 app:
# For iOS
npm run ios
# For Android
npm run android
這應該會在你的仿真器/模擬器上建置並啟動 app。
4. 實作 app
安裝相依套件
首先安裝所需套件。我們希望從 Hugging Face Hub 載入模型並在本機執行。為此,需要安裝:
llama.rn:供 React Native app 使用的llama.cpp綁定程式。react-native-fs:讓我們在 React Native 環境中管理裝置的檔案系統。axios:用來向 Hugging Face Hub API 發送請求的程式庫。
npm install axios react-native-fs llama.rn
像之前示範一樣,在仿真器/模擬器上執行 app,便可以開始開發。
狀態管理
首先,刪除 App.tsx 檔案內的所有內容,並建立如下的空白程式碼結構:
App.tsx
import React from 'react';
import {StyleSheet, Text, View} from 'react-native';
function App(): React.JSX.Element {
return <View> <Text>Hello World</Text> </View>;
}
const styles = StyleSheet.create({});
export default App;
我們會在 return 陳述式(屬於 App 函數)內定義要呈現的 UI,並在外部定義邏輯;不過,所有程式碼都會放在 App 函數內。
畫面會像這樣:
「Hello World」文字沒有正確顯示,因為我們使用了簡單的 View 元件;要正確顯示文字,應改用 SafeAreaView 元件,我們會在下一節處理。
現在先想想 app 要追蹤哪些資料:
聊天相關:
- 對話記錄(用戶與 AI 之間的訊息)
- 目前的用戶輸入
模型相關:
- 所選模型格式(例如 Llama 1B 或 Qwen 1.5B)
- 每種模型格式可用的 GGUF 檔案清單
- 要下載的 GGUF 檔案
- 模型下載進度
- 用來儲存已載入模型的 context
- 用來檢查模型是否正在下載的布林值
- 用來檢查模型是否正在生成回應的布林值
以下示範如何使用 React 的 useState hook 實作這些狀態(需要從 react 匯入該 hook)。
狀態管理程式碼
import { useState } from 'react';
...
type Message = {
role: 'system' | 'user' | 'assistant';
content: string;
};
const INITIAL_CONVERSATION: Message[] = [
{
role: 'system',
content:
'This is a conversation between user and assistant, a friendly chatbot.',
},
];
const [conversation, setConversation] = useState<Message[]>(INITIAL_CONVERSATION);
const [selectedModelFormat, setSelectedModelFormat] = useState<string>('');
const [selectedGGUF, setSelectedGGUF] = useState<string | null>(null);
const [availableGGUFs, setAvailableGGUFs] = useState<string[]>([]);
const [userInput, setUserInput] = useState<string>('');
const [progress, setProgress] = useState<number>(0);
const [context, setContext] = useState<any>(null);
const [isDownloading, setIsDownloading] = useState<boolean>(false);
const [isGenerating, setIsGenerating] = useState<boolean>(false);
這段程式碼會加入 App.tsx 檔案的 App 函數內、return 陳述式之外,因為它屬於邏輯部分。
Message 類型定義聊天訊息的結構,指定每則訊息必須包含 role(可以是 'user'、'assistant' 或 'system')和 content(實際訊息文字)。
基本狀態管理設定完成後,我們還要考慮如何:
- 從 Hugging Face 擷取可用的 GGUF 模型
- 在本機下載和管理模型
- 建立聊天介面
- 處理訊息生成
下一節會逐項處理……
從 Hub 擷取可用 GGUF 模型
首先,在 app 中定義支援的模型格式和對應儲存庫。當然,llama.rn 是 llama.cpp 的綁定程式,因此我們需要載入 GGUF 檔案。要尋找支援模型的 GGUF 儲存庫,可以在 Hugging Face 搜尋特定模型的 GGUF 檔案;也可以使用 quantize_gguf.py 指令碼;該指令碼由此處提供,可用來自行量化模型並把檔案上載至我們的 hub 儲存庫。
const modelFormats = [
{label: 'Llama-3.2-1B-Instruct'},
{label: 'Qwen2-0.5B-Instruct'},
{label: 'DeepSeek-R1-Distill-Qwen-1.5B'},
{label: 'SmolLM2-1.7B-Instruct'},
];
const HF_TO_GGUF = {
"Llama-3.2-1B-Instruct": "medmekk/Llama-3.2-1B-Instruct.GGUF",
"DeepSeek-R1-Distill-Qwen-1.5B":
"medmekk/DeepSeek-R1-Distill-Qwen-1.5B.GGUF",
"Qwen2-0.5B-Instruct": "medmekk/Qwen2.5-0.5B-Instruct.GGUF",
"SmolLM2-1.7B-Instruct": "medmekk/SmolLM2-1.7B-Instruct.GGUF",
};
HF_TO_GGUF 物件會把方便用戶辨識的模型名稱對應至 Hugging Face 儲存庫路徑。例如:
- 用戶選擇 'Llama-3.2-1B-Instruct' 時,會對應至
medmekk/Llama-3.2-1B-Instruct.GGUF;這是其中一個存放 Llama 3.2 1B Instruct 模型 GGUF 檔案的儲存庫。
modelFormats 陣列包含會在選擇畫面顯示的模型選項。我們選了 Llama 3.2 1B Instruct、DeepSeek R1 Distill Qwen 1.5B、Qwen 2 0.5B Instruct 和 SmolLM2 1.7B Instruct,因為它們是最熱門的小型模型。
接着,建立一個方法,從 hub 擷取並顯示所選模型格式可用的 GGUF 模型檔案。
用戶選擇模型格式時,我們會使用 HF_TO_GGUF 物件中對應的儲存庫路徑,向 Hugging Face 發出 API 呼叫。我們會特別尋找以 '.gguf' 副檔名結尾的檔案,也就是量化模型檔案。
收到回應後,我們會抽取 GGUF 檔案名稱,並把它們存入 availableGGUFs 狀態,使用 setAvailableGGUFs 更新狀態。這樣便可向用戶顯示可下載的 GGUF 模型變體清單。
擷取可用 GGUF 檔案
const fetchAvailableGGUFs = async (modelFormat: string) => {
if (!modelFormat) {
Alert.alert('Error', 'Please select a model format first.');
return;
}
try {
const repoPath = HF_TO_GGUF[modelFormat as keyof typeof HF_TO_GGUF];
if (!repoPath) {
throw new Error(
`No repository mapping found for model format: ${modelFormat}`,
);
}
const response = await axios.get(
`https://huggingface.co/api/models/${repoPath}`,
);
if (!response.data?.siblings) {
throw new Error('Invalid API response format');
}
const files = response.data.siblings.filter((file: {rfilename: string}) =>
file.rfilename.endsWith('.gguf'),
);
setAvailableGGUFs(files.map((file: {rfilename: string}) => file.rfilename));
} catch (error) {
const errorMessage =
error instanceof Error ? error.message : 'Failed to fetch .gguf files';
Alert.alert('Error', errorMessage);
setAvailableGGUFs([]);
}
};
注意:如尚未匯入 axios 和 Alert,請在檔案頂部加入。
我們要測試函數是否正常運作,先在 UI 加入按鈕來觸發函數,並不再使用 View,改用 SafeAreaView(稍後詳述),再以 ScrollView 顯示可用的 GGUF 檔案。按下按鈕時會觸發 onPress 函數:
<TouchableOpacity onPress={() => fetchAvailableGGUFs('Llama-3.2-1B-Instruct')}>
<Text>Fetch GGUF Files</Text>
</TouchableOpacity>
<ScrollView>
{availableGGUFs.map((file) => (
<Text key={file}>{file}</Text>
))}
</ScrollView>
畫面大致會像這樣:
注意:目前為止的完整程式碼可在
first_checkpoint分支的EdgeLLMBasic資料夾此處查看。
實作模型下載
現在在 handleDownloadModel 函數中實作模型下載功能;用戶按下下載按鈕時便會呼叫此函數。它會從 Hugging Face 下載所選 GGUF 檔案,並儲存至 app 的 Documents 目錄:
模型下載函數
const handleDownloadModel = async (file: string) => {
const downloadUrl = `https://huggingface.co/${
HF_TO_GGUF[selectedModelFormat as keyof typeof HF_TO_GGUF]
}/resolve/main/${file}`;
// we set the isDownloading state to true to show the progress bar and set the progress to 0
setIsDownloading(true);
setProgress(0);
try {
// we download the model using the downloadModel function, it takes the selected GGUF file, the download URL, and a progress callback function to update the progress bar
const destPath = await downloadModel(file, downloadUrl, progress =>
setProgress(progress),
);
} catch (error) {
const errorMessage =
error instanceof Error
? error.message
: 'Download failed due to an unknown error.';
Alert.alert('Error', errorMessage);
} finally {
setIsDownloading(false);
}
};
我們可以把 api 請求寫在 handleDownloadModel 函數內,但為了保持程式碼整潔易讀,會將它放在獨立檔案。handleDownloadModel 會呼叫 downloadModel 函數;該函數位於 src/api,並接收三個參數:modelName、downloadUrl 和 progress 回呼函數。下載期間會觸發回呼以更新進度。下載前,必須先將 selectedModelFormat 狀態設為要下載的模型格式。
在 downloadModel 函數內,我們使用 RNFS 模組(屬於 react-native-fs 程式庫)存取裝置檔案系統。開發者可用它讀取、寫入和管理裝置儲存空間中的檔案。在這個例子中,模型會透過 RNFS.DocumentDirectoryPath 儲存在 app 的 Documents 資料夾,確保 app 可以存取已下載檔案。進度列會相應更新,而進度列元件則定義在 components 資料夾。
建立 src/api/model.ts,並把 repo 中 src/api/model.ts 檔案的程式碼複製過來。邏輯應該很容易理解。src/components 資料夾中的進度列元件也是如此;它只是一個有顏色的 View,其闊度代表下載進度。
現在要測試 handleDownloadModel 函數:在 UI 加入按鈕來觸發函數,並顯示進度列。這會加在之前加入的 ScrollView 下方。
下載模型按鈕
<View style={{ marginTop: 30, marginBottom: 15 }}>
{Object.keys(HF_TO_GGUF).map((format) => (
<TouchableOpacity
key={format}
onPress={() => {
setSelectedModelFormat(format);
}}
>
<Text> {format} </Text>
</TouchableOpacity>
))}
</View>
<Text style={{ marginBottom: 10, color: selectedModelFormat ? 'black' : 'gray' }}>
{selectedModelFormat
? `Selected: ${selectedModelFormat}`
: 'Please select a model format before downloading'}
</Text>
<TouchableOpacity
onPress={() => {
handleDownloadModel("Llama-3.2-1B-Instruct-Q2_K.gguf");
}}
>
<Text>Download Model</Text>
</TouchableOpacity>
{isDownloading && <ProgressBar progress={progress} />}
UI 會顯示支援的模型格式清單,以及下載模型的按鈕。用戶選擇模型格式並按下按鈕後,便會顯示進度列並開始下載。測試時我們把要下載的模型寫死為 Llama-3.2-1B-Instruct-Q2_K.gguf,因此要讓函數正常運作,必須選擇 Llama-3.2-1B-Instruct 作為模型格式;畫面應該如下:
注意:目前為止的完整程式碼可在
second_checkpoint分支的EdgeLLMBasic資料夾此處查看。
模型載入和初始化
接着,我們會按照 llama.rn 文件(此處可查閲),把已下載的模型載入 Llama context。如果 context 已存在,便先釋放它、把 context 設為 null,並把對話重設至初始狀態。然後使用 initLlama 函數,把模型載入新的 context,並以剛初始化的 context 更新狀態。
模型載入函數
import {initLlama, releaseAllLlama} from 'llama.rn';
import RNFS from 'react-native-fs'; // File system module
...
const loadModel = async (modelName: string) => {
try {
const destPath = `${RNFS.DocumentDirectoryPath}/${modelName}`;
// Ensure the model file exists before attempting to load it
const fileExists = await RNFS.exists(destPath);
if (!fileExists) {
Alert.alert('Error Loading Model', 'The model file does not exist.');
return false;
}
if (context) {
await releaseAllLlama();
setContext(null);
setConversation(INITIAL_CONVERSATION);
}
const llamaContext = await initLlama({
model: destPath,
use_mlock: true,
n_ctx: 2048,
n_gpu_layers: 1
});
console.log("llamaContext", llamaContext);
setContext(llamaContext);
return true;
} catch (error) {
Alert.alert('Error Loading Model', error instanceof Error ? error.message : 'An unknown error occurred.');
return false;
}
};
用戶按下下載按鈕時,我們需要呼叫 loadModel 函數,因此要在下載成功完成後,於 handleDownloadModel 函數內呼叫它。
// inside the handleDownloadModel function, just after the download is complete
if (destPath) {
await loadModel(file);
}
要測試模型載入,可在 console.log 中輸出 context,並在 loadModel 函數內加入記錄,以檢查模型是否已正確載入。UI 維持原樣,因為按下下載按鈕會觸發 handleDownloadModel,而它會在內部呼叫 loadModel。要查看 console.log 輸出,需開啟 Developer Tools:在終端機按 j(該終端機已執行 npm start)。如果一切正常,便會在主控台看到 context。

注意:目前為止的完整程式碼可在
third_checkpoint分支的EdgeLLMBasic資料夾此處查看。
實作聊天功能
模型已載入 context,現在可以實作對話邏輯。我們會定義一個名為 handleSendMessage 的函數,並在用戶提交輸入時觸發。此函數會更新對話狀態,並透過 context.completion 把更新後的對話傳給模型。模型回應會再用來更新對話,因此這個函數會更新對話兩次。
聊天函數
const handleSendMessage = async () => {
// Check if context is loaded and user input is valid
if (!context) {
Alert.alert('Model Not Loaded', 'Please load the model first.');
return;
}
if (!userInput.trim()) {
Alert.alert('Input Error', 'Please enter a message.');
return;
}
const newConversation: Message[] = [
// ... is a spread operator that spreads the previous conversation array to which we add the new user message
...conversation,
{role: 'user', content: userInput},
];
setIsGenerating(true);
// Update conversation state and clear user input
setConversation(newConversation);
setUserInput('');
try {
// we define list the stop words for all the model formats
const stopWords = [
'</s>',
'<|end|>',
'user:',
'assistant:',
'<|im_end|>',
'<|eot_id|>',
'<|end▁of▁sentence|>',
'<|end▁of▁sentence|>',
];
// now that we have the new conversation with the user message, we can send it to the model
const result = await context.completion({
messages: newConversation,
n_predict: 10000,
stop: stopWords,
});
// Ensure the result has text before updating the conversation
if (result && result.text) {
setConversation(prev => [
...prev,
{role: 'assistant', content: result.text.trim()},
]);
} else {
throw new Error('No response from the model.');
}
} catch (error) {
// Handle errors during inference
Alert.alert(
'Error During Inference',
error instanceof Error ? error.message : 'An unknown error occurred.',
);
} finally {
setIsGenerating(false);
}
};
要測試 handleSendMessage 函數,需要在 UI 加入文字輸入欄和按鈕來觸發函數,並在 ScrollView 元件中顯示對話。
簡單聊天 UI
<View
style={{
flexDirection: "row",
alignItems: "center",
marginVertical: 10,
marginHorizontal: 10,
}}
>
<TextInput
style={{flex: 1, borderWidth: 1}}
value={userInput}
onChangeText={setUserInput}
placeholder="Type your message here..."
/>
<TouchableOpacity
onPress={handleSendMessage}
style={{backgroundColor: "#007AFF"}}
>
<Text style={{ color: "white" }}>Send</Text>
</TouchableOpacity>
</View>
<ScrollView>
{conversation.map((msg, index) => (
<Text style={{marginVertical: 10}} key={index}>{msg.content}</Text>
))}
</ScrollView>
如果實作正確,應該可以向模型發送訊息,並在 ScrollView 元件中查看對話。畫面當然不算美觀,但已是個不錯的開始,稍後會再改善 UI。
結果應該如下:
注意:目前為止的完整程式碼可在
fourth_checkpoint分支的EdgeLLMBasic資料夾此處查看。
UI 與邏輯
核心功能已實作完成,現在可專注處理 UI。UI 很直接,由模型選擇畫面(列出模型)和聊天介面(包括對話記錄及用戶輸入欄)組成。模型下載期間會顯示進度列。我們刻意不加入太多畫面,讓 app 保持簡單並聚焦核心功能。為追蹤 app 目前所在畫面,我們會增加另一個狀態變數 currentPage;它是一個字串,可以是 modelSelection 或 conversation。把它加入 App.tsx 檔案。
const [currentPage, setCurrentPage] = useState<
'modelSelection' | 'conversation'
>('modelSelection'); // Navigation state
CSS 會使用 EdgeLLMBasic repo 中相同的樣式,你可以從該處複製。
我們會先在 App.tsx 檔案處理模型選擇畫面,加入模型格式清單(你需要匯入所需項目,並刪除之前用來測試的 SafeAreaView 元件內的舊程式碼):
模型選擇 UI
<SafeAreaView style={styles.container}>
<ScrollView contentContainerStyle={styles.scrollView}>
<Text style={styles.title}>Llama Chat</Text>
{/* Model Selection Section */}
{currentPage === 'modelSelection' && (
<View style={styles.card}>
<Text style={styles.subtitle}>Choose a model format</Text>
{modelFormats.map(format => (
<TouchableOpacity
key={format.label}
style={[
styles.button,
selectedModelFormat === format.label && styles.selectedButton,
]}
onPress={() => handleFormatSelection(format.label)}>
<Text style={styles.buttonText}>{format.label}</Text>
</TouchableOpacity>
))}
</View>
)}
</ScrollView>
</SafeAreaView>
我們使用 SafeAreaView,確保 app 在不同螢幕大小和方向的裝置上都能正確顯示,並像上一節一樣使用 ScrollView,讓用戶可以捲動瀏覽模型格式。我們亦用 modelFormats.map 逐項讀取 modelFormats 陣列,並把每種格式顯示為按鈕;選取格式時按鈕樣式會改變。只有在 currentPage 狀態設為 currentPage 的值 modelSelection 時,才會顯示模型選擇畫面;這是透過 && 運算子實現。TouchableOpacity 元件則讓用戶按下按鈕選擇模型格式。
現在在 App.tsx 檔案中定義 handleFormatSelection:
const handleFormatSelection = (format: string) => {
setSelectedModelFormat(format);
setAvailableGGUFs([]); // Clear any previous list
fetchAvailableGGUFs(format);
};
我們會把所選模型格式存入狀態,並清除先前其他選擇留下的 GGUF 檔案清單,然後擷取所選格式的新 GGUF 檔案清單。 你的裝置畫面應該如下:
接着,在模型格式選擇區下方加入一個檢視區,顯示所選格式已可用的 GGUF 檔案清單。
可用 GGUF 檔案 UI
{
selectedModelFormat && (
<View>
<Text style={styles.subtitle}>Select a .gguf file</Text>
{availableGGUFs.map((file, index) => (
<TouchableOpacity
key={index}
style={[
styles.button,
selectedGGUF === file && styles.selectedButton,
]}
onPress={() => handleGGUFSelection(file)}>
<Text style={styles.buttonTextGGUF}>{file}</Text>
</TouchableOpacity>
))}
</View>
)
}
只有當 selectedModelFormat 狀態並非 null(即用戶已選擇模型格式)時,才顯示 GGUF 檔案清單。
我們要在 App.tsx 檔案中定義 handleGGUFSelection 函數,按下所選 GGUF 檔案時會觸發提示,確認是否下載。如果用戶按下 Yes,便會開始下載;否則會清除所選 GGUF 檔案。
確認下載提示
const handleGGUFSelection = (file: string) => {
setSelectedGGUF(file);
Alert.alert(
'Confirm Download',
`Do you want to download ${file}?`,
[
{
text: 'No',
onPress: () => setSelectedGGUF(null),
style: 'cancel',
},
{text: 'Yes', onPress: () => handleDownloadAndNavigate(file)},
],
{cancelable: false},
);
};
const handleDownloadAndNavigate = async (file: string) => {
await handleDownloadModel(file);
setCurrentPage('conversation'); // Navigate to conversation after download
};
handleDownloadAndNavigate 是一個簡單函數,會呼叫 handleDownloadModel(已在前文實作)下載所選 GGUF 檔案,並在下載完成後前往對話畫面。
現在按下 GGUF 檔案後,應該會出現提示,讓我們確認或取消下載:
當擷取可用 GGUF 檔案時,可在檢視區加入簡單的 ActivityIndicator 顯示載入狀態。為此,需要匯入 ActivityIndicator(來自 react-native),並把 isFetching 定義為布林狀態變數;在 fetchAvailableGGUFs 函數開始時設為 true,結束時設為 false,例子可見程式碼。然後把 ActivityIndicator 加入檢視區,放在 {availableGGUFs.map((file, index) => (...))} 之前,讓用戶看到 GGUF 檔案正在擷取。
{isFetching && (
<ActivityIndicator size="small" color="#2563EB" />
)}
擷取 GGUF 檔案時,app 會短暫顯示如下畫面:
現在按下各種模型格式,便可查看其可用的 GGUF 檔案;按下 GGUF 檔案時,也會看到確認是否下載模型的提示。
接着要在模型選擇畫面加入進度列:像之前一樣,將 ProgressBar 元件從 src/components/ProgressBar.tsx 匯入 App.tsx 檔案,並把它加在 {availableGGUFs.map((file, index) => (...))} 檢視之後,讓下載模型時顯示進度列。
下載進度列
{
isDownloading && (
<View style={styles.card}>
<Text style={styles.subtitle}>Downloading : </Text>
<Text style={styles.subtitle2}>{selectedGGUF}</Text>
<ProgressBar progress={progress} />
</View>
);
}
下載進度列現在會顯示在模型選擇畫面底部,因此用戶可能需要向下捲動才看得到。為解決這個問題,我們會修改顯示邏輯:只有在 currentPage 狀態設為 'modelSelection',而且沒有正在進行的模型下載時,才顯示模型選擇畫面。
{currentPage === 'modelSelection' && !isDownloading && (
<View style={styles.card}>
<Text style={styles.subtitle}>Choose a model format</Text>
...
確認下載模型後,畫面應該如下:
注意:目前為止的完整程式碼可在
fifth_checkpoint分支的EdgeLLMBasic資料夾此處查看。
模型選擇畫面已完成,現在可以開始建立帶有聊天介面的對話畫面。只有當 currentPage 設為 conversation 時,才會顯示此畫面。我們會加入對話記錄和用戶輸入欄;對話記錄會放在可捲動檢視區,而用戶輸入欄會固定在底部、位於可捲動區之外。每則訊息會按角色(用戶或助理)以不同顏色顯示。
在模型選擇畫面下方加入對話畫面的檢視區:
對話 UI
{currentPage == 'conversation' && !isDownloading && (
<View style={styles.chatContainer}>
<Text style={styles.greetingText}>
🦙 Welcome! The Llama is ready to chat. Ask away! 🎉
</Text>
{conversation.slice(1).map((msg, index) => (
<View key={index} style={styles.messageWrapper}>
<View
style={[
styles.messageBubble,
msg.role === 'user'
? styles.userBubble
: styles.llamaBubble,
]}>
<Text
style={[
styles.messageText,
msg.role === 'user' && styles.userMessageText,
]}>
{msg.content}
</Text>
</View>
</View>
))}
</View>
)}
我們會為用戶訊息和模型訊息使用不同樣式,並使用 conversation.slice(1) 移除對話中的第一則訊息,即 system 訊息。
現在可在畫面底部加入用戶輸入欄和傳送按鈕(不可放在 ScrollView 內)。如前所述,我們會使用 handleSendMessage 函數,把用戶訊息傳給模型,並以模型回應更新對話狀態。
傳送按鈕與輸入欄
{currentPage === 'conversation' && (
<View style={styles.inputContainer}>
<TextInput
style={styles.input}
placeholder="Type your message..."
placeholderTextColor="#94A3B8"
value={userInput}
onChangeText={setUserInput}
/>
<View style={styles.buttonRow}>
<TouchableOpacity
style={styles.sendButton}
onPress={handleSendMessage}
disabled={isGenerating}>
<Text style={styles.buttonText}>
{isGenerating ? 'Generating...' : 'Send'}
</Text>
</TouchableOpacity>
</View>
</View>
)}
用戶按下傳送按鈕時,會呼叫 handleSendMessage 函數,並把 isGenerating 狀態設為 true。接着停用傳送按鈕,並把文字改為 'Generating...'。模型完成生成回應後,isGenerating 狀態會設回 false,按鈕文字則改回 'Send'。
注意:目前為止的完整程式碼可在
main分支的EdgeLLMBasic資料夾此處查看。
現在對話頁面應該如下:
恭喜你!你剛完成第一個 AI 聊天機械人的核心功能,程式碼可在此處取得。現在可以開始為 app 加入更多功能,令它更易用、更有效率。
其他功能
app 現在功能完整:可以下載模型、選擇 GGUF 檔案,並與模型聊天,但用戶體驗仍有改善空間。在 EdgeLLMPlus repo 中,我加入了一些其他功能,例如即時生成、自動捲動、推論速度追蹤,以及像 deepseek-qwen-1.5B 那樣顯示模型思考過程等……本文篇幅有限,不會詳談所有內容,但會介紹部分概念和實作方法;完整程式碼可在 repo 中查看。
即時生成
app 會逐步生成回應,每次產生一個 token,而不是一次過輸出整批內容。這樣可改善用戶體驗,讓用戶在回應形成期間便開始閲讀。我們會使用 callback 函數,並在 context.completion 中呼叫;每生成一個 token 便會觸發它,讓我們相應更新 conversation 狀態。
自動捲動
自動捲動會在新增內容時自動把聊天檢視區捲至底部,確保用戶一直看得到最新訊息或 token。實作時要使用 ScrollView 的參照,以程式方式控制捲動位置;新增訊息時使用 scrollToEnd 方法,把 ScrollView 捲至 conversation 狀態所對應內容的底部。我們亦會定義 autoScrollEnabled 狀態變數;用戶向上捲動至距離 ScrollView 底部超過 100px 時,便把它設為 false。
推論速度追蹤
推論速度追蹤會計算生成每個 token 所需的時間,並顯示在模型生成的每則訊息下方。這項功能容易實作,因為 CompletionResult 物件由 context.completion 函數傳回,並包含 timings 屬性;這是一個列出推論流程多項指標的字典。我們可以使用 predicted_per_second 指標追蹤模型速度。
思考過程
思考過程功能會像 deepseek-qwen-1.5B 一樣顯示模型的思考過程。app 會識別特殊 token,例如 和 ,以處理模型的內部推理或「想法」。遇到 token 時,app 會進入「思考區塊」,收集代表模型推理過程的 token。偵測到結尾的 token 後,便會抽取已收集的思考內容並與訊息關聯,讓用戶切換是否顯示模型的推理過程。要實作此功能,需要加入 thought 和 showThought 屬性至 Message 類型。message.thought 會儲存模型的推理內容,而 message.showThought 是布林值;用戶按下訊息以切換思考內容顯示狀態時,會將它設為 true。
Markdown 呈現
app 使用 react-native-markdown-display 套件在對話中呈現 Markdown,讓程式碼以更理想的格式顯示。
模型管理
我們加入 checkDownloadedModels 函數至 App.tsx 檔案,檢查模型是否已下載至裝置;若尚未下載,便會下載,若已下載,則直接載入 context。我們亦在 UI 加入一些元素,顯示模型是否已下載。
停止/返回按鈕
我們在 UI 加入兩個重要按鈕:停止和返回。停止按鈕會停止生成回應;返回按鈕會前往模型選擇畫面。為此,我們加入 handleStopGeneration 函數至 App.tsx 檔案,透過呼叫 context.stop 停止生成回應,並把 isGenerating 狀態設為 false。我們亦加入 handleBack 函數至 App.tsx,把 currentPage 狀態設為 modelSelection,以返回模型選擇畫面。
5. 除錯方法
使用 Chrome DevTools 除錯
除錯時,我們會像網頁開發一樣使用 Chrome DevTools:
- 在 Metro bundler 終端機按
j,啟動 Chrome DevTools - 前往「Sources」分頁
3. 尋找你的原始碼檔案
4. 按下行號設定中斷點
5. 使用除錯控制項(右上角):
- Step Over - 執行目前一行
- Step Into - 進入函數呼叫
- Step Out - 離開函數
- Continue - 執行至下一個中斷點
常見除錯技巧
- 主控台記錄
console.log('Debug value:', someValue);
console.warn('Warning message');
console.error('Error details');
這會在 Chrome DevTools 主控台輸出記錄。
- Metro Bundler 問題 如果遇到 Metro bundler 問題,可以先嘗試清除快取:
# Clear Metro bundler cache
npm start --reset-cache
- 建置錯誤
# Clean and rebuild
cd android && ./gradlew clean
cd ios && pod install
6. 可以加入的額外功能
要改善用戶體驗,可以加入以下功能:
模型管理:
- 讓用戶從裝置刪除模型
- 加入功能,一次刪除裝置上所有已下載模型
- 在 UI 加入效能追蹤功能,以追蹤記憶體和 CPU 用量
模型選擇:
- 讓用戶搜尋模型
- 讓用戶按名稱、大小等條件排序模型
- 在 UI 顯示模型大小
- 支援 VLM
聊天介面:
- 以顏色顯示程式碼
- 數學公式格式化
我相信你一定想到不少很棒的 app 新功能,歡迎自行實作並與社羣分享 🤗
7. 鳴謝
感謝以下人士審閲這篇網誌文章並提供寶貴意見:
他們的專業知識和建議有助提升本指南的質素和準確度。
8. 結語
現在你已擁有一款可執行以下操作的 React Native app:
- 從 Hugging Face 下載模型
- 在本機執行推論
- 提供流暢的聊天體驗
- 追蹤模型效能
這個實作可作為基礎,讓你建立更複雜的 AI 流動應用程式。選擇模型和調整參數時,記得考慮裝置能力。
祝編碼愉快! 🚀
來源:Hugging Face Blog · huggingface.co


