# HOS Model Optimizer

HOS Model Optimizer 是一个面向小模型（0.5B-7B 参数）的完整优化工具链，针对 **8GB VRAM** 场景进行了深度优化。

## 项目介绍

本项目提供从模型量化、推理加速、微调到一键部署的全流程解决方案，帮助开发者在有限硬件资源下高效运行大语言模型。

### 核心特性

- **多种量化方案**：支持 GGUF、AWQ、GPTQ 三种主流量化格式
- **三后端推理引擎**：llama-cpp-python、vLLM、SGLang，自动选择最优后端
- **低资源微调**：QLoRA/LoRA 微调，8GB VRAM 即可训练 7B 模型
- **一键部署**：自动检测硬件并选择最优配置，快速启动 API 服务
- **智能配置**：根据场景自动生成 8GB VRAM 最优配置

## 核心功能列表

| 功能模块 | 说明 | 命令行工具 |
|---------|------|-----------|
| 量化 | GGUF/AWQ/GPTQ 量化、PPL 评估、格式转换 | `hos-quantize` |
| 推理 | 三后端统一接口、API 服务、交互模式、性能基准测试 | `hos-infer` |
| 训练 | QLoRA/LoRA 微调、数据集处理、模型合并 | `hos-train` |
| 部署 | 硬件检测、自动配置、一键启动 API 服务 | `hos-deploy` |
| 配置 | 最优配置生成、配置验证、模板管理 | `hos-config` |

## 快速开始

### 安装

```bash
# 基础安装
pip install -e .

# 安装全部依赖
pip install -e ".[all]"

# 按需安装
pip install -e ".[quantization]"   # 量化相关
pip install -e ".[inference]"      # llama-cpp 推理
pip install -e ".[vllm]"           # vLLM 推理
pip install -e ".[sglang]"         # SGLang 推理
pip install -e ".[training]"       # 训练加速
```

### 5 分钟上手

```bash
# 1. 量化模型（GGUF Q4_K_M）
hos-quantize --method gguf --model ./model --output ./model.gguf

# 2. 推理测试
hos-infer --model ./model.gguf --prompt "你好，请介绍一下自己"

# 3. 启动 API 服务
hos-infer --model ./model.gguf --serve --port 8000

# 4. 一键部署（自动检测硬件并选择最优配置）
hos-deploy --model ./model.gguf --model-size 7.0

# 5. 生成 8GB VRAM 最优配置
hos-config --generate --scenario inference_7b --model-path ./model
```

## 安装说明

### 系统要求

- Python >= 3.8
- CUDA >= 11.8（GPU 加速需要）
- 推荐 8GB+ VRAM（针对 8GB 场景优化）

### 安装方式

```bash
# 从源码安装
git clone https://github.com/hos-team/hos-model-optimizer.git
cd HOS-Model-Optimizer
pip install -e .

# 安装可选依赖
pip install -e ".[all]"
```

详细安装指南请参考 [INSTALL.md](INSTALL.md)。

## 使用示例

### 量化

```bash
# GGUF 量化（推荐 8GB VRAM 场景）
hos-quantize --method gguf --model ./model --output ./model.gguf --quant-type Q4_K_M

# AWQ 4-bit 量化
hos-quantize --method awq --bits 4 --model ./model --output ./model-awq

# GPTQ 量化
hos-quantize --method gptq --bits 4 --model ./model --output ./model-gptq

# 评估量化质量（PPL）
hos-quantize --method evaluate --model ./model-awq
```

### 推理

```bash
# 自动选择后端，单次推理
hos-infer --model ./model --prompt "什么是SQL注入？"

# 指定 vLLM 后端，启动 API 服务
hos-infer --backend vllm --model ./model --serve --port 8000

# 交互模式
hos-infer --model ./model --chat

# 性能基准测试
hos-infer --model ./model --benchmark
```

### 训练

```bash
# QLoRA 微调（8GB VRAM 可用）
hos-train --model Qwen/Qwen2.5-0.5B --dataset ./data.json --method qlora

# LoRA 微调并自动合并
hos-train --model ./model --dataset ./data.json --method lora --merge

# 自定义训练参数
hos-train --model ./model --dataset ./data.json \
    --epochs 3 --batch-size 2 --lr 2e-4 \
    --lora-rank 16 --lora-alpha 32
```

### 部署

```bash
# 部署 7B 模型
hos-deploy --model ./model.gguf --model-size 7.0

# 高并发场景
hos-deploy --model ./model.gguf --model-size 7.0 --use-case high_concurrency

# 多轮对话场景
hos-deploy --model ./model.gguf --model-size 7.0 --use-case multi_turn
```

更多示例请参考 [EXAMPLES.md](EXAMPLES.md)。

## 配置说明

### 配置文件格式

配置文件使用 YAML 格式，支持以下场景模板：

| 模板名称 | 说明 |
|---------|------|
| `llama_cpp` | llama-cpp 推理配置 |
| `vllm` | vLLM 推理配置 |
| `sglang` | SGLang 推理配置 |
| `quantize` | 量化配置 |
| `training` | 训练配置 |
| `deploy` | 部署配置 |

### 生成最优配置

```bash
# 根据场景生成
hos-config --generate --scenario inference_7b --model-path ./model

# 自动生成（根据模型大小和任务类型）
hos-config --auto --model-size 7.0 --task inference

# 验证配置文件
hos-config --validate --config my_config.yaml

# 列出所有模板
hos-config --list-templates

# 导出模板
hos-config --export-template llama_cpp --output ./llama_cpp.yaml
```

### 8GB VRAM 场景预设

| 场景 | 推荐后端 | 预期性能 |
|------|---------|---------|
| `inference_0.8b` | llama-cpp | 100+ tokens/s, 1-2GB VRAM |
| `inference_7b` | llama-cpp | 35-45 tokens/s, 5-6GB VRAM |
| `training_0.8b` | QLoRA | 2-3GB VRAM |
| `training_7b` | QLoRA | 6-8GB VRAM |
| `high_throughput_serving` | vLLM | 高吞吐服务 |
| `multi_turn_dialogue` | SGLang | 多轮对话优化 |

## 性能优化建议

### 推理优化

1. **选择合适的量化格式**
   - GGUF Q4_K_M：8GB VRAM 首选，平衡速度和精度
   - AWQ 4-bit：vLLM 后端首选，精度损失最小
   - GPTQ 4-bit：通用性好，兼容性强

2. **调整上下文长度**
   - 8GB VRAM + 7B 模型：建议 `n_ctx=512` 或 `max_model_len=512`
   - 8GB VRAM + 0.8B 模型：可使用 `n_ctx=2048`

3. **GPU Offload 策略**
   - llama-cpp：设置 `n_gpu_layers=-1` 全部 offload 到 GPU
   - 如果 OOM，逐步减少 offload 层数

4. **批处理优化**
   - vLLM：利用 Continuous Batching，设置合理的 `max_num_seqs`
   - SGLang：利用 RadixAttention，多轮对话可加速 3-5x

### 训练优化

1. **使用 QLoRA**：4-bit 量化 + LoRA，大幅降低显存需求
2. **梯度检查点**：启用 `gradient_checkpointing=True`
3. **梯度累积**：使用 `gradient_accumulation_steps` 模拟大批次
4. **Unsloth 加速**：安装 `unsloth` 可获得 2x 训练加速

### 部署优化

1. **自动配置**：使用 `hos-deploy` 自动检测硬件并选择最优配置
2. **健康检查**：部署后自动执行健康检查确保服务正常
3. **监控显存**：使用 `VRAMCallback` 监控训练过程中的显存使用

## 项目结构

```
HOS-Model-Optimizer/
├── hos_optimizer/
│   ├── __init__.py          # 包初始化，导出主要类
│   ├── cli.py               # 统一命令行接口
│   ├── config.py            # 配置管理和优化
│   ├── quantize.py          # 量化模块（GGUF/AWQ/GPTQ）
│   ├── inference.py         # 推理模块（llama-cpp/vLLM/SGLang）
│   ├── train.py             # 训练模块（QLoRA/LoRA）
│   ├── deploy.py            # 部署模块（硬件检测/自动配置）
│   └── utils.py             # 工具函数
├── docs/
│   └── architecture.md      # 架构文档
├── pyproject.toml           # 项目配置
├── requirements.txt         # 依赖列表
├── setup.py                 # 安装脚本
├── LICENSE                  # MIT 许可证
├── README.md                # 项目主文档（本文件）
├── INSTALL.md               # 安装指南
├── EXAMPLES.md              # 使用示例
└── API.md                   # API 文档
```

## 贡献指南

欢迎贡献！请遵循以下步骤：

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

### 开发规范

- 代码风格遵循 PEP 8，使用 `black` 格式化（行宽 100）
- 提交前运行 `flake8` 检查
- 新功能需要附带测试用例
- Commit message 使用语义化格式

```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试
pytest

# 代码格式化
black hos_optimizer/

# 代码检查
flake8 hos_optimizer/
```

## 许可证

本项目基于 [MIT License](LICENSE) 开源。

```
MIT License

Copyright (c) 2026 HOS Team

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
```

## 相关链接

- [安装指南](INSTALL.md) - 详细安装步骤
- [使用示例](EXAMPLES.md) - 完整使用示例
- [API 文档](API.md) - Python API 参考
- [架构文档](docs/architecture.md) - 系统架构说明
- [问题反馈](https://github.com/hos-team/hos-model-optimizer/issues)
- [项目源码](https://github.com/hos-team/hos-model-optimizer)