# Секция 3: Microsoft Olive Optimization Suite

## Съдържание
1. [Въведение](../../../Module04)
2. [Какво е Microsoft Olive?](../../../Module04)
3. [Инсталация](../../../Module04)
4. [Ръководство за бърз старт](../../../Module04)
5. [Пример: Конвертиране на Qwen3 към ONNX INT4](../../../Module04)
6. [Разширено използване](../../../Module04)
7. [Репозитори с рецепти на Olive](../../../Module04)
8. [Най-добри практики](../../../Module04)
9. [Отстраняване на проблеми](../../../Module04)
10. [Допълнителни ресурси](../../../Module04)

## Въведение

Microsoft Olive е мощен и лесен за използване инструмент за оптимизация на модели, съобразен с хардуера, който опростява процеса на оптимизиране на машинно обучени модели за внедряване на различни хардуерни платформи. Независимо дали целите са CPU, GPU или специализирани AI ускорители, Olive ви помага да постигнете оптимална производителност, като същевременно запазвате точността на модела.

## Какво е Microsoft Olive?

Olive е лесен за използване инструмент за оптимизация на модели, съобразен с хардуера, който обединява водещи техники за компресия, оптимизация и компилация на модели. Работи с ONNX Runtime като цялостно решение за оптимизация на инференция.

### Основни характеристики

- **Оптимизация, съобразена с хардуера**: Автоматично избира най-добрите техники за оптимизация за вашия целеви хардуер
- **40+ вградени компоненти за оптимизация**: Включва компресия на модели, квантизация, оптимизация на графи и други
- **Лесен CLI интерфейс**: Прости команди за често срещани задачи за оптимизация
- **Поддръжка на множество рамки**: Работи с PyTorch, модели на Hugging Face и ONNX
- **Поддръжка на популярни модели**: Olive може автоматично да оптимизира популярни архитектури на модели като Llama, Phi, Qwen, Gemma и други

### Ползи

- **Намалено време за разработка**: Няма нужда от ръчно експериментиране с различни техники за оптимизация
- **Подобрена производителност**: Значителни подобрения в скоростта (до 6 пъти в някои случаи)
- **Кросплатформено внедряване**: Оптимизираните модели работят на различни хардуери и операционни системи
- **Запазена точност**: Оптимизациите запазват качеството на модела, като същевременно подобряват производителността

## Инсталация

### Предварителни изисквания

- Python 3.8 или по-нова версия
- Мениджър на пакети pip
- Виртуална среда (препоръчително)

### Основна инсталация

Създайте и активирайте виртуална среда:

```bash
# Create virtual environment
python -m venv olive-env

# Activate virtual environment
# On Windows:
olive-env\Scripts\activate
# On macOS/Linux:
source olive-env/bin/activate
```

Инсталирайте Olive с функции за автоматична оптимизация:

```bash
pip install olive-ai[auto-opt]
pip install transformers onnxruntime-genai
```

### Допълнителни зависимости

Olive предлага различни допълнителни зависимости за допълнителни функции:

```bash
# For Azure ML integration
pip install olive-ai[azureml]

# For DirectML (Windows GPU acceleration)
pip install olive-ai[directml]

# For CPU optimization
pip install olive-ai[cpu]

# For all features
pip install olive-ai[all]
```

### Проверка на инсталацията

```bash
olive --help
```

Ако е успешно, трябва да видите помощното съобщение на Olive CLI.

## Ръководство за бърз старт

### Вашата първа оптимизация

Нека оптимизираме малък езиков модел, използвайки функцията за автоматична оптимизация на Olive:

```bash
olive auto-opt \
  --model_name_or_path HuggingFaceTB/SmolLM2-135M-Instruct \
  --output_path models/smolm2-optimized \
  --device cpu \
  --provider CPUExecutionProvider \
  --use_ort_genai \
  --precision int4 \
  --log_level 1
```

### Какво прави тази команда

Процесът на оптимизация включва: получаване на модела от локалния кеш, заснемане на ONNX графа и съхраняване на теглата в ONNX файл с данни, оптимизиране на ONNX графа и квантизация на модела до int4, използвайки метода RTN.

### Обяснение на параметрите на командата

- `--model_name_or_path`: Идентификатор на модел от Hugging Face или локален път
- `--output_path`: Директория, където ще бъде запазен оптимизираният модел
- `--device`: Целево устройство (cpu, gpu)
- `--provider`: Провайдър за изпълнение (CPUExecutionProvider, CUDAExecutionProvider, DmlExecutionProvider)
- `--use_ort_genai`: Използване на ONNX Runtime Generate AI за инференция
- `--precision`: Прецизност на квантизацията (int4, int8, fp16)
- `--log_level`: Ниво на логване (0=минимално, 1=подробно)

## Пример: Конвертиране на Qwen3 към ONNX INT4

Въз основа на предоставения пример от Hugging Face на [lokinfey/Qwen3-8B-ONNX-INT4-CPU](https://huggingface.co/lokinfey/Qwen3-8B-ONNX-INT4-CPU), ето как да оптимизирате модел Qwen3:

### Стъпка 1: Изтегляне на модела (по избор)

За да минимизирате времето за изтегляне, кеширайте само основните файлове:

```bash
huggingface-cli download Qwen/Qwen2.5-0.5B-Instruct *.json *.safetensors *.txt
```

### Стъпка 2: Оптимизиране на модела Qwen3

```bash
olive auto-opt \
  --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
  --output_path models/qwen3-onnx-int4 \
  --device cpu \
  --provider CPUExecutionProvider \
  --use_ort_genai \
  --precision int4 \
  --log_level 1
```

### Стъпка 3: Тестване на оптимизирания модел

Създайте прост Python скрипт за тестване на вашия оптимизиран модел:

```python
import onnxruntime_genai as og

# Load the optimized model
model = og.Model('models/qwen3-onnx-int4')
tokenizer = og.Tokenizer(model)

# Create a chat template
chat_template = '<|im_start|>user\n{input}<|im_end|>\n<|im_start|>assistant\n'

# Generate text
prompt = "What is machine learning?"
input_tokens = tokenizer.encode(chat_template.format(input=prompt))

params = og.GeneratorParams(model)
params.set_search_options(max_length=200)
params.input_ids = input_tokens

generator = og.Generator(model, params)

print("Generated response:")
while not generator.is_done():
    generator.compute_logits()
    generator.generate_next_token()
    
    new_token = generator.get_next_tokens()[0]
    print(tokenizer.decode([new_token]), end='', flush=True)

print()
```

### Структура на изхода

След оптимизацията, вашата изходна директория ще съдържа:

```
models/qwen3-onnx-int4/
├── model.onnx              # Optimized ONNX model
├── model.onnx.data         # Model weights
├── genai_config.json       # Generation configuration
├── tokenizer.json          # Tokenizer files
├── tokenizer_config.json
└── special_tokens_map.json
```

## Разширено използване

### Конфигурационни файлове

За по-сложни работни потоци за оптимизация можете да използвате JSON конфигурационни файлове:

```json
{
  "input_model": {
    "type": "PyTorchModel",
    "config": {
      "hf_config": {
        "model_name": "Qwen/Qwen2.5-0.5B-Instruct",
        "task": "text-generation"
      }
    }
  },
  "systems": {
    "local_system": {
      "type": "LocalSystem",
      "config": {
        "accelerators": [
          {
            "device": "cpu",
            "execution_providers": ["CPUExecutionProvider"]
          }
        ]
      }
    }
  },
  "evaluators": {
    "common_evaluator": {
      "metrics": [
        {
          "name": "latency",
          "type": "latency",
          "sub_types": [{"name": "avg"}]
        }
      ]
    }
  },
  "passes": {
    "conversion": {
      "type": "ModelBuilder",
      "config": {
        "precision": "int4"
      }
    },
    "optimization": {
      "type": "OrtTransformersOptimization",
      "config": {
        "model_type": "gpt2"
      }
    }
  },
  "engine": {
    "search_strategy": {
      "execution_order": "joint",
      "search_algorithm": "tpe"
    },
    "evaluator": "common_evaluator",
    "host": "local_system",
    "target": "local_system",
    "cache_dir": "cache",
    "output_dir": "models/optimized"
  }
}
```

Стартирайте с конфигурация:

```bash
olive run --config config.json
```

### Оптимизация за GPU

За оптимизация на CUDA GPU:

```bash
olive auto-opt \
  --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
  --output_path models/qwen3-gpu-int4 \
  --device gpu \
  --provider CUDAExecutionProvider \
  --use_ort_genai \
  --precision int4 \
  --log_level 1
```

За DirectML (Windows):

```bash
olive auto-opt \
  --model_name_or_path Qwen/Qwen2.5-0.5B-Instruct \
  --output_path models/qwen3-directml-int4 \
  --device gpu \
  --provider DmlExecutionProvider \
  --use_ort_genai \
  --precision int4 \
  --log_level 1
```

### Фина настройка с Olive

Olive също поддържа фина настройка на модели:

```bash
olive finetune \
  --model_name_or_path meta-llama/Llama-3.2-1B-Instruct \
  --data_name microsoft/dolly-15k \
  --text_template "### Question: {instruction}\n### Answer: {response}" \
  --max_steps 100 \
  --output_path models/llama-finetuned
```

## Най-добри практики

### 1. Избор на модел
- Започнете с по-малки модели за тестване (например 0.5B-7B параметри)
- Уверете се, че целевата архитектура на модела се поддържа от Olive

### 2. Хардуерни съображения
- Съобразете целта на оптимизацията с хардуера за внедряване
- Използвайте GPU оптимизация, ако имате хардуер, съвместим с CUDA
- Обмислете DirectML за Windows машини с интегрирана графика

### 3. Избор на прецизност
- **INT4**: Максимална компресия, леко намаление на точността
- **INT8**: Добър баланс между размер и точност
- **FP16**: Минимална загуба на точност, умерено намаление на размера

### 4. Тестване и валидиране
- Винаги тествайте оптимизираните модели с вашите специфични случаи на употреба
- Сравнете метриките за производителност (латентност, пропускателна способност, точност)
- Използвайте представителни входни данни за оценка

### 5. Итеративна оптимизация
- Започнете с автоматична оптимизация за бързи резултати
- Използвайте конфигурационни файлове за по-прецизен контрол
- Експериментирайте с различни оптимизационни проходи

## Отстраняване на проблеми

### Често срещани проблеми

#### 1. Проблеми с инсталацията
```bash
# If you encounter dependency conflicts:
pip install --upgrade pip
pip install olive-ai[auto-opt] --force-reinstall
```

#### 2. Проблеми с CUDA/GPU
```bash
# Verify CUDA installation:
nvidia-smi

# Install correct ONNX Runtime GPU package:
pip install onnxruntime-gpu
```

#### 3. Проблеми с паметта
- Използвайте по-малки размери на партидите по време на оптимизация
- Опитайте квантизация с по-висока прецизност първо (int8 вместо int4)
- Уверете се, че има достатъчно дисково пространство за кеширане на модела

#### 4. Грешки при зареждане на модела
- Проверете пътя на модела и разрешенията за достъп
- Проверете дали моделът изисква `trust_remote_code=True`
- Уверете се, че всички необходими файлове на модела са изтеглени

### Получаване на помощ

- **Документация**: [microsoft.github.io/Olive](https://microsoft.github.io/Olive/)
- **GitHub Issues**: [github.com/microsoft/Olive/issues](https://github.com/microsoft/Olive/issues)
- **Примери**: [microsoft.github.io/Olive/examples.html](https://microsoft.github.io/Olive/examples.html)

## Репозитори с рецепти на Olive

### Въведение в рецептите на Olive

Репозитори [microsoft/olive-recipes](https://github.com/microsoft/olive-recipes) допълва основния инструмент Olive, като предоставя обширна колекция от готови за използване рецепти за оптимизация на популярни AI модели. Този репозитори служи като практическа справка както за оптимизиране на публично достъпни модели, така и за създаване на работни потоци за оптимизация на собствени модели.

### Основни характеристики

- **100+ предварително изградени рецепти**: Готови за използване конфигурации за оптимизация на популярни модели
- **Поддръжка на множество архитектури**: Включва трансформерни модели, модели за визия и мултимодални архитектури
- **Оптимизации, съобразени с хардуера**: Рецепти, съобразени с CPU, GPU и специализирани ускорители
- **Популярни семейства модели**: Включва Phi, Llama, Qwen, Gemma, Mistral и много други

### Поддържани семейства модели

Репозитори включва рецепти за оптимизация за:

#### Езикови модели
- **Microsoft Phi**: Phi-3-mini, Phi-3.5-mini, Phi-4-mini, Phi-4-reasoning
- **Meta Llama**: Llama-2-7b, Llama-3.1-8B, Llama-3.2-1B/3B
- **Alibaba Qwen**: Qwen1.5-7B, Qwen2-7B, Qwen2.5 серия (0.5B до 14B)
- **Google Gemma**: Различни конфигурации на Gemma модели
- **Mistral AI**: Серия Mistral-7B
- **DeepSeek**: Модели от серията R1-Distill

#### Модели за визия и мултимодални модели
- **Stable Diffusion**: v1.4, XL-base-1.0
- **CLIP модели**: Различни конфигурации CLIP-ViT
- **ResNet**: Оптимизации за ResNet-50
- **Vision Transformers**: ViT-base-patch16-224

#### Специализирани модели
- **Whisper**: OpenAI Whisper-large-v3
- **BERT**: Основни и многоезични варианти
- **Sentence Transformers**: all-MiniLM-L6-v2

### Използване на рецепти на Olive

#### Метод 1: Клониране на конкретна рецепта

```bash
# Clone the recipes repository
git clone https://github.com/microsoft/olive-recipes.git
cd olive-recipes

# Navigate to a specific model recipe
cd microsoft-Phi-4-mini-instruct

# Run the optimization
olive run --config olive_config.json
```

#### Метод 2: Използване на рецепта като шаблон

```bash
# Copy a recipe configuration for your model
cp olive-recipes/microsoft-Phi-3-mini-4k-instruct/olive_config.json ./my_config.json

# Modify the configuration for your needs
# Update model paths, optimization parameters, etc.

# Run with your custom configuration
olive run --config my_config.json
```

### Структура на рецептата

Всяка директория с рецепта обикновено съдържа:

```
model-name/
├── olive_config.json       # Main optimization configuration
├── requirements.txt        # Python dependencies
├── README.md              # Model-specific instructions
├── user_script.py         # Custom preprocessing/evaluation scripts
└── sample_data/           # Sample input data for testing
```

### Пример: Използване на рецепта Phi-4-mini

Нека използваме рецептата Phi-4-mini като пример:

```bash
# Clone the repository
git clone https://github.com/microsoft/olive-recipes.git
cd olive-recipes/microsoft-Phi-4-mini-instruct

# Install dependencies
pip install -r requirements.txt

# Run the optimization
olive run --config olive_config.json
```

Конфигурационният файл обикновено включва:

```json
{
  "input_model": {
    "type": "PyTorchModel",
    "config": {
      "hf_config": {
        "model_name": "microsoft/Phi-4-mini-instruct",
        "task": "text-generation",
        "trust_remote_code": true
      }
    }
  },
  "systems": {
    "local_system": {
      "type": "LocalSystem",
      "config": {
        "accelerators": [
          {
            "device": "cpu",
            "execution_providers": ["CPUExecutionProvider"]
          }
        ]
      }
    }
  },
  "passes": {
    "convert": {
      "type": "ModelBuilder",
      "config": {
        "precision": "int4"
      }
    }
  }
}
```

### Персонализиране на рецепти

#### Промяна на целевия хардуер

За да промените целевия хардуер, актуализирайте секцията `systems`:

```json
{
  "systems": {
    "gpu_system": {
      "type": "LocalSystem",
      "config": {
        "accelerators": [
          {
            "device": "gpu",
            "execution_providers": ["CUDAExecutionProvider"]
          }
        ]
      }
    }
  }
}
```

#### Настройка на параметрите за оптимизация

Модифицирайте секцията `passes` за различни нива на оптимизация:

```json
{
  "passes": {
    "convert": {
      "type": "ModelBuilder",
      "config": {
        "precision": "int8",           // Change from int4 to int8
        "use_ort_genai": true,
        "use_dynamo_exporter": true
      }
    },
    "optimize": {
      "type": "OrtTransformersOptimization",
      "config": {
        "optimization_level": "all"
      }
    }
  }
}
```

### Създаване на собствена рецепта

1. **Започнете с подобен модел**: Намерете рецепта за модел с подобна архитектура
2. **Актуализирайте конфигурацията на модела**: Променете името/пътя на модела в конфигурацията
3. **Настройте параметрите**: Модифицирайте параметрите за оптимизация според нуждите
4. **Тествайте и валидирайте**: Стартирайте оптимизацията и валидирайте резултатите
5. **Допринасяйте обратно**: Помислете за допринасяне на вашата рецепта към репозитори

### Ползи от използването на рецепти

#### 1. **Доказани конфигурации**
- Тествани настройки за оптимизация за конкретни модели
- Избягване на проби и грешки при намиране на оптимални параметри

#### 2. **Настройка, съобразена с хардуера**
- Предварително оптимизирани за различни провайдъри за изпълнение
- Готови за използване конфигурации за CPU, GPU и NPU цели

#### 3. **Обширно покритие**
- Поддържа най-популярните модели с отворен код
- Редовни актуализации с нови версии на модели

#### 4. **Приноси от общността**
- Съвместно развитие с AI общността
- Споделени знания и най-добри практики

### Принос към рецепти на Olive

Ако сте оптимизирали модел, който не е обхванат в репозитори:

1. **Клонирайте репозитори**: Създайте собствено копие на olive-recipes
2. **Създайте директория за рецепта**: Добавете нова директория за вашия модел
3. **Включете конфигурация**: Добавете olive_config.json и съпътстващи файлове
4. **Документирайте употребата**: Осигурете ясно README с инструкции
5. **Изпратете Pull Request**: Допринасяйте обратно към общността

### Бенчмаркове за производителност

Много рецепти включват бенчмаркове за производителност, показващи:
- **Подобрения в латентността**: Типично 2-6x ускорение спрямо базовото ниво
- **Намаление на паметта**: 50-75% намаление на използването на паметта с квантизация
- **Запазване на точността**: 95-99% запазване на точността

### Интеграция с AI Toolkit

Рецептите работят безпроблемно с:
- **VS Code AI Toolkit**: Директна интеграция за оптимизация на модели
- **Azure Machine Learning**: Облачни работни потоци за оптимизация
- **ONNX Runtime**: Оптимизирано внедряване на инференция

## Допълнителни ресурси

### Официални връзки
- **GitHub репозитори**: [github.com/microsoft/Olive](https://github.com/microsoft/Olive)
- **Репозитори с рецепти на Olive**: [github.com/microsoft/olive-recipes](https://github.com/microsoft/olive-recipes)
- **Документация за ONNX Runtime**: [onnxruntime.ai/docs/performance/olive.html](https://onnxruntime.ai/docs/performance/olive.html)
- **Пример от Hugging Face**: [huggingface.co/lokinfey/Qwen3-8B-ONNX-INT4-CPU](https://huggingface.co/lokinfey/Qwen3-8B-ONNX-INT4-CPU)

### Примери от общността
- **Jupyter Notebooks**: Налични в репозитори на Olive — https://github.com/microsoft/Olive/tree/main/examples
- **Разширение за VS Code**: Преглед на AI Toolkit за VS Code — https://learn.microsoft.com/azure/ai-toolkit/overview
- **Блог публикации**: Microsoft Open Source Blog — https://opensource.microsoft.com/blog/

### Свързани инструменти
- **ONNX Runtime**: Високопроизводителен инференционен двигател — https://onnxruntime.ai/
- **Hugging Face Transformers**: Източник на много съвместими модели — https://huggingface.co/docs/transformers/index
- **Azure Machine Learning**: Облачни работни потоци за оптимизация — https://learn.microsoft.com/azure/machine-learning/

## ➡️ Какво следва

- [04: OpenVINO Toolkit Optimization Suite](./04.openvino.md)

---

**Отказ от отговорност**:  
Този документ е преведен с помощта на AI услуга за превод [Co-op Translator](https://github.com/Azure/co-op-translator). Въпреки че се стремим към точност, моля, имайте предвид, че автоматизираните преводи може да съдържат грешки или неточности. Оригиналният документ на неговия роден език трябва да се счита за авторитетен източник. За критична информация се препоръчва професионален човешки превод. Ние не носим отговорност за каквито и да е недоразумения или погрешни интерпретации, произтичащи от използването на този превод.