llama.rn

环境要求

• 已创建的 React Native 项目（v0.10 起要求启用新架构）
• Node.js 与 npm 环境（使用 Bun 时需将 llama.rn 标记为受信任包）
• iOS/Android 原生构建环境（Xcode 或 Android 构建工具链）
• 已准备好 GGUF 格式的模型文件，多模态还需对应 mmproj 文件

安装与启动步骤

1. 1安装 llama.rn

   在 React Native 项目根目录执行。postinstall 会自动下载 iOS 与 Android 预编译产物并做 SHA-256 校验，已下载的会复用。

   npm install llama.rn

   复制

2. 2确认新架构

   v0.10 起必须使用 React Native 新架构；若需旧架构支持或 v0.9.x 文档，请改用 v0.9 分支。

3. 3准备 GGUF 模型

   把下载好的 GGUF 模型放到应用可访问的路径，代码中以 file:// 开头的完整路径引用。多模态场景还需额外准备 mmproj 投影文件。

4. 4读取模型信息

   先用 loadLlamaModelInfo 验证模型文件路径正确、可被解析，控制台会打印出模型元信息。

   import { loadLlamaModelInfo } from 'llama.rn'
   
   const modelPath = 'file:///your/path/model.gguf'
   console.log('Model Info:', await loadLlamaModelInfo(modelPath))

   复制

5. 5初始化上下文

   用 initLlama 加载模型创建上下文，首次加载耗时较长；n_gpu_layers 控制放入 GPU 的层数，可按设备调整。

   import { initLlama } from 'llama.rn'
   
   const context = await initLlama({
     model: modelPath,
     use_mlock: true,
     n_ctx: 2048,
     n_gpu_layers: 99,
   })

   复制

6. 6发起对话补全

   向 context.completion 传入 messages 做聊天补全，或传 prompt 做文本补全；第二个参数是流式 token 回调。

   const stopWords = ['', '<|end|>', '<|eot_id|>', '<|end_of_text|>', '<|im_end|>']
   
   const msgResult = await context.completion(
     {
       messages: [
         { role: 'system', content: 'This is a conversation between user and assistant, a friendly chatbot.' },
         { role: 'user', content: 'Hello!' },
       ],
       n_predict: 100,
       stop: stopWords,
     },
     (data) => {
       const { token } = data
     },
   )
   console.log('Result:', msgResult.text)

   复制

关键配置

如何确认成功

调用 loadLlamaModelInfo 打印出模型信息，或 initLlama 成功返回 context 并输出 completion 的 text 与 timings，即表示推理链路可用。

常见问题

注意事项

• 首次 initLlama 加载模型可能耗时较久，需耐心等待。
• 模型必须放在应用可访问的路径，并以 file:// 形式传入。
• Android 的 Hexagon NPU 加速目前为实验特性。
• TTS 为实验功能，用完 vocoder 后应调用 releaseVocoder 释放资源。