快速开始 — xInfer

系统要求

组件	要求
操作系统	Linux (CUDA)、Windows (CUDA) 或 macOS (Metal)
Rust 工具链	Rust 1.75+（仅源码编译需要）
CUDA	11.x / 12.x / 13.0（Linux/Windows GPU）
Python	3.8+（仅 Python 绑定需要）

硬件要求

平台	最低 GPU	推荐
CUDA	SM70+ (V100) 8GB+	SM90 (H100) / RTX 5090
Metal	Apple Silicon M1+，8GB+	M4 Pro/Max 推荐

一键安装

自动检测平台，安装预编译二进制、DEB 包或 Python 包：

$ curl -sSL https://guoqingbao.github.io/xinfer/install.sh | bash

npm 安装

npm install -g xinfer-ai

源码编译

# 安装 Rust 工具链
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

# SM70/SM75 (V100)：移除 flashinfer,cutlass 特性
cargo install --git https://github.com/guoqingbao/xinfer xinfer \
  --features cuda,nccl,flashinfer,cutlass

cargo build --release --features metal

💡 提示

SM70/SM75 GPU（V100、T4）请移除 flashinfer 和 cutlass 特性。SM80+（A100）支持全部特性。SM90+（H100）额外支持 CUTLASS FP8 和 DeepGEMM。

Docker 部署

构建 Docker 镜像：

# 通过脚本构建（指定特性、SM 版本、CUDA 版本）
./build_docker.sh "cuda,nccl,flashinfer,python" sm_80 12.9.0

# 或通过 docker build 命令
docker build --network=host -f "Dockerfile" -t "xinfer:latest" \
  --build-arg CUDA_VERSION="12.9.0" \
  --build-arg WITH_FEATURES="cuda,nccl,flashinfer,cutlass,python" \
  --build-arg CUDA_COMPUTE_CAP="sm_80" .

运行容器：

# 查看帮助
docker run --rm -it --gpus all --network host xinfer:latest xinfer --help

# API 服务器（确保使用 --network host）
docker run --rm -it --gpus all --network host xinfer:latest \
  xinfer --m Qwen/Qwen3-0.6B --server

# 交互式 + 挂载本地模型
docker run --rm -it --gpus all --network host -v /data:/data xinfer:latest bash
xinfer --m /data/Qwen3-Coder-30B-A3B-FP8 --ui-server

Python 轮子

pip install maturin maturin[patchelf]
./build.sh --release --features cuda,nccl,flashinfer,cutlass,python
pip install target/wheels/xinfer*.whl --force-reinstall

启动模型

Rust CLI 启动

# FP8 模型 + Web UI + TurboQuant
xinfer --m Qwen/Qwen3.6-27B-FP8 --kvcache-dtype turbo4 --ui-server

# GGUF 模型
xinfer --m unsloth/Qwen3.5-27B-GGUF --f Qwen3.5-27B-Q4_K_M.gguf --ui-server

Python 启动

python3 -m xinfer.server --m Qwen/Qwen3.6-27B-FP8 --kvcache-dtype turbo4 --ui-server

测试 API

服务启动后，默认监听 http://localhost:8000：

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
  "model": "default",
  "messages": [{"role": "user", "content": "Hello!"}],
  "max_tokens": 128,
  "stream": true
}'

Web UI

添加 --ui-server 标志启动内置 ChatGPT 风格 Web UI。API 端口 8000，UI 端口 8001。

更多运行示例

GGUF 模型加载

GGUF 支持多种加载模式：

# 本地 GGUF 单文件
xinfer --m /path/model-Q4_K_M.gguf

# 本地 GGUF 目录（自动检测最大 .gguf 文件，多分片自动发现）
xinfer --m /path/GLM-5.2-GGUF/ --ui-server

# 远程 GGUF 单文件（从 HuggingFace 下载）
xinfer --m unsloth/Qwen3-0.6B-GGUF --f Qwen3-0.6B-Q4_K_M.gguf

# 远程 GGUF 子目录（自动检测多分片文件）
xinfer --d 0,1,2,3 --m unsloth/GLM-5.2-GGUF --f UD-Q2_K_XL

ISQ 在线量化

实时量化为 GGUF：

# ISQ Q4K + FP8 KV 缓存
xinfer --m Qwen/Qwen3.6-35B-A3B --isq q4k --kvcache-dtype fp8

# ISQ Q4K + TurboQuant
xinfer --m Qwen/Qwen3.6-35B-A3B --isq q4k --kvcache-dtype turbo4

# Metal ISQ
xinfer --m /path/Qwen3-4B --isq q6k

多模态模型

视觉语言模型：

# Qwen3.6 35B MoE 多模态 (FP8)
xinfer --m Qwen/Qwen3.6-35B-A3B-FP8 --ui-server

# Qwen3-VL 8B (GGUF)
xinfer --m unsloth/Qwen3-VL-8B-Instruct-GGUF --f Qwen3-VL-8B-Instruct-Q8_0.gguf --ui-server

# Gemma4 26B MoE 多模态 (NVFP4)
xinfer --m unsloth/gemma-4-26b-a4b-it-NVFP4 --ui-server

# Mistral-3 VL 3B (BF16)
xinfer --m mistralai/Ministral-3-3B --ui-server

📸 GGUF 视觉模型

GGUF 多模态模型的 mmproj 文件会自动检测。

交互式 CLI

xinfer --i --m unsloth/Qwen3.5-27B-GGUF --f Qwen3.5-27B-Q4_K_M.gguf

Agent 集成

启动 xInfer 后配置 Base URL 接入 Agent：

# 1) 启动 xInfer
xinfer --m Qwen/Qwen3.6-27B-FP8

# 2) 安装 xbot
npm install -g @trusted-ai/xbot

# 3) 配置 (选择 custom, Base URL: http://localhost:8000/v1/)
xbot config --provider

# 4) 使用
xbot repl

# 1) 启动 xInfer（Anthropic 兼容端点）
xinfer --m Qwen/Qwen3-Coder-Next-FP8 --server --d 0,1

# 2) 配置 Claude Code
export ANTHROPIC_BASE_URL="http://127.0.0.1:8000"
export ANTHROPIC_AUTH_TOKEN="sk-dummy"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1

# 或在 ~/.claude/settings.json 中持久化
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:8000",
    "ANTHROPIC_MODEL": "default",
    "ANTHROPIC_AUTH_TOKEN": "sk-dummy"
  }
}

# 3) 启动
claude

# 安装
curl -fsSL https://opencode.ai/install | bash

# 配置 ~/.config/opencode/config.json
{
  "provider": {
    "xinfer": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "xInfer Local",
      "options": { "baseURL": "http://localhost:8000/v1" },
      "models": { "qwen3-coder": { "name": "Qwen3 Coder" } }
    }
  },
  "model": "xinfer/qwen3-coder"
}

# 启动
opencode

# 安装 (https://block.github.io/goose/)
export VLLM_API_KEY="empty"

# 配置 (Custom Providers → OpenAI Compatible)
goose configure
# Provider: xinfer, URL: http://127.0.0.1:8000/v1/, Models: default

# 启动
goose

# 安装
npm install -g @kilocode/cli

# 配置 ~/.config/kilo/config.json (同 OpenCode 格式)

# 启动
kilo

💡 Qwen Coder 模型

Qwen Coder 推荐 --enforce-parser qwen_coder。

编译特性矩阵

特性	说明	GPU 要求
`cuda`	CUDA 后端	SM70+
`nccl`	多 GPU 通信	SM70+
`flashinfer`	FlashInfer	SM80+
`cutlass`	CUTLASS	SM80+
`flashattn`	Flash Attn	SM80+
`metal`	Metal	Apple M1+
`python`	Python 绑定	—

⚠️ SM70/SM75 注意

V100 / T4 用户请移除 flashinfer 和 cutlass 特性。

✅ 完成

恭喜！你已成功运行了 xInfer。接下来查看使用指南了解高级配置。