predibase/lorax · 上手攻略

仓库：predibase/lorax
链接：https://github.com/predibase/lorax
分类：engineering（LLM 推理服务 / Multi-LoRA）
作者：spark
更新：2026-07-17

是什么

LoRAX（LoRA eXchange）是 Predibase 开源的 多 LoRA 适配器推理服务器，目标是在一张 GPU 上同时服务成百上千个微调后的 LLM，而吞吐和延迟几乎不打折。它通过"动态加载适配器 + 异构连续批处理 + 适配器交换调度"三大机制，让一份基座模型（如 Mistral-7B、Llama-3、Qwen）被数千个不同任务的 LoRA 适配器复用。许可 Apache-2.0，stars 约 3.8k。

它和 vLLM、TGI（Text Generation Inference）属于同一类基础推理引擎，但 LoRAX 的核心差异点是把"多 adapter 共存"当成一等公民，而不是事后兼容特性。

解决什么问题

LLM 微调后常见部署困境：

每个微调模型都是一份独立服务——一个客服场景 1 个 LoRA，5 个场景就 5 份副本，显存爆炸。
冷启动延迟——临时加载一份 LoRA 要几秒到几十秒，业务不可接受。
不同 adapter 之间无法批处理——传统框架按请求路由到对应 worker，跨 adapter 没法合并 batch，吞吐严重浪费。
运维复杂——1000 个模型配 1000 个 K8s deployment 是不现实的。

LoRAX 用一个统一服务器接受任意带 adapter_id 的请求，运行时即时加载/卸载 adapter，并对不同 adapter 的请求做"异构连续批处理"——同一 batch 里既有 base-only 的请求，也有 adapter A 的、adapter B 的，互不阻塞。底层用了 SGMV（Segmented Matrix-Vector Multiplication）、flash-attention、paged attention 等优化。

快速安装

硬件前置条件

NVIDIA GPU（Ampere 架构及以上，即 A100 / A10 / 4090 / L4 等；不支持 Turing 及更早）
驱动支持 CUDA 11.8+
Linux（macOS / Windows 不支持）
建议先装 nvidia-container-toolkit

路径 A：Docker（最稳）

官方预编译镜像包含 CUDA kernel，无需自己编译：

sudo systemctl daemon-reload
sudo systemctl restart docker

model=mistralai/Mistral-7B-Instruct-v0.1
volume=$PWD/data

docker run --gpus all --shm-size 1g -p 8080:80 -v $volume:/data \
  ghcr.io/predibase/lorax:main --model-id $model

--shm-size 1g 必须给，否则 PyTorch DataLoader 多 worker 会爆共享内存。镜像首次跑会下载基座权重，请预留磁盘（Mistral-7B ~14GB，Llama-3-8B ~16GB）。

路径 B：Kubernetes

官方提供 Helm chart：

helm repo add lorax https://predibase.github.io/lorax
helm install lorax lorax/lorax \
  --set model.id=mistralai/Mistral-7B-Instruct-v0.1

详细参数和持久化配置见 Kubernetes Getting Started。

路径 C：从源码构建

需要 CUDA Toolkit 11.8+、PyTorch 2.x、若干编译依赖，时间和坑都比较多，生产环境不建议走源码路线，调试或魔改时才用。

核心用法

1. 调基座模型（REST）

服务起来后，监听 :8080：

curl 127.0.0.1:8080/generate -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": "<s> 写一首关于秋天的诗。 </s>",
    "parameters": {"max_new_tokens": 128, "temperature": 0.7}
  }'

注意 Mistral / Llama 这种指令微调过的模型要在 inputs 前后包特殊 token（<s>、[INST]...[/INST] 等），README 里 README 为了避坑用了 [REMOVED_SPECIAL_TOKEN] 占位说明这一点。

2. 调指定 LoRA adapter

curl 127.0.0.1:8080/generate -X POST \
  -H 'Content-Type: application/json' \
  -d '{
    "inputs": "<s> 用一句话解释 transformer </s>",
    "parameters": {
      "max_new_tokens": 64,
      "adapter_id": "username/my-finetuned-adapter",
      "adapter_source": "hub"   # hub=HF Hub, predibase=Predibase 平台, local=本地路径
    }
  }'

第一次请求会即时拉取 adapter 并加载到 GPU 缓存，后续相同 adapter 的请求复用内存；超过容量时调度器把最久未用的 adapter 异步卸载到 CPU 内存或本地磁盘。

3. OpenAI 兼容聊天 API

服务监听 /v1/chat/completions，可以无缝替换 OpenAI 客户端：

from openai import OpenAI
client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="not-used")

resp = client.chat.completions.create(
    model="mistralai/Mistral-7B-Instruct-v0.1",
    messages=[{"role": "user", "content": "你好"}],
    extra_body={"adapter_id": "my-org/zh-style-adapter"},
)
print(resp.choices[0].message.content)

4. Python 客户端

pip install lorax-client

from lorax import Client
client = Client("http://127.0.0.1:8080")

out = client.generate(
    "<s> 写一个 Python 快速排序 </s>",
    max_new_tokens=128,
    adapter_id="my-org/code-adapter",
)
print(out.generated_text)

5. Adapter merge / 集成

支持把多个 LoRA 在请求时 merge 成"组合超能力"——例如 base + 中文风格 + 客服语气：

{
  "inputs": "...",
  "parameters": {
    "adapter_id": "zh-style-adapter",
    "merges": [{"adapter_id": "support-tone-adapter", "weight": 0.7}]
  }
}

典型适用场景

多租户 / 多业务线 SaaS：一份基座 + N 个客户微调出来的 LoRA，按请求动态切换。
A/B 评测平台：同一 base 并行 100+ 实验性 adapter，无需重启服务。
客服 / 教育 / 营销等垂类微调：每个客户 / 课程 / 品牌一份 LoRA，几十到上千份共存。
研究团队共享 GPU 池：避免"一人独占一份 vLLM"。
JSON Mode / 结构化输出（/generate 的 response_format 字段，2024+ 已稳定）。

坑与注意

仓库活跃度：从 README / issues 看，2026 年起社区活跃度明显放缓，新 issue 创建已被 restrict，最近 commit 在 2026-05-28 附近（采集自卡片）。Predibase 的工程重心看起来转向了商业平台 Ludwig / Predibase Cloud。生产选型前请确认是否能接受"上游响应慢"，并准备好 fork 维护。
GPU 架构限制：必须是 Ampere（A100/A10/3090/4090 等），Turing（T4/V100）不支持 flash-attention 2，跑不起来或极慢。
adapter 数量≠ 无限：物理显存减去 base model 后剩余多少就能 cache 多少 adapter，超出会异步 swap 到 CPU/磁盘，吞吐会下降。建议监控 /metrics 上 adapter cache hit rate。
adapter 格式：必须用 PEFT 或 Ludwig 训练出来的标准 LoRA，full fine-tune 的权重不能当 adapter 用。
特殊 token 处理：Mistral / Llama 系列的 chat template 要自己拼或用 tokenizer，apply_chat_template 不能直接复用 OpenAI 客户端。
认证 / 多租户：LoRAX 支持 per-request tenant 隔离，但需要在请求里带 api_key 或自定义 header；生产部署务必打开。
JSON mode 和 streaming 同时使用：早期版本有 bug，需要 >=0.5.x 才稳定。

与同类对比

项目	强项	弱项	适合
LoRAX	多 adapter 共存、一份基座服务上千 LoRA	社区活跃度 2026 起下行	多 LoRA 场景的核心方案
vLLM	通用推理性能 SOTA，LoRA 支持近年加入	多 adapter 同时服务能力弱于 LoRAX	单一 / 少量 adapter 场景
TGI（HuggingFace）	易部署、HuggingFace 生态完善	多 adapter 调度不是设计目标	快速上线、HF 用户
SGLang	RadixAttention、前端 DSL 强	LoRA 多 adapter 模式相对新	复杂 prompt 程序
OpenLLM	BentoML 生态、上手快	性能与多 LoRA 调度不及 LoRAX	简单部署 + BentoML 用户
llama.cpp / llama-server	CPU/量化/边缘推理	多 LoRA 调度能力有限	本地、低资源

一句话推荐结论

LoRAX 是"单 GPU 服务上千 LoRA"场景目前最成熟的开源方案；2026 年社区活跃度走低是最大风险点，建议选型时同步评估 vLLM 的 --enable-lora 多 adapter 模式作为备份。