从 #28688（pickle-to-msgpack 迁移）中提取样式、类型注释、字段排序和注释改进作为独立的清理 PR，与序列化/PickleWrapper 更改解耦，降低主 PR 的审查噪音。
建议开发者快速浏览以了解代码库的样式约定和类型注释模式，尤其关注 io_struct.py 中字段排序和 SessionParams 的文档风格，可作为后续新增 IPC 结构体的参考。
无实质性 review 讨论。所有变更均为纯样式/类型改进，PR 作者声明无行为变更，CI 通过。
http_server.py）：将 load_lora_adapter、load_lora_adapter_from_tensors、unload_lora_adapter 三个端点中重复的 if/else 分支合并为单行三元表达式 + 返回，减少冗余。data_parallel_controller.py）：将端口握手中的 rep_socket.recv().decode() 和 req_socket.send(...encode()) 替换为已有的 sock_recv/sock_send 包装函数，与其余 IPC 代码保持一致。io_struct.py）：调整 EmbeddingReqInput 字段顺序以对齐 GenerateReqInput；为 SessionParams 每个字段添加详细 docstring；将 ImageDataInputItem 等类型加宽为包含 bytes 和 Dict[str, Any]；移除无用的 FinishReasonDict/CachedTokensDetails 别名；加宽部分类型注释（如 input_embeds、embeddings 等）并缩小 serialized_named_tensors 至 List[bytes]。output_streamer.py）：更新共享池化隐藏状态的注释，明确两种格式（stacked/non-stacked）及其接收方逻辑；调整条件检查，仅当多于1个请求时才尝试 stack 并包裹为单元素列表（[torch.stack(phs_list)]）。tokenizer_manager.py）：将 input_embeds 参数类型从 Optional[Union[List[float], None]] 修正为 Optional[List[List[float]]]；在 _handle_batch_output 中添加 PHS 解包注释并实现与 sender 格式对应的解包逻辑（单元素列表缩展为 tensor）。| 文件 | 模块 | 状态 | 重要度 |
|---|---|---|---|
python/sglang/srt/managers/io_struct.py |
IPC 结构体 | modified | 8.49 |
python/sglang/srt/managers/scheduler_components/output_streamer.py |
输出流 | modified | 5.96 |
python/sglang/srt/entrypoints/http_server.py |
HTTP 服务 | modified | 5.81 |
python/sglang/srt/managers/tokenizer_manager.py |
Tokenizer 管理 | modified | 5.68 |
python/sglang/srt/managers/data_parallel_controller.py |
数据并行 | modified | 4.39 |
python/sglang/srt/managers/io_struct.py
dependency-wiring
核心数据结构定义文件；涉及字段重排、类型加宽、注释补全和冗余别名清理，是本次改动量最大的文件。
# 类型定义加宽：支持 bytes 和显式 Dict[str, Any]
ImageDataInputItem = Union[str, bytes, Dict[str, Any], ImageData, Image]
AudioDataInputItem = Union[str, bytes, Dict[str, Any]]
VideoDataInputItem = Union[str, bytes, Dict[str, Any], VideoData]
# SessionParams 每个字段添加详细 docstring
@dataclass
class SessionParams:
# 会话标识符，调度器用于查找或创建 Session 对象
id: Optional[str] = None
# 会话内的请求标识符，用于选择分支点或追加
rid: Optional[str] = None
# token 级别插入偏移量：context[:offset] + new_tokens
offset: Optional[int] = None
# 是否替换已有节点（非流式会话不支持）
replace: Optional[bool] = None
# 是否丢弃前序输出 token（非流式会话不支持）
drop_previous_output: Optional[bool] = None
python/sglang/srt/managers/scheduler_components/output_streamer.py
core-logic
修改 PHS 序列化逻辑的注释和条件，优化跨 IPC 边界的序列化格式说明。
# 优化 pooled hidden states (PHS) 的 IPC 序列化。
# 两种格式，接收方按长度区分：
# Stacked: [stacked_tensor(N, ...)] — 长度为 1，N > 1
# Non-stacked: [tensor_0, tensor_1, ...] — 长度 == N
# Stacking 将 N 次 pickle/__reduce_ex__ 调用降为 1 次。
# 仅当所有条目非 None 且形状相同时才可 stacking。
# 见 tokenizer_manager.py 中成对的接收逻辑。
stacked_phs = None
if has_phs:
all_have_phs = all(t is not None for t in phs_list)
if all_have_phs:
if len(phs_list) > 1 and all(
t.shape == phs_list[0].shape for t in phs_list
):
# Stacked: 单张量，包裹在列表中
stacked_phs = [torch.stack(phs_list)]
else:
# Non-stacked: 单个请求、形状不统一或含 None
stacked_phs = phs_list
else:
# Non-stacked: 部分请求无 PHS（None 条目）
stacked_phs = phs_list
当前评论区没有形成足够清晰的争议点或结论，后续有更多讨论时会体现在这里。
由于是纯样式、注释和类型标记的改进，未涉及任何生产逻辑变更，回归风险极低。唯一潜在风险是类型注释的加宽可能掩盖实际运行时类型错误，但此类修改均依据实际运行时值调整（如 input_embeds 始终为 List[List[float]]），且未改变传入值格式，因此无实际影响。
对用户完全透明，API 行为和输出一致。对系统无性能或安全影响。对团队主要提升代码可读性和维护性，减少后续 lint/类型检查告警。影响范围限于 5 个文件，其中 io_struct.py 影响最大（+182/-203 行），但 90% 为注释和空格。
当前没有检测到明确关联的 Issue 链接，后续同步到相关引用后会出现在这里。
参与讨论