从社区资源到个人模型：用CSGHub SDK完成一次文本分类微调

在模型社区里找到一个合适的基座模型并不难。真正需要花时间的，是怎样把社区里的模型和数据集下载到本地，完成一次针对具体任务的微调，再把训练结果保存下来，变成可以继续使用和管理的个人模型。

CSGHub提供了模型、数据集、代码和应用等AI资源的托管能力。社区用户可以在平台上创建自己的模型仓库和数据集仓库，也可以通过Git、命令行工具或者SDK管理这些资源。

csghub-sdk则是连接CSGHub与本地开发环境的Python客户端。通过它，可以把社区中的模型和数据集下载到本地；训练完成后，再配合命令行工具将模型结果上传回社区。

这次实践将走通一条完整的模型微调链路。

01 使用csghub-sdk微调分类模型：先看完整链路

这次要完成的是一个中文文本二分类模型。模型接收一段中文评论后，判断文本表达的是正面倾向还是负面倾向。

实际操作中，CSGHub和本地训练环境承担的工作并不相同。

CSGHub用于保存和管理基座模型、训练数据集以及最终得到的微调模型；csghub-sdk负责把这些社区资源下载到本地；模型的加载、训练和评估则由Transformers等训练工具完成。

整个过程可以分成六个阶段：

第一阶段：准备环境并下载资源

先在本地安装csghub-sdk和训练依赖，再从CSGHub下载已经准备好的中文基座模型和文本分类数据集。

第二阶段：加载和处理数据

读取JSONL格式的数据文件，将数据划分为训练集和测试集，然后使用与基座模型配套的分词器处理中文文本。

第三阶段：加载模型并配置训练参数

在中文基座模型上增加二分类输出层，同时设置训练轮数、批次大小、评估策略和模型保存策略。

第四阶段：执行训练和评估

使用训练集更新模型参数，并在每轮训练结束后通过测试集观察准确率，保留表现最好的模型版本。

第五阶段：保存模型并进行本地推理

训练完成后，将模型权重、配置文件和分词器保存到本地目录，再输入一条新的中文评论检查预测结果。

第六阶段：上传微调模型

确认模型可以正常加载和推理后，将整个模型目录上传到CSGHub，形成一个新的个人模型仓库。

“这六个阶段覆盖了从社资源到个人模型的完整过程。下面从账号和本地环境开始，逐步完成每一步操作。”

02 准备工作

注册OpenCSG账号并获取Access Token

https://opencsg.com

点击页面右上角的注册或登录入口，完成账号注册并登录。

登录后，点击个人头像进入账户设置，在“Access Token”页面创建一个新的Token。后续使用csghub-sdk或者csghub-cli访问个人仓库时，都需要通过这个Token完成身份认证。

Token创建完成后，先复制并妥善保存。出于安全考虑，Token不建议直接写进Python代码，也不要提交到公开的Git仓库。

在终端中设置环境变量：

exportCSGHUB_TOKEN=your_access_token

当前终端会话关闭后，临时设置的环境变量通常会失效。重新打开终端执行训练或上传操作时，需要再次设置。

创建Python虚拟环境

本次操作使用macOS环境进行演示，Python版本为3.12。其他操作系统的整体步骤基本一致，虚拟环境的激活命令可能有所不同。

先安装uv：

curl-LsSf https://astral.sh/uv/install.sh | sh

安装完成后，在准备运行训练代码的目录中创建Python 3.12虚拟环境：

创建成功后，终端会显示类似下面的信息：

UsingCPython3.12
Creatingvirtual environment at: .venv
Activatewith: source .venv/bin/activate

在macOS或Linux中激活虚拟环境：

Windows环境可以使用：

虚拟环境激活后，终端提示符前通常会出现.venv标识。

安装csghub-sdk和训练依赖

在已经激活的虚拟环境中安装csghub-sdk：

如果要同时安装训练相关依赖，可以使用：

uvpip install"csghub-sdk[train]"

为了完成模型评估和训练调度，还需要安装scikit-learn和accelerate：

uvpip install scikit-learn accelerate

至此，本地环境已经具备连接CSGHub、下载资源和运行训练代码的基本条件。

验证本地环境

正式开始上传和训练之前，可以先下载一个公开模型，检查csghub-cli能否正常连接CSGHub。

确认当前终端已经设置Token：

exportCSGHUB_TOKEN=your_access_token

然后执行：

csghub-cli download Qwen/Qwen3-0.6B \ --local-dir ./Qwen3-0.6B

这里使用公开的Qwen模型进行连接测试。看到模型文件开始下载，说明csghub-sdk、命令行工具、网络连接和身份认证已经可以正常工作。

03 上传基座模型与数据集

本地环境准备完成后，需要在CSGHub上建立两个资源仓库：

一个模型仓库，用于保存中文基座模型；
一个数据集仓库，用于保存文本分类训练数据。

训练完成后，还会再创建一个新的模型仓库，用于保存微调结果。

在CSGHub上创建基座模型仓库

登录CSGHub后，点击个人头像进入“新建资源”页面，选择创建模型仓库。

填写模型仓库信息：

Model Name：bert-base-chinese

License：根据模型实际协议选择

Visibility：Public或Private

确认信息后点击创建。

模型仓库创建完成后，平台会生成一个独立的仓库页面，用于保存模型权重、配置文件、分词器文件以及后续补充的模型说明。

上传BERT中文基座模型

如果已经在本地准备好bert-base-chinese模型目录，可以使用csghub-cli上传整个文件夹。

先确认Token已经写入当前环境：

exportCSGHUB_TOKEN=your_access_token

然后执行：

csghub-cli upload-large-folder \ -t model \ your-username/bert-base-chinese \ ./bert-base-chinese

其中，-t model表示上传目标为模型仓库，最后一个参数是本地模型目录。

上传过程中，命令行会显示文件扫描和上传进度。模型文件较大时，需要等待一段时间。

完成这一步后，基座模型已经从本地文件变成了个人账号下可以持续管理的社区资源。

准备文本分类数据集

这次使用JSONL格式保存训练数据。JSONL文件中的每一行都是一条独立数据，包含两个字段：

text ：需要分类的中文文本；
label ：对应的分类标签，0表示负面，1表示正面。

示例数据如下：

{"text":"这部电影真的太精彩了！演员演技在线，剧情环环相扣，看得我热血沸腾。","label":1}
{"text":"餐厅的菜难吃死了，服务态度也很差，绝对不会再来了。","label":0} {"text":"这个产品质量超出预期，性价比超高，推荐给所有需要的朋友！","label":1}
{"text":"完全是浪费钱，做工粗糙，用了两次就坏掉了，太失望了。","label":0}
{"text":"酒店房间干净整洁，窗外的城市夜景美不胜收，住得非常舒服。","label":1}
{"text":"这本书内容枯燥乏味，读了一半就读不下去了，人物塑造也很失败。","label":0}
{"text":"客服太给力了！态度热情专业，几分钟就帮我解决了所有问题。","label":1}
{"text":"这个App频繁闪退，还特别耗电，体验极差，建议不要下载。","label":0}
{"text":"吃过最好吃的披萨！饼底酥脆，配料新鲜，芝士拉丝超长。","label":1}
{"text":"快递太慢了，等了整整一周才收到，而且没有任何物流更新，很失望。","label":0}

在本地创建下面的目录和文件：

sentiment-train-data/
└── bert_sample.jsonl

将示例数据写入bert_sample.jsonl。

这里的10条数据主要用于展示数据格式和验证训练流程。正式训练分类模型时，需要准备规模更大、质量更高且标签准确的数据集，并尽量保证不同类别的样本数量相对均衡。

创建数据集仓库

回到CSGHub的“新建资源”页面，选择创建数据集仓库。

数据集名称填写：sentiment-train-data

选择合适的开源协议和可见范围后，完成仓库创建。

对于小于5MB的数据文件，可以直接通过网页端上传。如果希望继续使用命令行，也可以上传整个本地目录。

上传文本分类数据集

确认终端中已经设置Token：

exportCSGHUB_TOKEN=your_access_token

执行下面的命令：

csghub-cli upload-large-folder
\ -t dataset
\ your-username/sentiment-train-data
\ ./sentiment-train-data

-t dataset表示上传目标为数据集仓库。命令会扫描sentiment-train-data目录，并将其中的文件上传到对应的社区仓库。

上传结束后，打开数据集仓库，确认bert_sample.jsonl已经出现在文件列表中。

完成这一步后，训练需要使用的基座模型和文本分类数据已经全部保存在CSGHub上。

04 使用csghub-sdk下载资源并完成微调

资源准备好后，后续操作可以转到本地训练环境。

使用SDK下载数据集

在Python代码中导入snapshot_download：

frompycsghub.snapshot_downloadimportsnapshot_download

dataset_id ="your-username/sentiment-train-data"
snapshot_download(
  dataset_id,
  repo_type="dataset",
  local_dir="./sentiment-train-data"
)

下载完成后，数据集文件会保存在：

使用SDK下载基座模型

继续使用snapshot_download下载模型仓库：

model_id ="your-username/bert-base-chinese"
snapshot_download(
  model_id,
  repo_type="model",
  local_dir="./bert-base-chinese"
)

模型会保存在：

这样，模型和数据集都通过CSGHub仓库进入了本地训练目录，不需要再单独寻找文件来源。

加载数据集

使用Datasets读取JSONL数据：

fromdatasetsimportload_dataset
dataset =load_dataset(
 "json",
  data_files="./sentiment-train-data/bert_sample.jsonl"
)

可以先查看数据集的基本信息和前两条样本：

print("\n训练数据集信息：", dataset)
print("\n数据集前两条数据：", dataset["train"][:2])

确认字段名称和数据内容没有问题后，按照8∶2的比例划分训练集和测试集：

dataset= dataset["train"].train_test_split(test_size=0.2,seed=42)

seed=42用于固定随机划分结果，让重复运行时的数据划分尽量保持一致。

加载分词器和分类模型

使用Transformers加载刚刚下载的本地模型：

from transformers import (
  AutoTokenizer,
  AutoModelForSequenceClassification
)
model_path ="./bert-base-chinese"
tokenizer = AutoTokenizer.from_pretrained(model_path)
model = AutoModelForSequenceClassification.from_pretrained(
  model_path,
  num_labels=2
)

num_labels=2表示当前任务包含两个分类结果，即正面和负面。

对训练文本进行分词

原始中文文本不能直接输入模型，需要先通过分词器转换成Token序列。

定义数据处理函数：

deftokenize_function(examples):
 returntokenizer(
    examples["text"],
    padding="max_length",
    truncation=True,
    max_length=256
  )

对整个数据集进行批量处理：

tokenized_dataset = dataset.map(
  tokenize_function,
  batched=True
)

其中，padding="max_length"会将文本补齐到统一长度，truncation=True会截断超过最大长度的内容，max_length=256表示每条文本最多保留256个Token。

设置训练参数

训练参数可以通过TrainingArguments统一设置：

fromtransformersimportTrainingArguments
training_args = TrainingArguments(
  output_dir="./model-checkpoints",
  num_train_epochs=3,
  per_device_train_batch_size=4,
  per_device_eval_batch_size=4,
  eval_strategy="epoch",
  save_strategy="epoch",
  logging_steps=5,
  load_best_model_at_end=True,
  metric_for_best_model="accuracy",
  dataloader_pin_memory=False,
  seed=42,
  report_to="none"
)

这组参数会训练3轮，每批处理4条数据，并在每个训练轮次结束后进行评估和保存。

如果本地Transformers版本较旧，eval_strategy可能需要改为：

evaluation_strategy="epoch"

定义模型评估指标

使用scikit-learn计算准确率：

fromsklearn.metricsimportaccuracy_score
defcompute_metrics(pred):
  labels = pred.label_ids
  predictions = pred.predictions.argmax(-1)
  accuracy = accuracy_score(labels, predictions)
 return{"accuracy": accuracy}

准确率表示所有样本中预测正确的比例。示例数据规模很小，准确率主要用于观察训练流程是否正常。

正式训练时，如果不同类别的样本数量差异较大，可以继续增加以下指标：

Precision：模型预测为正例的数据中，有多少是真正的正例；
Recall：所有真正的正例中，模型成功找到多少；
F1-score：综合衡量Precision和Recall。
创建Trainer并执行训练

将模型、训练参数、训练集、测试集和评估函数交给Trainer：

fromtransformersimportTrainer
trainer =Trainer(
  model=model,
  args=training_args,
  train_dataset=tokenized_dataset["train"],
  eval_dataset=tokenized_dataset["test"],
  compute_metrics=compute_metrics
)

开始训练：

训练过程中，模型会不断更新参数。每个训练轮次结束后，程序会使用测试集计算准确率，并根据metric_for_best_model保留表现最好的模型版本。

保存微调模型

训练结束后，将模型权重和分词器保存到同一个目录：

output_path ="./chs-sentiment-model"
model.save_pretrained(output_path)
tokenizer.save_pretrained(output_path)

保存完成后，本地会生成：

这个目录中包含模型权重、模型配置、分词器配置和词表等文件。

进行本地推理测试

为了确认模型能够正常加载和输出结果，可以输入一条没有直接出现在训练代码中的中文评论：

test_text="这家店的奶茶超级好喝，珍珠也很Q弹！"

完成分词并执行推理：

device = model.device
inputs = tokenizer(
  test_text,
  return_tensors="pt",
  truncation=True,
  max_length=256
)
inputs = {
  key: value.to(device)
  for key, value in inputs.items()
}
outputs = model(**inputs)
prediction = outputs.logits.argmax(dim=-1).item()
result ="正面"if prediction == 1else"负面"
print(f"\n测试文本：{test_text}")
print(f"预测结果：{result}")

程序会输出模型对这段文本的分类结果。

05将微调模型上传回CSGHub

本地推理能够正常输出结果后，就可以把chs-sentiment-model目录上传回CSGHub。

创建微调模型仓库

进入CSGHub“新建资源”页面，创建新的模型仓库。

模型名称填写：chs-sentiment-model

选择开源协议和可见范围后完成创建。

微调模型与基座模型分开保存，可以避免覆盖原始模型，也方便后续继续训练和管理不同版本。

使用命令行上传微调模型

确认当前终端中已经设置Token：

exportCSGHUB_TOKEN=your_access_token

执行上传命令：

csghub-cli upload-large-folder  -t model  your-username/chs-sentiment-model  ./chs-sentiment-model

命令会将本地模型目录中的权重、配置文件和分词器文件上传到新建的模型仓库。

查看模型仓库

上传完成后，进入CSGHub个人主页，打开chs-sentiment-model仓库。

在文件列表中，可以看到微调模型相关文件已经完整保存。

后续还可以继续补充模型介绍，包括：

模型适用的文本分类任务；
训练数据的来源和字段格式；
训练参数；
模型评估结果；
本地加载和推理方法；
模型存在的限制。

这些信息能够帮助之后的使用者了解模型是如何训练出来的，也方便自己继续管理不同实验版本。

06 从一次微调到可复用的社区模型

完整跑过一次之后，CSGHub在这条链路中的作用会更加清楚。

它把模型训练前后的资源连接起来：基座模型和数据集从社区仓库进入本地环境，训练结果再从本地回到新的模型仓库。

整个过程可以归纳为四步：

在CSGHub创建并管理模型、数据集仓库；
使用csghub-sdk将社区资源下载到本地；
使用Transformers完成模型微调和推理验证；
使用csghub-cli将训练结果上传回CSGHub。

这次使用的示例数据规模很小，重点是验证从资源准备、SDK下载到模型上传的完整链路。要让模型真正用于实际任务，还需要继续扩大训练数据规模，检查数据质量，并根据数据分布增加Precision、Recall和F1-score等评估指标。

但从社区资源到个人模型的基本路径已经形成。后续无论是主题分类、内容审核、评论分析还是用户意图识别，都可以在这套流程上替换数据集、调整标签数量和训练参数，继续完成新的分类模型。

07 关于OpenCSG

OpenCSG 是全球领先的开源大模型社区平台，致力于打造开放、协同、可持续生态，AgenticOps是人工智能领域的一种AI原生方法论，由OpenCSG（开放传神）提出AgenticOps是Agentic AI的最佳落地实践也是方法论。核心产品CSGHub提供模型、数据集、代码与 AI 应用的一站式托管、协作与共享服务，具备业界领先的模型资产管理能力，支持多角色协同和高效复用。

posted @ 2026-09-27 16:20 OpenCSG 阅读(4) 评论(0) 收藏举报

刷新页面返回顶部

OpenCSG