xLLM-AI/xllm · 上手攻略

  • 仓库：xLLM-AI/xllm
  • 链接：https://github.com/xLLM-AI/xllm
  • 分类：llm-infra / ai
  • 作者：Jay
  • 更新：2026-07-10

是什么

xLLM 是由京东零售团队开发、现托管于 OpenAtom 基金会的高性能 LLM 推理引擎。它不是面向普通用户的 AI 产品，而是给企业级部署场景用的底层 Infra 工具——目标是让大模型的推理在特定 AI 加速器上跑得更快、更划算。

支持的模型类型不只有 LLM，还包括： - LLM（大语言模型） - VLM（视觉语言模型） - DiT（扩散Transformer，图像生成类） - REC（推荐模型）

核心差异化在于：xLLM 对国产 AI 加速器（如昇腾等）做了深度优化，是国产硬件环境下部署大模型的一个可选方案。

⚠️ 注意：本指南基于 2026 年 7 月公开信息编写。该项目成熟度标注为 research，部分 API 和功能可能随版本变化，建议以 GitHub 最新 Release 为准。

解决什么问题

企业级大模型推理面临的几个核心挑战：

  1. 国产硬件适配：主流开源推理框架（vLLM、TGI）对国产加速器的支持不够完善，xLLM 填补了这个空白
  2. 推理效率：PD（Prefill-Decode）分离架构、动态调度、投机推理等技术，提升吞吐量、降低延迟
  3. 在线离线混合部署：生产环境通常同时有实时请求和批处理任务，xLLM 的服务层支持统一调度
  4. 多模态支持：不只是 LLM，还支持 VLM、DiT、REC 多种模型类型，统一框架管理

技术架构概览

xLLM 采用服务层与引擎层分离（service-engine decoupled）的设计：

服务层（xLLM-Service）

负责请求调度、资源管理、故障容错： - 弹性调度：在线/离线请求统一调度，在线请求优先执行 - 动态 PD 分离（Prefill-Decode Disaggregation）：根据负载自适应调整 prefill 和 decode 的资源配比 - EPD 混合机制：Encode-Prefill-Decode 分离，专门针对多模态输入优化 - 故障容错：实例错误快速检测、自动重调度

引擎层（xLLM Core）

负责具体计算： - 多流并行计算（Multi-stream Parallel Computing） - 算子图融合优化（Graph Fusion Optimization） - 投机推理（Speculative Inference）：用小模型预测、大模型验证，加速生成 - 动态负载均衡 - 全局 KV Cache 管理

快速安装

⚠️ 安装细节（版本 V1.0 附近）需以 GitHub 最新 Release 为准，以下为基于公开文档的结构性说明，实际安装前请务必查看 GitHub 仓库 的最新 README 和 Quick Start 说明。

方式一：pip 安装（推荐个人/开发测试）

pip install xllm

方式二：从源码编译（推荐生产部署）

git clone https://github.com/xLLM-AI/xllm.git
cd xllm
# 详细编译步骤见仓库 BUILD.md 或 INSTALL.md
# 编译依赖 C++ 工具链、CMake 等

方式三：Docker（推荐快速体验）

xLLM 社区提供了 Docker 镜像，适合快速验证功能：

# 拉取官方镜像（具体镜像名见 GitHub Releases）
docker pull xllm/xllm:latest

# 运行
docker run -it --gpus all xllm/xllm:latest

⚠️ 不确定处：Docker 镜像具体命名和 tag 需查阅最新 Release 说明。首次安装建议从 pip 开始降低门槛。

前置依赖

  • Python >= 3.8（pip 方式）
  • CUDA / cuDNN（使用 NVIDIA GPU 时）
  • 国产加速器驱动（昇腾 CANN 等，使用国产硬件时）
  • CMake >= 3.18（从源码编译时）
  • C++ 编译工具链

核心用法

1. 基本推理调用（Python SDK）

import xllm

# 初始化推理引擎
engine = xllm.Engine(
    model_path="/path/to/your/model",
    device="cuda",       # 或 "npu"（昇腾）
    tensor_parallel=1,    # 多卡并行数
)

# 同步推理
response = engine.generate(
    prompt="用三句话解释量子计算",
    max_tokens=256,
    temperature=0.7,
)
print(response)

2. 流式输出

for token in engine.generate_stream(
    prompt="写一段 Python 代码实现快速排序",
    max_tokens=512,
):
    print(token, end="", flush=True)

3. VLM（视觉语言模型）推理

response = engine.generate(
    prompt="这张图片里有什么？",
    images=["/path/to/image.jpg"],
)

4. 启动 HTTP 服务（生产部署）

xLLM 提供 REST API 服务，适合生产环境：

xllm server \
    --model /path/to/model \
    --port 8000 \
    --device cuda \
    --max_batch_size 32

调用方式：

curl -X POST http://localhost:8000/v1/generate \
  -H "Content-Type: application/json" \
  -d '{"prompt": "解释什么是 RAG", "max_tokens": 256}'

5. 调度配置（xLLM-Service 层）

在集群部署场景下，通过配置文件管理在线/离线任务调度：

# service_config.yaml
scheduler:
  online_priority: high
  offline_best_effort: true
  pd_disaggregation: dynamic  # 动态 PD 分离

resource_pool:
  gpu_count: 8
  memory_gb: 128

⚠️ 不确定处：具体配置文件格式和参数名以官方文档为准，以上为基于 arXiv 技术报告的结构性示意。

典型适用场景

场景 1：昇腾/国产加速器上的 LLM 部署

在华为昇腾 NPU 硬件上部署 Llama、Qwen 等开源模型，用 vLLM 等框架支持不足时，xLLM 是针对性更强的选择。

场景 2：多模态模型生产服务

同时服务 LLM（问答）、VLM（图片理解）、DiT（图像生成）等多种模型类型，xLLM 的统一引擎层减少运维复杂度。

场景 3：在线离线混合推理服务

电商推荐系统（REC）+ 客服 LLM 在同一集群部署，用 xLLM-Service 的弹性调度实现资源最大化利用。

场景 4：超大规模推理集群优化

xLLM 的全局 KV Cache 管理 + 动态 PD 分离适合超长上下文、高并发场景（如金融研报生成、法律文档分析）。

坑与注意

  1. 成熟度为 research：GitHub 标注成熟度为 research，不代表能直接用于生产。生产使用前务必评估社区活跃度、文档完整度和线上案例。

  2. 国产硬件生态文档有限：昇腾等国产加速器的使用文档、常见错误排查指南相对较少，遇到问题可能需要看源码或提 Issue。

  3. 版本更新快：项目在 OpenAtom 基金会下，API 和接口可能在短周期内有 Breaking Change。

  4. benchmark 数据有限：目前公开的量化性能数据（相比 vLLM/TGI 的具体吞吐提升）披露有限，选型时建议自己实测。

  5. 社区规模较小：相比 vLLM（Stars 50k+），xLLM Stars 仅约 1,400，Stack Overflow / 博客教程资源少。

  6. 编译依赖复杂：从源码编译需要 CMake、C++ 工具链、CUDA/昇腾驱动，门槛比 pip 安装高不少。

  7. 与 vLLM 的取舍：如果你不需要国产硬件适配、且 vLLM 已经够用，优先考虑 vLLM——社区更成熟、生态更完整。

与同类对比

框架 Stars 硬件支持 成熟度 特色
xLLM ~1,400 NVIDIA + 昇腾等国产 Research 国产加速器优化、EPD 分离、多模态统一
vLLM 50k+ NVIDIA 为主 Production PagedAttention、连续批处理、社区成熟
TGI (HuggingFace) 20k+ NVIDIA Production 易用、模型支持广、推理优化强
DeepSpeed-Inference 10k+ NVIDIA + AMD Production DeepSpeed 生态集成好
llama.cpp 60k+ CPU + GPU Production 纯 C++、无需 GPU、量化领先

xLLM 的核心优势：国产 AI 加速器的原生优化 + 多模态统一推理框架。如果你的 Infra 跑在昇腾等国产硬件上，它是最值得测试的选项；如果用 NVIDIA GPU，vLLM 生态更成熟。

一句话推荐结论

如果你在国产 AI 加速器（昇腾等）上部署大模型，xLLM 是目前最专门的优化框架，值得花时间实测；如果用 NVIDIA GPU、追求稳定生产，vLLM 仍是更稳妥的选择。xLLM 代表着国产 Infra 适配的重要方向，但采用前建议仔细评估当前版本的生产就绪程度。

参考来源

  • GitHub 仓库：https://github.com/xLLM-AI/xllm
  • xLLM Technical Report（arXiv:2510.14686）：https://arxiv.org/html/2510.14686v1
  • xLLM-Service（服务层）：https://github.com/jd-opensource/xllm-service
  • OpenAtom 基金会：https://openatom.cn/ -Awesome-LLM-Inference-Engine 对比研究：https://github.com/sihyeong/Awesome-LLM-Inference-Engine

⚠️ 编写说明（供编辑参考）

本攻略涉及的不确定处已在正文中用 ⚠️ 标注，主要包括： - Docker 镜像具体命名和 tag（未在公开文档找到明确说明） - Python SDK 完整 API 签名（README 未提供代码示例，基于通用推理引擎模式推断） - xLLM-Service 配置文件 schema（基于 arXiv 技术报告结构推断） - 编译详细步骤（需参阅仓库内 BUILD.md）

建议以 GitHub 最新 README 和 Release Notes 为准进行核实。