模型文件硬塞進 Git，GitHub 直接打回原形：使用Git-LFS管理大文件
前言
最近接手了一個計算機視覺項目
代碼是屎山就不說了，反正我也不看代碼
主要就是構(gòu)建一下 docker 鏡像，測試一下部署的兼容性
這本來不難
但是，國內(nèi)服務(wù)器的網(wǎng)絡(luò)環(huán)境實在是惡劣，需要配置各種鏡像（docker鏡像、apt鏡像、pip鏡像），這些鏡像還各有各的問題，結(jié)果就是搭配下來一直無法構(gòu)建成功。
之后我靈機一動，利用 GitHub Actions 來構(gòu)建鏡像，以 GitHub 的服務(wù)器網(wǎng)絡(luò)，所有問題不就迎刃而解了嗎？
試了之后果然可以成功構(gòu)建出鏡像
不過中途也踩了一些坑，比如大文件的問題
之前的項目沒遇到過大文件，因為我從不把 PyTorch 的模型文件放在代碼里跟著提交到 git 里！
能做出這種操作的，多少帶點那啥??
GitHub對大文件的限制
GitHub 文件大小限制：
- 單個文件 > 50MB 會有警告
- 單個文件 > 100MB 會直接被拒絕推送
結(jié)果就是:
Writing objects: 100% (304/304), 463.41 MiB | 3.23 MiB/s, done. Total 304 (delta 32), reused 0 (delta 0), pack-reused 0 (from 0) remote: Resolving deltas: 100% (32/32), done. remote: warning: File fire_detection/yolov5l.pt is 88.50 MB; this is larger than GitHub's recommended maximum file size of 50.00 MB remote: error: Trace: 52267c96d371181694b02dad5eebead817ce6d985e2f8d356c2b458adfbb2a09 remote: error: See https://gh.io/lfs for more information. remote: error: File runs/detect/fire_smoke_detection/weights/best.pt is 166.91 MB; this exceeds GitHub's file size limit of 100.00 MB remote: error: File runs/detect/fire_smoke_detection/weights/best.pt is 250.32 MB; this exceeds GitHub's file size limit of 100.00 MB remote: error: GH001: Large files detected. You may want to try Git Large File Storage - https://git-lfs.github.com. To github.com:cppstudio/fire-detection.git ! [remote rejected] master -> master (pre-receive hook declined) error: failed to push some refs to 'github.com:studio/fire-detection.git'
解決辦法就是用 Git LFS (Large File Storage)，GitHub 官方提供的專門存儲大文件（模型權(quán)重、二進制、音頻視頻）的功能。
不過這個也挺摳門的，GitHub LFS 免費額度只有 1GB 存儲 + 1GB 流量，超出需要買額外配額（或者用 HuggingFace/百度網(wǎng)盤/OSS 等托管模型文件）。
如果只是存 .pt 模型，可以考慮把權(quán)重放 HuggingFace，然后在 README 里寫下載鏈接。
安裝 git-lfs 工具
每個系統(tǒng)都能很容易安裝
# Linux (Ubuntu/Debian)
sudo apt install git-lfs
# macOS (brew)
brew install git-lfs
# Windows (scoop)
scoop install git-lfs
然后初始化
git lfs install
跟蹤大文件類型
比如說在本文的場景里，.pt 模型文件很大，可以指定讓 LFS 管理
git lfs track "*.pt"
這會在倉庫生成一個 .gitattributes 文件，內(nèi)容大概是
*.pt filter=lfs diff=lfs merge=lfs -text
記得把這個 .gitattributes 也提交進 git
git add .gitattributes
git commit -m "track large files with Git LFS"
重新提交大文件
之前的提交如果包含了大文件
需要把這些大文件重新提交到 LFS
好在 git-lfs 提供了很方便的命令來清理歷史，不然就得用我之前發(fā)的那篇文章里的方法來清理大文件了。詳見: 如何清理誤提交到git的歷史大文件？
# 用 git lfs migrate 自動替換歷史中的大文件
git lfs migrate import --include="*.pt"
# 強制推送
git push origin master --force
之后正常執(zhí)行推送操作就行了
git push origin master
GitHub 就會把大文件存到 LFS，而不是普通 Git 倉庫里。
拉取大文件
用了 Git LFS 之后，倉庫里保存的大文件（比如 .pt）在普通 git clone 的時候只會看到一個 指針文件（幾十字節(jié)，記錄了真實文件在 LFS 存儲里的位置）。
要把大文件本體下載下來，必須要安裝過 Git LFS。
具體情況
- 如果機器上沒裝 Git LFS：clone 下來后，大文件就是“指針文件”，打不開、用不了。
- 如果機器上裝了 Git LFS：clone 時會自動替換成真正的大文件。
- 如果已經(jīng) clone 過但大文件沒拉下來：可以手動執(zhí)行：
git lfs pull
所以通常項目 README 里會寫一句提示：
## 注意
本項目使用 [Git LFS](https://git-lfs.github.com/) 管理大文件（模型權(quán)重等）。
請先執(zhí)行：
```bash
git lfs install
git lfs pull
```
小結(jié)
這次折騰 GitHub 大文件問題，其實給了我?guī)c啟發(fā)：
- GitHub 的限制：超過 100MB 的文件是絕對過不去的，別想著強行提交。
- Git LFS 的價值：官方解決方案簡單好用，但免費額度很摳，適合小規(guī)模文件管理。
- 替代方案：如果模型文件動輒幾百 MB，推薦放在 HuggingFace、OSS、百度網(wǎng)盤等專門的存儲平臺，再在代碼里提供下載腳本或鏈接。
- 最佳實踐：代碼就是代碼，模型就是模型，別混著提交；把倉庫保持干凈，后期協(xié)作和部署都省心。
簡單一句話總結(jié)：學會用 Git LFS，能應(yīng)急；但別把它當免費網(wǎng)盤用。
另外，再多嘴一句：這個項目看著就像典型的“大學生作業(yè)倉庫”——代碼像屎山，模型直接丟進 git 里，八成還是教授一拍腦袋甩給研究生的“科研成果”。說實話，能跑起來已經(jīng)算奇跡了 ??。
浙公網(wǎng)安備 33010602011771號