Mesh-LLM/mesh-llm

Mesh LLM 可将跨机器的 GPU 和内存资源汇聚起来，并统一通过 http://localhost:9337/v1 提供与 OpenAI 兼容的 API。你可以先启动一个节点，后续随时添加更多节点。Mesh 系统会自动决策模型是在本地运行、路由至对等节点（Peer），还是利用 Skippy 分段技术（Stage splits）来运行超出单机负载的超大模型。

快速入门

安装最新版本：

curl -fsSL https://raw.githubusercontent.com/Mesh-LLM/mesh-llm/main/install.sh | bash

加入公共 Mesh 网络并开始服务：

mesh-llm serve --auto

该命令会自动选择后端配置，根据需要下载合适的模型，加入最佳的已发现公共 Mesh，在 9337 端口启动本地 API，并在 3131 端口启动 Web 控制台。

查看可用模型：

curl -s http://localhost:9337/v1/models | jq '.data[].id'

发送一个与 OpenAI 兼容的请求：

curl http://localhost:9337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"GLM-4.7-Flash-Q4_K_M","messages":[{"role":"user","content":"hello"}]}'

对于服务器部署，添加 --headless 参数可以在隐藏 Web UI 的同时，保持管理 API 在 --console 端口运行：

mesh-llm serve --auto --headless

选择你需要的操作流程

目标	命令	完整指南
尝试公共 Mesh	mesh-llm serve --auto	docs/MESHES.md
启动私有 Mesh	mesh-llm serve --model Qwen3-8B-Q4_K_M	docs/MESHES.md
发布你自己的 Mesh	mesh-llm serve --model Qwen3-8B-Q4_K_M --publish	docs/MESHES.md
通过邀请令牌加入	mesh-llm serve --join	docs/MESHES.md
运行仅 API 客户端	mesh-llm client --auto	docs/MESHES.md
运行带有分段的大模型	mesh-llm serve --model hf://meshllm/@ --split	docs/SKIPPY_SPLITS.md
挂载 Flash-MoE SSD 后端	带有 [[plugin]] name = "flash-moe" 的 mesh-llm serve	docs/plugins/flash-moe.md
将一个提示词分发给 Mesh 中的所有模型	curl ... -d '{"model":"mesh", ...}'	docs/design/MOA_GATEWAY.md
使用 Goose, OpenCode, Claude Code 或 Pi	mesh-llm goose, mesh-llm opencode, mesh-llm claude, mesh-llm pi	docs/AGENTS.md
构建或贡献代码	just build	CONTRIBUTING.md

Mesh 的工作原理

• 优先单机部署。 如果单节点能够容纳整个模型，它将在本地运行，无需产生分段流量。
• Mesh 路由。 每个节点都暴露相同的 /v1 API。请求会根据 model 字段路由至能够服务该模型的对等节点。
• 所有者控制平面。 操作员配置和库存操作使用附加的 mesh-llm-control/1 通道，并带有显式的端点引导；而公共 Mesh 的加入、Gossip 协议、路由和推理则保留在公共 Mesh 平面上，以实现不同版本间的兼容性。
• Skippy 分段（Stage splits）。 大型密集模型可以作为基于包的层级片段加载。协调器规划连续的层范围，优先启动下游片段，等待其就绪后，再发布 stage-0 路由。
• 层级包（Layer packages）。 包仓库包含 model-package.json 以及 GGUF 片段，因此对等节点仅需获取其分配的片段所需的部分。
• 公共发现。 已发布的 Mesh 通过 Nostr 协议进行广告发现；私有 Mesh 则基于邀请令牌。

欲了解更深入的操作指南，请参阅 docs/USAGE.md。有关所有 CLI 命令和选项，请参阅 docs/CLI.md。

智能体混合（Mixture-of-Agents，model: "mesh"） — 实验性功能

⚠️ 实验性功能。 MoA 网关在此版本中为全新功能。在我们进行调优的过程中，行为、路由启发式算法、错误信息结构和调优参数可能会在不同版本间发生变化。请将 model: "mesh" 视为预览功能，而非稳定的生产环境路径；在需要语义稳定的场景下，请使用特定的模型 ID。

发送带有 "model": "mesh" 的请求，代理会将请求并行分发给 Mesh 中所有可用的模型，通过确定性逻辑仲裁其响应，并返回一个与 OpenAI 兼容的回复。仲裁器在代码中运行（而非作为另一个模型调用），仅在出现真正冲突时才升级至 LLM 归约器（Reducer）。工具调用会贯穿整个处理流程。

curl http://localhost:9337/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"mesh","messages":[{"role":"user","content":"What is the capital of Japan?"}]}'

需要 Mesh 中至少有两个不同的模型。有关架构、仲裁规则和调优参数，请参阅 docs/design/MOA_GATEWAY.md。

支持的模型系列

Mesh LLM 的 Skippy 运行时跟踪 llama.cpp 系列的兼容性，并经过了 GGUF 认证代表模型的验证。目前经过验证的支持集涵盖了 72 个 P0/P1 系列，在完整兼容性清单中包含 89 个认证系列。