一、项目释义当下主流LLM推理引擎例如vLLM、TensorRT-LLM设计目标是通用性优先。一套代码要兼容几十款显卡、多种模型结构、多卡分布式、五花八门量化格式。为了适配各种场景代码里大量if分支、抽象封装层、动态shape逻辑会带来额外开销很难把单卡硬件性能压榨到极限。这个项目选择完全相反的路线高性能单GPU推理只适配选定的GPU型号与指定模型权重文件。不再做全硬件、全模型兼容砍掉所有为通用性准备的冗余逻辑聚焦在单张GPU上为指定模型做深度定制优化。整套引擎从零使用C20 CUDA开发原生支持Dense、MoE两类Transformer架构支持文本、图片、多图、视频混合多模态输入。对外提供两套交互入口本地命令行一次性推理兼容OpenAI、Anthropic协议的HTTP服务接口支持流式输出、工具调用、token用量统计。引擎设计约束进程启动时仅加载一个模型权重全程驻留显存最大并发请求数量在启动阶段固定范围1~8路请求队列采用FIFO。项目使用自定义模型工件文件工件内部打包模型配置、编码量化权重、算子绑定参数、多模态前端资源。支持的工件版本为V3旧版V2工件可以本地原地升级不需要重新下载权重。同时支持用户自行编写转换脚本把原始模型权重导出为本引擎的工件格式。支持的模型工件清单模型权重类型工件文件Qwen3.6-27Bgroupwise-intqwen3_6_27b.ninferQwen3.6-27Bnvfp4qwen3_6_27b_nvfp4.ninferQwen3.8-27Bgroupwise-intqwen3_8_27b.ninferQwen3.8-27Bnvfp4qwen3_8_27b_nvfp4.ninferQwen3.6-35B-A3Bgroupwise-intqwen3_6_35b_a3b.ninfer二、行业技术知识点1. Blackwell架构NVFP4量化目标GPU搭载Blackwell架构硬件原生支持NVFP4 4bit浮点计算。和传统INT4整数量化对比NVFP4保留浮点指数大模型权重压缩时精度损失更小。引擎手写CUDA算子原生支持NVFP4权重加载、反量化与矩阵计算无需上层框架格式转换。引擎同时支持BF16、INT8、FP8、K8V4多种KV缓存存储格式。2. MTP推测解码 DFlash增强推测解码MTP多候选推测解码原理是先用轻量Draft头并行生成多个候选token批量送入主模型一次性验证匹配成功直接输出失败则截断回退重生成。普通MTP支持1~5个draft token窗口35B-A3B模型额外支持DFlash增强推测解码draft窗口上限提升至15。DFlash可以加速多模态Prefill之后的文本解码阶段不参与图像编码加速。3. 分层KV缓存 精确前缀缓存复用KV缓存分为两层存储GPU显存设备缓存、主机锁页内存缓存。前缀检查点prefix checkpoint保存完整prompt对应的KV缓存模型状态快照。新请求到来时检索前缀哈希表命中则直接复用已计算好的KV跳过重复prefill长文档RAG场景收益巨大。当显存资源紧张调度器评估恢复开销自动把冷门前缀缓存从GPU显存迁移到主机锁页内存再次访问时拷贝回显存。4. Chunked Prefill 分块预填充 CUDA Graph 捕获Decode图超长prompt不会一次性全部送入GPU计算拆分为固定大小分块逐块prefill防止单次计算显存溢出。Decode阶段使用CUDA Graph捕获完整算子序列推理时直接提交Graph消除反复kernel launch带来CPU-GPU调度开销是高并发吞吐的核心优化手段。引擎使用精确批次CUDA Graph解码。5. 工件打包格式设计自定义V3工件文件把模型配置、量化权重、前端资源打包在单个二进制文件方便分发与版本管理。权重提前按照CUDA算子最优内存排布存储减少推理时的内存转置拷贝。三、架构设计思路整体架构划分为4大模块工件解析与权重加载模块、CUDA算子内核模块、KV缓存与资源调度模块、前端服务模块工件解析与权重加载模块读取自定义二进制工件解析模型结构、量化参数、权重数据。进程启动阶段一次性将权重反量化、重排内存布局拷贝到GPU显存运行阶段权重常驻显存。支持本地升级旧版本工件。CUDA算子内核模块手写CUDA Kernel专门针对sm_120a架构优化。编译阶段强制校验GPU架构非sm_120a直接编译失败。算子包含多头因果注意力、LayerNorm、FFN、NVFP4/FP8/groupwise-int量化矩阵乘、MTP验证算子、图像视频编解码算子。不依赖cuBLAS等通用矩阵库针对模型固定shape特化减少通用库额外开销。KV缓存与资源调度模块全局共享KV内存池所有并发请求共用这块显存空间。调度器负责追踪每个请求KV占用大小设备KV与主机锁页KV之间的数据迁移前缀缓存哈希查找、LRU淘汰、快照管理请求准入控制最大并发1~8路。KV池容量在进程启动时确定运行期间无法动态扩容。前端服务模块两套入口本地CLI一次性推理HTTP服务实现OpenAI Chat Completions、Anthropic消息协议支持SSE流式输出、token计数、工具调用。引擎只返回解析后的工具调用结构不会执行工具代码。图片、视频输入依赖FFmpeg库做视频帧解码。四、核心代码实现原理源码详细解读4.1 CMake构建脚本GPU架构强校验项目使用CMakeNinja构建强制C20标准。编译脚本增加CUDA架构硬校验只允许sm_120a#CMake片段限制CUDA架构if(NOT CMAKE_CUDA_ARCHITECTURES STREQUAL120a)message(FATAL_ERROREngine only support sm_120a GPU architecture. Other arch not allowed.)endif()# 构建预设定义include(CMakePresets)#release预设关闭测试与benchmark只编译推理主程序#dev预设开启单元测试、性能基准自动查找本地Python环境构建两个预设release生产版本关闭测试与benchmarkdev开发调试版本开启测试与性能基准自动检索Python解释器。重要特性项目没有install安装目标编译产物只能在build目录直接运行不做系统级安装部署。Python权重转换脚本独立于C编译流程HBM探测工具拥有独立编译命令。4.2 V3工件文件解析核心C代码工件是二进制文件使用mmap内存映射方式加载避免一次性大文件读入内存。文件头部保存元信息包含配置偏移、权重偏移、文件版本标识// 工件头部结构体定义structArtifactHeader{uint32_tmagic;uint32_tversion;uint64_tconfig_offset;uint64_tweight_offset;uint64_tweight_size;uint64_tresource_offset;uint64_tresource_size;};// 加载工件完整函数#includefcntl.h#includeunistd.h#includesys/mman.h#includecstdint#includestringstructModelArtifact{void*config_ptr;uint8_t*weights_ptr;size_t weight_bytes;};ModelArtifactload_artifact(conststd::stringartifact_path){intfdopen(artifact_path.c_str(),O_RDONLY);if(fd0){throwstd::runtime_error(open artifact file failed);}off_t file_szlseek(fd,0,SEEK_END);lseek(fd,0,SEEK_SET);void*mappedmmap(nullptr,file_sz,PROT_READ,MAP_SHARED,fd,0);if(mappedMAP_FAILED){close(fd);throwstd::runtime_error(mmap artifact failed);}ArtifactHeader*hdrreinterpret_castArtifactHeader*(mapped);if(hdr-version!3){munmap(mapped,file_sz);close(fd);throwstd::runtime_error(only support v3 artifact);}ModelArtifact art;art.config_ptrstatic_castuint8_t*(mapped)hdr-config_offset;art.weights_ptrstatic_castuint8_t*(mapped)hdr-weight_offset;art.weight_byteshdr-weight_size;returnart;}加载后将art.weights_ptr指向的量化权重通过cudaMemcpy一次性拷贝到GPU显存拷贝完成后根据量化类型在CUDA kernel内部实时做反量化计算。4.3 KV缓存分层存储结构体 C源码区分设备显存Buffer与主机锁页Buffer每个slot保存token长度与标记标记区分普通KV与可复用前缀检查点#includecuda_runtime.hstructDeviceBuffer{void*ptr;size_t bytes;~DeviceBuffer(){if(ptr)cudaFree(ptr);}};structHostPinnedBuffer{void*ptr;size_t bytes;~HostPinnedBuffer(){if(ptr)cudaFreeHost(ptr);}};structKVCacheSlot{DeviceBuffer k_dev;DeviceBuffer v_dev;HostPinnedBuffer k_host;HostPinnedBuffer v_host;size_t token_len;boolis_prefix_checkpoint;};调度器维护全局std::unordered_mapuint64_t, KVCacheSlot prefix_poolkey为prompt前缀哈希值。收到新请求计算prompt哈希查找prefix_pool命中直接复用slot跳过prefill。显存不足时调度器调用cudaMemcpyAsync将slot数据在GPU显存与主机锁页内存之间迁移。4.4 MTP推测解码执行控制逻辑 C// MTP推测解码主循环伪实现项目原生C逻辑非伪代码// draft_tokens配置的draft token数量如3// accept_threshold验证通过逻辑structMTPResult{std::vectorintaccept_tokens;inttruncate_pos;};MTPResultmtp_verify(ModelContext*ctx,conststd::vectorintdraft_tokens){// 将draft序列打包送入主模型一次性批量验证ctx-submit_draft_batch(draft_tokens);ctx-wait_cuda_graph();std::vectorintaccept;intcut_pos0;for(;cut_posdraft_tokens.size();cut_pos){if(ctx-get_verify_token(cut_pos)draft_tokens[cut_pos]){accept.push_back(draft_tokens[cut_pos]);}else{break;}}return{accept,cut_pos};}MTP流程主模型MTP Draft头并行生成N个候选draft token打包draft序列送入主模型使用CUDA Graph批量验证逐个比对token收集连续匹配token作为输出在第一个不匹配位置截断丢弃后面draft token主模型重新生成。4.5 HTTP服务请求处理逻辑OpenAI接口内置HTTP服务接收JSON请求解析messages送入调度器生成token后SSE流式返回。// HTTP请求处理核心逻辑voidhandle_chat_completion(HttpRequestreq,HttpResponseresp,Engine*engine){autochat_reqparse_json_chat(req.body);InferenceTask task;task.messageschat_req.messages;task.max_new_tokenschat_req.max_tokens;task.streamchat_req.stream;// 提交任务到调度器FIFO队列TaskHandle handleengine-submit_task(task);resp.set_header(Content-Type,text/event-stream);// 流式循环输出SSEwhile(true){autochunkengine-get_next_chunk(handle);if(chunk.is_finish)break;resp.write_chunk(build_sse_json(chunk));}resp.write_chunk(build_finish_event());}视频输入部分引擎调用FFmpeg libavformat/libavcodec库读取视频文件、解码视频帧送入视觉编码算子。五、环境配置与运行测试教程硬件硬性约束GPU目标NVIDIA显卡sm_120a架构OS64位LinuxWindows平台不支持完整软件依赖清单CMake ≥ 3.28Ninja构建工具C20兼容编译器GCC / ClangCUDA Toolkit 13.1官方验证版本CMake不强制下限但推荐使用13.1FFmpeg开发库libavformat、libavcodec、libavutil、libswscalelibcurl 7.85可选依赖Python环境仅用于权重转换脚本推理运行不需要Python编译步骤cd source_dir#Release正式编译cmake-S.-B build-G Ninja-DCMAKE_BUILD_TYPERelease cmake--build build-j编译完成可执行文件位于build/apps/两个核心程序cli-infer本地一次性CLI推理程序infer-serveHTTP推理服务程序模型工件下载使用HuggingFace CLI下载预打包工件放置models目录hf download 模型仓库标识 qwen3_8_27b_nvfp4.ninfer --local-dir models测试1本地CLI一次性推理./build/apps/cli-infer models/qwen3_8_27b_nvfp4.ninfer \--promptExplain prefill and decode, then give a concise conclusion.\--max-context32768\--max-new8192\--kv-dtype fp8 \--spec mtp--draft-tokens3\--lm-head-draft输出规则模型回答内容输出stdout启动日志、吞吐、时序、MTP验证统计信息输出stderr--log-level debug打印完整启动调试日志--messages FILE加载结构化对话文件--vision开启图片/视频多模态输入。测试2启动HTTP推理服务2并发./build/apps/infer-serve models/qwen3_8_27b_nvfp4.ninfer \ --max-context 240000 \ --kv-capacity 240000 \ --max-concurrency 2 \ --kv-dtype fp8 \ --device-state-slots 2 \ --host-state-slots 8 \ --host-kv-mib 8192 \ --spec mtp --draft-tokens 3 \ --lm-head-draft \ --preserve-thinking参数说明max-context单条请求逻辑最大token上限kv-capacity全局KV池总token容量max-concurrency最大并发请求数量device-state-slotsGPU显存保存状态快照数量host-state-slots主机内存保存状态快照数量host-kv-mib主机锁页KV缓存容量单位MiB--preserve-thinking保留模型内部思考推理内容。服务启动后监听127.0.0.1:8080。测试3调用OpenAI兼容接口curl[http://127.0.0.1:8080/v1/chat/completions](http://127.0.0.1:8080/v1/chat/completions) \ -H Content-Type: application/json \ -d {model:qwen3.8-27b,messages:[{role:user,content:Reply with one short sentence.}],max_tokens:64}Docker容器部署主机提前安装NVIDIA Container Toolkit# 构建镜像 docker build--tag llm-single-infer:local.# 启动容器挂载模型目录端口映射 docker run--rm \--gpusdevice0\--publish8080:8080\--volume$PWD/models:/models:ro\ llm-single-infer:local \ infer-serve/models/qwen3_8_27b_nvfp4.ninfer \--host0.0.0.0\--max-context240000\--kv-capacity240000\--max-concurrency2\--kv-dtype fp8 \--device-state-slots2\--host-state-slots8\--host-kv-mib8192\--spec mtp--draft-tokens3\--lm-head-draft \--preserve-thinking六、落地用途单卡私有化本地部署小团队、个人本地私有化部署大模型单卡即可承载27B/35B级别模型原生支持图文视频多模态对外提供OpenAI兼容API业务侧代码几乎不用修改。长文档RAG后端服务依托前缀缓存复用机制大量请求共用相同知识库Prompt大幅降低重复Prefill开销适合企业知识库、长文档问答场景。Blackwell架构底层学习研究全套CUDA算子、KV缓存调度、MTP推测解码手写实现没有厚重通用框架封装适合研究NVFP4量化、CUDA Graph、推测解码、分层KV缓存底层原理。多模态Agent原型快速验证原生支持图片、多图、视频输入支持保留模型thinking推理内容适合本地多模态Agent原型开发。离线Perplexity评估内置离线因果困惑度打分能力用于模型效果评估。七、实测性能数据全部测试基于目标GPU测试环境使用INT8 group-64 KV、CUDA Graph、MTP3每次请求生成8192 token并发MTP3解码吞吐tok/s / 候选token接受率模型配置C1C2C4C8C8/C1加速比Qwen3.6-27B groupwise-int185.8 / 68.2%247.0 / 69.0%309.5 / 68.4%535.0 / 68.3%2.88×Qwen3.6-27B nvfp4202.4 / 69.3%399.7 / 71.4%699.7 / 69.3%1146.9 / 68.6%5.67×Qwen3.6-35B-A3B groupwise-int642.5 / 68.6%907.2 / 66.3%1213.5 / 69.6%1380.7 / 68.0%2.15×Qwen3.8-27B nvfp4143.8 / 48.9%267.6 / 48.1%461.1 / 45.8%766.6 / 46.0%5.33×单请求Prefill性能tok/s模型配置7680 token短Prefill260096 token超长Prefill结构化MTP3解码Qwen3.6-35B-A3B groupwise-int17705.45247.0779.6Qwen3.6-27B groupwise-int3218.11614.8193.0Qwen3.6-27B nvfp411191.52510.6252.2Qwen3.8-27B groupwise-int3274.71609.7224.4Qwen3.8-27B nvfp48340.42203.1219.8模型评测结果0-shot单样本评测模型配置AIME 2025AIME 2026GPQA-DiamondERQARealWorldQAQwen3.6-27B groupwise-int86.67%93.33%86.87%--Qwen3.6-27B NVFP493.33%93.33%84.34%--Qwen3.6-35B-A3B groupwise-int90.00%90.00%85.35%--Qwen3.8-27B groupwise-int96.67%96.67%87.37%66.25%82.22%Qwen3.8-27B NVFP496.67%96.67%90.40%66.25%83.53%If you need the complete source code, please add the WeChat number (c17865354792)八、项目边界与局限单引擎进程只能绑定单张目标GPU不支持其他显卡型号无多卡分布式推理进程启动加载模型权重常驻显存运行期间不能动态切换模型不支持请求抢占、任务优先级QoS调度没有权重CPU/GPU动态换页能力引擎只返回解析后的工具调用信息不会执行任何工具源码内C头文件不作为对外SDK仅能在源码编译目录运行KV池容量、最大并发数量进程启动后固定运行阶段不可动态调整仅对显式实现的模型架构、shape、量化路径提供支持。Welcome to follow WeChat official account【程序猿编码】