sgl-project/sglang-omni

一、项目定位

SGLang-Omni 是 sgl-project 下的多阶段（multi-stage）推理服务运行时，专门面向 omni 模型、语音 / TTS 模型以及统一多模态模型。它把一次生成拆成多个异构阶段——预处理、编码器、自回归引擎、talker、解码器、vocoder、聚合器——分别匹配不同的调度器与传输后端，对外暴露 OpenAI 兼容的 /v1/audio/speech、/v1/audio/transcriptions、多模态 chat 等接口。项目明确把自己定位在 SGLang 生态之上：自回归调度与 token 级执行复用 SGLang，而 pipeline 拓扑、阶段生命周期、跨阶段传输、模型族适配层、serving surface 由 SGLang-Omni 自己拥有。 从 README 与提交历史看，项目处于活跃但偏早期的生产化阶段：PyPI 最新 release 为 v0.1.7（2026-09-28），近一周提交热点集中在 Qwen3-Omni 内核级性能优化（MoE kernel compile、predictor 重叠发射、MRoPE 元数据裁剪）、MiniCPM-o HiFT decode compile、CosyVoice3 / MOSS-TTS 的跨阶段零拷贝、以及 XPU / Router 安全修复。README 把 Apple Silicon、Intel XPU 都标为 Experimental，CUDA 为默认完整支持后端。仓库结构上，sglang_omni/（739 文件）是主 Python 包，sglang_omni_router/ 是 Rust+Python 的多 worker 前置路由，sglang_omni_mlx/ 是 Apple Silicon 适配层，OmniTyper 与 Voxt 是 Swift / iOS 侧配套项目，tests/（610 文件）和 benchmarks/（87 文件）提供测试与回归基准。整体是一个正在从研究原型走向多硬件、多模型族产品化的 serving 框架。

解决什么问题、给谁用

解决的核心问题是：现代 omni / TTS / 语音模型不再是单一自回归 decode，而是由多个计算模式完全不同、依赖结构各异、资源需求不等的阶段串/并而成（如文本 thinker → 音频 talker → vocoder，或 ASR encoder → LLM → 说话人日志）。现有 serving 框架要么只覆盖纯文本 LLM（vLLM、TensorRT-LLM），要么只覆盖单阶段扩散/解码，无法原生表达这种多阶段 pipeline 的调度、阶段间 tensor 传输、异构硬件后端切换、以及流式 vocoder 输出。SGLang-Omni 的目标用户是：需要把 Qwen3-Omni、MiniMax Music 3、Higgs Audio v3、MOSS-TTS、Fish Speech S2-Pro、Qwen3-ASR 等模型以生产级延迟与吞吐部署在 NVIDIA CUDA、Intel XPU、Apple Silicon、ROCm、NPU 等多硬件上的推理工程师、MLSys 研究者、以及需要 OpenAI 兼容音频 API 的产品团队。典型场景包括：实时语音对话（全双工）、歌词→立体声歌曲生成、批量 TTS、流式语音、上传参考语音克隆、ASR+说话人分离一站式服务。

1) 推理系统工程师：负责把 omni / TTS 模型部署到 GPU 集群，需要多阶段 pipeline 调度、跨阶段 tensor relay、NCCL/NIXL/Mooncake 传输后端、以及 OpenAI 兼容 API；2) 性能优化工程师：在 Qwen3-Omni、MiniCPM-o 等模型上做 kernel 级调优（MoE compile、HiFT decode、predictor 重叠、MRoPE 裁剪）；3) 多硬件支持工程师：为 Intel XPU、Apple Silicon MLX、ROCm、NPU 等非 CUDA 后端添加适配层；4) 研究者 / 评测工程师：使用 benchmarks/ 与 playground/ 跑回归、对比不同模型族；5) 端侧 / iOS 开发者：通过 OmniTyper、Voxt 把能力带到 Apple 平台。

同类项目与差别

• SGLang (sgl-project/sglang)：SGLang 是纯文本 LLM 的高性能 autoregressive 调度与模型执行引擎；SGLang-Omni 在其之上接管多阶段 pipeline、阶段间传输、vocoder/talker 调度、音频 API。自回归部分复用 SGLang，非自回归阶段由 Omni 自己拥有。
• vLLM：vLLM 聚焦单阶段自回归 LLM serving，无多阶段 pipeline、无 vocoder/talker 调度、无跨阶段 tensor relay、无 OpenAI 兼容音频端点。Omni 在音频/多模态 serving 层面是 vLLM 的上层扩展。
• TensorRT-LLM：NVIDIA 官方优化，深度绑定 CUDA/TensorRT，单阶段为主；Omni 面向多硬件（XPU/ROCm/NPU/MLX）、多阶段、模型族更宽（TTS/ASR/音乐/Omni），但单卡极致优化深度可能不如 TRT-LLM。
• FasterWhisper / WhisperX：专注 ASR 单任务；Omni 把 ASR、TTS、音乐生成、多模态 chat 统一到一个 serving surface 与多阶段框架下。
• Coqui TTS / ChatTTS：专注 TTS 模型本身；Omni 是 serving 运行时，把 TTS 作为多阶段 pipeline 之一，支持 batch/streaming/voice-clone 以及与其他模态组合。

核心能力

阶段：活跃开发、早期生产化。PyPI 最新 v0.1.7（2026-09-28），近一周仍有密集性能提交；README 明确标注 Apple Silicon、XPU 为 Experimental；CUDA 为默认完整支持后端。

技术栈：Python 3.10–3.12（主包 sglang_omni）；Rust + Python（sglang_omni_router）；Swift（OmniTyper、Voxt）；PyTorch 2.13.0 + torchvision 0.28.0；SGLang 0.5.21（自回归调度/执行）；MLX / mlx-lm（Apple Silicon 后端）；flashinfer_python[cu13] 0.6.18 + flash-attn-4 + kernels 0.14.x（CUDA 内核）；cache-dit 1.3.0（MiniMax Music 3 DIT）；nixl-cu13 / mooncake-transfer-engine-cuda13（跨阶段传输）；transformers 5.12.1, accelerate, pyzmq, msgpack, msgspec, pydantic, PyYAML, fastapi, uvicorn；多硬件 pyproject_*.toml（cpu/musa/npu/rocm/xpu）；setuptools 构建；GitHub Actions CI（.github/workflows）

规模：主包 sglang_omni 739 文件；tests/ 610 文件；benchmarks/ 87 文件；examples/ 66 文件；docs/ 95 文件；sglang_omni_router/ 72 文件；sglang_omni_mlx/ 8 文件；OmniTyper 42 文件；Voxt 1008 文件。最近提交热点：tests/unit_test 24 次、sglang_omni/models 20 次、sglang_omni/preprocessing 4 次。PyPI release v0.1.7（2026-09-28）、v0.1.6（2026-09-17）、v0.1.5（2026-09-10），约每周一版。README 显示 GitHub stars、open/closed issues 徽章（具体数值需验证）。最近提交日期 2026-10-08，开发活跃。

二、架构与代码地图

SGLang-Omni 在纵向上可以划分为五层。最上层是接入层（Serving Surface），由 sglang_omni/http/、sglang_omni/cli/、sglang_omni/client/ 以及前置的 sglang_omni_router/ 组成，负责把 OpenAI 兼容的 HTTP/WS 请求、CLI 命令、Python SDK 调用转成内部 StagePayload，并落到 admission 控制与 scheduler 队列里。第二层是调度层（Scheduling & Pipeline Orchestration），核心在 sglang_omni/scheduling/、sglang_omni/pipeline/、sglang_omni/admission.py，分别承载 OmniScheduler、EngineFactory、Stage 生命周期、跨阶段 KV/tensor 传输策略与准入控制。第三层是执行层（Model Execution），由 sglang_omni/model_runner/ 与 sglang_omni/models/<model_family>/ 构成：model_runner 把调度请求翻译成 SGLang 的 ForwardBatch/ScheduleBatch，每个模型族则提供 engine_builder.py、sglang_model.py、model_runner.py、stages.py 把自己的多阶段拓扑注册到框架里。第四层是硬件与传输层（Hardware & Transport），sglang_omni/platforms/、sglang_omni/mps/、sglang_omni_mlx/、sglang_omni/comm/ 把 CUDA、Apple Silicon MLX/MPS、XPU、NPU 的差异收敛成统一后端，comm/ 下 data_ref.py、kv_transfer.py、relay.py、stage_io.py 提供共享内存、NCCL、NIXL、Mooncake 四种 tensor 传输路径。第五层是工具与支撑层（Tooling & Profiling），sglang_omni/profiler/、sglang_omni/diagnostics/、sglang_omni/utils/、benchmarks/、tests/ 提供性能剖析、硬件诊断、回归基准与端到端测试。整个架构的关键思想是：SGLang 只负责单阶段 AR 调度与 kernel 执行，多阶段拓扑、阶段间传输、模型族适配、API 表面全部由 SGLang-Omni 自己拥有。

一次调用怎么流过这些模块

一次典型 /v1/audio/speech 请求的生命周期如下。第一步，HTTP 层 sglang_omni/http/ 把 multipart / JSON 请求反序列化，经过 sglang_omni/http/admin_auth.py 与媒体策略校验后，在 sglang_omni/admission.py 做准入控制，生成 StagePayload 并送入 sglang_omni_router（若部署了多 worker）或直连 sglang_omni/serve。第二步，sglang_omni/scheduling/omni_scheduler.py 的 OmniScheduler 收到请求，根据模型族对应的 stages.py 把请求分解成多个 SchedulerRequest，每个 SchedulerRequest 携带 ARRequestData 或对应的 payload_types.py 中的强类型数据（如 CosyVoice3SGLangRequestData、DotsTTSSGLangRequestData），进入对应阶段的队列。第三步，调度器通过 engine_factory.py 中对应的 TtsEngineBuilder（如 FunCosyVoice3EngineBuilder、HiggsTtsEngineBuilder、DotsTTSEngineBuilder）构造出 ModelWorker 与 ModelRunner；这些 EngineBuilder 在构造期调用 customize_server_args、generation_defaults 把自己的阶段需求（关闭 CUDA Graph、调整 mem_fraction_static、设定 max_running_requests）注入 SGLang 的 ServerArgs。第四步，进入执行循环：sglang_omni/model_runner/base.py 的 ModelRunner 把 SchedulerRequest 翻译成 SGLang 的 ScheduleBatch 与 ForwardBatch，由 sglang_model_runner.py / sglang_execution.py 调用上游 SGLang 的 GenerationBatchResult 完成 prefill 与 decode；每个阶段特有的逻辑（如 dots.tts 的 latent recurrence、Fun-CosyVoice3 的 token-hop streaming、FishAudio S2-Pro 的 codebook 输出收集）由对应模型族的 model_runner.py 在 before_prefill、post_prefill、post_decode、custom_prefill_forward 钩子中实现。第五步，阶段间 tensor 传输由 sglang_omni/comm/ 处理：data_ref.py 做零拷贝引用计数，kv_transfer.py 在 AR 阶段之间搬运 KV cache，relay.py 与 stage_io.py 根据部署选择共享内存、NCCL、NIXL 或 Mooncake 后端，把 talker 的 semantic token、vocoder 的 audio chunk 以 OutgoingMessage 形式推到下一阶段。第六步，最终阶段（vocoder / aggregator）把音频帧通过 streaming_vocoder.py 或 streaming.py 以流式方式经 HTTP WS 或 client/audio.py 推回客户端。关键调度点包括：admission 的并发上限、OmniScheduler 的阶段批化策略、SGLang 内部的 radix cache 与 chunked prefill 开关、以及 generation_batch_policy.py 中 CudaGraphBackend 的 batch size 选择。关键数据结构包括：StagePayload、SchedulerRequest、ARRequestData、RequestOutput、SchedulerOutput、ForwardBatch、ScheduleBatch、GenerationBatchResult，以及各模型族自定义的 payload_types.py。

关键类型与函数

扩展点

• 新模型族接入：在 sglang_omni/models/<new_family>/ 下新建目录，实现五件套：engine_builder.py（继承 AsrEngineBuilder 或 TtsEngineBuilder，在 customize_server_args / generation_defaults 注入阶段参数）、sglang_model.py（继承 SGLang 的模型基类）、model_runner.py（继承 ModelRunner，在 before_prefill / post_decode 等钩子实现特有逻辑）、stages.py（描述阶段拓扑与 StagePayload 映射）、request_builders.py（定义强类型请求数据）。现有最佳参考是 dots_tts/、fun_cosyvoice3/、fishaudio_s2_pro/、higgs_tts/、arkasr/、fun_asr/ 这六个族，它们的 engine_builder 都展示了如何把多阶段需求注入 SGLang。
• 新硬件后端接入：在 sglang_omni/platforms/ 下扩展 current_platform 的判断逻辑，并在 sglang_omni_mlx/（Apple Silicon）、sglang_omni/mps/（MPS）或新增 sglang_omni/xpu/ 目录下实现对应的 ModelWorker 与权重加载路径。pyproject_*.toml（pyproject_xpu.toml、pyproject_npu.toml、pyproject_rocm.toml、pyproject_musa.toml、pyproject_cpu.toml）已经给出了每种后端的依赖模板，新后端可参照添加条件依赖。sglang_omni/comm/ 的传输后端扩展需在 relay.py / stage_io.py 中注册新的 DataRef 传输方式。
• 新 kernel / 算子融合：kernel 级优化主要发生在两个位置：一是各模型族 model_runner.py 中的 custom_prefill_forward / before_prefill / post_decode 钩子，可插入自定义 Triton / CUDA kernel（如 Qwen3-Omni 最近提交 #2599 编译 MoE kernel、#2598 重叠 fused predictor、#2597 裁剪 MRoPE 元数据）；二是 sglang_omni_mlx/ 与 sglang_omni/mps/ 下的 Apple Silicon 适配层，可写 MLX 自定义 kernel。若需修改 SGLang 内核本身，应在上游 sglang 仓库贡献，SGLang-Omni 通过 sglang==0.5.21 固定版本消费。
• 新调度策略 / 传输策略：调度策略扩展点在 sglang_omni/scheduling/generation_batch_policy.py（CudaGraphBackend、prefill coalesce 策略）与 sglang_omni/scheduling/engine_factory.py（SchedulerExtras、GenerationDefaults）。传输策略扩展点在 sglang_omni/comm/router.py（选择 shmem / NCCL / NIXL / Mooncake）与 sglang_omni/comm/kv_transfer.py（KV 搬运调度）。准入控制扩展点在 sglang_omni/admission.py。

最近在动的地方

• sglang_omni/models/：提交热点 20 次/周，是所有目录中最活跃的；Qwen3-Omni、MiniCPM-o、CosyVoice3、MOSS-TTS、AuK 等模型族的内核级优化与零拷贝改造集中在此
• tests/unit_test/：提交热点 24 次/周，全仓库最高；说明项目处于重构期（README 提及 2026/8 TTS architecture refactor），测试在快速补强
• sglang_omni/preprocessing/：提交热点 4 次/周，输入管线仍在演化，与多模态模型接入直接相关
• sglang_omni_router/python/：Router 安全加固（#2581 admin key、#2583 profiler 鉴权）是最近提交重点，生产化关键路径
• sglang_omni/scheduling/：调度层提交活跃；engine_factory.py 与 generation_batch_policy.py 是模型族接入和性能调优的核心
• sglang_omni/pipeline/：README 明确 pipeline topology 是 SGLang-Omni 自己拥有的核心抽象，提交活跃说明拓扑描述仍在迭代
• sglang_omni/platforms/ 与 sglang_omni/comm/：XPU 提交 #2542 把共享 accelerator 助手从 torch.cuda 解耦；Apple Silicon MLX 路径在 pyproject.toml 中显式维护
• sglang_omni/models/arkasr/ 与 sglang_omni/models/fun_asr/：ASR 族（Arkasr、Fun-ASR）含 encoder_cuda_graph.py、encoder_service.py、torch_mps_runner.py，是 CUDA Graph 与 Apple Silicon 优化的重点

建议阅读顺序

1. README.md（项目定位、硬件支持矩阵、Quick Start）
2. sglang_omni/scheduling/engine_factory.py（EngineBuilder 抽象，理解模型族接入契约）
3. sglang_omni/scheduling/types.py（SchedulerRequest / ARRequestData / OutgoingMessage 等核心数据结构）
4. sglang_omni/model_runner/base.py（ModelRunner 基类，理解 prefill/decode 生命周期钩子）
5. sglang_omni/models/dots_tts/ 或 sglang_omni/models/fun_cosyvoice3/（选一个模型族完整读 engine_builder → sglang_model → model_runner → stages → request_builders 五件套）
6. sglang_omni/models/arkasr/ 或 sglang_omni/models/fun_asr/（ASR 族，理解 encoder_service 与 CUDA Graph 路径）
7. sglang_omni/comm/（data_ref.py、kv_transfer.py、relay.py、stage_io.py，理解跨阶段传输）
8. sglang_omni/platforms/ 与 sglang_omni_mlx/（硬件后端抽象，Apple Silicon 适配）
9. sglang_omni/http/ 与 sglang_omni_router/python/（接入层，理解请求入口与鉴权）
10. tests/unit_test/ 与 benchmarks/eval/（通过测试用例反推模块契约与性能基准）

三、本地跑起来（没有 GPU 的 Mac）

安装

1. # 1. 前置：Homebrew + Python 3.10–3.12（Apple Silicon 要求）
2. brew install uv
3. # 2. 克隆仓库
4. git clone https://github.com/sgl-project/sglang-omni.git && cd sglang-omni
5. # 3. 一键安装脚本（README Quick Start 明确指向）
6. # 内部会检测 arm64 + darwin，走 pyproject.toml 的 mlx/mlx-lm 分支，跳过 flashinfer_python[cu13]/flash-attn-4/nixl-cu13/mooncake-transfer-engine-cuda13/kernels 等 CUDA-only 依赖
7. ./install.sh
8. # 4. 失败回退：手动用 uv 创建 venv 并安装 Apple Silicon 子集
9. # pyproject.toml 中 Apple Silicon 专属依赖：mlx>=0.32.0, mlx-lm；CUDA 依赖通过 sys_platform != 'darwin' or platform_machine != 'arm64' 自动排除
10. uv venv --python 3.11 .venv && source .venv/bin/activate
11. uv pip install -e . --prerelease=allow
12. # 5. 验证安装（应看到 torch=2.13.0, transformers=5.12.1, sglang 从源码编译的 all_mps 变体, mlx 已安装）
13. python -c "import sglang_omni, torch, mlx; print('torch', torch.__version__); print('mlx ok')"
14. # 6. 跳过/不会装上的依赖（pyproject.toml 中 sys_platform 条件排除）：
15. # flashinfer_python[cu13]==0.6.18, flash-attn-4>=4.0.0b18, kernels>=0.14.1,<0.15,
16. # nixl-cu13>=1.1.0, mooncake-transfer-engine-cuda13>=0.3.10
17. # 这些是 CUDA relay/attention 后端，Apple Silicon 上 import 会直接报错，不要尝试安装

哪些路径能真跑

['# 能在 Apple Silicon / MPS / MLX 上真正执行的代码路径：', '# - sglang_omni_mlx/ 整个包：Qwen3-ASR 的 MLX 推理路径（README 明确 Apple Silicon 支持 Qwen3-ASR via MLX）', '# - sglang_omni/models/*/mlx/ 子模块：arkasr/mlx/, fun_cosyvoice3/mlx/, fun_asr/torch_mps_runner.py —— 这些是 Apple Silicon 专用 runner', '# - sglang_omni/model_runner/audio_mlx.py, audio_torch_mps.py —— MLX/MPS 音频执行器', '# - sglang_omni/mps/ —— Metal Performance Shaders 后端适配', "# - sglang_omni/models/fun_cosyvoice3/engine_builder.py 中 uses_torch_mps() 分支（device.type == 'mps' 时走 Torch MPS 而非 MLX）", '# - sglang_omni/models/fun_asr/torch_mps_runner.py —— Fun-ASR 的 MPS 实现', '# - sglang_omni_router/ —— Rust+Python 路由层，无 GPU 依赖，纯 CPU 可编译运行', '# - tests/unit_test/ —— 纯 Python 单元测试（调度逻辑、配置解析、payload 序列化）', '# - sglang_omni/config/ —— 配置系统，CPU 可跑', '# - sglang_omni/scheduling/ —— 调度逻辑（除 CUDA graph 相关）', '# - sglang_omni/pipeline/ —— pipeline 拓扑定义', '# - sglang_omni/profiler/, diagnostics/ —— 诊断工具（部分 GPU 相关功能会降级）', '#', '# 只能读代码或必须 Colab T4 验证的路径：', '# - 所有 *cuda_graph*.py：encoder_cuda_graph.py, step_cuda_graph.py, vocoder_cuda_graph.py, prefix_cuda_graph.py, whisper_prefill_cuda_graph_runner.py', '# - sglang_omni/comm/kv_transfer.py 中 NCCL 路径、relay.py 中 NIXL/Mooncake 后端', '# - sglang_omni/models/qwen3_omni/ 的 thinker/talker 内核（MoE compile、MRoPE 优化均为 CUDA 专属）', '# - sglang_omni/models/dots_tts/ 的 torch_compile 路径（configure_optimized_kernels）', '# - sglang_omni/models/fishaudio_s2_pro/ 的 Fast-AR attention（强制要求 SM89/90/100/120 + flashinfer）', '# - sglang_omni/models/higgs_tts/ 的 CUDA graph 路径', '# - sglang_omni/platforms/ 中 CUDA 后端的具体 kernel 调用', '# - benchmarks/ 下所有 eval 脚本（均需真实 GPU 推理）']

最小可运行

1. # 冒烟测试 1：验证 Apple Silicon 上 Qwen3-ASR MLX 路径可 import 并加载模型（README 明确这是 Apple Silicon 主打功能）
2. python -c "from sglang_omni_mlx import qwen3_asr; print('Qwen3-ASR MLX module loaded')"
3. # 冒烟测试 2：验证 Torch MPS 音频 runner 可实例化（不跑推理，只验 import 和设备检测）
4. python -c "from sglang_omni.model_runner.audio_torch_mps import *; print('Torch MPS audio runner import ok')"
5. # 冒烟测试 3：验证 Fun-ASR Torch MPS runner 路径（sglang_omni/models/fun_asr/torch_mps_runner.py 存在）
6. python -c "from sglang_omni.models.fun_asr.torch_mps_runner import FunASRTorchMpsModelRunner; print('FunASR MPS runner import ok')"
7. # 冒烟测试 4：验证 CosyVoice3 MLX 子模块可 import（fun_cosyvoice3/mlx/ 目录存在）
8. python -c "from sglang_omni.models.fun_cosyvoice3.mlx import model as cv3_mlx_model; print('CosyVoice3 MLX import ok')"
9. # 冒烟测试 5：验证配置系统 CPU 可跑（无 GPU 依赖）
10. python -c "from sglang_omni.config.manager import ConfigManager; cm = ConfigManager(); print('ConfigManager init ok')"
11. # 冒烟测试 6：验证 sglang_omni_router Python 层可 import（Rust 部分需单独编译）
12. python -c "from sglang_omni_router.python import *; print('Router Python layer import ok')" # 需验证具体导出

测试

['# 测试框架：pytest（tests/ 目录 610 文件，含 test_ci/, test_model/, unit_test/, utils/）', '# 目录结构：', '# tests/unit_test/ —— 纯 CPU 单元测试（调度、配置、payload、序列化）', '# tests/test_ci/ —— CI 专用测试', '# tests/test_model/ —— 模型级测试（多数需 GPU）', '# tests/utils/ —— 测试工具', '# tests/data/ —— 测试数据', '#', '# 只跑 CPU 子集（Apple Silicon 推荐）：', "pytest tests/unit_test/ -x -v --timeout=120 -k 'not gpu and not cuda and not trt'", '# 预估耗时：unit_test 子集在 16GB MacBook Air 上约 5–15 分钟（取决于是否触发模型下载）', '#', '# 跳过 GPU 测试的标记（需验证具体 marker 名称）：', '# 查看 pytest.ini 或 conftest.py 中是否有 @pytest.mark.gpu / @pytest.mark.cuda', '# 若无显式 marker，用 -k 排除关键词过滤', '#', '# 注意：tests/test_model/ 下多数测试会尝试 import flashinfer 或 CUDA 相关模块，', '# 在 Apple Silicon 上会 collect error，建议只跑 unit_test/']

调试

• # 日志开关：
• # SGLANG_OMNI_LOG_LEVEL=DEBUG —— 全局日志级别（需验证环境变量名）
• # sglang 自身：SGLANG_LOG_LEVEL=DEBUG
• # 各 model_runner 模块使用标准 logging.getLogger(__name__)，可通过 logging.basicConfig(level=DEBUG) 开启
• #
• # 断点入口（关键类和方法）：
• # - sglang_omni/scheduling/omni_scheduler.py:OmniScheduler.schedule() —— 多阶段调度主循环
• # - sglang_omni/pipeline/ 下各 Stage 的 process() 方法 —— 单阶段执行
• # - sglang_omni/model_runner/base.py:ModelRunner.before_prefill/post_prefill/post_decode —— 模型执行钩子
• # - sglang_omni/comm/data_ref.py —— 跨阶段 tensor 传输的共享内存路径（CPU 可断点）
• # - sglang_omni_mlx/qwen3_asr/ —— Apple Silicon MLX 推理入口
• #
• # Profiling 入口：
• # - sglang_omni/profiler/ —— 内置性能剖析工具
• # - sglang_omni/diagnostics/gpu.py —— GPU 诊断（Apple Silicon 上部分功能降级）
• # - .claude/skills/omni-gpu-deep-dive/scripts/omni_trace_pair.py —— 提交轨迹追踪脚本
• # - benchmarks/runtime_metrics.py —— 运行时指标采集
• #
• # 环境变量（需验证）：
• # SGLANG_OMNI_MLX_DEVICE=1 —— 强制使用 MLX 后端（Apple Silicon）
• # SGLANG_DISABLE_CUDA_GRAPH=1 —— 禁用 CUDA graph（CPU/MPS 调试时）
• # Metal/MPS 相关：PYTORCH_MPS_HIGH_WATERMARK_RATIO=0.0 —— 调整 MPS 内存上限

CI

['# CI 系统：GitHub Actions（.github/workflows/ 下多个 workflow，.github/scripts/ 含辅助脚本）', '# 关键 CI 脚本：', '# .github/scripts/pr_ci_gate.py —— PR 门禁逻辑', '# .github/scripts/verify_omni_installed_pins.py —— 验证依赖 pin 一致性', '# .github/scripts/omni_missing_dependencies.py —— 缺失依赖检测', '# .github/update_ci_permission.py —— CI 权限管理', '#', '# 多后端 CI 矩阵（docker/ 目录对应）：', '# Dockerfile（CUDA 默认）、cpu.Dockerfile、musa.Dockerfile、npu.Dockerfile、rocm.Dockerfile、xpu.Dockerfile', '# CI 会分别在这些镜像中跑测试', '#', '# PR 会被卡住的检查（推测，需看 workflows 文件名确认）：', '# 1. pre-commit：isort、check_if_else.py、check_leading_underscore.py 等代码风格检查', '# 2. unit_test 子集必须在 CPU 上通过', '# 3. 依赖 pin 一致性检查（verify_omni_installed_pins.py）', '# 4. 多后端构建验证（CUDA/XPU/NPU/ROCm 各自有 CI job）', '# 5. 可能有的 docs 构建检查（docs/ 含 Makefile 和 serve.sh）', '#', '# Apple Silicon 相关 CI：需确认是否有 macOS arm64 runner（README 标 Experimental，可能无专属 CI）']

坑

• # 坑 1：sglang PyPI wheel 的 CUDA 依赖是 unconditional 的
• # pyproject.toml 注释明确说：'SGLang's PyPI wheel has unconditional CUDA dependencies, so Apple Silicon installs this exact tag from source with the all_mps extra'
• # 解决：必须用 install.sh 或从源码编译 sglang 的 all_mps extra，不能直接 pip install sglang
• #
• # 坑 2：flashinfer_python[cu13] 的 cubin wheel 问题
• # pyproject.toml 注释：'Do NOT add flashinfer-cubin: PyPI has no matching cubin, and any leftover cubin wheel fails MiniMax DIT import'
• # 在 Apple Silicon 上这些会被 sys_platform 条件排除，但如果你手动改 pyproject 或混用 pip install 可能触发
• #
• # 坑 3：torch==2.13.0 和 transformers==5.12.1 是硬 pin
• # 这是为了匹配 sglang 的 pinned stack，不要随意升级，否则 sglang 内部会 break
• #
• # 坑 4：Apple Silicon 上 Qwen3-ASR 是唯一官方支持的端到端推理路径
• # README Hardware Support 表：'Apple Silicon | Experimental | Qwen3-ASR runs through native MLX or Torch MPS'
• # 其他模型（Qwen3-Omni, dots.tts, FishAudio S2-Pro 等）在 Apple Silicon 上无法跑推理，只能读代码
• #
• # 坑 5：MLX 和 Torch MPS 路径的切换逻辑不透明
• # fun_cosyvoice3/engine_builder.py 中 uses_torch_mps() 依赖 sglang.srt.hardware_backend.mlx.runtime.use_mlx() 的返回值
• # 如果 MLX 库存在但 device 是 mps，会走 Torch MPS；否则走 MLX。切换逻辑需要读源码确认，无文档说明
• #
• # 坑 6：tests/test_model/ 在 Apple Silicon 上会大量 collect error
• # 这些测试会 import flashinfer、CUDA graph 相关模块，在 macOS 上 import 阶段就失败
• # 建议只跑 tests/unit_test/，不要跑全量 pytest tests/
• #
• # 坑 7：sglang_omni_router 的 Rust 部分需要独立编译
• # sglang_omni_router/ 含 rust/ 子目录，需要 cargo 工具链
• # 如果只跑 Python 层，需确认 python/ 子目录的纯 Python fallback 是否完整
• #
• # 坑 8：16GB 内存限制对 unit_test 的影响
• # 部分 unit_test 可能加载小模型或 mock 权重，16GB 可能紧张
• # 建议用 -k 过滤 + --timeout 限制，避免 OOM
• #
• # 坑 9：cache-dit==1.3.0 和 addict==2.4.0 是 hard import 不是 optional
• # pyproject.toml 注释：'hard import, not optional'
• # 这两个包在 Apple Silicon 上也会被安装，如果它们有 CUDA 依赖可能会 import error（需验证）
• #
• # 坑 10：CONTRIBUTING 文件为空字符串（仓库 evidence 中 contributing 字段为空）
• # 项目可能依赖 AGENTS.md / CLAUDE.md 中的 coding style 指南
• # 修改代码前必须读 .claude/skills/code-review/coding-style.md（AGENTS.md 明确要求）

四、维护者与社区

高频迭代。最近三个 PyPI release 集中在 2026-09：v0.1.5（09-10）、v0.1.6（09-17）、v0.1.7（09-28），间隔约 7–10 天，呈周级发版节奏。提交活动集中在 2026-10-08 当天，单日至少 12 个 PR 合入，热点全部是 Qwen3-Omni 内核性能优化（#2597 MRoPE 元数据裁剪、#2598 predictor 重叠发射、#2599 MoE kernel compile）、MiniCPM-o HiFT decode compile（#2518）、CosyVoice3 / MOSS-TTS 跨阶段零拷贝（#2555、#2525）、Router 安全修复（#2581、#2583）。仓库整体处于活跃的产品化冲刺阶段。

流程与 Review 风格

仓库没有独立的 CONTRIBUTING.md（根目录、docs/ 下均未见，contributing 字段为空）。从现有证据推断的贡献流程：1）鼓励先开 Issue 讨论——仓库大量使用 [Roadmap]、[RFC]、[Tracking]、[Runtime Profiling]、[Feature]、[Bug] 前缀的 Issue 模板（见 .github/ISSUE_TEMPLATE 目录），几乎所有工作都先落到一个 Issue 再开 PR；2）PR 标题沿用 [Perf]、[Fix]、[Feature]、[XPU]、[Apple]、[MiniCPM-o]、[Router] 等前缀，与 Issue 标签体系对齐；3）pre-commit 已配置（仓库根有 .pre-commit-config.yaml，docs/README.md 明确要求「Run pre-commit run --all-files before opening a PR」）；4）CI 权限与代码归属由 .github/CODEOWNERS、CI_PERMISSIONS.json、update_ci_permission.py 管理；5）未发现 CLA / DCO 文件（需验证：仓库根目录仅有 LICENSE，未提及 CLA 或 DCO 签署流程）。

从近期 PR 与提交推断：响应速度快（10-08 当天密集合入多个 perf PR），review 聚焦具体技术点——如 #2597–#2599 三个 Qwen3-Omni perf commit 是同一工作被拆成三个细粒度 PR 分别合入，说明维护者偏好小而精、可独立验证的 PR；安全类修复（#2581 Router admin key、#2583 profiler routes）同样快速合入。路线图类 Issue（#1754、#1883、#2459）评论数高达 10–27 条，说明设计阶段讨论充分，但一旦进入实现则 PR 拆分很细。整体风格偏「先 Issue 对齐 → 小 PR 快速迭代 → 性能可量化验证」。

渠道

• https://slack.sglang.io
• https://github.com/sgl-project/sglang-omni/issues
• https://github.com/sgl-project/sglang-omni/pulls
• https://sgl-project.github.io/sglang-omni/developer_reference/main.html

这里的规矩

• 得体：1）先开 Issue 对齐方案再写代码，尤其是新模型支持、新硬件后端、架构重构类工作——仓库里 [RFC]、[Roadmap]、[Tracking] 前缀的 Issue 是标准入口；2）PR 标题使用 [Perf]/[Fix]/[Feature]/[XPU]/[Apple] 等前缀，与现有标签体系保持一致；3）性能类 PR 附带可量化的 benchmark 数据（从 #2597–#2599 等 perf commit 推断，维护者关注具体收益）；4）提交前跑 pre-commit run --all-files（docs/README.md 明确要求）；5）小步拆分，避免巨型 monolithic PR。
• 不得体：1）跳过 Issue 讨论直接提大型重构 PR；2）在 Apple Silicon 上尝试安装 CUDA-only 依赖（flashinfer_python[cu13]、flash-attn-4、nixl-cu13、mooncake-transfer-engine-cuda13、kernels）——pyproject.toml 已通过 sys_platform 条件排除这些依赖，强行安装会直接报错；3）在 Issue / PR 中不标注复现步骤或性能数据；4）忽视 CODEOWNERS 与 CI 权限配置。

维护者现在最想要的帮助

• Runtime Profiling 与性能优化：多个活跃 Issue 明确在招人做模型级 profiling——#1882（Dots-TTS）、#1883（Fun-CosyVoice3）、#1988（Fish Speech S2-Pro）、#2273（MiniCPM-o 4.5）、#2559（Nemotron-VoiceChat P0 pipeline profiling）、#2580（MiniCPM-o 4.5 Video-AMME runtime profiling）。这是当前最密集的需求方向，与候选人 GPU kernel / 训练性能工程背景高度契合。
• Apple Silicon 支持扩展：Issue #1967「Apple Silicon support roadmap」有 23 条评论，assignee 为 AkazaAkane，目前仅 Qwen3-ASR 有 MLX 路径（sglang_omni_mlx/qwen3_asr），急需把更多模型族（尤其是 TTS / Omni）迁到 MLX/MPS 后端。候选人目前只有 MacBook Air，这是最现实的切入点。
• 新模型族集成：#2574（Irodori-TTS）、#2207（LLaDA-Uni）、#1864（Cosmos 3）、#2458（PersonaPlex）、#2459（Nemotron-VoiceChat 11b）均在跟踪新模型支持。
• 全双工（Full Duplex）会话：#1909、#2559、#2561（Recoverable Unit Failures for Full-Duplex Sessions）显示这是架构级优先事项。
• 多硬件后端：#1588（Intel XPU H2'26）、#1598（MUSA）、#2076（Ascend NPU）、#2416（AMD ROCm）——项目在积极扩展非 CUDA 后端。
• 代码质量与风格治理：#2195「Roadmap: Coding Style」显示维护者在推动统一编码规范。

五、切入方案

它现在缺什么（你无 GPU 也能补）

第一批 PR

怎么知道自己站住了

• 第一个 PR 在 2 周内被合并，且收到 maintainer 正面反馈
• 在 Slack 被邀请加入 Apple Silicon 相关讨论或 working group
• Apple Silicon 相关 Issue 被 assign 给你
• 你的 Apple Silicon 测试/基准 PR 被纳入 CI
• 成功跑通至少一个非 Qwen3-ASR 模型族的 Apple Silicon 端到端流程
• 获得 triage 或 reviewer 权限
• 你的移植指南或文档被引用到其他 PR 或 Issue 中