模型文件硬塞进 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