Imagine: an AI assistant in a mobile app works offline, all data stays on the device. No server transfers, no network latency. Cloud LLMs require constant connectivity, transmit sensitive data, and introduce delays. For medicine or finance, this is unacceptable. An on-device solution solves these issues but requires careful platform-specific integration. We integrate Llama.cpp — an LLM inference library on CPU/GPU — into iOS and Android apps. Let's dive into the technical details: from model selection to thermal management.
How to Choose a Model for an Offline Assistant?
Llama.cpp works with models in GGUF format. Popular options for mobile:
| Model | Quantization | Size | RAM | Speed (iPhone 14) |
|---|---|---|---|---|
| Llama-3.2-1B | Q4_K_M | 0.8 GB | ~1.2 GB | 25–35 t/s |
| Llama-3.2-3B | Q4_K_M | 2.0 GB | ~2.5 GB | 10–15 t/s |
| Phi-3-mini-4k | Q4_K_M | 2.2 GB | ~2.8 GB | 8–12 t/s |
| Gemma-2-2B | Q4_K_M | 1.6 GB | ~2.0 GB | 12–18 t/s |
| Qwen2.5-1.5B | Q4_K_M | 1.0 GB | ~1.4 GB | 20–28 t/s |
On iPhone SE 2nd gen (3 GB RAM), Llama-3.2-3B Q4 runs at the limit — OOM is possible with long contexts. A safe choice for a wide range of devices is models up to 1.5–2 GB. In one project for a financial app, we chose Llama-3.2-1B Q4_K_M, which kept memory usage under 1 GB on iPhone SE. Generation speed was 25–30 t/s, sufficient for answering queries. Thermal throttling was minimized by limiting the context to 1024 tokens.
Problems and Solutions for On-Device LLM
| Problem | Solution |
|---|---|
| OOM at large context | Limit n_ctx to 1024–2048 tokens |
| Thermal throttling | Monitor thermalState, pause between generations |
| Corrupted GGUF file | Verify SHA256 after download |
| Low speed on old devices | Use 1B models with Q4 quantization |
How to Build llama.cpp for iOS?
# Clone repository git clone https://github.com/ggerganov/llama.cpp cd llama.cpp # Build via CMake for iOS cmake -B build-ios \ -DCMAKE_TOOLCHAIN_FILE=ios.toolchain.cmake \ -DPLATFORM=OS64 \ # arm64 only -DLLAMA_METAL=ON \ # Metal GPU acceleration -DLLAMA_STATIC=ON cmake --build build-ios --config Release Result — libllama.a static library. Create a Swift Package with C-bridging header:
// llama_bridge.h #include "llama.h" // Wrappers for Swift-friendly API void* llama_create_context(const char* model_path, int n_ctx, int n_gpu_layers); const char* llama_generate_token(void* ctx, const char* prompt); void llama_free_context(void* ctx); n_gpu_layers — number of layers offloaded to Metal GPU. A value of -1 means all layers on GPU. On iPhone 14 with 6 GB unified memory — use -1. On devices with 3 GB — experiment: too many layers on GPU cause OOM.
Swift Wrapper for Token Streaming
import Foundation actor LlamaSession { private var context: OpaquePointer? private var model: OpaquePointer? func load(modelPath: String, contextSize: Int32 = 2048, gpuLayers: Int32 = -1) throws { var params = llama_model_default_params() params.n_gpu_layers = gpuLayers model = llama_load_model_from_file(modelPath, params) guard model != nil else { throw LlamaError.modelLoadFailed } var ctxParams = llama_context_default_params() ctxParams.n_ctx = UInt32(contextSize) ctxParams.n_batch = 512 context = llama_new_context_with_model(model, ctxParams) } func generate(prompt: String) -> AsyncThrowingStream<String, Error> { AsyncThrowingStream { continuation in Task.detached(priority: .userInitiated) { // Tokenization var tokens = [llama_token](repeating: 0, count: 4096) let nTokens = llama_tokenize(self.model, prompt, Int32(prompt.utf8.count), &tokens, 4096, true, false) // Inference — one token at a time for i in 0..<nTokens { llama_batch_add(&batch, tokens[Int(i)], llama_pos(i), [0], false) } while true { llama_decode(self.context, batch) let nextToken = llama_sample_token_greedy(self.context, &candidates) if nextToken == llama_token_eos(self.model) { break } // Convert token to string var buf = [Int8](repeating: 0, count: 64) llama_token_to_piece(self.model, nextToken, &buf, 64, 0, true) let piece = String(cString: buf) continuation.yield(piece) } continuation.finish() } } } } Streaming tokens via AsyncThrowingStream — users see text as it's generated, without waiting for the full response. This is critical for UX: 10 tokens per second feels acceptable when text appears gradually.
Why Thermal Constraints Are Critical?
Llama.cpp on iPhone heats the device during prolonged generation. iOS throttling: when overheating, the system reduces clock speed, and generation speed drops from 25 t/s to 8–10 t/s. This is not a bug — it's system behavior.
Practical solution: limit the maximum context (n_ctx) to 1024–2048 for short sessions. Pause between requests. Monitor ProcessInfo.processInfo.thermalState on iOS:
NotificationCenter.default.addObserver(forName: ProcessInfo.thermalStateDidChangeNotification, ...) { _ in let state = ProcessInfo.processInfo.thermalState if state == .critical || state == .serious { // Pause generation, notify user } } Typical Integration Mistakes
- Context too large — choose n_ctx ≤ 2048 for mobile devices.
- Ignoring thermal throttling — monitor thermalState and pause.
- Wrong model version — verify GGUF file compatibility with your llama.cpp build.
- Missing hash verification — corrupt files cause crashes.
Android: llama.cpp via NDK
// CMakeLists.txt in jni/ add_library(llama_jni SHARED llama_jni.cpp) target_link_libraries(llama_jni llama ggml) // Kotlin side class LlamaEngine { init { System.loadLibrary("llama_jni") } external fun loadModel(modelPath: String, nGpuLayers: Int): Long // returns handle external fun generateNext(handle: Long, tokens: IntArray): String external fun freeModel(handle: Long) } On Android — Vulkan backend instead of Metal: include LLAMA_VULKAN=ON in CMakeLists. Supported on devices with Vulkan 1.1+, practically all with Android 10+.
Problem on Android: the process does not have a memory limit as a pooled resource — the system may kill the app (SIGKILL) when RAM is insufficient without warning. ComponentCallbacks2.onTrimMemory(TRIM_MEMORY_RUNNING_CRITICAL) — the last chance to free context before process termination.
Model Download: Progress and Verification
GGUF files weigh 1–4 GB. Download via URLSession (iOS) or WorkManager with DownloadManager (Android). SHA256 verification is mandatory: after download, compute the hash and compare with the expected one from the repository on HuggingFace. A corrupted GGUF causes a crash during header parsing or later during inference — better to catch it at verification.
The mobile neural network operates faster without network latency, which is especially important for time-critical applications. Cost savings: a fully offline solution eliminates server infrastructure expenses.
What's Included in Integration
- Analysis of device fleet and selection of optimal quantization model
- Building llama.cpp for iOS (Metal) and/or Android (Vulkan)
- Development of Swift/Kotlin wrapper with asynchronous token streaming
- Implementation of model download with progress and SHA256 verification
- Chat UI with thermal state indication
- Stress testing on real devices and fine-tuning of context parameters
- Integration documentation and support during launch
Estimated Timelines
Single platform, basic chat interface with chosen model — from 3 weeks. Both platforms, multiple model choices, background download, context management — from 7 weeks. Cost is calculated individually.
Our experience: 5 years in mobile development and over 20 projects with on-device ML. We guarantee the solution works on target devices after testing. Get a consultation on model selection and project evaluation. Order integration and see the benefits of an offline AI assistant.