Гайд · TNWS AI
Как передать top_k в vLLM через extra_body и оценить эффект
Отправляем нестандартный для OpenAI параметр top_k через extra_body и сравниваем ответы на фиксированном корпусе.
Задача и применимость
Вопрос читателя: «как передать top_k в vLLM OpenAI SDK extra_body». Для Chat API vLLM с текстовой моделью и Python-клиентом OpenAI либо HTTP; актуальный синтаксис сверен 20 сентября 2026 года. В примере стандартная библиотека Python напрямую передаёт поле top_k в JSON.
Для воспроизводимости запишите фактическую версию установленного vLLM, модельный checkpoint и параметры запуска. Путь /models/your-chat-checkpoint либо /models/your-embedding-checkpoint в команде ниже — заполнитель, а не реальный файл. Наличие GPU, объём памяти и условия лицензии весов проверяются до запуска. Демонстрация не утверждает, что ответ модели заранее известен по буквам.
Проверенные возможности
Официальная документация приводит top_k как пример параметра vLLM, которого нет в обычном интерфейсе OpenAI; через Python SDK он передаётся в extra_body={"top_k":50}. При прямом HTTP JSON дополнительное поле просто включается в тело запроса. Меняйте top_k лишь при понятной задаче на выбор токенов.
Пошаговая процедура
- Определите контрольный русский промпт, для которого известны обязательные факты.
- Получите реальный model id из /v1/models.
- Отправьте HTTP-тело с top_k=1, явно задав прочие параметры.
- Повторите с top_k=50, не меняя вход и checkpoint.
- Сравните формат и точность на нескольких входах, а не выберите «лучший» ответ по одному примеру.
Команда для тестового запуска на локальном адресе (подставьте законно полученный checkpoint):
vllm serve /models/your-chat-checkpoint --host 127.0.0.1 --port 8000
Готовый запрос и контроль ответа
В приведённом фрагменте используется стандартная библиотека Python и простой общий помощник для отправки JSON. Подставьте при необходимости Bearer-токен через защищённую переменную окружения и проверьте, что ваш сервер его ожидает.
import json, urllib.request
BASE = "http://127.0.0.1:8000"
def call(path, payload):
data = json.dumps(payload, ensure_ascii=False).encode("utf-8")
request = urllib.request.Request(BASE + path, data=data,
headers={"Content-Type": "application/json"}, method="POST")
with urllib.request.urlopen(request, timeout=120) as reply:
return json.load(reply)
model = json.load(urllib.request.urlopen(BASE + "/v1/models"))["data"][0]["id"]
for k in (1, 50):
payload = {"model": model, "messages": [
{"role": "user", "content": "Напиши одну фразу: возврат товара — 14 дней."}],
"top_k": k, "temperature": 0.7, "max_tokens": 64}
reply = call("/v1/chat/completions", payload)
print(k, reply["choices"][0]["message"]["content"])
Пример входа и ожидаемого результата
Вход содержит правило о 14 днях. Ожидаемый критерий в обоих ответах — число 14 и отсутствие новых условий, которых во входе не было. При разных top_k слова могут отличаться; это не доказывает автоматического роста качества. Код печатает k рядом с ответом, чтобы избежать путаницы логов.
Как интерпретировать результат
top_k ограничивает множество кандидатов для следующего токена, но не задаёт смысловой фильтр «не ошибаться». Даже если при одном значении результат выглядит увереннее, это всего одна реализация. Для объективного выбора подготовьте несколько десятков задач с проверяемыми фактами: сроки, артикулы, отрицания и запрос без ответа. Сохраните одинаковый системный промпт и другие параметры. Если поменять сразу temperature, max_tokens и top_k, причину разницы уже не установить. Не переносите выбранный порог на другую модель без нового теста.
Развёртывание без потери контекста
При использовании SDK привычка записать extra_body в документации своего сервиса критична: стандартный интерфейс клиента может не показывать серверные расширения в сигнатуре метода. При прямом HTTP ключ top_k находится на том же уровне, что и messages. Отдельно проверьте файл generation_config.json: он может менять умолчания остальных параметров и исказить сравнение окружений. Для технической диагностики логируйте k и model id, но не храните приватный текст пользователя рядом с открытыми логами.
Проверки качества и границы метода
Короткий промпт из примера полезен для демонстрации передачи параметра, но не для вывода «top_k=50 оптимально». Проверяйте длинные ответы, русский язык, повторные запросы и долю нарушений обязательных фактов. Если строгие требования к структуре, отдельная схема или валидация результата принесут больше пользы, чем настройка выборки. Вариант top_k=1 может ухудшить разнообразие, а большое k не делает модель более информированной; решение принимайте по реальному сценарию публикации.
В протоколе эксперимента фиксируйте количество правильных фактов и процент отказов при отсутствии информации. Эти измерения отделяют стилистическое разнообразие от реальной пользы. Анализируйте ошибки по категориям, например «пропущено 14» и «придуман дополнительный срок», а не усредняйте всё в субъективную оценку. Настройку внедряйте сначала на тестовом трафике с откатом. Не обещайте читателю воспроизводимости текста до буквы только потому, что отправлено одно и то же top_k.
Критерии готовности
- JSON содержит top_k и сервер принимает запрос.
- Оба теста сохраняют исходный срок.
- Сравнение произведено при неизменных остальных настройках.
Типичные ошибки и чего не делать
- Не передавать top_k как неизвестный именованный аргумент стандартного SDK без extra_body.
- Не считать top_k проверкой истинности.
- Не менять много параметров в одном эксперименте.
Частые вопросы
Как передать top_k через SDK?
Через extra_body.
Можно ли передать его напрямую по HTTP?
Да, как поле JSON-тела.
Есть ли универсальное лучшее значение?
Нет, тестируйте на своей модели и данных.
Официальные источники
Частые вопросы
Как передать top_k через SDK?
Через extra_body.
Можно ли передать его напрямую по HTTP?
Да, как поле JSON-тела.
Есть ли универсальное лучшее значение?
Нет, тестируйте на своей модели и данных.
Читайте также
Как извлечь JSON по схеме в vLLM через response_format
Схема для извлечения артикула и количества из текста: разбираем ответ и проверяем значения против исходника.
Как обработать named tool call в vLLM без произвольного выполнения кода
Требуем вызов одной безопасной функции, валидируем аргументы и не отдаём модели право запускать произвольные команды.
Как ограничить ответ vLLM вариантами choice при классификации заявок
Получаем одну из заранее разрешённых меток и отдельно проверяем, что классификация совпала с текстом обращения.
Комментарии
Пока тихо. Скажите первое слово