mesh-llm 故障排查手冊(cè)網(wǎng)絡(luò)、GPU 與拆分失敗的 12 個(gè)常見問題【免費(fèi)下載鏈接】mesh-llmDistributed AI/LLM for the people. Share compute privately or publicly to power your agents and chat.項(xiàng)目地址: https://gitcode.com/gh_mirrors/me/mesh-llmmesh-llm 故障排查手冊(cè)來了mesh-llm 是一款把多臺(tái)機(jī)器的 GPU 和內(nèi)存池化、對(duì)外暴露 OpenAI 兼容 API 的分布式 AI/LLM 平臺(tái)默認(rèn)在http://localhost:9337/v1提供服務(wù)。當(dāng)模型太大單機(jī)放不下時(shí)它會(huì)自動(dòng)啟用 Skippy 分層拆分。但不少新手在組網(wǎng)、顯存分配和拆分環(huán)節(jié)頻頻踩坑。本文整理了 mesh-llm 網(wǎng)絡(luò)、GPU 與拆分失敗的 12 個(gè)高頻問題從癥狀、原因到修復(fù)命令一次講清。排查前先確認(rèn)基礎(chǔ)環(huán)境執(zhí)行mesh-llm setup完成初始化用mesh-llm serve --auto啟動(dòng)服務(wù)。狀態(tài)接口為http://localhost:3131/api/statusWeb 控制臺(tái)為http://localhost:3131。 網(wǎng)絡(luò)類問題問題 1~5問題 1節(jié)點(diǎn)之間互相發(fā)現(xiàn)不了加入 mesh 總是失敗癥狀mesh-llm serve --auto找不到任何可用 meshmesh-llm discover列表為空。原因默認(rèn)發(fā)現(xiàn)機(jī)制走 Nostr relay公網(wǎng)中繼如果節(jié)點(diǎn)在純內(nèi)網(wǎng)、Nostr 被墻或中繼不可達(dá)就看不到已發(fā)布的 mesh。解決辦法# 局域網(wǎng)內(nèi)改用 mDNS 發(fā)現(xiàn)啟動(dòng)時(shí)僅限 LAN mesh-llm serve --mesh-discovery-mode mdns mesh-llm discover --name my-mesh私有 mesh 必須使用邀請(qǐng)令牌mesh-llm serve --join token。詳細(xì)說明見 docs/MESHES.md。問題 2Docker 或多網(wǎng)卡主機(jī)連到了錯(cuò)誤的網(wǎng)卡172.17.0.1癥狀節(jié)點(diǎn)明明在同一內(nèi)網(wǎng)卻互相連不上日志里出現(xiàn) Docker bridge 地址172.17.0.1或 CNI 地址。原因在docker run --network host或帶多個(gè)網(wǎng)卡的 Linux 主機(jī)上iroh 可能發(fā)現(xiàn)并廣播了 Docker/CNI 橋接地址。若每臺(tái)宿主機(jī)橋接地址相同peer 就會(huì)搶占錯(cuò)誤的本地網(wǎng)橋而非真實(shí)管理網(wǎng)絡(luò)。解決辦法顯式指定主機(jī)間通信的 IP 和端口# 種子節(jié)點(diǎn) mesh-llm serve --split --bind-ip 10.1.2.3 --bind-port 47916 --model Qwen3-8B-Q4_K_M # 工作節(jié)點(diǎn) mesh-llm serve --split --join token --model Qwen3-8B-Q4_K_M注意--listen-all只影響本地 HTTP API/控制臺(tái)監(jiān)聽不負(fù)責(zé)選擇 mesh QUIC 網(wǎng)卡別搞混。問題 3控制臺(tái)或 API 端口打不開、請(qǐng)求超時(shí)癥狀curl http://localhost:3131或:9337/v1/models無響應(yīng)。原因端口被占用或服務(wù)以--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會(huì)報(bào)告 mesh 發(fā)布狀態(tài)private/public/publish_failed是判斷服務(wù)是否健康的第一入口。問題 4云服務(wù)器上節(jié)點(diǎn)被判定為 relay-only無法參與拆分癥狀拆分規(guī)劃時(shí)某節(jié)點(diǎn)被排除提示只能走 relay 中繼拆分遲遲不開始。原因云廠商對(duì)容器 UDP 端口做了 NAT 重映射邀請(qǐng)令牌廣播的地址不可直連。relay-only 節(jié)點(diǎn)會(huì)被故意排除出拆分計(jì)劃拆分需要低延遲直連 UDP 路徑。解決辦法確認(rèn)邀請(qǐng)令牌廣播的是可達(dá)的公網(wǎng)端點(diǎn)并在模型加載前先驗(yàn)證運(yùn)行時(shí)診斷顯示為 direct path。使用低延遲、可直接訪問的 UDP 路徑詳見 docs/skippy/WAN_SPLIT_PERF.md。問題 5WSL2 / Windows 下 CUDA 或局域網(wǎng)組網(wǎng)失敗癥狀Windows 上mesh-llm serve無法識(shí)別 GPU或 WSL2 里節(jié)點(diǎn)連不上局域網(wǎng)其他機(jī)器。原因WSL2 的網(wǎng)絡(luò)是 NAT 虛擬化與宿主機(jī)默認(rèn)網(wǎng)段不同CUDA 13 等新特性也要求特定 WSL2 配置。解決辦法先在 WSL2 內(nèi)執(zhí)行mesh-llm gpus確認(rèn)后端可見多節(jié)點(diǎn)組網(wǎng)時(shí)給每個(gè)節(jié)點(diǎn)指定--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顯存不足啟動(dòng)時(shí)直接失敗或 OOM癥狀啟動(dòng)時(shí)報(bào)does not fit/ 顯存溢出模型無法加載。原因模型權(quán)重 KV cache 運(yùn)行時(shí)工作區(qū) 安全余量超出單卡或單機(jī)容量。mesh-llm 在--local-model-only模式下啟動(dòng)失敗時(shí)不會(huì)自動(dòng)降級(jí)為分布式服務(wù)必須主動(dòng)指定容量或拆分。解決辦法# 限制最大顯存占用單位 GB讓調(diào)度器重新規(guī)劃 mesh-llm serve --split --model meshllm/Qwen3-8B-Q4_K_M-layers --max-vram 5建議先用mesh-llm gpus detect刷新真實(shí)硬件指紋與帶寬再參照 docs/specs/vram-accounting.md 計(jì)算容量。顯存預(yù)算的判定規(guī)則詳見 docs/CLI.md。問題 7GPU 識(shí)別不到或跑到了錯(cuò)誤的計(jì)算后端癥狀mesh-llm gpus輸出為空或 CPU 上龜速運(yùn)行。原因驅(qū)動(dòng)/后端未裝好或默認(rèn)后端選擇不符合本機(jī)硬件。解決辦法mesh-llm gpus # 查看識(shí)別到的 GPU mesh-llm gpus detect # 刷新硬件指紋、帶寬、算力提示NVIDIA 需要nvccAMD 需要 ROCm/HIPVulkan 需要glslc開發(fā)文件CPU-only 與 Jetson/Tegra 也受支持詳見 docs/USAGE.md 中的后端說明。問題 8拆分推理慢吞吐遠(yuǎn)低于預(yù)期癥狀分詞吞吐tok/s低響應(yīng)延遲高。原因上下文窗口、批量大小、KV cache 策略、flash attention、投機(jī)解碼等參數(shù)未調(diào)優(yōu)。解決辦法用內(nèi)置基準(zhǔn)自動(dòng)調(diào)參并寫回配置mesh-llm benchmark tune --model /models/qwen3-8b.gguf mesh-llm benchmark tune --model /models/qwen3-8b.gguf --apply --replace-existingtune會(huì)掃描 ctx/batch/ubatch/mmap/mlock/flash-attention/投機(jī)解碼組合推薦吞吐最高且上下文最大的方案。注意不要把節(jié)點(diǎn)大小只按包字節(jié)數(shù)和顯存估算還要預(yù)留足夠的系統(tǒng)內(nèi)存給運(yùn)行時(shí)工作區(qū)否則拆分規(guī)劃會(huì)嚴(yán)重失衡。 拆分失敗類問題問題 9~12問題 9拆分時(shí) coordinator 只看到自己一個(gè)節(jié)點(diǎn)癥狀mesh-llm doctor split顯示只有本機(jī)是有效拆分參與者。原因其他節(jié)點(diǎn)未用同一個(gè)層包模型啟動(dòng)或節(jié)點(diǎn)選擇器無法唯一解析多個(gè)節(jié)點(diǎn)用了相同主機(jī)名 / endpoint id。解決辦法# 所有參與節(jié)點(diǎn)必須使用同一個(gè)層包模型和相同的 --split 參數(shù) 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會(huì)解釋哪些 peer 合格、哪些被排除以及下一步操作加--output-dir dir可導(dǎo)出完整診斷包。問題 10模型一直不出現(xiàn)在/v1/modelsstage 不 ready癥狀curl http://localhost:9337/v1/models看不到拆分模型。原因Skippy 拆分的啟動(dòng)順序是「下游/final 層先加載 → 全部 stage 就緒 → 才發(fā)布 stage 0 路由」。只要有一個(gè) stage 未就緒模型就不會(huì)出現(xiàn)在模型列表。解決辦法檢查每個(gè)節(jié)點(diǎn)的狀態(tài)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確保所有節(jié)點(diǎn)使用一致的上下文分配如--ctx-size 131072和同一層包引用鏡像下載慢可開啟可信環(huán)境的 peer 傳輸MESH_LLM_ARTIFACT_TRANSFERtrusted mesh-llm serve --model hf://meshllm/reporevision --split問題 11長上下文冷啟動(dòng)請(qǐng)求返回 HTTP 504癥狀大模型冷 prefille 階段請(qǐng)求超時(shí)返回 504 Gateway Timeout但日志顯示原生推理正常。原因冷啟動(dòng) prefille 耗時(shí)可能超過 OpenAI 前端 300 秒的非流式后端截止時(shí)間。解決辦法改用流式請(qǐng)求。流式會(huì)在 prefille 完成前就建立響應(yīng)同時(shí)能把客戶端取消傳遞給生成 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節(jié)點(diǎn)掉線導(dǎo)致拓?fù)涑坊鼗虬ｒ?yàn)失敗癥狀拆分運(yùn)行中某節(jié)點(diǎn)宕機(jī)后整個(gè)模型不可用或certify/preflight校驗(yàn)不通過。原因鎖定拓?fù)?-split-topology-lock下鎖定的 stage 丟失后拓?fù)鋾?huì)整體撤回并進(jìn)入不可用狀態(tài)不會(huì)折疊為本地回退包校驗(yàn)失敗通常是 manifest 摘要、分片大小或 SHA 不匹配。解決辦法上線前先做包級(jí)預(yù)檢與運(yùn)行時(shí)驗(yàn)證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會(huì)校驗(yàn)解析、manifest 形狀、分片大小/SHA、tokenizer/projector 側(cè)車文件與本地物化。鎖定拓?fù)鋾r(shí)節(jié)點(diǎn)選擇器必須唯一解析、層范圍必須連續(xù)覆蓋0..layer_countJSON 文件需在每臺(tái)節(jié)點(diǎn)上保持一致。緩存空間不足時(shí)用mesh-llm models prune --yes清理派生物化緩存活動(dòng)中的 stage 會(huì)被保護(hù)。 排查工具箱速查場(chǎng)景命令 / 入口總體狀態(tài)curl http://localhost:3131/api/status網(wǎng)絡(luò)發(fā)現(xiàn)mesh-llm discover --name my-meshGPU 指紋mesh-llm gpus detect拆分診斷mesh-llm doctor split --model-ref pkg --port 3131包預(yù)檢skippy-model-package preflight ./model-package --verify-sha256運(yùn)行驗(yàn)證mesh-llm models certify hf://meshllm/reporev --api-base http://127.0.0.1:9337性能調(diào)優(yōu)mesh-llm benchmark tune --model /models/x.gguf --apply緩存清理mesh-llm models prune --yes更完整的運(yùn)維手冊(cè)見 docs/USAGE.md逐命令參考 docs/CLI.md拆分部署細(xì)節(jié)見 docs/SKIPPY_SPLITS.md組網(wǎng)與發(fā)布見 docs/MESHES.md。記住一條核心心法拆分調(diào)試先看/api/status與/api/runtime/stages網(wǎng)絡(luò)問題先查--bind-ip與發(fā)現(xiàn)模式顯存問題先跑gpus detect再談參數(shù)。按這 12 個(gè)問題逐項(xiàng)對(duì)照大多數(shù) mesh-llm 故障都能在十分鐘內(nèi)定位解決?！久赓M(fèi)下載鏈接】mesh-llmDistributed AI/LLM for the people. Share compute privately or publicly to power your agents and chat.項(xiàng)目地址: https://gitcode.com/gh_mirrors/me/mesh-llm創(chuàng)作聲明：本文部分內(nèi)容由AI輔助生成（AIGC），僅供參考