目录
master
分支1
标签0
+ 疑修
Web IDE
Christin-liu
Add compute voucher and MetaX instance setup steps
3天前4次提交
README.md

PaperScope

Academic Paper Classification with InternLM

基于 InternLM 的学术论文分类实战（沐曦 GPU）。

本教程使用 VS Code 连接远端沐曦 GPU 开发机，完成环境配置、论文数据准备、LoRA 领域适配、分类指令微调和模型推理。学习者需要具备基本的终端操作能力，并准备支持 SSH 登录的 GPU 容器。

项目目标

  1. 掌握通过 VS Code 连接远端 GPU、配置环境并运行模型训练的基本流程。
  2. 能够整理论文数据，使用 InternLM 和 LoRA 完成论文分类模型微调。
  3. 能够输入论文标题与摘要获得学科分类，并保存模型、分析分类效果。

学生任务

自行寻找并整理论文训练数据，基于统一的 InternLM2.5-1.8B-Chat 模型完成分类微调，提交模型 adapter、数据和训练配置。教师使用不公开的统一测试集评测并打分。

教程演示两阶段训练；课程作业采用单阶段 LoRA SFT，便于统一加载和评测。具体要求见 学生任务与提交要求。

目录

  1. 环境介绍
  2. 算力获取与 VS Code 连接
  3. 开发机和目录介绍
  4. 安装包、模型与数据准备
  5. 开启训练
  6. 模型推理与论文分类
  7. 常见问题
  8. 备份与恢复
  9. 模型发布与评测

1. 环境介绍

1.1 软件与硬件要求

本文配置面向以下沐曦软件栈。创建开发机时应核对镜像版本；其他版本需要重新确认兼容性。

项目 配置
系统 Ubuntu 22.04
GPU MetaX C500，实例可用显存约 16 GB 或以上
内存 32 GiB 或以上
存储 建议准备 100 GB 数据盘，容纳模型、检查点和备份
MACA / 驱动 3.5.3.20 / 3.8.30
Python /opt/conda/bin/python3.10，3.10.10
PyTorch 厂商版 2.8.0+metax3.5.3.9
XTuner / Transformers 0.1.23 / 4.48.0
MMEngine / PEFT 0.10.6 / 0.14.0
DeepSpeed 0.16.5+9e364b1b.maca3.5.3.5

容器分配的显存可能小于显卡物理显存，请以容器实际配额为准。Python 环境需要继承镜像中的沐曦 PyTorch，因此应选用预装厂商软件栈的镜像。

1.2 任务和训练流程

输入论文标题、作者与摘要，模型输出对应学科类别。训练使用 InternLM2.5-1.8B-Chat，分为两个阶段：

  1. 领域适配：使用 575 条论文文本训练 LoRA，让模型适应论文表达方式，再将 adapter 合并到基础模型。
  2. 分类指令微调：在第一阶段合并模型上，使用 495 条分类指令训练 LoRA，再合并为最终分类模型。

目录中的 pretrain 指领域适配阶段，不是从零预训练。按照配套数据和配置，两个阶段分别包含 575 和 1485 个训练迭代。

2. 算力获取与 VS Code 连接

2.1 领取算力券并创建实例

0. 领取算力

进入对应通道，按页面提示完成领取。领取条件、券的使用范围和有效期以活动页面为准。

1. 访问沐曦算力平台

进入 模力方舟（Gitee AI）沐曦算力平台。

2. 创建沐曦 GPU 实例

  1. 在“芯片厂商”中选择 沐曦，选择 曦云 C500。本实验可使用 16 GB、32 GB 或 64 GB 显存，具体以课程提供的资源为准。
  2. 点击 “租用”，进入订单创建页面。
  3. 参考课程提供的截图，选择 沐曦-vllm 预装镜像，并核对其 Python、MACA 和厂商 PyTorch 版本是否符合第 1 节要求。
  4. 按页面要求填写项目信息，确认实例配置及算力券适用情况后，点击 “创建项目”。
  5. 等待实例启动，进入实例详情页，获取 SSH 连接信息。

3. 准备远端连接信息

在算力平台创建符合第 1 节要求的实例，启用 SSH，并记录服务器地址、SSH 端口、用户名及登录方式。确认实例可以下载模型和 Python 软件包，且账号有权创建 /data 下的目录。系统安装命令按具备管理员权限的容器编写。

准备 教程配套文件包，解压后可获得配置、训练脚本、推理脚本和两份数据。将配套包与本教程一起提供给学习者。

2.2 使用 Remote - SSH 连接

  1. 安装并打开 VS Code，确保电脑已安装 OpenSSH 客户端。
  2. 打开扩展面板，安装 Microsoft 发布的 Remote - SSH。
  3. 按 F1 打开命令面板，选择 **Remote-SSH: Add New SSH Host…**。
  4. 按平台提供的凭据填写连接命令，替换下面三个占位符：
ssh -p <SSH端口> <用户名>@<服务器地址>
  1. 选择保存 SSH 配置的文件。
  2. 再次按 F1，选择 **Remote-SSH: Connect to Host…**，选择刚添加的主机；如提示选择远端系统，选 Linux。
  3. 根据提示使用密码或 SSH 密钥登录，等待 VS Code Server 安装完成。

左下角出现 SSH: 主机名称 表示当前窗口已连接远端。以上操作通过 Remote - SSH 打开远端工作区。参考：VS Code Remote - SSH 官方说明。

2.3 打开远端终端和工作目录

在已连接的 VS Code 窗口中选择 终端 → 新建终端，运行：

bash -l
mkdir -p /data/paper-classify /data/data /data/models

随后选择 文件 → 打开文件夹，输入 /data/paper-classify。资源管理器中的文件和这个窗口中新建的终端都属于远端开发机。

后续所有 Bash 和 Python 命令均在 VS Code 的远端终端中执行。 上传、下载文件的操作会单独说明。

每次新开远端终端，先加载登录环境；虚拟环境创建完成后，再激活它：

bash -l
source /data/xtuner-env/bin/activate
cd /data/paper-classify
export HF_HOME=/data/huggingface_home

首次操作时先跳过 source，按第 4 节创建环境。

3. 开发机和目录介绍

路径 用途
/opt/conda 镜像内的 Python、沐曦 PyTorch
/data/xtuner-env 训练使用的 Python 环境
/data/models/internlm2_5-1_8b-chat 原始模型
/data/data 两份训练数据
/data/paper-classify 配置、脚本、日志和训练输出
work_dirs/pretrain/hf 第一阶段 LoRA adapter
work_dirs/pretrain/merged 第一阶段合并模型，也是 SFT 的基础模型
work_dirs/sft/hf 第二阶段 LoRA adapter
work_dirs/sft/merged 最终可推理模型 
cat /etc/os-release
df -h /data
free -h
command -v mx-smi && mx-smi
printf 'MACA_PATH=%s\n' "$MACA_PATH"
/opt/conda/bin/python3.10 --version
mkdir -p /data/paper-classify /data/data /data/models

4. 安装包、模型与数据准备

依次完成软件环境、训练文件、数据和模型准备。本节依赖第 1 节的厂商镜像及其基础包，不适用于未配置 GPU 软件栈的纯 Ubuntu 镜像。

4.1 系统工具和 Python 环境

仅在缺少基础工具时执行：

apt update
apt install -y git git-lfs wget curl

使用镜像自带的 Python 创建环境，以继承沐曦 PyTorch；保留厂商 PyTorch，避免安装普通 CPU/CUDA 版本将其覆盖。

/opt/conda/bin/python3.10 -m venv --system-site-packages /data/xtuner-env
source /data/xtuner-env/bin/activate
python -c "import sys,torch; print(sys.executable); print(torch.__version__)"

应看到 /data/xtuner-env/bin/python 和 2.8.0+metax3.5.3.9。--system-site-packages 用来继承镜像中的厂商 PyTorch。

4.2 安装训练依赖

安装与上述软件栈匹配的固定版本。使用 --no-deps 避免依赖解析替换厂商 PyTorch；这不是适用于任意裸 Ubuntu 的通用依赖清单。

python -m pip install --no-deps \
  xtuner==0.1.23 transformers==4.48.0 tokenizers==0.21.4 \
  mmengine==0.10.6 peft==0.14.0 sentencepiece==0.1.99 \
  protobuf==3.20.3 opencv-python-headless==4.10.0.84 \
  modelscope-hub==0.4.5 accelerate==1.15.0 addict==2.4.0 \
  matplotlib==3.10.9 yapf==0.43.0 openpyxl==3.1.5 \
  scikit-image==0.25.2 transformers-stream-generator==0.0.5 \
  lagent==0.2.4 hjson==3.1.0 \
  contourpy==1.3.2 cycler==0.12.1 fonttools==4.65.0 \
  kiwisolver==1.5.1 pyparsing==3.3.3 lazy-loader==0.6 \
  ImageIO==2.38.0 tifffile==2025.5.10

python -m pip install --no-deps \
  'deepspeed==0.16.5+9e364b1b.maca3.5.3.5' \
  -i https://repos.metax-tech.com/r/maca-pypi/simple \
  --trusted-host repos.metax-tech.com

镜像需要提供 NumPy 1.26.4、datasets 4.8.4、SciPy 1.15.3 等基础包。若镜像不同、出现缺包，请先核对版本，不要直接升级整个环境。即使不用 ZeRO，XTuner 启动也会导入 DeepSpeed，因此厂商版 DeepSpeed 仍需安装。

4.3 GPU 和关键导入检查

python - <<'PYCODE'
import sys, torch
import xtuner, transformers, mmengine, peft, deepspeed
print('Python:', sys.executable)
print('Torch:', torch.__version__)
print('Transformers:', transformers.__version__)
print('GPU available:', torch.cuda.is_available())
assert torch.cuda.is_available(), 'GPU 不可用，先检查镜像与驱动'
print('GPU:', torch.cuda.get_device_name(0))
a = torch.randn(512, 512, device='cuda', dtype=torch.bfloat16)
b = a @ a
assert torch.isfinite(b).all().item()
print('GPU BF16 矩阵运算通过')
PYCODE
xtuner version

沐曦兼容层也使用 torch.cuda 接口。

4.4 上传配置、脚本和数据

配套包中的配置已经使用本文约定的目录。请保持文件名和路径一致。

文件 用途 上传到远端的位置
pretrain_metax_16g.py 领域适配配置 /data/paper-classify/
sft_metax_16g.py 分类微调配置 /data/paper-classify/
run_full_training.sh 自动执行两阶段训练、转换与合并 /data/paper-classify/
validate_final_model.py 加载模型并生成分类 /data/paper-classify/
restore_from_adapters.sh 从两阶段 adapter 恢复模型 /data/paper-classify/
data/pretrain.jsonl 论文文本数据 /data/data/pretrain.jsonl
data/sftdata.jsonl 分类指令数据 /data/data/sftdata.jsonl

在 VS Code 远端资源管理器中打开 /data/paper-classify，将解压后的五个脚本文件从电脑文件管理器拖入这个文件夹。通过 文件 → 将文件夹添加到工作区 添加 /data/data，再把两份 JSONL 数据拖入该目录。文件较多或拖拽不可用时，也可以使用算力平台的文件上传入口，上传到表中相同位置。

确认上传完成后，在远端终端校验数据：

python - <<'PYCODE'
import json
from pathlib import Path
for name, keys, expected in [
    ('pretrain.jsonl', ['text'], 575),
    ('sftdata.jsonl', ['instruction', 'input', 'output'], 495),
]:
    rows = [json.loads(s) for s in (Path('/data/data')/name).read_text().splitlines() if s.strip()]
    assert len(rows) == expected, (name, len(rows))
    assert all(all(k in r for k in keys) for r in rows), name
    print(name, len(rows), '条，字段检查通过')
PYCODE

4.5 下载原始模型

export HF_HOME=/data/huggingface_home
ms-hub download Shanghai_AI_Laboratory/internlm2_5-1_8b-chat \
  --local-dir /data/models/internlm2_5-1_8b-chat
ls -lh /data/models/internlm2_5-1_8b-chat

等待下载完成；基础模型约 3.6 GiB，包含配置、Tokenizer、模型代码和两个 safetensors 权重分片。不要在下载未完成时开始训练。

5. 开启训练

5.1 正式配置为何这样设置

参数 领域适配 SFT
batch_size 1 1
max_length 1024 1024
epochs 1 3
学习率 2e-5 2e-4
梯度累积 16 1
LoRA r / alpha 64 / 16 64 / 16
精度 / 注意力 BF16 / eager BF16 / eager
激活检查点 开启 开启
数据拼接 / workers 不拼接 / 0 不拼接 / 0

这里使用 BF16 LoRA，不使用 bitsandbytes 4bit、FlashAttention 或 DeepSpeed ZeRO。SFT 使用 internlm2_chat 模板。请直接使用配套配置文件，避免遗漏模型路径、数据模板或优化器设置。

5.2 推荐：后台运行完整流水线

只在尚无正式训练输出的工作目录启动。脚本检测到已有正式 .pth 会停止，以免误覆盖；如要重新实验，先备份并迁移旧的正式输出，确认没有训练进程运行后再开始。

cd /data/paper-classify
nohup bash -lc 'bash /data/paper-classify/run_full_training.sh' \
  > /data/paper-classify/full_pipeline.log 2>&1 < /dev/null &
echo $!

必须保留 bash -lc：登录环境会加载 MACA 的路径设置。nohup 能避免普通 SSH 断开终止任务，但不能抵御容器重启或释放。

查看进度：

cat /data/paper-classify/pipeline.status
tail -n 30 /data/paper-classify/full_pipeline.log
# 第一阶段启动后查看
tail -f /data/paper-classify/logs/pretrain.log
# SFT 启动后查看；按 Ctrl+C 只退出日志查看
tail -f /data/paper-classify/logs/sft.log

流水线依次运行 pretrain、pretrain_convert、pretrain_merge、sft、sft_convert、sft_merge。各阶段日志位于 logs/对应阶段.log。启动返回 PID 不代表完成。

完成后 pipeline.status 应包含：

stage=completed
result=succeeded
exit_code=0

5.3 学习用：拆开执行六步

这是 5.2 的替代方式，不要和后台流水线同时运行，也不要在完成后再重复运行。以下检查点编号对应本文同一份数据和配置；改变样本数或 epochs 后必须换成实际保存的编号。

cd /data/paper-classify
source /data/xtuner-env/bin/activate

# 1. 论文文本领域适配
python -m xtuner.tools.train pretrain_metax_16g.py --work-dir work_dirs/pretrain

# 2. 第一阶段检查点转换为 HF adapter
TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1 python -m xtuner.tools.model_converters.pth_to_hf \
  pretrain_metax_16g.py work_dirs/pretrain/iter_575.pth work_dirs/pretrain/hf

# 3. 第一阶段 adapter 合入原始模型
python -m xtuner.tools.model_converters.merge \
  /data/models/internlm2_5-1_8b-chat work_dirs/pretrain/hf \
  work_dirs/pretrain/merged --max-shard-size 2GB

# 4. 基于第一阶段合并模型做分类 SFT
python -m xtuner.tools.train sft_metax_16g.py --work-dir work_dirs/sft

# 5. SFT 检查点转换为 HF adapter
TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1 python -m xtuner.tools.model_converters.pth_to_hf \
  sft_metax_16g.py work_dirs/sft/iter_1485.pth work_dirs/sft/hf

# 6. 第二阶段 adapter 合入第一阶段模型
python -m xtuner.tools.model_converters.merge \
  work_dirs/pretrain/merged work_dirs/sft/hf \
  work_dirs/sft/merged --max-shard-size 2GB

逐条执行并检查是否报错。最后一步基础模型必须是 work_dirs/pretrain/merged，不能重新指向最初下载的模型，否则无法保留完整的两阶段训练链路。

6. 模型推理与论文分类

6.1 加载训练完成的模型

bash -l
source /data/xtuner-env/bin/activate
cd /data/paper-classify
python validate_final_model.py
cat final_model_validation.json

脚本加载最终模型，对自然语言处理和量子物理两篇示例论文生成分类，并将结果写入 final_model_validation.json。对应类别分别为 D 和 J，可将生成结果与类别含义对照。这是推理演示，不能代替独立数据集的准确率评测。

流水线不会自动运行此验证脚本，训练完成后需要单独执行。

6.2 输入自己的论文

python - <<'PYCODE'
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM
path = '/data/paper-classify/work_dirs/sft/merged'
tok = AutoTokenizer.from_pretrained(path, trust_remote_code=True)
model = AutoModelForCausalLM.from_pretrained(
    path, trust_remote_code=True, torch_dtype=torch.bfloat16,
    attn_implementation='eager').cuda().eval()
# 将下面三个变量替换为论文的真实信息
title = 'Neural machine translation for low-resource languages'
authors = 'Example Authors'
abstract = 'We evaluate multilingual machine translation on low-resource language pairs.'
options = '\nA. astro-ph\nB. cond-mat.mes-hall\nC. cond-mat.mtrl-sci\nD. cs.CL\nE. cs.CV\nF. cs.LG\nG. gr-qc\nH. hep-ph\nI. hep-th\nJ. quant-ph'
query = ('你是个优秀的论文分类师\n'
         f"Based on the title '{title}', authors '{authors}', and abstract '{abstract}', "
         'please determine the scientific category of this paper.' + options)
with torch.inference_mode():
    answer, _ = model.chat(tok, query, history=[], meta_instruction='',
                           do_sample=False, max_new_tokens=64)
print('分类结果:', answer)
PYCODE

最终模型可能保存为两个 .bin 分片；不要求一定出现 .safetensors。通过实际加载和生成判断模型是否有效。

7. 常见问题

问题 处理方式
系统 Python 找不到 torch 用 /opt/conda/bin/python3.10 创建继承系统包的 venv
安装 CPU 或普通 CUDA PyTorch 保留厂商 +metax 版；不要覆盖
MACA 路径为空，Triton 报 NoneType 重新进入 bash -l；后台任务用 bash -lc
只分配约 16 GB 显存 batch 1、长度 1024、BF16 LoRA、激活检查点、eager
未使用 ZeRO 却报缺 DeepSpeed XTuner 启动仍导入它；安装本手册指定厂商版
转换 .pth 出现 weights-only 加载错误 对自己可信的检查点使用命令级 TORCH_FORCE_NO_WEIGHTS_ONLY_LOAD=1
命令结束但实际有 traceback 使用本文的 Python 模块命令，并检查日志和产物
pip check 显示 vLLM、OpenCV 等冲突 原镜像含其他用途依赖；这些包可能有不同的版本约束，不要为它们升级 torch；以关键导入和实际训练检查为准
SFT 合并回最初基础模型 改为合入第一阶段 pretrain/merged
断开 SSH 后台任务通常继续；重连后看状态和日志
容器重启后状态仍显示 running 状态文件可能残留；检查进程和新日志，不能仅凭状态文件判断任务仍运行
训练已完成，脚本提示已有检查点 正常保护，直接验证模型；不要删除成果来消除提示

GPU 检查失败时，先核对 MACA_PATH、厂商 torch 版本和容器 GPU 配额。对应软件栈的登录环境中 MACA_PATH=/opt/maca。如果不是同一镜像，停止照搬安装步骤并重新核对厂商依赖。

8. 备份与恢复

8.1 保存两阶段 adapter

训练完成后，在远端终端执行：

cd /data/paper-classify
python -m pip freeze > environment-freeze.txt
tar -czf /data/paper-classify-adapters.tar.gz \
  pretrain_metax_16g.py sft_metax_16g.py \
  run_full_training.sh validate_final_model.py restore_from_adapters.sh \
  environment-freeze.txt work_dirs/pretrain/hf work_dirs/sft/hf
cd /data
sha256sum paper-classify-adapters.tar.gz > paper-classify-adapters.tar.gz.sha256

在算力平台文件管理器中下载压缩包及校验文件，并保存在容器之外。这个包可以恢复推理模型，未包含原始模型、训练数据、完整合并权重和优化器检查点。两阶段 adapter 必须一起保留。

8.2 在新开发机中恢复模型

按第 2—4 节准备环境并下载同一原始模型，通过文件上传入口将压缩包和校验文件上传到 /data，然后执行：

bash -l
source /data/xtuner-env/bin/activate
cd /data
sha256sum -c paper-classify-adapters.tar.gz.sha256
mkdir -p /data/paper-classify-backup
cd /data/paper-classify-backup
tar -xzf /data/paper-classify-adapters.tar.gz
bash restore_from_adapters.sh \
  /data/models/internlm2_5-1_8b-chat /data/paper-classify-restored

校验成功会显示 OK。恢复输出目录 /data/paper-classify-restored 必须尚不存在；最终模型位于 /data/paper-classify-restored/final。将推理代码中的 path 改成这个目录即可使用。

environment-freeze.txt 用于记录版本，不能直接作为另一镜像的通用安装清单。

8.3 保存完整工作目录

需要保留数据、检查点和完整合并模型时，先确认训练进程已经结束，并检查存储空间：

df -h /data
tar -czf /data/paper-classify-full-backup.tar.gz \
  -C /data paper-classify data

通过平台文件管理器下载备份后再释放容器。数据盘是否在重启、释放后保留取决于平台存储策略，不能将容器内文件作为唯一副本。

9. 模型发布与评测

9.1 模型发布（可选）

训练和推理不依赖模型发布。若需要分享模型，可以在支持的模型托管平台创建自己的模型仓库，并上传 work_dirs/sft/merged 目录内的模型、配置、Tokenizer 和模型代码，同时补充模型说明、使用方式与许可信息。

只分享 adapter 时，应注明原始模型标识及“两阶段依次合并”的使用方式。

9.2 独立评测

准备未参与训练的有标签论文数据，保持标题、作者、摘要及分类选项的提示格式一致，逐条生成分类。统计总体准确率、各类别表现与混淆情况，用于判断模型对新论文的分类能力。

输出字母 类别
A astro-ph（天体物理）
B cond-mat.mes-hall（介观系统与量子霍尔效应）
C cond-mat.mtrl-sci（材料科学）
D cs.CL（计算与语言）
E cs.CV（计算机视觉）
F cs.LG（机器学习）
G gr-qc（广义相对论与量子宇宙学）
H hep-ph（高能物理唯象学）
I hep-th（高能物理理论）
J quant-ph（量子物理）

完成本教程后，应得到最终模型目录 work_dirs/sft/merged，能够输入论文信息获得分类，并将训练成果备份到容器之外。

关于

基于沐曦国产GPU及InternLM 的学术论文分类实战

README.md
2.0 MB
邀请码
    Gitlink（确实开源）
  • 加入我们
  • 官网邮箱：gitlink@ccf.org.cn
    • QQ群
  • QQ群
    • 公众号
  • 公众号

版权所有：中国计算机学会技术支持：开源发展技术委员会
京ICP备13000930号-9 京公网安备 11010802047560号