# Catálogo de modelos

> Cómo un servicio LMSP lista sus modelos locales, el objeto de modelo y sus indicadores de capacidad, los estados del ciclo de vida del modelo, los ids estables de modelo y las revisiones del catálogo.

Source: https://madeforagent.com/es/lmsp/1.0/models/
Language: es
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` | Devuelve solo los modelos que tienen la capacidad indicada, por ejemplo `chat`, `embeddings` o `tools`. |
| `ready_only` | Si es `true`, devuelve solo los modelos cuyo `status` es `ready`. Por defecto es `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 que los clientes no tengan que obtener el catálogo completo una y otra vez, un servicio **DEBERÍA** devolver una cabecera `ETag`, un campo `catalog_revision`, o ambos:

- `catalog_revision` es una cadena opaca que cambia cada vez que cambia el catálogo.
- Un servicio que envía `ETag` **DEBERÍA** responder con `304 Not Modified` a un `If-None-Match` coincidente.

## 5.2 Objeto de modelo {#object}

| Campo | Significado |
| --- | --- |
| `id` | Identificador estable del modelo, usado en toda solicitud que nombra un modelo. |
| `object` | Siempre `"model"`. |
| `display_name` | Nombre legible. El usuario puede cambiarlo. |
| `aliases` | Lista opcional de nombres alternativos. Son solo informativos. |
| `owned_by` | De dónde procede el modelo. `local` para los modelos instalados en este dispositivo. |
| `family` | Familia del modelo, como `qwen3`. |
| `revision` | Resumen criptográfico del contenido del modelo, como `sha256:8f27...`. |
| `status` | Estado del ciclo de vida ([sección 5.3](https://madeforagent.com/es/lmsp/1.0/models.md#lifecycle)). |
| `capabilities` | Indicadores booleanos: `chat`, `completion`, `embeddings`, `tools`, `vision`, `structured_output` y `streaming`. |
| `input_modalities`, `output_modalities` | Los tipos de contenido que el modelo lee y escribe. `text` es la única modalidad definida en 1.0. |
| `context_window` | Número máximo de tokens de contexto. |
| `max_output_tokens` | Número máximo de tokens en una respuesta. |
| `runtime` | `backend` (por ejemplo `llama.cpp`), `device` (por ejemplo `metal`) y `load_on_demand`. |
| `error` | Presente cuando `status` es `error`. Un objeto de problema ([sección 9.3](https://madeforagent.com/es/lmsp/1.0/common-rules.md#errors)). |

El `id` de un modelo **DEBE** ser estable. El usuario puede cambiar el nombre para mostrar y los alias, así que **NO DEBEN** usarse como clave primaria.

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

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

| Estado | Significado |
| --- | --- |
| `installed` | El modelo existe pero no está cargado. |
| `loading` | Se está asignando memoria o el entorno de ejecución se está inicializando. |
| `ready` | El modelo puede procesar solicitudes de inmediato. |
| `unloading` | Se están liberando recursos. |
| `error` | La carga falló. El objeto de modelo **DEBERÍA** incluir un error estructurado. |

Una nueva solicitud de carga devuelve a `loading` un modelo que está en estado `error`.

Cuando una solicitud nombra un modelo que está `installed` y su `runtime.load_on_demand` es `true`, el servicio lo carga como parte de la solicitud. Si el modelo no puede usarse de inmediato y no se carga bajo demanda, el servicio responde `409` con `model_not_ready`. Si la carga falla, el error es `model_load_failed`.

## 5.4 Operaciones con modelos {#operations}

`GET /lmsp/v1/models/{model_id}` devuelve un objeto de modelo. Un id desconocido produce `404` con `model_not_found`.

Dos endpoints opcionales controlan la carga de forma explícita. Están disponibles cuando la capacidad `model_management` es `true`, y requieren el ámbito `models:manage` ([sección 10.3](https://madeforagent.com/es/lmsp/1.0/security.md#scopes)):

| Endpoint | Comportamiento |
| --- | --- |
| `POST /lmsp/v1/models/{model_id}/load` | Precarga el modelo. Devuelve el objeto de modelo con `202 Accepted` cuando la carga ha comenzado, o `200` cuando ya está `ready`. |
| `POST /lmsp/v1/models/{model_id}/unload` | Libera el modelo de la memoria. Devuelve el objeto de modelo. Repetir la solicitud es inocuo. |

Ambos aceptan un `Idempotency-Key` ([sección 9.2](https://madeforagent.com/es/lmsp/1.0/common-rules.md#idempotency)).