Nanbeige4.1-3B入门指南：HuggingFace Model Hub上传全流程（含license与card规范）

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账户。有两种方式：

方式一：使用命令行令牌登录（推荐）

1. 访问 HuggingFace 网站，点击右上角头像 ->Settings->Access Tokens。
2. 点击New token，创建一个具有write权限的令牌。
3. 在终端执行以下命令，粘贴你的令牌：

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_code=True) model = AutoModelForCausalLM.from_pretrained( model_name, torch_dtype=torch.bfloat16, device_map="auto", trust_remote_code=True ) # 构建对话 messages = [{"role": "user", "content": "你好"}] input_ids = tokenizer.apply_chat_template(messages, return_tensors="pt").to(model.device) # 生成 outputs = model.generate(input_ids, max_new_tokens=100) print(tokenizer.decode(outputs[0], skip_special_tokens=True))

训练数据

模型基于约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密钥，也可以用：git@huggingface.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_TOKEN@huggingface.co/你的用户名/Nanbeige4.1-3B main

3.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_type="model", token=你的token )

3.4 上传后检查与优化

上传完成后，刷新你的模型仓库页面：

1. 检查文件：确保config.json,model.safetensors,README.md,LICENSE等核心文件都在。
2. 验证模型卡片：页面应该能正确渲染你的README.md，并且顶部的标签、许可证信息都显示正确。
3. 试用推理API：HuggingFace会自动尝试加载你的模型。稍等几分钟，页面上的 “Hosted inference API” 部分应该会出现一个文本框，你可以直接输入文字测试模型是否加载成功。
4. 补充信息：你可以在仓库页面的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星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。