如何在requirements.txt中正确配置txtai依赖完成Heroku部署

报错核心原因 #

你遇到的两类报错对应两个明确问题：

1. 依赖声明格式错误：重复声明txtai、直接引用git仓库带扩展标记的写法不符合pip解析规则，会直接触发安装流程中断
2. Slug体积超限：全量安装txtai[pipeline]会默认拉入完整PyTorch、全量机器学习依赖，加上git拉取仓库时带入的源码、测试、文档文件、pip构建缓存，很容易突破Heroku 500M的slug大小上限；哪怕移除pipeline扩展，git源安装时拉取的全量仓库历史、开发态构建依赖也会把slug撑到1G以上，这也是你删了pipeline依赖还是报体积超限的直接原因。

正确配置步骤 #

1. 重写requirements.txt，规避冗余和重型依赖 #

• 不要直接引用txtai的git仓库地址作为依赖源：git安装会下载全量仓库文件（含测试用例、示例、文档，占额外空间），且扩展依赖解析容易出兼容问题，直接使用PyPI发布的稳定版即可
• 不要直接安装txtai[pipeline]全量扩展：这个扩展会一次性安装所有NLP、CV、音频方向的依赖，单是完整版PyTorch就接近700M，装完必然超容量。只安装你代码实际用到的依赖组件即可
• 去掉重复的txtai声明，同一依赖不要在requirements.txt里写两行
  参考常规文本搜索/嵌入场景的最小可用配置（总依赖体积约300M）：

streamlit==1.10.0
nltk==3.7
txtai==6.0.0 # 选择和你本地开发版本一致的稳定版即可
onnxruntime==1.15.1 # 用轻量ONNX运行时替代重型PyTorch做推理，体积小90%
sentence-transformers==2.2.2 # 需要句向量功能时再加
Pillow==9.5.0
beautifulsoup4==4.12.2

如果你确实需要用到依赖PyTorch的pipeline功能，不要装完整版PyTorch，在requirements.txt最顶部加CPU-only版本源，安装轻量CPU版PyTorch，比全量版小2/3：

--extra-index-url https://download.pytorch.org/whl/cpu
torch==2.0.1+cpu
torchvision==0.15.2+cpu

2. 配置.slugignore压缩slug体积 #

在项目根目录新建.slugignore文件，把不需要打包进运行环境的文件全部排除，进一步压缩体积：

.git
__pycache__
*.pyc
tests/
examples/
docs/
nltk_data/
.cache/
venv/
.env
*.md
*.ipynb

3. 调整Heroku构建配置 #

• 在Heroku应用的环境变量配置里新增PIP_NO_CACHE_DIR = 1，禁止pip把安装缓存打进slug，能省出50-100M空间
• NLTK只下载你实际用到的语料包，不要执行全量nltk数据下载，比如只需要分词功能就只下载punkt语料，全量NLTK数据超过300M，很容易撑爆容量
• 本地提前验证体积：新建空虚拟环境安装所有依赖，查看site-packages总大小，控制在450M以内再部署，留足系统依赖和项目代码的空间

避坑提醒 #

不要用git+https://github.com/neuml/txtai#egg=txtai[xxx]这种格式声明依赖，Heroku的构建环境对git源带扩展标记的解析存在兼容问题，是你一开始遇到安装报错的直接原因，生产环境部署一律用PyPI发布的正式版本。

内容的提问来源于stack exchange，提问作者CsG.