开发指南

架构概览

xInfer 采用分层架构设计：

🌐 API 层 — OpenAI/Anthropic 兼容 REST + Web UI + MCP

↕

⚙️ 推理引擎 — 连续批处理、流式生成、引导解码

↕

📋 调度器 — PagedAttention、KV 缓存管理、TurboQuant

↕

🔧 计算后端 — Flash Attention / FlashInfer / DeepGEMM / Candle

↕

🖥️ 硬件层 — CUDA (SM70+) / Metal (Apple Silicon) / NCCL 多 GPU

推理流水线

请求的完整生命周期：

🌐

① 请求接入

HTTP 请求通过 API 端点进入。MCP 工具自动注入。

▼

📝

② 分词和模板

应用 chat template → 分词 → grammar 组合。

▼

📦

③ 连续批处理

调度 → PagedAttention → 前缀缓存 → TurboQuant。

▼

⚡

④ 前向传播

FlashInfer / FlashAttn / DeepGEMM → CUDA Graph → PD → MTP。

▼

🎯

⑤ 采样 + 引导解码

采样 → mask → penalties → llguidance 约束。

▼

📡

⑥ 流式响应

SSE 流式 → 工具解析状态机 → 返回客户端。

Rust Crate 使用

xInfer 可以作为 Rust 库集成：

# Cargo.toml
[dependencies]
xinfer = { git = "https://github.com/guoqingbao/xinfer", features = ["cuda"] }

Crate API 示例

文本生成

use xinfer::api::{EngineBuilder, ModelRepo};
use xinfer::server::{ChatMessage, MessageContentType};
use xinfer::utils::{config::SamplingParams, log_throughput};

fn main() -> anyhow::Result<()> {
    let mut engine =
        EngineBuilder::new(ModelRepo::ModelID(("google/gemma-3-4b-it", None))).build()?;

    let messages = vec![ChatMessage {
        role: "user".to_string(),
        content: MessageContentType::PureText("Say hello from the Rust API.".to_string()),
    }];

    let params = SamplingParams::default();
    let output = engine.generate(params, messages)?;
    println!("\n\n{}", output.decode_output);
    log_throughput(&vec![output]);
}

多模态请求

use xinfer::api::{EngineBuilder, ModelRepo};
use xinfer::server::{ChatMessage, MessageContent, MessageContentType};
use xinfer::utils::config::SamplingParams;

fn main() -> candle_core::Result<()> {
    let mut engine = EngineBuilder::new(ModelRepo::ModelID((
        "Qwen/Qwen3-VL-8B-Instruct".to_string(), None,
    ))).build()?;

    let messages = vec![ChatMessage {
        role: "user".to_string(),
        content: MessageContentType::Multi(vec![
            MessageContent::Text { text: "Describe this image:".to_string() },
            MessageContent::ImageUrl {
                image_url: "https://example.com/cat.png".to_string(),
            },
        ]),
    }];

    let output = engine.generate(SamplingParams::default(), messages)?;
    println!("{}", output.decode_output);
    Ok(())
}

启动 API 服务器

use xinfer::api::{EngineBuilder, ModelRepo};

fn main() -> candle_core::Result<()> {
    let mut engine = EngineBuilder::new(ModelRepo::ModelID((
        "Qwen/Qwen3-0.6B".to_string(), None,
    ))).build()?;

    engine.start_server(8000, true, false)?;
    Ok(())
}

多 GPU (Rust API)

use xinfer::api::{EngineBuilder, ModelRepo};

fn main() -> candle_core::Result<()> {
    let mut engine = EngineBuilder::new(ModelRepo::ModelFile(vec![
        "/path/Qwen3-VL-8B-Instruct-GGUF-Q4_KM.gguf".to_string(),
    ]))
    .with_multirank("0,1")?
    .build()?;

    engine.start_server(8000, true, true)?;
    Ok(())
}

贡献指南

Fork 和克隆

git clone https://github.com/YOUR_USER/xinfer.git
cd xinfer

创建分支
```
git checkout -b feature/my-feature
```

编译和测试

cargo build --features cuda
cargo test
cargo fmt --check
cargo clippy -- -D warnings

提交 PR

推送到 Fork 并创建 Pull Request。

添加新模型（AI 辅助）

AI 辅助添加模型：

阶段	说明
0 — 收集信息	收集模型信息
1 — 分析	架构分析
2 — 内核	内核检查
3 — 实现	模型实现
4 — 注册	模型注册
5 — 编译	编译测试
6 — 验证	质量验证
7 — 测试	端到端测试

支持的配置

维度	支持类型
格式	Safetensors (HF), GGUF, GPTQ, AWQ
架构	Dense, MoE, Hybrid MoE, Multimodal (VL)
量化	ISQ (Q4K, Q8_0...), FP8, MXFP4, NVFP4, GPTQ, AWQ
注意力	GQA, MQA, MHA, Sliding Window, MLA
平台	CUDA (Linux/Windows), Metal (macOS)

# 在 Cursor 中让 Agent 添加模型
Add support for the model google/gemma-4-26B-A4B-it
# 或提供本地路径
Add support for the model at /path/to/my-model/

模型兼容性检查

AI 辅助的兼容性检查：

# 在 Cursor 中
Check this model: https://huggingface.co/AxionML/Qwen3.5-27B-NVFP4/blob/main/config.json
# 或检查本地模型
Check the model at /data/Qwen3.5-122B-A10B-NVFP4/ for 4-GPU loading

检查项	说明
张量格式	验证量化格式张量
量化忽略列表	混合精度忽略列表
多 GPU 整除性	TP 整除性检查
加载器路径	加载器兼容性

模型测试

自动化模型测试：

# 在 Cursor 中
Test all models in /data/
# 或指定模型
Test models AxionML/Qwen3.5-2B-NVFP4, Qwen/Qwen3-4B

阶段	说明
0 — 收集模型	模型列表
1 — 资源估算	GPU 分配
2 — 编译	编译项目
3 — 创建测试	测试脚本
4 — 逐模型测试	逐个测试
5 — 结果汇总	汇总表

Agent 集成

xInfer 作为 OpenAI/Anthropic 兼容后端，已验证支持多种 AI Agent 框架。详细配置步骤请参考：

📖 快速开始 → Agent 集成指南