docs/architecture.md

# HOS Model Optimizer 架构文档

## 目录

- [系统架构概述](#系统架构概述)
- [模块结构](#模块结构)
- [数据流图](#数据流图)
- [技术选型说明](#技术选型说明)

---

## 系统架构概述

HOS Model Optimizer 采用分层架构设计，以核心引擎为中心，通过模块化方式组织各个功能组件。

```
┌─────────────────────────────────────────────────────────┐
│                    CLI 命令行接口层                        │
│                   (hos_optimizer/cli.py)                 │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                    核心引擎层                             │
│              (hos_optimizer/core.py)                     │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐  │
│  │ 模型管理     │  │ 配置管理     │  │ 资源监控     │  │
│  └──────────────┘  └──────────────┘  └──────────────┘  │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                    功能模块层                             │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ 量化模块 │ │ 推理模块 │ │ 训练模块 │ │ 部署模块 │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
└────────────────────┬────────────────────────────────────┘
                     │
┌────────────────────▼────────────────────────────────────┐
│                    工具层                                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐  │
│  │ 日志工具 │ │ 文件工具 │ │ 网络工具 │ │ 硬件检测 │  │
│  └──────────┘ └──────────┘ └──────────┘ └──────────┘  │
└─────────────────────────────────────────────────────────┘
```

### 架构特点

1. **分层设计**：清晰的层次结构，上层依赖下层，下层不依赖上层
2. **模块化**：各功能模块独立，可单独使用和测试
3. **配置驱动**：通过配置管理系统统一控制各模块行为
4. **资源感知**：内置硬件检测和 VRAM 优化策略

---

## 模块结构

### 1. CLI 命令行接口层

**文件**: `hos_optimizer/cli.py`

**职责**:
- 提供统一的命令行入口
- 解析用户命令和参数
- 调用核心引擎执行操作
- 格式化输出结果

**设计模式**: 命令模式（Command Pattern）

```python
# 命令注册示例
@cli.command()
@click.option('--model', help='模型路径')
def quantize(model):
    """量化模型"""
    engine = CoreEngine()
    engine.quantize(model)
```

### 2. 核心引擎层

**文件**: `hos_optimizer/core.py`

**职责**:
- 协调各功能模块
- 管理模型生命周期
- 维护全局配置状态
- 提供统一的 API 接口

**核心类**:

#### CoreEngine
```python
class CoreEngine:
    """核心引擎类"""
    
    def __init__(self, config: Optional[Dict] = None):
        self.config = config or {}
        self.model_manager = ModelManager()
        self.config_manager = ConfigManager()
        self.resource_monitor = ResourceMonitor()
    
    def quantize(self, model_path: str, **kwargs):
        """量化模型"""
        pass
    
    def inference(self, model_path: str, **kwargs):
        """执行推理"""
        pass
    
    def train(self, model_path: str, **kwargs):
        """训练模型"""
        pass
    
    def deploy(self, model_path: str, **kwargs):
        """部署模型"""
        pass
```

#### ModelManager
```python
class ModelManager:
    """模型管理器"""
    
    def load_model(self, path: str) -> Any:
        """加载模型"""
        pass
    
    def save_model(self, model: Any, path: str):
        """保存模型"""
        pass
    
    def validate_model(self, path: str) -> bool:
        """验证模型"""
        pass
```

#### ConfigManager
```python
class ConfigManager:
    """配置管理器"""
    
    def load_config(self, path: str) -> Dict:
        """加载配置文件"""
        pass
    
    def save_config(self, config: Dict, path: str):
        """保存配置"""
        pass
    
    def merge_configs(self, base: Dict, override: Dict) -> Dict:
        """合并配置"""
        pass
    
    def validate_config(self, config: Dict) -> bool:
        """验证配置"""
        pass
```

#### ResourceMonitor
```python
class ResourceMonitor:
    """资源监控器"""
    
    def get_gpu_info(self) -> Dict:
        """获取 GPU 信息"""
        pass
    
    def get_vram_usage(self) -> float:
        """获取 VRAM 使用量"""
        pass
    
    def optimize_for_vram(self, vram_limit: float) -> Dict:
        """根据 VRAM 限制优化配置"""
        pass
```

### 3. 功能模块层

#### 3.1 量化模块

**文件**: `hos_optimizer/quantize.py`

**职责**:
- 实现多种量化算法（GGUF、AWQ、GPTQ）
- 提供量化质量评估（PPL 计算）
- 支持量化格式转换

**核心组件**:

```
quantize.py
├── QuantizationEngine          # 量化引擎基类
│   ├── GGUFQuantizer          # GGUF 量化器
│   ├── AWQQuantizer           # AWQ 量化器
│   └── GPTQQuantizer          # GPTQ 量化器
├── QualityEvaluator           # 质量评估器
│   └── PerplexityCalculator  # PPL 计算器
└── FormatConverter            # 格式转换器
```

**设计模式**: 策略模式（Strategy Pattern）

```python
class QuantizationEngine:
    """量化引擎基类"""
    
    def quantize(self, model: Any, config: Dict) -> Any:
        """执行量化"""
        raise NotImplementedError

class GGUFQuantizer(QuantizationEngine):
    """GGUF 量化器"""
    
    def quantize(self, model: Any, config: Dict) -> Any:
        # GGUF 量化实现
        pass
```

#### 3.2 推理模块

**文件**: `hos_optimizer/inference.py`

**职责**:
- 提供统一的推理接口
- 支持多种推理后端（llama-cpp、vLLM、SGLang）
- 实现性能监控和优化

**核心组件**:

```
inference.py
├── InferenceEngine             # 推理引擎基类
│   ├── LlamaCppBackend        # llama-cpp 后端
│   ├── VLLMBackend            # vLLM 后端
│   └── SGLangBackend          # SGLang 后端
├── PerformanceMonitor         # 性能监控器
│   ├── LatencyTracker        # 延迟追踪
│   ├── ThroughputTracker     # 吞吐量追踪
│   └── VRAMTracker           # VRAM 追踪
└── BackendSelector            # 后端选择器
```

**设计模式**: 工厂模式（Factory Pattern）+ 观察者模式（Observer Pattern）

```python
class InferenceEngine:
    """推理引擎基类"""
    
    def generate(self, prompt: str, **kwargs) -> str:
        """生成文本"""
        raise NotImplementedError

class BackendFactory:
    """后端工厂"""
    
    @staticmethod
    def create_backend(backend_type: str, **kwargs) -> InferenceEngine:
        """创建推理后端"""
        backends = {
            'llama-cpp': LlamaCppBackend,
            'vllm': VLLMBackend,
            'sglang': SGLangBackend
        }
        return backends[backend_type](**kwargs)
```

#### 3.3 训练模块

**文件**: `hos_optimizer/train.py`

**职责**:
- 实现 QLoRA 和 LoRA 微调
- 提供数据集加载和预处理
- 支持训练监控和日志

**核心组件**:

```
train.py
├── TrainingEngine              # 训练引擎
│   ├── QLoRATrainer           # QLoRA 训练器
│   └── LoRATrainer            # LoRA 训练器
├── DatasetProcessor           # 数据集处理器
│   ├── AlpacaFormatter       # Alpaca 格式处理器
│   └── ShareGPTFormatter     # ShareGPT 格式处理器
└── TrainingCallback           # 训练回调
    └── VRAMCallback          # VRAM 监控回调
```

**设计模式**: 模板方法模式（Template Method Pattern）

```python
class TrainingEngine:
    """训练引擎基类"""
    
    def train(self, dataset: Dataset, config: Dict):
        """训练流程模板"""
        self.prepare_data(dataset)
        self.setup_model(config)
        self.run_training()
        self.save_model()
    
    def prepare_data(self, dataset: Dataset):
        raise NotImplementedError
    
    def setup_model(self, config: Dict):
        raise NotImplementedError
    
    def run_training(self):
        raise NotImplementedError
    
    def save_model(self):
        raise NotImplementedError
```

#### 3.4 部署模块

**文件**: `hos_optimizer/deploy.py`

**职责**:
- 自动检测硬件环境
- 选择最优部署配置
- 启动和管理推理服务
- 提供健康检查接口

**核心组件**:

```
deploy.py
├── HardwareDetector            # 硬件检测器
│   ├── GPUDetector           # GPU 检测
│   ├── CPUDetector           # CPU 检测
│   └── MemoryDetector        # 内存检测
├── ConfigSelector             # 配置选择器
│   └── VRAMOptimizer         # VRAM 优化器
├── ServiceLauncher            # 服务启动器
│   ├── LlamaCppLauncher     # llama-cpp 启动器
│   ├── VLLMLauncher         # vLLM 启动器
│   └── SGLangLauncher       # SGLang 启动器
└── HealthChecker              # 健康检查器
```

**设计模式**: 建造者模式（Builder Pattern）

```python
class DeploymentBuilder:
    """部署构建器"""
    
    def __init__(self):
        self.hardware = None
        self.config = None
        self.launcher = None
    
    def detect_hardware(self) -> 'DeploymentBuilder':
        """检测硬件"""
        self.hardware = HardwareDetector.detect()
        return self
    
    def select_config(self) -> 'DeploymentBuilder':
        """选择配置"""
        self.config = ConfigSelector.select(self.hardware)
        return self
    
    def create_launcher(self) -> 'DeploymentBuilder':
        """创建启动器"""
        self.launcher = ServiceLauncher.create(self.config)
        return self
    
    def build(self) -> ServiceLauncher:
        """构建部署"""
        return self.launcher
```

### 4. 工具层

**文件**: `hos_optimizer/utils.py`

**职责**:
- 提供通用工具函数
- 日志记录和格式化
- 文件操作和路径处理
- 网络请求和下载

**核心组件**:

```
utils.py
├── Logger                      # 日志工具
│   ├── setup_logger()        # 配置日志
│   └── get_logger()          # 获取日志器
├── FileUtils                   # 文件工具
│   ├── ensure_dir()          # 确保目录存在
│   ├── get_file_size()       # 获取文件大小
│   └── download_file()       # 下载文件
├── NetworkUtils                # 网络工具
│   ├── download_model()      # 下载模型
│   └── check_connection()    # 检查连接
└── HardwareUtils               # 硬件工具
    ├── get_gpu_info()         # 获取 GPU 信息
    └── get_vram_usage()       # 获取 VRAM 使用量
```

---

## 数据流图

### 1. 量化流程数据流

```
用户输入
    │
    ▼
┌─────────────────┐
│ CLI 解析参数    │
│ (cli.py)        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ CoreEngine      │
│ 接收量化请求    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ModelManager    │
│ 加载模型        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ResourceMonitor │
│ 检测 VRAM       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ConfigManager   │
│ 生成优化配置    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ QuantizationEngine │
│ 执行量化        │
│ (GGUF/AWQ/GPTQ) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ QualityEvaluator│
│ 评估质量 (PPL)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ModelManager    │
│ 保存量化模型    │
└────────┬────────┘
         │
         ▼
    输出结果
```

### 2. 推理流程数据流

```
用户输入 (Prompt)
    │
    ▼
┌─────────────────┐
│ CLI 解析参数    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ CoreEngine      │
│ 接收推理请求    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ BackendSelector │
│ 选择最优后端    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ InferenceEngine │
│ 加载模型        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ PerformanceMonitor │
│ 开始监控        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ 执行推理        │
│ (generate)      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ PerformanceMonitor │
│ 记录性能指标    │
└────────┬────────┘
         │
         ▼
    输出结果
```

### 3. 训练流程数据流

```
用户输入
    │
    ▼
┌─────────────────┐
│ CLI 解析参数    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ CoreEngine      │
│ 接收训练请求    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ DatasetProcessor│
│ 加载数据集      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ DatasetProcessor│
│ 格式化数据      │
│ (Alpaca/ShareGPT)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ResourceMonitor │
│ 检测 VRAM       │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ConfigManager   │
│ 生成训练配置    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ TrainingEngine  │
│ 准备模型        │
│ (QLoRA/LoRA)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ TrainingEngine  │
│ 执行训练        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ VRAMCallback    │
│ 监控 VRAM 使用  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ModelManager    │
│ 保存模型        │
└────────┬────────┘
         │
         ▼
    输出结果
```

### 4. 部署流程数据流

```
用户输入
    │
    ▼
┌─────────────────┐
│ CLI 解析参数    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ CoreEngine      │
│ 接收部署请求    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ HardwareDetector│
│ 检测硬件环境    │
│ (GPU/CPU/Memory)│
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ConfigSelector  │
│ 选择最优配置    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ ServiceLauncher │
│ 启动服务        │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ HealthChecker   │
│ 健康检查        │
└────────┬────────┘
         │
         ▼
    服务运行中
```

---

## 技术选型说明

### 1. 编程语言

**选择**: Python 3.8+

**理由**:
- 丰富的机器学习和深度学习库生态
- 易于开发和维护
- 广泛的用户群体
- 良好的跨平台支持

### 2. 深度学习框架

**选择**: PyTorch 2.0+

**理由**:
- 动态计算图，易于调试
- 强大的 GPU 支持
- 丰富的模型库（Hugging Face Transformers）
- 活跃的社区支持

### 3. 模型库

**选择**: Hugging Face Transformers 4.35+

**理由**:
- 支持大量预训练模型
- 统一的模型接口
- 完善的文档和示例
- 活跃的社区

### 4. 量化技术

#### 4.1 GGUF (llama.cpp)

**用途**: CPU+GPU 混合推理

**优势**:
- 支持 CPU 和 GPU 混合推理
- 低 VRAM 场景友好
- 推理速度快
- 社区活跃

**适用场景**: 8GB VRAM 场景的首选

#### 4.2 AWQ (Activation-aware Weight Quantization)

**用途**: 4-bit 量化

**优势**:
- 精度损失最小
- 保护显著权重通道
- 适合小模型

**适用场景**: 需要高精度的量化场景

#### 4.3 GPTQ (GPU-based Post-Training Quantization)

**用途**: 4/8-bit 量化

**优势**:
- 基于 GPU 加速
- 逐层量化和误差补偿
- 兼容性好

**适用场景**: 通用量化场景

### 5. 推理后端

#### 5.1 llama-cpp-python

**用途**: GGUF 格式推理

**优势**:
- 支持 CPU+GPU 混合推理
- 低 VRAM 场景优化
- 推理速度快

**适用场景**: 8GB VRAM 场景

#### 5.2 vLLM

**用途**: 高吞吐推理

**优势**:
- PagedAttention 技术
- Continuous Batching
- 高吞吐量

**适用场景**: 高并发服务场景

#### 5.3 SGLang

**用途**: 结构化生成

**优势**:
- RadixAttention 技术
- 约束生成（JSON Schema）
- 多轮对话优化

**适用场景**: 结构化输出和多轮对话场景

### 6. 微调技术

#### 6.1 QLoRA (Quantized Low-Rank Adaptation)

**用途**: 4-bit 量化 + LoRA 微调

**优势**:
- 显存占用极低
- 训练速度快
- 精度损失小

**适用场景**: 8GB VRAM 场景的微调

#### 6.2 LoRA (Low-Rank Adaptation)

**用途**: 全精度 LoRA 微调

**优势**:
- 精度高
- 训练稳定
- 可解释性强

**适用场景**: 显存充足的微调场景

### 7. 配置管理

**选择**: YAML 格式

**理由**:
- 易于阅读和编写
- 支持复杂数据结构
- 良好的层级关系
- 广泛的工具支持

### 8. CLI 框架

**选择**: Click 8.0+

**理由**:
- 简洁的 API
- 强大的功能
- 良好的文档
- 支持复杂的命令行接口

### 9. 日志系统

**选择**: Python logging 模块

**理由**:
- 标准库，无需额外依赖
- 灵活的配置
- 支持多种输出格式
- 易于集成

### 10. 硬件检测

**选择**: psutil + nvidia-smi

**理由**:
- psutil: 跨平台系统监控
- nvidia-smi: GPU 信息检测
- 组合使用，覆盖全面

---

## 设计模式总结

### 1. 创建型模式

- **工厂模式**: BackendFactory 创建推理后端
- **建造者模式**: DeploymentBuilder 构建部署配置
- **单例模式**: ConfigManager 全局配置管理

### 2. 结构型模式

- **适配器模式**: 统一不同推理后端的接口
- **装饰器模式**: PerformanceMonitor 装饰推理过程
- **组合模式**: 配置文件的层级结构

### 3. 行为型模式

- **策略模式**: 不同量化算法的选择
- **观察者模式**: PerformanceMonitor 监控性能指标
- **模板方法模式**: TrainingEngine 定义训练流程
- **命令模式**: CLI 命令的执行

---

## 扩展性设计

### 1. 插件化架构

各功能模块采用插件化设计，易于添加新功能：

```python
# 注册新的量化器
class NewQuantizer(QuantizationEngine):
    def quantize(self, model: Any, config: Dict) -> Any:
        pass

# 注册到工厂
QuantizerFactory.register('new', NewQuantizer)
```

### 2. 配置驱动

通过配置文件控制模块行为，无需修改代码：

```yaml
# config.yaml
quantization:
  method: gguf
  bits: 4
  
inference:
  backend: llama-cpp
  n_gpu_layers: -1
```

### 3. 接口抽象

通过抽象基类定义统一接口，便于扩展：

```python
class InferenceEngine(ABC):
    @abstractmethod
    def generate(self, prompt: str, **kwargs) -> str:
        pass
```

---

## 性能优化策略

### 1. VRAM 优化

- 自动检测 VRAM 限制
- 动态调整批次大小
- 梯度检查点技术
- 模型量化

### 2. 推理优化

- KV Cache 管理
- 批处理推理
- GPU Offload 策略
- 内存映射（mmap）

### 3. 训练优化

- 梯度累积
- 混合精度训练
- LoRA 参数高效微调
- Unsloth 加速

### 4. 资源监控

- 实时 VRAM 监控
- 性能指标追踪
- 自动优化建议

---

## 安全性考虑

### 1. 模型安全

- 模型文件验证
- 信任远程代码控制
- 模型来源检查

### 2. 数据安全

- 数据集验证
- 敏感信息保护
- 日志脱敏

### 3. 网络安全

- API 认证
- 请求限流
- 输入验证

---

## 未来演进方向

### 1. 功能扩展

- 支持更多量化算法
- 支持更多推理后端
- 支持分布式训练
- 支持模型压缩

### 2. 性能优化

- 更智能的 VRAM 优化
- 更高效的批处理
- 更好的硬件兼容性

### 3. 用户体验

- Web UI 界面
- 可视化配置
- 自动化工作流

### 4. 生态集成

- 与 Hugging Face Hub 深度集成
- 支持更多模型格式
- 插件市场

---

## 附录

### A. 模块依赖关系

```
cli.py
  └── core.py
        ├── config.py
        ├── quantize.py
        ├── inference.py
        ├── train.py
        ├── deploy.py
        └── utils.py
```

### B. 关键类图

```
┌─────────────────┐
│   CoreEngine    │
├─────────────────┤
│ - config        │
│ - model_manager │
│ - config_manager│
├─────────────────┤
│ + quantize()    │
│ + inference()   │
│ + train()       │
│ + deploy()      │
└────────┬────────┘
         │
         ├──────────────┬──────────────┬──────────────┐
         │              │              │              │
         ▼              ▼              ▼              ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ModelManager │ │ConfigManager│ │Quantization │ │Inference    │
├─────────────┤ ├─────────────┤ ├─────────────┤ ├─────────────┤
│+load_model()│ │+load_config()│ │+quantize()  │ │+generate()  │
│+save_model()│ │+save_config()│ │+evaluate()  │ │+serve()     │
└─────────────┘ └─────────────┘ └─────────────┘ └─────────────┘
```

### C. 配置文件示例

```yaml
# 完整配置示例
model:
  path: ./model
  format: gguf

quantization:
  method: gguf
  type: Q4_K_M
  bits: 4

inference:
  backend: llama-cpp
  n_gpu_layers: -1
  n_ctx: 512
  n_batch: 512

training:
  method: qlora
  lora_rank: 16
  lora_alpha: 32
  epochs: 3
  batch_size: 2

deployment:
  use_case: general
  host: 0.0.0.0
  port: 8000
```

---

**文档版本**: 1.0  
**最后更新**: 2026-07-16  
**维护者**: HOS Team