Impressão digital do sistema e reprodutibilidade
Nesta página
O system_fingerprint: rastreio da configuração
Cada resposta da API de Completions de Chat inclui um campo system_fingerprint — uma cadeia de caracteres que identifica a configuração do sistema utilizada para gerar a resposta. Os programadores ignoram frequentemente este campo, mas ele é valioso para a depuração e a reprodutibilidade.
{
"id": "chatcmpl-abc123",
"system_fingerprint": "fp_44709d6fcb",
"choices": [...],
"usage": {...}
}
Para que serve o system_fingerprint?
A impressão digital identifica a combinação da versão do modelo, dos parâmetros do sistema e da infraestrutura utilizados para processar o seu pedido. Dois pedidos idênticos processados com a mesma impressão digital produzirão resultados mais próximos do que dois pedidos com impressões digitais diferentes.
Casos de uso práticos
- Depuração: quando uma resposta muda inesperadamente, verifique se a impressão digital mudou. Uma alteração na impressão digital indica uma atualização do lado do servidor.
- Reprodutibilidade: se precisar de reproduzir um resultado, anote a impressão digital. Mesmo prompt + mesma impressão digital = maiores chances de obter a mesma resposta.
- Auditoria: em ambientes regulamentados, a impressão digital permite documentar exatamente qual versão do sistema produziu uma determinada resposta.
Versões de modelos e impressões digitais
A impressão digital está intimamente ligada à versão do modelo. A xAI oferece três convenções de nomenclatura para os modelos:
Alias simples
model = "grok-4.20"
Aponta para a versão estável mais recente. A impressão digital pode mudar quando a xAI atualiza esta versão estável, mesmo que o nome do modelo permaneça igual.
Alias “latest” (mais recente)
model = "grok-4.20-latest"
Aponta para a versão de ponta. A impressão digital mudará frequentemente, pois esta versão evolui continuamente.
Versão fixa
model = "grok-4.20-0309"
Aponta para uma versão específica que nunca mudará. A impressão digital será mais estável com este tipo de referência.
Reprodutibilidade da resposta
Mesmo com o mesmo prompt, modelo e impressão digital, as respostas nem sempre são idênticas. A geração de texto envolve um elemento de aleatoriedade controlado pelo parâmetro temperature.
Para maximizar a reprodutibilidade:
response = client.chat.completions.create(
model="grok-4.20-0309", # Versão fixa
messages=[
{"role": "user", "content": "Calculate 2 + 2"}
],
temperature=0, # Determinístico
seed=42 # Semente para o gerador aleatório
)
# Guardar a impressão digital para referência
print(f"Fingerprint: {response.system_fingerprint}")
Combinação para máxima reprodutibilidade
- Versão fixa do modelo (
grok-4.20-0309): garante que o modelo não muda - Temperatura definida como 0: remove a amostragem aleatória
- Semente fixa: inicializa o gerador aleatório no mesmo ponto
- Mesma impressão digital: confirma que a infraestrutura não mudou
Mesmo com tudo isto, a reprodutibilidade não é garantida a 100% devido a otimizações numéricas (operações de vírgula flutuante não determinísticas). Mas, na prática, os resultados serão muito próximos.
Registo de impressões digitais em produção
Uma boa prática é guardar a impressão digital com cada pedido para facilitar a depuração posterior:
def call_grok(messages: list, model: str = "grok-4.20-0309"):
response = client.chat.completions.create(
model=model,
messages=messages
)
# Registo para depuração
log = {
"response_id": response.id,
"model": response.model,
"fingerprint": response.system_fingerprint,
"finish_reason": response.choices[0].finish_reason,
"tokens": response.usage.total_tokens
}
logger.info("API call", extra=log)
return response.choices[0].message.content
Ciclo de vida do modelo
Os modelos da xAI seguem um ciclo de vida de três fases:
- Ativo: disponível e recomendado para uso em produção
- Descontinuado: ainda funciona, mas será removido. Pode aparecer um aviso nas respostas. Migre o mais breve possível.
- Obsoleto: removido. Os pedidos falharão com um erro.
Quando um modelo passa de Ativo para Descontinuado, a impressão digital muda frequentemente, pois a xAI pode redirecionar os pedidos para uma versão mais recente.
Pontos-chave
- O
system_fingerprintidentifica a configuração do sistema utilizada para gerar a resposta - Uma alteração na impressão digital indica uma mudança do lado do servidor (atualização do modelo ou da infraestrutura)
- Utilize versões fixas (
grok-4.20-0309) para máxima estabilidade em produção - Combine versão fixa + temperatura 0 + semente fixa para a melhor reprodutibilidade
- Registe a impressão digital com cada pedido para facilitar a depuração