使用指南

模型格式

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

# 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-NVFP4Copy

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 Q6KCopy

TurboQuant KV 缓存压缩

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

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

多 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_IPCopy

PD 分离

PD 分离部署：

# 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-clientCopy

# 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-serverCopy

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-serverCopy

多 Token 预测 (MTP)

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

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

结构化输出

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"]
      }
    }
  }
}'Copy

MCP 工具调用

xInfer 内置 MCP 支持：

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

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

配置文件格式

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

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

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

工具解析器

模型特定的工具解析器：

嵌入端点

同一服务器支持 Chat 和 Embedding：

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

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

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

前缀缓存

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

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

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

默认缓存大小

缓存命中检查

检查缓存命中：

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

推理模型还返回：

"completion_tokens_details": { "reasoning_tokens": 192 }

视觉语言模型

支持的 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"}}
  ]}]}'Copy

推理控制

推理模式控制：

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

支持多种推理努力级别。

运行时参数

聊天日志

启用聊天日志：

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

故障排查