# 代码概述 - 飞桨大语言模型推理部署工具包

跳转至

English

# 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

## 六、开发指引速查

### 添加新模型

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

### 添加新算子

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

### 新硬件平台适配

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

### 优化推理性能

1. 注意力优化：`custom_ops/gpu_ops/append_attn/`
2. MoE 优化：`custom_ops/gpu_ops/moe/`
3. 图优化：`fastdeploy/model_executor/graph_optimization/`

### PD 分离部署

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

## 七、配置体系

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

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

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