# Секция 2: Ръководство за имплементация на Llama.cpp

## Съдържание
1. [Въведение](../../../Module04)
2. [Какво е Llama.cpp?](../../../Module04)
3. [Инсталация](../../../Module04)
4. [Сглобяване от изходен код](../../../Module04)
5. [Квантизация на модела](../../../Module04)
6. [Основна употреба](../../../Module04)
7. [Разширени функции](../../../Module04)
8. [Интеграция с Python](../../../Module04)
9. [Отстраняване на проблеми](../../../Module04)
10. [Най-добри практики](../../../Module04)

## Въведение

Това подробно ръководство ще ви запознае с всичко, което трябва да знаете за Llama.cpp – от основната инсталация до сложни сценарии за употреба. Llama.cpp е мощна имплементация на C++, която позволява ефективно използване на големи езикови модели (LLMs) с минимална настройка и отлична производителност на различни хардуерни конфигурации.

## Какво е Llama.cpp?

Llama.cpp е рамка за използване на LLM, написана на C/C++, която позволява локално изпълнение на големи езикови модели с минимална настройка и водеща производителност на широк спектър от хардуер. Основните характеристики включват:

### Основни функции
- **Чиста имплементация на C/C++** без зависимости
- **Съвместимост между платформи** (Windows, macOS, Linux)
- **Оптимизация за хардуер** за различни архитектури
- **Поддръжка на квантизация** (от 1.5-битова до 8-битова целочислена квантизация)
- **Ускорение чрез CPU и GPU**
- **Ефективност на паметта** за ограничени среди

### Предимства
- Работи ефективно на CPU без необходимост от специализиран хардуер
- Поддържа множество GPU бекенди (CUDA, Metal, OpenCL, Vulkan)
- Лек и преносим
- Apple Silicon е приоритет – оптимизиран чрез ARM NEON, Accelerate и Metal рамки
- Поддържа различни нива на квантизация за намалена употреба на паметта

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

### Метод 1: Предварително компилирани бинарни файлове (Препоръчително за начинаещи)

#### Изтегляне от GitHub Releases
1. Посетете [Llama.cpp GitHub Releases](https://github.com/ggml-org/llama.cpp/releases)
2. Изтеглете подходящия бинарен файл за вашата система:
   - `llama-<version>-bin-win-<feature>-<arch>.zip` за Windows
   - `llama-<version>-bin-macos-<feature>-<arch>.zip` за macOS
   - `llama-<version>-bin-linux-<feature>-<arch>.zip` за Linux

3. Извлечете архива и добавете директорията към PATH на вашата система

#### Използване на мениджъри на пакети

**macOS (Homebrew):**
```bash
brew install llama.cpp
```

**Linux (Различни дистрибуции):**
```bash
# Ubuntu/Debian
sudo apt install llama.cpp

# Arch Linux
sudo pacman -S llama.cpp
```

### Метод 2: Python пакет (llama-cpp-python)

#### Основна инсталация
```bash
pip install llama-cpp-python
```

#### С хардуерно ускорение
```bash
# For CUDA (NVIDIA GPUs)
CMAKE_ARGS="-DGGML_CUDA=on" pip install llama-cpp-python

# For Metal (Apple Silicon)
CMAKE_ARGS="-DGGML_METAL=on" pip install llama-cpp-python

# For OpenBLAS (CPU optimization)
CMAKE_ARGS="-DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS" pip install llama-cpp-python
```

## Сглобяване от изходен код

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

**Системни изисквания:**
- Компилатор за C++ (GCC, Clang или MSVC)
- CMake (версия 3.14 или по-нова)
- Git
- Инструменти за компилация за вашата платформа

**Инсталиране на предварителни изисквания:**

**macOS:**
```bash
xcode-select --install
```

**Ubuntu/Debian:**
```bash
sudo apt update
sudo apt install build-essential cmake git
```

**Windows:**
- Инсталирайте Visual Studio 2022 с инструменти за разработка на C++
- Инсталирайте CMake от официалния уебсайт
- Инсталирайте Git

### Основен процес на компилация

1. **Клонирайте хранилището:**
```bash
git clone https://github.com/ggml-org/llama.cpp
cd llama.cpp
```

2. **Конфигурирайте компилацията:**
```bash
cmake -B build
```

3. **Компилирайте проекта:**
```bash
cmake --build build --config Release
```

За по-бърза компилация използвайте паралелни задачи:
```bash
cmake --build build --config Release -j 8
```

### Компилации, специфични за хардуера

#### Поддръжка на CUDA (NVIDIA GPU)
```bash
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release
```

#### Поддръжка на Metal (Apple Silicon)
```bash
cmake -B build -DGGML_METAL=ON
cmake --build build --config Release
```

#### Поддръжка на OpenBLAS (Оптимизация за CPU)
```bash
cmake -B build -DGGML_BLAS=ON -DGGML_BLAS_VENDOR=OpenBLAS
cmake --build build --config Release
```

#### Поддръжка на Vulkan
```bash
cmake -B build -DGGML_VULKAN=1
cmake --build build --config Release
```

### Разширени опции за компилация

#### Компилация за дебъг
```bash
cmake -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build
```

#### С допълнителни функции
```bash
cmake -B build \
    -DGGML_CUDA=ON \
    -DGGML_BLAS=ON \
    -DGGML_BLAS_VENDOR=OpenBLAS \
    -DBUILD_SHARED_LIBS=ON
```

## Квантизация на модела

### Разбиране на GGUF формат

GGUF (Generalized GGML Unified Format) е оптимизиран файлов формат, предназначен за ефективно изпълнение на големи езикови модели с помощта на Llama.cpp и други рамки. Той предлага:

- Стандартизирано съхранение на теглата на модела
- Подобрена съвместимост между платформи
- Усъвършенствана производителност
- Ефективно управление на метаданни

### Типове квантизация

Llama.cpp поддържа различни нива на квантизация:

| Тип | Битове | Описание | Приложение |
|-----|--------|----------|------------|
| F16 | 16 | Половин прецизност | Високо качество, голяма памет |
| Q8_0 | 8 | 8-битова квантизация | Добър баланс |
| Q4_0 | 4 | 4-битова квантизация | Умерено качество, по-малък размер |
| Q2_K | 2 | 2-битова квантизация | Най-малък размер, по-ниско качество |

### Конвертиране на модели

#### От PyTorch към GGUF
```bash
# Convert Hugging Face model
python convert_hf_to_gguf.py path/to/model --outdir ./models

# Quantize the model
./llama-quantize ./models/model.gguf ./models/model-q4_0.gguf q4_0
```

#### Директно изтегляне от Hugging Face
Много модели са налични в GGUF формат на Hugging Face:
- Търсете модели с "GGUF" в името
- Изтеглете подходящото ниво на квантизация
- Използвайте директно с llama.cpp

## Основна употреба

### Интерфейс на командния ред

#### Проста генерация на текст
```bash
# Basic text completion
./llama-cli -m model.gguf -p "Hello, my name is" -n 50

# Interactive chat mode
./llama-cli -m model.gguf -cnv
```

#### Използване на модели от Hugging Face
```bash
# Download and run directly
./llama-cli -hf microsoft/DialoGPT-medium
```

#### Режим на сървър
```bash
# Start server
./llama-server -m model.gguf --host 0.0.0.0 --port 8080

# With GPU acceleration
./llama-server -m model.gguf --n-gpu-layers 32
```

### Често използвани параметри

| Параметър | Описание | Пример |
|-----------|----------|--------|
| `-m` | Път до файла на модела | `-m model.gguf` |
| `-p` | Текст на подканата | `-p "Hello world"` |
| `-n` | Брой токени за генериране | `-n 100` |
| `-c` | Размер на контекста | `-c 4096` |
| `-t` | Брой нишки | `-t 8` |
| `-ngl` | GPU слоеве | `-ngl 32` |
| `-temp` | Температура | `-temp 0.7` |

### Интерактивен режим

```bash
# Start interactive session
./llama-cli -m model.gguf -cnv

# Example conversation:
# > Hello, how are you?
# Hi there! I'm doing well, thank you for asking...
# > What can you help me with?
# I can assist with various tasks such as...
```

## Разширени функции

### API на сървъра

#### Стартиране на сървъра
```bash
./llama-server -m model.gguf \
    --host 0.0.0.0 \
    --port 8080 \
    --ctx-size 4096 \
    --n-gpu-layers 32
```

#### Употреба на API
```bash
# Chat completion
curl -X POST http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Hello!"}
    ],
    "temperature": 0.7,
    "max_tokens": 100
  }'

# Text completion
curl -X POST http://localhost:8080/completion \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "The capital of France is",
    "n_predict": 50
  }'
```

### Оптимизация на производителността

#### Управление на паметта
```bash
# Set context size
./llama-cli -m model.gguf -c 2048

# Enable memory mapping
./llama-cli -m model.gguf --mlock
```

#### Многопоточност
```bash
# Use all CPU cores
./llama-cli -m model.gguf -t $(nproc)

# Specific thread count
./llama-cli -m model.gguf -t 8
```

#### Ускорение чрез GPU
```bash
# Offload layers to GPU
./llama-cli -m model.gguf -ngl 32

# Use specific GPU
CUDA_VISIBLE_DEVICES=0 ./llama-cli -m model.gguf -ngl 32
```

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

### Основна употреба с llama-cpp-python

```python
from llama_cpp import Llama

# Initialize model
llm = Llama(
    model_path="./models/model.gguf",
    n_ctx=2048,
    n_threads=8,
    n_gpu_layers=32
)

# Generate text
output = llm("Hello, my name is", max_tokens=50)
print(output['choices'][0]['text'])
```

### Чат интерфейс

```python
from llama_cpp import Llama

llm = Llama(model_path="./models/chat-model.gguf")

# Chat completion
response = llm.create_chat_completion(
    messages=[
        {"role": "user", "content": "Hello!"}
    ],
    temperature=0.7,
    max_tokens=100
)

print(response['choices'][0]['message']['content'])
```

### Потокови отговори

```python
# Streaming text generation
stream = llm("Tell me a story", max_tokens=200, stream=True)

for output in stream:
    print(output['choices'][0]['text'], end='', flush=True)
```

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

```python
from langchain.llms import LlamaCpp
from langchain.prompts import PromptTemplate
from langchain.chains import LLMChain

# Initialize LLM
llm = LlamaCpp(
    model_path="./models/model.gguf",
    n_ctx=2048,
    n_threads=8
)

# Create prompt template
template = "Question: {question}\nAnswer:"
prompt = PromptTemplate(template=template, input_variables=["question"])

# Create chain
chain = LLMChain(llm=llm, prompt=prompt)

# Use the chain
result = chain.run(question="What is artificial intelligence?")
print(result)
```

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

### Чести проблеми и решения

#### Грешки при компилация

**Проблем: CMake не е намерен**
```bash
# Solution: Install CMake
# Ubuntu/Debian
sudo apt install cmake

# macOS
brew install cmake
```

**Проблем: Компилаторът не е намерен**
```bash
# Solution: Install build tools
# Ubuntu/Debian
sudo apt install build-essential

# macOS
xcode-select --install
```

#### Проблеми при изпълнение

**Проблем: Зареждането на модела се проваля**
- Проверете пътя до файла на модела
- Проверете разрешенията на файла
- Уверете се, че има достатъчно RAM
- Опитайте различни нива на квантизация

**Проблем: Слаба производителност**
- Активирайте хардуерно ускорение
- Увеличете броя на нишките
- Използвайте подходяща квантизация
- Проверете използването на GPU паметта

#### Проблеми с паметта

**Проблем: Недостиг на памет**
```bash
# Solutions:
# 1. Use smaller quantization
./llama-cli -m model-q4_0.gguf

# 2. Reduce context size
./llama-cli -m model.gguf -c 1024

# 3. Offload to GPU
./llama-cli -m model.gguf -ngl 32
```

### Проблеми, специфични за платформата

#### Windows
- Използвайте MinGW или компилатор на Visual Studio
- Уверете се, че PATH е правилно конфигуриран
- Проверете за намеса от антивирусен софтуер

#### macOS
- Активирайте Metal за Apple Silicon
- Използвайте Rosetta 2 за съвместимост, ако е необходимо
- Проверете инструментите за команден ред на Xcode

#### Linux
- Инсталирайте пакети за разработка
- Проверете версиите на драйверите за GPU
- Уверете се, че е инсталиран CUDA toolkit

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

### Избор на модел
1. **Изберете подходяща квантизация** според вашия хардуер
2. **Вземете предвид размера на модела** спрямо качеството
3. **Тествайте различни модели** за вашия конкретен случай

### Оптимизация на производителността
1. **Използвайте GPU ускорение**, когато е налично
2. **Оптимизирайте броя на нишките** за вашия CPU
3. **Задайте подходящ размер на контекста** за вашия случай
4. **Активирайте паметта за големи модели**

### Деплоймънт в продукция
1. **Използвайте режим на сървър** за достъп до API
2. **Имплементирайте правилно управление на грешки**
3. **Следете използването на ресурси**
4. **Настройте логване и мониторинг**

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

### Съображения за сигурност
1. **Валидирайте входните подканяния**
2. **Имплементирайте ограничаване на скоростта**
3. **Защитете API крайните точки**
4. **Следете за модели на злоупотреба**

## Заключение

Llama.cpp предоставя мощен и ефективен начин за локално изпълнение на големи езикови модели на различни хардуерни конфигурации. Независимо дали разработвате AI приложения, провеждате изследвания или просто експериментирате с LLMs, тази рамка предлага гъвкавостта и производителността, необходими за широк спектър от приложения.

Основни изводи:
- Изберете метода на инсталация, който най-добре отговаря на вашите нужди
- Оптимизирайте за вашата специфична хардуерна конфигурация
- Започнете с основна употреба и постепенно изследвайте разширени функции
- Помислете за използване на Python връзките за по-лесна интеграция
- Следвайте най-добрите практики за деплоймънт в продукция

За повече информация и актуализации посетете [официалното хранилище на Llama.cpp](https://github.com/ggml-org/llama.cpp) и се запознайте с подробната документация и наличните ресурси от общността.

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

- [03: Microsoft Olive Optimization Suite](./03.MicrosoftOlive.md)

---

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