# Каталог моделей

> Как сервис LMSP перечисляет свои локальные модели, объект модели и его флаги возможностей, состояния жизненного цикла, стабильные идентификаторы моделей и ревизии каталога.

Source: https://madeforagent.com/ru/lmsp/1.0/models/
Language: ru
Specification: LMSP 1.0 (draft)
Updated: 2026-11-08

## 5.1 Список моделей {#list}

```http
GET /lmsp/v1/models?capability=chat&ready_only=false
Authorization: Bearer <token>
```

| Параметр запроса | Значение |
| --- | --- |
| `capability` | Возвращает только модели с указанной возможностью, например `chat`, `embeddings` или `tools`. |
| `ready_only` | При значении `true` возвращает только модели, у которых `status` равен `ready`. По умолчанию `false`. |

```json
{
  "object": "list",
  "catalog_revision": "42",
  "data": [
    {
      "id": "qwen3:14b-q4_k_m",
      "object": "model",
      "display_name": "Qwen3 14B Q4_K_M",
      "owned_by": "local",
      "family": "qwen3",
      "revision": "sha256:8f27c1a4e9b05d36f2a7c8e1b4d90a63c5e2f7b8a1d4c9e60b3f5a7d2c8e1b04",
      "status": "ready",
      "capabilities": {
        "chat": true,
        "completion": true,
        "embeddings": false,
        "tools": true,
        "vision": false,
        "structured_output": true,
        "streaming": true
      },
      "input_modalities": ["text"],
      "output_modalities": ["text"],
      "context_window": 32768,
      "max_output_tokens": 8192,
      "runtime": {
        "backend": "llama.cpp",
        "device": "metal",
        "load_on_demand": true
      }
    }
  ]
}
```

Чтобы клиентам не приходилось раз за разом запрашивать весь каталог, сервису **СЛЕДУЕТ** возвращать заголовок `ETag`, поле `catalog_revision` или и то и другое:

- `catalog_revision` — непрозрачная строка, которая меняется при каждом изменении каталога.
- Сервису, который отправляет `ETag`, **СЛЕДУЕТ** отвечать на совпадающий `If-None-Match` кодом `304 Not Modified`.

## 5.2 Объект модели {#object}

| Поле | Значение |
| --- | --- |
| `id` | Стабильный идентификатор модели, используемый в каждом запросе, где названа модель. |
| `object` | Всегда `"model"`. |
| `display_name` | Читаемое имя. Пользователь может его изменить. |
| `aliases` | Необязательный список альтернативных имён. Носят только информационный характер. |
| `owned_by` | Откуда взялась модель. `local` — для моделей, установленных на этом устройстве. |
| `family` | Семейство модели, например `qwen3`. |
| `revision` | Дайджест содержимого модели, например `sha256:8f27...`. |
| `status` | Состояние жизненного цикла ([раздел 5.3](https://madeforagent.com/ru/lmsp/1.0/models.md#lifecycle)). |
| `capabilities` | Булевы флаги: `chat`, `completion`, `embeddings`, `tools`, `vision`, `structured_output` и `streaming`. |
| `input_modalities`, `output_modalities` | Виды содержимого, которые модель читает и пишет. В версии 1.0 определена только модальность `text`. |
| `context_window` | Максимальное число токенов контекста. |
| `max_output_tokens` | Максимальное число токенов в одном ответе. |
| `runtime` | `backend` (например, `llama.cpp`), `device` (например, `metal`) и `load_on_demand`. |
| `error` | Присутствует, когда `status` равен `error`. Объект проблемы ([раздел 9.3](https://madeforagent.com/ru/lmsp/1.0/common-rules.md#errors)). |

Идентификатор `id` модели **ДОЛЖЕН** быть стабильным. Отображаемое имя и алиасы пользователь может менять, поэтому они **НЕ ДОЛЖНЫ** использоваться как первичный ключ.

## 5.3 Жизненный цикл модели {#lifecycle}

```text
installed --> loading --> ready --> unloading --> installed
                 |
                 +-----> error
```

| Статус | Значение |
| --- | --- |
| `installed` | Модель существует, но не загружена. |
| `loading` | Выделяется память или инициализируется среда выполнения. |
| `ready` | Модель может сразу обрабатывать запросы. |
| `unloading` | Ресурсы освобождаются. |
| `error` | Загрузка не удалась. Объект модели **СЛЕДУЕТ** снабжать структурированной ошибкой. |

Новый запрос на загрузку переводит модель из состояния `error` обратно в `loading`.

Если запрос называет модель в состоянии `installed`, у которой `runtime.load_on_demand` равен `true`, сервис загружает её в рамках этого запроса. Если модель нельзя использовать сразу и она не загружается по требованию, сервис отвечает `409` с кодом `model_not_ready`. Если загрузка не удалась, возвращается ошибка `model_load_failed`.

## 5.4 Операции с моделями {#operations}

`GET /lmsp/v1/models/{model_id}` возвращает один объект модели. Неизвестный идентификатор даёт `404` с кодом `model_not_found`.

Два необязательных эндпоинта управляют загрузкой явно. Они доступны, когда возможность `model_management` равна `true`, и требуют область доступа `models:manage` ([раздел 10.3](https://madeforagent.com/ru/lmsp/1.0/security.md#scopes)):

| Эндпоинт | Поведение |
| --- | --- |
| `POST /lmsp/v1/models/{model_id}/load` | Предварительно загружает модель. Возвращает объект модели с `202 Accepted`, если загрузка началась, или с `200`, если модель уже `ready`. |
| `POST /lmsp/v1/models/{model_id}/unload` | Выгружает модель. Возвращает объект модели. Повторный запрос безвреден. |

Оба принимают `Idempotency-Key` ([раздел 9.2](https://madeforagent.com/ru/lmsp/1.0/common-rules.md#idempotency)).