★ FEATURED ARTICLE 如何构建 h2oGPT macOS 一键安装器从 conda 环境到 PyInstaller 打包的完整指南【免费下载链接】h2ogptPrivate chat with local GPT with document, images, video, etc. 100% private, Apache 2.0. Supports oLLaMa, Mixtral, llama.cpp, and more. Demo: https://gpt.h2o.ai/ https://gpt-docs.h2o.ai/项目地址: https://gitcode.com/gh_mirrors/h2/h2ogpt这篇指南带你把 h2oGPT macOS 一键安装器从零构建出来。你将学会准备 conda 编译环境、切换 CPU 与 MPSMetal GPU 加速两种构建目标、用 PyInstaller 把整个 Python 运行时和 OCR 工具链打进单个可执行文件。读完后你既能用一条命令出包也能看懂脚本内部在做什么。先说风险官方在 dev_installers/mac/README.md 中把该方案标注为Experimental实验性且仍在开发中。如果出包失败退回手动安装流程即可详见 docs/README_MACOS.md。一键安装器到底是什么手动安装 h2oGPT 要创建 conda 环境、装 PyTorch、编译llama-cpp-python需要 Rust 和 CMake、再装 OCR 依赖步骤多且容易卡住。一键安装器把这些全部固化Python 解释器、h2oGPT 代码、第三方库、Tesseract 与 poppler 命令行工具全部压缩进一个单文件可执行程序PyInstaller 的 one-file 模式运行时会自动解压到临时目录再执行。最终用户只需双击浏览器就会自动打开本地聊天界面理解这个产物后面所有打包参数的意义就清楚了我们要保证冻结环境里每个被动态导入的模块、每个被调用的外部命令都存在。前置条件开工前检查三件事构建机必须同时满足下面三个条件缺一不可条件原因不满足的后果已安装 conda构建脚本第一步就是command -v conda找不到直接退出脚本秒退Mac 实体机器PyInstaller 不支持跨平台构建交叉构建即在 A 系统产出 B 系统的安装包只能在 Mac 上出 macOS 包Homebrew 装好 tesseract 和 poppler脚本会从 Cellar 目录把这两个工具链整体复制进安装包供 OCR 与 PDF 文本抽取使用复制命令因路径不存在而失败 关于第三条注意脚本里拷贝的是写死的版本路径见下文如果你的 Homebrew 版本对不上得先手动修正这两行。一条命令完成构建 出包入口是 dev_installers/mac/build_mac_installer.sh。先说命令里一个容易踩的坑前面用的是.等价于source而不是bash。因为脚本内部靠conda activate修改当前 shell 的环境变量用bash执行的话激活发生在子 shell 里后续 pip 装依赖会装错地方。先克隆代码并构建 CPU 版git clone https://gitcode.com/gh_mirrors/h2/h2ogpt cd h2ogpt . ./dev_installers/mac/build_mac_installer.sh需要 MPSApple Silicon GPU 加速版时加一个环境变量即可BUILD_MPS1 . ./dev_installers/mac/build_mac_installer.sh两种目标的全部差异只有两处差异点CPU 版MPS 版llama-cpp 编译开关CMAKE_ARGS-DLLAMA_METALoffCMAKE_ARGS-DLLAMA_METALon仅当BUILD_MPS1最终使用的 spech2ogpt-osx-m1-cpu.spech2ogpt-osx-m1-gpu.spec两个 spec 除产物名称不同外打包逻辑完全一致。两种构建都会配合FORCE_CMAKE1强制走 CMake 编译避免命中旧的 pip 缓存轮子。构建脚本内部发生了什么对照 build_mac_installer.sh 源码整条流水线分七段全部可复现每次构建都先删旧环境再重建阶段动作为什么1 环境校验command -v conda失败即退出快速失败避免装到一半才报错2 清理删除项目根下的Tesseract-OCR、poppler目录防止上次的旧工具链混进新包3 重建环境conda env remove -n h2ogpt-mac后重建python3.10 rustRust 是编译 llama-cpp-python 的工具链4 装依赖依次安装requirements.txt走 PyTorch CPU 源、LangChain、PyMuPDF/ArXiv、Selenium/PlayWright、DocTR OCR 五个清单覆盖聊天、文档问答、OCR 全链路全程以reqs_optional/reqs_constraints.txt做版本约束5 编译 llama-cpp先pip uninstall llama-cpp-python再按LLAMA_METAL开关重装并加--no-cache-dir保证 Metal 开关真正生效6 拷贝工具链pip install PyInstaller从/opt/homebrew/Cellar/poppler/24.02.0/和/opt/homebrew/Cellar/tesseract/5.3.4_1/复制进项目根版本号是硬编码的本机 brew 版本不同要改这两行7 出包make clean dist→pip install ./dist/h2ogpt*.whl→pyinstaller spec先产出 h2ogpt 的 wheelMakefile 的dist目标执行setup.py bdist_wheel装进环境再打包安装器第 7 阶段有个细节值得知道setup.py 里install_requires不只是requirements.txt还合并了 LangChain、llama-cpp、DocTR、音频、图像等 8 个可选依赖清单所以装 wheel 时会把整条依赖树一次性拉齐。手动构建自己重新生成 spec 文件什么情况下不用脚本、走手动流程当你改了收集配置或依赖清单需要重新生成 spec 并调试打包行为时。流程分三步。第一步在项目根目录生成 spec。命令较长但每个参数都有明确职责pyi-makespec mac_run_app.py -F --nameh2ogpt-osx-m1-cpu \ --hidden-importh2ogpt --collect-allh2ogpt \ --recursive-copy-metadatatransformers \ --collect-datalangchain --collect-datagradio_client \ --collect-allgradio --collect-allsentencepiece \ --collect-allgradio_pdf --collect-allllama_cpp \ --collect-alltiktoken_ext \ --add-data../../Tesseract-OCR:Tesseract-OCR \ --add-data../../poppler:poppler参数作用与不改的后果参数作用漏掉的后果-F产出单文件包变成一堆散落文件的目录--hidden-importh2ogpt显式声明 h2ogpt 包动态导入的模块分析不出来启动 ImportError--collect-allpkg一次性收集该包的.py模块、数据文件、二进制对 6 个包各调一次gradio 组件、llama.cpp 绑定、tokenizer 文件缺失--collect-datalangchain/--collect-datagradio_client只收数据文件模板与静态资源丢失--recursive-copy-metadatatransformers递归拷包元数据运行时importlib.metadata读不到版本部分库启动报错--add-data../../xxx:xxx把项目根外的工具目录原样打进包../../是相对 spec 所在目录dev_installers/mac/用户机器没有 tesseract/poppler 时 OCR 与 PDF 抽取直接不可用第二步打开生成的h2ogpt-osx-m1-cpu.spec或 gpu 版在Analysis(...)调用里补上这一段module_collection_mode{ gradio : py, gradio_pdf : py, },这行是官方文档特别强调的关键修改。PyInstaller 默认以字节码pyc模式收集模块而 gradio 大量使用运行时动态注册按py源码模式收集才能避免启动时找不到模块。仓库里现成的 h2ogpt-osx-m1-cpu.spec 已经带这段配置可直接参考。第三步执行打包pyinstaller h2ogpt-osx-m1-cpu.spec产物落在dist/目录即dist/h2ogpt-osx-m1-cpu或-gpu。双击之后启动器做了什么安装器的入口是 dev_installers/mac/mac_run_app.py。理解它的四件事就能解释为什么冻结环境里还能跑通修复导入路径把自身目录和h2ogpt包下的src、iterators、gradio_utils、metrics、models子目录逐个追加进sys.path同时写入PYTHONPATH。冻结环境下模块搜索路径和正常 venv 不同不修就会大面积 ImportError。注入外部命令把随包携带的poppler/bin、poppler/lib、Tesseract-OCR拼进系统PATH并把NLTK_DATA指向随包的nltk_data。这样pdftotext、tesseract无需用户安装就能被文档问答链路调用。启动服务调用 generate.py 的entrypoint_main内部是H2O_Fire(main)启动前设h2ogpt_block_gradio_exitFalse防止 Gradio 退出、h2ogpt_score_model关掉评分模型省内存。因为走的是 h2oGPT 标准 CLI 入口环境变量形式的启动参数同样生效。开浏览器并保活读取h2ogpt_server_name/H2OGPT_SERVER_NAME默认localhost与GRADIO_SERVER_PORT默认7860拼出 URL 后webbrowser.open()随后进入while True: time.sleep(10000)死循环保持进程存活。验证结果 在 Finder 里进入h2ogpt/dist/双击h2ogpt-osx-m1-cpuMPS 版双击h2ogpt-osx-m1-gpu。预期看到三步控制台窗口弹出先打印PYTHONPATH、NLTK_DATA、PATH等调试信息——这正好验证了启动器的路径注入生效h2oGPT 服务在localhost:7860起来浏览器自动打开聊天界面。首次启动会很慢单文件包要先解压运行时模型权重首次还要从 Hugging Face 下载。模型选择建议看 docs/README_CPU.md 和 docs/README_GPU.md下载与配置问题查 docs/FAQ.md。注意事项 / 已知限制⚠️ 发布或长期使用前先把这几条边界条件记牢实验性方案官方标注 Experimental 且仍在迭代。出包异常时回退 docs/README_MACOS.md 的手动流程不要硬刚。只能 Mac 构建PyInstaller 不支持交叉构建Linux/Windows 机器产不出 macOS 安装包。产物未签名spec 中codesign_identity与entitlements_file均为None分发给同事前需要自行补 Apple 签名与公证否则 Gatekeeper 可能拦截。硬编码的 brew 版本脚本固定拷贝poppler/24.02.0与tesseract/5.3.4_1本机 Homebrew 版本不同时必须手动改这两行cp -R。模型不在包内安装器只封装运行时与依赖权重仍需首启下载或按 docs/README_offline.md 预置离线模型。构建耗时与体积llama-cpp-python 的 CMake 编译较慢单文件包内含完整运行时、六个核心库与 OCR 工具链产物偏大。建议稳定网络下构建并给dist/留足磁盘空间。【免费下载链接】h2ogptPrivate chat with local GPT with document, images, video, etc. 100% private, Apache 2.0. Supports oLLaMa, Mixtral, llama.cpp, and more. Demo: https://gpt.h2o.ai/ https://gpt-docs.h2o.ai/项目地址: https://gitcode.com/gh_mirrors/h2/h2ogpt创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
阅读完成 · 觉得有帮助？
