读运行时控制面：logging、weights group 与 expert record#

前面的代码导读已经把请求主线、输出尾部、prefix cache、多 worker、session 和 health check 这些主要脊梁都落回了源码，但还有一类对维护者特别重要、却仍然容易散在 http_server.py、tokenizer_communicator_mixin.py、scheduler.py、engine.py 和若干 util 文件里的控制面没有被正式收束：

configure_logging
init_weights_update_group / destroy_weights_update_group
start_expert_distribution_record / dump_expert_distribution_record
remote_instance_transfer_engine_info

这章真正要补齐的，就是把这组运行时控制面收成一条稳定的源码阅读路径，让读者知道：系统跑起来以后，维护者怎样通过正式控制面去看它、配它、协同它，而不是只知道“代码怎么跑”。

先把这组控制面看成三类维护动作，而不是零散端点#

如果只扫路由，很容易把这些 API 看成一串平铺的运维端点。更稳的理解方式，是先把它们分成三个稳定簇：

flowchart TD
    Log["日志与证据控制\nconfigure_logging"] --> TM["TokenizerManager"]
    Weights["远端权重协调\nweights_update_group / transfer info"] --> Comm["Communicator / tp_worker / model_runner"]
    Experts["专家分布记录\nstart/stop/dump expert record"] --> Rec["scheduler / expert_distribution recorder"]

这张图最重要的一点是：这组控制面并不在同一层做同一件事，而是在回答三类完全不同的维护动作。

第一组：`configure_logging` 是运行中可切换的证据控制面#

http_server.py 暴露 /configure_logging，最终落到：

TokenizerManager.configure_logging(...)
再进入 RequestLogger.configure(...)

这说明请求日志并不是“启动时定好就永远不能变”的静态配置，而是一条运行中可调整的正式控制面。它的工程价值很直接：

正常运行时可以保持轻量
到问题窗口期再把 request logger / dump 粒度切重

也就是说，日志控制不是外围工具，而是 live control plane 的一部分。对维护者来说，理解这点特别重要，因为它会直接改变你对“证据应该在什么时候加重采集”的做法。

第二组：weights update group 讲的不是“换权重”，而是“先搭协作通道”#

很多人看到 init_weights_update_group(...) / destroy_weights_update_group(...)，会下意识把它们和具体的 update_weights_from_* 混成一类。更稳的理解是：

具体权重更新是在换数据
weights update group 更像是在先搭一条之后可用于分布式权重协同更新的通道

这条链最值得顺着源码看的是：

http_server.py 提供入口
TokenizerManager 通过 communicator 把控制消息发下去
scheduler_update_weights_mixin.py
tp_worker.py
model_runner.py

这样读，你就不会再把它看成“多一个管理接口”，而会看成一条真正的分布式协调控制链。

第三组：expert distribution record 把执行层专家路由重新接回运维控制面#

http_server.py 里会暴露：

/start_expert_distribution_record
/stop_expert_distribution_record
/dump_expert_distribution_record

而 scheduler 里又会调用：

get_global_expert_distribution_recorder().start_record()
...stop_record()
...dump_record()

同时模型与 MoE 路径又会不断通过：

with_current_layer(...)
disable_this_region()
on_select_experts(...)

把专家选择信息喂给 recorder。

这说明 expert distribution record 不是一个“看点统计”的旁路端点，而是把执行层专家路由、全局 recorder 和对外运维端点正式接成了闭环。对代码导读来说，这类闭环特别值钱，因为它能把 execution model 和维护层重新落回同一条源码路径。

为什么它和 `return_routed_experts` 不能混为一谈#

两者都和专家路由有关，但职责完全不同：

return_routed_experts 更像单请求级别的旁路返回语义
expert distribution record 更像全局、长窗口的运行时记录能力

这恰好是系统书比普通笔记更应该主动拆开的地方。否则读者很容易把两者都归成“专家可视化能力”，而忽略一个偏 request-level，一个偏 runtime-level 的根本差异。

`remote_instance_transfer_engine_info` 为什么也应归到这一组#

前一章已经解释过远端 transfer 协调的 bootstrap server，这里值得再补一层维护者视角：

/remote_instance_transfer_engine_info

是把那条远端协调链重新暴露到主控制面上的查询入口。换句话说：

运行时架构章节负责解释它为什么存在
这章负责解释维护者怎样把它当成正式控制面来读

这种“架构存在理由”和“控制面阅读顺序”分开讲，正是代码导读章法比普通源码笔记更稳的地方。

这组控制面的共同特征，其实定义了“运行时控制面”这个概念#

它们虽然分属不同主题，但有三个共同点：

都不是普通业务请求
都会穿过正式 communicator / manager / scheduler / worker 链
都在运行中改变或查询系统的维护状态，而不是模型业务语义本身

也正因为这样，“运行时控制面”本身才值得被看成一类稳定概念，而不是几个恰好都长得像运维接口的端点。

真正顺着源码读这组控制面时，更稳的顺序#

建议按下面顺序：

先看 http_server.py 里的控制面路由入口
再看 TokenizerManager / communicator mixin 的接线方式
然后分叉到：
- RequestLogger.configure(...)
- scheduler_update_weights_mixin.py / tp_worker.py / model_runner.py
- scheduler.py 里的 expert_distribution_handle(...)
- bootstrap / transfer info 查询路径

这条顺序的价值，在于你先抓“控制请求怎样进入系统”，再看“它们分别会改哪一层”。否则很容易变成一堆平铺函数导览。

最容易出现的四种误判#

第一，误以为这些只是零散运维 API。
实际上它们共同构成了正式运行时控制面。

第二，误以为 configure_logging 只是本地工具。
它是运行中切换 request logger / dump 策略的正式入口。

第三，误以为 weights update group 和具体权重更新是一回事。
前者更像先搭协同通道，后者才是真正更新数据。

第四，误以为 expert distribution record 和 return_routed_experts 是同一种能力。
一个偏全局 recorder，一个偏单请求旁路返回。

小结#

这一章真正补齐的，是代码导读里此前散落的运行时控制面：请求日志控制、分布式权重协调、专家分布记录和远端 transfer 信息查询，并不只是几条顺手暴露出来的运维端点，而是系统跑起来以后维护者真正依赖的一组正式控制动作。

到这里，代码导读就不只是在教你“系统怎么跑”，也开始教你“系统跑起来以后，维护者怎样通过正式控制面去看它、配它、协同它”。