KoBERT

• KoBERT
  • 韩语 BERT 预训练大小写模型 (KoBERT)
    • 为什么？
    • 训练环境
    • 要求
    • 如何安装
  • 使用方法
    • 与 PyTorch 结合使用
    • 与 ONNX 结合使用
    • 与 MXNet-Gluon 结合使用
    • 分词器
  • 子任务
    • Naver 情感分析
    • 基于 KoBERT 和 CRF 的韩语命名实体识别器
    • 韩语 Sentence BERT
  • 发布
  • 联系方式
  • 许可证

---

韩语 BERT 预训练大小写模型 (KoBERT)

为什么？

• 谷歌 BERT base 多语言大小写模型在韩语上的性能局限性

训练环境

• 架构

predefined_args = {
        'attention_cell': 'multi_head',
        'num_layers': 12,
        'units': 768,
        'hidden_size': 3072,
        'max_length': 512,
        'num_heads': 12,
        'scaled': True,
        'dropout': 0.1,
        'use_residual': True,
        'embed_size': 768,
        'embed_dropout': 0.1,
        'token_type_vocab_size': 2,
        'word_embed': None,
    }

• 训练数据集

数据	句子	单词
韩语维基	5M	54M

• 训练环境
  • V100 GPU x 32, Horovod（使用 InfiniBand）

• 词汇表
  • 大小：8,002
  • 基于韩语维基学习的分词器（SentencePiece）
  • 参数量较少（92M < 110M）

要求

• 请参阅 requirements.txt

如何安装

• 将 KoBERT 安装为 Python 包

  pip install git+https://git@github.com/SKTBrain/KoBERT.git@master
  

• 如果您想修改源代码，请克隆此仓库

  git clone https://github.com/SKTBrain/KoBERT.git
  cd KoBERT
  pip install -r requirements.txt
  

---

使用方法

PyTorch

如果您更喜欢使用 Huggingface transformers API，请参考这里。

>>> import torch
>>> from kobert import get_pytorch_kobert_model
>>> input_ids = torch.LongTensor([[31, 51, 99], [15, 5, 0]])
>>> input_mask = torch.LongTensor([[1, 1, 1], [1, 1, 0]])
>>> token_type_ids = torch.LongTensor([[0, 0, 1], [0, 1, 0]])
>>> model, vocab  = get_pytorch_kobert_model()
>>> sequence_output, pooled_output = model(input_ids, input_mask, token_type_ids)
>>> pooled_output.shape
torch.Size([2, 768])
>>> vocab
Vocab(size=8002, unk="[UNK]", reserved="['[MASK]', '[SEP]', '[CLS]']")
>>> # 最后一层编码
>>> sequence_output[0]
tensor([[-0.2461,  0.2428,  0.2590,  ..., -0.4861, -0.0731,  0.0756],
        [-0.2478,  0.2420,  0.2552,  ..., -0.4877, -0.0727,  0.0754],
        [-0.2472,  0.2420,  0.2561,  ..., -0.4874, -0.0733,  0.0765]],
       grad_fn=<SelectBackward>)

model 默认以 eval() 模式返回，因此在用于训练时，需要通过 model.train() 命令将其切换到训练模式。

• Naver 情感分析与 PyTorch 微调
  • 建议在 Colab 中使用 [运行时] - [更改运行时类型] - 硬件加速器（GPU）。
  • 

ONNX

>>> import onnxruntime
>>> import numpy as np
>>> from kobert import get_onnx_kobert_model
>>> onnx_path = get_onnx_kobert_model()
>>> sess = onnxruntime.InferenceSession(onnx_path)
>>> input_ids = [[31, 51, 99], [15, 5, 0]]
>>> input_mask = [[1, 1, 1], [1, 1, 0]]
>>> token_type_ids = [[0, 0, 1], [0, 1, 0]]
>>> len_seq = len(input_ids[0])
>>> pred_onnx = sess.run(None, {'input_ids':np.array(input_ids),
>>>                             'token_type_ids':np.array(token_type_ids),
>>>                             'input_mask':np.array(input_mask),
>>>                             'position_ids':np.array(range(len_seq))})
>>> # 最后一层编码
>>> pred_onnx[-2][0]
array([[-0.24610452,  0.24282141,  0.25895312, ..., -0.48613444,
        -0.07305173,  0.07560554],
       [-0.24783179,  0.24200465,  0.25520486, ..., -0.4877185 ,
        -0.0727044 ,  0.07536091],
       [-0.24721591,  0.24196623,  0.2560626 , ..., -0.48743123,
        -0.07326943,  0.07650235]], dtype=float32)

ONNX 转换得到了 soeque1 的帮助。

MXNet-Gluon

>>> import mxnet as mx
>>> from kobert import get_mxnet_kobert_model
>>> input_id = mx.nd.array([[31, 51, 99], [15, 5, 0]])
>>> input_mask = mx.nd.array([[1, 1, 1], [1, 1, 0]])
>>> token_type_ids = mx.nd.array([[0, 0, 1], [0, 1, 0]])
>>> model, vocab = get_mxnet_kobert_model(use_decoder=False, use_classifier=False)
>>> encoder_layer, pooled_output = model(input_id, token_type_ids)
>>> pooled_output.shape
(2, 768)
>>> vocab
Vocab(size=8002, unk="[UNK]", reserved="['[MASK]', '[SEP]', '[CLS]']")
>>> # 最后一层编码
>>> encoder_layer[0]
[[-0.24610372  0.24282135  0.2589539  ... -0.48613444 -0.07305248
   0.07560539]
 [-0.24783105  0.242005    0.25520545 ... -0.48771808 -0.07270523
   0.07536077]
 [-0.24721491  0.241966    0.25606337 ... -0.48743105 -0.07327032
   0.07650219]]
<NDArray 3x768 @cpu(0)>

• Naver 情感分析与 MXNet 微调
  • 

分词器

• 预训练的 Sentencepiece 分词器

>>> from gluonnlp.data import SentencepieceTokenizer
>>> from kobert import get_tokenizer_path
>>> tok_path = get_tokenizer_path()
>>> sp  = SentencepieceTokenizer(tok_path)
>>> sp('分享韩语模型。')
['▁한국', '어', '▁모델', '을', '▁공유', '합니다', '.']

---

任务微调

Naver 情感分析

• 数据集： https://github.com/e9t/nsmc

模型	准确率
BERT base 多语言大小写模型	0.875
KoBERT	0.901
KoGPT2	0.899

使用KoBERT和CRF构建的韩语实体识别器

• https://github.com/eagle705/pytorch-bert-crf-ner

请输入句子：得益于SKTBrain公开的KoBERT模型，我们能够轻松开发基于BERT-CRF的实体识别器。
len: 40, input_token:['[CLS]', '▁SK', 'T', 'B', 'ra', 'in', '에서', '▁K', 'o', 'B', 'ER', 'T', '▁모델', '을', '▁공개', '해', '준', '▁덕분에', '▁B', 'ER', 'T', '-', 'C', 'R', 'F', '▁기반', '▁', '객', '체', '명', '인', '식', '기를', '▁쉽게', '▁개발', '할', '▁수', '▁있었다', '.', '[SEP]']
len: 40, pred_ner_tag:['[CLS]', 'B-ORG', 'I-ORG', 'I-ORG', 'I-ORG', 'I-ORG', 'O', 'B-POH', 'I-POH', 'I-POH', 'I-POH', 'I-POH', 'O', 'O', 'O', 'O', 'O', 'O', 'B-POH', 'I-POH', 'I-POH', 'I-POH', 'I-POH', 'I-POH', 'I-POH', 'O', 'O', 'O', 'O', 'O', 'O', 'O', 'O', 'O', 'O', 'O', 'O', 'O', 'O', '[SEP]']
decoding_ner_sentence: [CLS] <SKTBrain:ORG>에서 <KoBERT:POH> 모델을 공개해준 덕분에 <BERT-CRF:POH> 기반 객체명인식기를 쉽게 개발할 수 있었다.[SEP]

韩语句子BERT

• https://github.com/BM-K/KoSentenceBERT-SKT

模型	余弦相似度 (皮尔逊)	余弦相似度 (斯皮尔曼)	欧几里得距离 (皮尔逊)	欧几里得距离 (斯皮尔曼)	曼哈顿距离 (皮尔逊)	曼哈顿距离 (斯皮尔曼)	点积 (皮尔逊)	点积 (斯皮尔曼)
NLl	65.05	68.48	68.81	68.18	68.90	68.20	65.22	66.81
STS	80.42	79.64	77.93	77.43	77.92	77.44	76.56	75.83
STS + NLI	78.81	78.47	77.68	77.78	77.71	77.83	75.75	75.22

---

发布

• v0.2.4
  • 更改为从Hugging Face Hub下载大文件
• v0.2.3
  • 支持onnx 1.8.0
• v0.2.2
  • 修复错误：No module named 'kobert.utils'
• v0.2.1
  • 修改导入语句
• v0.2
  • 更改为从aws s3下载大文件
  • 更改函数名称
• v0.1.2
  • 修正transformers库的兼容性
  • 修改填充标记的索引
• v0.1.1
  • 将词汇表和分词器合并
• v0.1
  • 初始模型发布

联系方式

有关KoBERT的问题，请在这里提交。

许可证

KoBERT根据Apache-2.0许可证公开。使用该模型和代码时，请遵守许可证条款。完整的许可证内容可在LICENSE文件中查看。

KoBERT 快速上手指南

KoBERT 是专为韩语优化的 BERT 预训练模型，解决了谷歌多语言 BERT 在韩语任务上的性能瓶颈。本指南帮助中国开发者快速在 PyTorch 环境中集成并使用该模型。

环境准备

• 系统要求: Linux / macOS / Windows
• Python 版本: 建议 Python 3.6+
• 核心依赖:
  • PyTorch
  • gluonnlp (用于加载词汇表和分词器)
  • sentencepiece
• 硬件建议: 推理可在 CPU 运行，微调或训练建议使用 GPU。

注意: 由于模型权重文件较大，首次运行时会自动从 Hugging Face Hub 或 AWS S3 下载。国内用户若遇到下载缓慢问题，建议配置网络代理或检查 requirements.txt 中的源设置。

安装步骤

你可以选择直接安装发布版，或克隆源码进行开发。

方式一：直接安装（推荐）

pip install git+https://git@github.com/SKTBrain/KoBERT.git@master

方式二：源码安装（如需修改代码）

git clone https://github.com/SKTBrain/KoBERT.git
cd KoBERT
pip install -r requirements.txt

基本使用

以下是最简单的 PyTorch 使用示例，展示如何加载模型并进行前向传播。

1. 加载模型与分词器

import torch
from kobert import get_pytorch_kobert_model, get_tokenizer_path
from gluonnlp.data import SentencepieceTokenizer

# 加载预训练模型和词汇表
# 默认返回 eval() 模式，如需训练请调用 model.train()
model, vocab = get_pytorch_kobert_model()

# 加载分词器
tok_path = get_tokenizer_path()
tokenizer = SentencepieceTokenizer(tok_path)

2. 文本预处理与推理

假设输入两句韩语文本，将其转换为模型所需的 Tensor 格式：

# 模拟分词后的 ID (实际使用中需将文本通过 tokenizer 转为 input_ids)
# 这里直接使用示例 ID 演示流程
input_ids = torch.LongTensor([[31, 51, 99], [15, 5, 0]])
input_mask = torch.LongTensor([[1, 1, 1], [1, 1, 0]])
token_type_ids = torch.LongTensor([[0, 0, 1], [0, 1, 0]])

# 执行前向传播
with torch.no_grad():
    sequence_output, pooled_output = model(input_ids, input_mask, token_type_ids)

# 输出维度说明
print(f"Pooled Output Shape: {pooled_output.shape}") 
# 结果: torch.Size([2, 768])，可用于分类任务

print(f"Sequence Output Shape: {sequence_output.shape}") 
# 结果: torch.Size([2, 3, 768])，可用于序列标注等任务

3. 实际分词示例

text = '한국어 모델을 공유합니다.'
tokens = tokenizer(text)
print(tokens)
# 输出: ['▁한국', '어', '▁모델', '을', '▁공유', '합니다', '.']

# 后续需将 tokens 映射为 vocab 中的 index 构建 input_ids

提示: 对于具体的下游任务（如情感分析、命名实体识别），官方提供了基于 PyTorch 和 MXNet 的 Fine-tuning 脚本，可参考项目仓库中的 scripts 目录或 Colab 示例。