ecGlypher新手安装分步指南（标准化流程）

VecGlypher 新手安装分步指南（标准化流程）

以下按「前置条件→环境检测→代码下载→环境安装→运行测试」的标准化步骤拆解，全程适配新手，所有命令可直接复制执行：

一、前置条件（必须满足，否则安装必失败）

1. 系统/硬件要求

场景	最低配置	推荐配置
仅推理（生成字形）	Linux/macOS/Windows(WSL2)、8G内存	Linux(Ubuntu20.04+)、8G内存+NVIDIA显卡（≥8G显存）
训练/微调	Linux、16G内存+NVIDIA显卡（≥16G）	Linux、32G内存+NVIDIA显卡（≥24G）

2. 基础工具要求

必须安装：Git（版本≥2.0）、Python（3.9~3.11，禁止3.12+，兼容性未验证）
系统依赖（SVG/字体处理核心）：
- Linux：libcairo2-dev libfreetype6-dev libxml2-dev libxslt1-dev
- macOS：cairo freetype libxml2 libxslt（需先装Homebrew）
- Windows：优先用WSL2（直接复用Linux依赖），原生Windows需装Visual Studio C++构建工具

二、环境检测（提前排查问题）

1. 检测Git是否安装

打开终端/命令行，执行：

bash 复制代码

git --version

✅ 输出git version x.x.x则正常；❌ 无输出则需安装Git（官网：https://git-scm.com/）。

2. 检测Python版本

bash 复制代码

python3 --version  # Linux/macOS/WSL
python --version   # Windows原生

✅ 输出Python 3.9.x/3.10.x/3.11.x则正常；❌ 版本不符则下载对应版本（https://www.python.org/）。

3. 检测系统依赖（仅Linux/macOS）

bash 复制代码

# Linux(Ubuntu/Debian)
dpkg -l | grep -E "cairo|freetype|libxml2|libxslt"
# macOS（需Homebrew）
brew list | grep -E "cairo|freetype|libxml2|libxslt"

✅ 输出对应依赖名称则已安装；❌ 无输出则先补装（参考「前置条件」）。

三、代码下载（克隆项目仓库）

步骤1：选择存放目录

建议在用户目录下创建项目文件夹，执行：

bash 复制代码

# Linux/macOS/WSL
mkdir -p ~/projects && cd ~/projects
# Windows(cmd/PowerShell)
mkdir %USERPROFILE%\projects && cd %USERPROFILE%\projects

步骤2：克隆代码仓库

bash 复制代码

# 官方仓库（若网速慢，替换为国内镜像：https://gitee.com/mirrors/VecGlypher.git）
git clone https://github.com/xk-huang/VecGlypher.git

# 进入项目根目录（后续所有操作均在此目录执行）
cd VecGlypher

✅ 执行后目录下会出现src/ docs/ scripts/等文件夹，说明克隆成功。

四、环境安装（核心步骤，隔离依赖+装包）

步骤1：创建并激活Python虚拟环境

（避免系统Python依赖冲突，必做）

bash 复制代码

# 创建虚拟环境（命名为vecglypher-env）
python3 -m venv vecglypher-env  # Linux/macOS/WSL
python -m venv vecglypher-env   # Windows原生

# 激活虚拟环境
# Linux/macOS/WSL（bash/zsh）
source vecglypher-env/bin/activate
# Windows(cmd)
vecglypher-env\Scripts\activate.bat
# Windows(PowerShell)
vecglypher-env\Scripts\Activate.ps1

✅ 激活成功后，终端开头会显示(vecglypher-env)标识。

步骤2：安装项目依赖

优先用国内PyPI镜像加速，执行：

bash 复制代码

# 升级pip（避免低版本pip安装失败）
pip install --upgrade pip -i https://pypi.tuna.tsinghua.edu.cn/simple

# 安装requirements.txt中的所有依赖
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

步骤3：运行环境配置脚本（自动化补全）

项目提供一键配置脚本，执行：

bash 复制代码

# 进入脚本目录
cd scripts/setup_env/

# 执行配置脚本（Linux/macOS/WSL）
bash setup_env.sh
# Windows原生：手动参考脚本内命令执行（或优先用WSL）

✅ 脚本无报错输出，说明环境配置完成。

五、运行测试（验证安装是否成功）

回到项目根目录，执行验证脚本，检查核心功能：

bash 复制代码

# 回到项目根目录
cd ../../

# 运行SVG解析验证脚本（核心功能测试）
python src/tools/svg_validate.py --test

测试结果判断

✅ 成功：终端输出SVG validation passed!，无报错；

❌ 失败：根据报错信息排查（优先参考docs/public/troubleshooting.md）：

若报错No module named 'cairo'：补装系统依赖（参考「前置条件」）；
若报错Python version too new：降级到Python3.10/3.11；
若报错Permission denied：Linux/macOS加sudo，Windows用管理员终端。

新手进阶：体验基础推理功能

测试成功后，可参考docs/public/inference.md运行字形生成：

bash 复制代码

# 单字符生成示例（需先下载预训练模型）
python scripts/eval_locally/infer_single_char.py --char "中" --model_path ./models/pretrained_model

生成的SVG文件会保存在output/目录，能正常打开即说明功能可用。