dstack Prototyping: teste modelos em GPU antes de publicar o serviço

ANÁLISE EDITORIAL

Publicar um serviço de modelo sem testar a configuração no hardware real mistura duas perguntas. A imagem consegue iniciar? E a definição do serviço está correta? Quando tudo é tentado de uma vez, um erro de memória, cache, porta, comando ou backend pode parecer falha da plataforma, enquanto uma configuração de serviço defeituosa pode parecer problema do modelo.

A dstack Prototyping separa essas perguntas. A Skill orienta testar primeiro uma tarefa longa no mesmo tipo de hardware, iniciar o servidor dentro desse ambiente e enviar uma requisição real ao modelo. Só depois o conjunto aprovado de imagem, comando, recursos, variáveis, cache e destino é promovido para um serviço dstack e testado novamente pela URL pública ou privada correspondente.

Esse procedimento não promete que um modelo será rápido, barato ou adequado para produção. Ele cria uma sequência verificável para reduzir tentativa cega. Provisionar GPU pode gerar custo, baixar pesos pode consumir tempo e armazenamento, e uma configuração mal protegida pode expor um endpoint. A aprovação humana continua necessária antes de criar recursos, abrir acesso ou manter capacidade ativa.

O que esta Skill faz

A Skill cobre a fase em que ainda não há certeza sobre imagem, instalação, versão do framework de serving, comando de inicialização, porta, parâmetros, memória, quantidade de GPU, cache, fleet ou backend. Em vez de começar por um serviço, ela pede uma tarefa com um comando ocioso, como sleep infinity, para que o operador entre no ambiente e valide cada hipótese.

Dentro da tarefa, o fluxo instala ou confirma dependências, baixa o modelo, inicia o servidor, acompanha logs e envia uma requisição compatível com o comportamento esperado. Um endpoint de saúde ou uma importação bem-sucedida não bastam. Para um modelo de conversa, por exemplo, é necessário testar uma requisição que realmente use o modelo e conferir se a resposta tem o formato esperado.

Depois, a mesma configuração é submetida como serviço. Essa segunda execução não repete a exploração inteira. Ela verifica se o que funcionou localmente na tarefa também funciona sob o runtime de serviço, com URL, autenticação, porta, réplicas e roteamento corretos.

Para quem serve

Serve a equipes de IA, MLOps e plataforma que usam dstack para executar vLLM, SGLang ou outro servidor de modelo em nuvens de GPU, Kubernetes ou máquinas próprias. Também ajuda desenvolvedores que precisam transformar uma receita experimental em uma configuração de serviço sem esconder as decisões de hardware e custo.

É especialmente útil quando uma primeira tentativa falha com falta de memória, incompatibilidade de imagem, download lento, porta incorreta, flag removida ou ausência de oferta. A tarefa interativa permite mudar uma variável por vez e registrar o que realmente funcionou.

Não serve para provisionar recursos sem autorização, escolher automaticamente o provedor mais barato, estimar custo total ou certificar desempenho. A Skill também não substitui documentação do modelo, termos do provedor, política de dados nem revisão de segurança do endpoint.

Origem, adoção e versão

A origem auditada é o repositório oficial dstackai/dstack. Em 17 de setembro de 2026, a API pública do GitHub registrava 2.252 estrelas e 262 forks. A contagem atende ao critério de adoção do catálogo, mas não demonstra segurança, economia ou qualidade de um ambiente específico.

A curadoria fixou o commit 06d8dc4796f5be363c85c4fcc557a88235f474a5. Esse commit corresponde ao tag anotado da release 0.22.1. A Skill não declara versão própria no frontmatter, portanto 0.22.1 é a versão do projeto dstack, não uma versão independente da Skill.

O repositório declara licença MPL-2.0 e não estava arquivado na consulta. A referência reproduzível é o commit fixado, os dois SKILL.md e seus hashes, não a posição do projeto em listas ou a contagem de estrelas.

Compatibilidade e pré-requisitos

A Skill principal manda usar a Skill-base dstack para comandos, campos YAML, aplicação, anexação, estados e URLs. Por isso o pacote auditado inclui as duas instruções. A execução funcional exige um servidor dstack, a CLI configurada para um projeto e ao menos uma fleet capaz de provisionar ou reutilizar uma oferta compatível.

O guia oficial de instalação deve prevalecer sobre comandos lembrados de versões antigas. Backends de nuvem exigem contas e credenciais do provedor. Kubernetes exige um cluster compatível. Fleets SSH exigem hosts, chaves e rede aprovados. Nenhum desses itens está no ZIP.

Para serving, confirme também requisitos do modelo e do framework. A Skill aponta receitas e releases de vLLM e SGLang, mas manda reler as fontes atuais antes de escolher imagem, flags e formato de requisição.

Instalação

A origem documenta a instalação das Skills do repositório por um cliente compatível. Para preservar a revisão desta página, extraia o ZIP local em uma pasta de Skills e mantenha as duas subpastas, dstack e dstack-prototyping. Não mescle os dois SKILL.md.

unzip dstack-prototyping.zip -d .agents/skills/

O comando apenas cria arquivos Markdown e a licença. Revise o ZIP e o diff antes de continuar. Para instalar a CLI ou o servidor, siga a documentação oficial do projeto em ambiente separado. Não copie tokens para o SKILL.md, para arquivos versionados ou para mensagens do agente.

Clientes com outro diretório de Skills podem exigir caminho diferente. A compatibilidade depende de o cliente reconhecer frontmatter e instruções Markdown. O pacote não altera configuração do dstack nem instala Python, containers ou drivers.

Configuração antes do primeiro uso

Comece identificando servidor, projeto, fleet e backend autorizados. Liste somente os nomes das variáveis secretas no YAML. Valores reais devem permanecer em mecanismo de segredo ou arquivo local protegido, como o fluxo .envrc citado na Skill-base.

Defina limites antes de aplicar: tipo e quantidade de GPU, memória, região permitida, política spot ou sob demanda, armazenamento, duração máxima, dados que podem sair do ambiente e teto de custo. Se a fleet aceita escalonamento, confirme também duração ociosa e regra de término.

Escolha um modelo pequeno ou uma variante autorizada para o primeiro teste quando isso responder à mesma pergunta técnica. Não use dados de produção para validar a plumbing do serviço. Registre a origem do modelo, licença, termos de uso e necessidade de token.

Primeiro uso seguro

O primeiro uso deve parar na visualização do plano. Crie uma configuração de tarefa com nome explícito, recursos limitados e sleep infinity. Use o modo de plano da CLI e não confirme a aplicação até revisar backend, região, GPU, disco, variáveis, mounts e possível custo.

Depois da aprovação, aplique em modo destacado. A Skill-base orienta checar o run com dstack run get e saída JSON, acompanhando estados como pending, provisioning, running, failed e done. Não parseie a tabela humana como fonte de automação.

Quando a tarefa estiver ativa, anexe ou use SSH no job correto. Inicie o servidor em segundo plano com log conhecido, envie uma requisição local ao modelo e salve apenas a evidência necessária. Pare a tarefa ao concluir, respeitando a confirmação exigida e aguardando estado terminal antes de submeter outra.

Como o fluxo organiza o trabalho

A sequência separa descoberta, prova e promoção. Primeiro escolha hardware que comporte o objetivo. Depois valide fontes do framework. Em seguida teste imagem, instalação, cache, comando, porta, flags, recursos e requisição na tarefa. Só então crie o serviço com o mesmo conjunto aprovado.

Quando várias ofertas servem de forma equivalente, a Skill prefere destinos capazes de reutilizar instâncias ociosas ou volumes de instância. Isso pode reduzir downloads repetidos, mas não garante economia. Instâncias paradas, discos e caches podem continuar gerando custo conforme o provedor.

Se mudar imagem, classe de hardware ou caminho principal de instalação, volte a uma tarefa. Se o serviço falhar apenas por configuração do runtime dstack, corrija essa camada sem reabrir hipóteses já provadas. O relatório deve dizer qual hipótese mudou.

Da tarefa ao serviço

O serviço deve repetir a configuração que funcionou: imagem, comando, porta, recursos, variáveis, mounts de cache e escolha de fleet ou backend. O teste final usa a URL de serviço retornada pelo estado do run, com autenticação quando habilitada.

Uma resposta local na tarefa não prova que o gateway, a rota ou o token do serviço estão corretos. Do mesmo modo, um serviço marcado como ativo não prova que o modelo responde. Envie a mesma classe de requisição nas duas fases e compare formato, status e comportamento esperado.

Não exponha auth: false por conveniência. Se a configuração exigir acesso público, trate isso como decisão separada, com autorização, domínio, TLS, limitação de tráfego, logs e plano de remoção.

PD disaggregation exige outro nível de validação

Para prefill e decode separados, a Skill exige fleet com placement: cluster. Na tarefa, os componentes usam grupos de nós. No serviço, usam grupos de réplicas. O roteador normalmente pode ficar em CPU, enquanto workers exigem GPU.

O teste deve chamar o roteador, não apenas os workers. Conectividade, topologia, versões e interconexão entram no resultado. Um worker saudável isoladamente não demonstra que a composição distribuída atende requisições.

Como esse desenho amplia custo e superfície de falha, não o adote apenas porque aparece em uma receita. Documente a necessidade, a oferta escolhida, o plano de término e a evidência que justificaria manter a arquitetura.

Resultado esperado

A entrega mínima inclui a configuração testada, o plano aprovado, a identificação do run, o hardware realmente provisionado, o comando executado, a origem da imagem, o caminho de cache, a requisição usada, o status final e os logs relevantes.

Para o serviço, registre a URL sem expor segredo, o método de autenticação, a mesma requisição funcional e o estado depois do teste. Também informe se a tarefa, o serviço e a fleet temporária foram encerrados ou preservados por decisão explícita.

O resultado não é um benchmark. Latência de uma chamada, tempo de download ou custo de uma oferta isolada não sustentam conclusão geral. Se desempenho ou custo forem objetivos, crie protocolo separado com amostra, duração e métricas adequadas.

Permissões e riscos

O uso funcional pode ler e alterar arquivos YAML, consultar ofertas, provisionar GPU, baixar imagens e modelos, montar volumes, abrir portas, iniciar serviços e consumir créditos. Também pode enviar prompts e dados ao modelo ou ao backend escolhido.

Credenciais de nuvem, tokens de registro e tokens de modelos nunca devem aparecer no artigo, no ZIP ou no YAML versionado. Limite o projeto e a conta, prefira credenciais temporárias e revise logs antes de compartilhá-los.

O maior risco operacional é deixar recursos ativos. Use nomes reconhecíveis, tags quando disponíveis, prazo de término, alerta de custo e verificação final. Parar um run não implica automaticamente remover volume, fleet ou recurso externo associado.

Erros comuns e como corrigir

A tarefa fica em no offers

Consulte ofertas com filtros equivalentes e confirme se alguma fleet pode provisionar ou reutilizar a capacidade. Não aumente região, GPU ou preço sem autorização. Registre qual restrição impede a oferta.

O servidor inicia, mas a requisição falha

Confira porta, formato da API, nome do modelo, caminho do tokenizer, licença, token e logs do processo. Um health check verde não substitui a requisição real.

O download se repete em cada tentativa

Verifique se o backend é baseado em container limpo e se a configuração usa volume ou instância reutilizável. Não presuma que o cache local sobreviverá. Calcule também o risco de persistir dados ou pesos em armazenamento compartilhado.

O serviço funciona localmente, mas a URL retorna erro

Separe runtime do modelo de configuração do serviço. Confira porta declarada, campo model, base URL, autenticação, gateway e TLS. Se imagem e comando já foram provados, não troque tudo de uma vez.

O attach bloqueia a automação

A Skill-base orienta execução não bloqueante em contextos de agente. Para tarefas sem porta, logs podem ser suficientes. Se a sessão precisar de SSH ou encaminhamento de porta, use uma sessão controlada e finalize-a sem encerrar o run por engano.

Versão, licença e pacote auditado

A Skill sem versão própria foi fixada no commit 06d8dc4796f5be363c85c4fcc557a88235f474a5, correspondente ao projeto dstack 0.22.1. O pacote contém quatro arquivos: o SKILL.md de prototipagem, o SKILL.md-base do dstack, LICENSE e ORIGEM.md. O SHA-256 do ZIP é f92a850e87c4220d1d2db902b7de3c7593b72f54499377a8fc84ba06b4ffec20.

A MPL-2.0 fixada permite redistribuir o código-fonte coberto sob seus termos. O pacote preserva os dois arquivos de origem sem modificação, inclui a licença integral e informa como obter a fonte. Isto é descrição técnica, não aconselhamento jurídico.

Limites do pacote local

O ZIP não contém aplicação dstack, CLI, servidor, runner, código Python ou TypeScript, scripts, executáveis, containers, dependências, drivers, modelos, pesos, datasets, exemplos, imagens ou arquivos de configuração.

Também não contém conta de nuvem, projeto, fleet, backend, Kubernetes, host SSH, chave, token, credencial, endpoint, prompt, resposta, cache, volume, log, benchmark ou resultado. A Skill-base foi incluída porque a Skill de prototipagem delega a ela comandos e campos necessários.

Checklist antes de usar

• Confirme servidor, projeto, fleet, backend, região e conta autorizados.
• Defina teto de custo, duração máxima e plano de encerramento.
• Fixe commit, release, modelo, imagem e framework de serving.
• Mantenha valores secretos fora do YAML e do histórico do agente.
• Revise o plano antes de aplicar qualquer recurso.
• Teste requisição real dentro da tarefa antes do serviço.
• Repita a mesma requisição pela URL do serviço.
• Não confunda health check com inferência validada.
• Registre runs, logs, recursos e decisões sem expor credenciais.
• Confirme o término de serviços, tarefas, fleets e recursos temporários.

Fontes oficiais consultadas

• Repositório oficial dstack
• Commit auditado
• Release 0.22.1
• dstack Prototyping SKILL.md fixado
• dstack SKILL.md-base fixado
• Documentação oficial de tasks
• Documentação oficial de services
• Documentação oficial de backends
• Instalação oficial
• Licença MPL-2.0