Você já desejou poder ver por que o modelo Gemini escolheu uma palavra em vez de outra? Para desenvolvedores que criam aplicativos sofisticados, é crucial entender o processo de tomada de decisões de um modelo. Agora você pode fazer isso. O raciocínio do modelo não é mais uma caixa preta. O recurso logprobs foi oficialmente introduzido na API Gemini na Vertex AI, desbloqueando uma visão mais aprofundada das escolhas do modelo.
Esse recurso permite ver as pontuações de probabilidade para o token escolhido e suas principais alternativas, oferecendo insights sem precedentes do raciocínio do modelo. Ele é mais do que uma simples ferramenta de depuração; é uma maneira de criar aplicativos mais inteligentes, confiáveis e sensíveis a contexto.
Esta postagem do blog orienta você passo a passo pelo notebook "Intro to Logprobs", mostrando como ativar o recurso e aplicá-lo a casos de uso poderosos, como classificação confiável, preenchimento automático dinâmico e avaliação quantitativa de RAG.
Primeiro, vamos preparar seu ambiente para acompanhar o processo.
%pip install -U -q google-genai2. Configure o projeto: configure o ID e a localização do projeto do Google Cloud. Este tutorial usa essas credenciais para a autenticação do ambiente.
PROJECT_ID = "[your-project-id]"3. Inicialize o cliente e o modelo: crie um cliente para interagir com a API Vertex AI e especifique o modelo Gemini que deseja usar.
from google import genai
client = genai.Client(vertexai=True, project=PROJECT_ID, location="global")
MODEL_ID = "gemini-2.5-flash"Antes de ativar o recurso, vamos esclarecer o que é uma logprob (abreviação de "log probability", ou "probabilidade logarítmica"). Uma logprob é o logaritmo natural da pontuação de probabilidade que o modelo atribui a um token.
Estes são os principais conceitos:
Portanto, uma pontuação de logprob mais próxima de 0 indica maior confiança do modelo em sua escolha.
É possível ativar as probabilidades logarítmicas definindo dois parâmetros no generation_config da solicitação.
response_logprobs=True: diz ao modelo para retornar as probabilidades logarítmicas dos tokens escolhidos para a saída. O padrão é False.logprobs=[integer]: solicita que o modelo também retorne as probabilidades logarítmicas para um número especificado dos principais tokens alternativos em cada passo. O valor aceito está entre 1 e 20.
Vejamos isso em ação com um simples prompt de classificação. Pediremos ao modelo para classificar uma frase como "Positive," "Negative" ou "Neutral" (positiva, negativa ou neutra).
from google.genai.types import GenerateContentConfig
prompt = "I am not sure if I really like this restaurant a lot."
response_schema = {"type": "STRING", "enum": ["Positive", "Negative", "Neutral"]}
response = client.models.generate_content(
model=MODEL_ID,
contents=prompt,
generation_config=GenerateContentConfig(
response_mime_type="application/json",
response_schema=response_schema,
response_logprobs=True,
logprobs=3,
),
)Os dados de logprobs são retornados dentro do objeto de resposta. Você pode usar uma função auxiliar para imprimir as probabilidades logarítmicas em um formato legível. A função a seguir fornece uma visão detalhada das previsões do modelo para cada token na resposta gerada.
def print_logprobs(response):
"""
Print log probabilities for each token in the response
"""
if response.candidates and response.candidates[0].logprobs_result:
logprobs_result = response.candidates[0].logprobs_result
for i, chosen_candidate in enumerate(logprobs_result.chosen_candidates):
print(
f"Token: '{chosen_candidate.token}' ({chosen_candidate.log_probability:.4f})"
)
if i < len(logprobs_result.top_candidates):
top_alternatives = logprobs_result.top_candidates[i].candidates
alternatives = [
alt
for alt in top_alternatives
if alt.token != chosen_candidate.token
]
if alternatives:
print("Alternative Tokens:")
for alt_token_info in alternatives:
print(
f" - '{alt_token_info.token}': ({alt_token_info.log_probability:.4f})"
)
print("-" * 20)Digamos que o modelo tenha retornado o seguinte:
2. Tokens alternativos:
Essa saída mostra que o modelo está altamente confiante em sua escolha "Neutral", pois sua probabilidade logarítmica (-0,0214) é muito próxima de 0. As alternativas, "Positive" e "Negative", têm probabilidades logarítmicas significativamente mais baixas (mais negativas), indicando que o modelo as considerou muito menos prováveis.
As logprobs transformam a classificação de uma resposta simples em uma decisão transparente, permitindo a criação de sistemas mais robustos.
Cenário: você deseja automatizar uma tarefa de classificação, mas precisa sinalizar casos ambíguos sobre os quais o modelo não está confiante.
Por que usar logprobs?: uma pequena diferença entre as duas principais probabilidades logarítmicas é um sinal de ambiguidade. Você pode verificar essa diferença em relação a uma margem para decidir se a análise humana é necessária.
A função check_for_ambiguity no notebook calcula a diferença absoluta entre as logprobs da primeira e da segunda opções. Se essa diferença for inferior a uma ambiguity_margin predefinida, ela sinalizará o resultado como ambíguo.
Cenário: para aplicações críticas, você quer aceitar uma classificação apenas se a confiança do modelo exceder um determinado nível, como 90%.
Por que usar logprobs?: as logprobs fornecem uma medida direta da confiança do modelo. Você pode converter a probabilidade logarítmica do token escolhido em uma pontuação de probabilidade bruta para aplicar um limite.
A função accept_if_confident demonstra isso usando math.exp() para converter a logprob em uma porcentagem de probabilidade e, em seguida, verifica se ela está acima de um threshold (limite).
Cenário: você deseja criar um recurso de preenchimento automático que sugira as próximas palavras mais prováveis à medida que o usuário digitar.
Por que usar logprobs?: ao consultar repetidamente o modelo com o texto em expansão e examinar as logprobs dos principais candidatos, você pode observar as previsões de mudança do modelo e oferecer sugestões relevantes em tempo real.
O notebook simula um usuário digitando, palavra por palavra, o seguinte: "The best thing about living in Toronto is the" (A melhor coisa de morar em Toronto é). À medida que o contexto se expande, as sugestões para a próxima palavra se tornam mais específicas e precisas:
Análise:
Isso mostra como as logprobs oferecem uma janela para a compreensão contextual do modelo, permitindo criar recursos mais adaptáveis e conscientes de contexto.
Cenário: você tem um sistema de RAG e precisa avaliar se as respostas dele têm respaldo de acordo com o contexto recuperado.
Por que usar logprobs?: quando um LLM tem contexto relevante, sua confiança na geração de uma resposta factualmente consistente aumenta, o que se reflete em probabilidades logarítmicas mais altas. Você pode calcular uma probabilidade logarítmica média para a resposta gerada a fim de obter uma pontuação de "embasamento" ou "confiança".
O notebook configura uma base de conhecimento fictícia e testa três cenários: boa recuperação, recuperação ruim e nenhuma recuperação.
Análise:
Os resultados mostram uma correlação clara. O cenário "Good Retrieval" (boa recuperação) tem a pontuação mais alta (mais próxima de zero), já que o modelo está muito confiante de que sua resposta é respaldada pelo texto. Isso faz com que as logprobs sejam uma métrica poderosa para automatizar a avaliação e melhoria de sistemas de RAG.
Você aprendeu a usar as logprobs para obter uma visão mais profunda do processo de tomada de decisões do modelo. Explicamos como aplicar esses insights para analisar resultados de classificação, criar recursos de preenchimento automático dinâmico e avaliar sistemas de RAG.
Esses são apenas alguns exemplos de aplicações e, com esse recurso, há muitos outros casos de uso a serem explorados pelos desenvolvedores.
Para se aprofundar, explore o notebook completo e consulte a documentação oficial:
