Чтобы получить чистый Markdown этой страницы, добавьте .md к этому URL. Полный индекс документации см. на https://docs.nvidia.com/dynamo/llms.txt. Полное содержимое, включая справочник API и примеры SDK, см. на https://docs.nvidia.com/dynamo/llms-full.txt.

Расширения запросов NVIDIA (nvext)

nvext - это верхнеуровневый JSON-объект в теле запроса, который предоставляет расширения NVIDIA для совместимого с OpenAI API. Поля nvext используются frontend'ом Dynamo, preprocessor'ом, router'ом и backend worker'ами для управления маршрутизацией, preprocessing, метаданными ответа, планированием и приоритетом на уровне движка.

Использование

Добавляйте nvext как верхнеуровневое поле рядом со стандартными полями, совместимыми с OpenAI:

{
    "model": "my-model",
    "messages": [{"role": "user", "content": "Hello"}],
    "nvext": {
        "greed_sampling": true,
        "extra_fields": ["worker_id", "timing"],
        "agent_hints": {
            "osl": 1024,
            "priority": 5
        }
    }
}

Справочник полей

Поле	Тип	По умолчанию	Используется	Описание
`greed_sampling`	`bool`	`None`	Preprocessor	Принудительно включает жадную выборку независимо от других параметров sampling.
`use_raw_prompt`	`bool`	`None`	Preprocessor	Обходит шаблон prompt и передаёт prompt напрямую tokenizer'у.
`annotations`	`string[]`	`None`	Preprocessor	Запускает передачу внеполосной информации в потоке SSE через поле `event:`.
`backend_instance_id`	`u64`	`None`	Router	Маршрутизирует запрос к конкретному backend instance.
`token_data`	`u32[]`	`None`	Preprocessor	Предтокенизированные токены prompt'а. Если переданы вместе с `backend_instance_id`, токенизация пропускается.
`max_thinking_tokens`	`u32`	`None`	Backend	Максимально допустимое число thinking tokens (передаётся в backend).
`extra_fields`	`string[]`	`None`	Response builder	Поля, которые нужно включить в `nvext` ответа. Поддерживаются: `"worker_id"`, `"timing"`, `"routed_experts"`, `"engine_data"`, `"stop_reason"`.
`prefill_worker_id`	`u64`	`None`	Router	Маршрутизирует запрос к конкретному prefill worker (disaggregated serving).
`decode_worker_id`	`u64`	`None`	Router	Маршрутизирует запрос к конкретному decode worker (disaggregated serving).
`agent_context`	object	`None`	Preprocessor	Пассивная идентичность сессии и trajectory для agent traces. См. Agent Context ниже и Agent Tracing.
`agent_hints`	object	`None`	Router	Подсказки на уровне запроса для планирования и балансировки нагрузки. См. Agent Hints.
`session_control`	object	`None`	Router	Жизненный цикл сессии и sticky routing для изоляции KV subagent'ов. См. Session Control.

Связанная корневая опция вывода Dynamo:

Поле	Тип	По умолчанию	Используется	Описание
`return_tokens_as_token_ids`	`bool`	`false`	Response builder	Форматирует строки токенов logprob как `token_id:<id>` вместо декодированного текста.

return_tokens_as_token_ids изменяет только отображение возвращаемых токенов logprob. Чтобы остановка происходила по token ID, передавайте целочисленные ID в обычном массиве stop, например "stop": [576]. Строки вроде "token_id:576" остаются буквальными stop-sequences и не интерпретируются как token ID.

Переопределение через заголовки

Поля маршрутизации также можно задавать через HTTP-заголовки, и они имеют приоритет над значениями nvext:

Заголовок	Переопределяет
`x-worker-instance-id`	`backend_instance_id` и `decode_worker_id`
`x-prefill-instance-id`	`prefill_worker_id`

Agent Context

Подобъект agent_context передаёт пассивную идентичность сессии и trajectory для agentic-запросов. Dynamo использует эти метаданные, чтобы выводить request traces, когда включён sink agent trace. Это не влияет на маршрутизацию, планирование или поведение кэша.

Поле	Тип	Обязательно	Описание
`session_type_id`	`string`	Да	Переиспользуемый профиль или метка класса agent'а.
`session_id`	`string`	Да	Идентификатор верхнеуровневого запуска/сессии agent'а.
`trajectory_id`	`string`	Да	Одна планируемая trajectory для reasoning/tool.
`parent_trajectory_id`	`string`	Нет	Родительская trajectory, обычно для subagent'ов.

{
    "nvext": {
        "agent_context": {
            "session_type_id": "deep_research",
            "session_id": "research-run-42",
            "trajectory_id": "research-run-42:researcher",
            "parent_trajectory_id": "research-run-42:planner"
        }
    }
}

О семантике идентичности, настройке trace sink и деталях JSONL-схемы см. Agent Tracing.

Agent Hints

Подобъект agent_hints передаёт подсказки на уровне запроса, которые router использует для планирования, балансировки нагрузки и оптимизации KV cache.

Поле	Тип	По умолчанию	Описание
`priority`	`i32`	`None`	Единый приоритет запроса. Чем выше значение, тем выше приоритет на уровне Dynamo API. Используется для упорядочивания очереди router'а и планирования/вытеснения в backend.
`osl`	`u32`	`None`	Ожидаемая длина выходной последовательности (tokens). Используется для отслеживания output blocks и оценки ресурсов.
`speculative_prefill`	`bool`	`false`	Когда `true`, выполняет speculative prefill прогнозируемого prompt'а следующего хода после завершения текущего хода, чтобы прогреть KV cache.

`priority`

priority - это единственная пользовательская подсказка для планирования. Более высокие значения означают "более важный" запрос во всём Dynamo.

Когда задан --router-queue-threshold и очередь активна, запросы с более высоким приоритетом сдвигаются раньше в очереди router'а. После отправки Dynamo передаёт тот же семантический приоритет backend engine для упорядочивания очереди, preemption и вытеснения из KV cache. Dynamo внутренне нормализует полярность, зависящую от backend'а, включая соглашение vLLM, где более низкое значение означает более высокий приоритет.

{
    "nvext": {
        "agent_hints": {
            "priority": 5
        }
    }
}

`osl`

Ожидаемая длина выходной последовательности - приблизительное число выходных tokens, которое сгенерирует запрос. Router использует эту подсказку двумя способами:

Отслеживание блоков вывода: когда включён --router-track-output-blocks, router добавляет заглушки блоков во время генерации и применяет дробное затухание в зависимости от прогресса к osl.
Оценка ресурсов: помогает router'у оценивать суммарные потребности в ресурсах при принятии решений о маршрутизации.

{
    "nvext": {
        "agent_hints": {
            "osl": 1024
        }
    }
}

`speculative_prefill`

Если установлено true, система выполняет speculative prefill прогнозируемого prompt'а следующего хода после завершения текущего хода assistant'а. Это предназначено для многоходовых agentic workloads, где префикс следующего запроса предсказуем.

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

По мере потоковой передачи ответа assistant'а система накапливает полный текст ответа.
После завершения ответа фоновая задача формирует prompt следующего хода, добавляя ответ assistant'а к истории диалога (при этом thinking content удаляется для не последнего хода).
Сформированный prompt токенизируется и отправляется как запрос max_tokens=1, чтобы прогреть KV cache на worker'е.
Когда приходит фактический следующий запрос, он использует уже прогретый KV cache, что сокращает TTFT.

{
    "nvext": {
        "agent_hints": {
            "speculative_prefill": true
        }
    }
}

Детали backend'а:

SGLang: Требует --enable-priority-scheduling для упорядочивания очереди и --radix-eviction-policy priority для вытеснения на основе приоритета.
vLLM: Требует --scheduling-policy priority.
TensorRT-LLM: Пока не поддерживает приоритет на уровне отдельного запроса.

{
    "nvext": {
        "agent_hints": {
            "priority": 5
        }
    }
}

Session Control

session_control включает sticky routing по session_id. Используйте action: "bind" для sticky affinity только на уровне router'а без RPC к backend engine. Используйте action: "open" / "close" для жизненного цикла streaming-session в backend, если движок это поддерживает.

Поле	Тип	По умолчанию	Описание
`session_control.session_id`	`string`	—	Уникальный идентификатор сессии. Присутствует на каждом ходе.
`session_control.action`	`string`	omitted	Необязательное действие: `"bind"`, `"open"` или `"close"`. На промежуточных ходах не указывается.
`session_control.timeout`	`integer`	`300`	Тайм-аут неактивности в секундах. Используется с `action: "bind"` и `action: "open"`.

{
    "nvext": {
        "session_control": {
            "session_id": "subagent-1",
            "action": "open",
            "timeout": 300
        }
    }
}

Требует --router-mode=kv на frontend'е. Router-only sticky routing использует action: "bind" и не требует поддержки сессий на backend. Жизненный цикл сессии, поддерживаемый движком, требует поддержки backend; см. SGLang for Agentic Workloads для деталей настройки streaming-session в SGLang.

Расширения ответа

Когда клиент запрашивает метаданные ответа через extra_fields, ответ включает объект nvext с запрошенными полями:

Поле	Запрашивается через	Описание
`worker_id`	`extra_fields: ["worker_id"]`	ID prefill/decode worker'ов и data parallel rank'и, которые обработали запрос.
`timing`	`extra_fields: ["timing"]`	Временные показатели для каждого запроса (TTFT, ITL, время в очереди и т. д.).
`routed_experts`	`extra_fields: ["routed_experts"]`	Payload с захваченными routed experts, возвращаемый запросами на базе SGLang.
`engine_data`	`extra_fields: ["engine_data"]`	Непрозрачные метаданные engine, предоставленные backend'ом.
`stop_reason`	`extra_fields: ["stop_reason"]`	Совпавшее условие остановки, специфичное для backend'а; возвращается в `nvext`, потому что не входит в schema OpenAI completions. Сейчас Dynamo выдаёт это как поле уровня ответа для запросов с одним вариантом выбора; поддержка `n > 1` потребует индексированной формы на уровне каждого варианта.
`token_ids`	Automatic (GAIE Stage 1)	Tokenized prompt для повторного использования в режиме query-only Stage 2.

Пример ответа `nvext`

{
    "nvext": {
        "worker_id": {
            "prefill_worker_id": 1,
            "prefill_dp_rank": 0,
            "decode_worker_id": 2,
            "decode_dp_rank": 0
        },
        "timing": {
            "ttft_ms": 45.2,
            "itl_ms": 12.1
        }
    }
}

См. также

Документ	Описание
Frontend Guide	Конфигурация и интеграция KServe gRPC
Configuration and Tuning	Полная конфигурация router'а и аргументы CLI
Agent Tracing	Пассивная идентичность сессии/trajectory, JSONL-traces запросов и приём tool events в harness
Agent Hints	Подсказки serving на уровне запроса для маршрутизации, планирования и поведения кэша
SGLang for Agentic Workloads	Флаги SGLang engine для приоритетного планирования, политик вытеснения и управления сессиями

Использование​

Справочник полей​

Переопределение через заголовки​

Agent Context​

Agent Hints​

priority​

osl​

speculative_prefill​

Session Control​

Расширения ответа​

Пример ответа nvext​

См. также​