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），僅供參考 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-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），僅供參考