# Catálogo de modelos

> Como um serviço LMSP lista seus modelos locais, o objeto de modelo e suas flags de capacidade, os estados do ciclo de vida do modelo, IDs de modelo estáveis e revisões do catálogo.

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

## 5.1 Listar modelos {#list}

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

| Parâmetro de consulta | Significado |
| --- | --- |
| `capability` | Retorna apenas os modelos que têm a capacidade informada, por exemplo `chat`, `embeddings` ou `tools`. |
| `ready_only` | Quando `true`, retorna apenas os modelos cujo `status` é `ready`. O padrão é `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
      }
    }
  ]
}
```

Para poupar os clientes de buscar o catálogo completo repetidamente, um serviço **DEVERIA** retornar um cabeçalho `ETag`, um campo `catalog_revision`, ou ambos:

- `catalog_revision` é uma string opaca que muda sempre que o catálogo muda.
- Um serviço que envia `ETag` **DEVERIA** responder a um `If-None-Match` correspondente com `304 Not Modified`.

## 5.2 Objeto de modelo {#object}

| Campo | Significado |
| --- | --- |
| `id` | Identificador estável do modelo, usado em toda requisição que nomeia um modelo. |
| `object` | Sempre `"model"`. |
| `display_name` | Nome legível. O usuário pode alterá-lo. |
| `aliases` | Lista opcional de nomes alternativos. São apenas informativos. |
| `owned_by` | De onde vem o modelo. `local` para modelos instalados neste dispositivo. |
| `family` | Família do modelo, como `qwen3`. |
| `revision` | Digest do conteúdo do modelo, como `sha256:8f27...`. |
| `status` | Estado do ciclo de vida ([seção 5.3](https://madeforagent.com/pt-br/lmsp/1.0/models.md#lifecycle)). |
| `capabilities` | Flags booleanas: `chat`, `completion`, `embeddings`, `tools`, `vision`, `structured_output` e `streaming`. |
| `input_modalities`, `output_modalities` | Os tipos de conteúdo que o modelo lê e escreve. `text` é a única modalidade definida na 1.0. |
| `context_window` | Número máximo de tokens de contexto. |
| `max_output_tokens` | Número máximo de tokens em uma resposta. |
| `runtime` | `backend` (por exemplo `llama.cpp`), `device` (por exemplo `metal`) e `load_on_demand`. |
| `error` | Presente quando `status` é `error`. Um objeto de problema ([seção 9.3](https://madeforagent.com/pt-br/lmsp/1.0/common-rules.md#errors)). |

O `id` de um modelo **DEVE** ser estável. O nome de exibição e os aliases podem ser alterados pelo usuário, portanto **NÃO DEVEM** ser usados como chave primária.

## 5.3 Ciclo de vida do modelo {#lifecycle}

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

| Status | Significado |
| --- | --- |
| `installed` | O modelo existe, mas não está carregado. |
| `loading` | A memória está sendo alocada ou o ambiente de execução está sendo inicializado. |
| `ready` | O modelo pode processar requisições imediatamente. |
| `unloading` | Os recursos estão sendo liberados. |
| `error` | O carregamento falhou. O objeto de modelo **DEVERIA** carregar um erro estruturado. |

Uma nova requisição de carregamento move um modelo no estado `error` de volta para `loading`.

Quando uma requisição nomeia um modelo que está `installed` e cujo `runtime.load_on_demand` é `true`, o serviço o carrega como parte da requisição. Se o modelo não puder ser usado imediatamente e não for carregado sob demanda, o serviço responde `409` com `model_not_ready`. Se o carregamento falhar, o erro é `model_load_failed`.

## 5.4 Operações com modelos {#operations}

`GET /lmsp/v1/models/{model_id}` retorna um objeto de modelo. Um ID desconhecido resulta em `404` com `model_not_found`.

Dois endpoints opcionais controlam o carregamento explicitamente. Eles estão disponíveis quando a capacidade `model_management` é `true` e exigem o escopo `models:manage` ([seção 10.3](https://madeforagent.com/pt-br/lmsp/1.0/security.md#scopes)):

| Endpoint | Comportamento |
| --- | --- |
| `POST /lmsp/v1/models/{model_id}/load` | Pré-carrega o modelo. Retorna o objeto de modelo com `202 Accepted` quando o carregamento começou, ou `200` quando ele já está `ready`. |
| `POST /lmsp/v1/models/{model_id}/unload` | Descarrega o modelo. Retorna o objeto de modelo. Repetir a requisição é inofensivo. |

Ambos aceitam um `Idempotency-Key` ([seção 9.2](https://madeforagent.com/pt-br/lmsp/1.0/common-rules.md#idempotency)).