intentee/paddler · 上手攻略

• 仓库：intentee/paddler
• 链接：https://github.com/intentee/paddler
• 分类：ai / llm-infra / serving
• 作者：spark
• 更新：2026-07-28

是什么

Paddler 是一款用 Rust 写的开源 LLM/VLM 推理负载均衡与服务平台。架构非常克制：只有两个组件——balancer（对外暴露 OpenAI 兼容推理接口、管理面和 Web 控制台）和 agent（真正跑推理，注册到 balancer 上即可上线）。底层直接用 llama.cpp 推理引擎（fork 版本，Paddler 自己实现了 slot 管理来保留每个 slot 独立的 context / KV cache）。

它和 vLLM、TGI、llm-d 这类项目的目标类似（自托管、可横向扩、OpenAI API 兼容），但官方刻意把"会动的零件"压到最少：

• 单二进制分发，paddler balancer / paddler agent 两条命令就能跑起来。
• 走 llama.cpp / ggml 生态，CPU 和 GPU 都能用，GGUF 模型直接喂进来。
• Agent 动态加入 / 离开，balancer 自动调度；支持请求缓冲，因此可以从 0 实例冷启动。
• 内置 Web 管理面板（监控、模型切换、聊天模板 / 推理参数调整、对话试跑）。
• 提供 Embedding 端点（多模态 / VLM 也已支持）。

项目自定位是 "less moving parts and simple deployments"——在 llm-d、vLLM、TGI 之外提供一个"几分钟就能搭起来、组件数量一只手数得过来"的自托管选项。

解决什么问题

当你希望把 LLM 推理搬到自己的机器上，但又不想维护一整套 Kubernetes + vLLM + Ingress + Prometheus 的组合时，Paddler 想压扁这条链路。它主要解决：

1. 自托管门槛：vLLM、TGI 多数场景要 Python 环境 + GPU 驱动 + K8s；Paddler 只给两个二进制和一个 Web UI。
2. 私有 / 合规 / 成本可控：医疗、金融等场景需要"模型不离场、可审计、按 GPU 小时计价"，而不是按 token 计费的 SaaS。
3. 冷启动 / 弹性伸缩：内置请求缓冲（request buffering），允许下游 agent 从 0 起拉起。
4. 多模态 / VLM 支持：在 llama.cpp 路线下同时提供文本生成、Embedding、VLM 推理。
5. 桌面 / 办公混合部署：官方提供桌面端（CLI + GUI），可以把同事的 RTX 5090 临时挂上来当一个 agent。

快速安装

Paddler 是单二进制，没有 Docker 强依赖，部署路径非常短。

# 1) 下载最新二进制（Linux x86_64 示例）
VERSION=$(curl -s https://api.github.com/repos/intentee/paddler/releases/latest \
  | grep -oE '"tag_name":\s*"[^"]+"' | head -1 | cut -d'"' -f4)
curl -L -o paddler \
  "https://github.com/intentee/paddler/releases/download/${VERSION}/paddler-${VERSION}-linux-amd64"
chmod +x paddler && sudo mv paddler /usr/local/bin/

# 2) 准备一个 GGUF 模型文件，放到所有 agent 都能读到的路径
#    例如把 Hugging Face 上的 Qwen2.5-7B-Instruct 的 gguf 拉到 /opt/models/qwen2.5-7b-instruct-q4_k_m.gguf

如果要从源码构建（MSRV 是 1.88.0）：

git clone https://github.com/intentee/paddler.git
cd paddler
cargo build --release
./target/release/paddler --help

核心用法

1. 起一个最小集群

Balancer（对外暴露 OpenAI 兼容推理端点 + 管理面 + 可选 Web 管理面板）：

paddler balancer \
  --inference-addr      127.0.0.1:8061 \
  --management-addr     127.0.0.1:8060 \
  --web-admin-panel-addr 127.0.0.1:8062

• 8061：对外的 OpenAI 兼容推理端口（应用从这里调）。
• 8060：balancer 与 agent 之间的管理 / 心跳端口。
• 8062：Web 管理面板（可选，但开起来会很方便排查）。

Agent（在另一台机器或同机的另一个进程）：

paddler agent \
  --management-addr 127.0.0.1:8060 \
  --slots 4

--slots 表示这台机器同时并发处理的请求数，等价于 llama.cpp 的并行槽位。每个 slot 各自保留自己的 context 和 KV cache。

当 agent 跑在远端机器上时，把 --management-addr 指向 balancer 的 IP，并确保 8060 端口在网内可达。

2. 加载模型 + 调整推理参数

加载模型和设置 chat template 在 Web 管理面板里最直观；命令行 / API 走 paddler 的管理接口也行：

# 拉取模型元数据 / 上传 gguf（参考 docs 里的 management API）
curl -X POST http://127.0.0.1:8060/v1/models \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "qwen2.5-7b-instruct",
    "path": "/opt/models/qwen2.5-7b-instruct-q4_k_m.gguf",
    "chat_template": "chatml",
    "context_length": 8192
  }'

具体字段以 docs（paddler.intentee.com/docs）的最新 management API 为准，上面只是示意。

3. 调用推理（OpenAI 兼容）

Paddler 暴露的是 OpenAI 兼容协议，应用层接入零成本：

curl http://127.0.0.1:8061/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "qwen2.5-7b-instruct",
    "messages": [
      {"role": "user", "content": "用一句话解释 RaBitQ 是什么"}
    ]
  }'

from openai import OpenAI

client = OpenAI(base_url="http://127.0.0.1:8061/v1", api_key="not-needed")
resp = client.chat.completions.create(
    model="qwen2.5-7b-instruct",
    messages=[{"role": "user", "content": "用一句话解释 RaBitQ 是什么"}],
)
print(resp.choices[0].message.content)

Embedding 端点走 /v1/embeddings，多模态 / VLM 走 /v1/chat/completions 配合 image_url。

4. 多 agent 横向扩展

只需要在新的机器上跑 paddler agent --management-addr <balancer>:8060 --slots N，balancer 会自动发现并调度；agent 离线时，balancer 把请求 buffer 在队列里，等新 agent 起来再分发——这是它"scaling from zero hosts"的卖点，对低频 / 弹性场景尤其有用。

5. Web 管理面板

打开 http://127.0.0.1:8062，能直接：

• 看每个 agent 的 slot 利用率、活跃请求数。
• 切换模型 / 调整 chat template、temperature、top_p 等。
• 在 UI 里直接跑对话测试。

对小团队 / 内部工具非常省事。

典型适用场景

• 小到中型自托管推理平台：1~10 台 GPU 机器，没有专职平台团队，希望"上午决定上、下午跑通"。
• 合规 / 成本敏感行业：医疗、金融、政企，要求"模型部署在自有网络内、按 GPU 小时算账、可观测可审计"。
• 冷启动型负载：低 QPS 业务、办公时间集中流量、希望闲时为 0 实例。
• 混合设备 GPU 池：研发团队每个人都有 4090/5090，想把闲时算力聚合成一个共享集群。Paddler 桌面端正是为这种场景设计的。
• 需要同时跑 Embedding + VLM + Chat Completion：因为底层是 llama.cpp + 自定义 slot，多模态和 embedding 都能直接用。

不太适合：

• 需要 GPU 张量并行、Pipeline 并行的大模型训练级部署：Paddler 是单机多 slot 的横向扩展，不替代 Megatron / DeepSpeed。
• 要求生产级 K8s 集成、Prometheus exporter 完善：vLLM / TGI 在生态上更成熟，Paddler 在监控指标和 operator 上仍偏轻。

坑与注意

1. 生态还在成长期：相对 vLLM、TGI，Paddler 周边（operator、Helm chart、第三方 exporter、benchmark）数量少很多；如果你已经在 K8s 上重度依赖 Helm/Operator，可能要自己写一层包装。
2. MSRV 较新（1.88.0）：从源码构建要求 Rust 工具链 ≥ 1.88，老发行版要先升级。
3. Slot 数和显存是硬约束：--slots 不是"想开几个开几个"，而是要按 (KV cache per slot × slots) ≤ 显存余量 估算；模型上下文越长，单 slot 占用越高。
4. 模型加载走 Web / Management API，不是命令行 flag：第一次跑时容易在 CLI 里翻不到 --model 参数——它故意把模型管理放进管理面板和 API 里，方便动态切换。
5. 从 0 拉起 = 第一次延迟高：冷启动时第一个请求要等 agent 拉起 + 模型加载，记得给前端加"正在准备"提示。
6. OpenAI 兼容 ≠ 完全兼容：少数 SDK 高级特性（structured outputs / vision 边角）要实测一下，尤其是 VLM 走 image_url 的输入格式。
7. GGUF 模型选择：Paddler 走 llama.cpp 路线，所以只能喂 GGUF；Hugging Face 原始 safetensors 需要先用 llama.cpp 的转换脚本导出。
8. 安全：默认 balancer / agent 之间没有 mTLS，生产内网要靠网络策略隔离；管理端口 8060 不要直接对外暴露。

与同类对比

如果你的目标是"今天就上线一个能用的自托管推理平台"，Paddler 是当前最省心的；如果你的目标是"在大规模生产里做弹性推理 + 完善可观测性"，vLLM / TGI / llm-d 的生态更厚。

一句话推荐结论

想要"十分钟搭起来一个自托管 LLM 服务"的最低摩擦路线，比 vLLM/TGI 简单得多，比 Ollama 更适合多机集群——前提是接受 llama.cpp 生态和轻量级监控。