Практическое руководство: как собрать локальный AI-агент для iPhone с llama.cpp и Metal

Почему локальный агент на iPhone — это ад и мечта одновременно

Представьте: ваш iPhone самостоятельно отправляет сообщения, ищет информацию в календаре, управляет умным домом — и всё это без единого запроса в облако. Никаких подписок, никакой слежки, полная приватность. Звучит как фантастика? На самом деле это уже работает. Но путь к этой утопии усеян костями неверно выбранных моделей, перегретых процессоров и разочарований в человечество.

Основная проблема в том, что мобильные LLM до 2025 года были либо тупыми, либо прожорливыми. Модели на 7-8 миллиардов параметров жрали память как не в себя, а маленькие 1-2B модели не умели даже толком поддерживать диалог, не говоря уже о tool calling (вызове внешних инструментов). Всё изменилось с появлением архитектур типа Llama 3.2 3B и Qwen2.5 3B — они стали тем самым золотым сечением между размером и интеллектом.

1 Выбираем модель: не всё то золото, что блестит

Здесь большинство разработчиков наступают на первые грабли. Берут первую попавшуюся модель с Hugging Face, конвертируют её в GGUF и удивляются, почему агент не понимает, что от него хотят. Для tool calling нужны модели, которые обучены на специфических данных вызовов функций в JSON-формате.

Лично я остановился на Llama 3.2 3B Instruct — её создатели специально дообучили модель на датасетах вызовов функций, и она стабильно возвращает валидный JSON даже в сложных сценариях. Если вы только начинаете, посмотрите мой предыдущий гайд про создание мобильного приложения с локальным ИИ, там разобраны основы.

2 Квантование: искусство жертвовать тем, чего не жалко

Q4_K_M — это не просто случайные буквы. Это конкретный алгоритм сжатия весов модели, который отбрасывает наименее значимые биты, сохраняя при этом 99% качества. Расшифровывается как "4-битное квантование с блочным размером K и средним значением". В переводе на русский: мы экономим 75% памяти ценой незаметного падения точности.

# Конвертируем модель в GGUF и сразу квантуем в Q4_K_M
python3 convert.py --outfile llama-3.2-3b-instruct.Q4_K_M.gguf \
  --outtype q4_k_m \
  ~/Downloads/llama-3.2-3b-instruct/

# Альтернативно используем quantize из llama.cpp
./quantize ~/models/llama-3.2-3b-instruct.f16.gguf \
  ~/models/llama-3.2-3b-instruct.Q4_K_M.gguf q4_k_m

3 Собираем llama.cpp с Metal: танцы с бубном вокруг Xcode

Самая болезненная часть процесса. Официальная документация llama.cpp предполагает, что у вас установлены все зависимости, но в реальности Homebrew вечно что-то ломает. Вот рабочий рецепт на март 2026:

# Клонируем репозиторий с актуальными правками для Metal
git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp

# Переключаемся на стабильную ветку (на 16.03.2026 это 'master')
git checkout master

# Собираем с поддержкой Metal и BLAS (ускоряет вычисления)
LLAMA_METAL=1 make -j8

# Проверяем, что Metal работает
./main -m ~/models/llama-3.2-3b-instruct.Q4_K_M.gguf \
  -p "Hello, Metal!" -n 10 -ngl 99

Флаг -ngl 99 означает "загрузить 99% слоев на GPU". Metal на iPhone отлично справляется с 3B моделью, оставляя CPU свободным для логики приложения. Если сборка падает с ошибкой, проверьте версию Xcode — требуется 16.2 или новее.

4 Интеграция в Swift-приложение: где собака зарыта

Тут многие разработчики совершают фатальную ошибку — пытаются вызывать llama.cpp через system() или Process. Так делать нельзя! iOS убивает фоновые процессы без церемоний. Правильный путь — встроить llama.cpp как библиотеку в ваш проект.

// Пример вызова llama.cpp через C-интерфейс в Swift
import Foundation

class LocalAIAgent {
    private var modelContext: OpaquePointer?
    
    func loadModel(path: String) throws {
        let params = llama_model_default_params()
        modelContext = llama_load_model_from_file(path, params)
        
        if modelContext == nil {
            throw NSError(domain: "AI", code: 1, 
                         userInfo: [NSLocalizedDescriptionKey: "Failed to load model"])
        }
    }
    
    func generateToolCall(prompt: String) -> String {
        // Системный промпт для tool calling
        let systemPrompt = """
        You are an AI assistant that can call tools. 
        Respond ONLY with valid JSON in this format:
        {"tool": "tool_name", "parameters": {"key": "value"}}
        """
        
        let fullPrompt = "[INST]" + systemPrompt + "\n" + prompt + "[/INST]"
        
        // Здесь происходит магия генерации с использованием llama_decode
        // Полный код слишком объёмный для примера
        return callLlamaCpp(fullPrompt)
    }
}

Самая хитрая часть — управление памятью. Llama.cpp аллоцирует буферы под тензоры, и если не чистить их после каждой сессии, приложение будет убито системой через 2-3 минуты. Обязательно вызывайте llama_free в deinit и используйте autoreleasepool для временных объектов.

5 Настройка генерации: почему temperature 0.1 — ваш новый лучший друг

Для tool calling нужна детерминированность. Случайные креативные ответы — последнее, что вам нужно, когда агент решает, какую команду выполнить. Вот мои настройки на март 2026:

{
  "temperature": 0.1,           // Почти детерминировано
  "top_p": 0.95,               // Убираем совсем уж маловероятные варианты
  "top_k": 40,                 // Ограничиваем выбор топ-40 токенами
  "min_p": 0.05,               // Новый параметр в llama.cpp 2025+
  "repeat_penalty": 1.1,       // Слегка штрафуем повторения
  "frequency_penalty": 0.1,    // Штраф за частые токены
  "presence_penalty": 0.1,     // Штраф за уже упомянутые
  "mirostat": 2,               // Включаем mirostat для контроля энтропии
  "mirostat_tau": 3.0,         // Целевой уровень perplexity
  "mirostat_eta": 0.2,         // Скорость обучения mirostat
  "typical_p": 1.0,            // Типичная выборка выключена
  "tfs_z": 1.0,                // Tail-free sampling выключен
  "seed": 42                   // Фиксируем сид для воспроизводимости
}

Параметр min_p появился в конце 2024 года и стал спасением для маленьких моделей. Он отсекает токены с вероятностью ниже указанной, даже если они входят в top_p. Для 3B моделей значение 0.05-0.1 работает идеально.

FAQ: вопросы, которые вы зададите через час отладки

Что дальше? От агента к экосистеме

Когда базовый агент работает, начинается самое интересное. Добавьте векторную базу данных для долговременной памяти (ChromaDB портирована на iOS), подключите голосовой интерфейс через Whisper.cpp, научите агента работать с локальными API ваших приложений.

Самое безумное, что можно сделать — связать несколько iPhone в кластер через Bluetooth LE. Один девайс работает как координатор, другие как вычислительные узлы. Об этом я писал в статье про соединение iPhone и Mac в суперкомпьютер — те же принципы работают для связки iPhone-iPhone.

И последнее: не забудьте про энергопотребление. Пользователь не обрадуется, если ваш агент съест 40% батареи за час. Мониторьте температуру и GPU-загрузку, делайте паузы между запросами. Идеальный агент работает незаметно — как дворецкий, который появляется только когда нужен.

Подписаться на канал