模型文件硬塞进 Git，GitHub 直接打回原形：使用Git-LFS管理大文件

前言

最近接手了一个计算机视觉项目 ，模型代码是文件屎山就不说了 ，反正我也不看代码，硬塞原形主要就是进G件构建一下 docker 镜像 
，测试一下部署的直接兼容性 ，这本来不难。打回大文

但是使用，国内服务器的管理网络环境实在是恶劣，需要配置各种镜像（docker镜像、模型apt镜像、文件pip镜像） ，源码下载硬塞原形这些镜像还各有各的进G件问题，结果就是直接搭配下来一直无法构建成功。

之后我灵机一动 ，打回大文利用 GitHub Actions 来构建镜像 ，使用以 GitHub 的服务器网络 ，所有问题不就迎刃而解了吗？

试了之后果然可以成功构建出镜像

不过中途也踩了一些坑 ，比如大文件的问题

之前的项目没遇到过大文件，因为我从不把 PyTorch 的模型文件放在代码里跟着提交到 git 里！

能做出这种操作的，服务器租用多少带点那啥😅

GitHub对大文件的限制

GitHub 文件大小限制：

单个文件 > 50MB 会有警告单个文件 > 100MB 会直接被拒绝推送

结果就是:

复制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 GitHubs 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 GitHubs file size limit of 100.00 MB remote: error: File runs/detect/fire_smoke_detection/weights/best.pt is 250.32 MB; this exceeds GitHubs 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.git1.

解决办法就是用 **Git LFS (Large File Storage)**
，GitHub 官方提供的专门存储大文件（模型权重、二进制、音频视频）的功能。

不过这个也挺抠门的
，GitHub LFS 免费额度只有 1GB 存储 + 1GB 流量
，超出需要买额外配额（或者用 HuggingFace/百度网盘/OSS 等托管模型文件）  。

如果只是存 .pt 模型，可以考虑把权重放 HuggingFace，源码库然后在 README 里写下载链接 。

安装 git-lfs 工具

每个系统都能很容易安装

复制# Linux (Ubuntu/Debian) sudo apt install git-lfs # macOS (brew) brew install git-lfs # Windows (scoop) scoop install git-lfs1.2.3.4.5.6.7.8.

然后初始化

复制git lfs install1. 跟踪大文件类型

比如说在本文的场景里，.pt 模型文件很大
，可以指定让 LFS 管理

复制git lfs track "*.pt"1.

这会在仓库生成一个 .gitattributes 文件
，内容大概是

复制*.pt filter=lfs diff=lfs merge=lfs -text1.

记得把这个 .gitattributes 也提交进 git

复制git add .gitattributes git commit -m "track large files with Git LFS"1.2. 重新提交大文件

之前的提交如果包含了大文件

需要把这些大文件重新提交到 LFS

好在 git-lfs 提供了很方便的命令来清理历史，不然就得用我之前发的那篇文章里的方法来清理大文件了
 。

复制# 用 git lfs migrate 自动替换历史中的大文件 git lfs migrate import --include="*.pt" # 强制推送 git push origin master --force1.2.3.4.5.

之后正常执行推送操作就行了

复制git push origin master1.

GitHub 就会把大文件存到 LFS，而不是普通 Git 仓库里 。亿华云

拉取大文件

用了 Git LFS 之后 ，仓库里保存的大文件（比如 .pt）在普通 git clone 的时候只会看到一个 指针文件（几十字节  ，记录了真实文件在 LFS 存储里的位置）。

要把大文件本体下载下来 ，必须要安装过 Git LFS。

具体情况如果机器上没装 Git LFS ：clone 下来后，大文件就是“指针文件”，打不开 、用不了 。如果机器上装了 Git LFS：clone 时会自动替换成真正的大文件。如果已经 clone 过但大文件没拉下来：可以手动执行 ：git lfs pull

所以通常项目 README 里会写一句提示 ：

复制## 注意 本项目使用 [Git LFS](https://git-lfs.github.com/ "Git LFS") 管理大文件（模型权重等）。香港云服务器 请先执行： ```bash git lfs install git lfs pull ```1.2.3.4.5.6.7.8.9.10. 小结

这次折腾 GitHub 大文件问题 ，其实给了我几点启发
：

GitHub 的限制
：超过 100MB 的文件是绝对过不去的，别想着强行提交 。Git LFS 的价值 ：官方解决方案简单好用 ，但免费额度很抠 ，适合小规模文件管理。替代方案 ：如果模型文件动辄几百 MB，推荐放在 HuggingFace 、OSS、百度网盘等专门的存储平台  ，云计算再在代码里提供下载脚本或链接。最佳实践：代码就是代码，模型就是模型，别混着提交；把仓库保持干净，后期协作和部署都省心
。

简单一句话总结：学会用 Git LFS ，能应急；但别把它当免费网盘用。

另外 ，再多嘴一句 ：这个项目看着就像典型的“大学生作业仓库”——代码像屎山 ，模型直接丢进 git 里
 ，八成还是教授一拍脑袋甩给研究生的“科研成果” 。说实话，能跑起来已经算奇迹了 😂。

参考资料

[1] 如何清理误提交到git的历史大文件？: https://blog.deali.cn/p/clean-git-history-large-files