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）

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

2. 核心引擎层

文件: hos_optimizer/core.py

职责:

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

核心类:

CoreEngine

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

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

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

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）

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）

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）

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）

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. 插件化架构

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

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

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

2. 配置驱动

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

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

3. 接口抽象

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

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. 配置文件示例

# 完整配置示例
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