Skip to content

refactor: separate service routing and cluster responsibilities. - #95

Open
PixelFlat wants to merge 3 commits into
xLLM-AI:mainfrom
PixelFlat:refactor/service-router
Open

PixelFlat wants to merge 3 commits into
xLLM-AI:mainfrom
PixelFlat:refactor/service-router

Conversation

@PixelFlat

@PixelFlat PixelFlat commented Oct 22, 2026 •

Copy link
Copy Markdown
Contributor

重构目的

原来的 scheduler/ 同时承担选路、实例注册与健康管理、etcd watch、引擎连接、请求存储及输出处理,InstanceMgr 和 Scheduler 的职责较集中。本 PR 按这些职责拆分模块,将 scheduler/ 调整为 router/,并把实例管理拆为 cluster/ 与 coordinator/,方便分别演进路由策略、实例控制和部署管理。

这是阶段性的架构重构草案,先以 draft 形式讨论目录边界、依赖和生命周期。继续使用现有 CLI、HTTP/RPC 协议、etcd 注册格式与 RR/CAR/SLO_AWARE 策略;CAR 的评分公式保持不变。JSON/YAML 拉起引擎、进程托管、自动扩缩容和 Kubernetes 控制器尚未在本 PR 中实现。

目录与文件组织

以下路径均相对于 xllm_service/;.h/.cpp 表示同名声明和实现文件。

xllm_service/
├── main.cpp                         # 进程入口、配置加载与信号处理
├── service_app.h/.cpp               # 应用装配与整体启停
├── config/                          # 启动配置
│   ├── service_config.h
│   └── config_loader.h/.cpp
├── router/                          # 路由、服务侧调度状态、请求生命周期
│   ├── router.h/.cpp
│   ├── routing_types.h
│   ├── routing_policy.h
│   ├── routing_state.h/.cpp
│   ├── request_manager.h/.cpp
│   └── policies/
│       ├── round_robin.h/.cpp
│       ├── cache_aware_routing.h/.cpp
│       └── slo_aware.h/.cpp
├── cluster/                         # 引擎实例状态、控制与通信
│   ├── instance_types.h
│   ├── instance_state.h/.cpp
│   ├── instance_controller.h/.cpp
│   └── instance_client.h/.cpp
├── coordinator/                     # etcd 发现与服务自身成员管理
│   ├── etcd_client.h/.cpp
│   ├── instance_discovery.h/.cpp
│   └── service_membership.h/.cpp
├── request/                         # 请求数据、输入预处理与有序输出
│   ├── request.h
│   ├── chat_message.h
│   ├── request_metrics.h
│   ├── request_output.h
│   ├── request_preprocessor.h/.cpp
│   └── output_dispatcher.h/.cpp
├── kv_conductor/                    # 异步 KV 事件消费与分层前缀索引
├── http_service/                    # HTTP 协议入口与客户端响应编码
├── rpc_service/                     # 引擎 RPC 控制及结构化结果入口
├── chat_template/                   # 对话模板
├── tokenizer/                       # 分词实现与线程池
├── common/                          # 公共类型、工具、指标及基础设施
├── proto/                           # 服务接口的 protobuf 定义
└── examples/                        # 调用与部署示例

目录命名备选

当前代码采用 coordinator/ 和 kv_conductor/,以下名字保留为评审时的备选:

当前目录 备选名称 侧重点
coordinator/ membership/ 实例与服务成员的加入退出、租约及主备关系
coordinator/ etcd/ 按当前使用的协调基础设施命名
coordinator/ coordination/ 注册发现、租约、主备选举及状态同步的整体协调
kv_conductor/ kv_directory/ 对外提供实例、DP 和 Device/Host 分层 KV 目录及前缀匹配查询

kv_conductor/ 统筹 KV 元数据的订阅、恢复、索引和查询。内部保留 KVDirectory、
kv_index、kv_event_decoder 等具体名称。配置中的 discovery 字段继续表示
KV 事件端点的自动发现规则,与源码目录命名独立。

应用入口与配置

文件 职责
main.cpp 解析启动参数、加载配置、检查端口并运行应用;信号处理函数只记录退出信号,由主线程执行停机。
service_app.h/.cpp 创建模块及依赖,管理 RPC/HTTP 监听、发现、健康检查、KV 订阅和请求队列的启停顺序。构造函数不启动后台任务。
config/service_config.h 保存配置值和默认值,由构造函数传给业务模块。由原 common/options.h 整理而来。
config/config_loader.h/.cpp 将现有 gflags 转换为 ServiceConfig,集中处理配置读取边界。

router/:选路与请求生命周期

文件 职责
router.h/.cpp 组织请求预处理、查询本地 KV 目录、调用策略并绑定选中的实例代际。
routing_types.h 定义候选实例快照、策略输入和路由决策,统一策略之间的数据接口。
routing_policy.h 定义 RoutingPolicy 接口。策略消费状态快照,不直接访问 etcd 或调用引擎。
policies/round_robin.h/.cpp RR 选点。
policies/cache_aware_routing.h/.cpp CAR 选点:结合 Device/Host KV 前缀命中收益与队列负载选择 P,结合负载选择 D。
policies/slo_aware.h/.cpp 根据候选实例的 TTFT/TPOT 预测进行 SLO 选点,并返回角色调整决策。
routing_state.h/.cpp 保存服务本地的请求/token 预留与时间预测器,协调选路和预留提交、实例代际校验及完成后的释放。与引擎实际上报的负载分开。
request_manager.h/.cpp 管理请求准入、请求表、结果接收、完成/取消、失败实例上的请求清理及停机取消;与实例下线共用准入屏障。

RequestManager 保留在 router/,因为它持有服务端请求生命周期和调度预留;request/ 放请求数据、输入预处理和有序输出分发。

cluster/:实例事实、控制和通信分离

文件 职责
instance_types.h 定义类型化的实例事件、负载事件和只读实例视图。注册元数据通过共享只读对象在快照间复用。
instance_state.h/.cpp 保存本地实例集合、角色索引、健康状态、心跳及引擎上报负载;提供状态更新接口和一致快照,不执行引擎网络操作,也不持有请求表。
instance_controller.h/.cpp 消费实例/负载事件,协调注册、替换、租约丢失宽限期、健康探测、实例下线和 P/D Link/Unlink;通过同步回调让请求管理器完成下线清理。
instance_client.h/.cpp 按实例地址与代际维护 Channel,封装健康探测、P/D Link/Unlink 和推理请求提交。旧实例的清理不会误删同地址新实例的连接。

InstanceState 记录引擎和注册系统提供的事实;RoutingState 记录服务自己产生的预留与预测。二者独立,避免心跳更新覆盖服务侧预留,也避免实例状态锁承担路由策略计算。

coordinator/:注册发现与服务成员

文件 职责
etcd_client.h/.cpp 封装现有 etcd 访问、watch 和租约操作。
instance_discovery.h/.cpp 读取初始实例与负载状态,消费 watch 并转换为类型化事件,通过串行后台队列交给实例控制模块;主服务发布实例负载供其他服务成员读取。
service_membership.h/.cpp 管理 service 自身注册、租约续约、主备选举,以及主服务的周期性负载发布触发。

请求、KV 索引与协议适配

目录 / 文件 职责
request/request.h 请求输入、选中的 P/D 路由与代际、输出回调以及请求状态。
request/chat_message.h 与具体模板实现解耦的消息、工具和函数输入类型,从 Jinja 模板头文件中提取。
request/request_metrics.h、request_output.h 请求阶段转换、计时和输出相关数据。
request/request_preprocessor.h/.cpp 负责模板渲染、分词及模型相关输入准备,复用现有模板和 tokenizer pool。
request/output_dispatcher.h/.cpp 按请求 ID 将结果和取消操作映射到固定串行队列,维护同一请求的输出顺序,并提供排空能力。
kv_conductor/kv_event_decoder.h/.cpp 解码 ZMQ KV 事件。
kv_conductor/kv_index.h/.cpp 维护 Host/Device KV 块和前缀索引。
kv_conductor/kv_directory.h/.cpp 管理后台订阅、恢复与实例级目录;从实例快照生成订阅目标,向路由提供本地前缀匹配查询。路由过程不等待 ZMQ 或 replay。
http_service/service.h/.cpp 处理 HTTP 请求校验、协议转换、调度与发送,以及内部心跳和 KV 查询接口;vLLM 后端沿用 HTTP JSON/SSE 转发路径。
http_service/response_handler.h/.cpp 从原 scheduler/ 移入,绑定客户端输出回调,构造 OpenAI/Anthropic 响应。
http_service/chat_json_parser.*、anthropic_adapter.*、anthropic_stream_encoder.*、usage_proto_adapter.* 保留现有协议解析、适配与流式编码职责。
rpc_service/service.h/.cpp 接收引擎心跳、实例查询和批量 Generations,分别转交实例控制、实例状态和请求管理模块。
rpc_service/disagg_generation_adapter.h/.cpp 将引擎回传的结构化结果转换为服务内部输出;tool call/reasoning 的解析继续由引擎完成。
rpc_service/client.h/.cpp 保留现有 RPC 客户端辅助代码。

数据流与并发边界

客户端 HTTP
  → HTTP 协议解析
  → Router → RequestPreprocessor
           → KVDirectory 本地匹配
           → RoutingState + RoutingPolicy → 实例代际绑定与调度预留
  → ResponseHandler 绑定输出回调
  → RequestManager 准入
  → InstanceClient → P → D

D → RPC Generations
  → RequestManager
  → OutputDispatcher(同请求串行)
  → HTTP 响应回调 → 客户端

etcd 初始状态 / watch
  → InstanceDiscovery → InstanceController → InstanceState
                                          → InstanceClient(探测、Link/Unlink)
                                          → RequestManager(同步下线清理)
  • 请求准入和实例下线使用同一屏障;准入时重新验证选中的代际,拒绝已下线或被替换的实例。
  • 结果和取消事件在请求锁内按序入队;终止后的结果不再调用客户端回调,预留和指标只释放一次。
  • 实例状态锁内不执行路由策略、健康探测、Link/Unlink 或 etcd 操作;快照复用只读注册元数据,避免反复复制 profiling 数组。
  • RPC 控制入口先启动;有可用 DEFAULT 实例或 P/D 组合后再开放业务 HTTP。实例暂不可用时保留控制入口供恢复。
  • 停机时停止服务成员、发现、健康检查及 KV 订阅,然后取消并排空请求,最后等待网络服务退出。

迁移与文档

  • 原 Scheduler 拆为 Router、RequestPreprocessor、RequestManager 和 OutputDispatcher。
  • 原 InstanceMgr 拆为 InstanceState、InstanceController、InstanceClient、InstanceDiscovery、ServiceMembership 和 RoutingState。
  • 原 master.* 拆为 main.cpp 与 service_app.*;各模块的 CMake 依赖同步调整。
  • 测试按 cluster/、router/、request/ 和 http_service/ 重新归类,覆盖代际替换、准入/下线竞争、有序输出、预留释放与选路。
  • 增加 docs/zh/architecture.md,更新中英文 README 的目录结构、KV events 文档和 sidecar 的源码引用。

验证

  • Linux ARM64 环境下服务编译通过。
  • 服务 CTest:190/190 通过。
  • 独立 etcd + mock 后端联测通过:控制入口提前可用、实例注册后开放业务入口、HTTP 请求及参数转发、备用服务发现已有实例、实例删除后的就绪状态切换、P/D 组合就绪、SIGTERM 退出及主备接管。
  • 原生 P/D Link/Unlink 已使用 mock brpc Decode 服务验证。
  • 修改的 C++ 文件已使用 clang-format 20.1.6 格式化,git diff --check 通过。
  • 真实 NPU 联测通过:Qwen3-8B BF16,1P1D、TP=1、DP=1;使用本 PR 新编译的 Service 和已有的兼容引擎产物。etcd 自动注册发现、P/D 联动、CAR 请求处理与 KV 目录同步均正常。
  • 14 项功能检查通过:chat/completions 的 JSON 与 SSE、tool call、reasoning 及两者组合、logprobs、非法参数和两路并发;另一个基本语义检查正确返回 2。
  • 成功联测中,P、D 和 Service 均以 0 退出,无强制结束或存活测试进程。
  • 以上覆盖 CPU/mock 回归和 NPU 功能验证;未进行性能对比、多机或 TP>1 验证。

@PixelFlat
PixelFlat marked this pull request as ready for review October 23, 2026 13:14
@PixelFlat
PixelFlat marked this pull request as draft October 23, 2026 13:14
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 23, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-23T14:16:42.843509Z 741fa88 Draft marked ready
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@PixelFlat
PixelFlat marked this pull request as ready for review October 23, 2026 14:06

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 741fa88588

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

Comment on lines +130 to +132
} else if (info.type == InstanceType::DECODE &&
peer.role == InstanceType::PREFILL) {
result.emplace_back(info.rpc_address, *peer.info);

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Send decode unlinks to the surviving prefill peers

When a dedicated DECODE instance is deregistered, deregister_instance() calls this with removing=true, but this branch still builds (info.rpc_address, *peer.info). The resulting UnlinkInstance is sent to the decode endpoint being removed and identifies the prefill as its peer; if that decode is failed or unreachable, the call fails and every surviving prefill retains the stale decode link. For removal, reverse the tuple so the surviving prefill receives the removed decode metadata.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant