Pular para o conteúdo principal

Aliases de modelos hospedados

Um modelo hospedado é um alias estável, local ao projeto, para um job de treinamento ou para um ModelArtifact ReOpenly verificado. 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/v1/projects/{owner_slug}/{project_slug}/models
POST /api/v1/projects/{owner_slug}/{project_slug}/models
PUT  /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}
PATCH /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}
GET  /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/target-compatibility
GET  /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/download-metadata
POST /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/disable
POST /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/enable
GET  /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/shares
POST /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/shares
DELETE /api/v1/projects/{owner_slug}/{project_slug}/models/{model_slug}/shares/{share_id}

Criar um alias de geração de texto exige nome de exibição, slug estável e job de origem:

{
  "name": "Assistente de suporte",
  "slug": "assistente-suporte",
  "training_job_id": 87
}

Um alias de embedding referencia um receipt de artefato verificado e pertencente ao projeto por meio de uma fonte discriminada. O catálogo e a proveniência do Hugging Face são controlados pelo servidor; o cliente não envia URL ou branch como alvo de serving:

{
  "name": "Codificador de citações",
  "slug": "codificador-citacoes",
  "task": "embedding",
  "source": {
    "kind": "provisioned_artifact",
    "model_artifact_id": 101
  }
}

No exemplo de geração de texto, o job deve ter um artefato promovido. Reapontar um alias existente permite publicar um novo resultado sem mudar o slug usado pelos clientes. O corpo da atualização pode carregar somente a nova referência de job; nome e slug continuam estáveis:

{
  "training_job_id": 87
}

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

O reapontamento de embedding só aceita o mesmo task. Se o candidato mudar a dimensão ou a normalização dos vetores, envie index_compatibility_acknowledged: true depois de consultar GET .../target-compatibility; caso contrário o servidor retorna 409. GET .../download-metadata retorna hashes e tamanhos verificados para um alias de embedding autorizado, mas nunca URL de storage, prefixo de objeto ou manifesto bruto. Esse download é para um modelo provisionado no seu projeto; um modelo que você treinou é baixado como adaptador pelo job de treinamento (GET .../training-jobs/{job_id}/download, veja Jobs de treinamento).

Em um job concluído, Hospedar modelo usa o mesmo diálogo para projetos de texto e embedding. Escolha um novo endpoint ou um alias existente no projeto e revise o ajuste, o nome sugerido e o slug da API. Redirecionar um alias que muda a dimensão ou a normalização exige confirmar que os índices existentes precisam ser reconstruídos. O recibo mostra o alias salvo e seu estado até você selecionar Concluir; redirecionar um alias desativado o mantém desativado.

Modelos de embedding treinados​

Como em um ajuste de texto, um job de embedding concluído pode ser hospedado assim que o adaptador for verificado e promovido; nenhuma avaliação é exigida antes:

{
  "name": "Codificador de citações ajustado",
  "slug": "citacoes-ajustadas",
  "task": "embedding",
  "source": {"kind": "training_job", "training_job_id": 87}
}

PUT .../models/{model_slug} aponta um alias de embedding para outro job da mesma forma. Cada mudança incrementa a revisão auditável do destino, e o alias registra o adaptador que serve; toda requisição é atendida exatamente por esse adaptador.

Esta versão não inclui os painéis Qualidade de recuperação e Avaliação de recuperação. Jobs de avaliação separados para texto e embeddings estão planejados para uma versão futura. A validação do treino escolhe o checkpoint; ela não mede a qualidade servida. evaluation_receipt_sha256 e evaluation_acknowledged continuam aceitos e ignorados por compatibilidade; nenhum é obrigatório para hospedar um modelo.

Listagem e paginação​

A lista de aliases do projeto sempre usa uma página limitada por cursor, sem parâmetro de ativação. O cursor pertence ao projeto e não pode ser usado em outro.

GET /api/v1/projects/{owner_slug}/{project_slug}/models?limit=25
GET /api/v1/projects/{owner_slug}/{project_slug}/models?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/v1/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.

Compartilhamentos privados​

O proprietário cria um compartilhamento para o slug de uma conta e escolhe quem paga:

{
  "user_slug": "alex",
  "payer": "user",
  "extra_charge_percent": 10
}

payer é exatamente owner ou user. Com owner, o uso é cobrado do dono do modelo; com user, o destinatário precisa ter créditos suficientes e paga a inferência base mais extra_charge_percent. A sobretaxa vai de 0 a 100. Listar e remover compartilhamentos são operações exclusivas do proprietário.

Acesso público​

Atualize o alias com is_public e public_extra_charge_percent. Chamadores públicos pagam a própria inferência mais a sobretaxa configurada, também limitada de 0 a 100. Alterar o compartilhamento não reativa um alias desabilitado: somente a rota explícita /enable o ativa.

Servir um alias​

Use o alias diretamente:

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

A ReOpenly resolve o alias para seu proprietário e pagador e serve exatamente o adaptador verificado para o qual ele aponta. Um adaptador 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.

Revogar um compartilhamento pelo endpoint DELETE retorna 200 com {"status":"deleted"}.

Modelos base​

Todo projeto existente ou novo lista os modelos base da sua tarefa em Modelos hospedados. Use um modelo base sem criar um alias ou fazer ajuste fino. Usar modelo fornece exemplos Python, cURL e JavaScript com a URL do projeto. Modelos base de embeddings suportam Busca, Vetor e Similaridade sem alias. Chamadas ao modelo base são exclusivas do proprietário e dependem da disponibilidade de inferência.

Os exemplos de modelos base em Usar modelo omitem input_type: as bases públicas não têm instrução de consulta para aplicar. Os exemplos hospedados especificam query para aplicar a instrução treinada. Python envia o campo em extra_body={"input_type": "query"}; cURL e JavaScript incluem input_type no corpo. Para gerar embeddings de documentos com um modelo hospedado, escolha document. A API continua aceitando o papel opcional para modelos base.

A seção global de modelos base mostra cada base pública uma vez. Quando vários projetos podem usá-la, selecione o projeto no cartão antes de Usar modelo; o exemplo de SDK e o link do Playground usam esse projeto.