FastDeploy 代码结构详解

本文档详细介绍 FastDeploy 代码库的结构，帮助开发者快速了解各模块功能，便于开发和新功能扩展。

目录结构总览

FastDeploy/
├── fastdeploy/          # 核心代码目录
├── custom_ops/          # C++/CUDA 自定义算子
├── tests/               # 单元测试
├── scripts/             # 工具脚本
├── tools/               # 开发工具
├── docs/                # 文档
├── examples/            # 示例代码
├── benchmarks/          # 性能基准测试
├── dockerfiles/         # Docker 镜像构建文件
└── setup.py             # Python 包安装脚本

一、核心代码目录 (fastdeploy/)

主入口文件 fastdeploy/__init__.py 导出核心类：

LLM - 主入口类，离线推理接口
SamplingParams - 采样参数配置
ModelRegistry - 模型注册器
version - 版本信息

1. engine/ - 核心引擎模块

功能: 管理 LLM 推理的生命周期，协调各组件工作。

文件	功能	开发指引
`engine.py`	`LLMEngine` 核心引擎类，管理调度器、预处理器、资源管理器	修改引擎行为、添加新组件的入口
`async_llm.py`	异步 LLM 接口，`AsyncRequestQueue` 请求队列管理	异步推理、流式输出相关开发
`request.py`	请求核心数据结构：`Request`, `RequestOutput`, `RequestStatus`	新增请求字段、修改请求处理逻辑
`sampling_params.py`	`SamplingParams` 采样参数配置	添加新采样策略参数
`args_utils.py`	`EngineArgs` 引擎参数解析	新增引擎配置参数
`resource_manager.py`	GPU/CPU 资源管理	资源分配优化

子目录:

sched/ - 调度核心实现，包含 resource_manager_v1.py (核心调度逻辑所在)

2. model_executor/ - 模型执行器

功能: 模型推理的核心执行模块，包含模型定义、网络层、算子等。

2.1 models/ - 模型实现

文件/目录	功能	开发指引
`model_base.py`	`ModelRegistry` 模型注册基类	添加新模型必看
`deepseek_v3.py`	DeepSeek V3 模型	MoE 大模型参考
`ernie4_5_moe.py`	ERNIE 4.5 MoE 模型	百度主力模型
`ernie4_5_mtp.py`	ERNIE 4.5 MTP 多token预测	推测解码模型
`qwen2.py`	Qwen2 模型	通用模型参考
`qwen3.py`	Qwen3 模型	最新模型参考
`ernie4_5_vl/`	ERNIE 4.5 视觉语言模型	多模态模型开发参考
`qwen2_5_vl/`	Qwen2.5 VL 多模态模型	VL 模型参考
`paddleocr_vl/`	PaddleOCR VL 模型	OCR 多模态参考

2.2 layers/ - 网络层实现

子目录/文件	功能	开发指引
`attention/`	注意力机制实现 (flash_attn, append_attn, mla_attn)	优化注意力性能首选
`moe/`	MoE 层实现 (Cutlass, Triton, DeepGEMM 后端)	MoE 性能优化
`quantization/`	量化层 (FP8, W4A8, WINT2, Weight-only)	量化方案开发
`linear.py`	线性层实现	矩阵乘法优化
`embeddings.py`	嵌入层实现	词嵌入修改
`normalization.py`	归一化层 (RMSNorm, LayerNorm)	归一化优化
`rotary_embedding.py`	旋转位置编码 ROPE	位置编码修改
`sample/`	采样器实现	采样策略开发
`backends/`	硬件后端实现 (cuda, xpu, dcu, hpu, metax, gcu, npu)	新硬件适配入口

2.3 其他子模块

目录	功能	开发指引
`model_loader/`	模型权重加载器	新模型格式支持
`guided_decoding/`	引导解码 (JSON/regex 约束输出)	结构化输出开发
`graph_optimization/`	图优化 (CUDA Graph)	推理性能优化
`logits_processor/`	Logits 处理器	输出控制逻辑
`ops/`	Python 可调用算子 (按硬件平台组织)	算子调用入口

关键文件:

model_base.py - 模型基类、注册器定义
pre_and_post_process.py - 前后处理工具

3. scheduler/ - 调度器模块

功能: 请求调度，支持单机、分布式、PD 分离等场景。

注意: - 核心调度逻辑主要在 engine/sched/resource_manager_v1.py 中实现 - 本目录下的 scheduler 正在逐步废弃，PD 分离调度请使用 router/ 或 golang_router/

文件	功能	开发指引
`global_scheduler.py`	`GlobalScheduler` 分布式调度器 (Redis)	(逐步废弃)
`local_scheduler.py`	`LocalScheduler` 本地调度器	(逐步废弃)
`splitwise_scheduler.py`	`SplitwiseScheduler` PD 分离调度	(逐步废弃，请使用 router)
`dp_scheduler.py`	数据并行调度器	(逐步废弃)
`config.py`	`SchedulerConfig` 调度配置	调度参数调整
`storage.py`	存储适配器，封装 Redis 连接	存储层修改

调度核心实现 (engine/sched/):

文件	功能	开发指引
`resource_manager_v1.py`	核心调度逻辑，包含 `ScheduledDecodeTask`、`ScheduledPreemptTask` 等任务类	调度策略修改首选

4. entrypoints/ - API 入口

功能: 对外服务接口，包括离线推理和在线 API 服务。

文件	功能	开发指引
`llm.py`	`LLM` 主入口类，离线推理接口	使用 FastDeploy 入口
`engine_client.py`	引擎客户端	请求转发逻辑修改

4.1 openai/ - OpenAI 兼容 API

文件	功能	开发指引
`api_server.py`	FastAPI 服务器	部署服务入口
`protocol.py`	OpenAI 协议定义	API 格式修改
`serving_chat.py`	Chat Completion API	聊天接口开发
`serving_completion.py`	Completion API	补全接口开发
`serving_embedding.py`	Embedding API	向量化接口
`tool_parsers/`	工具调用解析器	Function Calling 开发

5. worker/ - Worker 进程模块

功能: 模型推理的实际执行进程。

文件	功能	开发指引
`gpu_model_runner.py`	GPU 模型运行器 (核心推理循环)	推理流程修改首选
`gpu_worker.py`	GPU Worker 进程管理	Worker 生命周期管理
`xpu_model_runner.py`	XPU 模型运行器	昆仑芯片适配
`hpu_model_runner.py`	HPU 模型运行器	Intel HPU 适配
`worker_process.py`	Worker 进程基类	进程管理逻辑

6. input/ - 输入处理模块

功能: 输入数据预处理，包括分词、多模态输入处理。

文件	功能	开发指引
`text_processor.py`	`BaseDataProcessor` 文本处理器基类	输入处理扩展
`ernie4_5_processor.py`	ERNIE 4.5 输入处理器	百度模型输入处理
`ernie4_5_tokenizer.py`	ERNIE 4.5 分词器	分词逻辑修改
`preprocess.py`	输入预处理工具	预处理流程

多模态处理子目录:

目录	功能
`ernie4_5_vl_processor/`	ERNIE 4.5 VL 图像/视频处理
`qwen_vl_processor/`	Qwen VL 多模态处理
`paddleocr_vl_processor/`	PaddleOCR VL 处理

7. output/ - 输出处理模块

功能: 推理结果后处理，流式输出管理。

文件	功能	开发指引
`token_processor.py`	`TokenProcessor` Token 输出处理	流式输出、推测解码
`pooler.py`	池化输出处理	Embedding 输出
`stream_transfer_data.py`	流式传输数据结构	数据传输格式

8. cache_manager/ - 缓存管理模块

功能: KV Cache 管理，支持前缀缓存、跨设备传输。

文件	功能	开发指引
`prefix_cache_manager.py`	`PrefixCacheManager` 前缀树缓存	KV Cache 优化首选
`cache_transfer_manager.py`	KV Cache 跨设备传输	PD 分离缓存传输
`cache_data.py`	`BlockNode`, `CacheStatus` 数据结构	缓存数据定义
`multimodal_cache_manager.py`	多模态缓存管理	多模态缓存

子目录:

transfer_factory/ - 缓存传输工厂 (IPC, RDMA)

9. platforms/ - 硬件平台支持

功能: 多硬件平台适配，定义各平台的算子和特性。

文件	功能	开发指引
`base.py`	`Platform` 基类，`_Backend` 枚举	新硬件适配入口
`cuda.py`	NVIDIA CUDA 平台	GPU 优化
`xpu.py`	百度昆仑 XPU 平台	昆仑芯片适配
`dcu.py`	AMD DCU (ROCm) 平台	AMD GPU 适配
`maca.py`	MetaX GPU (MACA) 平台	壁仞 GPU 适配
`intel_hpu.py`	Intel HPU 平台	Intel Gaudi 适配
`iluvatar.py`	天数智芯 GPU 平台	天数智芯适配

10. metrics/ - 监控指标模块

功能: Prometheus 指标收集，性能监控。

文件	功能	开发指引
`metrics.py`	Prometheus 指标定义	新增监控指标
`stats.py`	ZMQ 指标统计	分布式监控
`trace_util.py`	OpenTelemetry 分布式追踪	链路追踪

11. 其他重要模块

目录	功能	开发指引
`inter_communicator/`	进程间通信 (ZMQ)	Engine-Worker 通信修改
`spec_decode/`	推测解码 (MTP, N-gram)	推测解码策略开发
`distributed/`	分布式通信 (AllReduce)	分布式推理开发
`multimodal/`	多模态数据处理	多模态功能扩展
`reasoning/`	推理模式解析 (DeepSeek R1 风格)	思考链解析
`router/`	请求路由器，PD 分离调度推荐使用	PD 分离部署首选
`golang_router/`	Go 语言实现的路由器，PD 间调度性能更优	高性能 PD 分离场景
`eplb/`	Expert Parallel 负载均衡	MoE 负载均衡
`rl/`	强化学习 Rollout	RLHF 场景
`plugins/`	插件系统	自定义扩展
`logger/`	日志模块	日志格式修改
`trace/`	追踪模块	性能分析

12. 配置文件

文件	功能	开发指引
`config.py`	`FDConfig` 总配置类	配置参数修改入口
`envs.py`	环境变量配置	新增环境变量
`utils.py`	通用工具函数	工具函数复用

二、自定义算子目录 (custom_ops/)

功能: C++/CUDA 高性能算子实现，按硬件平台组织。

custom_ops/
├── gpu_ops/           # NVIDIA GPU 算子 (主要)
├── cpu_ops/           # CPU 算子
├── xpu_ops/           # 百度昆仑 XPU 算子
├── iluvatar_ops/      # 天数智芯 GPU 算子
├── metax_ops/         # MetaX GPU 算子
├── utils/             # 公共工具
└── third_party/       # 第三方库 (cutlass, DeepGEMM)

gpu_ops/ - GPU 算子详解

目录/文件	功能	开发指引
`append_attn/`	Append Attention 实现	注意力优化首选
`moe/`	MoE 算子 (fused_moe, expert_dispatch)	MoE 性能优化
`flash_mask_attn/`	Flash Mask Attention	注意力掩码优化
`mla_attn/`	Multi-Head Latent Attention	MLA 模型支持
`machete/`	Machete GEMM	矩阵乘法优化
`quantization/`	量化算子	量化性能优化
`sample_kernels/`	采样算子	采样性能优化
`speculate_decoding/`	推测解码算子	推测解码优化
`cutlass_kernels/`	CUTLASS 内核	高性能 GEMM
`cpp_extensions.cc`	C++ 扩展入口	新增算子注册入口
`append_attention.cu`	Append Attention 核心	注意力核心实现

关键算子文件:

fused_rotary_position_encoding.cu - 融合旋转位置编码
multi_head_latent_attention.cu - MLA 注意力
per_token_quant_fp8.cu - FP8 量化

三、测试目录 (tests/)

功能: 单元测试和端到端测试，按模块组织。

tests/
├── e2e/               # 端到端服务测试
├── operators/         # 算子单元测试
├── model_executor/    # 模型执行器测试
├── model_loader/      # 模型加载测试
├── layers/            # 网络层测试
├── scheduler/         # 调度器测试
├── cache_manager/     # 缓存管理测试
├── entrypoints/       # API 入口测试
├── input/             # 输入处理测试
├── output/            # 输出处理测试
├── metrics/           # 指标测试
├── distributed/       # 分布式测试
├── graph_optimization/# 图优化测试
├── quantization/      # 量化测试
├── multimodal/        # 多模态测试
├── xpu_ci/            # XPU CI 测试
├── ce/                # CE 环境测试
├── ci_use/            # CI 工具测试
└── conftest.py        # pytest 配置

测试目录详解

目录	内容	开发指引
`e2e/`	各模型服务完整测试 (ERNIE, Qwen, DeepSeek 等)	服务集成测试
`operators/`	算子单元测试 (`test_fused_moe.py`, `test_flash_mask_attn.py` 等)	算子开发必写测试
`layers/`	网络层测试 (attention, moe, quantization)	网络层测试
`model_executor/`	模型执行流程测试	模型执行测试
`scheduler/`	调度器功能测试	调度逻辑验证
`cache_manager/`	缓存管理测试	缓存逻辑验证

四、脚本工具目录 (scripts/)

功能: CI/CD、性能调优、工具脚本。

文件	功能	使用场景
`run_unittest.sh`	单元测试运行	本地测试
`run_ci_xpu.sh`	XPU CI 运行	昆仑 CI
`run_ci_hpu.sh`	HPU CI 运行	Intel HPU CI
`run_ci_dcu.sh`	DCU CI 运行	AMD DCU CI
`coverage_run.sh`	代码覆盖率统计	代码质量
`tune_cublaslt_int8_gemm.py`	cuBLASLt INT8 GEMM 调优	性能调优
`tune_cutlass_fp8_gemm.py`	CUTLASS FP8 GEMM 调优	性能调优
`offline_w4a8.py`	离线 W4A8 量化工具	模型量化
`extract_mtp_weight_from_safetensor.py`	MTP 权重提取	模型处理

五、其他目录

docs/ - 文档

使用文档、API 文档、架构设计文档

examples/ - 示例代码

各模型使用示例、部署示例

benchmarks/ - 性能基准

性能测试脚本、基准数据

tools/ - 开发工具

codestyle/ - 代码风格检查工具
dockerfile/ - Docker 构建工具

dockerfiles/ - Docker 镜像

各平台运行环境 Dockerfile

六、开发指引速查

添加新模型

参考 models/model_base.py 了解模型注册机制
在 models/ 下创建新模型文件
在 input/ 下添加对应的输入处理器
在 tests/model_executor/ 下添加测试

添加新算子

在 custom_ops/gpu_ops/ 下实现 CUDA 算子
在 cpp_extensions.cc 中注册算子
在 model_executor/ops/gpu/ 下添加 Python 封装
在 tests/operators/ 下添加测试

新硬件平台适配

参考 platforms/base.py 创建新平台类
在 custom_ops/ 下创建硬件算子目录
在 model_executor/layers/backends/ 下创建后端实现
在 worker/ 下创建模型运行器

优化推理性能

注意力优化：custom_ops/gpu_ops/append_attn/
MoE 优化：custom_ops/gpu_ops/moe/
图优化：fastdeploy/model_executor/graph_optimization/

PD 分离部署

路由器：router/router.py (Python 实现，推荐)
高性能路由：golang_router/ (Go 实现，PD 间调度性能更优)
缓存传输：cache_manager/cache_transfer_manager.py

七、配置体系

FDConfig (config.py)
├── ModelConfig      # 模型配置
├── CacheConfig      # 缓存配置
├── ParallelConfig   # 并行配置
├── SchedulerConfig  # 调度配置
├── LoRAConfig       # LoRA 配置
└── ...

环境变量配置 (envs.py)
├── FD_* 系列环境变量
└── 运行时行为控制

本文档涵盖了 FastDeploy 代码库的主要模块和关键文件，可作为代码导航和开发参考使用。如有疑问，请参考各模块的详细文档或源码注释。