读 entrypoints/openai：协议表面怎样回到 runtime#

代码导读前面的章节已经把仓库主线、tests、benchmark 和故障入口讲得比较厚了，但如果你想从协议表面真正往里读，python/sglang/srt/entrypoints/openai/ 这一层仍然是最容易被误读的入口之一。很多工程读者会把这里看成“单纯的接口适配目录”，好像它做完字段转换就结束了。真正的源码组织远比这更关键：它同时承接模板解释、请求转换、stream / non-stream 分支、tool call 语义翻译，以及最终回到 runtime 的主入口。

这也是为什么这棵树值得单独成章。它不是在重复 API 章节，而是在回答另一个更靠近源码的问题：如果我要顺着 OpenAI-compatible 表面把系统读进去，最稳的顺序到底是什么？

先把这层放回全书主线#

entrypoints/openai 在全书里正好站在协议表面和 runtime 主链之间。它不像 http_server.py 那样主要负责路由装配，也不像 TokenizerManager 那样真正进入请求状态桥，而是承担中间那段最关键的解释工作：

  • 哪些 surface 共享同一骨架
  • 哪些差异是 chat 特有的
  • 哪些差异来自 completions、embeddings、rerank 或 Responses API
  • 这些差异最后怎样重新收敛到 TokenizerManager.generate_request(...)

所以更稳的理解是：这里不是“协议目录”，而是一条从协议表面回到 runtime 的源码斜坡。读稳它，很多前后章节就会自然接起来。

先看这张图，再决定从哪读进去#

下面这张图的价值，不在于重复函数调用顺序，而在于先把“共用骨架”和“surface 差异”拆开。很多人一头扎进 serving_chat.py 就会把两者混在一起，结果越读越大。

flowchart LR
    Route["http_server route"] --> Base["OpenAIServingBase.handle_request()"]
    Base --> Convert["_convert_to_internal_request()"]
    Convert --> Stream["_handle_streaming_request() / _handle_non_streaming_request()"]
    Stream --> TM["TokenizerManager.generate_request()"]
    TM --> Runtime["scheduler / detokenizer / response path"]

这张图比纯文字多解释的一点是：OpenAI-compatible surface 并不是每个 handler 各写一套完整逻辑，而是先经过基类统一骨架，再落到各自的请求转换和结果翻译。

更稳的入口永远是 http_server.py，不是某个最大 handler#

如果你一上来就跳进 serving_chat.py，最容易把“路由绑定”“基类骨架”和“chat 特有逻辑”混成同一个层。更稳的顺序通常是：

  1. 先看 http_server.py 怎样把 /v1/chat/completions、/v1/completions、/v1/embeddings 等路由绑定到 app state 上的 serving 对象。
  2. 再看 serving_base.py::handle_request(...) 的统一骨架。
  3. 最后才进入具体 handler，例如 OpenAIServingChat 的 _convert_to_internal_request(...)、_generate_chat_stream(...) 或 _handle_non_streaming_request(...)。

这条顺序的真正价值是：你先建立“哪些东西大家都共享”，再理解“哪里开始出现 surface-specific 的分叉”。这比一开始就读最大文件稳定得多，也更符合代码导读章节应该提供的帮助。

OpenAIServingBase.handle_request(...) 是最值得先记住的骨架#

如果整个目录只先记一个函数，最值钱的就是 OpenAIServingBase.handle_request(...)。因为它把 OpenAI-compatible 入口统一成一个很稳定的顺序：

  1. _validate_request(request)
  2. 记录原始 OpenAI 请求日志
  3. _convert_to_internal_request(request, raw_request)
  4. 根据 request.stream 决定走 _handle_streaming_request(...) 还是 _handle_non_streaming_request(...)
  5. 统一处理 HTTPException、ValueError 和内部异常

这条骨架特别重要，因为之后无论你读 chat、completions、embedding 还是 rerank，都可以先问自己一个问题：当前差异到底出现在“请求转换”阶段，还是出现在“stream / non-stream 处理”阶段。只要这点先站稳，这个目录就不再像一组并排 handler 文件，而会像一套共享框架。

chat handler 真正值得抓的是哪两段#

OpenAIServingChat 里最值得单独抓住的不是整份文件，而是两段。

第一段是 _convert_to_internal_request(...)。
这里会把：

  • reasoning_effort
  • multimodal message preprocessing
  • request.to_sampling_params(...)
  • GenerateReqInput(...)
  • routed_dp_rank
  • LoRA 解析

统一压到内部请求对象上。换句话说，chat 请求在这里并不是“被转成另一份 JSON”，而是被正式翻译成 SGLang 自己的生成请求对象。

第二段是 _generate_chat_stream(...)。
这段更适合用来理解 streaming surface 的复杂性，因为它要维护：

  • parser dict
  • reasoning parser dict
  • stream buffers
  • finish reasons
  • usage tracking

然后一边消费 TokenizerManager.generate_request(...) 的输出，一边把它翻译成 OpenAI stream chunk。这说明 streaming 并不是“runtime 已经 stream 了，所以接口层原样转发”，而是 surface 层仍然在持续做状态维护和语义翻译。

为什么 serving_responses.py 值得顺手对照#

OpenAIServingResponses 直接继承 OpenAIServingChat，这对代码阅读特别有价值。它说明一件很实用的事：Responses API 并不是另一套完全独立的实现，而是复用了 chat handler 的大量基础逻辑。因此当你读到两者的差异时，更应该先问：

  • 这是新协议真的新增的运行语义
  • 还是同一套基础 handler 在不同外表面下的轻微改写

这种对照非常像一本成熟技术书后半程会做的工作：不是只解释最大文件，而是解释“最大文件在整个 handler 家族里的位置”。

completions、embeddings、rerank 的对照能帮你避免另一种误读#

如果只读 chat handler，很容易形成另一个错觉：好像所有 OpenAI surface 都和 messages / template 强绑定。对照：

  • serving_completions.py
  • serving_embedding.py
  • serving_rerank.py

你会更清楚地看到：

  • 有的 surface 更偏 prompt / suffix 转换
  • 有的 surface 更偏模板与 tokenizer 使用差异
  • 有的 surface 只复用基类骨架，但转换逻辑已经完全不同

这类对照阅读的价值很高，因为它会把“OpenAI-compatible API”从单一幻觉重新拆成一个有共享骨架、也有明确表面差异的 handler 家族。

真正顺着这棵树读时，更稳的顺序#

把上面的内容压成最小读法，推荐顺序其实很简单：

  1. http_server.py 里的路由注册
  2. serving_base.py::handle_request(...)
  3. serving_chat.py::_convert_to_internal_request(...)
  4. serving_chat.py::_generate_chat_stream(...)
  5. 再回头对照 serving_completions.py、serving_responses.py

这样读，你拿到的不只是某个 handler 的局部理解，而是一张“协议 surface 怎样统一落回 runtime”的源码地图。对代码导读来说，这比一开始就深入某个大函数更值钱。

最容易出现的三种误判#

第一，误把 entrypoints/openai 当成纯接口适配目录。
实际上这里承接了模板解释、请求转换、stream 语义和结果翻译，是协议表面真正回到 runtime 的中间层。

第二，误把 serving_chat.py 看成一切逻辑都从这里开始。
更稳的阅读入口其实是 http_server.py 和 OpenAIServingBase.handle_request(...)。

第三，误以为不同 surface 只是路由不同。
它们在请求转换、模板依赖和结果翻译这几层已经有明显语义差异。

小结#

entrypoints/openai 真正值得单独成章的地方，不在于它覆盖了很多 API，而在于它给出了一个从协议表面回到 runtime 的稳定阅读入口：先从路由绑定进来，再经过基类骨架，最后再进各 surface-specific 的转换和 stream 逻辑。

把这棵树读稳之后，代码导读部分就不只是告诉你“目录里有什么”，而是开始教你怎样顺着一个真实协议表面把整套系统读进去。