lxcxjxhx

Upload INSTALL.md with huggingface_hub

8624936 verified 24 days ago

preview code

Raw

History Blame Contribute Delete

10.2 kB

安装指南

本文档提供 HOS Model Optimizer 的详细安装步骤，涵盖系统要求、依赖安装、虚拟环境配置以及常见问题的解决方案。

系统要求

基础要求

组件	最低版本	推荐版本	说明
Python	3.8	3.10+	必须 64 位版本
CUDA	11.8	12.1+	GPU 加速必需
GPU VRAM	4GB	8GB+	针对 8GB 场景优化
系统内存	8GB	16GB+	量化/训练时需要
磁盘空间	10GB	50GB+	模型文件较大

操作系统支持

Windows 10/11（推荐）
Linux（Ubuntu 20.04+）
macOS（仅 CPU 推理）

硬件检测

安装前可以使用以下命令检测硬件：

# 检测 GPU 和 CUDA 版本
nvidia-smi

# 检测 Python 版本
python --version

# 检测系统内存
# Windows
systeminfo | findstr /C:"Total Physical Memory"
# Linux
free -h

依赖安装步骤

第一步：安装基础依赖

# 克隆项目
git clone https://github.com/hos-team/hos-model-optimizer.git
cd HOS-Model-Optimizer

# 基础安装（包含核心功能）
pip install -e .

第二步：安装可选依赖

根据使用场景选择安装：

# 量化相关（GGUF/AWQ/GPTQ）
pip install -e ".[quantization]"

# llama-cpp 推理（GGUF 格式）
pip install -e ".[inference]"

# vLLM 推理（高吞吐场景）
pip install -e ".[vllm]"

# SGLang 推理（结构化生成）
pip install -e ".[sglang]"

# 训练加速（Unsloth）
pip install -e ".[training]"

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

第三步：验证安装

# 检查版本
hos-optimizer --version

# 检查命令行工具
hos-quantize --help
hos-infer --help
hos-train --help
hos-deploy --help
hos-config --help

# 检查 GPU 可用性
python -c "import torch; print(f'CUDA available: {torch.cuda.is_available()}'); print(f'CUDA version: {torch.version.cuda}')"

依赖列表

核心依赖

包名	版本要求	说明
click	>=8.0.0	命令行框架
pyyaml	>=6.0	配置文件解析
requests	>=2.28.0	HTTP 请求
psutil	>=5.9.0	系统信息检测
torch	>=2.0.0	深度学习框架
transformers	>=4.35.0	模型加载和推理
datasets	>=2.14.0	数据集处理
peft	>=0.5.0	LoRA/QLoRA 训练

可选依赖

包名	版本要求	说明
autoawq	>=0.1.0	AWQ 量化
auto-gptq	>=0.5.0	GPTQ 量化
bitsandbytes	>=0.41.0	4-bit 量化支持
llama-cpp-python	>=0.2.0	GGUF 推理后端
vllm	>=0.2.0	vLLM 推理后端
sglang	>=0.1.0	SGLang 推理后端
unsloth	>=0.1.0	训练加速

虚拟环境配置

使用 Conda（推荐）

# 创建虚拟环境
conda create -n hos-optimizer python=3.10 -y

# 激活环境
conda activate hos-optimizer

# 安装项目
pip install -e .

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

使用 venv

# 创建虚拟环境
python -m venv hos-env

# 激活环境
# Windows
hos-env\Scripts\activate
# Linux/macOS
source hos-env/bin/activate

# 升级 pip
python -m pip install --upgrade pip

# 安装项目
pip install -e .

使用 Poetry

# 初始化项目（如果尚未初始化）
poetry init

# 添加依赖
poetry add click pyyaml requests psutil torch transformers datasets peft

# 安装可选依赖
poetry add autoawq auto-gptq bitsandbytes
poetry add llama-cpp-python
poetry add vllm
poetry add sglang

# 安装项目
poetry install

环境隔离建议

为不同场景创建独立环境

# 推理环境
conda create -n hos-infer python=3.10 -y
conda activate hos-infer
pip install -e ".[inference]"

# 训练环境
conda create -n hos-train python=3.10 -y
conda activate hos-train
pip install -e ".[training]"

# 完整环境
conda create -n hos-full python=3.10 -y
conda activate hos-full
pip install -e ".[all]"

固定依赖版本

# 导出依赖
pip freeze > requirements-frozen.txt

# 从固定版本安装
pip install -r requirements-frozen.txt

llama-cpp-python 安装

llama-cpp-python 是 GGUF 格式推理的核心依赖，安装时需要特别注意 CUDA 支持。

CPU 版本安装

# 纯 CPU 版本（无需 CUDA）
pip install llama-cpp-python

CUDA 版本安装（推荐）

Windows

# 设置环境变量（CUDA 12.x）
set CMAKE_ARGS="-DGGML_CUDA=on"
set FORCE_CMAKE=1

# 安装
pip install llama-cpp-python --force-reinstall --no-cache-dir

Linux

# 设置环境变量
export CMAKE_ARGS="-DGGML_CUDA=on"
export FORCE_CMAKE=1

# 安装
pip install llama-cpp-python --force-reinstall --no-cache-dir

指定 CUDA 版本

# CUDA 11.8
set CMAKE_ARGS="-DGGML_CUDA=on -DCMAKE_CUDA_ARCHITECTURES=80"

# CUDA 12.x
set CMAKE_ARGS="-DGGML_CUDA=on -DCMAKE_CUDA_ARCHITECTURES=89"

验证安装

# 检查是否支持 CUDA
python -c "from llama_cpp import Llama; print('llama-cpp-python installed successfully')"

# 测试 GPU 加速
python -c "
from llama_cpp import Llama
llm = Llama(model_path='path/to/model.gguf', n_gpu_layers=-1)
print('GPU offload layers:', llm.n_gpu_layers)
"

从源码编译

如果预编译版本不可用，可以从源码编译：

# 克隆 llama.cpp
git clone https://github.com/ggerganov/llama.cpp.git
cd llama.cpp

# 编译（CUDA 支持）
# Windows
cmake -B build -DGGML_CUDA=ON
cmake --build build --config Release

# Linux
mkdir build && cd build
cmake -DGGML_CUDA=ON ..
make -j$(nproc)

# 安装 llama-cpp-python
cd ../bindings/python
CMAKE_ARGS="-DLLAMA_CUBLAS=on" pip install --force-reinstall --no-cache-dir .

常见问题解决

问题 1：CUDA 不可用

症状：torch.cuda.is_available() 返回 False

解决方案：

# 检查 CUDA 安装
nvidia-smi

# 检查 PyTorch CUDA 版本
python -c "import torch; print(torch.version.cuda)"

# 重新安装 PyTorch（CUDA 12.1）
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

问题 2：llama-cpp-python 安装失败

症状：编译错误或缺少 CUDA 支持

解决方案：

# 方案 1：使用预编译 wheel
pip install llama-cpp-python --prefer-binary

# 方案 2：设置正确的 CUDA 路径
# Windows
set CUDA_PATH=C:\Program Files\NVIDIA GPU Computing Toolkit\CUDA\v12.1
set CMAKE_ARGS="-DGGML_CUDA=on"
pip install llama-cpp-python --force-reinstall --no-cache-dir

# Linux
export CUDA_HOME=/usr/local/cuda
export CMAKE_ARGS="-DGGML_CUDA=on"
pip install llama-cpp-python --force-reinstall --no-cache-dir

问题 3：内存不足（OOM）

症状：训练或推理时出现 CUDA out of memory

解决方案：

# 方案 1：减小批次大小
hos-train --model ./model --dataset ./data.json --batch-size 1

# 方案 2：启用梯度检查点
# 在配置文件中设置
gradient_checkpointing: true

# 方案 3：使用 QLoRA 代替 LoRA
hos-train --model ./model --dataset ./data.json --method qlora

# 方案 4：减小上下文长度
hos-infer --model ./model --max-model-len 512

问题 4：模型加载失败

症状：OSError: Model path does not exist

解决方案：

# 检查模型路径
python -c "
import os
path = './model'
print(f'Path exists: {os.path.exists(path)}')
print(f'Is directory: {os.path.isdir(path)}')
if os.path.isdir(path):
    print(f'Files: {os.listdir(path)}')
"

# 使用绝对路径
hos-infer --model C:/path/to/model --prompt "你好"

问题 5：依赖冲突

症状：pip install 时报依赖冲突

解决方案：

# 方案 1：使用虚拟环境隔离
conda create -n hos-clean python=3.10 -y
conda activate hos-clean
pip install -e .

# 方案 2：升级 pip
python -m pip install --upgrade pip

# 方案 3：使用 --no-deps 跳过依赖检查
pip install package-name --no-deps

问题 6：vLLM 安装失败

症状：vLLM 编译或安装失败

解决方案：

# 方案 1：使用预编译版本
pip install vllm --prefer-binary

# 方案 2：检查 CUDA 版本兼容性
# vLLM 需要 CUDA 11.8+ 或 12.x
nvidia-smi

# 方案 3：从源码安装
git clone https://github.com/vllm-project/vllm.git
cd vllm
pip install -e .

问题 7：Windows 路径问题

症状：路径中的反斜杠导致解析错误

解决方案：

# 使用正斜杠
hos-infer --model C:/path/to/model

# 使用双反斜杠
hos-infer --model C:\\path\\to\\model

# 使用引号包裹
hos-infer --model "C:\path\to\model"

问题 8：量化后模型精度下降

症状：量化后模型输出质量明显下降

解决方案：

# 方案 1：使用更高精度的量化
hos-quantize --method gguf --model ./model --quant-type Q5_K_M  # 5-bit
hos-quantize --method gguf --model ./model --quant-type Q8_0    # 8-bit

# 方案 2：使用 AWQ 量化（精度损失更小）
hos-quantize --method awq --bits 4 --model ./model

# 方案 3：评估 PPL 选择最佳量化方案
hos-quantize --method evaluate --model ./model-quantized

安装检查清单

完成安装后，运行以下检查：

# 1. 检查 Python 版本
python --version  # 应该 >= 3.8

# 2. 检查 CUDA 可用性
python -c "import torch; print(f'CUDA: {torch.cuda.is_available()}')"

# 3. 检查核心依赖
python -c "import transformers; import datasets; import peft; print('Core deps OK')"

# 4. 检查命令行工具
hos-optimizer --version

# 5. 运行简单推理测试
hos-infer --model Qwen/Qwen2.5-0.5B --prompt "Hello" --max-tokens 10

如果所有检查通过，说明安装成功！

下一步

阅读使用示例了解详细用法
查阅 API 文档了解 Python 接口
查看架构文档了解系统设计

lxcxjxhx
/

HOS-Model-Optimizer

安装指南

目录

系统要求

基础要求

操作系统支持

硬件检测

依赖安装步骤

第一步：安装基础依赖

第二步：安装可选依赖

第三步：验证安装

依赖列表

核心依赖

可选依赖

虚拟环境配置

使用 Conda（推荐）

使用 venv

使用 Poetry

环境隔离建议

llama-cpp-python 安装

CPU 版本安装

CUDA 版本安装（推荐）

Windows

Linux

指定 CUDA 版本

验证安装

从源码编译

常见问题解决

问题 1：CUDA 不可用

问题 2：llama-cpp-python 安装失败

问题 3：内存不足（OOM）

问题 4：模型加载失败

问题 5：依赖冲突

问题 6：vLLM 安装失败

问题 7：Windows 路径问题

问题 8：量化后模型精度下降

安装检查清单

下一步