Nanbeige4.1-3B入门指南HuggingFace Model Hub上传全流程含license与card规范你是不是刚训练好一个模型想把它分享给全世界却卡在了上传这一步特别是面对HuggingFace Model Hub模型中心那一堆文件要求和格式规范感觉头都大了。别担心这篇文章就是为你准备的。我们将以最近备受关注的Nanbeige4.1-3B模型为例手把手带你走一遍从本地模型到成功发布在HuggingFace上的完整流程。我会把每一步都掰开揉碎了讲特别是最容易出错的许可证License和模型卡片Model Card规范保证你看完就能自己操作。1. 上传前准备认识你的模型与HuggingFace在开始上传之前我们先花几分钟搞清楚两件事你要上传的模型是什么以及HuggingFace Model Hub是什么。1.1 Nanbeige4.1-3B一个值得分享的“小钢炮”根据你提供的资料Nanbeige4.1-3B是一个相当有竞争力的开源小模型。我们快速回顾一下它的亮点参数小能力不弱只有30亿参数但对标的是更大模型的能力特别是在逻辑推理和遵循指令方面。上下文长支持长达262K tokens的上下文处理长文档、长对话很拿手。工具调用强支持600步长的工具调用这在构建智能体Agent时非常有用。完全开源权重、技术报告、合成数据全部开放这符合HuggingFace社区推崇的开源精神。正因为这些特性把它分享到HuggingFace上能让更多开发者、研究者发现并使用它非常有价值。1.2 HuggingFace Model Hub不只是个网盘你可以把HuggingFace Model Hub理解为一个“GitHub for Models”。它不仅仅提供模型文件的存储和下载更是一个完整的模型开发生态版本控制像Git一样可以管理模型的不同版本。在线推理API用户可以直接在网页上试用你的模型无需下载。社区互动其他人可以点赞、收藏、评论甚至创建模型变体。发现平台你的模型会被纳入HuggingFace的搜索和推荐系统。要成功上传你的模型仓库需要包含一些必需的文件并遵循一定的结构规范。接下来我们就进入实战环节。2. 核心实战一步步上传模型到HuggingFace这个过程就像打包一个快递整理物品模型文件、填写运单模型信息、选择服务许可证最后寄出上传。我们一步一步来。2.1 第一步安装工具与登录工欲善其事必先利其器。首先我们需要安装HuggingFace官方命令行工具huggingface_hub。# 在终端中执行以下命令安装 pip install huggingface-hub安装完成后我们需要登录到你的HuggingFace账户。有两种方式方式一使用命令行令牌登录推荐访问 HuggingFace 网站点击右上角头像 -Settings-Access Tokens。点击New token创建一个具有write权限的令牌。在终端执行以下命令粘贴你的令牌huggingface-cli login然后按照提示操作即可。方式二使用环境变量适合脚本自动化# 在终端中设置环境变量 export HF_TOKEN你的令牌2.2 第二步整理你的模型文件这是最关键的一步。你需要把本地的模型文件整理成HuggingFace Transformers库能直接识别的格式。通常一个完整的模型仓库包含以下文件Nanbeige4.1-3B/ # 你的本地模型文件夹 ├── config.json # 模型配置文件必须 ├── model.safetensors # 模型权重文件或pytorch_model.bin ├── tokenizer.json # 分词器文件必须 ├── tokenizer_config.json # 分词器配置文件 ├── special_tokens_map.json # 特殊token映射文件 ├── generation_config.json # 生成参数配置文件可选但推荐 ├── README.md # 模型卡片必须后面详讲 └── LICENSE # 许可证文件必须后面详讲如何生成这些文件如果你的模型是用transformers库训练或转换的通常保存时就会自动生成大部分文件from transformers import AutoModelForCausalLM, AutoTokenizer # 假设你的模型和分词器已经加载 model AutoModelForCausalLM.from_pretrained(./my_local_nanbeige) tokenizer AutoTokenizer.from_pretrained(./my_local_nanbeige) # 保存到指定目录HuggingFace格式 save_directory ./Nanbeige4.1-3B-hf-format model.save_pretrained(save_directory) tokenizer.save_pretrained(save_directory) print(f模型已保存至: {save_directory})检查一下save_directory文件夹应该已经有了config.json,pytorch_model.bin等核心文件。权重格式小贴士pytorch_model.bin传统的PyTorch权重格式。.safetensors推荐使用。这是HuggingFace推广的一种更安全、加载更快的格式。你可以使用safetensors库进行转换。2.3 第三步创建模型卡片README.md模型卡片是你的模型的“简历”和“使用说明书”。一个优秀的模型卡片能极大提升模型的可用性和受欢迎程度。它必须是一个名为README.md的Markdown文件。你可以直接在你整理好的模型文件夹例如./Nanbeige4.1-3B-hf-format里创建这个文件。下面是一个为Nanbeige4.1-3B量身定制的模板--- language: - zh - en license: apache-2.0 # 这里填写许可证标识后面会讲 tags: - nanbeige - 3B - causal-lm - reasoning - agent - long-context widget: - text: 请用Python写一个快速排序函数。 example_title: 代码生成 - text: 假设有一个房间里有三个开关对应隔壁房间的三盏灯。你只能进一次有灯的房间如何确定哪个开关控制哪盏灯 example_title: 逻辑推理 - text: 翻译以下英文The rapid advancement of artificial intelligence is reshaping various industries. example_title: 中英翻译 --- # Nanbeige4.1-3B ## 模型简介 Nanbeige4.1-3B 是一个拥有30亿参数的开源通用语言模型。它在保持较小参数规模的同时在**逻辑推理**、**指令遵循**和**智能体Agent工具调用**方面表现出色尤其擅长处理长上下文任务。 ## 模型详情 - **开发者:** [你的名字或团队名] - **模型类型:** 因果语言模型 (Causal LM) - **语言:** 中文、英文 - **许可证:** Apache License 2.0 - **参数量:** 3B (30亿) - **上下文长度:** 262,144 tokens - **输入格式:** ChatML 格式 ## 如何使用 可以直接使用 transformers 库加载 python from transformers import AutoModelForCausalLM, AutoTokenizer model_name 你的用户名/Nanbeige4.1-3B # 上传后的路径 tokenizer AutoTokenizer.from_pretrained(model_name, trust_remote_codeTrue) model AutoModelForCausalLM.from_pretrained( model_name, torch_dtypetorch.bfloat16, device_mapauto, trust_remote_codeTrue ) # 构建对话 messages [{role: user, content: 你好}] input_ids tokenizer.apply_chat_template(messages, return_tensorspt).to(model.device) # 生成 outputs model.generate(input_ids, max_new_tokens100) print(tokenizer.decode(outputs[0], skip_special_tokensTrue))训练数据模型基于约23T高质量、多语言文本数据进行训练并经过严格的筛选和清洗。评估结果此处可以粘贴或链接到你的模型在常见基准测试上的表现如C-Eval, MMLU等。如果还没有可以写“评估进行中”或暂时省略。局限性与使用须知模型可能会生成不准确、有偏见或有害的内容。对于关键性任务如医疗、法律、金融建议请务必进行人工核查。推荐在对话、创意生成、代码辅助等场景使用。引用如果你使用了本模型请引用相关的技术报告如果存在misc{nanbeige2025, title{Nanbeige4.1-3B: A Compact and Capable Language Model}, author{Your Name or Team}, year{2025}, howpublished{\url{https://huggingface.co/你的用户名/Nanbeige4.1-3B}}, }模型卡片内容可以更长包括更详细的使用示例、硬件需求、微调指南等。**重点**文件顶部的 YAML 元数据块被 --- 包裹的部分对于HuggingFace网站正确分类和展示你的模型至关重要不要遗漏。 ### 2.4 第四步选择并添加许可证LICENSE **这是法律步骤不能跳过** 没有明确的许可证其他人无法合法使用你的模型。 1. **选择许可证**对于开源模型常见的选择有 - **Apache 2.0**非常宽松允许商用、修改、分发只需保留版权声明。**对于希望被广泛使用的模型这是最推荐的选择**。 - **MIT**和Apache 2.0类似非常宽松。 - **CC-BY-SA-4.0**允许商用和修改但基于此模型的衍生作品也必须使用相同许可证分享。 - **GPL**具有“传染性”基于此模型的衍生作品也必须开源。 根据你提供的资料Nanbeige4.1-3B是“完全开源”的选择 **Apache License 2.0** 非常合适。 2. **添加LICENSE文件** - 在你本地的模型文件夹根目录下创建一个名为 LICENSE 的纯文本文件。 - 前往 [Apache 2.0许可证全文页面](https://www.apache.org/licenses/LICENSE-2.0.txt)复制全部内容到你的 LICENSE 文件中。 - **重要**记得将许可证中的 [yyyy] [name of copyright owner] 替换成实际的年份和你的名字/团队名。例如 Copyright 2025 Your Name 3. **在模型卡片中声明**确保你的 README.md 文件顶部的YAML块里 license: 字段和文件内容一致比如 license: apache-2.0。 ## 3. 上传与发布最后的临门一脚 所有文件准备就绪后就可以上传了。 ### 3.1 在HuggingFace上创建模型仓库 1. 登录HuggingFace网站。 2. 点击右上角头像旁边的 New - Model。 3. 填写仓库信息 - **Owner**: 选择你的个人账户或组织。 - **Model name**: 例如 Nanbeige4.1-3B。 - **Visibility**: 选择 Public公开或 Private私有。 - **License**: 选择 Apache 2.0与你LICENSE文件一致。 4. 点击 Create Model。你会得到一个空的模型仓库地址类似 https://huggingface.co/你的用户名/Nanbeige4.1-3B。 ### 3.2 使用Git上传文件推荐方式 这是最标准、支持版本管理的方式。你需要一点基础的Git知识。 bash # 1. 将你的本地模型文件夹初始化为Git仓库 cd /path/to/your/Nanbeige4.1-3B-hf-format git init git lfs install # 安装Git LFS来管理大文件模型权重 # 2. 告诉Git LFS跟踪大文件.safetensors或.bin文件 git lfs track *.safetensors git lfs track *.bin # 如果有其他大文件也一并跟踪 # git lfs track *.pth # git lfs track *.h5 # 3. 添加HuggingFace仓库为远程地址 git remote add origin https://huggingface.co/你的用户名/Nanbeige4.1-3B # 如果你使用SSH密钥也可以用githuggingface.co:你的用户名/Nanbeige4.1-3B.git # 4. 添加所有文件并提交 git add . git commit -m Initial upload of Nanbeige4.1-3B model # 5. 推送文件到HuggingFace git push origin main如果提示认证失败可能需要配置Git凭证或者使用Access Token作为密码git push https://你的用户名:你的HF_TOKENhuggingface.co/你的用户名/Nanbeige4.1-3B main3.3 使用huggingface_hub库上传编程方式如果你更喜欢用Python脚本也可以from huggingface_hub import HfApi, create_repo api HfApi() # 如果仓库还没创建可以创建需要token # create_repo(repo_id你的用户名/Nanbeige4.1-3B, token你的token) # 上传整个文件夹 api.upload_folder( folder_path/path/to/your/Nanbeige4.1-3B-hf-format, repo_id你的用户名/Nanbeige4.1-3B, repo_typemodel, token你的token )3.4 上传后检查与优化上传完成后刷新你的模型仓库页面检查文件确保config.json,model.safetensors,README.md,LICENSE等核心文件都在。验证模型卡片页面应该能正确渲染你的README.md并且顶部的标签、许可证信息都显示正确。试用推理APIHuggingFace会自动尝试加载你的模型。稍等几分钟页面上的 “Hosted inference API” 部分应该会出现一个文本框你可以直接输入文字测试模型是否加载成功。补充信息你可以在仓库页面的Settings里添加更详细的标签、库类型如transformers让模型更容易被搜索到。4. 总结与后续步骤恭喜你走到这一步你的Nanbeige4.1-3B模型已经成功在HuggingFace Model Hub安家了。我们来快速回顾一下核心要点准备是关键确保模型文件是标准的Transformers格式config.json, 权重文件分词器文件。法律意识不能少务必添加一个合适的开源许可证文件如LICENSE并在模型卡片中声明。文档就是门面花时间写一个清晰的README.md模型卡片详细介绍模型特点、用法、限制这是吸引用户的第一步。上传二选一使用git推荐支持版本管理或huggingface_hub库上传。模型上传只是开始。为了让你的模型获得更多关注分享链接在相关社区、论坛、社交媒体分享你的模型主页。收集反馈关注仓库的“讨论Discussion”区积极回复用户的问题。持续迭代如果发布了改进版本可以通过创建新的Git tag如v2.0来管理版本让用户能选择使用稳定版本。现在全世界的研究者和开发者都可以通过一行简单的from_pretrained(“你的用户名/Nanbeige4.1-3B”)来使用你的成果了。享受开源带来的成就感和社区互动吧获取更多AI镜像想探索更多AI镜像和应用场景访问 CSDN星图镜像广场提供丰富的预置镜像覆盖大模型推理、图像生成、视频生成、模型微调等多个领域支持一键部署。