LLM Inference on Edge: A Fun and Easy Guide to run LLMs via React Native on your Phone!

As LLMs continue to evolve, they are becoming smaller and smarter, enabling them to run directly on your phone. Take, for instance, the DeepSeek R1 Distil Qwen 2.5 with 1.5 billion parameters, this model really shows how advanced AI can now fit into the palm of your hand! In this blog, we will guide you through creating a mobile app that allows you to chat with these powerful models locally. The complete code for this tutorial is available in our EdgeLLM repository. If you've ever felt overwhelmed by the complexity of open-source projects, fear not! Inspired by the Pocket Pal app, we will help you build a straightforward React Native application that downloads LLMs from the Hugging Face hub, ensuring everything remains private and runs on your device. We will utilize llama.rn, a binding for llama.cpp, to load GGUF files efficiently!

This tutorial is designed for anyone who:

• Is interested in integrating AI into mobile applications
• Wants to create a conversational app compatible with both Android and iOS using React Native
• Seeks to develop privacy-focused AI applications that operate entirely offline

By the end of this guide, you will have a fully functional app that allows you to interact with your favorite models.

Before we dive into building our app, let's talk about which models work well on mobile devices and what to consider when selecting them.

When running LLMs on mobile devices, size matters significantly:

Small models (1-3B parameters): Ideal for most mobile devices, offering good performance with minimal latency
Medium models (4-7B parameters): Work well on newer high-end devices but may cause slowdowns on older phones
Large models (8B+ parameters): Generally too resource-intensive for most mobile devices, but can be used if quantized to low precision formats like Q2_K or Q4_K_M

When downloading GGUF models, you'll encounter various quantization formats. Understanding these can help you choose the right balance between model size and performance:

• Basic, straightforward quantization methods
• Each block is stored with:
  • Quantized values (the compressed weights).
  • One (_0) or two (_1) scaling constants.
• Fast but less efficient than newer methods => not used widely anymore
• Introduced in this PR
• Smarter bit allocation than legacy quants
• The K in "K-quants" refers to a mixed quantization format, meaning some layers get more bits for better accuracy.
• Suffixes like _XS, _S, or _M refer to specific mixes of quantization (smaller = more compression), for example :
  • Q3_K_S uses Q3_K for all tensors
  • Q3_K_M uses Q4_K for the attention.wv, attention.wo, and feed_forward.w2 tensors, and Q3_K for the rest.
  • Q3_K_L uses Q5_K for the attention.wv, attention.wo, and feed_forward.w2 tensors, and Q5_K for the rest.
• It still uses the block-based quantization, but with some new features inspired by QuIP
• Smaller file sizes but may be slower on some hardware
• Best for devices with strong compute power but limited memory

Here are some models that perform well on mobile devices:

To find additional GGUF models on Hugging Face:

• Visit huggingface.co/models
• Use the search filters:
  • Visit the GGUF models page
  • Specify the size of the model in the search bar
  • Look for "chat" or "instruct" in the name for conversational models

모델을 선택할 때는 파라미터 개수와 양자화 수준을 모두 고려하세요. 예를 들어, Q2_K 양자화로 7B 모델은 Q8_0 양자화로 2B 모델보다 더 잘 실행될 수 있습니다. 따라서 기기에 작은 모델을 편안하게 설치할 수 있다면, 더 큰 양자화 모델을 사용하는 것이 성능이 더 좋을 수 있습니다.

React Native 는 JavaScript 와 React 를 사용하여 모바일 애플리케이션을 구축하는 데 널리 사용되는 프레임워크입니다. 개발자는 Android 와 iOS 플랫폼 모두에서 실행되는 앱을 만들 수 있으며, 상당한 코드를 공유함으로써 개발 프로세스를 가속화하고 유지보수 노력을 줄일 수 있습니다.

React Native 로 코딩하기 전에 환경을 올바르게 설정해야 합니다.

Node.js: Node.js 는 JavaScript 코드를 실행할 수 있는 JavaScript 런타임입니다. React Native 프로젝트에서 패키지와 종속성을 관리하는 데 필수적입니다. Node.js 다운로드에서 설치할 수 있습니다.react-native-community/cli: 이 명령어는 React Native 명령줄 인터페이스 (CLI) 를 설치하며, 앱을 생성하고 구축하고 관리하는 데 도구를 제공합니다. 다음 명령어를 실행하여 설치하세요:

npm i @react-native-community/cli

개발 중에 앱을 실행하려면 에뮬레이터 또는 시뮬레이터를 사용해야 합니다:

macOS 에서라면: Windows 나 Linux 에서라면:

• iOS: LambdaTest 와 BrowserStack 같은 클라우드 기반 시뮬레이터에 의존해야 합니다.
• Android: Java Runtime 과 Android Studio 를 설치 -> Device Manager 로 이동하고 에뮬레이터를 생성하세요.

시뮬레이터와 에뮬레이터의 차이점에 대해 궁금하다면, 이 기사의 내용을 읽을 수 있습니다: Emulator 와 Simulator 의 차이, 하지만 간단히 말하면, 에뮬레이터는 하드웨어와 소프트웨어를 모두 복제하고, 시뮬레이터는 오직 소프트웨어만 복제합니다.

Android Studio 를 설정하려면 Expo 의 훌륭한 튜토리얼을 따르세요: Android Studio Emulator Guide

이 프로젝트를 시작해 보겠습니다!

이 프로젝트의 전체 코드는 EdgeLLM repo 에서 찾을 수 있습니다, 두 개의 폴더가 있습니다:

EdgeLLMBasic

: 앱의 간단한 채팅 인터페이스를 가진 기본 구현
EdgeLLMPlus

: 더 복잡한 채팅 인터페이스와 추가 기능을 가진 앱의 향상된 버전

먼저 @react-native-community/cli 를 사용하여 앱을 시작해야 합니다:

npx @react-native-community/cli@latest init <ProjectName>

앱 폴더는 다음과 같이 조직화됩니다:

android/

• 네이티브 Android 프로젝트 파일을 포함합니다
  목적: Android 기기에 앱 구축 및 실행

ios/

• 네이티브 iOS 프로젝트 파일을 포함합니다
  목적: iOS 기기에 앱 구축 및 실행

node_modules/

목적: 프로젝트에서 사용된 모든 npm 종속성을 보유합니다

App.tsx

• TypeScript 로 작성된 앱의 주요 루트 컴포넌트
  목적: 앱 UI 와 논리의 진입점

index.js

• 루트 컴포넌트를 등록합니다 (App)
  목적: React Native 런타임의 진입점입니다. 이 파일을 수정할 필요가 없습니다.

• 루트 컴포넌트를 등록합니다

추가 구성 파일

tsconfig.json

: TypeScript 설정을 구성합니다
babel.config.js

: Babel 을 현대 JavaScript/TypeScript 를 컴파일하기 위해 구성하며, 이는 현대 JS/TS 코드를 오래된 브라우저나 기기와 호환되는 오래된 JS/TS 코드로 변환할 것입니다.
jest.config.js

: React Native 컴포넌트와 논리를 테스트하기 위해 Jest 를 구성합니다.
metro.config.js

: Metro bundler 를 프로젝트에 맞게 커스터마이징합니다. React Native 에专门为 설계된 JavaScript bundler 입니다. 프로젝트의 JavaScript 와 assets 을 받아서 단일 파일로 (또는 효율적인 로딩을 위해 여러 파일로) 묶어주며, 개발 중에 앱에 제공합니다. Metro 는 빠른 인크리멘탈 빌드 최적화, 핫 리로딩 지원, React Native 의 플랫폼별 파일 (.ios.js 또는 .android.js) 처리를 지원합니다.

: Watchman 을 구성합니다. React Native 에서 핫 리로딩을 위해 사용하는 파일 감시 서비스입니다.

프로젝트를 실행하고 가상 디바이스 위에서 어떻게 보이는지 확인하려면 다음 단계를 따르세요:

Repository 를 Clone 합니다: git clone https://github.com/MekkCyber/EdgeLLM.git

프로젝트 디렉토리로 이동합니다: cd EdgeLLMPlus #or cd EdgeLLMBasic

Dependencies 를 설치합니다: npm install

iOS 폴더로 이동하고 설치합니다: cd ios pod install

Metro Bundler 를 시작합니다: 프로젝트 폴더 (EdgeLLMPlus 또는 EdgeLLMBasic) 에서 다음 명령어를 실행하세요: npm start

iOS 또는 Android Simulator 에서 앱을 실행합니다: 다른 터미널을 열고 다음을 실행하세요:
# For iOS npm run ios # For Android npm run android

이것은 빌드하고 앱이 에뮬레이터/시뮬레이터에서 실행되도록 하여, 코딩을 시작하기 전에 프로젝트를 테스트할 수 있게 합니다.

React Native 애플리케이션을 실행하려면 에뮬레이터/시뮬레이터 또는 물리적 디바이스가 필요합니다. 우리는 에뮬레이터를 사용하도록 집중할 것입니다. 왜냐하면 코드 편집기와 디버깅 도구가 옆에 있는 개발 경험을 더 간소화하기 때문입니다.

우리는 개발 환경이 준비되었는지 확인하고, 프로젝트 폴더에 있어야 하며 다음 명령어를 실행해야 합니다:

# Install dependencies
npm install
# Start the Metro bundler
...

새로운 터미널에서 우리는 선택한 플랫폼에서 앱을 실행할 것입니다:

# For iOS
npm run ios
# For Android
...

이것은 에뮬레이터/시뮬레이터에서 앱을 빌드하고 실행하도록 해야 합니다.

먼저, 필요한 패키지를 설치해 보겠습니다. 우리는 Hugging Face Hub 에서 모델을 로드하고 로컬에서 실행하는 것을 목표로 합니다. 이를 위해 다음을 설치해야 합니다:

llama.rn

: llama.cpp 의 React Native 앱용 바인딩입니다.

react-native-fs

: React Native 환경에서 디바이스의 파일 시스템을 관리할 수 있게 합니다.

axios

: Hugging Face Hub API 에 요청을 보내는 라이브러리입니다.

npm install axios react-native-fs llama.rn

우리가 전에 보여준 것처럼 에뮬레이터/시뮬레이터에서 앱을 실행하여 개발을 시작할 수 있습니다.

우리는 App.tsx 파일의 모든 것을 삭제하고 다음과 같은 빈 코드 구조를 생성할 것입니다:

App.tsx

import React from 'react';
import {StyleSheet, Text, View} from 'react-native';
function App(React.JSX.Element {
...

App 함수의 return 문에서 UI 를 렌더링하고, 바깥쪽에서는 논리를 정의하지만 모든 코드는 App 함수 안에 있습니다.

우리는 다음과 같이 보이는 화면을 가질 것입니다:

텍스트 "Hello World" 는 제대로 표시되지 않습니다. 우리는 간단한 View 컴포넌트를 사용하고 있기 때문입니다. 텍스트를 올바르게 표시하려면 SafeAreaView 컴포넌트를 사용해야 하며, 다음 섹션에서 다룰 것입니다.

이제 우리가 현재 앱을 추적해야 할 것을 생각해 봅시다:

Chat-related

• 대화 기록 (사용자와 AI 간의 메시지)
• 현재 사용자 입력

모델 관련 기능

• 선택된 모델 포맷 (예: Llama 1B 또는 Qwen 1.5B)
• 각 모델 포맷에 대한 사용 가능한 GGUF 파일 목록
• 다운로드할 선택된 GGUF 파일
• 모델 다운로드 진행 상황
• 로딩된 모델을 저장하기 위한 컨텍스트
• 모델이 다운로드 중인지 확인하는 보울 (boolean)
• 응답을 생성 중인지 확인하는 보울 (boolean)

이러한 상태를 React의 useState 훅으로 구현하는 방법은 다음과 같습니다 (react 에서 이를 import 해야 합니다).

상태 관리 코드

import { useState } from 'react';
...
type Message = {
...

이는 App.tsx 파일 내부의 App 함수 안에, 그러나 return 문 밖에서 추가됩니다. 이는 로직의 일부이기 때문입니다.

Message 타입은 채팅 메시지의 구조를 정의하며, 각 메시지는 역할 (user 또는 assistant 또는 system) 과 내용 (실제 메시지 텍스트) 을 갖도록 지정합니다.

이제 기본 상태 관리가 설정되었으므로 다음을 어떻게 해야 할지 생각해 보아야 합니다:

• Hugging Face 에서 사용 가능한 GGUF 모델을 가져오기
• 로컬에서 모델을 다운로드하고 관리하기
• 채팅 인터페이스 생성하기
• 메시지 생성 처리하기

다음 섹션에서 하나씩 해보겠습니다...

우선 앱이 지원할 모델 포맷과 해당 리포지토리를 정의해 보겠습니다. 물론 llama.rn은 llama.cpp의 바인딩입니다. 따라서 우리는 GGUF 파일을 로드해야 합니다. 우리가 지원하는 모델에 대한 GGUF 리포지토리를 찾기 위해 Hugging Face 의 검색창을 사용하여 특정 모델에 대한 GGUF 파일을 검색하거나, 여기에서 제공된 quantize_gguf.py 스크립트를 사용하여 모델을 ourselves 으로 양자화하고 파일들을 our hub repository 에 업로드할 수 있습니다.

const modelFormats = [
{label: 'Llama-3.2-1B-Instruct'},
{label: 'Qwen2-0.5B-Instruct'},
...

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.');
...

참고: 이미 import 되지 않은 경우, axios 와 Alert 를 파일의 상단에 import 해야 합니다.

우리는 함수가 올바르게 작동하는지 테스트해야 합니다. UI 에 버튼을 추가하여 함수를 트리거하도록 하되, View 대신 SafeAreaView (그것에 대한 자세한 내용은 나중에) 컴포넌트를 사용하며, 우리는 사용 가능한 GGUF 파일을 ScrollView 컴포넌트에서 표시합니다. onPress 함수는 버튼이 눌릴 때 트리거됩니다.