xorbitsai/inference（Xinference）· 上手攻略

  • 仓库：xorbitsai/inference
  • 链接：https://github.com/xorbitsai/inference
  • 分类：ai（llm-infra / multimodal）
  • 作者：Jay
  • 更新：2026-07-11

是什么

Xinference（Xorbits Inference）是 xorbitsai 团队开源的统一推理服务平台，一行代码替换 GPT 为任意开源 LLM。它让你在本地、云端或笔记本上运行开源语言模型、语音模型和多模态模型，通过统一的 OpenAI 兼容 API 提供服务。

Xinference 的核心差异化在于：支持最多的推理引擎（vLLM、SGLang、llama.cpp、Transformers、MLX），以及原生支持多模态和语音模型——这是 FastChat、OpenLLM 等竞品所不具备的。它还内置了 Agent 服务能力（通过 Xagent 集成），支持动态规划、工具调用和多步推理。

解决什么问题

  • 推理框架碎片化：vLLM 跑这个模型、llama.cpp 跑那个模型，Xinference 一个平台统一管理
  • 部署门槛高：一行命令启动本地推理服务，不需要写 Dockercompose、配置 Kubernetes
  • OpenAI API 迁移成本：兼容 OpenAI API，直接改 base URL 就能切换到本地模型
  • 多模态支持：不只是文本，图像生成、语音识别、多模态理解都能跑
  • 集群部署：单机跑不下？Xinference 支持多节点分布式推理

快速安装

# 全量安装（支持所有模型类型）
pip install "xinference[all]"

# 指定推理引擎安装（节省空间）
pip install "xinference[transformers]"      # PyTorch 格式模型
pip install "xinference[vllm]"              # vLLM 加速（推荐生产环境）
pip install "xinference[llama.cpp]"         # GGUF 格式量化模型
pip install "xinference[sglang]"             # SGLang 引擎

# 验证安装
xinference --version

⚠️ 依赖：Linux/macOS/Windows 均支持，GPU 推理需要 NVIDIA GPU + CUDA 11.8+ 或 Apple Silicon（MLX 后端）。macOS Metal 加速通过 llama.cpp 引擎支持。

核心用法

1. 启动本地服务

# 启动本地推理服务器
xinference-local --host 0.0.0.0 --port 9997

# 服务器启动后访问：
# - Web UI: http://127.0.0.1:9997
# - API 文档: http://127.0.0.1:9997/docs

2. 通过命令行部署模型

# 列出可用模型
xinference list

# 启动一个内置模型（以 Qwen2.5 为例）
xinference launch --model-name qwen2.5-instruct --model-format pytorch --quantization none --size-in-billions 7

3. 通过 Python 客户端使用

pip install xinference-client

from xinference.client import RESTClient

client = RESTClient("http://127.0.0.1:9997")

# 查询可用模型
models = client.list_models()

# 对话（Chat API）
chat_response = client.chat(
    model_uid="qwen2.5-instruct",
    messages=[
        {"role": "user", "content": "用 Python 写一个快速排序"}
    ]
)
print(chat_response["choices"][0]["message"]["content"])

4. 通过 cURL 调用

curl -X POST http://127.0.0.1:9997/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-instruct",
    "messages": [{"role": "user", "content": "你好"}]
  }'

📌 注意：如果你熟悉 OpenAI ChatGPT API，Xinference 的 API 完全兼容，只需把 base URL 改成 http://127.0.0.1:9997/v1，模型名改成 Xinference 里部署的模型 UID 即可。

5. 部署图像/多模态模型

# 启动图像模型（如 MiniCPM-V 多模态模型）
xinference launch \
  --model-name MiniCPM-V-4.6 \
  --model-format pytorch \
  --size-in-billions 2

# 使用 Python 客户端
from xinference.client import RESTClient
client = RESTClient("http://127.0.0.1:9997")

response = client.chat(
    model_uid="MiniCPM-V-4.6",
    messages=[{
        "role": "user",
        "content": [
            {"type": "image_url", "image_url": {"url": "https://example.com/image.jpg"}},
            {"type": "text", "text": "这张图片里有什么？"}
        ]
    }]
)

6. 集群部署（多节点）

# 在主节点启动 supervisor
xinferenceSupervisor

# 在工作节点启动 worker
xinferenceWorker --supervisor-port 9997

# 指定分布式 запуска
xinference launch --model-name qwen2.5-instruct --worker-endpoint http://worker1:9967

核心推理引擎对比

引擎 适用场景 量化和格式 备注
vLLM 生产环境、高吞吐 FP16/BF16 推荐生产使用，PagedAttention
SGLang 长上下文、Agent FP16/BF16 v1.8+ 因依赖冲突需单独安装
llama.cpp CPU/GGUF 量化模型 4bit/8bit 等 macOS Metal 加速首选
Transformers 小模型、调试 PyTorch 原生 最通用但最慢
MLX Apple Silicon 量化 macOS M 系列芯片专用

⚠️ 版本注意：v1.8.1+ 因依赖冲突将 SGLang 从 all extra 中移除，需单独 pip install 'xinference[sglang]' 安装。

典型适用场景

  • 本地 LLM 部署：不想把数据发到 OpenAI？在本地用 Xinference 跑 Qwen、DeepSeek、GLM 等开源模型
  • 模型对比评测：同一 API 端点切换不同模型，对比输出质量
  • Agent 应用开发：内置 Xagent 支持动态规划、工具调用，适合构建 AI Agent
  • 多模态 RAG：用 MiniCPM-V 等多模态模型做图像问答，配合 RAG 系统
  • 私有化部署：企业不想用云服务 API，Xinference 提供完整的私有部署方案

坑与注意

  1. vLLM 版本冲突：Xinference 依赖的 vLLM 版本与其他项目可能冲突（transformers、sglang 等）。生产环境建议用 Docker 隔离或 venv
  2. 模型下载慢：Xinference 自动从 Hugging Face 下载模型，国内网络建议配置镜像（HF_ENDPOINT 环境变量）
  3. 显存估算不准：部分量化模型实际显存占用与声明不符，跑之前用 xinference cal-model-mem 估算
  4. GGUF 模型需 llama.cpp 引擎：不要用错了引擎格式，比如 Qwen2.5 的 GGUF 版本需要 llama.cpp 引擎才能加载
  5. 分布式部署复杂：多节点集群需要 NCCL 网络，配置不当会导致性能反而下降，建议从单机开始
  6. Apple Silicon：macOS M 系列芯片推荐用 MLX 引擎（pip install "xinference[mlx]"），而不是直接用 PyTorch（会很慢）
  7. Function Calling：OpenAI 兼容的 Function Calling 在 Xinference 中已支持，但需要确认具体模型是否支持（有的模型微调过才能用）

与同类对比

Xinference FastChat（ChatUI） OpenLLM vLLM（直接用）
多推理引擎 ✅ vLLM/llama.cpp/SGLang/Transformers ❌ ⚠️ ❌（单一引擎）
多模态模型 ✅ ❌ ❌ ❌
语音模型 ✅ ❌ ❌ ❌
OpenAI API 兼容 ✅ 完整兼容 ✅ ✅ ❌
Agent 原生 ✅（Xagent 集成） ❌ ⚠️ ❌
分布式集群 ✅ ❌ ✅ ✅
上手难度 低（一条命令启动） 低 低 高（需自己配）

结论：如果你需要统一管理多种模型（语言 + 多模态 + 语音），不想维护多个推理服务，Xinference 是最省心的选择。如果只是单纯跑 vLLM 做推理且不需要其他引擎，直接用 vLLM 反而更简单。

一句话推荐结论

Xinference 把「本地跑模型」变成了一件优雅的事——无论你是想在笔记本上跑 Qwen2.5 写代码，还是在集群里部署多模态 Agent，一套 API 全搞定，是目前开源推理平台中功能覆盖最全面的选择之一。