LMDeploy Request Distributor Server（Proxy）完全指南：部署、节点管理与路由策略

人工智能大模型模型推理服务推理引擎本地部署模型量化【免费下载链接】lmdeployLMDeploy is a toolkit for compressing, deploying, and serving LLMs.项目地址https://gitcode.com/gh_mirrors/lm/lmdeploy点击查看免费下载LMDeploy 的 Request Distributor Server请求分发服务即 Proxy位于 docs/en/llm/proxy_server.md 所述的核心能力之上它把多个api_server服务横向并行化对外暴露一个统一入口内部自动完成请求分发与负载均衡。读完本文你将掌握 Proxy 的完整启动参数、--proxy-url注册机制、curl/Python 两种节点管理方式以及 Hybrid / DistServe 两种服务策略与 random / min_expected_latency / min_observed_latency 三种路由策略的底层实现原理能够直接搭建一套多节点推理集群。一、Proxy 是什么请求分发服务的定位与设计请求分发服务Request Distributor Server的核心作用是并行化多个api_server服务。用户只需要访问一个统一的 Proxy URL就可以间接访问背后挂载的多个api_server服务节点Proxy 在内部自动进行请求分发实现负载均衡。从仓库源码可以确认其技术实现核心代码位于 lmdeploy/serve/proxy/proxy.py它基于 FastAPI 构建 HTTP 服务第 463 行app FastAPI(docs_url/)即根路径/直接暴露 Swagger UI使用aiohttp异步转发请求并通过NodeManager统一管理所有下游节点。其数据模型定义如下proxy.pyStatus描述单个节点的状态包含role服务角色、models该节点承载的模型列表、unfinished当前未完成请求数、latency最近请求的延迟队列、speed吞吐能力指标可为 RPM 等。Node由url和status组成的节点描述。启动成功后脚本会打印 Proxy 服务的 URL浏览器访问该地址即可打开 Swagger UI 交互式文档。二、启动 Proxy 服务2.1 启动命令与参数详解启动 Proxy 的标准命令如下lmdeploy serve proxy --server-name {server_name} --server-port {server_port} --routing-strategy min_expected_latency --serving-strategy Hybrid对应 CLI 解析器定义在 lmdeploy/cli/serve.py 的add_parser_proxy()中各参数说明如下参数默认值可选值说明--server-name0.0.0.0任意 hostProxy 服务的监听地址--server-port8000任意端口Proxy 服务的监听端口--serving-strategyHybridHybrid、DistServe服务策略Hybrid 表示 Prefill 与 Decode 工作负载共存于同一引擎DistServe 表示 Prefill-Decode 分离部署--dummy-prefillFalsestore_true—启用 dummy prefill用于性能剖析profiler场景--routing-strategymin_expected_latencyrandom、min_expected_latency、min_observed_latency请求分发到节点时的路由策略--disable-cache-statusFalsestore_true—禁用状态缓存若设置Proxy 将遗忘上一次的节点状态--migration-protocolRDMARDMA、NVLINKDistServe 模式下 KV Cache 迁移使用的传输协议--link-typeRoCERoCE、IBRDMA 链路类型--disable-gdrFalsestore_true—是否禁用 GPU Direct Memory Access--api-keysNone字符串或列表设置 API Key 鉴权不设置则无鉴权--sslFalse—启用 SSL需要环境变量SSL_KEYFILE和SSL_CERTFILE--log-levelINFO日志级别设置日志级别这些参数最终被传入 proxy.py 中的proxy()函数并作用于全局node_manager实例第 471 行创建。需要特别说明的两个细节状态缓存机制默认情况下cache_statusTrue节点信息会被写入proxy_config.json位于lmdeploy/serve/proxy/目录重启 Proxy 后可以自动恢复之前的节点注册信息通过--disable-cache-status可关闭该行为。心跳管理Proxy 启动时会拉起一个心跳守护线程proxy.py通过环境变量LMDEPLOY_CONTROLLER_HEART_BEAT_EXPIRATION默认 90 秒控制检查周期定期调用remove_stale_nodes_by_expiration()探测各节点的/health接口剔除失联节点。2.2 将 api_server 注册到 Proxy启动 Proxy 后用户需要在启动api_server时通过--proxy-url参数将其注册到 Proxy 上例如lmdeploy serve api_server InternLM/internlm2-chat-1_8b --proxy-url http://0.0.0.0:8000从源码看--proxy-url参数定义于 lmdeploy/cli/serve.py在 api_server.py 的register_to_proxy()函数中api_server 启动后会向{proxy_url}/nodes/add发送 POST 请求完成自动注册注册数据包含urlapi_server 自身的访问地址status.models该节点承载的模型列表status.role节点角色Hybrid / Prefill / Decode。这样用户就可以通过 Proxy 节点访问所有api_server的服务。Proxy 的用法与 api_server 完全一致均兼容 OpenAI 格式包括以下接口/v1/models查看全部可用模型/v1/chat/completions对话补全/v1/completions文本补全。这些接口的实现同样位于 proxy.py请求到达后由NodeManager依据路由策略选择目标节点并异步转发。三、节点管理通过 Swagger UI 可以看到多个管理 API。与 api_server 节点管理相关的接口包括/nodes/status查看所有 api_server 服务节点/nodes/add添加某个节点/nodes/remove删除某个节点。其后端实现分别对应 proxy.py 中的node_status()、add_node()、remove_node()三个 FastAPI 路由最终由NodeManager.add()/NodeManager.remove()完成实际的注册与摘除逻辑。此外Proxy 还额外提供/nodes/terminate终止单个节点和/nodes/terminate_all终止全部节点两个管理接口。3.1 通过 curl 管理节点查看所有节点状态curl -X GET \ http://localhost:8000/nodes/status \ -H accept: application/json添加一个新节点curl -X POST \ http://localhost:8000/nodes/add \ -H accept: application/json \ -H Content-Type: application/json \ -d { url: http://0.0.0.0:23333 }删除一个节点curl -X POST \ http://localhost:8000/nodes/remove?node_urlhttp://0.0.0.0:23333 \ -H accept: application/json \ -d 从 proxy.py 的add_node()文档 可以看到添加节点时除了url字段还可以通过status字段显式声明节点能力例如{models: [intern-s2-preview], speed: 1}其中speed可以是 RPM 等吞吐指标且所有节点的 speed 必须使用同一度量单位否则路由权重将失去可比性。3.2 通过 Python 管理节点查看所有节点# query all nodes import requests url http://localhost:8000/nodes/status headers {accept: application/json} response requests.get(url, headersheaders) print(response.text)添加一个新节点# add a new node import requests url http://localhost:8000/nodes/add headers { accept: application/json, Content-Type: application/json } data {url: http://0.0.0.0:23333} response requests.post(url, headersheaders, jsondata) print(response.text)删除一个节点# delete a node import requests url http://localhost:8000/nodes/remove headers {accept: application/json,} params {node_url: http://0.0.0.0:23333,} response requests.post(url, headersheaders, data, paramsparams) print(response.text)值得补充的是NodeManager.add()proxy.py在收到节点 URL 后如果status为空会自动通过APIClient拉取该节点的available_models来补全模型信息若节点不可达则返回 API 超时错误码。而remove()在摘除节点的同时还会调用pd_connection_pool.dereg_instance()注销对应的分布式连接保证在 DistServe 模式下不会残留失效连接。四、服务策略Serving StrategyLMDeploy 当前支持两种服务策略其枚举定义见 lmdeploy/pytorch/disagg/config.pyHybrid不区分 Prefill 与 Decoding 实例Prefill 和 Decode 工作负载共存于同一个引擎中遵循传统推理部署模式。这是默认策略一个节点就是一个完整的推理服务。DistServe将 Prefill 和 Decoding 实例分离部署在不同的服务节点上从而实现更灵活、更高效的资源调度和可扩展性。Prefill 引擎完成预填充阶段后KV Cache 会从 Prefill 引擎迁移到 Decode 引擎config.py 的注释明确描述了这一过程。在 DistServe 模式下请求的处理流程发生了本质变化。从 proxy.py 的/v1/chat/completions实现 可以看到完整调用链Prefill 阶段Proxy 将原始请求复制一份强制设置max_tokens1、streamFalse、with_cacheTrue、preserve_cacheTrue通过get_node_url(request.model, EngineRole.Prefill)选择 Prefill 节点执行预填充仅生成 1 个 token 并保留 KV Cache连接建立若 Prefill 与 Decode 节点之间尚未建立连接则通过pd_connection_pool.connect()按migration_protocol默认 RDMA建立 KV 迁移通道Decode 阶段Proxy 将 Prefill 阶段产生的remote_session_id、remote_block_ids、remote_token_id等封装进MigrationRequest选择 Decode 节点继续生成剩余 token并以流式streamTrue或非流式方式把结果返回给客户端。该场景的完整部署示例可参考 lmdeploy/pytorch/disagg/README.md先启动带--serving-strategy DistServe的 Proxy再分别以--role Prefill和--role Decode启动两个 api_server 并通过--proxy-url注册。目前仅Pytorch backend支持 PD Disaggregation。DistServe 模式下/v1/chat/completions不支持n 1的多次生成proxy.py 会直接返回 400 错误。五、路由策略Dispatch Strategy / Routing StrategyProxy 服务的当前分发策略共有三种枚举与字符串映射定义在 lmdeploy/serve/proxy/utils.py 的RoutingStrategy中具体调度逻辑实现在NodeManager.get_node_url()proxy.py5.1 random按吞吐加权随机根据用户提供的每个 api_server 节点的请求处理能力speed进行加权随机分发吞吐越大的节点被分配到的概率越高未提供吞吐指标的节点则按其他节点的平均吞吐对待。源码实现第 279-287 行会先收集匹配模型且提供speed的节点再计算weights [speed / speed_sum ...]最后用random.choices(..., weightsweights)做加权采样。5.2 min_expected_latency最小期望延迟根据每个节点当前等待处理的请求数unfinished以及节点的吞吐能力speed计算完成响应所需的期望时间latency unfinished / speed期望时间最短的节点获得分发未提供吞吐的节点同样按平均吞吐处理。源码中第 288-303 行还会对候选节点索引做random.shuffle打乱以避免低并发场景下请求始终集中在某个节点。5.3 min_observed_latency最小观测延迟根据每个节点过去处理一定数量请求的平均耗时进行分发平均耗时最短的节点被选中。该策略依赖Status.latency队列——这是一个deque(maxlenLATENCY_DEQUE_LEN)默认长度 15见 utils.py由post_call()在每次响应结束后追加time.time() - start来滚动记录proxy.py。源码实现第 304-316 行对每个候选节点求np.mean(latency)取最小值没有历史延迟数据的节点按inf处理。选择建议若下游节点能力差异明显min_expected_latency能同时兼顾当前负载与处理能力是默认且通常最均衡的选择random实现最简单、开销最低min_observed_latency则更依赖历史反馈适合节点能力相对稳定、请求模式均匀的场景。六、进阶错误处理、鉴权与流式转发除文档直接描述的内容外从源码还可以挖掘出几个对生产部署有实际价值的细节错误码体系Proxy 定义了统一的错误码utils.pyMODEL_NOT_FOUND10400请求的模型不在模型列表中、SERVICE_UNAVAILABLE10401、API_TIMEOUT10402转发请求超时或目标节点不可达。请求前会先通过check_request_model()校验模型是否存在返回 404转发失败时handle_api_timeout()会返回带 10402 错误码的响应。超时控制AIOHTTP_TIMEOUT可通过环境变量在启动 Proxy 前设置用于控制转发给下游节点的总超时时间。API Key 鉴权通过--api-keys传入密钥后Proxy 会挂载AuthenticationMiddleware中间件对进入 Proxy 的请求做鉴权校验proxy.py。流式响应对于streamTrue的请求Proxy 通过ProxyStreamingResponse见 lmdeploy/serve/proxy/streaming_response.py以text/event-stream格式逐行转发下游返回的内容同时借助 FastAPIBackgroundTasks在响应结束后回调post_call()更新延迟统计保证路由策略的数据始终新鲜。请求头透传forward_raw_request_*系列函数proxy.py会保留原始请求头剔除Host并追加X-Forwarded-For、X-Forwarded-Host、X-Forwarded-Proto标准转发头确保下游服务能识别真实客户端来源。DistServe 连接池/distserve/connection_warmup接口可对 Prefill 与 Decode 节点执行批量建连预热身注意 disagg README 明确提示不要将同一个引擎节点注册到多个不同的 Proxy 上这是当前不支持的用法。七、小结LMDeploy 的 Request Distributor Server 是构建多实例、高可扩展 LLM 推理服务的关键一环它用统一的 OpenAI 兼容入口收敛多个api_server提供/nodes/status、/nodes/add、/nodes/remove等完整的节点生命周期管理接口并支持从简单的 Hybrid 共置部署到 Prefill/Decode 分离的 DistServe 部署配合三种路由策略实现按负载、按吞吐、按历史延迟的智能分发。无论是为了横向扩展吞吐还是追求更精细的资源调度都可以直接基于 docs/en/llm/proxy_server.md 与本仓库的 lmdeploy/serve/proxy/proxy.py 源码快速上手落地。赞分享人工智能大模型模型推理服务推理引擎本地部署模型量化【免费下载链接】lmdeployLMDeploy is a toolkit for compressing, deploying, and serving LLMs.项目地址https://gitcode.com/gh_mirrors/lm/lmdeploy点击查看免费下载相关推荐LMDeploy 请求分发服务器Proxy Server完全指南多 api_server 节点的统一接入与负载均衡LMDeploy 请求分发服务器Proxy Server完全指南多 api_server 节点的统一接入与负载均衡 LMDeploy 的请求分发服务器P人工智能大模型模型推理服务推理引擎本地部署模型量化Flet 路由 URL 策略 RouteUrlStrategy 完全指南path 与 hash 模式的原理、配置与部署Flet 路由 URL 策略 RouteUrlStrategy 完全指南path 与 hash 模式的原理、配置与部署 本篇技术指南聚焦 Flet 框架中用于前端跨平台桌面应用移动开发TensorRT-LLM 多 GPU 与多节点推理部署完全指南TP/PP/EP 并行策略实战TensorRT LLM 多 GPU 与多节点推理部署完全指南TP/PP/EP 并行策略实战 导读 本文以 AI Research SKILLs 仓库中 TeAI 技能人工智能大模型深度学习上一篇OpenSpec常见问题解答新手必知的30个问题下一篇分治算法实战指南快速乘法与矩阵运算的终极教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考