很多朋友训练完一个模型以后第一反应就是怎么把它分享出去让别人也能用我之前在一个技术群里看到有人问“我把自己训练的模型传到HF上接入文档该怎么写”当时群里给了不少零散答案但真自己动手的时候还是有一堆细节坑。这篇就把我自己上传模型到 Hugging Face简称 HF并整理接入文档的完整流程写出来从文件整理、上传 SDK、模型卡到 HTTP 接口对接全都是在实际操作中验证过的路子。写这篇的初衷也很简单你训练模型这件事本身已经很难了别让“分享/接入”这一步拖后腿。无论你手头是照片修复模型、图像分类模型还是一个基于 LSTM 的时间序列预测模型上传到 HF 的方法都是相近的。这篇文章适合两类人看一是准备把自己训练的模型开源出去的个人开发者二是需要在团队内部用 HF 管理模型、对接项目的工程师。1. 先把模型整理成能“见人”的样子1.1 为什么优先选 HF 而不是自建服务器你可能也纠结过我自己有服务器直接把模型文件扔上去不行吗行但只适合自用。一旦涉及分享、协作、版本回滚、在线演示HF 的优势就很明显了。HF 提供了模型仓库、Git 版本管理、大文件 LFS、模型卡片、讨论区甚至一键部署 Inference API。这就好比你自己搭了个网站放简历和把简历放到一个招聘平台的差别平台自带曝光、协作机制和调用方式。另外HF 生态里的 transformers、diffusers 库已经和平台深度集成。用户拿到你的 model id一行from_pretrained就能加载不需要关心文件具体存在哪。接入文档也就不用写“下载地址 手动解压”而是直接告诉对方“你用这个 id 就能调”体验完全不同。这里有一个很容易忽略的点如果你只是把模型文件塞到百度网盘或自己的服务器别人拿到手还需要匹配权重文件和代码结构稍有不慎就加载不对。而 HF 仓库可以按标准结构组织config.json、model.safetensors、README.md都放在固定位置后续就算你更新了权重别人重新拉取也会自动同步。1.2 上传前检查清单一份文件列表值回票价我在踩了无数次坑之后总结出上传前先照下面这份清单理一遍文件能省掉后面大部分“别人加载不了”的问题权重文件优先导出为.safetensors格式而不是.bin或.ckpt。配置文件config.json或者模型代码里需要的配置项。分词器/特征提取器如果你的模型是文本类tokenizer.json、vocab.txt这些一定带上。模型代码如果你用了自定义网络结构最好在仓库里放模型定义代码并在 README 里说明依赖。License明确许可证类型没有许可证的模型别人是不太敢拿去商用的。README/Model Card写清楚模型能干什么、怎么用这就是接入文档的雏形。测试输入输出至少给一个 demo 输入和对应输出方便使用者验证。以 PyTorch 为例很多人直接上传pytorch_model.bin文件能用但不是最优解。.safetensors格式不仅加载更快还避免了 pickle 反序列化带来的安全风险。HF 现在也支持直接上传safetensors加载时优先读它。至于文件结构常见有两种一种是 transformers 原生结构包含config.json和权重另一种是自定义结构带有inference.py或自定义代码。无论哪种我建议在仓库里保留一个requirements.txt把transformers、torch、diffusers这些依赖版本锁定。很多人模型上传后别人加载不了八成是少装了依赖或者版本不一致。2. 上传模型的完整流程2.1 创建 HF 账号和访问令牌上传的第一步不是点“New Model”而是先去注册账号并拿到访问令牌Access Token。注册环节没什么好说的重点说令牌进入 Settings → Access Tokens → New token权限至少要勾选Write因为上传模型、创建仓库都需要建仓和写入权限。如果你还想顺带创建自动训练任务或者修改数据集就选Fine-grained自定义权限。令牌生成后马上复制保存它只显示一次丢了就只能重新建。需要注意令牌别提交到公开仓库里。把它写到环境变量或者保存在本地的.env文件并在.gitignore里把它忽略掉。我之前见过有人把 token 硬编码在训练脚本里结果上传模型时把整个仓库一起传到 GitHub等于把写权限暴露给所有人这是很低级的失误。2.2 用网页端上传小模型如果说模型文件总量小于 2GB用网页端是最快的。在 HF 首页点击 New Model填好 owner个人或组织、模型名称、license、tags就能得到一个空仓库。网页端上传支持拖拽文件也支持直接创建 README。我实际操作中感觉网页端适合传一两个文件和写文档因为它的上传没有断点续传文件一多网络稍有波动就可能失败又得重新拖。所以我的建议是小文件、文档、配图用网页端大权重文件用命令行或 Python SDK。另外网页端创建模型仓库时可以同时把它设为 public 或 private。个人实验、团队内部用的模型在没想清楚开源协议之前先设 private 更安全。等你把文档补齐、许可证选好再切换为 public 也不迟。2.3 用 huggingface_hub 上传大模型和整个目录大文件的推荐姿势是 Python SDK比较简单粗暴而且支持断点续传。先安装库pip install huggingface_hub然后把整个模型目录传上去from huggingface_hub import HfApi api HfApi() # 先创建仓库如果已经建过可以跳过这一步 api.create_repo( repo_idyour_username/awesome-model, repo_typemodel, privateFalse, ) # 上传整个目录断点续传默认开启 api.upload_folder( repo_idyour_username/awesome-model, folder_path./my_model_output, ignore_patterns[*.cache, *.tmp], )第一次上传后如果后面只更新了部分文件可以继续用upload_fileapi.upload_file( path_or_fileobj./my_model_output/model.safetensors, path_in_repomodel.safetensors, repo_idyour_username/awesome-model, )如果你更习惯 Git 的工作流也可以本地git clone https://huggingface.co/your_username/awesome-model把文件复制进去后用 Git 提交推送。HF 自动处理 LFS超过一定大小的文件会走 Git LFS不用手动标记。上传过程中有几个细节我要特别提醒仓库里的 weight 文件如果更新尽量不要用“model_1.safetensors”“model_final_v2.safetensors”这种命名叠加。直接覆盖model.safetensors别人加载时不需要改代码。上传之前先删除模型输出目录里的日志、checkpoint 中间状态这些杂项别人拉取的是整个仓库东西太杂会让人一头雾水。用upload_folder时ignore_patterns能帮你过滤掉不需要的文件比如.cache、__pycache__、临时文件。2.4 补写模型卡和标签提升可发现性HF 仓库的 README 上有 YAML 头信息别小看它它决定了你的模型在 HF 搜索里能不能被路人发现。一个基本的头信息长这样--- license: apache-2.0 language: zh tags: - image-restoration - pytorch pipeline_tag: image-to-image model-index: - name: photo-restore results: [] ---license 一定要如实填写常见的有apache-2.0、mit、cc-by-nc-4.0。如果不想让别人商用就选cc-by-nc-4.0。没有许可证的风险相当于“保留所有权利”别人反而不知道怎么合法使用。tags 和pipeline_tag会影响模型是否被自动识别。比如一个照片修复模型pipeline_tag可以填image-to-image如果是文本生成可以填text-generation。这样对方在 HF 页面点“Use in transformers”时生成的代码会更准确。3. 接入文档到底怎么写才不挨骂3.1 一张能直接用的 Model Card 模板接入文档的本质是让只见过你模型名字的人也能迅速跑通。我常用的模型卡结构是固定的你可以直接照着填# 模型名称 ## 简介 一句话说清这个模型解决什么问题基于什么数据训练。 ## 模型效果 在标准验证集上的指标比如 PSNR、Accuracy、Loss。有对比图更好。 ## 输入输出说明 - 输入图片尺寸 512x512RGB - 输出修复后的图片尺寸 512x512PNG ## 依赖环境 - Python 3.10 - torch 2.0 - transformers 4.30 - diffusers 0.20 ## 快速开始 给出一段可以直接跑的代码包含加载模型和推理的最小示例。 ## API 接入 如果提供了 HTTP 接口贴出请求地址、参数、返回 JSON 格式。 ## 版本记录 V1.0初始版本 V1.1修复了低光场景下色彩偏移问题 ## License apache-2.0这里最核心的部分是“快速开始”。很多模型的 README 只写了一句“安装依赖后运行 inference.py”没有任何输入输出说明使用者还得自己翻代码猜输入格式很劝退。所以哪怕你只给一个十行的示例价值都很大。3.2 从 Python 示例代码到 HTTP 接口文档如果你的模型打算给后端服务调用光在 HF 上有一个from_pretrained的用法还不够。因为大多数用户并不打算装你的训练环境他们希望你提供一个 HTTP 服务数据丢进去结果出来。我在接入文档里通常会把接口文档也一起写清楚。假设我用 FastAPI 包了一个照片修复服务from fastapi import FastAPI, UploadFile, File from io import BytesIO from PIL import Image import torch app FastAPI() model None app.post(/restore) async def restore_image(file: UploadFile File(...)): image Image.open(BytesIO(await file.read())).convert(RGB) # 这里调用你的模型推理 # result model_inference(image) result image # 占位替换成真实推理结果 buf BytesIO() result.save(buf, formatPNG) return { success: True, output: data:image/png;base64, base64.b64encode(buf.getvalue()).decode() }对应的接入文档可以这么写### 请求方式 POST /restore ### 请求参数 | 参数 | 类型 | 必填 | 说明 | | --- | --- | --- | --- | | file | multipart/form-data | 是 | 待修复的图片文件 | ### 返回示例 { success: true, output: data:image/png;base64,... }返回图片我习惯用 base64 字符串避免对方二次调用下载接口。如果你返回的是 JSON就明确列出每个字段的含义。接口文档最忌讳“只写路径不写返回结构”对方联调时只能靠猜。如果你不想自己维护 HTTP 服务HF 也有 Inference API付费或按量使用。但你要先确认自己的模型属于 HF 支持的 pipeline 类型比如text-generation、image-classification这类比较稳一些很偏门自定义任务不一定支持。所以我的建议是接入文档里至少写两套方案——本地 Python 调用和 HTTP 接口调用。3.3 在 ComfyUI 里接入自定义模型结合创作链路来看很多人上传模型到 HF最终是为了在 ComfyUI 里使用比如照片修复模型、超分模型、Diffusion 模型。ComfyUI 接入自定义模型大致分三步第一步把模型权重放到 ComfyUI 的模型目录比如models/checkpoints、models/loras具体位置取决于模型类型。第二步在 ComfyUI 里选择对应节点填模型文件名。第三步如果模型结构是自训练的ComfyUI 里没有现成节点就需要写一个自定义节点把推理部分包装成 Python 节点。这里有一个和 HF 强相关的操作很多人在 ComfyUI 里会去直接下载 HF 上的基础模型比如 Flux 系列。如果下载速度很慢可以给 ComfyUI 设置 HF 镜像源在不影响原仓库稳定性的前提下加速拉取文件。一般做法是设置环境变量export HF_ENDPOINThttps://hf-mirror.com设置后ComfyUI 中依赖huggingface_hub的下载请求会自动走镜像站。注意这只影响下载类操作不影响上传。你要是想把自己训练的模型传到 HF还是用官方端点不要用镜像端点。ComfyUI 的接入文档我建议写清楚节点名称、输入输出类型、模型目录位置以及一个手工 ComfyUI 工作流截图。因为 ComfyUI 用户习惯于可视化连线你只给代码他们还要猜怎么在画布里拼节点。4. 上传和接入的常见坑4.1 文件传了一半失败或者上传后仓库是空的这个问题在我早期上传大模型时出现过很多次。页面拖拽上传几十 GB 的权重文件传着传着就停住网页刷新后仓库里只有部分文件。后来我还是老老实实用upload_folder因为它的断点续传体验好得多。如果你用 Git 方式上传注意 LFS 文件被误判为普通文本的情况。一个常见症状是仓库里有model.safetensors但别人下载回来后却发现它是一个只有几百字节的文本指针文件。这通常是因为没有装 Git LFS 插件导致大文件没有正确跟踪。解决方式很简单先git lfs install再对特定文件后缀设置跟踪。4.2 网络下载慢或者连不上 HF国内网络访问 HF 官方域名速度和稳定性经常是一言难尽。解决方案是设置镜像端点也就是前面提到的HF_ENDPOINT。下载模型时可以用export HF_ENDPOINThttps://hf-mirror.com但要注意这个变量只对下载工具生效对浏览器网页访问不一定有效。另外如果你是在团队内网上传模型通常走官方端点更稳上传和下载对镜像站的支持是不对等的。还有一个容易被忽视的问题如果你的项目代码里设置了HF_ENDPOINThttps://hf-mirror.com然后你用它去加载一个很大的模型会出现版本过旧加载失败吗一般不会但镜像站同步有时差刚上传的私有模型镜像站未必能立刻拉到。所以我的习惯是上传用官方端点下载慢时再切镜像代码里不写死环境变量而是用独立.env文件管理。4.3 别人加载模型时报错或者推理结果不对劲用户拿到你的模型后最常见的加载报错是KeyError或UnrecognizedConfigException。前者多半是你更新了权重但没有同步更新 config后者多半是模型结构需要trust_remote_codeTrue但用户代码里没打开。我建议在你自己的接入文档里写清楚加载条件from transformers import AutoModel model AutoModel.from_pretrained( your_username/awesome-model, trust_remote_codeTrue )如果你的模型不是基于 transformers 的架构那就在 README 里直接给纯 PyTorch 加载方式import torch from my_model import MyModel model MyModel() state_dict torch.load(model.safetensors, map_locationcpu) model.load_state_dict(state_dict)另外图片类模型经常出现推理结果全黑、全白的问题。这通常是输入尺寸和模型训练时不一致或者像素归一化方式不一样。接入文档里要把预处理写清楚比如 resize、normalize 的具体公式而不是简单写一句“把图片缩放到 512x512”。我在文档中会直接贴一小段预处理代码因为输入处理真的很重要。4.4 许可证和版权不明确这个坑不是技术上的但危害比技术问题更大。有些训练数据来自网络爬取许可证不干净模型上传后一旦公开原作者可以主张你侵权。HF 官方也会定期检查非法内容。所以上传前最好确认三件事训练数据的来源是否合法、权重文件是否由你独立训练、模型里是否包含第三方代码库的源码。如果你只是微调了别人的开源模型比如基于某个开源 base model 微调那么在模型卡里必须注明 base model 的出处并遵守原模型的许可证。很多人忽略这一点最后被要求下架模型非常被动。5. 一些建议与心得5.1 低显存用户怎么使用你的模型一个模型上传到 HF不代表所有人都能跑起来尤其是显存只有 6GB 或 8GB 的用户。我在写接入文档时会单独写一个“低显存配置”小节典型做法是用device_map和load_in_8bitfrom transformers import AutoModelForImageClassification model AutoModelForImageClassification.from_pretrained( your_username/awesome-model, device_mapauto, load_in_8bitTrue, )对大模型来说这能显著降低显存占用代价是推理速度稍慢。如果模型支持 ONNX 导出我建议在仓库里附一个 ONNX 版本的模型文件这样用户可以使用更轻量的推理后端也能在 CPU 上跑。HF 仓库同时放多个格式没有关系写清楚不同文件的适用场景就行。5.2 把模型仓库当作一个完整交付物来维护上传模型和写博客很像第一次上传只是开始后面每次迭代训练、修 bug都应该同步更新模型卡和版本记录。我现在的个人习惯是每训练一个新版本都会把模型的指标变化、训练数据规模、限制场景写进 README 的版本记录里然后覆盖上传权重文件。这样用户在任何时间点看到你的模型页面都能知道这个模型的边界在哪里。有时候我甚至会把“训练数据的样本数量”写进去。别小看这一行字它能让使用者判断你的模型是否适合自己的场景。比如一个照片修复模型只用了人脸数据训练你在文档里明确写“对人像效果好对复杂风景不稳定”用户就不会拿它去修风景然后给你差评。最后再分享一个小技巧上传到 HF 之前先在本地用一条全新路径加载一次你的仓库。也就是 clone 下来装好 requirements跑通 README 里的示例代码。这一步能拦住几乎所有“以为自己传好了实际没法用”的尴尬。我自己经历过太多次“本地能跑克隆下来就跑不了”的情况多数都是依赖版本或相对路径问题。把这句话当作验收标准如果连一个完全没看过你训练代码的人都能照 README 跑通那你这篇接入文档才算及格。