安装指南¶
本指南将帮助你在不同环境下安装Genesis深度学习框架。
📋 系统要求¶
硬件要求¶
- CPU: x86_64架构,支持AVX指令集
- 内存: 最少8GB,推荐16GB+
- GPU: NVIDIA GPU with Compute Capability ≥ 6.0 (可选但推荐)
- 存储: 2GB可用空间
软件要求¶
- 操作系统: Linux (Ubuntu 20.04+), macOS (10.15+), Windows 10+
- Python: 3.8, 3.9, 3.10, 3.11
- CUDA: 11.0+ (GPU加速需要)
🚀 快速安装¶
方式一:从源码安装 (推荐)¶
Bash
# 1. 克隆仓库
git clone https://github.com/phonism/genesis.git
cd genesis
# 2. 创建虚拟环境 (推荐)
python -m venv genesis-env
source genesis-env/bin/activate # Linux/macOS
# genesis-env\\Scripts\\activate # Windows
# 3. 安装依赖
pip install -r genesis/requirements.txt
# 4. 安装Genesis
pip install -e genesis/
方式二:使用pip安装¶
🔧 详细安装步骤¶
第一步:准备Python环境¶
第二步:安装CUDA (GPU加速)¶
GPU支持说明
如果你只需要CPU版本,可以跳过此步骤。但强烈推荐安装CUDA以获得最佳性能。
Bash
# 下载CUDA Toolkit
wget https://developer.download.nvidia.com/compute/cuda/11.8.0/local_installers/cuda_11.8.0_520.61.05_linux.run
sudo sh cuda_11.8.0_520.61.05_linux.run
# 设置环境变量
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
第三步:安装核心依赖¶
Bash
# 创建并激活虚拟环境
python -m venv genesis-env
source genesis-env/bin/activate
# 升级pip
pip install --upgrade pip setuptools wheel
# 安装PyTorch (根据你的CUDA版本选择)
# CUDA 11.8
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
# CPU版本
# pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
# 安装Triton
pip install triton
# 安装其他依赖
pip install numpy matplotlib tqdm
第四步:安装Genesis¶
Bash
# 克隆源码
git clone https://github.com/phonism/genesis.git
cd genesis
# 查看可用版本
git tag
# 切换到稳定版本 (可选)
git checkout v0.1.0
# 安装Genesis
pip install -e genesis/
✅ 验证安装¶
运行以下代码验证安装是否成功:
Python
#!/usr/bin/env python3
"""Genesis安装验证脚本"""
def test_basic_import():
"""测试基础导入"""
try:
import genesis
import genesis.nn as nn
import genesis.optim as optim
print("✅ Genesis导入成功")
print(f" 核心模块: genesis, nn, optim")
print(f" 可用函数: {len([x for x in dir(genesis) if not x.startswith('_')])}")
except ImportError as e:
print(f"❌ Genesis导入失败: {e}")
return False
return True
def test_tensor_operations():
"""测试张量操作"""
try:
import genesis
# 创建张量
x = genesis.randn(3, 4)
y = genesis.randn(3, 4)
# 基础运算
z = x + y
w = genesis.matmul(x, y.T) # 使用实际的Genesis API
print("✅ 张量运算正常")
print(f" 加法结果形状: {z.shape}")
print(f" 矩阵乘法形状: {w.shape}")
except Exception as e:
print(f"❌ 张量运算失败: {e}")
return False
return True
def test_neural_networks():
"""测试神经网络模块"""
try:
import genesis
import genesis.nn as nn
# 使用实际的Genesis模块创建简单模型
model = nn.Sequential([
nn.Linear(10, 5),
nn.ReLU(),
nn.Linear(5, 1)
])
# 测试前向传播
x = genesis.randn(2, 10)
y = model(x)
print("✅ 神经网络模块正常")
print(f" 模型层数: {len(list(model.parameters()))} 个参数张量")
print(f" 输出形状: {y.shape}")
except Exception as e:
print(f"❌ 神经网络模块失败: {e}")
return False
return True
def test_backend_support():
"""测试后端支持"""
try:
import genesis
from genesis.backend import default_device
# 测试基础后端功能
device = default_device()
x = genesis.randn(5, 5)
print("✅ 后端支持正常")
print(f" 默认设备: {device}")
print(f" 张量设备: {x.device}")
# 尝试检测CUDA是否可用
try:
# 测试是否可以创建CUDA张量
import torch
if torch.cuda.is_available():
print(" 检测到CUDA(通过PyTorch后端)")
else:
print(" CUDA不可用(仅CPU)")
except:
print(" 后端: Genesis原生")
except Exception as e:
print(f"❌ 后端测试失败: {e}")
return False
return True
def test_autograd():
"""测试自动微分"""
try:
import genesis
# 测试基础自动微分
x = genesis.randn(5, requires_grad=True)
y = genesis.functional.sum(x * x) # 使用实际的Genesis API
y.backward()
print("✅ 自动微分正常")
print(f" 输入形状: {x.shape}")
print(f" 梯度已计算: {x.grad is not None}")
print(f" 梯度形状: {x.grad.shape if x.grad is not None else 'None'}")
except Exception as e:
print(f"❌ 自动微分失败: {e}")
return False
return True
def test_optimizers():
"""测试优化器功能"""
try:
import genesis
import genesis.nn as nn
import genesis.optim as optim
# 创建简单模型和优化器
model = nn.Linear(5, 1)
optimizer = optim.Adam(model.parameters(), lr=0.01)
# 测试基础优化步骤
x = genesis.randn(3, 5)
y_pred = model(x)
loss = genesis.functional.sum(y_pred * y_pred)
optimizer.zero_grad()
loss.backward()
optimizer.step()
print("✅ 优化器功能正常")
print(f" 优化器类型: {type(optimizer).__name__}")
print(f" 学习率: 0.01")
print(f" 参数已更新: {len(list(model.parameters()))}")
except Exception as e:
print(f"❌ 优化器测试失败: {e}")
return False
return True
def test_serialization():
"""测试模型保存/加载"""
try:
import genesis
import genesis.nn as nn
# 创建并保存模型
model = nn.Linear(3, 2)
state_dict = model.state_dict()
# 测试序列化功能
genesis.save(state_dict, 'test_model.pkl')
loaded_state = genesis.load('test_model.pkl')
print("✅ 序列化功能正常")
print(f" 模型保存和加载成功")
print(f" 状态字典键数量: {len(state_dict)}")
# 清理
import os
if os.path.exists('test_model.pkl'):
os.remove('test_model.pkl')
except Exception as e:
print(f"❌ 序列化测试失败: {e}")
return False
return True
if __name__ == "__main__":
print("🔍 Genesis安装验证\n")
tests = [
test_basic_import,
test_tensor_operations,
test_neural_networks,
test_backend_support,
test_autograd,
test_optimizers,
test_serialization
]
passed = 0
total = len(tests)
for test in tests:
try:
if test():
passed += 1
except Exception as e:
print(f"❌ 测试异常失败: {e}")
print()
print(f"📊 测试结果: {passed}/{total} 通过")
if passed == total:
print("🎉 恭喜!Genesis安装成功,所有功能正常!")
elif passed >= total * 0.8: # 80%通过率
print("✅ Genesis安装基本成功!检测到少量问题。")
print(" 大部分功能正常运行。请检查上面的失败测试。")
else:
print("⚠️ Genesis安装存在问题。请检查:")
print(" 1. Genesis正确安装: pip install -e .")
print(" 2. 依赖已安装: pip install torch triton")
print(" 3. Python版本为3.8+")
将上述代码保存为 test_installation.py
并运行:
🔧 常见问题解决¶
问题1:CUDA版本不匹配¶
错误信息:
解决方案:
Bash
# 检查系统CUDA版本
nvidia-smi
# 检查PyTorch CUDA版本
python -c "import torch; print(torch.version.cuda)"
# 重新安装匹配版本的PyTorch
pip uninstall torch torchvision torchaudio
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118
问题2:Triton编译失败¶
错误信息:
解决方案:
问题3:内存不足¶
错误信息:
解决方案:
Python
import genesis
# 启用内存优化
genesis.cuda.empty_cache()
# 减小批量大小
batch_size = 16 # 替代原来的32
# 启用梯度检查点 (如果支持)
model.gradient_checkpointing = True
问题4:导入错误¶
错误信息:
解决方案:
Bash
# 检查虚拟环境
which python
pip list | grep genesis
# 重新安装
pip uninstall genesis-dl
pip install -e genesis/
🐳 Docker安装¶
如果你遇到环境问题,可以使用Docker:
Bash
# 下载预构建镜像
docker pull genesis/genesis:latest
# 或构建自己的镜像
git clone https://github.com/phonism/genesis.git
cd genesis
docker build -t genesis:local .
# 运行容器
docker run -it --gpus all genesis:local bash
Dockerfile内容:
Docker
FROM nvidia/cuda:11.8-devel-ubuntu22.04
# 设置环境变量
ENV DEBIAN_FRONTEND=noninteractive
ENV PATH="/opt/conda/bin:$PATH"
# 安装系统依赖
RUN apt-get update && apt-get install -y \\
wget git build-essential && \\
rm -rf /var/lib/apt/lists/*
# 安装Miniconda
RUN wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh && \\
bash Miniconda3-latest-Linux-x86_64.sh -b -p /opt/conda && \\
rm Miniconda3-latest-Linux-x86_64.sh
# 创建环境并安装依赖
RUN conda create -n genesis python=3.9 -y
SHELL ["conda", "run", "-n", "genesis", "/bin/bash", "-c"]
RUN pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu118 && \\
pip install triton numpy matplotlib tqdm
# 复制并安装Genesis
COPY . /workspace/genesis
WORKDIR /workspace/genesis
RUN pip install -e genesis/
# 设置启动命令
ENTRYPOINT ["conda", "run", "-n", "genesis"]
CMD ["bash"]
📊 性能优化建议¶
安装完成后,可以通过以下方式优化性能:
Bash
# 设置环境变量
export CUDA_VISIBLE_DEVICES=0 # 指定GPU
export PYTHONPATH=$PWD:$PYTHONPATH
# 启用优化选项
export GENESIS_OPTIMIZE=1
export TRITON_CACHE_DIR=/tmp/triton_cache
🎯 下一步¶
安装完成后,建议:
如果在安装过程中遇到问题,请查看FAQ或在GitHub上提交issue。