mesh-llm 故障排查手册：网络、GPU 与拆分失败的 12 个常见问题

mesh-llm 故障排查手册：网络、GPU 与拆分失败的 12 个常见问题

【免费下载链接】mesh-llmDistributed AI/LLM for the people. Share compute privately or publicly to power your agents and chat.项目地址: https://gitcode.com/gh_mirrors/me/mesh-llm

mesh-llm 故障排查手册来了！mesh-llm 是一款把多台机器的 GPU 和内存池化、对外暴露 OpenAI 兼容 API 的分布式 AI/LLM 平台，默认在http://localhost:9337/v1提供服务。当模型太大单机放不下时，它会自动启用 Skippy 分层拆分。但不少新手在组网、显存分配和拆分环节频频踩坑。本文整理了 mesh-llm 网络、GPU 与拆分失败的 12 个高频问题，从症状、原因到修复命令一次讲清。

排查前先确认基础环境：执行mesh-llm setup完成初始化，用mesh-llm serve --auto启动服务。状态接口为http://localhost:3131/api/status，Web 控制台为http://localhost:3131。

📶 网络类问题（问题 1~5）

问题 1：节点之间互相发现不了，加入 mesh 总是失败

症状：mesh-llm serve --auto找不到任何可用 mesh，mesh-llm discover列表为空。

原因：默认发现机制走 Nostr relay（公网中继）；如果节点在纯内网、Nostr 被墙或中继不可达，就看不到已发布的 mesh。

解决办法：

# 局域网内改用 mDNS 发现，启动时仅限 LAN mesh-llm serve --mesh-discovery-mode mdns mesh-llm discover --name "my-mesh"

私有 mesh 必须使用邀请令牌：mesh-llm serve --join <token>。详细说明见 docs/MESHES.md。

问题 2：Docker 或多网卡主机连到了错误的网卡（172.17.0.1）

症状：节点明明在同一内网，却互相连不上；日志里出现 Docker bridge 地址172.17.0.1或 CNI 地址。

原因：在docker run --network host或带多个网卡的 Linux 主机上，iroh 可能发现并广播了 Docker/CNI 桥接地址。若每台宿主机桥接地址相同，peer 就会抢占错误的本地网桥而非真实管理网络。

解决办法：显式指定主机间通信的 IP 和端口：

# 种子节点 mesh-llm serve --split --bind-ip 10.1.2.3 --bind-port 47916 --model Qwen3-8B-Q4_K_M # 工作节点 mesh-llm serve --split --join <token> --model Qwen3-8B-Q4_K_M

注意：--listen-all只影响本地 HTTP API/控制台监听，不负责选择 mesh QUIC 网卡，别搞混。

问题 3：控制台或 API 端口打不开、请求超时

症状：curl http://localhost:3131或:9337/v1/models无响应。

原因：端口被占用，或服务以--headless模式隐藏了 UI。

解决办法：

mesh-llm serve --auto --headless # 隐藏 UI 但管理 API 仍可用 curl -s http://localhost:3131/api/status | jq . curl -s http://localhost:3131/api/discover | jq .

/api/status会报告 mesh 发布状态（private/public/publish_failed），是判断服务是否健康的第一入口。

问题 4：云服务器上节点被判定为 relay-only，无法参与拆分

症状：拆分规划时某节点被排除，提示只能走 relay 中继，拆分迟迟不开始。

原因：云厂商对容器 UDP 端口做了 NAT 重映射，邀请令牌广播的地址不可直连。relay-only 节点会被故意排除出拆分计划（拆分需要低延迟直连 UDP 路径）。

解决办法：确认邀请令牌广播的是可达的公网端点，并在模型加载前先验证运行时诊断显示为 direct path。使用低延迟、可直接访问的 UDP 路径；详见 docs/skippy/WAN_SPLIT_PERF.md。

问题 5：WSL2 / Windows 下 CUDA 或局域网组网失败

症状：Windows 上mesh-llm serve无法识别 GPU，或 WSL2 里节点连不上局域网其他机器。

原因：WSL2 的网络是 NAT 虚拟化，与宿主机默认网段不同；CUDA 13+ 等新特性也要求特定 WSL2 配置。

解决办法：先在 WSL2 内执行mesh-llm gpus确认后端可见；多节点组网时给每个节点指定--bind-ip <lan-ip>和--bind-port，并在 Windows 防火墙放行 QUIC/UDP。Windows 下可用 PowerShell 收集诊断包：

.\contrib\windows\CollectSplitDiagnostics.ps1 ` -Model meshllm/Qwen3-8B-Q4_K_M-layers ` -ConsoleUrls http://127.0.0.1:3131 ` -ApiUrls http://127.0.0.1:9337/v1

🎮 GPU 类问题（问题 6~8）

问题 6：显存不足，启动时直接失败或 OOM

症状：启动时报does not fit/ 显存溢出，模型无法加载。

原因：模型（权重 + KV cache + 运行时工作区 + 安全余量）超出单卡或单机容量。mesh-llm 在--local-model-only模式下启动失败时不会自动降级为分布式服务，必须主动指定容量或拆分。

解决办法：

# 限制最大显存占用（单位 GB），让调度器重新规划 mesh-llm serve --split --model meshllm/Qwen3-8B-Q4_K_M-layers --max-vram 5

建议先用mesh-llm gpus detect刷新真实硬件指纹与带宽，再参照 docs/specs/vram-accounting.md 计算容量。显存预算的判定规则详见 docs/CLI.md。

问题 7：GPU 识别不到，或跑到了错误的计算后端

症状：mesh-llm gpus输出为空，或 CPU 上龟速运行。

原因：驱动/后端未装好，或默认后端选择不符合本机硬件。

解决办法：

mesh-llm gpus # 查看识别到的 GPU mesh-llm gpus detect # 刷新硬件指纹、带宽、算力提示

NVIDIA 需要nvcc，AMD 需要 ROCm/HIP，Vulkan 需要glslc开发文件；CPU-only 与 Jetson/Tegra 也受支持，详见 docs/USAGE.md 中的后端说明。

问题 8：拆分推理慢，吞吐远低于预期

症状：分词吞吐（tok/s）低，响应延迟高。

原因：上下文窗口、批量大小、KV cache 策略、flash attention、投机解码等参数未调优。

解决办法：用内置基准自动调参并写回配置：

mesh-llm benchmark tune --model /models/qwen3-8b.gguf mesh-llm benchmark tune --model /models/qwen3-8b.gguf --apply --replace-existing

tune会扫描 ctx/batch/ubatch/mmap/mlock/flash-attention/投机解码组合，推荐吞吐最高且上下文最大的方案。注意：不要把节点大小只按包字节数和显存估算，还要预留足够的系统内存给运行时工作区，否则拆分规划会严重失衡。

🔀 拆分失败类问题（问题 9~12）

问题 9：拆分时 coordinator 只看到自己一个节点

症状：mesh-llm doctor split显示只有本机是有效拆分参与者。

原因：其他节点未用同一个层包模型启动，或节点选择器无法唯一解析（多个节点用了相同主机名 / endpoint id）。

解决办法：

# 所有参与节点必须使用同一个层包模型和相同的 --split 参数 mesh-llm serve --model hf://meshllm/Qwen3-235B-A22B-UD-Q4_K_XL-layers@<revision> --split mesh-llm doctor split --model-ref meshllm/Qwen3-8B-Q4_K_M-layers --port 3131

doctor split会解释哪些 peer 合格、哪些被排除，以及下一步操作；加--output-dir <dir>可导出完整诊断包。

问题 10：模型一直不出现在/v1/models，stage 不 ready

症状：curl http://localhost:9337/v1/models看不到拆分模型。

原因：Skippy 拆分的启动顺序是「下游/final 层先加载 → 全部 stage 就绪 → 才发布 stage 0 路由」。只要有一个 stage 未就绪，模型就不会出现在模型列表。

解决办法：检查每个节点的状态：

curl -sS http://127.0.0.1:3232/api/status | jq '{state:.node_state, ready:.llama_ready, peers:(.peers|length), stages:.runtime.stages}' curl -sS http://127.0.0.1:9447/v1/models | jq '.data[].id'

确保所有节点使用一致的上下文分配（如--ctx-size 131072）和同一层包引用；镜像下载慢可开启可信环境的 peer 传输：

MESH_LLM_ARTIFACT_TRANSFER=trusted mesh-llm serve --model hf://meshllm/<repo>@<revision> --split

问题 11：长上下文冷启动请求返回 HTTP 504

症状：大模型冷 prefille 阶段请求超时，返回 504 Gateway Timeout，但日志显示原生推理正常。

原因：冷启动 prefille 耗时可能超过 OpenAI 前端 300 秒的非流式后端截止时间。

解决办法：改用流式请求。流式会在 prefille 完成前就建立响应，同时能把客户端取消传递给生成 worker：

curl -sS http://127.0.0.1:9447/v1/chat/completions \ -H 'Authorization: Bearer mesh' \ -d '{"model":"meshllm/Qwen3-8B-Q4_K_M-layers","stream":true,"messages":[{"role":"user","content":"hi"}]}'

问题 12：节点掉线导致拓扑撤回，或包校验失败

症状：拆分运行中某节点宕机后，整个模型不可用；或certify/preflight校验不通过。

原因：锁定拓扑（--split-topology-lock）下，锁定的 stage 丢失后拓扑会整体撤回并进入不可用状态，不会折叠为本地回退；包校验失败通常是 manifest 摘要、分片大小或 SHA 不匹配。

解决办法：上线前先做包级预检与运行时验证：

skippy-model-package preflight ./model-package --stages 2 --verify-sha256 mesh-llm models certify hf://meshllm/Qwen3-8B-Q4_K_M-layers --package-only --report-out cert.json mesh-llm models certify hf://meshllm/Qwen3-8B-Q4_K_M-layers --api-base http://127.0.0.1:9337 --json

certify会校验解析、manifest 形状、分片大小/SHA、tokenizer/projector 侧车文件与本地物化。锁定拓扑时节点选择器必须唯一解析、层范围必须连续覆盖0..layer_count，JSON 文件需在每台节点上保持一致。缓存空间不足时用mesh-llm models prune --yes清理派生物化缓存（活动中的 stage 会被保护）。

🧰 排查工具箱速查

更完整的运维手册见 docs/USAGE.md，逐命令参考 docs/CLI.md，拆分部署细节见 docs/SKIPPY_SPLITS.md，组网与发布见 docs/MESHES.md。记住一条核心心法：拆分调试先看/api/status与/api/runtime/stages，网络问题先查--bind-ip与发现模式，显存问题先跑gpus detect再谈参数。按这 12 个问题逐项对照，大多数 mesh-llm 故障都能在十分钟内定位解决。

【免费下载链接】mesh-llmDistributed AI/LLM for the people. Share compute privately or publicly to power your agents and chat.项目地址: https://gitcode.com/gh_mirrors/me/mesh-llm