Made for Agent
Idioma: Português (Brasil)

Catálogo de modelos

5.1 Listar modelos

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. 
{
  "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

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).
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).

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

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

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):

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).