Перейти до основного вмісту

Компіляція моделі.

Огляд​

Model Compiler надає інструмент командного рядка LLiMa під назвою llima-compile, який використовується для компіляції моделей із файлів Hugging Face safetensors, GGUF, або попередньо квантованих моделей compressed-tensors (GPTQ/AutoRound):

llima-compile [options] <model_path>

Формати вхідних даних для моделі.​

LLiMa приймає три шляхи для введення даних у модель. Оберіть один із них, виходячи з наявності контрольних точок, вимог до точності та того, чи є модель LLM або VLM.

Вхідні даніОпис.Коли використовувати.
Оригінал Hugging Face safetensorsКонтрольна точка FP/BF16, яка LLiMa виконує квантування під час компіляції.Немає точної попередньо квантованої відповідності, або потрібні оригінальні значення параметрів.
Попередньо квантовані Hugging Face safetensors (GPTQ/AutoRound)Контрольна точка, квантовані ваги якої повторно використовуються LLiMa.Рекомендується використовувати, коли колекція містить точну відповідність.
GGUFНаявна квантована контрольна точка LLM.Зручний варіант резервного копіювання LLM; не підтримується для VLM.

Один лише формат вхідних даних не забезпечує сумісність. Архітектура моделі, її розмір, токенізатор і будь-які мультимодальні компоненти також повинні підтримуватися.

Почніть з SiMa.ai попередньо квантована модель​

Рекомендовані вхідні дані.

Перш ніж завантажувати оригінальні ваги Hugging Face або GGUF, перевірте колекцію попередньо квантованих моделей SiMa.ai . Використовуйте точну відповідність для потрібної архітектури, розміру параметрів, варіанту та модальності, якщо така є.

Пункти збору даних залежать від конкретної моделі та попередньо налаштовані.LLiMa compressed-tensors артефакти, які можна безпосередньо передавати до llima-compileВони дозволяють уникнути додаткового етапу компіляції, який передбачає перетворення чисел із рухомою комою на квантовані значення, і містять інформацію про походження квантування, необхідну для розуміння їхньої точності та структури. Вони є вхідними даними для компілятора, а не скомпільованим кодом. Modalix моделі.

Для індивідуального налаштування існуючої підтримуваної моделі відповідний репозиторій може містити специфічні для цієї моделі дані. quantize.py, recipe.yamlі versions.txtПерегляньте інформаційну картку моделі для цього репозиторію та використовуйте документований скрипт, що там наведено; не використовуйте повторно рецепт, який підходить лише для дещо схожої моделі.

hf download simaai/<model-repository> \
    --revision <immutable-revision> \
    --local-dir <prequantized-model-directory>
llima-compile <prequantized-model-directory> -o <output-directory>

Опишіть модель. Агент з LLiMa набір навичок, який це передбачає.​

SiMa.ai LLiMa підтримує компіляцію моделі для агентів одразу після встановлення, за допомогою навичок, що входять до складу середовища розробки Neat (Neat SDK). Ці навички надають агентам, що виконують кодування, контекст для оцінки сумісності LLM та VLM, вибору точного попередньо квантованого вхідного значення, якщо воно доступне, використання встановленого CLI LLiMa та дотримання процесу розгортання та валідації Modalix.

Рекомендований процес для агентів може компілювати модель, розгортати її на доступному Modalix DevKit, перевіряти результати та діагностику, а також вдосконалювати компіляцію. Традиційна компіляція через CLI залишається паралельним шляхом для безпосереднього керування за допомогою тих самих інструментів. Обидва способи створюють стандартні, доступні для перевірки артефакти LLiMa, тому ви можете переглянути вибрану модель, команди, параметри та вихідні дані або переходити між двома процесами в міру зміни вимог. Див. Налаштування Neat SDK, щоб увімкнути компіляцію для агентів.

Запитайте повний процес природною мовою, наприклад:

Compile <model ID or local path> with LLiMa, deploy it to my Modalix at
<user@host>, and smoke-test it. Prefer an exact SiMa.ai pre-quantized
checkpoint when available.

Агент фіксує інформацію про модель і джерело рецепту, дотримується правил командного рядка (CLI) встановленої версії та повідомляє про будь-які непідтримувані межі моделі або недоступність апаратного забезпечення для перевірки, замість того щоб непомітно замінювати іншу модель або формат.

Результат компіляції.​

За замовчуванням, повний процес обробки даних створює таку структуру каталогів:

output_directory/
└── sima_files/                # Compiled model files
    ├── devkit/                # Runtime configuration and model data
    │   ├── tokenizer.json
    │   ├── vlm_config.json
    │   └── ...
    ├── mpk/                   # MPK archives with compiled binaries
    │   ├── layer_0.tar.gz
    │   └── ...
    ├── npy_files/             # LoRA adapter weights (only when compiled with LoRA)
    │   ├── <adapter_name>/
    │   │   └── *.npy
    │   └── ...
    └── ...

Аргументи командного рядка​

Інструмент llima-compile приймає різні аргументи для налаштування процесу компіляції. Наступні таблиці містять опис доступних параметрів:

АргументОпис.
model_pathШлях до вхідної моделі (каталог HuggingFace, файл GGUF або каталог із попередньо квантованими стиснутими тензорами).
-o, --outputДиректорія для збереження скомпільованих файлів. За замовчуванням використовується назва моделі.
-c, --configuration_fileСкрипт Python, який використовується для налаштування точності для кожного шару (наприклад, для використання змішаної точності).
--max_num_tokensМаксимальна довжина контексту. Має бути кратна 1024. Значення за замовчуванням: 4096.
--resumeПродовжуйте перервані процеси збирання, пропускаючи наявні файли.
-j, --jobsКількість паралельних процесів компіляції. За замовчуванням: кількість фізичних ядер процесора.
--log_levelРівень реєстрації (DEBUG, INFO, WARNING, ERROR). За замовчуванням: WARNING.
--input_heightВисота вхідного зображення в пікселях. Має бути вказана разом із --input_width. Обов’язково для моделей Qwen 2 VL, Qwen 3 VL, Qwen3.5 та Gemma 4; необов’язково для зміни встановленого розміру моделі SigLIP2.
--input_widthШирина вхідного зображення в пікселях. Має бути вказана разом із --input_height. Обов’язково для моделей Qwen 2 VL, Qwen 3 VL, Qwen3.5 та Gemma 4; необов’язково для зміни встановленого розміру моделі SigLIP2.
--system_promptСистемне повідомлення, яке потрібно зберегти для використання в режимі командного рядка та для попереднього завантаження моделі.
--system_prompt_fileШлях до текстового файлу, що містить системне повідомлення.
--chat_templateРядок шаблону чату, який зберігатиметься в скомпільованій моделі. Не сумісний з --chat_template_file.
--chat_template_fileШлях до файлу, що містить шаблон чату. Не сумісний з --chat_template.
примітка

Більшість моделей підтримують довжину контексту до 8192 токенів. Використовуйте --max_num_tokens 8192, щоб увімкнути контекст довжиною 8K.

Розширений аргумент.Опис.
--language_group_sizeРозмір пакета для паралельної обробки токенів під час попереднього заповнення. Більші значення (наприклад, 256) можуть покращити час до отримання першого токена (TTFT) для великих вхідних запитів, але можуть погіршити його для менших вхідних запитів. Значення за замовчуванням: 128.
--future_token_mask_sizeРозмір маски для повторного використання скомпільованих моделей для різних позицій токенів. Більші значення зменшують кількість скомпільованих бінарних файлів, але можуть зменшити кількість токенів за секунду (TPS). Значення за замовчуванням: 128.
--no-quantize_embeddingsВимкніть квантування таблиці вбудовувань, яке за замовчуванням увімкнено для підтримуваних LLM та VLM.
--no-quantize_kv_cacheВимкніть квантування кешу KV, яке за замовчуванням увімкнено.
--return_logitsПовертайте значення логітів на виході останнього шару (необхідно для оцінювача моделі).
--draft_model_pathШлях до сумісної чернеткової моделі EAGLE3, Gemma4 MTP або DFlash. Метод визначається автоматично.
--speculative_block_sizeШирина перевірки DFlash: 4, 8 або 16. За замовчуванням: 8.
--lora_nameНазва для адаптера LoRA, який компілюється разом із базовою моделлю.
--lora_pathШлях до каталогу адаптера LoRA, який використовуватиметься для компіляції разом із базовою моделлю.
--compile_lora, --no-compile_loraУвімкніть або вимкніть компіляцію ваг адаптера, коли вказано шляхи до LoRA. За замовчуванням увімкнено.

Для DFlash розмір групи попереднього заповнення має перевищувати розмір блока, а довжина контексту має бути кратною розміру групи:

llima-compile <target-model-path> --draft_model_path <dflash-draft-path> \
    --speculative_block_size 16

Системні підказки.​

Використовуйте --system_prompt або --system_prompt_file для збереження системного запиту в скомпільованій конфігурації моделі. Ці параметри є взаємовиключними.

sima-user@docker-image-id:/home/docker$ llima-compile Llama-3.2-3B-Instruct \
    --system_prompt "You are a concise technical assistant." \
    -o Llama-3.2-3B-Instruct_out

У режимі командного рядка (CLI) це стає стандартним системним запитом. Його можна замінити на set system <prompt> або видалити за допомогою clear system під час сеансу.

У веб-режимі/GenAIServer, збережений запит використовується під час підготовки моделі та може бути збережений у кеші для першого запиту. Він не додається автоматично до API-запитів. Клієнт повинен включити системний запит у масив messages першого запиту та кожного наступного запиту.

Файл конфігурації​

Файл конфігурації дозволяє налаштувати процес компіляції для кожного модуля компілятора, забезпечуючи можливість використання змішаної точності та вибіркової компіляції.

LLM процес обчислень складається з двох окремих етапів, і компілятор генерує оптимізовані моделі для кожного з них:

  • Попереднє заповнення (групові моделі): обробляє вхідний запит партіями, використовуючи language_group_size (наприклад, 128 токенів за один раз). На цьому етапі визначається час отримання першого токена (TTFT), і він оптимізовано для забезпечення високої продуктивності.
  • Декодування (моделі, що працюють з окремими токенами): генерує токени вихідного тексту по черзі, використовуючи авторегресивний підхід. На цьому етапі визначається показник TPS (кількість токенів, що генеруються за секунду), і він оптимізовано для забезпечення мінімальної затримки під час генерації.

Оскільки ці фази мають різні характеристики продуктивності, ви можете застосувати різні стратегії квантування до кожної з них, використовуючи прапорець is_group у функції конфігурації.

Вхідні параметри

Функція get_layer_configuration викликається для кожного модуля компілятора та отримує:

  • model_properties: словник із такими полями:

    • "num_hidden_layers": кількість мовних шарів
    • "is_draft_model": True під час налаштування чернеткової моделі для спекулятивного декодування

  • layer: Словник, що містить:

    • "part": Логічний компонент, наприклад, "PRE", "CACHE", "POST". "VISION", "DRAFT_FC" або "PER_LAYER". Моделі Mixture-of-Experts додають "ROUTER", "EXPERT" та "WEIGHTEDSUM".
    • "is_group": значення True використовується для варіанта, що містить кілька токенів/групу токенів, і False в інших випадках.
    • "index": Індекс даного модуля компілятора. Для "PRE" та "POST" це зазвичай відповідає шару трансформатора. Для "CACHE" він визначає кеш або варіант, що враховує позицію токена, а не шар трансформатора.
    • "expert_idx": індекс експерта в межах шару для записів "EXPERT". Для всіх інших частин, зокрема для всіх щільних моделей, значення становить -1.

    Читайте потрібні значення за ключем. У майбутніх випусках можуть додаватися нові ключі, тому не розпаковуйте цей словник у фіксований список аргументів і не перевіряйте точну відповідність набору ключів.

Повернені значення

Функція повертає словник, що містить:

  • "precision": Рівень квантування (необов’язково, за замовчуванням: "BF16").

    • "BF16": Максимальна точність – найкраща якість, найбільший розмір, найповільніша швидкість.
    • "A_BF16_W_INT8": Квантування середнього рівня – хороша якість, помірний розмір.
    • "A_BF16_W_INT4": Високе квантування – прийнятна якість, найменший розмір, найвища швидкість.

  • "compile": Встановіть значення False, щоб пропустити компіляцію цього шару (необов’язково, за замовчуванням: True).

  • "lora": режим LoRA для цього шару (необов’язково, за замовчуванням: "LORA_DISABLED").

    • "LORA_DISABLED": Для цього шару не передбачено підтримки LoRA. Це значення за замовчуванням, яке використовується, коли не надано файл конфігурації, в результаті чого створюється стандартна модель без додаткових накладних витрат, пов’язаних з адаптером.
    • "LORA_BRANCH": Компілює паралельні гілки LoRA з нульовими вагами разом із базовою моделлю. Ваги адаптера завантажуються з файлів .npy під час роботи, що дає змогу динамічно перемикатися між адаптерами без перезапуску моделі. Використовуйте цей режим, коли потрібно швидко змінювати адаптери.
    • "LORA_MERGED": Ваги LoRA об’єднуються з вагами базової моделі під час роботи. Адаптер стає постійно активним протягом сесії, і його неможливо вимкнути або видалити. Використовуйте цей режим, коли вам завжди потрібно, щоб адаптер був застосований, і вам не потрібне динамічне перемикання.
примітка

Рекомендована практика: використовуйте INT8 (A_BF16_W_INT8) для групових шарів, щоб підтримувати якість під час попереднього заповнення, INT4 (A_BF16_W_INT4) для шарів, що обробляють окремі токени, для швидкої генерації, і BF16 для візуальних кодувальників, щоб зберегти якість розпізнавання зображень. Для більшості моделей ця конфігурація забезпечує оптимальний баланс між точністю моделі, продуктивністю та використанням пам’яті.

Приклади​

Приклад 1: Компіляція простої LLM

Скомпілюйте Llama модель, завантажену з Hugging Face, використовуючи налаштування за замовчуванням:

sima-user@docker-image-id:/home/docker$ hf download meta-llama/Llama-3.2-3B --local-dir Llama-3.2-3B-Instruct
sima-user@docker-image-id:/home/docker$ llima-compile Llama-3.2-3B-Instruct -o Llama-3.2-3B-Instruct_out

Це дозволить:

  • Використовуйте стандартну точність BF16 для всіх шарів.
  • Встановіть довжину контексту на 4096 токенів.
  • Вивести результат у каталог Llama-3.2-3B-Instruct_out.

Приклад 2: Компіляція з використанням заданої довжини контексту

sima-user@docker-image-id:/home/docker$ hf download meta-llama/Llama-3.2-3B --local-dir Llama-3.2-3B-Instruct
sima-user@docker-image-id:/home/docker$ llima-compile --max_num_tokens 4096 Llama-3.2-3B-Instruct -o Llama-3.2-3B-Instruct_out

Це дозволить:

  • Використовуйте стандартну точність BF16 для всіх шарів.
  • Встановіть довжину контексту на 4096 токенів.
  • Вивести результат у каталог Llama-3.2-3B-Instruct_out.

Приклад 3: Компіляція Gemma 3 VLM із використанням змішаної точності

Для складних моделей, таких як Gemma 3 VLM, можливо, знадобиться вказати різні рівні точності для різних шарів (наприклад, зберегти візуальний кодувальник у форматі BF16).

  1. Завантажте модель:

    sima-user@docker-image-id:/home/docker$ hf download simaai/gemma3-siglip448 --local-dir gemma-3-model

  2. Створіть файл конфігурації (наприклад, config.py):

    def get_layer_configuration(model_properties, layer):
        # Keep vision encoder in full precision
        if layer["part"] == "VISION":
            precision = "BF16"
        # Use INT8 for batch processing layers (better quality)
        elif layer["is_group"]:
            precision = "A_BF16_W_INT8"
        # Use INT4 for single-token layers (smaller size)
        else:
            precision = "A_BF16_W_INT4"
        return {"precision": precision}

  3. Запустіть компілятор:

    sima-user@docker-image-id:/home/docker$ llima-compile -c config.py --max_num_tokens 2048 gemma-3-model -o gemma-3-model_out

Приклад 4: Розширена конфігурація

Змішана точність із налаштуваннями, специфічними для кожного шару трансформера:

def get_layer_configuration(model_properties, layer):
    # PRE and POST indices normally identify transformer layers.
    if layer["part"] in {"PRE", "POST"} and layer["index"] < 4:
        return {"precision": "BF16"}

    # Keep every required compiler unit and use INT8 elsewhere.
    return {"precision": "A_BF16_W_INT8"}

Не слід інтерпретувати індекси "CACHE" як індекси шарів трансформера. Виключення варіантів кешу може призвести до того, що скомпільований результат буде неповним і непридатним для використання під час виконання.

Приклад 5: Компіляція LLM з використанням LoRA

LoRA (адаптація з низьким рангом) дозволяє точно налаштувати базову модель, а адаптер динамічно застосовувати або видаляти під час виконання, не перекомпілюючи базову модель. Базова модель компілюється з паралельними гілками LoRA (ініціалізованими нулями), а ваги адаптера компілюються окремо у файли .npy, які завантажуються за потреби.

примітка

Гілки LoRA завжди компілюються у форматі INT8, навіть якщо вказано INT4, для забезпечення кращої точності.

  1. Завантажте базову модель і адаптер LoRA:

    sima-user@docker-image-id:/home/docker$ hf download meta-llama/Llama-3.2-3B-Instruct --local-dir Llama-3.2-3B-Instruct
    sima-user@docker-image-id:/home/docker$ hf download <org>/<lora-adapter> --local-dir my-lora

  2. Створіть файл конфігурації (наприклад, lora_config.py):

    Ключ lora визначає режим LoRA для кожного шару. Використовуйте "LORA_BRANCH", щоб увімкнути динамічне перемикання під час роботи в середовищі виконання.

    def get_layer_configuration(model_properties, layer):
        if layer["is_group"]:
            return {"precision": "A_BF16_W_INT8", "compile": True, "lora": "LORA_BRANCH"}
        else:
            return {"precision": "A_BF16_W_INT4", "compile": True, "lora": "LORA_BRANCH"}

  3. Зберіть базову модель з використанням адаптера LoRA:

    sima-user@docker-image-id:/home/docker$ llima-compile Llama-3.2-3B-Instruct \
        --lora_name my_adapter \
        --lora_path my-lora \
        -c lora_config.py \
        -o Llama-3.2-3B-lora-out

    Це дозволяє об’єднати базову модель з однією гілкою LoRA і автоматично інтегрувати ваги адаптера в Llama-3.2-3B-lora-out/sima_files/npy_files/my_adapter/.

Кілька адаптерів можна об’єднати за один крок, повторюючи --lora_name і --lora_path:

``` console
sima-user@docker-image-id:/home/docker$ llima-compile Llama-3.2-3B-Instruct \
    --lora_name my_adapter_A --lora_path my-lora_A \
    --lora_name my_adapter_B --lora_path my-lora_B \
    -c lora_config.py \
    -o Llama-3.2-3B-lora-out
```

4. Щоб додати більше адаптерів, не перекомпілюючи базову модель, використовуйте llima-compile-lora для кожного додаткового адаптера:

``` console
sima-user@docker-image-id:/home/docker$ llima-compile-lora Llama-3.2-3B-Instruct ./lora-c \
    -w Llama-3.2-3B-lora-out/sima_files/mpk \
    -o Llama-3.2-3B-lora-out/sima_files/npy_files/adapter_c
```

**аргументи для llima-compile-lora**

| Аргумент | Опис. |
|----|----|
| `base_path` | Шлях до початкової директорії базової моделі (у форматі HuggingFace). |
| `lora_path` | Шлях до каталогу адаптера LoRA, який потрібно використати для компіляції. |
| `-w, --weight_map_path` | **Обов’язково.** Шлях до папки `mpk/` від базової директорії, де зберігається компіляція моделі. Містить карти вагових коефіцієнтів, необхідні для компіляції адаптера. |
| `-o, --output` | Директорія для збереження скомпільованих файлів адаптера `.npy`. За замовчуванням використовується назва директорії адаптера. |