FAQ
起router失败
router需要检查prefill和decoder的health，必须都有返回
如果下面打印完这一步不打印了，则手工检查prefill和decoder的health
2025-10-15 10:45:11 INFO sglang_router_rs::server: src/server.rs:561: Starting router on 0.0.0.0:31000 | mode: PrefillDecode { prefill_urls: [("http://10.202.5.87:30000", None)], decode_urls: ["http://10.202.5.42:30000"], prefill_policy: None, decode_policy: None } | policy: CacheAware { cache_threshold: 0.3, balance_abs_threshold: 64, balance_rel_threshold: 1.5, eviction_interval_secs: 120, max_tree_size: 67108864 } | max_payload: 512MB
2025-10-15 10:45:11 INFO sglang_router_rs::server: src/server.rs:662: Single router mode (enable_igw=false)
2025-10-15 10:45:11 INFO sglang_router_rs::routers::http::router: src/routers/http/router.rs:202: Waiting for 2 workers to become healthy (timeout: 600s)
检查health
# IP换为PD的主节点IP的端口
curl http://10.202.5.27:30000/health
curl http://10.202.5.38:30000/health
#如果不能正常访问则说明有问题 同时检查没有正常结束的节点日志有没有打印报错日志
# 日志可能如下
[2025-10-15 10:47:27] Health check failed. Server couldn't get a response from detokenizer for last 20 seconds. tic start time: 10:47:07. last_heartbeat time: 09:44:42
这种情况说明 detokenizer 服务未启动，重启整个服务即可解决。
如果 Router 显示 "Timeout 600s waiting for workers [xxxxxx] to become healthy"，而 Prefill 和 Decode Server 可以正常访问，则是启动太慢导致 Router 健康检查超时，请单独重启 Router。
PD分离 RDMA 注册失败
首先检查驱动配置有无输出5555。以及mt-peer是否安装。
# 检查KMD配置
cat /sys/module/mtgpu/parameters/tp_pci_vender_id
# 结果应输出5555
# 检查mt_peermem是否安装
lsmod | grep mt_peermem
# 正常结果显示类似以下内容
# mt_peermem 16384 0
# mtgpu 4210688 17 mt_peermem
# ib_core 401408 9 rdma_cm,ib_ipoib,mt_peermem,iw_cm,ib_umad,rdma_ucm,ib_uverbs,mlx5_ib,ib_cm
驱动文件配置丢失（Segmentation fault ）
在卸载驱动后，mtgpu.conf文件的配置会被清除，导致部署decode节点时会出现如下报错：
musa failed with an illegal memory access was encountered
Fatal Python error: Segmentation fault
只需重新添加mtgpu.conf文件即可解决。
triton 算子不匹配
torch._dynamo.exc.BackendCompilerFailed: backend='inductor' raised:
TypeError: AttrsDescriptor.__init__() got an unexpected keyword argument 'divisible_by_16'
Set TORCHDYNAMO_VERBOSE=1 for the internal stack trace (please do this especially if you're reporting a bug to PyTorch). For even more developer context, set TORCH_LOGS="+dynamo"
[2026-05-27 18:34:22] Scheduler or DataParallelController 1880936 terminated with -3
一般发生在重装triton后，清理缓存即可：
rm -rf ~/.triton/cache/ && rm -rf /tmp/*
DEEPEP_MODE=low_latency 模式异常
若出现以下错误：
init failed for transport: IBGDAillegal memory accessSegmentation fault
建议处理顺序：
- 先切换 Decode 配置
DEEPEP_MODE=normal，重启服务恢复在线。 - 参考 GPU 内核模块参数配置 是否已写入,
modinfo mtgpu参数是否匹配。 - 参考 网卡检测 ，检查
--disaggregation-ib-device与ibdev2netdev是否一致。 - 再按需开启
DEEPEP_MODE=low_latency并做小流量验证。
MCCL bootstrap/connect 错误
多机服务启动后，MCCL 通信卡死/超时/通信 abort，打开 MCCL_DEBUG=INFO 后能看到 bootstrap/connect 类警告，或者日志尝试连接 IP 是 127.0.0.1或 172.17.x（docker0 段）而不是节点私网 IP ：
Bootstrap: no socket interface found / cannot connect / Connection refused / Network is unreachableTransport NetSocket: connection failed / timeout
因为 MCCL 在 bootstrap/控制面阶段需要用一个 Socket 接口做节点间握手与通信。当机器存在多网卡，或进程跑在容器/K8s overlay 网络里时，自动探测可能选中"有 IP 但不可达对端节点"的接口，于是建连失败或直接 hang。建议参考业务网络网卡检测在启动容器或在部署脚本中显式设置环境变量：
export MCCL_SOCKET_IFNAME=bond0
如果 MCCL INFO 显示 NET/IB : No Device found. ，请联系技术支持确定网卡是否和软件已做好适配。
mtshmem failed 导致 deep ep dispatch报错
服务日志显示 mtshmem failed to open shared memory slab，导致后面在执行到deep ep的时候dispatch报错。
可在 Prefill 和 Decode 启动脚本中加上 NVSHMEM_DEBUG=INFO NVSHMEM_DEBUG_SUBSYS=ALL 两个环境变量。如果 NVSHMEM INFO 日志中（ host name：xxxx hash xxxxxxxxxx），不同机器的 host hash 完全一致，则会导致MPI等工具无法用，mtshmem比mccl先启动，如果mccl启动也会报一样的错。联系运维把 host name 配成不一样的值。
