Aliases, Latest e Versões Fixas
Nesta página
Três formas de referenciar um modelo
O campo model do seu pedido aceita três convenções de nomenclatura para designar aquilo que, à primeira vista, é o mesmo modelo. Isto não é apenas um pormenor documental: dependendo da convenção que escolher, a sua aplicação receberá exatamente o mesmo modelo em todas as chamadas durante meses, ou uma versão suscetível de mudar sem aviso prévio. A maioria das regressões inexplicáveis em produção — «as nossas respostas ficaram mais longas, mas ninguém alterou nada» — resulta disto.
Alias simples
O alias simples utiliza o nome base do modelo, sem sufixo:
{
"model": "grok-4.20"
}
Isto aponta para a versão estável mais recente do modelo. A xAI pode atualizar a versão subjacente a qualquer momento e só o saberá monitorizando os seus próprios resultados. Esta flexibilidade é exatamente o que deseja durante o desenvolvimento e a prototipagem: trabalha sempre com a melhor versão disponível sem ter de atualizar nada. Enquanto estiver a iterar sobre prompts, a explorar capacidades do modelo e a reprodutibilidade exata das respostas não for importante, esta convenção funciona.
Alias latest
O alias latest aponta para a versão mais avançada, uma que ainda não foi estabilizada:
{
"model": "grok-4.20-latest"
}
O que obtém aqui pode mudar frequentemente e incluir alterações ainda em validação. É uma ferramenta de avaliação, útil para testar versões futuras antes de se tornarem o alias padrão, medir ganhos de qualidade ou desempenho e preparar a sua migração de forma informada.
Pertence a ambientes de teste, nunca a produção. Uma alteração pode ocorrer da noite para o dia, modificar o comportamento do seu prompt e chegar aos seus utilizadores sem aviso — não terá uma linha de commit ou um ticket para culpar e entender o que aconteceu.
Versão fixa (Pinned)
Uma versão fixa inclui uma data no identificador:
{
"model": "grok-4.20-0309"
}
O sufixo -0309 corresponde à data de lançamento, neste caso 9 de março. Esta versão não se move: enquanto permanecer ativa, o modelo que responde hoje será o mesmo que responderá daqui a seis meses. É a única opção defensável para produção, por quatro razões sólidas. O comportamento da sua aplicação torna-se reprodutível, tornando os seus testes de integração e regressão válidos a longo prazo. Nenhuma atualização silenciosa o pode apanhar desprevenido. O timing da migração torna-se uma decisão planeada da equipa, não algo que lhe acontece. E se o comportamento mudar na mesma, sabe que a causa está do seu lado.
Uma convenção por ambiente
A melhor prática não é escolher entre as três, mas atribuir cada uma ao seu ambiente:
import os
ENVIRONMENT = os.getenv("APP_ENV", "development")
MODEL = {
"development": "grok-4.20", # Alias simples: última estável
"staging": "grok-4.20-latest", # Latest: testar novas funcionalidades
"production": "grok-4.20-0309", # Versão fixa: máxima estabilidade
}[ENVIRONMENT]
Encare este dicionário como um sistema de alerta precoce. O seu staging executa permanentemente no latest: se uma alteração futura quebrar um prompt, os seus testes de integração detetam-no antes dos seus utilizadores. A sua produção mantém-se entretanto numa versão fixa. Deteta alterações a montante sem nunca as sofrer a jusante.
Migrar de uma versão fixa para a seguinte
Quando surge uma nova versão fixa — digamos grok-4.20-0612 — a mudança merece um procedimento em vez de uma simples alteração de string. Primeiro, implemente a nova versão no staging através do alias latest, execute aí a sua suíte de testes de prompts e compare os resultados com os da versão atualmente em produção. Se a comparação for satisfatória, atualize a configuração de produção, monitore as métricas durante 48 horas — qualidade da resposta, taxa de satisfação, custo — e valide a migração ou reverta para a versão anterior.
O passo de comparação é o núcleo do sistema e pressupõe que manteve os resultados da versão em vigor: sem esta referência, «comparar» reduz-se a uma impressão. A fase de observação inclui deliberadamente o custo. Uma versão mais recente pode ser mais verbosa, gerar mais tokens de saída e aumentar a sua fatura em vários percentuais para uma qualidade percebida igual. Quarenta e oito horas são geralmente suficientes para ver isto, e reverter para a versão anterior continua a ser uma simples linha de configuração.
Pontos-chave
- Alias simples (
grok-4.20): versão estável mais recente, para desenvolvimento - Alias latest (
grok-4.20-latest): versão de ponta, apenas para testes - Versão fixa (
grok-4.20-0309): imutável, a única opção recomendada para produção - Utilize convenções diferentes por ambiente (dev/staging/prod)
- Planeie um processo de migração estruturado ao passar de uma versão fixa para outra