在 macOS 上安装与部署 CodeGeeX（非 OpenAI Codex），以下是完整操作指南——首个硬性门槛是芯片必须为 Apple Silicon：M1、M2、M3 或 M4，Intel 处理器 Mac 连基础演示都无法运行。系统版本需至少 macOS 13.0（Ventura），Python 版本固定于 3.8 到 3.10 之间。缺少任一条，后续步骤均无效。确认以上前提后，方可使用 Homebrew 安装依赖、创建虚拟环境、安装支持 MPS 的 PyTorch 与 Transformers，最终下载模型、验证 MPS 可用性并启动 Web 界面。
确认芯片类型与系统版本
打开「关于本机」→ 查看「芯片」行：只有显示 Apple M1、M2、M3 或 M4 才可继续；若显示 Intel，建议直接关闭页面，后续无需尝试。
系统版本同样不可忽略：进入「软件更新」→ 确保升级至 macOS 13.0（Ventura）或更高。macOS 12.x 虽可运行 Python，但 MPS 后端支持不完整，加载模型时常出错。
在终端中执行 python --version，输出必须为 3.8、3.9 或 3.10 —— Python 3.11 及以上版本与当前 CodeGeeX2 的 Transformers 存在 ABI 冲突，会引发 ImportError: cannot import name 'is_torch_available'，请避免使用。
安装必要依赖工具链
方法一：使用 Homebrew 安装核心组件（推荐）
先安装 Homebrew（若未安装）：
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
接着安装依赖：
brew install git python@3.10 llvm
方法二：手动安装 Python 3.10
前往 python.org 下载适用于 macOS 13+ 的 Python 3.10.x pkg 安装包，安装时勾选「Add Python to PATH」。请勿使用系统自带的 /usr/bin/python3，因其版本固定且缺乏 pip 权限，后续会遇到诸多问题。
安装完成后，在终端验证：
which python3 && python3 -m pip --version
输出路径应包含 /opt/homebrew/bin/python3 或 /usr/local/bin/python3，而非 /usr/bin/python3。此步骤若出错，后续操作将充满隐患。
配置虚拟环境并安装 CodeGeeX2
第一步：创建隔离环境
python3 -m venv ~/codegeex2-env
第二步：激活环境
source ~/codegeex2-env/bin/activate
第三步：升级 pip 并安装依赖
pip install --upgrade pip
pip install -r https://gitcode.com/gh_mirrors/co/CodeGeeX2/raw/main/requirements.txt
此步骤耗时较长，会自动下载 torch-2.3.0+cpu 和 transformers==4.36.2。若提示 torch 安装失败，说明你并非在 Apple Silicon 环境下运行——Intel Mac 无法安装带 MPS 支持的 torch，此时必须终止操作，切勿强行继续。
下载模型权重并验证 MPS 可用性
进入项目目录：
git clone https://gitcode.com/gh_mirrors/co/CodeGeeX2 && cd CodeGeeX2
执行 MPS 检查脚本：
python -c "import torch; print('MPS available:', torch.backends.mps.is_available())"
输出必须为 True，否则后续所有推理将回退至 CPU 模式，响应延迟超过 90 秒，基本无法进行交互。这一步至关重要。
下载 6B 模型（需要 Git LFS）：
git lfs install && git clone https://huggingface.co/THUDM/codegeex2-6b ./models/codegeex2-6b
模型文件夹结构必须为 ./models/codegeex2-6b/，内含 config.json、pytorch_model.bin、tokenizer.json 等 12 个核心文件。缺少任意一个，启动时会报 OSError: Unable to load weights from pytorch checkpoint。
启动本地 Web UI
确保仍然处于激活的虚拟环境中：
source ~/codegeex2-env/bin/activate
运行演示程序：
cd CodeGeeX2 && python demo/run_demo.py
终端出现 Running on local URL: http://127.0.0.1:7860 即表示成功。使用 Safari 或 Chrome 访问该地址，随意输入一段代码测试生成效果。
若浏览器显示空白或报 502 错误，请回看终端最后一行日志：若包含 “MPS is not available”，说明之前的 torch 检查被跳过，必须重新安装 torch 并指定 MPS 构建版本，否则前功尽弃。