NVIDIAから提供されているPyTorch NGCコンテナをApptainerで使用する際のTipsを紹介します。

PyTorch NGCコンテナは、CUDAやcuDNNなどのNVIDIAライブラリが事前にインストールされており、GPUを活用したモデル学習を簡単に行えます。しかし、Dockerコンテナとして提供されているため、HPC環境で使用するにはApptainer向けに変換が必要です。また、追加のライブラリをインストールする手順がDockerを用いる場合と若干異なります。¹

本記事では、これらの差異に着目して、ApptainerでのPyTorch NGCコンテナの使用方法を解説します。

前提

HPC環境でApptainerがインストールされていることを前提とします。インストールされていない場合は、管理者に依頼してください。

手順

1. Apptainerをロードする

自動的にApptainerがロードされる場合もありますが、手動でロードする必要がある場合は以下のようにコマンドを実行してください。なお、下記はHPC環境によって異なるため、適宜読み替えてください。

$ module load Apptainer/<version>

2. PyTorch NGCコンテナをダウンロードする

$ apptainer pull docker://nvcr.io/nvidia/pytorch:<version>

ここで、<version>は使用したいPyTorch NGCのバージョンを指定します。例えば、PyTorch 25.04-py3を使用する場合は以下のようにします。バージョンは、NGCカタログページから確認できます。

$ apptainer pull docker://nvcr.io/nvidia/pytorch:25.04-py3

変換後のファイル名は、pytorch_<version>-py3.sifの形式になります。例えば、上記のコマンドを実行すると、pytorch_25.04-py3.sifというファイルが生成されます。

3. コンテナを適切なディレクトリに移動する

ダウンロードしたコンテナファイルは、デフォルトではカレントディレクトリに保存されます。個人の好みに応じて、プロジェクトディレクトリや特定のフォルダに移動することをお勧めします。私の場合は、以下のようにプロジェクトディレクトリ内のcontainersフォルダに移動しています。

$ mkdir -p $PROJ_HOME/containers
$ mv pytorch_25.04-py3.sif $PROJ_HOME/containers

4. コンテナを実行する

続いて、ダウンロードしたコンテナを実行します。--nvオプションを指定して、GPUサポートを有効にします。また、--bindオプションを使用して、プロジェクトディレクトリをコンテナ内にマウントします。これにより、コンテナ内からプロジェクトファイルにアクセスできるようになります。

$ apptainer exec \
    --bind $PROJ_HOME:$PROJ_HOME \
    --nv $PROJ_HOME/containers/pytorch_25.04-py3.sif \
    /bin/bash

HPC環境によっては、ホームディレクトリとLustreベースのファイルストレージを自動的にマウントする設定がされている場合があります。その場合、--bindオプションは不要です。マウントされているか否かについては、使用するHPCのドキュメントを確認してください。

5. 必要なライブラリを追加インストールする

PyTorch NGCコンテナには、基本的なPyTorch環境が整っていますが、Transformersやその他のライブラリを使用する場合は、追加でインストールが必要です。追加のインストールには仮想環境を使用することをお勧めします。以下は、pipを使用してTransformersライブラリをインストールする例です。

$ python3 -m venv --system-site-packages $PROJ_HOME/envs/test
$ source $PROJ_HOME/envs/test/bin/activate
$ unset PIP_CONSTRAINT
$ pip install transformers

このコマンドは、プロジェクトディレクトリ内のenvs/testに仮想環境を作成し、そこにTransformersライブラリをインストールします。--system-site-packagesオプションを使用することで、コンテナ内のシステムパッケージも利用できます。

なお、PIP_CONSTRAINT環境変数を解除することで、PyTorch NGCコンテナに設定されているバージョンロックを一時的に無視してインストールを行います。この点がDockerコンテナと異なる点です。/etc/pip/constraint.txtにバージョンロックが設定されていますが、編集できない場合があるため、環境変数を解除する方法を採用しています。

インストールが完了したら、一旦コンテナ内から抜けてください。

$ exit

6. 実際にコンテナを使用する

インタラクティブジョブの場合

インタラクティブジョブを使用してコンテナを実行する場合、上記の4.に示したコマンドをそのまま使用できます。

$ apptainer exec \
    --bind $PROJ_HOME:$PROJ_HOME \
    --nv $PROJ_HOME/containers/pytorch_25.04-py3.sif \
    /bin/bash

なお、コンテナ内でライブラリの環境変数を設定する必要がある場合は、以下を参考にしてください。ただし、パスは環境によっては異なる可能性があります。コンテナが使用するCUDAのバージョンは、公式のサポート表を参照してください。25.04-py3の場合は、CUDA 12.9が使用されているため、以下のように設定します。

export CUDA_HOME=/usr/local/cuda-12.9
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
export TMPDIR=/tmp

ジョブスクリプトの場合

ジョブスクリプトを使用してコンテナを実行する場合、以下のようにapptainer execコマンドを使用します。Slurmのジョブスクリプトの例を以下に示します。

#!/bin/bash
#SBATCH --job-name=pytorch_job
#SBATCH --output=pytorch_job.out
#SBATCH --error=pytorch_job.err
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --gres=gpu:1
#SBATCH --time=01:00:00
#SBATCH --partition=gpu

module load Apptainer/<version>
PROJ_HOME=/path/to/your/project
apptainer exec \
    --bind $PROJ_HOME:$PROJ_HOME \
    --nv $PROJ_HOME/containers/pytorch_25.04-py3.sif \
    python3 $PROJ_HOME/scripts/train.py

コマンドライン引数をたくさん指定したい場合は、シェルスクリプトを実行用(内部)とSlurmジョブスクリプト(ラッパー)用に分けることをおすすめします。以下がその例です。

実行用スクリプト

#!/bin/bash

source $PROJ_HOME/envs/test/bin/activate

export CUDA_HOME=/usr/local/cuda-12.9
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
export TMPDIR=/tmp

python3 $PROJ_HOME/scripts/train.py "$@"  

Slurmジョブスクリプト

#!/bin/bash
#SBATCH --job-name=pytorch_job
#SBATCH --output=pytorch_job.out
#SBATCH --error=pytorch_job.err
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --gres=gpu:1
#SBATCH --time=01:00:00
#SBATCH --partition=gpu

module load Apptainer/<version>
PROJ_HOME=/path/to/your/project
apptainer exec \
    --bind $PROJ_HOME:$PROJ_HOME \
    --nv $PROJ_HOME/containers/pytorch_25.04-py3.sif \
    $PROJ_HOME/scripts/run.sh "$@"

このようにすることで、Slurmジョブスクリプトから実行用スクリプトを呼び出し、Pythonスクリプトを実行できます。

まとめ

本記事では、ApptainerでPyTorch NGCコンテナを使用する方法を解説しました。

PyTorch NGCコンテナはCUDA等の必要なライブラリがほとんど揃っているので、手早く実験環境を構築できます。使ったことがない方は、ぜひ試してみてください。

This post provides tips for using PyTorch NGC containers provided by NVIDIA with Apptainer.

PyTorch NGC containers come with NVIDIA libraries like CUDA and cuDNN pre-installed, making it easy to train models using GPUs. However, since they are provided as Docker containers, they need to be converted for Apptainer use in HPC environments. Additionally, the procedure for installing extra libraries differs slightly from using Docker.

This post focuses on these differences and explains how to use PyTorch NGC containers with Apptainer.

Prerequisites

This guide assumes Apptainer is installed in your HPC environment. If it is not, please ask your system administrator to install it.

Steps

1. Load Apptainer

While Apptainer may be loaded automatically in some cases, if you need to load it manually, run the following command. Note that this command may vary depending on your HPC environment, so adjust it as necessary.

$ module load Apptainer/<version>

2. Download the PyTorch NGC Container

$ apptainer pull docker://nvcr.io/nvidia/pytorch:<version>

Here, <version> specifies the desired PyTorch NGC version. You can check the available versions on the NGC Catalog page. For example, to use PyTorch 25.04-py3, you can run the following command:

$ apptainer pull docker://nvcr.io/nvidia/pytorch:25.04-py3

The converted container file will be in the format pytorch_<version>-py3.sif. For example, running the command above will generate a file named pytorch_25.04-py3.sif.

3. Move the Container to an Appropriate Directory

By default, the downloaded container file is saved in the current directory. I recommend moving it to a project directory or a specific folder according to your preference. In my case, I move it to a containers folder within my project directory as follows:

$ mkdir -p $PROJ_HOME/containers
$ mv pytorch_25.04-py3.sif $PROJ_HOME/containers

4. Run the Container

Next, execute the downloaded container. Specify the --nv option to enable GPU support. Also, use the --bind option to mount your project directory inside the container. This allows you to access project files from within the container.

$ apptainer exec \
    --bind $PROJ_HOME:$PROJ_HOME \
    --nv $PROJ_HOME/containers/pytorch_25.04-py3.sif \
    /bin/bash

In some HPC environments, home directories and Lustre-based file storage might be automatically mounted. In such cases, the --bind option is not necessary. Refer to your HPC documentation to confirm whether this is the case.

5. Install Additional Required Libraries

PyTorch NGC containers come with a basic PyTorch environment, but if you want to use libraries like Transformers or others, you will need to install them additionally. I recommend using a virtual environment for these extra installations. Here is an example of installing the Transformers library using pip:

$ python3 -m venv --system-site-packages $PROJ_HOME/envs/test
$ source $PROJ_HOME/envs/test/bin/activate
$ unset PIP_CONSTRAINT
$ pip install transformers

This command creates a virtual environment in envs/test within your project directory and installs the Transformers library there. The --system-site-packages option allows you to use system packages from within the container.

By unsetting the PIP_CONSTRAINT environment variable, you temporarily override the version lock set in the PyTorch NGC container. This is a key difference from Docker containers. While the version lock is configured in /etc/pip/constraint.txt, it might not be editable, which is why unsetting the environment variable is used.

Once the installation is complete, exit the container.

$ exit

6. Use the Container for Your Tasks

For Interactive Jobs

When running the container for an interactive job, you can use the same command shown in step 4:

$ apptainer exec \
    --bind $PROJ_HOME:$PROJ_HOME \
    --nv $PROJ_HOME/containers/pytorch_25.04-py3.sif \
    /bin/bash

If you need to set library environment variables within the container, refer to the following example. However, paths may vary depending on your environment. For the CUDA version used by the container, refer to the official support matrix. For 25.04-py3, CUDA 12.9 is used, so set it as follows:

export CUDA_HOME=/usr/local/cuda-12.9
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
export TMPDIR=/tmp

For Job Scripts

When running the container using a job script, use the apptainer exec command as shown below. Here’s an example of a Slurm job script:

#!/bin/bash
#SBATCH --job-name=pytorch_job
#SBATCH --output=pytorch_job.out
#SBATCH --error=pytorch_job.err
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --gres=gpu:1
#SBATCH --time=01:00:00
#SBATCH --partition=gpu

module load Apptainer/<version>
PROJ_HOME=/path/to/your/project
apptainer exec \
    --bind $PROJ_HOME:$PROJ_HOME \
    --nv $PROJ_HOME/containers/pytorch_25.04-py3.sif \
    python3 $PROJ_HOME/scripts/train.py

If you need to specify many command-line arguments, I recommend separating the shell script into an execution script (internal) and a Slurm job script (wrapper). Here is an example:

Execution Script

#!/bin/bash

source $PROJ_HOME/envs/test/bin/activate

export CUDA_HOME=/usr/local/cuda-12.9
export LD_LIBRARY_PATH=$CUDA_HOME/lib64:$LD_LIBRARY_PATH
export TMPDIR=/tmp

python3 $PROJ_HOME/scripts/train.py "$@"

Slurm Job Script

#!/bin/bash
#SBATCH --job-name=pytorch_job
#SBATCH --output=pytorch_job.out
#SBATCH --error=pytorch_job.err
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
#SBATCH --gres=gpu:1
#SBATCH --time=01:00:00
#SBATCH --partition=gpu

module load Apptainer/<version>
PROJ_HOME=/path/to/your/project
apptainer exec \
    --bind $PROJ_HOME:$PROJ_HOME \
    --nv $PROJ_HOME/containers/pytorch_25.04-py3.sif \
    $PROJ_HOME/scripts/run.sh "$@"

By doing this, you can call the execution script from the Slurm job script to run your Python script.

Conclusion

This post explained how to use PyTorch NGC containers with Apptainer.

PyTorch NGC containers come with most of the necessary libraries like CUDA pre-installed, allowing you to quickly set up an experimental environment. If you have not used them before, give them a try!

This post is a critique of the resubmission feature in ACL Rolling Review (ARR) – which must be the core feature of the system. In particular, I will focus on the problem of resubmission when we request the same set of reviewers. I hope that this post will help to raise awareness of the issues with the resubmission process in ARR, and hopefully increase the number of reviewers who follow the guidelines when reviewing resubmissions.

How resubmission should work in ARR

In ARR, when you resubmit a paper, you can request the same set of reviewers as before. This is a feature that is supposed to make the process smoother for authors who have already received feedback from those reviewers and have made changes based on that feedback.

The ARR Reviewer Guidelines state that:

• “You will need to reread the paper and comment on to what extent the authors successfully responded to the previous reviews. Please indicate that you read their revision notes and say whether you feel weaknesses were adequately addressed or not.”
• “In your review, you should refrain from raising new issues that were not discussed in the first round of reviews — otherwise, if resubmissions get a new round of weaknesses identified, then authors will never be able to move forward with commitment.”

Specifically for substitute reviewers, the guidelines state:

• “you should then edit your draft review, where (i) you explain the reasons why the revisions did not adequately address previously identified weaknesses; (ii) you explain the reasons why newly raised issues represent critical issues of soundness; and (iii) you reframe any other newly raised issues as suggestions for improvement.”

Great. So the idea seems to be that reviewers should focus on the changes made by the authors in response to the previous reviews, and not raise new issues that were not discussed in the first round of reviews. Furthermore, another important point is that even substitute reviewers should not raise new issues that were not discussed in the first round of reviews, unless they are critical issues of soundness.

How resubmission actually works in ARR

Unfortunately, the intended process for resubmissions in ARR often diverges from reality. In practice, some (many?) reviewers do not follow these guidelines, raise new issues that were not discussed in the first round of reviews, and assign low scores to the resubmitted paper, even if the authors have made significant changes based on the previous reviews.

Here, ARR offers a good feature to combat this kind of behaviour: Review issue reporting. With this feature, authors can report any issues with the reviews they receive, including issues with resubmissions. A meta-reviewer will then look into the reported issues and need to take them into account when making their recommendation.

However, a significant hurdle remains: the complex nature of conference acceptance. Even if a meta-reviewer acknowledges a reviewer’s deviation from guidelines and provides a constructive evaluation, a paper can still be, or is highly likely to be, rejected because of the initial low scores from reviewers.

One typical example of this is a paper I submitted to ARR, which was resubmitted with the same set of reviewers. All the reviewers raised new issues that were not discussed in the first round of reviews, and one of them even wrote a rewiew that was almost simply a copy of the previous review, without taking into account the changes made. Despite reporting these issues and the meta-reviewer agreeing that the guidelines were not followed (even providing a constructive evaluation with no “Summary of suggested revisions” – implying sufficient revisions), the paper was rejected. This outcome was likely due to the low scores the reviewers assigned.

The absence of a “Summary of suggested revisions” typically signifies that authors have adequately addressed previous concerns. Yet, in this case, the paper was still rejected, leaving us without a clear path forward, effectively leaving the paper “dead in the water” within the ARR system.

Discussion

While I understand that no system is perfect and that ARR keeps improving, I believe that the resubmission process in ARR needs significant improvement. The current system does not effectively address the issues that arise when reviewers do not follow the guidelines, and it can lead to unfair outcomes for authors who have made efforts to improve their work based on previous feedback.

While it might not be a problem with the ARR system per se, I believe that the resubmission process should be more robust and better enforced. If this is not possible, then I would think that the resubmission feature should be removed altogether (i.e. no sticky reviews), as it does not work as intended and can lead to frustration for authors.

In this sense, I also agree that “Experiment with Making Findings Decisions in ARR,” which is proposed in the ACL Peer Review Report, could be another good idea to reduce this kind of problem.

言語適応のための語彙拡張では、まず対象言語データで補助トークナイザを学習するのが一般的です。

その際、効果的な語彙拡張のためには、拡張元のトークナイザと同じ(近しい)学習設定を補助トークナイザに適用することが重要です。

しかし、SentencePieceのドキュメントや先行研究の論文には、トークナイザの学習設定をどのように抽出できるかは明確には説明されていません。¹

そこで本記事では、トークナイザの学習設定を抽出し、補助トークナイザに適用する方法を簡単に説明します。

なお、本記事は、Gemma 2の語彙拡張例を元に執筆しました。

SentencePieceモデルの学習設定の抽出

まず、元のトークナイザのモデルファイルを読み込みます。

import sentencepiece as spm
sp_model = spm.SentencePieceProcessor()
sp_model.load(
    "/path/to/models--google--gemma-2-9b/snapshots/33c193028431c2fde6c6e51f29e6f17b60cbfac6/tokenizer.model"
)

なお、上記では拡張元のトークナイザとしてGemma 2のtokenizer.modelを使用することを想定しています。

次に、SentencePieceモデルプロトをロードし、各種パラメタを取得します。²

from sentencepiece import sentencepiece_model_pb2 as sp_pb2_model
spm = sp_pb2_model.ModelProto()
spm.ParseFromString(sp_model.serialized_model_proto())

最後に、以下の手順で学習設定を抽出します。

from google.protobuf.json_format import MessageToDict
training_configs = MessageToDict(spm)['trainerSpec']

ここで、training_configsは、元のトークナイザの学習設定を含む辞書型変数です。

{'modelPrefix': '',
 'modelType': 'BPE',
 'vocabSize': 256000,
 'selfTestSampleSize': 0,
 'inputFormat': '',
 'characterCoverage': 0.0,
 'inputSentenceSize': '0',
 'seedSentencepieceSize': 0,
 'shrinkingFactor': 0.0,
 'numThreads': 0,
 'numSubIterations': 0,
 'maxSentenceLength': 0,
 'shuffleInputSentence': True,
 'maxSentencepieceLength': 16,
 'splitByUnicodeScript': True,
 'splitByWhitespace': True,
 'splitByNumber': True,
 'treatWhitespaceAsSuffix': False,
 'splitDigits': True,
 'allowWhitespaceOnlyPieces': True,
 'userDefinedSymbols': ['<mask>',
  '<2mass>',
  '[@BOS@]',
  ...
  '</sup>',
  '</code>'],
 'vocabularyOutputPieceScore': True,
 'hardVocabLimit': True,
 'useAllVocab': False,
 'byteFallback': True,
 'requiredChars': '',
 'unkId': 3,
 'bosId': 2,
 'eosId': 1,
 'padId': 0,
 'unkSurface': ' ⁇ ',
 'unkPiece': '<unk>',
 'bosPiece': '<bos>',
 'eosPiece': '<eos>',
 'padPiece': '<pad>',
 'trainExtremelyLargeCorpus': True,
 'enableDifferentialPrivacy': False,
 'differentialPrivacyNoiseLevel': 0.0,
 'differentialPrivacyClippingThreshold': '0'}

上記の学習設定を用いることで、先述のGemma 2の語彙拡張例に示したようにGemma 2の補助トークナイザを学習することができます。

まとめ

本記事では、元のトークナイザの学習設定を抽出し、補助トークナイザに適用する方法を簡単に説明しました。参考になれば幸いです。

In vocabulary expansion for target language adaptation, we usually first train an auxiliary tokeniser on target language data. For effective expansion, it is important to use the same training settings as the source tokeniser. However, the SentencePiece documentation and papers do not always clearly explain how to do this. In this post, I briefly describe how to extract the training settings of the source tokeniser and apply them to the auxiliary tokeniser.

This post is based on my script for vocabulary expansion with Gemma 2.

Extracting SentencePiece training settings

To extract the training settings of the source tokeniser, we first load the tokeniser model file as follows:

import sentencepiece as spm
sp_model = spm.SentencePieceProcessor()
sp_model.load(
    "/path/to/models--google--gemma-2-9b/snapshots/33c193028431c2fde6c6e51f29e6f17b60cbfac6/tokenizer.model"
)

Here, we assume that the source tokeniser is from Gemma 2 and we use its tokenizer.model.

Next, we load the SentencePiece model proto, which contains parameters.¹

from sentencepiece import sentencepiece_model_pb2 as sp_pb2_model
spm = sp_pb2_model.ModelProto()
spm.ParseFromString(sp_model.serialized_model_proto())

Finally, we can extract the training settings as follows:

from google.protobuf.json_format import MessageToDict
training_configs = MessageToDict(spm)['trainerSpec']

The training_configs variable is a dictionary that contains the training settings of the source tokeniser (as shown below).

{'modelPrefix': '',
 'modelType': 'BPE',
 'vocabSize': 256000,
 'selfTestSampleSize': 0,
 'inputFormat': '',
 'characterCoverage': 0.0,
 'inputSentenceSize': '0',
 'seedSentencepieceSize': 0,
 'shrinkingFactor': 0.0,
 'numThreads': 0,
 'numSubIterations': 0,
 'maxSentenceLength': 0,
 'shuffleInputSentence': True,
 'maxSentencepieceLength': 16,
 'splitByUnicodeScript': True,
 'splitByWhitespace': True,
 'splitByNumber': True,
 'treatWhitespaceAsSuffix': False,
 'splitDigits': True,
 'allowWhitespaceOnlyPieces': True,
 'userDefinedSymbols': ['<mask>',
  '<2mass>',
  '[@BOS@]',
  ...
  '</sup>',
  '</code>'],
 'vocabularyOutputPieceScore': True,
 'hardVocabLimit': True,
 'useAllVocab': False,
 'byteFallback': True,
 'requiredChars': '',
 'unkId': 3,
 'bosId': 2,
 'eosId': 1,
 'padId': 0,
 'unkSurface': ' ⁇ ',
 'unkPiece': '<unk>',
 'bosPiece': '<bos>',
 'eosPiece': '<eos>',
 'padPiece': '<pad>',
 'trainExtremelyLargeCorpus': True,
 'enableDifferentialPrivacy': False,
 'differentialPrivacyNoiseLevel': 0.0,
 'differentialPrivacyClippingThreshold': '0'}

We can now use these settings to train the auxiliary tokeniser as in my script for vocabulary expansion with Gemma 2.

Conclusion

In this post, I briefly described how to extract the training settings of the source tokeniser and apply them to the auxiliary tokeniser for vocabulary expansion. I hope this helps!

前提

• macOS Apple Silicon (Sonoma 14.7)

手順

以下の3手順で見かけ上のMACアドレスを変更することができます。なお、再起動すると元に戻ります。

1. Wi-Fiをオンにする

$ networksetup -setairportpower en0 on

en0 は自分の環境に合わせて変更してください。

2. MACアドレスを変更する

$ sudo ifconfig en0 ether 00:11:22:33:44:55

00:11:22:33:44:55 に変更先のMACアドレスを指定してください。

3. ネットワークを検出する

$ networksetup -detectnewhardware

参考

• https://support.apple.com/en-gb/guide/remote-desktop/apdd0c5a2d5/mac

Since the advent of LLaMA2, additional training with target language data, i.e. continued pre-training, has been actively used to build an LLM for specific languages. The main effect of vocabulary expansion is to reduce overfragmentation¹, resulting in better inference efficiency.

The idea of vocabulary expansion itself is quite simple, but the way it is implemented depends on how the target tokeniser is implemented. In this post, I share the procedure for expanding the vocabulary of a non-SentencePiece based BPE tokeniser.²

Background

The main difference between SentencePiece-based (e.g. LLaMA2, Mistral) and non-SentencePiece based (e.g. LLaMA3, OLMo) BPE tokenisers is whether they are byte-level or not.

The former, SentencePiece-based BPE, often uses the byte-fallback option, preventing the occurrence of UNK tokens.

On the other hand, recent non-SentencePiece based BPE tokenisers are typically based on byte-level BPE, which converts the input to UTF-8 encoded byte sequences before tokenisation. Since tokenisation is performed on byte sequences, no UNK tokens are generated.³

Therefore, even if the same algorithm is used between the two, the pre- and post-processing of strings is slightly different. This difference can also be seen in the metadata of the transformers tokenisers, specifically the pre_tokenizer and decoder parts.

import json
from transformers import AutoTokenizer

# LLaMA2
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-2-7b-hf")
tokenizer_json = json.loads(tokenizer._tokenizer.to_str())
print(tokenizer_json["pre_tokenizer"])
# None
print(tokenizer_json["decoder"])
# {'type': 'Sequence', 'decoders': [{'type': 'Replace', 'pattern': {'String': '▁'}, 'content': ' '}, {'type': 'ByteFallback'}, {'type': 'Fuse'}, {'type': 'Strip', 'content': ' ', 'start': 1, 'stop': 0}]}

# LLaMA3
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3-8B")
tokenizer_json = json.loads(tokenizer._tokenizer.to_str())
print(tokenizer_json["pre_tokenizer"])
# {'type': 'Sequence', 'pretokenizers': [{'type': 'Split', 'pattern': {'Regex': "(?i:'s|'t|'re|'ve|'m|'ll|'d)|[^\\r\\n\\p{L}\\p{N}]?\\p{L}+|\\p{N}{1,3}| ?[^\\s\\p{L}\\p{N}]+[\\r\\n]*|\\s*[\\r\\n]+|\\s+(?!\\S)|\\s+"}, 'behavior': 'Isolated', 'invert': False}, {'type': 'ByteLevel', 'add_prefix_space': False, 'trim_offsets': True, 'use_regex': False}]}
print(tokenizer_json["decoder"])
# {'type': 'ByteLevel', 'add_prefix_space': True, 'trim_offsets': True, 'use_regex': True}

Implementation

Here, we expand the vocabulary of a source tokeniser tokenizer with the help of an auxiliary tokeniser aux_tokenizer trained on a target language.

We use Greek as an example, where the effect of vocabulary expansion is relatively easy to see.

1. Load tokenisers and their metadata

First, we load the source tokeniser and auxiliary tokeniser, and get the merge rules and vocabulary of the target language.

In the example below, we use LLaMA3 as the source tokeniser and an auxiliary tokeniser trained on the Greek CC-100 subcorpus ($2^{20}$ sentences randomly sampled) with a vocabulary size of 50k tokens. The rest of the training settings are the same as LLaMA3.⁴

import json
import copy

from transformers import AutoTokenizer
from tokenizers.models import BPE

tokenizer = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3-8B")
vocab = tokenizer.get_vocab()
tokenizer_json = json.loads(tokenizer._tokenizer.to_str())
merges = tokenizer_json["model"]["merges"]

aux_tokenizer = AutoTokenizer.from_pretrained("atsuki-yamaguchi/cc100-el-50k")
aux_tokenizer_json = json.loads(aux_tokenizer._tokenizer.to_str())
aux_merges = aux_tokenizer_json["model"]["merges"]

2. Expand vocabulary and merge rules

We then add new target tokens and the corresponding merge rules to the source tokeniser’s vocabulary and merge rule list. Here, we add up to 10k new tokens.⁵

# merge the tokenizers
num_new_token = 0
max_new_token = 10000
ret_vocab = copy.copy(vocab)
ret_merges = []
old_merges = copy.copy(merges)
for merge in aux_merges:
    # vocab
    token_1, token_2 = merge.split(" ")
    token = token_1 + token_2
    if num_new_token < max_new_token:
        if token_1 not in ret_vocab and token_2 not in ret_vocab: # both are new
            ret_vocab[token_1] = len(vocab) + num_new_token
            ret_vocab[token_2] = len(vocab) + num_new_token + 1
            num_new_token += 2
        elif token_1 not in ret_vocab and token_2 in ret_vocab: # new + existing
            ret_vocab[token_1] = len(vocab) + num_new_token
            num_new_token += 1
        elif token_1 in ret_vocab and token_2 not in ret_vocab: # old + existing
            ret_vocab[token_2] = len(vocab) + num_new_token
            num_new_token += 1
        else: # both are existing tokens
            pass
        if token not in ret_vocab:
            ret_vocab[token] = len(vocab) + num_new_token
            num_new_token += 1
    # merge
    if merge in merges:
        old_merges.remove(merge)
        ret_merges.append(merge)
    elif token in ret_vocab and token_1 in ret_vocab and token_2 in ret_vocab:
        ret_merges.append(merge)

3. Retrain BPE tokeniser

We create an instance of the BPE tokeniser with the expanded vocabulary and merge rules, and overwrite the source tokeniser with it.

# retrain tokenizer
merges = ret_merges + old_merges
vocab = ret_vocab
tokenizer.backend_tokenizer.model = BPE(
    vocab=vocab,
    merges=[(merge.split(' ')[0], merge.split(' ')[1]) for merge in merges],
    fuse_unk=False,
)

4. Save the tokeniser

Finally, we save the tokeniser to an output directory.

# save
tokenizer.save_pretrained("/path/to/output/dir")

Efficacy of vocabulary expansion

We measure the number of tokens before and after vocabulary expansion with the following example.

Μου είπαν ότι, θα έπρεπε να καλέσω έναν άντρα στο τέλος για να συναντηθούμε. Ερώτηση: Ο τύπος εμφανίστηκε λίγο αργά. Αληθές, Ψευδές, ή Κανένα από τα δύο; Απάντηση: Κανένα από τα δύο

tokenizer = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3-8B")
modified_tokenizer = AutoTokenizer.from_pretrained("/path/to/output/dir")

text = "Μου είπαν ότι, θα έπρεπε να καλέσω έναν άντρα στο τέλος για να συναντηθούμε. Ερώτηση: Ο τύπος εμφανίστηκε λίγο αργά. Αληθές, Ψευδές, ή Κανένα από τα δύο; Απάντηση: Κανένα από τα δύο"

print(len(tokenizer.encode(text)))
# 81

print(len(modified_tokenizer.encode(text)))
# 46

As a result, the number of tokens was reduced by 35 by adding 10k target tokens to the vocabulary of the LLaMA3 tokeniser.

Summary

There are many examples of vocabulary expansion using SentencePiece-based BPE tokenisers, but I have not come across any practical examples of using non-SentencePiece-based tokenisers for vocabulary expansion. That’s why I decided to write a post about it. I hope this article is of some help.

This blog covers topics related to machine learning and natural language processing.

You can find the list of all articles on the site map (tag list). Note that some articles are written in Japanese and not available in English.

Contact

For inquiries or job requests, please contact me via the contact form or DM on X (formerly Twitter).

Privacy policy and disclaimer

For the disclaimer and privacy policy of this site, please see the Privacy Policy.

LLaMA2の登場以後、特定言語向けの言語モデル構築のため、語彙拡張を伴う英語モデルのターゲット言語のデータによる追加学習が盛んに行われています。

語彙拡張の目的はフラグメンテーション¹の改善にあり、これにより推論効率の改善が見込まれます。

語彙拡張のアイディア自体はシンプルですが、トークナイザの実装方法によってどのように拡張するかは変わってきます。本稿では、非SentencePieceベースのBPEトークナイザを語彙拡張する手順について共有します。（SentencePieceベースのBPEトークナイザを語彙拡張する方法については、SentencePieceのレポジトリ内に説明があります。）

前提

SentencePiece（LLaMA2やMistralなどが使用）と非SentencePieceベース（LLaMA3やOLMoなど）のBPEトークナイザの主な違いとして、byte-levelか否かが挙げられます。

SentencePiece系のBPEはbyte-fallbackオプションが適用されており、UNKトークン（=トークナイズできない）の発生を防いでいます。

他方、近年の非SentencePieceベースのBPEはbyte-level BPEとなっており、入力をUTF-8でエンコードされたバイト列に変換してからトークナイズを行っています。バイト列に対してトークナイズを行うので、UNKトークンは発生しません。²

したがって、同じアルゴリズムであっても、文字列の前処理・後処理が若干異なります。この違いは、実際にtransformersトークナイザのメタデータのうち、pre_tokenizerとdecoder部分からも確認できます。

import json
from transformers import AutoTokenizer

# LLaMA2
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Llama-2-7b-hf")
tokenizer_json = json.loads(tokenizer._tokenizer.to_str())
print(tokenizer_json["pre_tokenizer"])
# None
print(tokenizer_json["decoder"])
# {'type': 'Sequence', 'decoders': [{'type': 'Replace', 'pattern': {'String': '▁'}, 'content': ' '}, {'type': 'ByteFallback'}, {'type': 'Fuse'}, {'type': 'Strip', 'content': ' ', 'start': 1, 'stop': 0}]}

# LLaMA3
tokenizer = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3-8B")
tokenizer_json = json.loads(tokenizer._tokenizer.to_str())
print(tokenizer_json["pre_tokenizer"])
# {'type': 'Sequence', 'pretokenizers': [{'type': 'Split', 'pattern': {'Regex': "(?i:'s|'t|'re|'ve|'m|'ll|'d)|[^\\r\\n\\p{L}\\p{N}]?\\p{L}+|\\p{N}{1,3}| ?[^\\s\\p{L}\\p{N}]+[\\r\\n]*|\\s*[\\r\\n]+|\\s+(?!\\S)|\\s+"}, 'behavior': 'Isolated', 'invert': False}, {'type': 'ByteLevel', 'add_prefix_space': False, 'trim_offsets': True, 'use_regex': False}]}
print(tokenizer_json["decoder"])
# {'type': 'ByteLevel', 'add_prefix_space': True, 'trim_offsets': True, 'use_regex': True}

実装

はじめに、拡張元のトークナイザtokenizerとターゲットとなる言語で学習された補助のトークナイザaux_tokenizerを用意しておきます。

ここでは、比較的語彙拡張の効果が見られやすいギリシャ語を例に取ります。

1. 読み込み

拡張元のトークナイザとターゲット言語の補助トークナイザを読み込み、マージルールや語彙の辞書を取得します。

以下の例では、LLaMA3を拡張元のトークナイザとしています。 補助のトークナイザは、語彙サイズを5万トークンとし、ギリシャ語のCC-100コーパスから無作為に$2^{20}$文を抽出したデータセットで学習させたものです。それ以外の学習設定はLLaMA3に準じています。³

import json
import copy

from transformers import AutoTokenizer
from tokenizers.models import BPE

tokenizer = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3-8B")
vocab = tokenizer.get_vocab()
tokenizer_json = json.loads(tokenizer._tokenizer.to_str())
merges = tokenizer_json["model"]["merges"]

aux_tokenizer = AutoTokenizer.from_pretrained("atsuki-yamaguchi/cc100-el-50k")
aux_tokenizer_json = json.loads(aux_tokenizer._tokenizer.to_str())
aux_merges = aux_tokenizer_json["model"]["merges"]

2. 語彙とマージルールの追加

拡張元のトークナイザの語彙の辞書とマージルールのリストに、語彙と対応するマージルールを追加します。ここでは、1万個の新規語彙を最大値として追加します。⁴

# merge the tokenizers
num_new_token = 0
max_new_token = 10000
ret_vocab = copy.copy(vocab)
ret_merges = []
old_merges = copy.copy(merges)
for merge in aux_merges:
    # vocab
    token_1, token_2 = merge.split(" ")
    token = token_1 + token_2
    if num_new_token < max_new_token:
        if token_1 not in ret_vocab and token_2 not in ret_vocab: # both are new
            ret_vocab[token_1] = len(vocab) + num_new_token
            ret_vocab[token_2] = len(vocab) + num_new_token + 1
            num_new_token += 2
        elif token_1 not in ret_vocab and token_2 in ret_vocab: # new + existing
            ret_vocab[token_1] = len(vocab) + num_new_token
            num_new_token += 1
        elif token_1 in ret_vocab and token_2 not in ret_vocab: # old + existing
            ret_vocab[token_2] = len(vocab) + num_new_token
            num_new_token += 1
        else: # both are existing tokens
            pass
        if token not in ret_vocab:
            ret_vocab[token] = len(vocab) + num_new_token
            num_new_token += 1
    # merge
    if merge in merges:
        old_merges.remove(merge)
        ret_merges.append(merge)
    elif token in ret_vocab and token_1 in ret_vocab and token_2 in ret_vocab:
        ret_merges.append(merge)

3. トークナイザの再学習

拡張した語彙とマージルールを基に、BPEトークナイザのインスタンスを作成し、上書きします。

# retrain tokenizer
merges = ret_merges + old_merges
vocab = ret_vocab
tokenizer.backend_tokenizer.model = BPE(
    vocab=vocab,
    merges=[(merge.split(' ')[0], merge.split(' ')[1]) for merge in merges],
    fuse_unk=False,
)

4. 保存

最後に上書きしたトークナイザを保存して完了です。

# save
tokenizer.save_pretrained("/path/to/output/dir")

効果

下記の例文が語彙拡張前後のトークナイザで何トークンになるかを計測します。

Μου είπαν ότι, θα έπρεπε να καλέσω έναν άντρα στο τέλος για να συναντηθούμε. Ερώτηση: Ο τύπος εμφανίστηκε λίγο αργά. Αληθές, Ψευδές, ή Κανένα από τα δύο; Απάντηση: Κανένα από τα δύο

tokenizer = AutoTokenizer.from_pretrained("meta-llama/Meta-Llama-3-8B")
modified_tokenizer = AutoTokenizer.from_pretrained("/path/to/output/dir")

text = "Μου είπαν ότι, θα έπρεπε να καλέσω έναν άντρα στο τέλος για να συναντηθούμε. Ερώτηση: Ο τύπος εμφανίστηκε λίγο αργά. Αληθές, Ψευδές, ή Κανένα από τα δύο; Απάντηση: Κανένα από τα δύο"

print(len(tokenizer.encode(text)))
# 81

print(len(modified_tokenizer.encode(text)))
# 46

結果として1万トークンをLLaMA3トークナイザに新規に追加することで、35トークン減少しました。

おわりに

SentencePieceベースのBPEトークナイザの語彙拡張の例はたくさん見かけますが、それ以外の実践例をあまり見かけたことがなかったので今回の記事作成に至りました。 何かの役に立てば幸いです。

VS Code release 1.86 から最低システム要件が変更になった影響で、非対応となったOS（例：CentOS 7、Ubuntu 18.04）を搭載しているサーバへの接続が不可になりました。とはいえ、システム管理者でもない限り接続先サーバのアップデートは困難なので、クライアント側での対処手順を備忘録程度にまとめておきます。

前提

• macOS Apple Silicon

手順

1. VS Code 1.85 のダウンロード

Apple Siliconなら以下からダウンロードできます。

VSCode-darwin-arm64.zip

2. 適当な場所で解凍

私は $HOME/Applications 以下に配置しました。

3. Portable Mode の有効化

現行の環境と共存させるための作業を行います。

1. Visual Studio Code.app が配置されているディレクトリに code-portable-data を作成

   cd $HOME/Applications
   mkdir code-portable-data
   

2. アプリの検疫状態を解除

   xattr -dr com.apple.quarantine Visual\ Studio\ Code.app
   

3. アプリ起動後、左下歯車⚙️アイコンをクリック→検索欄に”update”と入力

4. アップデート関連の項目を軒並みオフに設定

4. Remote SSH をインストール

空っぽの状態なので、再びRemote SSHをインストール & その他環境を整えて完了です。

参考

• VS Code Remote Development FAQ
• VS Code Portable Mode
• GitHub 関連Issue