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-llmmesh-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/statusWeb 控制台为http://localhost:3131。 网络类问题问题 1~5问题 1节点之间互相发现不了加入 mesh 总是失败症状mesh-llm serve --auto找不到任何可用 meshmesh-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。问题 2Docker 或多网卡主机连到了错误的网卡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。问题 5WSL2 / 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。问题 7GPU 识别不到或跑到了错误的计算后端症状mesh-llm gpus输出为空或 CPU 上龟速运行。原因驱动/后端未装好或默认后端选择不符合本机硬件。解决办法mesh-llm gpus # 查看识别到的 GPU mesh-llm gpus detect # 刷新硬件指纹、带宽、算力提示NVIDIA 需要nvccAMD 需要 ROCm/HIPVulkan 需要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-existingtune会扫描 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-layersrevision --split mesh-llm doctor split --model-ref meshllm/Qwen3-8B-Q4_K_M-layers --port 3131doctor split会解释哪些 peer 合格、哪些被排除以及下一步操作加--output-dir dir可导出完整诊断包。问题 10模型一直不出现在/v1/modelsstage 不 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_TRANSFERtrusted mesh-llm serve --model hf://meshllm/reporevision --split问题 11长上下文冷启动请求返回 HTTP 504症状大模型冷 prefille 阶段请求超时返回 504 Gateway Timeout但日志显示原生推理正常。原因冷启动 prefille 耗时可能超过 OpenAI 前端 300 秒的非流式后端截止时间。解决办法改用流式请求。流式会在 prefille 完成前就建立响应同时能把客户端取消传递给生成 workercurl -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 --jsoncertify会校验解析、manifest 形状、分片大小/SHA、tokenizer/projector 侧车文件与本地物化。锁定拓扑时节点选择器必须唯一解析、层范围必须连续覆盖0..layer_countJSON 文件需在每台节点上保持一致。缓存空间不足时用mesh-llm models prune --yes清理派生物化缓存活动中的 stage 会被保护。 排查工具箱速查场景命令 / 入口总体状态curl http://localhost:3131/api/status网络发现mesh-llm discover --name my-meshGPU 指纹mesh-llm gpus detect拆分诊断mesh-llm doctor split --model-ref pkg --port 3131包预检skippy-model-package preflight ./model-package --verify-sha256运行验证mesh-llm models certify hf://meshllm/reporev --api-base http://127.0.0.1:9337性能调优mesh-llm benchmark tune --model /models/x.gguf --apply缓存清理mesh-llm models prune --yes更完整的运维手册见 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考