SGLang 多节点 3FSHF3FS分层 KV 缓存部署实战指南【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang导读本文基于 SGLang 仓库中 deploy_sglang_3fs_multinode.md 的官方部署流程完整讲解如何让多个节点的 SGLang 推理引擎共享同一个 3FSHF3FS分布式文件系统将其作为 L3 全局 KV 缓存HiCache 存储后端从而在跨节点场景下复用已生成的 KV Cache 页面。读完本文你将掌握从启动 3FS 元数据服务、编写 HF3FS 后端配置、双节点启动 SGLang 引擎、挂载 Router 到运行多轮multiturn基准测试的完整链路并理解背后HiCacheHF3FS存储后端、usrbio 客户端与全局元数据服务的实现原理。1. 部署架构总览在 SGLang 的分层 KV 缓存Hierarchical CacheHiCache体系中KV Cache 被组织为 GPU 显存L1、主机内存池L2与外部存储后端L3三层。HF3FS 后端让每个 rank 的 KV Cache 页面以固定大小页面page的形式写入 3FS 文件系统上的文件配合一个独立的元数据服务记录“key → 页面索引”的映射实现跨节点、跨进程的全局 KV 共享。多节点部署的核心是让多个 SGLang 引擎实例读写同一套 3FS 文件与同一份全局元数据3FS 元数据服务mini_3fs_metadata_server运行在独立节点上的 FastAPI 服务按rank:namespace管理页面分配与 key 映射是跨节点一致性的核心每个节点上的 SGLang 引擎通过环境变量SGLANG_HICACHE_HF3FS_CONFIG_PATH指向 HF3FS 后端配置文件引擎内部为每个 rank 创建多个 usrbio 客户端并发读写 3FS 文件Router将外部请求分发到各节点引擎--worker-urls指向 node1、node2 的 10000 端口多轮基准测试客户端通过 Router 施加多轮多客户端负载验证跨节点 KV 缓存命中效果。本部署方案的完整说明同时见 hf3fs/docs/README.mdk8s 3FS SGLang 的总体搭建指南与 setup_usrbio_client.mdusrbio 客户端编译与安装。2. 步骤 1启动 3FS 元数据服务多节点共享 KV 的前提是所有引擎向同一个元数据服务注册页面分配信息。官方流程首先在某个节点上以后台方式启动元数据服务nohup python3 -m sglang.srt.mem_cache.storage.hf3fs.mini_3fs_metadata_server meta.out 该模块的入口位于 mini_3fs_metadata_server.py是一个基于 FastAPI 的独立 HTTP 服务。从源码可以确认它支持以下命令行参数参数默认值说明--host0.0.0.0服务绑定地址--port18000服务端口需与 HF3FS 配置中的metadata_server_url保持一致--persistence-path无元数据持久化文件路径不指定则重启后状态丢失--save-interval60周期性将元数据落盘的时间间隔秒服务内部为每个rank配合namespace如kv、mamba、indexer维护一份RankMetadata包含空闲页面列表free_pages与key_to_index有序映射。它暴露了以下 REST 端点/{rank}/...这些端点与 storage_hf3fs.py 中Hf3fsMetadataInterface定义的元数据操作一一对应POST /{rank}/initialize初始化指定 rank 的页面总数POST /{rank}/exists批量判断 key 是否存在POST /{rank}/reserve_and_allocate_page_indices为 key 预留并分配页面索引key 已存在时直接复用POST /{rank}/confirm_write确认写入成功的 key 并回收写入失败的页面POST /{rank}/delete_keys删除 key 并释放对应页面POST /{rank}/clear清空该 rank 的全部元数据POST /{rank}/get_page_indices查询 key 对应的页面索引未命中返回null。客户端侧Hf3fsGlobalMetadataClient同一文件内实现通过带重试策略的requests.Session访问这些端点重试 3 次、退避因子 0.3、对 500/502/503/504 进行重试并维护了 256 的连接池容量以支撑高并发批量操作。注意如果服务端未开启--persistence-path元数据仅驻留内存此时重启元数据服务会导致全局 KV 索引丢失3FS 文件中的数据仍在但无法定位。生产环境建议配置持久化路径。3. 步骤 2HF3FS 配置与双节点引擎启动3.1 HF3FS 后端配置文件多节点部署要求每个节点上的引擎读取同一份 HF3FS 配置JSON 格式。官方示例路径为vim /sgl-workspace/sglang/benchmark/hf3fs/hf3fs_config.json示例内容{ file_path_prefix: /data/hicache, file_size: 1099511627776, numjobs: 16, entries: 8, metadata_server_url: http://metaServerIp:18000 }对照 storage_hf3fs.py 中HiCacheHF3FS.from_env_config()的解析逻辑各字段含义如下字段示例值是否必填说明file_path_prefix/data/hicache是3FS 文件路径前缀实际文件为{file_path_prefix}.{rank}.binMLA 模型统一使用 rank 0 的文件file_size1099511627776是单个后端文件大小字节。示例值1099511627776 1 TiB除以每页字节数即得总页数num_pages file_size // bytes_per_pagenumjobs16是并发客户端数量HiCacheHF3FS会创建numjobs个 usrbio 客户端并配套一个等大小的ThreadPoolExecutor线程池entries8是每次批量读写操作的条目数控制单次提交给 io_uring 的 I/O 数量metadata_server_urlhttp://metaServerIp:18000否多节点必须全局元数据服务地址配置后使用Hf3fsGlobalMetadataClient不配置则退化为单机Hf3fsLocalMetadataClientclient_timeout5否单次批量读写等待超时秒源码默认值 5从源码可以确认from_env_config()会检查必填键file_path_prefix、file_size、numjobs、entries是否齐全缺少任一键都会抛出ValueError。另外配置加载失败文件不存在或 JSON 解析错误会抛出带路径信息的RuntimeError。3.2 环境准备两个节点的启动命令完全一致均由三部分构成指定 HF3FS 配置文件export SGLANG_HICACHE_HF3FS_CONFIG_PATH...。该环境变量即HiCacheHF3FS.default_env_var源码中default_env_var SGLANG_HICACHE_HF3FS_CONFIG_PATH是引擎定位后端配置的唯一入口补充 usrbio 客户端动态库路径export LD_LIBRARY_PATH$LD_LIBRARY_PATH:/usr/local/lib/python3.12/dist-packages视hf3fs_py_usrbio的安装位置而定详见 setup_usrbio_client.md后台启动引擎并输出日志。3.3 node1export SGLANG_HICACHE_HF3FS_CONFIG_PATH/sgl-workspace/sglang/benchmark/hf3fs/hf3fs_config.json export LD_LIBRARY_PATH$LD_LIBRARY_PATH:/usr/local/lib/python3.12/dist-packages rm -rf instance1.out \ nohup python3 -m sglang.launch_server \ --model-path /code/models/Qwen3-32B/ \ --host 0.0.0.0 --port 10000 \ --page-size 64 \ --enable-hierarchical-cache \ --hicache-ratio 2 --hicache-size 0 \ --hicache-write-policy write_through \ --hicache-storage-backend hf3fs --tp 2 instance1.out 3.4 node2export SGLANG_HICACHE_HF3FS_CONFIG_PATH/sgl-workspace/sglang/benchmark/hf3fs/hf3fs_config.json export LD_LIBRARY_PATH$LD_LIBRARY_PATH:/usr/local/lib/python3.12/dist-packages rm -rf instance2.out \ nohup python3 -m sglang.launch_server \ --model-path /code/models/Qwen3-32B/ \ --host 0.0.0.0 --port 10000 \ --page-size 64 \ --enable-hierarchical-cache \ --hicache-ratio 2 --hicache-size 0 \ --hicache-write-policy write_through \ --hicache-storage-backend hf3fs --tp 2 instance2.out 两个节点各自以--tp 2的张量并行运行 Qwen3-32B监听各自的 10000 端口。关键 HiCache 参数默认值与含义以 memory.py 的声明为准参数本部署取值默认值含义--enable-hierarchical-cache开启关闭启用分层 KV 缓存--hicache-storage-backendhf3fs无L3 存储后端内置可选file、mooncake、hf3fs、nixl、aibrix等--hicache-ratio22.0主机 KV 内存池L2相对设备池L1的大小比例--hicache-size00显式指定主机池大小GB为 0 时回退到--hicache-ratio--hicache-write-policywrite_throughwrite_through写策略可选write_back、write_through、write_through_selective--page-size64—页面 token 数直接影响每页字节数bytes_per_page进而决定 3FS 文件的页容量两个节点必须指向同一个metadata_server_url否则各自为政无法实现跨节点 KV 命中。这也是多节点部署与单机部署不配置metadata_server_url使用Hf3fsLocalMetadataClient的本质区别单机版启动命令见 hf3fs/docs/README.md 的 “Single Node Deployment” 一节。4. 步骤 3启动 RouterRouter 负责把基准测试请求分发到两个引擎实例此时 node1、node2 上的引擎已通过 3FS 共享 KVRouter 无需感知缓存位置rm -rf router.out \ nohup python -m sglang_router.launch_router --worker-urls http://node1:10000 http://node2:10000 router.out --worker-urls后依次列出各 worker 地址。SGLang 的 Router 实现位于仓库 experimental/sgl-router 目录Rust 实现用于请求路由、负载均衡与高可用管理。5. 步骤 4启动多轮基准测试最后通过 benchmark/hicache/bench_multiturn.py 启动多轮多客户端基准测试验证跨节点 KV 共享下的端到端效果rm -rf bench_multiturn.out \ nohup python3 benchmark/hicache/bench_multiturn.py \ --model-path /code/models/Qwen3-32B \ --dataset-path /code/models/ShareGPT_V3_unfiltered_cleaned_split.json \ --port 30000 \ --request-length 2048 --num-clients 512 --num-rounds 5 --max-parallel 8 \ bench_multiturn.out 该脚本通过 Router 的 30000 端口发送请求核心参数与源码默认值对照如下参数本部署取值默认值说明--num-clients512256并发客户端数量--max-parallel8128最大并行请求数--request-length2048512每轮新请求的输入长度--output-length未指定64输出长度--num-rounds55每个客户端的对话轮数--port3000030000Router 服务端口多轮multiturn场景正是 HiCache 3FS 的价值所在后续轮次的 prompt 前缀与历史 KV Cache 可从 3FS 全局缓存中直接命中避免重复计算。脚本还支持--distribution poisson|uniform、--request-rate、--enable-round-barrier所有客户端完成第 i 轮后再发起第 i1 轮等高级参数可依据测试目标灵活调整。6. 前置条件usrbio 客户端的编译与安装引擎读写 3FS 文件依赖hf3fs_fuse的 usrbio 接口。从 hf3fs_usrbio_client.py 源码可见Hf3fsUsrBioClient通过from hf3fs_fuse.io import deregister_fd, extract_mount_point, make_ioring, make_iovec, register_fd使用用户态 io_uring 完成零拷贝批量读写若该包缺失导入时会将HF3FS_AVAILABLE置为False客户端构造时抛出ImportError。两种安装方式详见 setup_usrbio_client.md源码编译安装推荐按 Ubuntu 版本22.04 / 24.04选择对应的 clang、3FS 分支与 commitgit clone3FS 仓库、初始化子模块、应用补丁后执行python3 setup.py bdist_wheel生成 wheel 并pip install随后export LD_LIBRARY_PATH$LD_LIBRARY_PATH:/usr/local/lib/python3.12/dist-packages预编译包pip3 install hf3fs-py-usrbio。编译所需的系统依赖包括libaio-dev、libdouble-conversion-dev、libdwarf-dev、libgflags-dev、libgmock-dev、libgoogle-perftools-dev、liblz4-dev、liblzma-dev、libuv1-dev等并需要 3FS 已通过 fuse 挂载本部署中的file_path_prefix即指向该挂载点下的路径。7. 后端实现原理HiCacheHF3FS 如何工作7.1 初始化与并发模型HiCacheHF3FSstorage_hf3fs.py继承HiCacheStorage。初始化时计算num_pages file_size // bytes_per_page、gb_per_page bytes_per_page / (1 30)依据numjobs创建多个Hf3fsUsrBioClient实例或测试用的Hf3fsMockClient并用AtomicCounter轮询分配客户端创建max_workersnumjobs的ThreadPoolExecutor批量读写按entries分片提交实现高吞吐异步 I/O注册SIGINT/SIGTERM/SIGQUIT与atexit清理钩子进程退出时统一关闭客户端与线程池。7.2 批量读命中与批量写备份路径读路径先向元数据服务批量查询get_page_indices得到每个 key 的页面索引后计算文件偏移page_index * bytes_per_page按entries分片提交batch_read读满整页返回字节数等于bytes_per_page才算命中写路径先reserve_and_allocate_page_indices预留页面已存在的 key 返回(True, 已有索引)直接复用再按分片提交batch_write成功后通过confirm_write提交“key → 页面索引”映射失败的页面则归还到free_pages。整个流程与元数据服务端RankMetadata的reserve_and_allocate_page_indices/confirm_write实现严格对应。7.3 面向 MLA 模型的优化源码中针对 MLA 模型做了两项关键处理单副本备份is_mla_modelTrue时rank 非 0 的进程设置skip_backupTrue并统一使用 rank 0 的文件路径file_path {file_path_prefix}.0.bin避免 MLA 的 KV 在多 rank 间重复备份强制全局元数据MLA 模型必须配置metadata_server_url多节点部署否则from_env_config()直接抛出ValueError错误信息会指引到本文所讲解的部署文档。7.4 混合池支持若模型存在额外状态池如 Mamba / Indexerregister_mem_host_pool_v2会为每个池创建独立文件{file_path}.{pool_name}与独立namespace元数据读写走batch_get_v2/batch_set_v2并依据PoolHitPolicy.ALL_PAGES/TRAILING_PAGES计算跨池命中边界。8. 常见问题与注意事项MLA 模型必须使用全局元数据服务未配置metadata_server_url且模型为 MLA 时引擎启动即报错请确保部署文档中的元数据服务已运行且 URL 可达元数据持久化不传--persistence-path时元数据服务重启会丢失全部 key 映射建议为元数据服务配置持久化文件--persistence-path /path/to/meta.jsonmetadata_server_url缺失时的行为配置缺省时后端自动降级为Hf3fsLocalMetadataClient单机模式每 rank 内存内维护元数据仅适用于单节点部署CI 测试Hf3fsMockClienthf3fs_client.py通过普通文件读写模拟 usrbio可通过存储后端扩展配置中的use_mock_hf3fs_client开关启用用于无 3FS 环境下的单元测试环境变量是唯一配置入口引擎通过SGLANG_HICACHE_HF3FS_CONFIG_PATH定位 JSON 配置未设置时from_env_config()会回退到本地/data/hicache.{rank}.bin1 TiB、16 jobs、8 entries的默认单机配置端口规划元数据服务 18000、引擎 10000、Router 30000注意多节点环境下保证互访可达。9. 总结本文完整复现并深度解读了 SGLang 3FS 的多节点部署四步法启动全局元数据服务 → 编写 HF3FS 后端配置并双节点启动引擎 → 挂载 Router → 运行多轮基准测试。通过SGLANG_HICACHE_HF3FS_CONFIG_PATH环境变量、--hicache-storage-backend hf3fs以及metadata_server_url的组合多节点引擎得以共享同一份 3FS KV 缓存让多轮对话与重复前缀请求获得跨节点缓存命中收益。更底层的批量读写、页面分配、MLA 单副本优化等机制均可直接阅读仓库源码 storage_hf3fs.py、mini_3fs_metadata_server.py 与 hf3fs_usrbio_client.py 进一步验证。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
SGLang 多节点 3FS（HF3FS）分层 KV 缓存部署实战指南
SGLang 多节点 3FSHF3FS分层 KV 缓存部署实战指南【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang导读本文基于 SGLang 仓库中 deploy_sglang_3fs_multinode.md 的官方部署流程完整讲解如何让多个节点的 SGLang 推理引擎共享同一个 3FSHF3FS分布式文件系统将其作为 L3 全局 KV 缓存HiCache 存储后端从而在跨节点场景下复用已生成的 KV Cache 页面。读完本文你将掌握从启动 3FS 元数据服务、编写 HF3FS 后端配置、双节点启动 SGLang 引擎、挂载 Router 到运行多轮multiturn基准测试的完整链路并理解背后HiCacheHF3FS存储后端、usrbio 客户端与全局元数据服务的实现原理。1. 部署架构总览在 SGLang 的分层 KV 缓存Hierarchical CacheHiCache体系中KV Cache 被组织为 GPU 显存L1、主机内存池L2与外部存储后端L3三层。HF3FS 后端让每个 rank 的 KV Cache 页面以固定大小页面page的形式写入 3FS 文件系统上的文件配合一个独立的元数据服务记录“key → 页面索引”的映射实现跨节点、跨进程的全局 KV 共享。多节点部署的核心是让多个 SGLang 引擎实例读写同一套 3FS 文件与同一份全局元数据3FS 元数据服务mini_3fs_metadata_server运行在独立节点上的 FastAPI 服务按rank:namespace管理页面分配与 key 映射是跨节点一致性的核心每个节点上的 SGLang 引擎通过环境变量SGLANG_HICACHE_HF3FS_CONFIG_PATH指向 HF3FS 后端配置文件引擎内部为每个 rank 创建多个 usrbio 客户端并发读写 3FS 文件Router将外部请求分发到各节点引擎--worker-urls指向 node1、node2 的 10000 端口多轮基准测试客户端通过 Router 施加多轮多客户端负载验证跨节点 KV 缓存命中效果。本部署方案的完整说明同时见 hf3fs/docs/README.mdk8s 3FS SGLang 的总体搭建指南与 setup_usrbio_client.mdusrbio 客户端编译与安装。2. 步骤 1启动 3FS 元数据服务多节点共享 KV 的前提是所有引擎向同一个元数据服务注册页面分配信息。官方流程首先在某个节点上以后台方式启动元数据服务nohup python3 -m sglang.srt.mem_cache.storage.hf3fs.mini_3fs_metadata_server meta.out 该模块的入口位于 mini_3fs_metadata_server.py是一个基于 FastAPI 的独立 HTTP 服务。从源码可以确认它支持以下命令行参数参数默认值说明--host0.0.0.0服务绑定地址--port18000服务端口需与 HF3FS 配置中的metadata_server_url保持一致--persistence-path无元数据持久化文件路径不指定则重启后状态丢失--save-interval60周期性将元数据落盘的时间间隔秒服务内部为每个rank配合namespace如kv、mamba、indexer维护一份RankMetadata包含空闲页面列表free_pages与key_to_index有序映射。它暴露了以下 REST 端点/{rank}/...这些端点与 storage_hf3fs.py 中Hf3fsMetadataInterface定义的元数据操作一一对应POST /{rank}/initialize初始化指定 rank 的页面总数POST /{rank}/exists批量判断 key 是否存在POST /{rank}/reserve_and_allocate_page_indices为 key 预留并分配页面索引key 已存在时直接复用POST /{rank}/confirm_write确认写入成功的 key 并回收写入失败的页面POST /{rank}/delete_keys删除 key 并释放对应页面POST /{rank}/clear清空该 rank 的全部元数据POST /{rank}/get_page_indices查询 key 对应的页面索引未命中返回null。客户端侧Hf3fsGlobalMetadataClient同一文件内实现通过带重试策略的requests.Session访问这些端点重试 3 次、退避因子 0.3、对 500/502/503/504 进行重试并维护了 256 的连接池容量以支撑高并发批量操作。注意如果服务端未开启--persistence-path元数据仅驻留内存此时重启元数据服务会导致全局 KV 索引丢失3FS 文件中的数据仍在但无法定位。生产环境建议配置持久化路径。3. 步骤 2HF3FS 配置与双节点引擎启动3.1 HF3FS 后端配置文件多节点部署要求每个节点上的引擎读取同一份 HF3FS 配置JSON 格式。官方示例路径为vim /sgl-workspace/sglang/benchmark/hf3fs/hf3fs_config.json示例内容{ file_path_prefix: /data/hicache, file_size: 1099511627776, numjobs: 16, entries: 8, metadata_server_url: http://metaServerIp:18000 }对照 storage_hf3fs.py 中HiCacheHF3FS.from_env_config()的解析逻辑各字段含义如下字段示例值是否必填说明file_path_prefix/data/hicache是3FS 文件路径前缀实际文件为{file_path_prefix}.{rank}.binMLA 模型统一使用 rank 0 的文件file_size1099511627776是单个后端文件大小字节。示例值1099511627776 1 TiB除以每页字节数即得总页数num_pages file_size // bytes_per_pagenumjobs16是并发客户端数量HiCacheHF3FS会创建numjobs个 usrbio 客户端并配套一个等大小的ThreadPoolExecutor线程池entries8是每次批量读写操作的条目数控制单次提交给 io_uring 的 I/O 数量metadata_server_urlhttp://metaServerIp:18000否多节点必须全局元数据服务地址配置后使用Hf3fsGlobalMetadataClient不配置则退化为单机Hf3fsLocalMetadataClientclient_timeout5否单次批量读写等待超时秒源码默认值 5从源码可以确认from_env_config()会检查必填键file_path_prefix、file_size、numjobs、entries是否齐全缺少任一键都会抛出ValueError。另外配置加载失败文件不存在或 JSON 解析错误会抛出带路径信息的RuntimeError。3.2 环境准备两个节点的启动命令完全一致均由三部分构成指定 HF3FS 配置文件export SGLANG_HICACHE_HF3FS_CONFIG_PATH...。该环境变量即HiCacheHF3FS.default_env_var源码中default_env_var SGLANG_HICACHE_HF3FS_CONFIG_PATH是引擎定位后端配置的唯一入口补充 usrbio 客户端动态库路径export LD_LIBRARY_PATH$LD_LIBRARY_PATH:/usr/local/lib/python3.12/dist-packages视hf3fs_py_usrbio的安装位置而定详见 setup_usrbio_client.md后台启动引擎并输出日志。3.3 node1export SGLANG_HICACHE_HF3FS_CONFIG_PATH/sgl-workspace/sglang/benchmark/hf3fs/hf3fs_config.json export LD_LIBRARY_PATH$LD_LIBRARY_PATH:/usr/local/lib/python3.12/dist-packages rm -rf instance1.out \ nohup python3 -m sglang.launch_server \ --model-path /code/models/Qwen3-32B/ \ --host 0.0.0.0 --port 10000 \ --page-size 64 \ --enable-hierarchical-cache \ --hicache-ratio 2 --hicache-size 0 \ --hicache-write-policy write_through \ --hicache-storage-backend hf3fs --tp 2 instance1.out 3.4 node2export SGLANG_HICACHE_HF3FS_CONFIG_PATH/sgl-workspace/sglang/benchmark/hf3fs/hf3fs_config.json export LD_LIBRARY_PATH$LD_LIBRARY_PATH:/usr/local/lib/python3.12/dist-packages rm -rf instance2.out \ nohup python3 -m sglang.launch_server \ --model-path /code/models/Qwen3-32B/ \ --host 0.0.0.0 --port 10000 \ --page-size 64 \ --enable-hierarchical-cache \ --hicache-ratio 2 --hicache-size 0 \ --hicache-write-policy write_through \ --hicache-storage-backend hf3fs --tp 2 instance2.out 两个节点各自以--tp 2的张量并行运行 Qwen3-32B监听各自的 10000 端口。关键 HiCache 参数默认值与含义以 memory.py 的声明为准参数本部署取值默认值含义--enable-hierarchical-cache开启关闭启用分层 KV 缓存--hicache-storage-backendhf3fs无L3 存储后端内置可选file、mooncake、hf3fs、nixl、aibrix等--hicache-ratio22.0主机 KV 内存池L2相对设备池L1的大小比例--hicache-size00显式指定主机池大小GB为 0 时回退到--hicache-ratio--hicache-write-policywrite_throughwrite_through写策略可选write_back、write_through、write_through_selective--page-size64—页面 token 数直接影响每页字节数bytes_per_page进而决定 3FS 文件的页容量两个节点必须指向同一个metadata_server_url否则各自为政无法实现跨节点 KV 命中。这也是多节点部署与单机部署不配置metadata_server_url使用Hf3fsLocalMetadataClient的本质区别单机版启动命令见 hf3fs/docs/README.md 的 “Single Node Deployment” 一节。4. 步骤 3启动 RouterRouter 负责把基准测试请求分发到两个引擎实例此时 node1、node2 上的引擎已通过 3FS 共享 KVRouter 无需感知缓存位置rm -rf router.out \ nohup python -m sglang_router.launch_router --worker-urls http://node1:10000 http://node2:10000 router.out --worker-urls后依次列出各 worker 地址。SGLang 的 Router 实现位于仓库 experimental/sgl-router 目录Rust 实现用于请求路由、负载均衡与高可用管理。5. 步骤 4启动多轮基准测试最后通过 benchmark/hicache/bench_multiturn.py 启动多轮多客户端基准测试验证跨节点 KV 共享下的端到端效果rm -rf bench_multiturn.out \ nohup python3 benchmark/hicache/bench_multiturn.py \ --model-path /code/models/Qwen3-32B \ --dataset-path /code/models/ShareGPT_V3_unfiltered_cleaned_split.json \ --port 30000 \ --request-length 2048 --num-clients 512 --num-rounds 5 --max-parallel 8 \ bench_multiturn.out 该脚本通过 Router 的 30000 端口发送请求核心参数与源码默认值对照如下参数本部署取值默认值说明--num-clients512256并发客户端数量--max-parallel8128最大并行请求数--request-length2048512每轮新请求的输入长度--output-length未指定64输出长度--num-rounds55每个客户端的对话轮数--port3000030000Router 服务端口多轮multiturn场景正是 HiCache 3FS 的价值所在后续轮次的 prompt 前缀与历史 KV Cache 可从 3FS 全局缓存中直接命中避免重复计算。脚本还支持--distribution poisson|uniform、--request-rate、--enable-round-barrier所有客户端完成第 i 轮后再发起第 i1 轮等高级参数可依据测试目标灵活调整。6. 前置条件usrbio 客户端的编译与安装引擎读写 3FS 文件依赖hf3fs_fuse的 usrbio 接口。从 hf3fs_usrbio_client.py 源码可见Hf3fsUsrBioClient通过from hf3fs_fuse.io import deregister_fd, extract_mount_point, make_ioring, make_iovec, register_fd使用用户态 io_uring 完成零拷贝批量读写若该包缺失导入时会将HF3FS_AVAILABLE置为False客户端构造时抛出ImportError。两种安装方式详见 setup_usrbio_client.md源码编译安装推荐按 Ubuntu 版本22.04 / 24.04选择对应的 clang、3FS 分支与 commitgit clone3FS 仓库、初始化子模块、应用补丁后执行python3 setup.py bdist_wheel生成 wheel 并pip install随后export LD_LIBRARY_PATH$LD_LIBRARY_PATH:/usr/local/lib/python3.12/dist-packages预编译包pip3 install hf3fs-py-usrbio。编译所需的系统依赖包括libaio-dev、libdouble-conversion-dev、libdwarf-dev、libgflags-dev、libgmock-dev、libgoogle-perftools-dev、liblz4-dev、liblzma-dev、libuv1-dev等并需要 3FS 已通过 fuse 挂载本部署中的file_path_prefix即指向该挂载点下的路径。7. 后端实现原理HiCacheHF3FS 如何工作7.1 初始化与并发模型HiCacheHF3FSstorage_hf3fs.py继承HiCacheStorage。初始化时计算num_pages file_size // bytes_per_page、gb_per_page bytes_per_page / (1 30)依据numjobs创建多个Hf3fsUsrBioClient实例或测试用的Hf3fsMockClient并用AtomicCounter轮询分配客户端创建max_workersnumjobs的ThreadPoolExecutor批量读写按entries分片提交实现高吞吐异步 I/O注册SIGINT/SIGTERM/SIGQUIT与atexit清理钩子进程退出时统一关闭客户端与线程池。7.2 批量读命中与批量写备份路径读路径先向元数据服务批量查询get_page_indices得到每个 key 的页面索引后计算文件偏移page_index * bytes_per_page按entries分片提交batch_read读满整页返回字节数等于bytes_per_page才算命中写路径先reserve_and_allocate_page_indices预留页面已存在的 key 返回(True, 已有索引)直接复用再按分片提交batch_write成功后通过confirm_write提交“key → 页面索引”映射失败的页面则归还到free_pages。整个流程与元数据服务端RankMetadata的reserve_and_allocate_page_indices/confirm_write实现严格对应。7.3 面向 MLA 模型的优化源码中针对 MLA 模型做了两项关键处理单副本备份is_mla_modelTrue时rank 非 0 的进程设置skip_backupTrue并统一使用 rank 0 的文件路径file_path {file_path_prefix}.0.bin避免 MLA 的 KV 在多 rank 间重复备份强制全局元数据MLA 模型必须配置metadata_server_url多节点部署否则from_env_config()直接抛出ValueError错误信息会指引到本文所讲解的部署文档。7.4 混合池支持若模型存在额外状态池如 Mamba / Indexerregister_mem_host_pool_v2会为每个池创建独立文件{file_path}.{pool_name}与独立namespace元数据读写走batch_get_v2/batch_set_v2并依据PoolHitPolicy.ALL_PAGES/TRAILING_PAGES计算跨池命中边界。8. 常见问题与注意事项MLA 模型必须使用全局元数据服务未配置metadata_server_url且模型为 MLA 时引擎启动即报错请确保部署文档中的元数据服务已运行且 URL 可达元数据持久化不传--persistence-path时元数据服务重启会丢失全部 key 映射建议为元数据服务配置持久化文件--persistence-path /path/to/meta.jsonmetadata_server_url缺失时的行为配置缺省时后端自动降级为Hf3fsLocalMetadataClient单机模式每 rank 内存内维护元数据仅适用于单节点部署CI 测试Hf3fsMockClienthf3fs_client.py通过普通文件读写模拟 usrbio可通过存储后端扩展配置中的use_mock_hf3fs_client开关启用用于无 3FS 环境下的单元测试环境变量是唯一配置入口引擎通过SGLANG_HICACHE_HF3FS_CONFIG_PATH定位 JSON 配置未设置时from_env_config()会回退到本地/data/hicache.{rank}.bin1 TiB、16 jobs、8 entries的默认单机配置端口规划元数据服务 18000、引擎 10000、Router 30000注意多节点环境下保证互访可达。9. 总结本文完整复现并深度解读了 SGLang 3FS 的多节点部署四步法启动全局元数据服务 → 编写 HF3FS 后端配置并双节点启动引擎 → 挂载 Router → 运行多轮基准测试。通过SGLANG_HICACHE_HF3FS_CONFIG_PATH环境变量、--hicache-storage-backend hf3fs以及metadata_server_url的组合多节点引擎得以共享同一份 3FS KV 缓存让多轮对话与重复前缀请求获得跨节点缓存命中收益。更底层的批量读写、页面分配、MLA 单副本优化等机制均可直接阅读仓库源码 storage_hf3fs.py、mini_3fs_metadata_server.py 与 hf3fs_usrbio_client.py 进一步验证。【免费下载链接】sglangSGLang is a high-performance serving framework for large language models and multimodal models.项目地址: https://gitcode.com/GitHub_Trending/sg/sglang创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考