Back to blog
    React Nativellama.cppon-device AIcross-platformllama.rn

    在 React Native 中使用 llama.rn 實現裝置端 AI

    如何在 React Native 應用程式中直接在使用者手機上運行語言模型。使用 llama.rn 的設定、模型載入、串流生成和跨平台考量。

    Edward Xi Yang

    llama.rn 是一個 React Native 函式庫，提供連接 llama.cpp 的 JavaScript 繫結。它透過相同的 JavaScript API 在 iOS（Metal）和 Android（CPU/Vulkan）上原生運行 GGUF 語言模型。

    對 React Native 開發者來說，這意味著一套程式碼、一個 API、零雲端依賴的裝置端 AI。

    安裝

    npm install llama.rn
# 或
yarn add llama.rn

    iOS 需執行 pod install：

    cd ios && pod install

    Android 上，原生函式庫會透過 autolinking 自動包含。

    Expo

    如果您使用 Expo，由於 llama.rn 包含原生程式碼，需要開發建置版本（非 Expo Go）：

    npx expo prebuild
npx expo run:ios  # 或 run:android

    載入模型

    import { initLlama, LlamaContext } from "llama.rn";

let context: LlamaContext | null = null;

async function loadModel(modelPath: string) {
  context = await initLlama({
    model: modelPath,
    n_ctx: 2048,        // 上下文視窗
    n_threads: 4,       // CPU 執行緒
    n_gpu_layers: 99,   // 卸載到 GPU（Metal/Vulkan）
    use_mlock: true,    // 鎖定模型在記憶體中
  });

  console.log("Model loaded successfully");
}

    模型路徑

    模型路徑必須指向裝置檔案系統上的本地文件。如何將文件放到裝置上取決於您的交付策略：

    隨應用程式捆綁：

    // iOS：複製到應用程式 bundle，透過 RNFS 參照
import RNFS from "react-native-fs";
const modelPath = `${RNFS.MainBundlePath}/model.gguf`;

// Android：首次啟動時從 assets 複製到 files 目錄
const modelPath = `${RNFS.DocumentDirectoryPath}/model.gguf`;

    安裝後下載：

    import RNFS from "react-native-fs";

const modelUrl = "https://cdn.example.com/model.gguf";
const modelPath = `${RNFS.DocumentDirectoryPath}/model.gguf`;

const download = RNFS.downloadFile({
  fromUrl: modelUrl,
  toFile: modelPath,
  progress: (res) => {
    const percentage = (res.bytesWritten / res.contentLength) * 100;
    setDownloadProgress(percentage);
  },
});

await download.promise;

    生成文字

    簡單生成

    async function generate(prompt: string): Promise<string> {
  if (!context) throw new Error("Model not loaded");

  const result = await context.completion({
    prompt: prompt,
    n_predict: 256,
    temperature: 0.7,
    top_p: 0.9,
    stop: ["</s>", "<|eot_id|>"],  // 停止 token
  });

  return result.text;
}

    串流生成

    async function generateStream(
  prompt: string,
  onToken: (token: string) => void
): Promise<string> {
  if (!context) throw new Error("Model not loaded");

  const result = await context.completion(
    {
      prompt: prompt,
      n_predict: 256,
      temperature: 0.7,
      stop: ["</s>", "<|eot_id|>"],
    },
    (data) => {
      // 每生成一個 token 時呼叫
      onToken(data.token);
    }
  );

  return result.text;
}

    聊天完成

    對於多輪對話，使用模型的聊天範本格式化提示：

    interface Message {
  role: "system" | "user" | "assistant";
  content: string;
}

function formatChat(messages: Message[]): string {
  // Llama 3.2 聊天範本
  let prompt = "<|begin_of_text|>";

  for (const msg of messages) {
    prompt += `<|start_header_id|>${msg.role}<|end_header_id|>\n\n${msg.content}<|eot_id|>`;
  }

  prompt += "<|start_header_id|>assistant<|end_header_id|>\n\n";
  return prompt;
}

async function chat(messages: Message[], onToken: (token: string) => void) {
  const prompt = formatChat(messages);
  return generateStream(prompt, onToken);
}

    React Hook 模式

    import { useState, useCallback, useRef } from "react";
import { initLlama, LlamaContext } from "llama.rn";

export function useLlama(modelPath: string) {
  const contextRef = useRef<LlamaContext | null>(null);
  const [isLoaded, setIsLoaded] = useState(false);
  const [isGenerating, setIsGenerating] = useState(false);
  const [response, setResponse] = useState("");

  const load = useCallback(async () => {
    contextRef.current = await initLlama({
      model: modelPath,
      n_ctx: 2048,
      n_threads: 4,
      n_gpu_layers: 99,
    });
    setIsLoaded(true);
  }, [modelPath]);

  const generate = useCallback(async (prompt: string) => {
    if (!contextRef.current) return;
    setIsGenerating(true);
    setResponse("");

    await contextRef.current.completion(
      {
        prompt,
        n_predict: 256,
        temperature: 0.7,
        stop: ["</s>", "<|eot_id|>"],
      },
      (data) => {
        setResponse((prev) => prev + data.token);
      }
    );

    setIsGenerating(false);
  }, []);

  const unload = useCallback(() => {
    contextRef.current?.release();
    contextRef.current = null;
    setIsLoaded(false);
  }, []);

  return { load, generate, unload, isLoaded, isGenerating, response };
}

    在元件中使用

    function AiChat() {
  const { load, generate, unload, isLoaded, isGenerating, response } =
    useLlama(modelPath);
  const [input, setInput] = useState("");

  useEffect(() => {
    load();
    return () => unload();
  }, []);

  return (
    <View style={styles.container}>
      <ScrollView style={styles.responseArea}>
        <Text>{response}</Text>
      </ScrollView>
      <View style={styles.inputRow}>
        <TextInput
          value={input}
          onChangeText={setInput}
          style={styles.input}
          editable={!isGenerating}
        />
        <Button
          title="Send"
          onPress={() => {
            generate(input);
            setInput("");
          }}
          disabled={!isLoaded || isGenerating}
        />
      </View>
    </View>
  );
}

    跨平台考量

    效能一致性

    llama.rn 在兩個平台上執行原生程式碼。JavaScript 橋接僅用於傳遞提示和接收 token。實際推論效能與原生 Swift/Kotlin 整合相同：

    裝置1B 模型（tok/s）3B 模型（tok/s）
    iPhone 15 Pro35-4518-25
    iPhone 1425-3214-18
    Galaxy S2435-4518-25
    中階 Android18-258-12

    JS 橋接每個 token 增加不到 1 毫秒的開銷。可忽略不計。

    模型文件路徑差異

    iOS 和 Android 將文件存儲在不同位置。使用 react-native-fs 取得平台適當的路徑：

    import RNFS from "react-native-fs";
import { Platform } from "react-native";

const modelDir = Platform.OS === "ios"
  ? RNFS.DocumentDirectoryPath
  : RNFS.DocumentDirectoryPath;  // 相同 API，不同底層路徑

    記憶體管理

    React Native 不公開直接的記憶體 API。如需在載入前驗證可用 RAM，可透過原生模組進行平台特定檢查。或者，捕獲載入失敗並顯示適當的訊息。

    React Native 中的模型交付

    策略 1：小模型捆綁

    對於 1B 模型（約 600MB），隨應用程式捆綁是可行的：

    • iOS：作為資源新增到 Xcode 專案
    • Android：對超過 150MB 的文件使用 Android Asset Delivery

    策略 2：所有模型下載

    對於 3B 模型（約 1.7GB）或為了保持初始下載大小較小：

    async function ensureModelReady(): Promise<string> {
  const modelPath = `${RNFS.DocumentDirectoryPath}/model.gguf`;
  const exists = await RNFS.exists(modelPath);

  if (exists) return modelPath;

  // 帶進度的下載
  await RNFS.downloadFile({
    fromUrl: MODEL_CDN_URL,
    toFile: modelPath,
    progress: (res) => {
      updateProgress(res.bytesWritten / res.contentLength);
    },
  }).promise;

  // 驗證完整性
  const hash = await RNFS.hash(modelPath, "sha256");
  if (hash !== EXPECTED_HASH) {
    await RNFS.unlink(modelPath);
    throw new Error("Model download corrupted");
  }

  return modelPath;
}

    正式環境最佳實踐

    1. 延遲載入模型。 僅在使用者存取 AI 功能時載入。
    2. 失焦時卸載。 AI 畫面不在焦點時釋放模型記憶體。
    3. 優雅處理錯誤。 模型載入在低記憶體裝置上可能失敗。顯示清楚的訊息。
    4. 驗證下載。 下載後進行 SHA256 雜湊檢查。損壞的模型會導致當機。
    5. 緩衝 token。 批次 2-3 個 token 後再更新 UI，以獲得更流暢的文字顯示。
    6. 取消支援。 允許使用者在生成中途停止。

    模型品質取決於微調。基礎模型給出通用回應。在您的領域資料上微調的模型（透過 Ertas 或類似平台）給出針對應用程式特定使用場景的回應，在相同硬體上以相同速度運行。

    就本文向 AI 提問

    Ship AI that runs on your users' devices.

    Free plan with 30 credits/mo, no card required. Paid plans from $10/mo USD.

    or view pricing →

    Keep reading

    Guides

    React Native 的 AI：從雲端 API 到裝置端模型

    如何為 React Native 應用程式加入 AI 功能。使用 fetch 的雲端 API 整合、使用 llama.cpp 綁定的裝置端推論，以及從前者遷移到後者的實際路徑。

    Edward Xi Yang
    Guides

    Android 應用程式的 AI：ML Kit、雲端 API 與裝置端 LLM 比較

    Android 應用程式的三條 AI 路徑。Google ML Kit 用於常見任務，雲端 API 提供完整 LLM 能力，裝置端模型透過 llama.cpp 實現成本與隱私。為 Kotlin 開發者提供的實用比較。

    Edward Xi Yang
    Guides

    Flutter 應用程式的 AI：雲端 API、TFLite 與裝置端 LLM

    Flutter 的三條 AI 路徑。透過 http 套件的雲端 API、用於傳統 ML 任務的 TensorFlow Lite，以及透過 llama.cpp 的裝置端 LLM 進行文字生成。為 Dart 開發者提供的實用比較。

    Edward Xi Yang