Type to search documentation...

# 快速开始

从零开始，在几分钟内运行你的第一个本地 LLM。

## 系统要求

组件 | 要求
--- | ---
操作系统 | 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

## 启动模型

1. ### 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

2. ### 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。接下来查看使用指南了解高级配置。