Amostragem de núcleo top-p
Como top-p restringe a amostragem ao conjunto de tokens mais prováveis.
Amostragem de núcleo top-p é uma aula grátis de AI Prompt Engineering no CoddyKit. Esta é a aula 2 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Prompt Engineering, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Prompt Engineering inclui 4 aulas no total.
O que é a amostragem top-p?
A amostragem top-p (também chamada de amostragem de núcleo) é uma técnica que restringe a amostragem a um subconjunto dinâmico do vocabulário. Em vez de fazer a amostragem de todos os tokens, o modelo considera apenas o menor conjunto de tokens cuja probabilidade cumulativa seja pelo menos p.
Proposta no artigo 'O curioso caso da degeneração de textos neurais' (Holtzman et al., 2019), ela supera o simples escalonamento da temperatura na geração diversificada, mas coerente.
Como o top-p funciona passo a passo
Algoritmo:
- Calcule as probabilidades de softmax em todo o vocabulário
- Ordene os tokens por probabilidade (da maior para a menor)
- Percorra a lista ordenada, acumulando as probabilidades, até que a soma cumulativa alcance p
- Esse conjunto de tokens é o núcleo
- Faça a amostragem apenas do núcleo (normalize novamente as probabilidades para que a soma seja 1)
import numpy as np
def top_p_sample(logits, p=0.9):
probs = softmax(logits, temperature=1.0)
# Sort by probability descending
sorted_indices = np.argsort(probs)[::-1]
sorted_probs = probs[sorted_indices]
# Find nucleus: smallest set with cumulative prob >= p
cumulative = np.cumsum(sorted_probs)
nucleus_size = np.searchsorted(cumulative, p) + 1
nucleus_indices = sorted_indices[:nucleus_size]
nucleus_probs = sorted_probs[:nucleus_size]
# Renormalize
nucleus_probs = nucleus_probs / nucleus_probs.sum()
# Sample
chosen = np.random.choice(nucleus_indices, p=nucleus_probs)
return chosen
token = top_p_sample(logits, p=0.9)O núcleo dinâmico
A principal ideia do top-p é que o tamanho do núcleo é dinâmico. Quando o modelo está muito confiante (um token domina com probabilidade de 0.95), o núcleo contém apenas 1 token. Quando o modelo está incerto (muitos tokens têm probabilidades semelhantes), o núcleo se expande para incluir mais tokens.
Isso se adapta automaticamente à confiança do modelo — confiança alta → vocabulário reduzido → saída mais focada. Confiança baixa → vocabulário maior → mais exploração.
# High-confidence situation: model strongly prefers 'the'
high_confidence_logits = np.array([5.0, 1.0, 0.5, 0.1, -0.5])
hc_probs = softmax(high_confidence_logits)
print('High confidence probs:', np.round(hc_probs, 3))
# [0.974, 0.018, 0.011, 0.007, 0.004]
# Top-p=0.9 nucleus: just 1 token (cumulative after token 0 = 97.4% > 90%)
# Low-confidence situation: model unsure
low_confidence_logits = np.array([1.1, 1.0, 0.9, 0.8, 0.7])
lc_probs = softmax(low_confidence_logits)
print('Low confidence probs:', np.round(lc_probs, 3))
# [0.218, 0.208, 0.199, 0.190, 0.181]
# Top-p=0.9 nucleus: all 5 tokens (need all to reach 90%)Top-p na API da OpenAI
Defina top_p na sua chamada à API. O intervalo válido é de 0.0 a 1.0. O padrão é 1.0 (vocabulário completo, sem restrição de núcleo).
A OpenAI recomenda: se você alterar top_p, mantenha a temperatura em 1.0, e vice-versa. Ajustar ambos simultaneamente torna o comportamento efetivo da amostragem difícil de prever.
import openai
client = openai.OpenAI(api_key='sk-...')
# Nucleus sampling: top 90% of probability mass
resp = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': 'Tell me an interesting fact about the ocean.'}],
temperature=1.0, # leave temperature at default
top_p=0.9 # sample from top 90% nucleus
)
print(resp.choices[0].message.content)p=1.0: amostragem sem restrições
Quando top_p=1.0, o núcleo inclui todos os tokens — o vocabulário completo. Isso equivale à amostragem baseada apenas na temperatura, sem restrição de top-p. Todos os tokens, por menos prováveis que sejam, têm uma chance diferente de zero de serem selecionados.
Use p=1.0 quando quiser diversidade máxima. Com p=1.0, apenas a temperatura controla o formato da distribuição.
# p=1.0: all tokens in nucleus
resp_full = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': 'Generate a creative story opening.'}],
temperature=1.0,
top_p=1.0 # no nucleus restriction
)
# p=0.5: very focused nucleus
resp_focused = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': 'Generate a creative story opening.'}],
temperature=1.0,
top_p=0.5 # only top 50% probability mass
)Compromisso: top-p versus temperatura
Ambos os parâmetros controlam a diversidade da saída, mas de maneiras diferentes:
- Temperatura remodela toda a distribuição — a probabilidade relativa de um token em relação a todos os outros é alterada
- Top-p trunca a distribuição — um token é simplesmente excluído se estiver fora do núcleo, independentemente de sua probabilidade relativa
O top-p evita o problema da 'amostragem da cauda': com uma temperatura alta, tokens extremamente improváveis (texto sem sentido, palavras não relacionadas) são ocasionalmente selecionados. O top-p remove esses tokens da consideração por completo.
# The tail problem with temperature alone
high_temp_logits = np.array([3.0, 2.0, 1.0, 0.0, -1.0, -5.0, -10.0])
probs_high_temp = softmax(high_temp_logits, temperature=2.0)
print('High temp probs:', np.round(probs_high_temp, 4))
# The last token (logit=-10) still has a small probability
# With many tokens in a real vocab, these rare tokens accumulate
# and occasionally get sampled, producing incoherent output
# Top-p=0.9 cuts these off entirely
# ensuring only tokens contributing to the top 90% are consideredCombinando temperatura e top-p
Ao combinar os dois parâmetros, a temperatura é aplicada primeiro (remodelando a distribuição) e, depois, o top-p é aplicado às probabilidades resultantes (truncando-as até formar o núcleo).
Configurações comuns de produção:
- Escrita criativa: temperatura=1.0, top_p=0.95
- Conversa: temperatura=0.8, top_p=0.9
- Código: temperatura=0.2, top_p=1.0 (o top-p não é restritivo com uma temperatura baixa)
def combined_sample(logits, temperature=1.0, top_p=0.9):
# Step 1: apply temperature
probs = softmax(logits, temperature=temperature)
# Step 2: apply top-p nucleus
sorted_idx = np.argsort(probs)[::-1]
sorted_probs = probs[sorted_idx]
cumulative = np.cumsum(sorted_probs)
nucleus_size = np.searchsorted(cumulative, top_p) + 1
nucleus_idx = sorted_idx[:nucleus_size]
nucleus_probs = probs[nucleus_idx]
nucleus_probs = nucleus_probs / nucleus_probs.sum()
return np.random.choice(nucleus_idx, p=nucleus_probs)Top-p e repetição
Valores baixos de top-p podem causar repetição. Quando o núcleo é muito pequeno (por exemplo, p=0.5), o modelo faz repetidamente a amostragem de um conjunto minúsculo de tokens. A saída se torna repetitiva e previsível — o oposto do efeito criativo desejado.
Observe a repetição como um sinal de que o top-p está baixo demais para a tarefa. Um diagnóstico útil: se o modelo repete continuamente as mesmas frases, aumente o top-p ou a temperatura.
def detect_repetition(text, window=20):
words = text.split()
if len(words) < window * 2:
return False
# Check if any window of words repeats within the text
for i in range(len(words) - window):
phrase = ' '.join(words[i:i + window])
rest = ' '.join(words[i + window:])
if phrase in rest:
return True
return False
response = call_llm(prompt)
if detect_repetition(response):
print('Warning: repetition detected — consider increasing top_p or temperature')Top-p versus top-k: uma prévia
Top-p e top-k truncam o vocabulário antes da amostragem, mas de maneiras diferentes:
- Top-p: tamanho dinâmico do núcleo — expande quando o modelo está incerto e diminui quando está confiante
- Top-k: tamanho fixo do núcleo — sempre considera exatamente k tokens, independentemente da confiança
O top-p geralmente é preferido porque se adapta à confiança do modelo. O top-k será abordado em detalhes na próxima lição.
# Top-k equivalent for comparison
def top_k_sample(logits, k=50):
probs = softmax(logits)
# Keep only top-k tokens
top_k_indices = np.argsort(probs)[::-1][:k]
top_k_probs = probs[top_k_indices]
top_k_probs = top_k_probs / top_k_probs.sum()
return np.random.choice(top_k_indices, p=top_k_probs)
# Key difference: k is always 50, regardless of model confidence
# Top-p nucleus size varies from 1 to thousands depending on confidenceValores padrão e quando alterá-los
Valores padrão da API: top_p = 1.0 (sem restrição de núcleo). Quando você deve alterá-lo?
- Diminuir o top_p (0.7–0.9): quando as saídas parecem incoerentes ou contêm palavras sem sentido — há amostragem excessiva da cauda
- Manter em 1.0: quando a temperatura já é baixa — com uma temperatura baixa, a distribuição já é concentrada e o top-p não é restritivo de qualquer forma
- Não diminuir para menos de 0.5: isso causa repetição e perda de diversidade
# Guidance: what to adjust based on symptoms
TROUBLESHOOTING = {
'output is incoherent or contains random words': {
'fix': 'lower top_p to 0.9 or 0.85',
'or': 'lower temperature'
},
'output is repetitive and looping': {
'fix': 'increase top_p or temperature',
'also': 'try adding frequency_penalty or presence_penalty'
},
'output is too predictable and boring': {
'fix': 'increase temperature to 0.9-1.2',
'keep': 'top_p at 0.95'
},
'output needs to be deterministic': {
'fix': 'set temperature=0, top_p=1.0'
}
}Top-p no Claude da Anthropic
A API do Claude da Anthropic também expõe top_p como parâmetro. O comportamento é idêntico: o modelo cria um núcleo formado pelo menor conjunto de tokens cuja probabilidade cumulativa atinge o limite p e, em seguida, faz a amostragem desse núcleo.
Combine-o com a temperatura para obter um controle preciso: use a temperatura para moldar a distribuição e o top_p para limitar quais tokens podem ser selecionados dessa distribuição.
import anthropic
claude = anthropic.Anthropic(api_key='sk-ant-...')
# Creative writing with nucleus sampling
message = claude.messages.create(
model='claude-opus-4-5',
max_tokens=256,
temperature=1.0,
top_p=0.95,
messages=[{
'role': 'user',
'content': 'Write a short poem about the ocean.'
}]
)
print(message.content[0].text)Verificação de conhecimento
Qual é a principal vantagem da amostragem top-p (de núcleo) em relação à amostragem top-k?
Recapitulação: amostragem de núcleo top-p
A amostragem top-p cria um núcleo dinâmico — o menor conjunto de tokens que cobre pelo menos p da probabilidade total:
- p=1.0: vocabulário completo, sem restrições
- p=0.9: os 90% superiores da massa de probabilidade — configuração criativa típica
- p=0.5: muito focada — risco de repetição
O núcleo se expande quando o modelo está incerto e se contrai quando está confiante. Isso evita a amostragem da cauda (texto sem sentido proveniente de tokens improváveis) e preserva a diversidade. Próxima lição: amostragem top-k e como ela difere da top-p.
Perguntas Frequentes
A aula “Amostragem de núcleo top-p” é grátis?
Sim — o texto completo de “Amostragem de núcleo top-p” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Prompt Engineering, atualize para CoddyKit PRO. O curso de AI Prompt Engineering inclui 4 aulas no total.
O que vou aprender em “Amostragem de núcleo top-p”?
Como top-p restringe a amostragem ao conjunto de tokens mais prováveis. Você pratica AI Prompt Engineering com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar AI Prompt Engineering?
Nenhuma experiência prévia é necessária. AI Prompt Engineering no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 2 de 4.
Quanto tempo leva a aula “Amostragem de núcleo top-p”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de AI Prompt Engineering?
Sim. Cada aula de AI Prompt Engineering inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- O que é temperatura em LLMs?
- Amostragem de núcleo top-p
- Amostragem top-k
- Escolhendo parâmetros para seu caso de uso