Top-p / Nucleus Sampling

Top-p или nucleus sampling — это стратегия генерации текста, при которой модель на каждом шаге оставляет минимальный набор самых вероятных токенов, чья суммарная вероятность достигает порога p, и выбирает следующий токен только из этого набора. Проще говоря, вы не фиксируете точное число кандидатов заранее, как в top-k, а позволяете «ядру» кандидатов сжиматься или расширяться по текущему распределению вероятностей.

В актуальных инструментах это не только термин из статьи 2019 года: параметр top_p присутствует, например, в chat.completions.create в Python SDK OpenAI, а в Hugging Face Transformers он описан как часть настроек генерации. Практически это один из регуляторов разнообразия вывода, но его поддержка может отличаться между моделями и endpoint’ами.

Английский термин: top-p, nucleus sampling. В API и документации чаще встречается имя параметра top_p; в исследовательском контексте — nucleus sampling.

Простыми словами

Можно грубо представить это как короткий список «разумных продолжений», который модель пересчитывает после каждого токена. Если модель очень уверена, список получается маленьким. Если уверенность ниже и у нескольких вариантов близкие шансы, список расширяется.

В этом и смысл top-p: не держать жёстко, скажем, фиксированное число лучших вариантов всегда, а подстраиваться под ситуацию. Поэтому top-p обычно рассматривают как более адаптивный способ сэмплирования, чем фиксированное отсечение по количеству кандидатов.

Как это работает

Техническая последовательность выглядит так:

1. Модель считает вероятности следующего токена.
2. Токены сортируются по вероятности: от самого вероятного к менее вероятным.
3. Берётся минимальный префикс списка, у которого суммарная вероятность достигает порога p.
4. Все остальные токены отбрасываются.
5. Следующий токен случайно выбирается только из оставшегося «ядра».
6. Процесс повторяется для следующей позиции.

Пример распределения на одном шаге

Токен A = 0.55
Токен B = 0.20   суммарно 0.75
Токен C = 0.12   суммарно 0.87
Токен D = 0.06   суммарно 0.93
Токен E = 0.03
...

Если top_p = 0.90,
ядро = A + B + C + D
Из E и ниже модель уже не выбирает.

Ключевой нюанс: top-p работает с накопленной вероятностью, а не с процентом словаря и не с фиксированным числом кандидатов. Поэтому на одном шаге в ядро могут попасть 2 токена, а на другом — заметно больше.

Исторически сам подход был описан в статье Holtzman и соавторов The Curious Case of Neural Text Degeneration (2019), где и вводится идея nucleus sampling как способа ограничить хвост распределения.

Если вы используете Hugging Face Transformers, top-p влияет на результат только при do_sample=True. Без этого генерация остаётся greedy, и значение top_p не даёт эффекта. В документации Transformers также указано, что при top_p < 1 сохраняется минимальный набор токенов с суммарной вероятностью не ниже порога, а значение по умолчанию — 1.0.

Если вы используете OpenAI API через Python SDK, параметр top_p доступен в chat.completions.create. В комментариях к параметру OpenAI отдельно рекомендует менять либо top_p, либо temperature, но не оба сразу.

Где применяется

• Чат-генерация через API. Когда вы хотите сделать ответы менее однообразными, но не полностью отпускать выбор токенов, top-p выступает как управляемое отсечение маловероятного хвоста.
• Локальные эксперименты в Hugging Face Transformers. Для open-weight моделей top-p — базовая настройка в generate, особенно когда вы сравниваете greedy decoding и sampling.
• Исследование стратегий декодирования. В статьях и воспроизводимых экспериментах nucleus sampling используют как отдельную технику генерации, а не как часть обучения модели.
• Сравнение SaaS API и локального инференса. Если вы выбираете между закрытым API и open-weight стеком, полезно понимать, одинаково ли вообще доступны sampling-параметры в вашем endpoint и библиотеке. Для этого пригодятся материалы Open weights vs closed API: что выбрать и OpenAI API vs Google Gemini API: что выбрать.

Практический вывод: top-p нужен не «для качества вообще», а для контроля того, насколько широко модель смотрит на альтернативы при каждом следующем токене.

Практический пример

Ниже — минимальный сценарий, который показывает не «лучшую настройку», а сам принцип применения. Если вы хотите увидеть влияние параметра, сначала задайте только top_p, не смешивая его с temperature.

OpenAI Python SDK

from openai import OpenAI

client = OpenAI()

response = client.chat.completions.create(
    model="ваша_модель",
    messages=[
        {"role": "user", "content": "Сформулируй 3 варианта короткого заголовка про безопасность данных."}
    ],
    top_p=0.9
)

print(response)

Что важно в этом примере:

• top_p — актуальный параметр SDK, но поддержка зависит от конкретного endpoint и модели.
• Если вы оцениваете влияние параметра, не меняйте одновременно temperature, иначе будет сложнее понять, что именно изменило стиль ответа.
• Цены для API зависят от модели и проверяются на официальной странице OpenAI API pricing; их не стоит брать из старых статей или примеров кода.

Hugging Face Transformers

# Принципиальный пример: top_p сработает только при do_sample=True
outputs = model.generate(
    **inputs,
    do_sample=True,
    top_p=0.9
)

Если убрать do_sample=True, генерация останется greedy, и top-p не повлияет на результат. Для более детальной практики посмотрите как настроить Temperature и Top-p для контроля генерации.

Чем отличается от похожих терминов

Если вам нужен отдельный разбор пары методов, смотрите Top-p / top-k sampling.

Ограничения и заблуждения

• Заблуждение: top-p — это процент словаря. Нет. Это порог по суммарной вероятности, поэтому число оставшихся токенов заранее неизвестно.
• Заблуждение: top-p всегда работает, если параметр есть в коде. На практике поддержка зависит от endpoint и модели; это стоит проверять в актуальной документации нужного API.
• Заблуждение: в Transformers достаточно указать top_p. Нет. Без do_sample=True генерация остаётся greedy.
• Частая ошибка настройки: одновременно крутить top_p и temperature. OpenAI рекомендует менять один из этих параметров, а не оба сразу.
• Это не метод обучения. Nucleus sampling относится к этапу генерации текста, то есть к декодированию на инференсе.
• Комплаенс-ограничение для API. Если для вас важны региональная обработка данных и data residency, нельзя предполагать, что они одинаково доступны в каждом регионе: у OpenAI для не-US регионов требуются approval и ZDR amendment, а если региональная обработка не поддерживается, данные могут обрабатываться или храниться вне региона.

Редакционное ограничение: по состоянию на 2026-08-14 нельзя дать универсальный совет по «правильному» top-p для всех моделей. Поддержка параметра и его эффект зависят от конкретного endpoint, модели и библиотеки, поэтому перед внедрением сверяйте официальную документацию именно вашего стека.

Связанные материалы

• Top-p / top-k sampling — когда нужен именно разбор разницы между двумя способами отсечения кандидатов.
• Как настроить Temperature и Top-p для контроля генерации — практический сценарий настройки.
• Open weights vs closed API: что выбрать — где удобнее управлять параметрами декодирования.
• OpenAI API vs Google Gemini API: что выбрать — когда вы сравниваете API по возможностям интеграции.

Источники

• transformers/src/transformers/generation/configuration_utils.py at main · huggingface/transformers · GitHub
• Releases · huggingface/transformers · GitHub

• The Curious Case of Neural Text Degeneration
• Text generation strategies — Hugging Face Transformers
• openai-python: chat.completions.create и параметр top_p
• OpenAI Platform Docs: Make your first API request
• Models default usage policies by endpoint — OpenAI Platform Docs
• OpenAI API pricing

Вопросы и ответы

Что делает top-p?

Он ограничивает выбор следующего токена минимальным набором самых вероятных вариантов, чья суммарная вероятность достигает порога p. После этого токен выбирается только из этого набора.

Чем top-p отличается от top-k?

Top-k оставляет фиксированное количество кандидатов, а top-p — переменное количество, зависящее от формы распределения вероятностей на каждом шаге.

Нужно ли вместе настраивать top-p и temperature?

Обычно нет. В документации OpenAI рекомендуется менять либо top_p, либо temperature, но не оба сразу.

Почему top-p не работает в Transformers?

Чаще всего потому, что не включён sampling. В Hugging Face Transformers нужен do_sample=True, иначе генерация остаётся greedy.