一、Python 版本不兼容（如 “SyntaxError: invalid syntax” 在 Python 3.8 运行 3.10 + 代码）
- 解决办法：
- 查看项目README确认支持的 Python 版本（大模型项目通常要求 3.9+）。
- 用 conda 创建指定版本环境：conda create -n llm_env python=3.10。
- 升级 Python（Linux：sudo apt install python3.10；Windows：官网下载安装）。
- 若依赖库不支持高版本，降级 Python（如从 3.11 降到 3.10）。
- 修改代码中高版本语法（如match语句改为if-elif，|类型注解改为Union）。
二、深度学习框架版本冲突（如 PyTorch 与模型不兼容）
- 解决办法：
- 安装模型要求的框架版本（如 ChatGLM3 要求 PyTorch 1.10+）：pip install torch==2.0.1。
- 用conda install安装框架，自动解决依赖冲突：conda install pytorch==2.0.1 cudatoolkit=11.7 -c pytorch。
- 卸载冲突的库：pip uninstall torch torchvision，再重新安装适配版本。
- 检查框架与 CUDA 的兼容性（如 PyTorch 2.0 支持 CUDA 11.7/11.8）。
- 若使用 CPU，安装 CPU 版框架：pip install torch==2.0.1+cpu -f https://download.pytorch.org/whl/cpu/torch_stable.html。
三、第三方库版本不匹配（如 “ImportError: cannot import ‘AutoModel’ from transformers”）
- 解决办法：
- 安装指定版本的库：pip install transformers==4.30.2（参考项目requirements.txt）。
- 升级库到最新版：pip install –upgrade transformers accelerate（适合持续维护的项目）。
- 用pip check检测冲突，卸载冲突库后重新安装：pip uninstall tokenizers && pip install tokenizers==0.13.3。
- 安装完整依赖：pip install -r requirements.txt（确保所有库版本匹配）。
- 若库已更新接口，修改代码适配新接口（如from_pretrained参数变化）。
四、操作系统兼容性问题（如 Windows 安装 FlashAttention 失败）
- 解决办法：
- 优先使用 Linux 系统（大模型工具对 Linux 支持最好，如 Ubuntu 20.04/22.04）。
- Windows 系统启用 WSL2（安装 Ubuntu 子系统），在 WSL 中部署项目。
- 寻找 Windows 兼容版本的库（如flash-attn的 Windows 适配版）。
- 用 Docker 容器部署（如docker run -it –gpus all 镜像名），避免系统差异。
- macOS 用户选择 M 系列芯片适配的库（如pip install flash-attn –no-build-isolation针对 Apple Silicon）。
五、环境变量配置错误（如 “HF_HOME not set, model cache path invalid”）
- 解决办法：
- 设置模型缓存路径：export HF_HOME=/大磁盘路径/.cache/huggingface（避免默认路径空间不足）。
- 配置 CUDA 路径：export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH（Linux）。
- Windows 系统在 “环境变量” 中添加HF_HOME，值为缓存目录路径。
- 临时生效：启动项目前在终端执行export 变量名=值，永久生效则写入~/.bashrc（Linux）或.bash_profile（macOS）。
- 检查权限：确保环境变量指向的目录有读写权限（chmod 775 /路径）。