# SGLang HiCache: перенос KV-кеша между GPU и RAM

Источник: https://modelium.tech/zhurnal/sglang-hicache/

HiCache расширяет кеш префиксов SGLang: L1 хранит KV в памяти GPU, L2 — в оперативной памяти конкретного инстанса, а необязательный L3 — во внешнем хранилище. Начните с одного локального инстанса, выбранной модели и повторяющегося длинного префикса; проверьте успешные ответы, попадания и задержку в контролируемых сериях. Больший кеш не гарантирует ускорения, а L2 нельзя разделить между инстансами.

**Источник: официальные документы SGLang на Git-коммите **`**f385390**`** от 5 октября 2026 года; проверено 5 октября.** Ниже — план локального теста, не свидетельство запущенного сервера или измеренной экономии Modelium. Повторите проверку аргументов на своей версии. [s3](#src-s3) [s7](#src-s7)

## Когда нужен HiCache, а когда достаточно RadixCache?

Если несколько запросов к одной модели повторяют длинную инструкцию, документ или историю, SGLang может повторно использовать KV-состояние общего токенного префикса вместо пересчёта его prefill. Базовый RadixCache удерживает полезные префиксы в GPU; HiCache добавляет host DRAM и, при настройке отдельного backend, внешнее хранилище. Кешируется не готовый ответ и не любой похожий текст, а совместимая последовательность токенов после шаблона модели. [s1](#src-s1) [s5](#src-s5)

Маршрут для пилота: **повторяющаяся инструкция → конкретная совместимая модель (например, **`**qwen/qwen2.5-0.5b-instruct**`** из примера SGLang) → GPU и резерв доступной host DRAM → локальный SGLang → три серии запросов → сверка ответов и задержки**. Пример модели в документации показывает API, но не доказывает, что именно она подходит вашему длинному документу или помещается на вашем устройстве. До HiCache проверьте обычный ответ по [базовому гайду SGLang](/zhurnal/sglang/). [s5](#src-s5) [s3](#src-s3)

HiCache стоит рассматривать при реально повторяющихся больших префиксах и вытеснении их из L1. Если префикс меняется в начале, L2 не создаст повторного KV из ничего; если всё помещается в L1, дополнительный перенос через RAM может быть бесполезным. Это критерий для собственного сравнения, а не универсальное обещание ускорения. [s1](#src-s1)

## Какие уровни можно разделить между запросами и серверами?

**L1** — GPU-пул одного инстанса. **L2** — CPU DRAM *того же инстанса*: два процесса SGLang на одной машине не объединяют этот пул; тем более это не общая RAM нескольких машин. **L3** появляется при конфигурации `--hicache-storage-backend`; он может быть общим только если выбранный backend и namespace настроены для совместного доступа. Для `file` стандартное хранилище `/tmp/hicache` узловое, если каталог не является общим mount; удалённые backends требуют отдельной настройки. Не называйте добавление `--hicache-ratio` кластерным кешем. [s1](#src-s1) [s2](#src-s2)

`--hicache-ratio` задаёт отношение **host KV pool к device KV pool**; значение по умолчанию в закреплённых аргументах — `2.0`. `--hicache-size` в гигабайтах переопределяет ratio и выделяется **на каждый rank**; его нельзя читать как объём весов или точное системное требование памяти. Убедитесь, что host DRAM остаётся под ОС, модель и остальные процессы, и оцените бюджет именно для вашей конфигурации TP. Документация требует размер host KV-пула больше device KV-пула; маленькое произвольное число для `--hicache-size` не является безопасным шаблоном. [s1](#src-s1) [s3](#src-s3)

## Как подготовить одноинстансовый тест GPU ↔ RAM?

- На изолированном стенде с выбранной совместимой моделью сначала получите обычный ответ через native `POST /generate`, затем проверьте справку установленной версии `python3 -m sglang.launch_server --help`. Официальный пример native API использует `qwen/qwen2.5-0.5b-instruct`; в собственном окружении закрепите реальную ревизию модели и убедитесь, что веса доступны. Не подменяйте проверку API текстом из документации. [s5](#src-s5) [s3](#src-s3)

- Для L2 включите `--enable-hierarchical-cache` при запуске и подберите `--hicache-ratio` после оценки GPU KV pool и свободной RAM. В закреплённой документации флаг выключен по умолчанию, ratio имеет значение `2.0`; `--hicache-size` остаётся `0`, пока не нужен явный абсолютный бюджет. Для наблюдения включите `--enable-metrics`. Не добавляйте storage backend: этот тест проверяет **частный L2 одного инстанса**, не L3. [s3](#src-s3) [s1](#src-s1)

- Для примера запуска без копирования неподтверждённых весов используйте шаблон аргументов в строку: `python3 -m sglang.launch_server --model-path <проверенный_путь_к_модели> --host 127.0.0.1 --port 30000 --enable-hierarchical-cache --hicache-ratio 2 --enable-metrics`. Замените путь реальным и убедитесь, что ваша сборка поддерживает эти флаги; `127.0.0.1` оставляет тестовый HTTP-сервер на loopback, но не доказывает отсутствия любых других сетевых вызовов процесса. Проверка совместимости GPU/backend и фактической RAM — обязанность оператора. [s3](#src-s3) [s5](#src-s5)

- Зафиксируйте модель, её ревизию, tokenizer/chat template, GPU и CPU/RAM, SGLang commit/версию, число ranks, доступный KV-пул, размер длинного неизменного префикса, параметры генерации, число параллельных клиентов и политику записи. В HiCache по умолчанию указан `write_through`; варианты `write_back` и `write_through_selective` меняют момент переноса. Не меняйте настройки между контрольными сериями. [s1](#src-s1) [s3](#src-s3)

Это шаблон для лабораторного стенда, а не команда, исполненная Modelium. Если память закончилась при старте, не делайте вывод о «минимальной VRAM по размеру весов»: уберите явный размер host-пула, оцените общий бюджет и перейдите к меньшей модели или другой настройке после проверки своей конфигурации. [s1](#src-s1) [s3](#src-s3)

## Как доказать, что произошло чтение из L2, а не GPU-hit?

Проведите сначала серию **А** с одним длинным синтетическим префиксом и известным вопросом, сохраните полный ответ и метрики. Серия **Б** повторяет тот же префикс с новым вопросом и той же моделью: сравните успешность ответа, число использованных токенов, TTFT (время до первого токена) и общую частоту попаданий. Это прежде всего проверяет повторное использование, **не** доказывает перенос через L2. В `/metrics` документация приводит `sglang:cache_hit_rate` и `sglang:time_to_first_token_seconds`; примерные значения из документации не считаются результатом вашего стенда. [s4](#src-s4) [s1](#src-s1)

Для серии **В** добейтесь вытеснения *только неиспользуемого* тестового префикса из L1 другими синтетическими префиксами, сохраняя сервер и L2 активными, затем повторите А. Нужно отдельно подтвердить в телеметрии или трассировке конкретной версии, что L1 уже не содержит нужные блоки, L2 содержит их и при повторе произошло чтение L2→L1. Само снижение TTFT, общий `cache_hit_rate` или успешный ответ не локализуют уровень попадания. При отсутствии такой наблюдаемости формулируйте вывод как «совместимо с reuse», а не «RAM offload доказан». Сопоставьте контрольный прогон без HiCache при той же нагрузке, не очищая кеш посреди работающих запросов. Это **предложенный протокол** на основе схемы L1/L2, не проведённый эксперимент. [s1](#src-s1) [s4](#src-s4)

Проверьте ещё качество: сравните ответы с эталонными вопросами по тестовому документу и ошибки, а не только скорость. Зафиксируйте количество прогретых запросов, распределение задержки и общую память системы до/после. Если ждать загрузки из L2 дороже нового prefill для вашей короткой инструкции, откажитесь от настройки: полезность зависит от нагрузки. Ни один результат нельзя переносить на другой размер модели или иной GPU автоматически. [s1](#src-s1) [s4](#src-s4)

## Когда подключать L3 и какие у него риски?

L3 — отдельная задача кластерного или внешнего хранения. Документация перечисляет `file`, `mooncake`, `hf3fs`, `nixl`, `aibrix`; общий доступ требует совместимого backend, layout и namespace. `page_first` подходит для `kernel` I/O, а с `direct` документация описывает переход на `layer_first`; `page_first_direct` рассчитан на прямой перенос. Не переносите параметры многосерверного примера с `--tp 8`, RDMA и большими моделями на одиночную машину как обязательные требования HiCache. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3)

При использовании L3 выберите политику предварительного чтения: `best_effort`, `wait_complete` или `timeout`. Последняя стоит по умолчанию в закреплённых аргументах; ожидание полного prefetch может увеличить задержку конкретного запроса. Снова замерьте TTFT и успешные ответы на собственной нагрузке; обещания ускорения из примеров разработчика не являются воспроизведённым бенчмарком Modelium. [s1](#src-s1) [s2](#src-s2) [s3](#src-s3)

Storage backend можно присоединить или отсоединить административным HTTP API без перезапуска, **только когда нет активных и ожидающих запросов**; иначе операция отклоняется. При нескольких DP ranks общий ответ может быть ошибкой, хотя часть ranks уже изменила состояние, и автоматического отката частичного успеха нет. Не пробуйте эту операцию на рабочей очереди; изолируйте admin endpoints, опустошите трафик и сверяйте состояние каждого инстанса. Эта возможность относится к L3, а не к автоматическому объединению L2. [s6](#src-s6) [s1](#src-s1)

**Следующий шаг:** откройте [гайд по метрикам SGLang](/zhurnal/sglang-metrics-prometheus/) и сохраните ответы и показатели А/Б/В на своём локальном стенде. Если L2-read нельзя подтвердить трассировкой вашей сборки, оставьте гипотезу открытой; не публикуйте «рост скорости» или «экономию памяти» без измерений и условий. [s4](#src-s4) [s1](#src-s1)

## Источники

1. [SGLang HiCache: system design and tier sharing](https://github.com/sgl-project/sglang/blob/f385390be593575cda74cda06bc3a82591d52b18/docs/docs/advanced_features/hicache_design.mdx) — получено 2026-10-05
2. [SGLang HiCache best practices](https://github.com/sgl-project/sglang/blob/f385390be593575cda74cda06bc3a82591d52b18/docs/docs/advanced_features/hicache_best_practices.mdx) — получено 2026-10-05
3. [SGLang server arguments](https://github.com/sgl-project/sglang/blob/f385390be593575cda74cda06bc3a82591d52b18/docs/docs/advanced_features/server_arguments.mdx) — получено 2026-10-05
4. [SGLang production metrics](https://github.com/sgl-project/sglang/blob/f385390be593575cda74cda06bc3a82591d52b18/docs/docs/references/production_metrics.mdx) — получено 2026-10-05
5. [SGLang native API and model example](https://github.com/sgl-project/sglang/blob/f385390be593575cda74cda06bc3a82591d52b18/docs/docs/basic_usage/native_api.mdx) — получено 2026-10-05
6. [SGLang HiCache storage backend runtime attach/detach](https://github.com/sgl-project/sglang/blob/f385390be593575cda74cda06bc3a82591d52b18/docs/docs/advanced_features/hicache_storage_runtime_attach_detach.mdx) — получено 2026-10-05
7. [SGLang hierarchical KV caching documentation index](https://github.com/sgl-project/sglang/blob/f385390be593575cda74cda06bc3a82591d52b18/docs/docs/advanced_features/hicache.mdx) — получено 2026-10-05