Type to search documentation...

# 使用指南

深入了解量化格式、KV 缓存压缩、多 GPU 推理、PD 分离等高级功能。

## 模型格式

xInfer 支持多种模型格式，按照不同精度和硬件选择：

格式 | 精度 | 说明
--- | --- | ---
Safetensors | FP16/BF16 | 完整精度，需要更多显存
GGUF | Q2–Q8 | 最广泛的量化格式，社区支持好
GPTQ / AWQ | 4-bit | GPU 优化的 4-bit 量化
FP8 | E4M3/E5M2 | SM89+（Ada）原生支持
NVFP4 | 4-bit | SM100+（Blackwell）原生；V100 可用软件 FP4
ISQ | Q2–Q8 | In-situ 在线量化

    # Safetensors (FP16/BF16)
    xinfer --m meta-llama/Llama-3.1-8B-Instruct

    # GGUF
    xinfer --m unsloth/Qwen3-30B-A3B-GGUF --f Qwen3-30B-A3B-UD-Q4_K_XL.gguf

    # GPTQ
    xinfer --m Qwen/Qwen3-30B-A3B-GPTQ-Int4

    # FP8
    xinfer --m Qwen/Qwen3.6-27B-FP8

    # NVFP4 (Blackwell 原生)
    xinfer --m nvidia/Qwen3-30B-A3B-NVFP4

## ISQ 在线量化

ISQ 可以在加载 Safetensors 权重时实时量化为 GGUF 格式：

    xinfer --m meta-llama/Llama-3.1-8B-Instruct --isq Q4K
    xinfer --m meta-llama/Llama-3.1-8B-Instruct --isq Q6K

## TurboQuant KV 缓存压缩

基于 Walsh-Hadamard 变换的 KV 缓存量化：

模式 | 比特 | 压缩比
--- | --- | ---
`turbo8` | 8-bit | ~2×
`turbo4` | 4-bit | ~3.7×
`turbo2` | 2-bit | ~4.3×

    # 30B+ MoE 模型在 24GB GPU 上运行
    xinfer --m Qwen/Qwen3.6-27B-FP8 --kvcache-dtype turbo4

💡 提示

turbo4 是推荐的默认选择——在大幅节省内存的同时几乎不损失输出质量。

## 多 GPU 推理

使用张量并行跨多张 GPU 推理大模型：

    # 2 GPU 张量并行
    xinfer --m deepseek-ai/DeepSeek-V3 --num-ranks 2

    # 多节点推理
    # 节点 0（主节点）：
    xinfer --m deepseek-ai/DeepSeek-V3 --num-ranks 16 --local-num-ranks 8
    # 节点 1：
    xinfer --m deepseek-ai/DeepSeek-V3 --num-ranks 16 --local-num-ranks 8 --rank-offset 8 --master-addr NODE0_IP

## PD 分离

PD 分离部署：

模式 | 配置 | 场景
--- | --- | ---
Local IPC | 默认 | 同机 CUDA
File IPC | `--pd-url file:///path` | 容器间
Remote TCP | `--pd-url tcp://host:port` | 跨机器

    # PD Server（预填充 GPU，默认端口 7000）
    xinfer --d 0,1 --m Qwen/Qwen3-30B-A3B-Instruct-2507 --pd-server

    # PD Client（解码 GPU + API）
    xinfer --d 2,3 --m /path/Qwen3-30B --isq q4k --ui-server --port 8000 --pd-client

    # Server 机器 (192.168.1.100)
    xinfer --d 0,1 --m Qwen/... --pd-server --pd-url tcp://0.0.0.0:8100

    # Client 机器
    xinfer --d 0,1 --m /path/... --pd-client --pd-url tcp://192.168.1.100:8100 --ui-server

    mkdir -p /tmp/pd-sockets

    # Server 容器
    docker run --gpus '"device=0,1"' -v /tmp/pd-sockets:/sockets ...
    xinfer --d 0,1 --m Qwen/... --pd-server --pd-url file:///sockets

    # Client 容器
    docker run --gpus '"device=2,3"' -v /tmp/pd-sockets:/sockets ...
    xinfer --d 0,1 --m /path/... --pd-client --pd-url file:///sockets --ui-server

📘 Metal 注意

Metal/macOS 需要 --pd-url。

## 多 Token 预测 (MTP)

MTP 允许每次前向传播预测多个 Token：

    xinfer --m deepseek-ai/DeepSeek-R1 --mtp 2

## 结构化输出

xInfer 支持引导解码（Guided Decoding）：

    curl http://localhost:8000/v1/chat/completions \
      -d '{
      "model": "default",
      "messages": [{"role":"user","content":"List 3 cities"}],
      "response_format": {
        "type": "json_schema",
        "json_schema": {
          "name": "cities",
          "schema": {
            "type": "object",
            "properties": {
              "cities": {"type":"array","items":{"type":"string"}}
            },
            "required": ["cities"]
          }
        }
      }
    }'

## MCP 工具调用

xInfer 内置 MCP 支持：

    # 通过配置文件
    xinfer --m MODEL --mcp-config mcp.json

    # 或单个 MCP 服务器命令
    xinfer --m MODEL --mcp-command path/to/server --mcp-args arg1,arg2

### 配置文件格式

    {
      "mcpServers": {
        "filesystem": {
          "command": "path/to/executable",
          "args": ["arg1", "arg2"],
          "env": { "ENV_VAR": "value" }
        }
      }
    }

    {
      "mcpServers": {
        "remote_server": {
          "url": "https://mcp.example.com/api/",
          "headers": {
            "Authorization": "Bearer YOUR_TOKEN",
            "Accept": "text/event-stream"
          }
        }
      }
    }

多服务器工具名自动加前缀。

📘 工具调用流程

xInfer 不执行工具——客户端负责执行和回传结果。

### 工具解析器

模型特定的工具解析器：

模型族 | 检测方式 | 开始标记
--- | --- | ---
Qwen 2.5/3 | Token ID + Text | `<tool_call>`
Llama 3/3.1 | Token ID + Text | `<|python_tag|>`
Mistral | Token ID + Text | `[TOOL_CALLS]`
Gemma | 仅文本 | `<start_function_call>`
Phi4, GLM4 | 仅文本 | `<tool_call>`

## 嵌入端点

同一服务器支持 Chat 和 Embedding：

    curl -XPOST http://localhost:8000/v1/embeddings \
      -H "Content-Type: application/json" \
      -d '{"input":"hello world","model":"default","embedding_type":"mean"}'

    curl -XPOST http://localhost:8000/v1/embeddings \
      -H "Content-Type: application/json" \
      -d '{"input":"hello world","embedding_type":"last"}'

    curl -XPOST http://localhost:8000/v1/embeddings \
      -H "Content-Type: application/json" \
      -d '{"input":["hello","hola"],"embedding_type":"last","encoding_format":"base64"}'

参数 | 值 | 说明
--- | --- | ---
`embedding_type` | `mean` / `last` | 池化方式
`encoding_format` | `float` / `base64` | 编码格式

## 前缀缓存

前缀缓存默认启用，自动复用 KV 缓存：

    # 禁用前缀缓存
    xinfer --m MODEL --disable-prefix-cache

    # 限制前缀缓存大小（按 block 大小向下取整）
    xinfer --m MODEL --prefix-cache-max-tokens 65536

### 默认缓存大小

模式 | 默认占比
--- | ---
普通模式 | ~50%
PD Server | ~75%
PD Client | ~35%

### 缓存命中检查

检查缓存命中：

    // 响应中的 usage 字段
    {
      "usage": {
        "prompt_tokens": 499,
        "completion_tokens": 16,
        "prompt_tokens_details": { "cached_tokens": 480 }
      }
    }

推理模型还返回：

    "completion_tokens_details": { "reasoning_tokens": 192 }

💡 Hybrid Mamba 模型

混合 Mamba 模型需要匹配快照。

💡 调优建议

前缀缓存共享 KV 内存池。

## 视觉语言模型

支持的 VL 模型：

    # 通过 Web UI 上传图片
    xinfer --m Qwen/Qwen3-VL-8B-Instruct --ui-server

    # 通过 API 发送图片（image_url）
    curl http://localhost:8000/v1/chat/completions \
      -d '{"model":"default","messages":[{"role":"user","content":[
        {"type":"text","text":"Describe this image:"},
        {"type":"image_url","image_url":{"url":"https://example.com/cat.jpg"}}
      ]}]}'

## 推理控制

推理模式控制：

    # 禁用默认推理（显式请求值仍然优先）
    xinfer --m MODEL --disable-reasoning

支持多种推理努力级别。

## 运行时参数

参数 | 说明 | 默认
--- | --- | ---
`--max-model-len` | 最大上下文长度 | 模型默认
`--max-num-seqs` | 最大并发请求 | 32 (macOS: 8)
`--kv-fraction` | KV 缓存显存比例 | 自动
`--cpu-mem-fold` | CPU 换出比例 | `0.2`
`--prefill-chunk-size` | 预填充分块 | CUDA 8K, Metal 4K
`--max-tokens` | 最大响应 Token | `16384`
`--disable-cuda-graph` | 禁用 CUDA Graph | —
`--yarn-scaling-factor` | YARN 扩展因子 | —

## 聊天日志

启用聊天日志：

    export XINFER_CHAT_LOGGER=1
    xinfer --m MODEL --ui-server
    # 日志文件写入 ./log 目录

## 故障排查

⚠️ CUDA OOM

显存不足时，调整多个参数。

⚠️ Metal OOM

macOS 上降低上下文长度和批量。

⚠️ SM70 兼容性

V100 用户注意编译特性和并发设置。

💡 性能调优

使用 --log 监控，注意 swap 消息。