Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Convenções de Nomenclatura

Aula 13 de 14 Atualizada a 3 de novembro de 2026 Iniciante
Nesta página
  1. Compreender os identificadores de modelo
  2. Os três formatos de identificador
  3. Identificadores completos atuais
  4. Ciclo de vida do modelo
  5. Recomendações por ambiente
  6. Migração entre versões
  7. Endpoints da API
  8. Pontos-chave

Atualizado a 3 de novembro de 2026. Com base na página Models da xAI (secção Model Aliases): a tabela inclui o grok-4.7, o modelo recomendado pela xAI, e o grok-4.6. A recomendação para produção segue as orientações da xAI, que aconselha utilizar o alias para a maioria dos casos de uso e a versão datada para fluxos de trabalho que exigem consistência estrita. Fonte: Models.

Compreender os identificadores de modelo

Quando invoca a API da xAI, o campo model determina qual o modelo que processa o seu pedido. A xAI utiliza um sistema de nomenclatura estruturado com aliases e versões fixas. Compreender este sistema é essencial para gerir a estabilidade e a migração das suas aplicações.

Os três formatos de identificador

A xAI oferece três formas de referenciar um modelo, cada uma com um comportamento distinto:

Alias simples

{
  "model": "grok-4.20"
}

O alias simples aponta para a versão estável mais recente do modelo. Quando a xAI lança uma atualização menor, o alias redireciona automaticamente para a nova versão. A sua aplicação utiliza sempre a versão estável mais recente sem alterações de código.

Vantagem: beneficia automaticamente das melhorias. Risco: o comportamento pode mudar ligeiramente de uma versão para a outra.

Alias “latest”

{
  "model": "grok-4.20-latest"
}

O alias “latest” aponta para a versão de vanguarda — a iteração mais recente, incluindo versões ainda não promovidas para estáveis. Esta é a versão mais recente, mas potencialmente a menos testada.

Vantagem: acesso imediato às últimas melhorias. Risco: o comportamento pode mudar a qualquer momento; são possíveis regressões.

Versão fixa (Pinned)

{
  "model": "grok-4.20-0309"
}

A versão fixa identifica uma versão específica do modelo, indexada pela sua data de lançamento (neste caso, 9 de março). Esta versão nunca muda: o comportamento que observa hoje será idêntico daqui a seis meses.

Vantagem: estabilidade total, resultados reproduzíveis. Risco: a versão será eventualmente descontinuada e depois removida.

Identificadores completos atuais

Identificador da API Tipo Comportamento
grok-4.20-0309-reasoning Versão fixa Nunca muda
grok-4.20-0309-non-reasoning Versão fixa Nunca muda
grok-4.20-multi-agent-0309 Versão fixa Nunca muda
grok-4.7 Alias Versão estável mais recente do modelo recomendado pela xAI
grok-4.6 Alias Versão estável mais recente
grok-4.5 Alias Versão estável mais recente (alias `grok-4.5-latest` para a mais recente de todas)
grok-4.3 Alias Versão estável mais recente
grok-build-0.1 Alias Modelo de código, versão estável mais recente

Ciclo de vida do modelo

Cada modelo da xAI segue um ciclo de vida de três fases:

  1. Ativo — o modelo está disponível e recomendado para uso em produção
  2. Descontinuado — o modelo continua a funcionar, mas a xAI recomenda a migração para uma versão mais recente. É anunciado um prazo antes da remoção
  3. Obsoleto — o modelo é removido. Os pedidos para este modelo falham

Fique atento aos anúncios de descontinuação na consola da xAI e nas notas de lançamento. Quando um modelo for descontinuado, planeie a sua migração sem esperar pela data de remoção.

Recomendações por ambiente

Desenvolvimento

Utilize aliases simples (grok-4.7, grok-4.3) para beneficiar automaticamente das melhorias. No desenvolvimento, uma ligeira alteração de comportamento entre versões é aceitável e permite-lhe detetar incompatibilidades antes da produção.

Staging e testes

Utilize versões fixas (grok-4.20-0309-reasoning) para garantir a reprodutibilidade dos testes. Se um teste passar hoje, deve passar amanhã com exatamente o mesmo resultado.

Produção

A xAI recomenda o alias simples ou o alias -latest para a maioria dos casos de uso, permitindo-lhe beneficiar automaticamente de novas funcionalidades, e reserva a versão datada para fluxos de trabalho que exigem consistência estrita. Se a sua produção se enquadrar nesta categoria — resultados auditáveis, conformidade, testes de regressão — fixe a versão datada e planeie migrações periódicas após validação em staging.

Migração entre versões

Quando migrar de uma versão para outra:

  1. Atualize o campo model nos seus pedidos
  2. Teste os seus prompts existentes — os modelos mais recentes podem responder de forma diferente
  3. Verifique os parâmetros da API — uma nova versão pode suportar ou descontinuar certos parâmetros
  4. Valide os resultados — compare qualitativamente as saídas das versões antiga e nova

Endpoints da API

A xAI mantém dois endpoints principais:

  • /v1/responses — o endpoint principal, recomendado para todos os novos projetos
  • /v1/chat/completions — o endpoint legado, mantido para compatibilidade com clientes existentes

O endpoint legado já não recebe novas funcionalidades. Se estiver a iniciar um novo projeto, utilize exclusivamente o /v1/responses.

Pontos-chave

  • Três formatos: alias simples (estável), alias “latest” (vanguarda), versão fixa (imutável)
  • Em produção, utilize versões fixas para estabilidade
  • No desenvolvimento, utilize aliases para beneficiar das melhorias
  • Fique atento aos anúncios de descontinuação e planeie as suas migrações
  • O endpoint recomendado é /v1/responses, não /v1/chat/completions
  • Teste sempre os seus prompts ao migrar de versão