走进大模型推理引擎：从理念到 C++20 实现 —— PhotonInfer 推理框架介绍

在现代AI开发中，大模型推理引擎正逐步成为构建高性能AI应用的核心基础设施。本文将带你深入了解大模型推理引擎的核心理念，比较当前主流推理框架的优劣，并探讨为何在 C++20 环境下实现推理引擎尤为必要。随后，我们将介绍 PhotonInfer 框架的整体设计思路与架构布局。

🎯 本教程面向谁？

本教程适合以下人群阅读：

具备 C++ 基础的开发者：希望通过实战提升对语言本身的理解，掌握更现代的 C++20 编程范式。
对现代 C++ 感兴趣的学习者：希望学习 Concepts、constexpr、模板元编程等特性在工程中的实际用法。
正在求职或准备面试的 C++ 开发者：通过构建完整框架提升项目能力，积累可展示的实战经验。
希望了解大模型推理原理的人：尤其是在 PyTorch、TensorFlow 等框架中有相关经验，想了解底层实现机制在 C++ 中的实现方式。

如果你希望从零构建一个现代化、类型安全、高性能的大模型推理引擎，那么这份系列教程将为你提供系统的思路与代码支撑。

💡 为什么现在学习推理引擎？

🔥 行业趋势

大模型推理服务正在爆发式增长，ChatGPT、Claude 等应用每天处理数亿次请求
推理引擎是 AI 基础设施的核心，市场需求巨大
掌握推理引擎开发，等于掌握了 AI 时代的”操作系统”

💰 职业机会

大厂（字节、阿里、腾讯）都在自研推理引擎，人才需求旺盛
薪资水平：推理引擎开发工程师平均薪资 40K-80K+
技术壁垒高，竞争相对较小

🚀 技术价值

这是 C++、CUDA、深度学习的完美结合
从底层算子到系统架构，全方位提升技术能力
一个项目就能展示你的多项技能

1. 什么是大模型推理引擎？

大模型推理引擎是一种以”高效执行”和”自动优化”为核心的软件系统。其目标是当给定一个训练好的大语言模型（如 LLaMA、GPT 等）时，系统能够高效地执行前向推理，自动处理内存管理、算子优化、批处理调度等复杂任务，从而避免繁琐的手动优化逻辑，提升推理的吞吐量、降低延迟并优化资源利用率。

1.1 基本概念

张量计算（Tensor Computation）
将模型权重和输入数据组织成多维张量，通过高效的矩阵运算完成推理计算。

算子融合（Operator Fusion）
将多个连续的小算子合并为单个大算子，减少内核启动开销和内存访问次数。

内存管理（Memory Management）
智能管理 GPU 内存，包括 KV Cache 的分页存储、动态分配与回收，避免内存碎片。

批处理调度（Batch Scheduling）
动态管理多个推理请求，通过连续批处理（Continuous Batching）技术提升 GPU 利用率。

1.2 核心挑战

性能优化：如何在保证精度的同时最大化吞吐量
内存效率：如何管理大型模型的权重和 KV Cache
延迟控制：如何降低首 Token 延迟（TTFT）和生成延迟
并发处理：如何高效调度多个并发请求

1.3 实际应用场景

🤖 AI 对话服务

ChatGPT、Claude 等对话应用的后端引擎
需要低延迟、高并发的推理能力
连续批处理技术让单 GPU 可同时服务数百用户

📝 代码生成工具

GitHub Copilot、Codeium 等代码补全工具
需要快速响应，支持长上下文
Paged Attention 技术有效管理长序列

🎮 游戏 AI

NPC 对话系统、剧情生成
需要实时推理，延迟敏感
C++ 实现可直接集成到游戏引擎

🔍 搜索引擎增强

智能搜索、问答系统
需要高吞吐量处理大量查询
批量推理大幅提升服务能力

📊 数据分析工具

文档摘要、数据分析助手
需要处理大量并发请求
连续批处理提升资源利用率

2. 主流推理引擎对比分析

目前在不同编程语言生态中，已经诞生了众多推理引擎。它们各具特色，覆盖深度学习训练、推理服务乃至边缘计算领域。

2.1 Python 生态

PyTorch / TensorFlow

优点：生态完善，模型丰富，易于使用，支持动态图。
缺点：运行时开销大，内存占用高，不适合生产级高并发场景。

vLLM

优点：连续批处理技术领先，吞吐量高，适合生产环境。
缺点：基于 Python，性能仍有提升空间，底层实现封装较深。

Text Generation Inference (TGI)

优点：Rust 实现，性能优秀，支持多种模型。
缺点：学习曲线陡峭，C++ 开发者难以直接贡献。

2.2 C++ 生态

llama.cpp

优点：性能卓越，量化支持完善，社区活跃，易于集成。
缺点：批处理能力有限，不支持动态调度，架构相对简单。

TensorRT

优点：NVIDIA 官方优化，性能极致，算子融合能力强。
缺点：闭源，绑定 NVIDIA 硬件，学习成本高。

ONNX Runtime

优点：跨平台支持，模型格式标准化，易于部署。
缺点：通用性导致优化不够深入，性能不如专用引擎。

2.3 其他语言生态

Rust 实现（如 candle）

优点：内存安全，性能优秀，现代化设计。
缺点：生态相对较小，C++ 开发者迁移成本高。

Go 实现（如 go-llama.cpp）

优点：并发模型优秀，部署简单。
缺点：性能不及 C++，GC 影响延迟。

3. 为什么选择 C++20 来实现推理引擎？

C++20 带来了诸多颠覆性特性，为推理引擎的高效实现奠定了基础：

3.1 Concepts 与类型安全

强类型约束

template <typename T>
concept Allocator = requires(T alloc, usize size) {
  { alloc.allocate(size) } -> std::same_as<Result<void*>>;
};

编译期类型检查，避免运行时错误
比传统的 SFINAE 更清晰、更易读
提供更好的 IDE 支持和错误信息

3.2 std::span 与零拷贝设计

内存安全与性能并存

1	std::span<f32> q_data(q.ptr<f32>(), q.size());

广泛使用 std::span 替代原始指针
零拷贝数据传递，提升性能
类型安全，避免缓冲区溢出

3.3 constexpr 与编译期优化

零运行时成本抽象

大量使用 constexpr 进行编译期计算
类型映射、错误码转换都在编译期完成
实现”零成本抽象”的设计理念

3.4 Result<T, E> 与错误处理

类型安全的错误传播

auto result = Tensor::create({2, 3}, DataType::Float32);
if (!result) {
  return result.error();
}

借鉴 Rust 的错误处理模式
强制显式错误处理，避免异常开销
比 C++23 的 std::expected 更早实现

3.5 模板元编程能力增强

编译期逻辑构建

支持更强大的编译期逻辑
能够构建”零运行时成本”的依赖追踪机制
实现编译期优化的算子调度

借助这些新特性，我们可以打造一个编译期友好、性能卓越、类型安全的推理引擎，填补 C++ 生态在现代推理引擎实现方面的空白。

4. 架构设计详解

4.1 模块化分层架构

核心层（Core Layer）

Tensor：多维数组抽象，支持 CPU/CUDA，设备无关设计
Buffer：统一的内存管理接口，支持对齐分配
Allocator：内存分配器抽象，使用 Concepts 约束接口
Result<T, E>：类型安全的错误处理，借鉴 Rust 设计

算子层（Operator Layer）

基础算子：Add、MatMul、Embedding
Transformer 算子：
- Multi-Head Attention（MHA）：支持标准注意力和分页注意力
- RMSNorm：层归一化，支持批量处理
- RoPE：旋转位置编码，支持批量计算
- SwiGLU：激活函数，融合实现
CUDA 内核：每个算子都有 GPU 优化实现，使用向量化访问

架构层（Architecture Layer）

LLaMAModel：完整的 LLaMA 模型实现
TransformerBlock：Transformer 块封装，支持前向传播
模型支持：Llama-3.2、Qwen3，易于扩展新架构

运行时层（Runtime Layer）

KVCacheManager：KV Cache 生命周期管理
BlockManager：块级内存分配与回收
BlockTable：序列到块的映射表，支持动态扩展

调度层（Scheduler Layer）

ContinuousBatchScheduler：连续批处理调度器核心
ContinuousBatchEngine：批处理引擎，管理请求生命周期
InferenceRequest：推理请求封装，包含状态跟踪

4.2 整体架构图

以下 PlantUML 图展示了 PhotonInfer 的分层架构和各模块之间的交互关系：

@startuml PhotonInfer Architecture
title PhotonInfer 整体架构设计

skinparam ComponentBackgroundColor #E6F3FF
skinparam ComponentBorderColor #2E75B6
skinparam PackageBackgroundColor #FFF4E6
skinparam PackageBorderColor #FF8C00

package "调度层 (Scheduler Layer)" #FFF4E6 {
  component [ContinuousBatchScheduler] as scheduler #FFE6E6
  component [ContinuousBatchEngine] as engine #FFE6E6
  component [InferenceRequest] as request #FFE6E6
}

package "运行时层 (Runtime Layer)" #FFF4E6 {
  component [KVCacheManager] as kv_cache #E6F3FF
  component [BlockManager] as block_mgr #E6F3FF
  component [BlockTable] as block_table #E6F3FF
}

package "架构层 (Architecture Layer)" #FFF4E6 {
  component [LLaMAModel] as model #E6F3FF
  component [TransformerBlock] as transformer #E6F3FF
}

package "算子层 (Operator Layer)" #FFF4E6 {
  component [MHA] as mha #E6F3FF
  component [RoPE] as rope #E6F3FF
  component [RMSNorm] as rmsnorm #E6F3FF
  component [SwiGLU] as swiglu #E6F3FF
  component [MatMul] as matmul #E6F3FF
  component [CUDA Kernels] as cuda_kernels #E6F3FF
}

package "核心层 (Core Layer)" #FFF4E6 {
  component [Tensor] as tensor #E6F3FF
  component [Buffer] as buffer #E6F3FF
  component [Allocator] as allocator #E6F3FF
  component [Result<T,E>] as result #E6F3FF
}

' 调度层到运行时层
scheduler --> engine
engine --> request
engine --> kv_cache
engine --> block_mgr
block_mgr --> block_table

' 运行时层到架构层
kv_cache --> model
block_table --> model
model --> transformer

' 架构层到算子层
transformer --> mha
transformer --> rope
transformer --> rmsnorm
transformer --> swiglu
transformer --> matmul
mha --> cuda_kernels
rope --> cuda_kernels
rmsnorm --> cuda_kernels
swiglu --> cuda_kernels
matmul --> cuda_kernels

' 算子层到核心层
mha --> tensor
rope --> tensor
rmsnorm --> tensor
swiglu --> tensor
matmul --> tensor
tensor --> buffer
buffer --> allocator
tensor --> result

note right of scheduler
  连续批处理调度
  Token级动态调度
end note

note right of kv_cache
  Paged Attention
  块级KV Cache管理
end note

note right of cuda_kernels
  GPU优化内核
  向量化内存访问
end note

@enduml

4.3 推理请求处理时序图

以下时序图展示了连续批处理调度器处理推理请求的完整流程：

@startuml Inference Request Flow
title PhotonInfer 推理请求处理流程

skinparam ParticipantBackgroundColor #E6F3FF
skinparam ParticipantBorderColor #2E75B6
skinparam SequenceArrowThickness 2

actor "Client" as client #FFE6E6
participant "ContinuousBatchScheduler" as scheduler #FFE6E6
participant "ContinuousBatchEngine" as engine #FFE6E6
participant "InferenceRequest" as request #E6F3FF
participant "LLaMAModel" as model #E6F3FF
participant "KVCacheManager" as kv_cache #E6F3FF
participant "BlockManager" as block_mgr #E6F3FF
participant "TransformerBlock" as transformer #E6F3FF
participant "CUDA Kernels" as cuda #E6F3FF

== 请求提交阶段 ==
client -> scheduler : submit_request(prompt)
activate scheduler
scheduler -> engine : add_request(request)
activate engine
engine -> request : create_request(prompt)
activate request
request -> request : 状态: WAITING
deactivate request
engine --> scheduler : request_id
deactivate engine
scheduler --> client : request_id
deactivate scheduler

== 两阶段调度：阶段1 - 继续运行中的请求 ==
scheduler -> engine : schedule_phase1()
activate engine
engine -> request : get_running_requests()
activate request
request --> engine : [req1, req2, ...]
deactivate request

loop 对每个运行中的请求
    engine -> model : forward(token, pos)
    activate model
    model -> kv_cache : get_cache(seq_id)
    activate kv_cache
    kv_cache -> block_mgr : allocate_blocks(seq_len)
    activate block_mgr
    block_mgr --> kv_cache : block_ptrs
    deactivate block_mgr
    kv_cache --> model : cache_data
    deactivate kv_cache

    model -> transformer : forward(token)
    activate transformer
    transformer -> cuda : MHA kernel
    activate cuda
    cuda --> transformer : attention_output
    deactivate cuda
    transformer -> cuda : RoPE kernel
    activate cuda
    cuda --> transformer : rotated_output
    deactivate cuda
    transformer -> cuda : RMSNorm kernel
    activate cuda
    cuda --> transformer : normalized_output
    deactivate cuda
    transformer --> model : output
    deactivate transformer

    model -> kv_cache : update_cache(seq_id, k, v)
    activate kv_cache
    kv_cache -> cuda : paged_kv_write kernel
    activate cuda
    cuda --> kv_cache : updated
    deactivate cuda
    deactivate kv_cache

    model --> engine : logits
    deactivate model

    engine -> request : update_state(num_computed_tokens++)
    activate request
    request -> request : 检查是否完成
    request --> engine : status
    deactivate request
end

deactivate engine

== 两阶段调度：阶段2 - 接纳新请求 ==
scheduler -> engine : schedule_phase2()
activate engine
engine -> request : get_waiting_requests()
activate request
request --> engine : [req3, req4, ...]
deactivate request

loop 直到GPU容量用完
    engine -> request : promote_to_running()
    activate request
    request -> request : 状态: WAITING -> RUNNING
    request -> block_mgr : allocate_initial_blocks()
    activate block_mgr
    block_mgr --> request : initial_blocks
    deactivate block_mgr
    deactivate request

    engine -> model : forward_prompt(prompt_tokens)
    activate model
    note right of model
      处理prompt的所有token
      建立KV Cache
    end note
    model --> engine : prompt_processed
    deactivate model
end

deactivate engine

== Token生成阶段 ==
loop 直到所有请求完成
    scheduler -> engine : generate_step()
    activate engine
    engine -> model : batch_forward(tokens)
    activate model
    model -> transformer : batched_forward()
    activate transformer
    transformer -> cuda : batched_mha kernel
    activate cuda
    cuda --> transformer : batch_output
    deactivate cuda
    transformer --> model : batch_output
    deactivate transformer
    model --> engine : batch_logits
    deactivate model

    engine -> request : sample_token(logits)
    activate request
    request -> cuda : sampling kernel
    activate cuda
    cuda --> request : next_token
    deactivate cuda
    request --> engine : next_token
    deactivate request

    engine -> request : check_completion()
    activate request
    alt 请求完成
        request -> request : 状态: RUNNING -> FINISHED
        engine -> block_mgr : free_blocks(seq_id)
        activate block_mgr
        block_mgr --> engine : freed
        deactivate block_mgr
    else 继续生成
        request -> request : 状态: RUNNING
    end
    deactivate request
    deactivate engine
end

scheduler --> client : response_tokens

@enduml

4.4 KV Cache 管理流程

以下流程图展示了 Paged Attention 中 KV Cache 的分配、使用和回收过程：

@startuml KV Cache Management
title Paged Attention KV Cache 管理流程

skinparam ParticipantBackgroundColor #E6F3FF
skinparam ParticipantBorderColor #2E75B6
skinparam SequenceArrowThickness 2

participant "InferenceRequest" as request #FFE6E6
participant "BlockManager" as block_mgr #E6F3FF
participant "BlockTable" as block_table #E6F3FF
participant "KVCacheManager" as kv_cache #E6F3FF
participant "CUDA Kernels" as cuda #E6F3FF
participant "GPU Memory" as memory #E6F3FF

== 初始化阶段：分配初始块 ==
request -> block_mgr : allocate_initial_blocks(seq_id, initial_len)
activate block_mgr
block_mgr -> memory : allocate_blocks(num_blocks)
activate memory
memory --> block_mgr : block_ptrs[]
deactivate memory
block_mgr -> block_table : register_blocks(seq_id, blocks)
activate block_table
block_table -> block_table : 创建序列映射表
block_table --> block_mgr : registered
deactivate block_table
block_mgr --> request : block_ptrs[]
deactivate block_mgr

== 推理阶段：写入KV Cache ==
request -> kv_cache : write_kv_cache(seq_id, k, v, pos)
activate kv_cache
kv_cache -> block_table : get_blocks(seq_id)
activate block_table
block_table --> kv_cache : blocks[]
deactivate block_table

kv_cache -> cuda : paged_kv_write(k, v, blocks, pos)
activate cuda
note right of cuda
  计算目标块和偏移
  向量化写入 (float4)
end note
cuda -> memory : write to GPU memory
activate memory
memory --> cuda : written
deactivate memory
cuda --> kv_cache : success
deactivate cuda
deactivate kv_cache

== 动态扩展：分配新块 ==
alt 序列长度超过当前块数
    request -> block_mgr : allocate_additional_blocks(seq_id, new_len)
    activate block_mgr
    block_mgr -> memory : allocate_blocks(additional_blocks)
    activate memory
    memory --> block_mgr : new_block_ptrs[]
    deactivate memory
    block_mgr -> block_table : append_blocks(seq_id, new_blocks)
    activate block_table
    block_table -> block_table : 更新映射表
    block_table --> block_mgr : updated
    deactivate block_table
    block_mgr --> request : new_block_ptrs[]
    deactivate block_mgr
end

== 读取阶段：Paged Attention ==
request -> kv_cache : read_kv_cache(seq_id, query, pos)
activate kv_cache
kv_cache -> block_table : get_blocks(seq_id)
activate block_table
block_table --> kv_cache : blocks[]
deactivate block_table

kv_cache -> cuda : paged_attention(query, blocks, pos)
activate cuda
note right of cuda
  分页注意力计算
  块级内存访问
  避免内存碎片
end note
cuda -> memory : read from GPU memory
activate memory
memory --> cuda : k, v data
deactivate memory
cuda --> kv_cache : attention_output
deactivate cuda
deactivate kv_cache

== 清理阶段：释放块 ==
request -> block_mgr : free_blocks(seq_id)
activate block_mgr
block_mgr -> block_table : get_blocks(seq_id)
activate block_table
block_table --> block_mgr : blocks[]
block_table -> block_table : 删除映射表项
deactivate block_table

block_mgr -> memory : free_blocks(blocks)
activate memory
memory -> memory : 回收内存到池
memory --> block_mgr : freed
deactivate memory
block_mgr --> request : success
deactivate block_mgr

@enduml

4.5 架构设计优势总结

通过以上架构图和时序图，我们可以看到 PhotonInfer 的设计优势：

1. 清晰的分层架构

各层职责明确，低耦合高内聚
易于理解和维护
便于扩展新功能

2. 高效的批处理调度

两阶段调度器最大化 GPU 利用率
Token 级粒度控制，精细调度
动态容量管理，灵活应对负载

3. 智能的内存管理

Paged Attention 避免内存碎片
块级分配回收，高效利用 GPU 内存
动态扩展，支持长序列

4. 类型安全的接口

Concepts 约束接口，编译期检查
Result<T, E> 显式错误处理
std::span 零拷贝，性能与安全并存

5. 性能基准测试

5.1 测试环境

GPU: NVIDIA A100 80GB
模型: Llama 3.2 1B
量化: INT8/Q8
对比基准: llama.cpp (业界标杆)

5.2 单次推理性能

指标	PhotonInfer	llama.cpp	对比
吞吐量	185 tok/s	252 tok/s	0.73×
TTFT	387ms @ 100-token	-	-

分析：

单次推理性能接近 llama.cpp，证明了核心算子的优化效果
首 Token 延迟（TTFT）控制在 400ms 以内，满足生产需求

5.3 批量推理吞吐量

批量大小	PhotonInfer	llama.cpp	加速比
4	410 tok/s	252 tok/s	1.63×
8	720 tok/s	255 tok/s	2.82×
16	787 tok/s	253 tok/s	3.07×

关键洞察：

批量推理性能显著优于 llama.cpp，最高达到 3.07× 加速
这证明了连续批处理调度器的价值：通过动态调度最大化 GPU 利用率
随着批量大小增加，优势更加明显，适合高并发生产场景

6. 快速开始与学习路径

6.1 环境准备

系统要求

编译器: GCC 12+ / Clang 14+ / MSVC 19.30+（需要 C++20 支持）
CMake: 3.20+
CUDA Toolkit: 12.0+（用于 GPU 支持）
GPU: NVIDIA GPU，计算能力 7.0+（V100、T4、A100、RTX 30xx/40xx）

依赖库

Eigen3：用于 CPU 线性代数运算
glog：日志记录
Google Test：单元测试（可选）

6.2 编译与运行

从源码编译

# 克隆仓库
git clone https://github.com/your-repo/photon_infer.git
cd photon_infer

# 配置构建
mkdir build && cd build
cmake -DCMAKE_BUILD_TYPE=Release -DPHOTON_BUILD_CUDA=ON -DPHOTON_USE_EIGEN=OFF ..

# 编译
cmake --build . -j$(nproc)

# 安装（可选）
sudo cmake --install .

运行推理 Demo

./bin/llama_infer \
    <checkpoint_path> \
    <tokenizer_path> \
    cuda \
    --quantize

启动 Web 服务

photon_web_server \
    --port 5728 \
    --model /path/to/llama-3.2-1B-Instruct \
    --tokenizer /path/to/llama-3.2-1B-Instruct/tokenizer.json

访问 http://localhost:5728 使用 Web 界面进行交互式推理。

6.3 GPU服务器配置步骤

本节介绍在 Ubuntu 22.04 服务器上配置 GPU 环境的完整流程，包括 NVIDIA 驱动安装、Docker 部署和源码编译两种方式。

6.3.1 NVIDIA 驱动安装

在安装 Docker 和 CUDA 之前，需要先正确安装 NVIDIA 驱动。如果遇到驱动版本冲突或仓库中没有对应版本的情况，可以按照以下步骤处理：

步骤 1：清理旧驱动和冲突包

如果系统中存在旧的 NVIDIA 驱动或相关包，需要先清理以避免冲突：

1
2
3

sudo apt remove --purge '^nvidia-.*' '^libnvidia-.*'
sudo apt autoremove
sudo apt autoclean

这一步会把残留的 NVIDIA 驱动和相关库全部清理掉。

步骤 2：添加官方 PPA（保证最新驱动可用）

Ubuntu 22.04 默认仓库可能没有最新的驱动版本，需要添加官方 PPA：

1 2	sudo add-apt-repository ppa:graphics-drivers/ppa sudo apt update

步骤 3：查看可用驱动版本

使用以下命令查看系统推荐的驱动版本：

1	ubuntu-drivers devices

输出示例：

vendor   : NVIDIA Corporation
model    : RTX 3080
driver   : nvidia-driver-535 - distro non-free recommended
driver   : nvidia-driver-525 - distro non-free

💡 提示：这里会显示可用版本和推荐版本，建议安装标记为 recommended 的版本。

步骤 4：安装推荐驱动

根据上一步的输出，安装推荐的驱动版本（例如 nvidia-driver-535）：

1	sudo apt install nvidia-driver-535

⚠️ 注意：不要随意猜测驱动版本，务必按照 ubuntu-drivers devices 输出的推荐版本安装。

步骤 5：更新 initramfs 并重启

安装完成后需要更新 initramfs 并重启系统以使驱动生效：

1 2	sudo update-initramfs -u sudo reboot

步骤 6：验证安装

重启后，使用以下命令验证驱动是否安装成功：

1	nvidia-smi

如果显示 GPU 信息和驱动版本，说明安装成功。

注意事项：

Ubuntu 22.04 不一定自带 555/580 的驱动包，需要添加 PPA
如果之前使用 .run 文件安装过驱动，必须先卸载，否则 apt 会报冲突
如果以后想自动安装推荐驱动，可以使用：

1	sudo ubuntu-drivers autoinstall

6.3.2 Docker 部署方式

Docker 部署是最简单快捷的方式，适合快速体验和测试。以下是完整的 Docker 安装和配置流程：

步骤 1：卸载旧版本（如有）

如果系统中存在旧版本的 Docker，需要先卸载：

1	sudo apt-get remove docker docker-engine docker.io containerd runc

步骤 2：更新 apt 并安装依赖

安装 Docker 所需的工具包：

1 2	sudo apt-get update sudo apt-get install -y ca-certificates curl gnupg lsb-release

步骤 3：添加 Docker 官方 GPG key

添加 Docker 官方的 GPG 密钥以确保软件包的安全性：

1
2
3

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | \
  sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

步骤 4：添加 Docker 官方软件源

添加 Docker 官方软件源到系统：

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] \
  https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

步骤 5：安装 Docker 引擎

更新软件包列表并安装 Docker 引擎及相关组件：

1 2	sudo apt-get update sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

步骤 6：验证安装成功

运行测试容器验证 Docker 是否安装成功：

1	sudo docker run hello-world

如果看到 “Hello from Docker!” 输出，说明 Docker 已经成功安装。

步骤 7：（可选）让普通用户使用 docker 命令

默认情况下只有 root 用户能运行 docker 命令。如果希望当前用户不用 sudo 也能运行：

1 2	sudo usermod -aG docker $USER newgrp docker

测试是否生效：

docker ps

应该不会报 permission denied 错误。

步骤 8：（可选）启用开机自启动

设置 Docker 服务开机自启动：

1 2	sudo systemctl enable docker sudo systemctl start docker

步骤 9：安装 NVIDIA Container Toolkit

如果要在 Docker 中运行 CUDA 程序，需要安装 NVIDIA Container Toolkit：

# 添加 NVIDIA Docker repository
distribution=$(. /etc/os-release;echo $ID$VERSION_ID)
curl -s -L https://nvidia.github.io/libnvidia-container/gpgkey | sudo apt-key add -
curl -s -L https://nvidia.github.io/libnvidia-container/$distribution/libnvidia-container.list | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list

# 安装 NVIDIA container toolkit
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit

# 配置 Docker 运行时
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

步骤 10：拉取并运行 PhotonInfer Docker 镜像

安装完成后，可以直接拉取预构建的 Docker 镜像并运行：

# 拉取镜像
docker pull lumia431/photon_infer:latest

# 运行容器（映射端口 5728）
docker run --rm --gpus all -p 5728:5728 -e PORT=5728 lumia431/photon_infer:latest

容器启动后，可以通过 http://localhost:5728 访问 Web 界面进行交互式推理。

6.3.3 源码编译方式

如果你需要自定义编译选项或深入了解项目结构，可以选择从源码编译。以下是完整的编译环境配置流程：

步骤 1：克隆仓库

首先克隆 PhotonInfer 的源代码仓库：

1 2	git clone https://github.com/lumia431/photon_infer.git cd photon_infer

步骤 2：安装 CUDA Toolkit

PhotonInfer 需要 CUDA 12.0+ 支持。可以从 NVIDIA CUDA Toolkit Archive 下载对应版本。

以 CUDA 12.5 为例，安装步骤如下：

# 下载并安装 CUDA repository pin 文件
wget https://developer.download.nvidia.com/compute/cuda/repos/ubuntu2204/x86_64/cuda-ubuntu2204.pin
sudo mv cuda-ubuntu2204.pin /etc/apt/preferences.d/cuda-repository-pin-600

# 下载 CUDA 12.5 安装包
wget https://developer.download.nvidia.com/compute/cuda/12.5.0/local_installers/cuda-repo-ubuntu2204-12-5-local_12.5.0-555.42.02-1_amd64.deb

# 安装 CUDA repository
sudo dpkg -i cuda-repo-ubuntu2204-12-5-local_12.5.0-555.42.02-1_amd64.deb
sudo cp /var/cuda-repo-ubuntu2204-12-5-local/cuda-*-keyring.gpg /usr/share/keyrings/

# 更新并安装 CUDA Toolkit
sudo apt-get update
sudo apt-get -y install cuda-toolkit-12-5

安装完成后，需要将 CUDA 添加到环境变量：

1 2	export PATH=/usr/local/cuda-12.5/bin:$PATH export LD_LIBRARY_PATH=/usr/local/cuda-12.5/lib64:$LD_LIBRARY_PATH

建议将上述环境变量添加到 ~/.bashrc 文件中以便永久生效。

步骤 3：下载模型文件

从 Hugging Face 下载模型权重和分词器文件：

# 下载模型权重文件
wget https://huggingface.co/Lummy666/llama-3.2-1B-Instruct/resolve/main/model.bin?download=true -O model.bin

# 下载分词器文件
wget https://huggingface.co/Lummy666/llama-3.2-1B-Instruct/resolve/main/tokenizer.model?download=true -O tokenizer.model

💡 提示：如果下载速度较慢，可以在本地下载后通过 scp 传输到服务器：
1
scp -P 16016 model.bin tokenizer.model user@your-server:/home/user/

步骤 4：安装 GCC 12+

PhotonInfer 需要 GCC 12+ 或 Clang 14+ 编译器（支持 C++20）。如果系统默认 GCC 版本较低，需要安装 GCC 12：

# 移除旧版本 GCC（可选）
sudo apt remove gcc g++

# 安装 GCC 12
https://mirrors.nju.edu.cn/gnu/gcc/gcc-12.5.0/

sudo apt-get install build-essential libgmp-dev libmpfr-dev libmpc-dev flex bison texinfo zlib1g-dev libisl-dev

mkdir build

./configure \
    --prefix=/home/vipuser/gcc-12.5.0/build \
    --enable-languages=c,c++ \
    --disable-multilib \
    --with-system-zlib

make -j$(nproc)

export PATH="/home/vipuser/gcc-12.5.0/build/bin:$PATH"
export LD_LIBRARY_PATH="/home/vipuser/gcc-12.5.0/build/lib64:/home/vipuser/gcc-12.5.0/build/lib:$LD_LIBRARY_PATH"

验证编译器版本：

1	gcc --version

应该显示 GCC 12.x 版本。

步骤 5：安装 CMake 3.20+

PhotonInfer 需要 CMake 3.20+。如果系统默认 CMake 版本较低，可以从官方下载：

wget -q https://github.com/Kitware/CMake/releases/download/v3.27.7/cmake-3.27.7-linux-x86_64.sh && \
    chmod +x cmake-3.27.7-linux-x86_64.sh && \
    sudo ./cmake-3.27.7-linux-x86_64.sh --prefix=/usr/local --skip-license && \
    rm cmake-3.27.7-linux-x86_64.sh

验证 CMake 版本：

1	cmake --version

步骤 6：安装依赖库

安装编译和运行所需的依赖库：

sudo apt install -y \
    libgtest-dev \
    libgmock-dev \
    libgoogle-glog-dev \
    libgflags-dev \
    libssl-dev

步骤 7：编译项目

配置并编译项目：

# 创建构建目录
mkdir build && cd build

# 配置构建（启用 CUDA 支持）
cmake -DCMAKE_BUILD_TYPE=Release -DPHOTON_BUILD_CUDA=ON -DPHOTON_USE_EIGEN=OFF ..

# 编译（使用多核加速）
cmake --build . -j$(nproc)

编译完成后，可执行文件位于 build/bin/ 目录下。

步骤 8：运行推理

使用编译好的可执行文件运行推理：

./bin/llama_infer \
    <checkpoint_path> \
    <tokenizer_path> \
    cuda \
    --quantize

将 <checkpoint_path> 和 <tokenizer_path> 替换为实际的模型文件路径。

7. 为什么选择 PhotonInfer？

7.1 技术深度与广度

现代 C++20 特性全面应用

Concepts、constexpr、std::span 等新特性的实际应用
类型安全的错误处理模式
零成本抽象的设计理念

GPU 并行计算实战经验

CUDA 内核编写与优化
内存管理最佳实践
性能分析与调优

深度学习推理引擎完整实现

从张量操作到模型推理的完整链路
Transformer 架构的底层实现
生产级特性（连续批处理、量化等）

7.2 稀缺性与独特性

C++20 推理引擎

市面上 99% 的推理引擎都是 Python 实现
C++20 实现的推理引擎少之又少
填补了 C++ 生态的空白

从零到一的完整实现

不是简单的 API 封装
从底层算子到调度器的完整实现
每个模块都有清晰的代码和文档

生产级特性

连续批处理：类似 vLLM 的动态调度
INT8 量化：硬件加速的量化推理
Paged Attention：高效的内存管理

7.3 学习价值

系统性学习路径

从基础概念到高级特性的完整教程
清晰的代码结构和注释
丰富的示例和测试用例

现代 C++ 最佳实践

类型安全优先的设计
零拷贝和移动语义的使用
编译期优化技巧

高性能计算经验

GPU 编程实战
内存优化策略
性能分析与调优

7.4 简历价值

项目亮点

✅ 技术栈全面：C++20 + CUDA + 深度学习
✅ 代码质量高：类型安全、零拷贝、模块化
✅ 性能优秀：批量推理 3× 加速
✅ 生产就绪：连续批处理、量化等工业级特性

面试优势

展示现代 C++ 编程能力
证明 GPU 并行计算经验
体现对深度学习底层原理的理解
展现系统设计和性能优化能力

7.5 学习成果展示

🎓 学完这个项目，你将能够：

掌握现代 C++20
- 熟练使用 Concepts、constexpr、std::span
- 理解零成本抽象的设计理念
- 掌握类型安全的错误处理模式
精通 GPU 编程
- 编写高效的 CUDA 内核
- 优化内存访问模式
- 使用 Nsight 工具进行性能分析
理解推理引擎
- 从张量操作到模型推理的完整链路
- Transformer 架构的底层实现
- 批处理调度和内存管理策略
具备系统设计能力
- 模块化架构设计
- 性能优化技巧
- 生产级代码规范

8. 总结

PhotonInfer 不仅仅是一个开源项目，更是一个完整的学习体系和技术展示平台。

无论你是：

准备校招的学生：需要一个能展示 C++ 和 AI 能力的项目
转行 AI 的开发者：想要深入理解大模型推理的底层实现
C++ 爱好者：想要学习现代 C++20 的最佳实践
高性能计算研究者：需要了解 GPU 推理引擎的实现细节

这个项目都能为你提供从理论到实践的完整路径。

项目资源

GitHub: https://github.com/lumia431/photon_infer
在线演示: https://photoninfer.xyz/
文档: 完整的 API 文档和设计文档
社区: 欢迎贡献代码和提出 Issue

感谢大家的阅读！如果这个项目对你有帮助：

⭐ 给项目点个 Star - 支持项目发展
🔄 分享给朋友 - 让更多人了解这个项目
💬 提出建议 - 帮助我们改进
🤝 贡献代码 - 一起构建更好的推理引擎