扔掉 vLLM！从零构建 Qwen3-8B 推理引擎，C++/CUDA 实现性能追平 98%

一、项目核心释义

这是一套从零开始完整实现的Qwen3-8B大模型推理栈，采用「C++/CUDA底层计算 + Go上层服务」的双层架构，不依赖PyTorch、通用推理框架等第三方组件，走精简代码路线：放弃宽泛的多模型支持，只聚焦Qwen3-8B一条完整的推理路径，换来代码干净、逻辑清晰、易于阅读与二次开发。

引擎经历三个阶段的演进，从单文件教学级终端程序，逐步迭代为生产级服务端：最终在单张RTX 4090级别显卡、BF16精度下，服务吞吐达到主流推理引擎的95%~98%（关闭前缀缓存），真实对话场景下达到97%，整体性能相比初代版本提升约6倍，同时保持OpenAI兼容接口，可直接对接标准客户端。

二、行业核心技术知识点

2.1 推理引擎的三层演进逻辑

大模型推理引擎的发展通常遵循三个阶段：

1. 单流教学版：单文件、零依赖，跑通前向传播与采样，用于学习原理，性能最低
2. 批处理服务版：加入连续批处理、分页KV缓存，封装HTTP接口，可对外提供服务，吞吐提升数倍
3. 性能优化版：针对显存带宽、计算调度、缓存复用做深度优化，逐步追平主流框架的性能

这套引擎完整走完了这三步，每一步都保留了清晰的版本边界，是学习推理引擎演进的绝佳参考。

2.2 服务端推理的核心瓶颈

服务端大模型推理的性能瓶颈，从来不是单流速度，而是三个点：

• Prefill阶段：长提示的注意力计算，显存带宽压力大
• Decode阶段：逐个token生成，小矩阵乘法多，内核启动开销大
• 调度层面：多请求并发时，KV缓存管理、批处理调度策略，决定整体吞吐

真正的服务端优化，都是围绕这三个瓶颈逐层展开的。

2.3 关键加速技术

• FlashAttention：把注意力计算分块做，不用存完整的注意力矩阵，大幅降低显存占用，提升计算效率
• 分页KV缓存：把KV切成固定块，按需分配，支持冷热分层与并发调度
• 连续批处理：动态合并不同请求的解码步，凑大矩阵计算，提升GPU利用率
• GQA分组查询：多个查询头共享一组KV，减少KV显存与读取量
• 前缀缓存：相同前缀的请求复用KV状态，跳过重复的预填充计算

2.4 Go+C++的双层架构思路

服务端推理不只有计算，还有分词、协议、路由、业务逻辑。全用C++写开发慢，全用Go写性能不够。

• C++/CUDA内层：只做纯计算：权重加载、预填充、解码、采样、KV管理，输入输出全是token id，不碰文本，极致性能
• Go外层：处理所有文本侧工作：分词、模板、HTTP接口、工具调用解析，通过gRPC和内层通信
• 嵌入打包：C++二进制直接嵌入到Go程序里，最终只输出一个可执行文件，部署方便

三、整体架构与演进历程

3.1 最终双层架构

┌───────────────────────────────────────────────────────────┐
│                    Go 外层服务                             │
│  分词 / ChatML模板 / 工具调用检测 / OpenAI HTTP API      │
│  交互式CLI / 进程管理 / gRPC客户端                    │
└───────────────────────┬───────────────────────────────┘
                        │ gRPC 通信
┌───────────────────────────────────────────────────────────┐
│                  C++/CUDA 内层计算引擎                       │
│  权重加载 / 预填充计算 / 解码计算 / token采样           │
│  分页KV缓存 / 连续批调度 / CUDA内核优化               │
└───────────────────────────────────────────────────────────┘

分工原则：

• 内层纯计算，不碰任何文本与协议
• 外层纯业务，不碰任何GPU与张量
• 两层通过gRPC只传token id与控制指令，接口极简

3.2 三阶段演进路径

阶段	核心主题	核心特性	性能水平
阶段1	从零实现终端引擎	单C++/CUDA二进制，2000行以内，零第三方依赖，直接读取safetensors权重，终端单流运行	基础可用，单流速度慢
阶段2	批处理与服务化	加入连续批处理、分页注意力；Go封装OpenAI兼容API，gRPC跨层通信	吞吐数倍提升，可对外服务
阶段3	服务端性能优化	BF16精度、cuBLAS GEMM、FlashAttention-2、WMMA、GQA共享解码、前缀缓存	达到主流引擎的95%~98%

四、核心代码实现原理

4.1 双层架构：Go外层与C++内层的协作

4.1.1 Go外层：嵌入打包与进程管理

Go层通过embed指令把编译好的C++引擎二进制直接打包进最终可执行文件，运行时释放到临时目录并启动子进程，通过gRPC通信，最终交付只有一个文件。

核心嵌入与启动代码：

import _ "embed"

// 将编译好的C++引擎二进制直接嵌入Go程序
//go:embed engine_bin
var engineBinary []byte

func startComputeEngine(port int) (*grpc.ClientConn, error) {
    // 1. 释放二进制到临时目录
    tmpDir, err := os.MkdirTemp("", "infer-*")
    binPath := filepath.Join(tmpDir, "compute_engine")
    os.WriteFile(binPath, engineBinary, 0755)

    // 2. 启动C++引擎子进程
    cmd := exec.Command(binPath, "--rpc-port", strconv.Itoa(port))
    cmd.Stderr = os.Stderr
    cmd.Start()

    // 3. 等待启动并建立gRPC连接
    time.Sleep(200 * time.Millisecond)
    conn, err := grpc.Dial(
        "localhost:"+strconv.Itoa(port),
        grpc.WithInsecure(),
        grpc.WithBlock(),
    )
    return conn, err
}

代码讲解：

• 用//go:embed把C++编译产物打进Go二进制，最终交付只有一个可执行文件
• 运行时才释放到临时目录，子进程隔离故障，崩溃不影响外层服务
• Go层只做业务与转发，不参与计算，不干扰性能

4.1.2 跨层gRPC接口定义

两层之间只传输token id和控制参数，不传输文本，接口极简，序列化开销极低。

核心接口定义：

service InferenceService {
  rpc Prefill(PrefillReq) returns (PrefillResp);
  rpc DecodeStep(DecodeReq) returns (DecodeResp);
  rpc ResetSeq(ResetSeqReq) returns (ResetSeqResp);
}

message PrefillReq {
  repeated uint32 tokens = 1;  // 输入token id序列
  int64 seq_id = 2;          // 序列ID
  float temperature = 3;
  float top_p = 4;
}

message DecodeResp {
  uint32 next_token = 1;  // 采样后的下一个token
  bool finished = 2;
}

代码讲解：

• 接口非常薄，只有预填充、单步解码、缓存重置三个核心方法
• 输入输出全是整数token id，没有字符串，序列化开销可以忽略
• 每个序列分配唯一seq_id，内层按id独立管理KV缓存

4.2 C++计算引擎核心

4.2.1 张量结构与权重加载

直接读取原生safetensors格式的权重分片，不需要离线格式转换，加载时直接放到GPU显存，按计算访问顺序排布，优化显存局部性。

核心数据结构：

enum DataType { DT_BF16, DT_FP32 };

struct Tensor {
    void* dev_ptr;       // GPU显存指针
    std::vector<int> shape;
    DataType dtype;
};

struct ModelWeights {
    std::vector<LayerWeights> layers;
    TokenEmbedding embedding;
    Linear lm_head;

    // 直接从safetensors目录加载
    bool load(const std::string& model_dir) {
        // 1. 解析model.safetensors.index.json
        // 2. 按层逐个加载分片到GPU显存
        // 3. 按计算访问顺序重排权重，提升L2缓存命中率
        return true;
    }
};

代码讲解：

• 不做中间格式转换，直接读取safetensors分片到显存，加载快
• 权重按计算访问顺序排布，提升显存缓存命中率
• 原生BF16精度，配合cuBLAS做高性能矩阵乘法

4.2.2 Transformer层前向传播

标准Pre-LN结构，先层归一化再做运算，残差连接，和训练时结构严格对齐，保证输出一致性。

单层前向核心逻辑：

void forward_layer(Tensor& x, const LayerWeights& w, 
                 KVCache& kv_cache, int seq_len) {
    // 第一子层：RMSNorm + 自注意力 + 残差
    Tensor ln1 = rms_norm(x, w.ln1_gamma, w.ln1_beta);
    Tensor attn_out = self_attention(ln1, w.qkv, w.o_proj, kv_cache, seq_len);
    x = tensor_add(x, attn_out);

    // 第二子层：RMSNorm + MLP + 残差
    Tensor ln2 = rms_norm(x, w.ln2_gamma, w.ln2_beta);
    Tensor mlp_out = mlp_swiglu(ln2, w.gate_up, w.down_proj);
    x = tensor_add(x, mlp_out);
}

代码讲解：

• 标准Qwen3 Pre-LN结构，和训练时完全对齐，保证输出一致
• 注意力函数内部根据序列长度，自动选择预填充或解码路径
• 所有张量运算底层调用cuBLAS或自定义CUDA内核

4.3 分页KV缓存与连续批调度

4.3.1 分页KV缓存实现

KV缓存不做成连续大内存，切成固定大小的块，按需分配、空闲复用，天然支持多并发序列，内存碎片少。

核心数据结构：

const int BLOCK_SIZE = 256;  // 每个块的token数

struct KVBlock {
    Tensor k;
    Tensor v;
    int used;  // 块内已使用的token数
};

class KVBlockManager {
    std::deque<KVBlock> free_pool;       // 空闲块池
    std::unordered_map<uint64_t, std::vector<KVBlock*>> seq_map;

    KVBlock* alloc_one() {
        if (!free_pool.empty()) {
            KVBlock blk = std::move(free_pool.front());
            free_pool.pop_front();
            return new KVBlock(std::move(blk));
        }
        return new KVBlock(BLOCK_SIZE);
    }

    void append(uint64_t seq_id, Tensor k, Tensor v) {
        auto& blocks = seq_map[seq_id];
        // 最后一块满了就分配新块
        if (blocks.empty() || blocks.back()->used >= BLOCK_SIZE) {
            blocks.push_back(alloc_one());
        }
        blocks.back()->append(k, v);
    }
};

代码讲解：

• 固定块大小，分配释放都是O(1)，显存碎片少
• 空闲块复用，不用每次都申请释放显存，开销低
• 每个序列独立管理自己的块，天然支持高并发

4.3.2 连续批处理调度器

每步解码动态合并当前所有就绪请求，凑成大矩阵一起计算，大幅提升GPU利用率，不需要等满批，兼顾延迟与吞吐。

核心调度循环：

struct DecodeTask {
    uint64_t seq_id;
    uint32 last_token;
    std::promise<uint32> promise;
};

void batching_loop() {
    while (running_) {
        // 1. 收集所有就绪任务
        std::vector<DecodeTask> batch;
        DecodeTask task;
        while (task_queue.try_dequeue(task)) {
            batch.push_back(std::move(task));
        }
        if (batch.empty()) {
            std::this_thread::yield();
            continue;
        }

        // 2. 打包成一批，统一做解码计算
        Tensor batch_tokens = pack_last_tokens(batch);
        std::vector<uint32> next_tokens = decode_batch(batch_tokens, batch.size());

        // 3. 逐个返回结果
        for (size_t i = 0; i < batch.size(); ++i) {
            batch[i].promise.set_value(next_tokens[i]);
        }
    }
}

代码讲解：

• 不需要等满批，有多少算多少，兼顾延迟与吞吐
• 把多个单token的小计算拼成一个大矩阵乘法，大幅提升GPU利用率
• 每个请求独立promise异步返回，上层无阻塞

4.4 核心性能优化技术实现

4.4.1 FlashAttention-2 预填充注意力

分块计算注意力，不构造完整N×N矩阵，显存占用从O(N²)降到O(N)，长提示下优势明显。

核心分块逻辑：

Tensor flash_attn_prefill(Tensor Q, Tensor K, Tensor V, int seq_len) {
    Tensor output = zeros_like(Q);
    const int Blk = 128;  // 分块大小

    // 按块遍历Q
    for (int i = 0; i < seq_len; i += Blk) {
        int i_end = std::min(i + Blk, seq_len);
        Tensor Qi = Q.slice(i, i_end);
        Tensor acc = zeros_like(Qi);

        // 只计算当前块及之前的K/V，因果屏蔽后面
        for (int j = 0; j <= i; j += Blk) {
            int j_end = std::min(j + Blk, seq_len);
            Tensor Kj = K.slice(j, j_end);
            Tensor Vj = V.slice(j, j_end);

            // 块间点积 + 因果掩码
            Tensor scores = matmul(Qi, Kj.transpose()) / sqrt(d_head);
            apply_causal_mask(scores, i, j, Blk);

            // Softmax 后乘V累加
            scores = softmax_last_dim(scores);
            acc += matmul(scores, Vj);
        }
        output.slice(i, i_end) = acc;
    }
    return output;
}

代码讲解：

• 分块计算，显存里永远只有小块，不存完整大矩阵
• 因果掩码只计算当前块之前的部分，后面的直接忽略
• 长序列下显存占用和计算效率都远优于原生注意力实现

4.4.2 GQA分组查询解码

多个查询头共享一组KV，读一次KV计算多个查询，减少显存读取量，解码阶段收益明显。

核心分组逻辑：

Tensor gqa_decode_attn(Tensor Q, const KVCache& kv, int num_groups) {
    int num_heads = Q.shape[0];
    int heads_per_group = num_heads / num_groups;
    Tensor output = zeros_like(Q);

    for (int g = 0; g < num_groups; ++g) {
        // 一组查询头共享同一块KV，只读一次
        Tensor Kg = kv.get_k_group(g);
        Tensor Vg = kv.get_v_group(g);

        for (int h = 0; h < heads_per_group; ++h) {
            int head_idx = g * heads_per_group + h;
            Tensor qh = Q[head_idx];

            Tensor scores = dot(qh, Kg) / sqrt(d_head);
            scores = softmax(scores);
            output[head_idx] = matmul(scores, Vg);
        }
    }
    return output;
}

代码讲解：

• K按组存储，一组查询头共享同一组KV
• 减少KV存储量，也减少解码时的显存读取次数
• 解码阶段小KV读取的场景，吞吐提升明显

4.4.3 QKV算子融合

把Q、K、V三个线性投影合并成一个大矩阵乘法，减少2次内核启动开销，是最基础也最有效的算子融合。

核心对比：

// 融合前：3次小矩阵乘法，3次内核启动
Tensor q = linear(x, w_q);
Tensor k = linear(x, w_k);
Tensor v = linear(x, w_v);

// 融合后：1次大矩阵乘法，1次内核启动
Tensor qkv = linear(x, w_qkv_merged);  // 输出维度拼接
Tensor q = qkv.slice(0, d_model);
Tensor k = qkv.slice(d_model, d_model * 2);
Tensor v = qkv.slice(d_model * 2, d_model * 3);

代码讲解：

• 三个小矩阵乘合并成一个大的，减少2次内核启动开销
• 减少输入张量的读取次数，提升显存带宽利用率
• 实现简单，收益稳定，是算子融合的标配优化

4.4.4 自动前缀缓存

按内容哈希匹配KV，相同前缀直接复用，跳过对应长度的预填充，多轮对话、重复系统提示场景收益极大。

核心匹配逻辑：

class PrefixCache {
    std::unordered_map<uint64_t, CacheEntry> table;

    CacheEntry* match(const std::vector<uint32>& tokens) {
        // 1. 优先完全匹配
        uint64_t full_hash = token_hash(tokens);
        if (table.count(full_hash)) {
            return &table[full_hash];
        }

        // 2. 降级：最长前缀匹配
        for (int len = tokens.size() - 1; len > 0; --len) {
            uint64_t prefix_hash = token_hash(tokens.data(), len);
            if (table.count(prefix_hash)) {
                CacheEntry* entry = &table[prefix_hash];
                if (entry->length <= len) {
                    return entry;
                }
            }
        }
        return nullptr;
    }
};

代码讲解：

• 先尝试完全匹配，再尝试最长前缀匹配，逐级降级
• 匹配成功直接复用KV，跳过对应长度的预填充
• 多轮对话、重复系统提示这类场景，命中后速度提升极多

五、环境配置与运行全教程

5.1 环境要求

• 显卡：NVIDIA GPU，显存≥20GB，推荐RTX 4090/同级别计算卡
• 系统：Linux
• 编译依赖 ：
  • CUDA Toolkit 12.x
  • Go 1.26 及以上
  • gRPC 与 protobuf
  • cuBLAS
• 磁盘：至少20GB空闲空间

5.2 获取模型

模型使用标准的Qwen3-8B safetensors格式，包含权重分片、索引文件、分词器文件与生成配置。

通过官方命令行工具下载：

pip install -U huggingface_hub[cli]
huggingface-cli download Qwen/Qwen3-8B --local-dir models/qwen3-8b

国内可配置镜像环境变量加速下载。

模型目录必须包含：

• config.json
• 权重分片与索引文件
• 分词器相关文件
• 生成配置文件

5.3 编译构建

构建系统自动执行三步：

1. cmake构建C++计算引擎
2. 把C++二进制复制到嵌入目录
3. go build生成最终可执行文件

最终产物：根目录下的单个可执行文件。

1. 指定显卡架构

如果不是sm_89架构，需要在编译引擎时指定目标架构：

cmake -B build -DCMAKE_CUDA_ARCHITECTURES=<你的显卡架构>
cmake --build build

5.4 运行方式

1. 服务模式（OpenAI兼容API）

./qwen3-8b serve --model models/qwen3-8b

默认监听8000端口，提供标准OpenAI接口：

• POST /v1/chat/completions：支持流式与非流式、工具调用
• GET /v1/models：模型列表
• GET /healthz：健康检查

常用参数：

• --max-ctx N：最大上下文长度
• --slots N：最大并发序列数
• --token-budget N：每调度步的token预算
• --addr：监听地址

2. 交互式聊天模式

./qwen3-8b chat --model models/qwen3-8b

进入多轮对话终端界面，内置命令：

• /exit / /quit：退出
• /reset：清空上下文
• /think on|off：切换思考显示模式

5.5 验证说明

• 确定性模式下输出与参考实现严格对齐
• BF16前向传播数值误差在正常范围内
• 所有优化路径都有正确性验证

六、落地用途与场景

6.1 企业内部轻量推理服务

需要私有化部署内部大模型服务的场景，这套引擎精简高效，单卡就能搭起8B模型的标准API服务，足够支撑中小团队内部使用，成本低、可控性强。

6.2 推理引擎教学与学习

代码从零实现、分层清晰、没有多余封装，非常适合学习大模型服务端推理原理、批处理调度、KV缓存、性能优化等核心技术。

6.3 定制化推理底座

有特殊业务需求、需要深度定制推理逻辑的场景，可以基于这套干净的代码底座做二次开发，不用在庞大的通用框架里找钩子，改起来更直接。

6.4 端侧与离线部署

单二进制、少依赖的特性，也适合离线工具、端侧服务这类部署场景，不需要复杂的环境依赖，开箱即用。

If you need the complete source code, please add the WeChat number (c17865354792)

七、总结

这套从零构建的Qwen3-8B推理引擎，用「C++/CUDA算内层、Go做外层服务」的双层架构，走完了从单文件教学程序到生产级服务引擎的完整演进路径，通过十几步逐项优化，最终把服务端吞吐做到了主流框架的95%以上。

它最大的价值不是性能超越通用框架，而是提供了一套干净、完整、可阅读、可修改的推理服务端实现范本，让开发者可以从最底层理解服务端推理的每一个优化点，同时也可以作为定制化推理服务的基础底座。

Welcome to follow WeChat official account【程序猿编码】