Type to search documentation...

# 开发指南

了解 xInfer 的架构设计、如何作为 Rust crate 集成、以及如何贡献代码。

## 架构概览

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(())
    }

## 贡献指南

1. ### Fork 和克隆

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

2. ### 创建分支

       git checkout -b feature/my-feature

3. ### 编译和测试

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

4. ### 提交 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 集成指南