什么时候该选 OpenAI-compatible、native API 还是 offline engine#

这章解决什么问题#

前几章已经解释了不同 API surface 的存在理由，但工程读者通常还会继续问：如果我要真的做决策，到底什么时候该选哪一种？这件事如果不单独讲清楚，API 那一章仍然会更像“知道它们存在”，而不是“知道怎样做选择”。

这一章的目标就是把接口层写成一个选择问题，而不是一个列表问题。

为什么“选哪条表面”本身是架构决策#

调用表面的选择会直接影响后面的调试入口、部署方式、观测方法和可扩展性。也就是说，这不是“接口风格偏好”，而是系统边界怎样暴露给调用方的决策。

这也是为什么本章值得独立存在。很多普通专栏写到这里会停在“有哪些 API”；一本更成熟的技术书会再往前走一步，告诉读者“在什么语境下该选哪一类 API surface”。

一张更像工程判断的选择表#

场景：已有 OpenAI 风格客户端，需要最小迁移成本
优先：OpenAI-compatible API

场景：需要直接操作 /generate /flush_cache /server_info 之类原生能力
优先：native API

场景：想在 Python 进程里直接跑推理，不想起 HTTP server
优先：offline engine

场景：想在 prompt program 或运行时对象层直接组织生成逻辑
优先：frontend language / Runtime / Engine

这张表的价值在于，它把“支持哪些表面”升级成“不同表面对什么问题最合适”。对读者来说，这类判断框架比单纯知道有哪些接口更接近真实决策。

一个更贴近现实的比较维度#

当你在 OpenAI-compatible、native API 和 offline engine 之间做选择时，至少应该同时比较四件事：迁移成本、调试入口、部署位置和对内部能力的直接暴露程度。不同表面的差别，往往恰恰体现在这些地方。

例如，OpenAI-compatible API 往往迁移最顺，但对内部语义的暴露相对更间接；native API 更靠近 SGLang 原生能力，但会要求调用方更理解系统；offline engine 则把表面拉回程序内部，代价是你要自己接住更多运行时责任。

本章对应哪些代码路径#

这一章主要回指 docs/basic_usage/openai_api.rst、docs/basic_usage/native_api.ipynb、docs/basic_usage/offline_engine_api.ipynb、python/sglang/launch_server.py、python/sglang/srt/entrypoints/http_server.py 和 python/sglang/lang/api.py。

小结#

这一章真正想留下的不是更多接口知识，而是一句更实用的提醒：表面的选择，本身就是系统设计的一部分。对一本更像技术书的写法来说，这种“选择框架”比再多几段接口说明更有价值。