# LocalAI

Запустите совместимый с OpenAI локальный API с помощью LocalAI.

{% hint style="success" %}
Все примеры можно запускать на GPU-серверах, арендуемых через [CLORE.AI Marketplace](https://clore.ai/marketplace).
{% endhint %}

## Требования к серверу

| Параметр      | Минимум        | Рекомендуется |
| ------------- | -------------- | ------------- |
| ОЗУ           | 8GB            | 16 ГБ+        |
| VRAM          | 6 ГБ           | 8 ГБ+         |
| Сеть          | 200 Мбит/с     | 500 Мбит/с+   |
| Время запуска | **5–10 минут** | -             |

{% hint style="warning" %}
**Важно:** LocalAI полностью инициализируется при первом запуске в течение 5–10 минут. HTTP 502 в это время — нормально: служба загружает и инициализирует модели.
{% endhint %}

{% hint style="info" %}
LocalAI имеет небольшой вес. Для запуска LLM (модели 7B+) выбирайте серверы с 16 ГБ+ оперативной памяти и 8 ГБ+ видеопамяти.
{% endhint %}

## Что такое LocalAI?

LocalAI предоставляет:

* Полную замену OpenAI API «под ключ»
* Поддержку нескольких форматов моделей
* Генерация текста, изображений, аудио и эмбеддингов
* GPU не обязателен (но с GPU быстрее)

## Поддерживаемые модели

| Тип         | Форматы     | Примеры                       |
| ----------- | ----------- | ----------------------------- |
| LLM         | GGUF, GGML  | Llama, Mistral, Phi           |
| Эмбеддинги  | GGUF        | all-MiniLM, BGE               |
| Изображения | Diffusers   | SD 1.5, SDXL                  |
| Аудио       | Whisper     | Речь в текст (Speech-to-text) |
| TTS         | Piper, Bark | Текст в речь                  |

## Быстрое развертывание

**Docker-образ:**

```
localai/localai:master-aio-gpu-nvidia-cuda-12
```

**Порты:**

```
22/tcp
8080/http
```

**Команда не требуется** - сервер запускается автоматически.

### Проверьте, что всё работает

После развертывания найдите ваш `http_pub` URL в **Моих заказах** и протестируйте:

```bash
# Проверить, готова ли служба
curl https://your-http-pub.clorecloud.net/readyz

# Показать доступные модели
curl https://your-http-pub.clorecloud.net/v1/models

# Получить версию
curl https://your-http-pub.clorecloud.net/version
```

{% hint style="warning" %}
Если вы получаете HTTP 502, подождите 5–10 минут — LocalAI инициализируется дольше, чем другие сервисы.
{% endhint %}

## Предустановленные модели

LocalAI поставляется с несколькими моделями, доступными из коробки:

| Название модели            | Тип          | Описание                      |
| -------------------------- | ------------ | ----------------------------- |
| `gpt-4`                    | Чат          | LLM общего назначения         |
| `gpt-4o`                   | Чат          | LLM общего назначения         |
| `gpt-4o-mini`              | Чат          | Меньшая, быстрая LLM          |
| `whisper-1`                | STT          | Речь в текст (Speech-to-text) |
| `tts-1`                    | TTS          | Текст в речь                  |
| `text-embedding-ada-002`   | Эмбеддинги   | Векторы размерности 384       |
| `jina-reranker-v1-base-en` | Перераanking | Перерангировка документов     |

{% hint style="info" %}
Эти модели работают сразу после запуска без дополнительной настройки.
{% endhint %}

## Доступ к вашему сервису

При развертывании на CLORE.AI доступ к LocalAI осуществляется через `http_pub` URL:

```bash
# Chat completion
curl https://your-http-pub.clorecloud.net/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "gpt-4",
        "messages": [{"role": "user", "content": "Hello!"}]
    }'
```

{% hint style="info" %}
Все `localhost:8080` примеры ниже работают при подключении через SSH. Для внешнего доступа замените на ваш `https://your-http-pub.clorecloud.net/` URL.
{% endhint %}

## Развертывание в Docker (альтернатива)

```bash
docker run -d \
    --gpus all \
    -p 8080:8080 \
    -v /workspace/models:/models \
    -e THREADS=4 \
    -e CONTEXT_SIZE=4096 \
    localai/localai:master-aio-gpu-nvidia-cuda-12
```

## Загрузка моделей

### Из галереи моделей

LocalAI имеет встроенную галерею моделей:

```bash
# Показать доступные модели
curl http://localhost:8080/models/available

# Установить из галереи
curl http://localhost:8080/models/apply -d '{"id": "mistral-7b-instruct"}'
```

### С Hugging Face

```bash
mkdir -p /workspace/models

# Llama 3.1 8B GGUF
wget https://huggingface.co/bartowski/Meta-Llama-3.1-8B-Instruct-GGUF/resolve/main/Meta-Llama-3.1-8B-Instruct-Q4_K_M.gguf \
    -O /workspace/models/llama-3.1-8b.gguf

# Mistral 7B GGUF
wget https://huggingface.co/bartowski/Mistral-7B-Instruct-v0.3-GGUF/resolve/main/Mistral-7B-Instruct-v0.3-Q4_K_M.gguf \
    -O /workspace/models/mistral-7b.gguf
```

## Конфигурация модели

Создайте YAML-конфиг для каждой модели:

**models/llama-3.1-8b.yaml:**

```yaml
name: llama-3.1-8b
backend: llama-cpp
parameters:
  model: llama-3.1-8b.gguf
  context_size: 4096
  threads: 8
  gpu_layers: 35
template:
  chat: |
    {{.Input}}
    ### Ответ:
  completion: |
    {{.Input}}
```

## Использование API

### Chat Completions (совместимо с OpenAI)

```python
import openai

# Для внешнего доступа используйте ваш http_pub URL:
client = openai.OpenAI(
    base_url="https://your-http-pub.clorecloud.net/v1",
    api_key="не_требуется"
)

# Или через SSH-туннель:
# client = openai.OpenAI(base_url="http://localhost:8080/v1", api_key="not-needed")

response = client.chat.completions.create(
    model="mistral-7b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Объясните квантовые вычисления простыми словами."}
    ],
    temperature=0.7,
    max_tokens=500
)

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

### Потоковая передача (Streaming)

```python
stream = client.chat.completions.create(
    model="mistral-7b",
    messages=[{"role": "user", "content": "Напишите стихотворение об ИИ"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

### Эмбеддинги

```python
response = client.embeddings.create(
    model="all-minilm",
    input="The quick brown fox jumps over the lazy dog"
)

embedding = response.data[0].embedding
print(f"Размерность эмбеддинга: {len(embedding)}")
```

### Генерация изображений

```python
response = client.images.generate(
    model="stablediffusion",
    prompt="a beautiful sunset over mountains",
    size="512x512",
    n=1
)

image_url = response.data[0].url
```

## Примеры cURL

### Чат

```bash
curl https://your-http-pub.clorecloud.net/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "mistral-7b",
        "messages": [{"role": "user", "content": "Hello!"}]
    }'
```

### Эмбеддинги

```bash
curl https://your-http-pub.clorecloud.net/v1/embeddings \
    -H "Content-Type: application/json" \
    -d '{
        "model": "text-embedding-ada-002",
        "input": "Your text here"
    }'
```

Ответ:

```json
{
  "data": [{"embedding": [0.1, -0.2, ...], "index": 0}],
  "model": "text-embedding-ada-002",
  "usage": {"prompt_tokens": 4, "total_tokens": 4}
}
```

### Текст в речь (TTS)

```bash
curl https://your-http-pub.clorecloud.net/v1/audio/speech \
    -H "Content-Type: application/json" \
    -d '{
        "model": "tts-1",
        "input": "Hello, welcome to LocalAI!",
        "voice": "alloy"
    }' \
    --output speech.wav
```

Доступные голоса: `alloy`, `echo`, `fable`, `onyx`, `nova`, `shimmer`

### Речь в текст (STT)

```bash
curl https://your-http-pub.clorecloud.net/v1/audio/transcriptions \
    -F "file=@audio.mp3" \
    -F "model=whisper-1"
```

Ответ:

```json
{"text": "Транскрибированный текст здесь..."}
```

### Перераanking

Переранжирование документов по релевантности запросу:

```bash
curl https://your-http-pub.clorecloud.net/v1/rerank \
    -H "Content-Type: application/json" \
    -d '{
        "model": "jina-reranker-v1-base-en",
        "query": "Что такое машинное обучение?",
        "documents": [
            "Машинное обучение — это часть ИИ",
            "Сегодня хорошая погода",
            "Глубокое обучение использует нейронные сети"
        ],
        "top_n": 2
    }'
```

Ответ:

```json
{
  "results": [
    {"index": 0, "relevance_score": 0.95},
    {"index": 2, "relevance_score": 0.82}
  ]
}
```

## Полная справочная документация API

### Стандартные эндпоинты (совместимые с OpenAI)

| Эндпоинт                   | Метод | Описание                      |
| -------------------------- | ----- | ----------------------------- |
| `/v1/models`               | GET   | Показать доступные модели     |
| `/v1/chat/completions`     | POST  | Чат-завершение                |
| `/v1/completions`          | POST  | Завершение текста             |
| `/v1/embeddings`           | POST  | Генерация эмбеддингов         |
| `/v1/audio/speech`         | POST  | Текст в речь                  |
| `/v1/audio/transcriptions` | POST  | Речь в текст (Speech-to-text) |
| `/v1/images/generations`   | POST  | Генерация изображений         |

### Дополнительные эндпоинты

| Эндпоинт            | Метод | Описание                     |
| ------------------- | ----- | ---------------------------- |
| `/readyz`           | GET   | Проверка готовности          |
| `/healthz`          | GET   | Проверка состояния           |
| `/version`          | GET   | Получить версию LocalAI      |
| `/v1/rerank`        | POST  | Перерангировка документов    |
| `/models/available` | GET   | Показать модели галереи      |
| `/models/apply`     | POST  | Установить модель из галереи |
| `/swagger/`         | GET   | Документация Swagger UI      |
| `/metrics`          | GET   | Метрики Prometheus           |

#### Получить версию

```bash
curl https://your-http-pub.clorecloud.net/version
```

Ответ:

```json
{"version": "v2.26.0"}
```

#### Документация Swagger

Откройте в браузере для интерактивной документации API:

```
https://your-http-pub.clorecloud.net/swagger/
```

## Ускорение с помощью GPU

### CUDA-бэкенд

```yaml
# В конфиге модели
parameters:
  gpu_layers: 35  # Количество слоёв на GPU
  f16: true       # Использовать FP16
```

### Полная выгрузка на GPU

```yaml
parameters:
  gpu_layers: 99  # Все слои на GPU
  main_gpu: 0     # Идентификатор основного GPU
```

## Несколько моделей

LocalAI может обслуживать несколько моделей одновременно:

```
models/
├── llama-3.1-8b.yaml
├── llama-3.1-8b.gguf
├── mistral-7b.yaml
├── mistral-7b.gguf
├── whisper.yaml
└── whisper-base.bin
```

Доступ к каждой по имени модели в вызовах API.

## Настройка производительности

### Для скорости

```yaml
parameters:
  threads: 8
  gpu_layers: 99
  batch_size: 512
  use_mmap: true
  use_mlock: true
```

### Для экономии памяти

```yaml
parameters:
  gpu_layers: 20  # Частичная выгрузка
  context_size: 2048  # Меньший контекст
  batch_size: 256
```

## Бенчмарки

| Модель          | GPU      | Токенов/с |
| --------------- | -------- | --------- |
| Llama 3.1 8B Q4 | RTX 3090 | \~100     |
| Mistral 7B Q4   | RTX 3090 | \~110     |
| Llama 3.1 8B Q4 | RTX 4090 | \~140     |
| Mixtral 8x7B Q4 | A100     | \~60      |

*Бенчмарки обновлены в январе 2026.*

## Устранение неполадок

### HTTP 502 на http\_pub URL

LocalAI запускается дольше, чем другие сервисы. Подождите **5–10 минут** и попробуйте снова:

```bash
# Проверить готовность
curl https://your-http-pub.clorecloud.net/readyz

# Проверить состояние
curl https://your-http-pub.clorecloud.net/healthz
```

### Модель не загружается

* Проверьте путь к файлу в YAML
* Проверьте совместимость формата GGUF
* Проверьте доступный объем VRAM

### Медленные ответы

* Увеличьте `gpu_layers`
* Включите `use_mmap`
* Уменьшите `context_size`

### Недостаточно памяти

* Уменьшите `gpu_layers`
* Используйте меньшую квантизацию (Q4 вместо Q8)
* Уменьшите размер батча

### Проблемы с генерацией изображений

{% hint style="warning" %}
Stable Diffusion может иметь проблемы совместимости с CUDA на некоторых конфигурациях GPU. Если вы сталкиваетесь с ошибками CUDA при генерации изображений, рассмотрите возможность использования выделенной модели Stable Diffusion вместо этого.
{% endhint %}

## Оценка стоимости

Типичные расценки на маркетплейсе CLORE.AI:

| GPU      | VRAM  | Цена/день  | Подходит для       |
| -------- | ----- | ---------- | ------------------ |
| RTX 3060 | 12GB  | $0.15–0.30 | Модели 7B          |
| RTX 3090 | 24 ГБ | $0.30–1.00 | Модели 13B         |
| RTX 4090 | 24 ГБ | $0.50–2.00 | Быстрая инференция |
| A100     | 40GB  | $1.50–3.00 | Большие модели     |

*Цены в USD/день. Тарифы зависят от провайдера — проверьте* [*CLORE.AI Marketplace*](https://clore.ai/marketplace) *для текущих тарифов.*

## Дальнейшие шаги

* [vLLM инференция](https://docs.clore.ai/guides/guides_v2-ru/yazykovye-modeli/vllm) - Повышенная пропускная способность
* [Руководство по Ollama](https://docs.clore.ai/guides/guides_v2-ru/yazykovye-modeli/ollama) - Проще в настройке
* [RAG с LangChain](https://docs.clore.ai/guides/guides_v2-ru/prodvinutoe/api-integration) - Создавайте приложения