Aliases de modelos hospedados

Um modelo hospedado é um alias estável, local ao projeto, para um job de treinamento que produziu um artefato — um que terminou com sucesso, ou um que você parou depois de ele já ter treinado. Aliases são identidades de roteamento sobre um pool compartilhado; criá-los não aloca uma GPU dedicada.

Endpoints do ciclo de vida

GET  /api/projects/{owner_slug}/{project_slug}/models
POST /api/projects/{owner_slug}/{project_slug}/models
PUT  /api/projects/{owner_slug}/{project_slug}/models/{model_slug}
POST /api/projects/{owner_slug}/{project_slug}/models/{model_slug}/disable
POST /api/projects/{owner_slug}/{project_slug}/models/{model_slug}/enable

A criação/atualização deve apontar para um job com artefato promovido. Reapontar um alias permite publicar um novo resultado sem mudar o slug usado pelos clientes. O corpo da atualização carrega somente a nova referência de job; o nome e o slug do alias continuam estáveis:

{
  "training_job_id": 87
}

O proprietário pode fazer isso na tela Modelos do projeto. Uma base aposentada ou um job sem artefato promovido retorna 409.

Listagem e paginação

A lista de aliases do projeto mantém a resposta legada em array quando nenhum parâmetro de paginação é enviado. Clientes do produto devem usar o contrato limitado por cursor:

GET /api/projects/{owner_slug}/{project_slug}/models?pagination=cursor&limit=25
GET /api/projects/{owner_slug}/{project_slug}/models?pagination=cursor&limit=25&cursor=<next_cursor>

As respostas com cursor são {data, next_cursor, total_count}. O limite padrão é 25 e o máximo é 100. Cursores são opacos, ordenados pelo id imutável do alias, e devem ser reenviados sem alteração. A autorização e os filtros são aplicados antes da página, portanto seguir next_cursor alcança todos os aliases que o chamador pode ver.

O registro entre projetos é o endpoint separado GET /api/models. Ele usa o mesmo formato de cursor e limite padrão de 25/máximo de 100; filtros de access, status e visibilidade de arquivamento são aplicados no servidor. O objeto totals contém agregados de uso, não um total de linhas calculado pelo cliente.

Acesso

Um alias pode ser privado ao proprietário, compartilhado com contas escolhidas ou público, conforme os campos de compartilhamento. A lista de modelos OpenAI considera o chamador e só retorna aliases que o bearer pode invocar. Quem não tem acesso recebe o mesmo model_not_found de um alias desconhecido; isso impede enumeração de slugs.

Servir um alias

Use o alias diretamente:

{
  "model": "support-assistant",
  "messages": [{"role": "user", "content": "Olá"}]
}

O plano de controle resolve o alias para seu proprietário e pagador, verifica o artefato LoRA promovido e envia um descriptor assinado à unidade de serving. Um adapter ausente ou inválido nunca cai silenciosamente para o modelo base.

Para um job de origem parado, cancelled é o estado terminal da tentativa, não um sinal de que o adaptador desapareceu. O serving usa o artefato promovido e model_available; uma tentativa cancelled sem artefato promovido é recusada.

Depreciação

O catálogo é a fonte de verdade. Um fine-tune treinado em uma base aposentada é marcado como deprecated: true nos payloads de jobs/modelos, não pode ser publicado ou reapontado e retorna 410 com error.code = "model_deprecated" quando servido. Downloads dos artefatos existentes continuam disponíveis para migração ou auditoria.

Arquivamento de projetos

Arquivar é reversível e não remove chats, jobs, aliases ou artefatos. Projetos arquivados são somente leitura: escritas retornam o conflito normal de arquivo, enquanto a inferência OpenAI retorna:

{
  "error": {
    "type": "invalid_request_error",
    "code": "project_archived"
  }
}

A resposta OpenAI é 404, sem Retry-After, porque arquivar é uma ação deliberada do proprietário, não uma indisponibilidade transitória. Restaure o projeto nas configurações antes de servir novamente.