2024-04-07

Hydra を使ってみる

はじめに

今回は Hydra を使った設定管理について調べてみました！

Hydra というのは Meta が開発している python のフレームワークの一つであり、主に設定ファイルの管理に長けているものです。

github.com

この記事では、いくつかの基本的はシチュエーションにおける Hydra をみていきたいと思っています 🐲 🐲 🐲

1. yaml で設定管理したい

こちらの記事にあるように、argparse を使いプログラム実行時の引数を受け取る方法はよく使われていると思います。しかし、設定するパラメータ数が多いときなどには苦しさを感じることも多々あります。

以下の例で、特に設定数は多くないですが hydra を使ってみようと思います! hugguingface trainer を用いた fine-tuning のサンプルコードを参考にして例を作成しています。

import argparse

import transformers
from datasets import load_dataset
from transformers import AutoModelForSequenceClassification, AutoTokenizer


def main():
    parser = argparse.ArgumentParser(description="huggungface transformers training")

    # transformers
    parser.add_argument("--model_name", type=str, default="bert-base-uncased")
    parser.add_argument("--num_labels", type=int, default=2)
    parser.add_argument("--per_device_train_batch_size", type=int, default=8)
    parser.add_argument("--per_device_eval_batch_size", type=int, default=8)
    parser.add_argument("--evaluation_strategy", type=str, default="epoch")
    parser.add_argument("--num_epochs", type=int, default=3)
    parser.add_argument("--learning_rate", type=float, default=5e-5)
    parser.add_argument("--warmup_ratio", type=float, default=0.1)
    parser.add_argument("--gradient_accumulation_steps", type=int, default=1)
    parser.add_argument("--eval_accumulation_steps", type=int, default=1)
    parser.add_argument("--weight_decay", type=float, default=0.01)
    parser.add_argument("--save_strategy", type=str, default="epoch")
    parser.add_argument("--fp16", type=bool, default=False)
    # paths
    parser.add_argument("--logging_dir", type=str, default="logs")
    parser.add_argument("--output_dir", type=str, default="output")

    args = parser.parse_args()

    # model, tokenizer のロード
    tokenizer = AutoTokenizer.from_pretrained(args.model_name)
    model = AutoModelForSequenceClassification.from_pretrained(
        args.model_name, num_labels=args.num_labels
    )

    # example データセットのロード
    raw_datasets = load_dataset("glue", "mrpc")

    def tokenize_function(example):
        return tokenizer(example["sentence1"], example["sentence2"], truncation=True)

    tokenized_datasets = raw_datasets.map(tokenize_function, batched=True)

    # トレーニングの設定
    training_args = transformers.TrainingArguments(
        output_dir=args.output_dir,
        per_device_train_batch_size=args.per_device_train_batch_size,
        per_device_eval_batch_size=args.per_device_eval_batch_size,
        evaluation_strategy=args.evaluation_strategy,
        logging_dir=args.logging_dir,
        num_train_epochs=args.num_epochs,
        learning_rate=args.learning_rate,
        warmup_ratio=args.warmup_ratio,
        gradient_accumulation_steps=args.gradient_accumulation_steps,
        eval_accumulation_steps=args.eval_accumulation_steps,
        weight_decay=args.weight_decay,
        save_strategy=args.save_strategy,
        fp16=args.fp16,
    )

    trainer = transformers.Trainer(
        model,
        training_args,
        train_dataset=tokenized_datasets["train"],
        eval_dataset=tokenized_datasets["validation"],
        tokenizer=tokenizer,
    )
    trainer.train()


if __name__ == "__main__":
    main()

デフォルト値は設定していますが、全引数を設定すると以下のようになります。

rye run  python src/main_argparse.py --model_name bert-base-uncased --num_labels 2 --per_device_train_batch_size 8 --per_device_eval_batch_size 8 --evaluation_strategy epoch --num_epochs 3 --learning_rate 5e-5 --warmup_ratio 0.1 --gradient_accumulation_steps 1 --eval_accumulation_steps 1 --weight_decay 0.01 --save_strategy epoch --fp16 False --logging_dir logs --output_dir output

上記のような設定を yaml ファイルに書き、hydraを使うことで argparse から脱却することができます。また、設定ファイル自体に階層構造を持たせる、つまりグループ化することで、よりわかりやすく管理しやすい形で設定ファイルを扱うことができます。

今回は configs ディレクトリを作成し、さらにその中に paths と transformers を作り、それぞれに対応する設定ファイルを作ろうと思います。

├── configs
│   ├── config.yaml
│   ├── paths
│   │   └── default.yaml
│   └── transformers
│       └── default.yaml
└── src
    ├── __init__.py
    └── main_hydra.py

default.yaml には対応するディレクトリ名に関するデフォルト値を記載し、config.yaml は、それぞれの設定ファイルをまとめる役割を持っています。

model_name: bert-base-uncased
num_labels: 2
per_device_train_batch_size: 8
per_device_eval_batch_size: 8
evaluation_strategy: epoch
num_epochs: 3
learning_rate: 2e-5
warmup_ratio: 0
gradient_accumulation_steps: 1
eval_accumulation_steps: 1
weight_decay: 0.01
save_strategy: epoch
fp16: False

logging_dir: logs
output_dir: output

defaults:
  - paths: default
  - transformers: default
  - _self_

defaults: に関しては公式ドキュメントを参照ください。ディレクトリ名:設定ファイル名 という形式で設定を読み込み、指定した設定を使用できるようにします。

また config.yaml 自体にも paths や transformers の設定以外の設定などを書くことができます。- _self_ は、config.yaml 自身の設定を明示的に表しているものに過ぎません。

ただ、同じ設定が存在する場合はリストのより後のものが優先されます。今回の場合だと _self_ が最優先ということになります。

実行対象のファイルは以下のようになります。 main() に対して @hydra.main デコレータの追加があります。最終的に使う設定ファイルと、その設定ファイルが存在するディレクトリのパスをここで指定することで、その設定が使えるようになります。

import hydra
import transformers
from datasets import load_dataset
from omegaconf import DictConfig
from transformers import AutoModelForSequenceClassification, AutoTokenizer


@hydra.main(config_path="../configs", config_name="config", version_base="1.3")
def main(cfg: DictConfig):
    # model, tokenizer のロード
    tokenizer = AutoTokenizer.from_pretrained(cfg.transformers.model_name)
    model = AutoModelForSequenceClassification.from_pretrained(
        cfg.transformers.model_name, num_labels=cfg.transformers.num_labels
    )

    # example データセットのロード
    raw_datasets = load_dataset("glue", "mrpc")

    def tokenize_function(example):
        return tokenizer(example["sentence1"], example["sentence2"], truncation=True)

    tokenized_datasets = raw_datasets.map(tokenize_function, batched=True)

    # トレーニングの設定
    training_args = transformers.TrainingArguments(
        output_dir=cfg.paths.output_dir,
        per_device_train_batch_size=cfg.transformers.per_device_train_batch_size,
        per_device_eval_batch_size=cfg.transformers.per_device_eval_batch_size,
        evaluation_strategy=cfg.transformers.evaluation_strategy,
        logging_dir=cfg.paths.logging_dir,
        num_train_epochs=cfg.transformers.num_epochs,
        learning_rate=cfg.transformers.learning_rate,
        warmup_ratio=cfg.transformers.warmup_ratio,
        gradient_accumulation_steps=cfg.transformers.gradient_accumulation_steps,
        eval_accumulation_steps=cfg.transformers.eval_accumulation_steps,
        weight_decay=cfg.transformers.weight_decay,
        save_strategy=cfg.transformers.save_strategy,
        fp16=cfg.transformers.fp16,
    )

    trainer = transformers.Trainer(
        model,
        training_args,
        train_dataset=tokenized_datasets["train"],
        eval_dataset=tokenized_datasets["validation"],
        tokenizer=tokenizer,
    )
    trainer.train()


if __name__ == "__main__":
    main()

cfg.transformers.model_name や cfg.paths.output_dir のように ディレクトリ名.パラメタ名 という感じでアクセスできます。

引数をつけずに実行すると、もちろん yaml ファイルに書いた通りの設定で実行されます。

引数設定の例は以下です。

python src/main_hydra.py transformers.fp16=true

また、実行時にはデフォルトで outputs フォルダが作成されます。この中には log ファイルや、実行時のすべての hydra の設定ファイルが実行日/実行時間のフォルダに保存されます。

2. クラス単位で設定したい

設定パラメタを受け取り、あるクラスや関数の引数として使用する場合、なんとなく冗長な気がします。また、パラメタの値によって対象のクラス・関数を変更したい時、いちいち対象のクラス・関数を import し条件文で分岐を作るなども少しダルイ感じがあります。

hydra には Instantiating というシステムがあり、これが前述の問題を解決してくれます。

これを使うことで最終的な main.py は以下のようになります。

import hydra
from datasets import load_dataset
from omegaconf import DictConfig


@hydra.main(config_path="../configs", config_name="config", version_base="1.3")
def main(cfg: DictConfig):
    # model, tokenizer のロード
    model = hydra.utils.get_method(cfg.transformers.model)(
        cfg.transformers.model_name,
        num_labels=cfg.transformers.num_labels,
    )
    tokenizer = hydra.utils.get_method(cfg.transformers.tokenizer)(cfg.transformers.model_name)

    # example データセットのロード
    raw_datasets = load_dataset("glue", "mrpc")

    def tokenize_function(example):
        return tokenizer(example["sentence1"], example["sentence2"], truncation=True)

    tokenized_datasets = raw_datasets.map(tokenize_function, batched=True)
    trainer = hydra.utils.instantiate(
        cfg.transformers.trainer,
        model=model,
        train_dataset=tokenized_datasets["train"],
        eval_dataset=tokenized_datasets["validation"],
        tokenizer=tokenizer,
    )
    trainer.train()


if __name__ == "__main__":
    main()

注目すべきは trainer = hydra.utils.instantiate( こちらですね。configs/transformers/default.yaml にある trainer を instantiate しています。

さらには model や tokenizer さえも yaml で設定できます。今回は AutoTokenizer などの Auto 系のクラスがあるのでいいですが、特定のクラスを使うときなどには get_method や get_class が使えます。

configs/transformers/default.yaml はこんな感じです。

model_name: bert-base-uncased
num_labels: 2

model: transformers.AutoModelForSequenceClassification.from_pretrained
tokenizer: transformers.AutoTokenizer.from_pretrained

trainer:
  _target_: transformers.Trainer
  args:
    _target_: transformers.TrainingArguments
    output_dir: ${paths.output_dir}
    logging_dir: ${paths.logging_dir}
    per_device_train_batch_size: 8
    per_device_eval_batch_size: 8
    evaluation_strategy: epoch
    num_train_epochs: 3
    learning_rate: 2e-5
    warmup_ratio: 0
    gradient_accumulation_steps: 1
    eval_accumulation_steps: 1
    weight_decay: 0.01
    save_strategy: epoch
    fp16: False

_target_ に instantiate 対象へのパスを書き、その下に引数を書くことができます。ここにすべての引数を書かずとも前述のように

 trainer = hydra.utils.instantiate(
        cfg.transformers.trainer,
        model=model,
        train_dataset=tokenized_datasets["train"],
        eval_dataset=tokenized_datasets["validation"],
        tokenizer=tokenizer,
    )

インスタンス化のタイミングで追加で引数を設定できます。また、functools.partial と同様のものも作成することができます。(参考)

hydra.utils.get_class や hydra.utils.get_method を使うことで、クラスやそのメソッド、関数そのものを呼び出すことができます。

3. 設定をカスタマイズしたい

bert 系のモデルを使う時など、large モデルを使うときはマシンの関係上バッチサイズも小さく、さらに学習率も小さくしたいなど、対象のモデルに応じて各設定のデフォルトを変更したい場合があります。もちろんコマンドライン上で transformers.model_name=roberta-large transformers.trainer.args.learning_rate=1e-5 などのように override することもできますが、設定ファイルとして残したい気持ちもあります。

├── configs
│   ├── config.yaml
│   ├── paths
│   │   └── default.yaml
│   └── transformers
│       |── default.yaml
|       |── roberta-base.yaml
|       └── roberta-large.yaml
└── src
    ├── __init__.py
    └── main.py

このように roberta-base.yaml と roberta-large.yaml の設定ファイルを追加してみます。

defaults:
  - default

model_name: roberta-base

defaults:
  - default

model_name: roberta-large

trainer:
  args:
    num_train_epochs: 2
    learning_rate: 1e-5
    gradient_accumulation_steps: 4

defaults: - default は、同じ階層の default.yaml を overriede するために追加します。それぞれの設定ファイルからみて取れるように、変更点 (override 対象) 以外は、 defaults で指定した値のパラメタが適用されます。この場合だと defaults.yaml がそれですね。

こうすることで、変更箇所以外の余計な設定を省略しつつ設定を行うことができました。

次にこの設定を適用する方法についてです。

configs/config.yaml を書き換える
実行時のコマンドライン引数で指定する

1 については、以下のように config.yaml を修正します。default だった部分を roberta-large にしただけです。

defaults:
  - paths: default
  - transformers: roberta-large
  - _self_

2 については以下のコマンドライン引数を使います。transformers の設定を変更した感じです。

python run src/main.py transformers=roberta-large

話はずれますが、hydra ではデフォルトの値を設定せず、コマンドライン引数として必ず設定するパラメタは ??? と書くことができます。??? に当たる部分が未指定だとエラーが発生します。

defaults:
  - paths: default
  - transformers: ???
  - _self_

例えば上のように書けば、python run src/main.py transformers= をコマンドラインから指定する必要があります (コマンドライン以外からも指定する方法はあります)。

4. その他

環境変数を使う

こちらの記事が参考になります。

root_dir: ${oc.env:PROJECT_ROOT}
output_dir: ${hydra:runtime.output_dir}
work_dir: ${hydra:runtime.cwd}

環境変数以外にも、実行時のログ保存ディレクトリなどの hydra 特有のパスにもアクセスできます。もちろん変更も可能なので、例えば指定した引数と同じ名前の出力ディレクトリを作ることなども可能です。

hydra.cc

omegaconf.readthedocs.io

notebook で使う

with hydra.initialize(version_base=1.3, config_path="../configs"):
    CFG = hydra.compose(
        config_name="config.yaml",
        return_hydra_config=True,
        overrides=OVERRIDES,
    )
    # use HydraConfig for notebook to use hydra job
    HydraConfig.instance().set_config(CFG)

OVERRIDES には transformers=default などのようにコマンドライン引数での設定に相当する部分を書けば OK です。

multirun

今回は特に触れてなかったですが、hydra の目玉機能の一つです。

hydra.cc

複数の異なる設定で実行する場合に使います。例えば、学習率を変えた実験を行いたい場合などですね。直列での実行になりますが、Launcher を変更することで並列の実行を可能にします。

おわりに

hydra を使った設定管理について、よく使うシチュエーションと実際のコードを作ってみました。この記事に書いた使い方以外にもまだまだ色々なことができそうですし、やりたいことはほぼできると使ってみて感じました。

公式 github にもある Hydra Ecosystem なんかも参考になりそうです。

今回使用したコードはこちらにあります。

github.com

2023-10-04

GCE インスタンス内のコンテナで Git を使う

はじめに

こちらの記事で GCP を使い GPU つきのインスタンスを作り、その中で vecode の Dev Container を使い環境を整えました。今回は、こちらで作ったコンテナの中で Git を使いコード管理をし、GitHub と連携できるようにしたいと思います。

インスタンス内やコンテナ内で SSH 鍵を作ることはせず、ローカルのPCで鍵を作成し、それを使うようにしたいと思います。

SSH鍵の作成

適当な鍵を適当な場所に作ります。こちらの記事などが参考になります。

qiita.com

ssh-keygen -t ed25519

今回はこちらのコマンドで鍵を作成しました。

SSHでインスタンスに接続する

こちらの記事が参考になります。記事に倣って進めてみましょう！

zenn.dev

まず鍵を登録してみます。筆者は Mac を使っているので以下のコマンドを実行しました。

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

今回はこの SSH 鍵を GitHub と GCE それぞれの ssh-key としたいと思います。GCE についてはこちらの記事の通り公開鍵を指定します。GitHub に関しては、先ほどのこちらの記事にもありますので参考にしてください。*1

次に config ファイルを修正します。~/.ssh/config の変更箇所として、ForwardAgent を設定しています。*2

Host {適当な名前: instance-1など}
    Hostname {外部IPアドレス}
    User {SSH鍵のユーザー名}
    ForwardAgent yes

インスタンスの中に入って、ssh -T git@github.com で GitHub との接続確認をしてみます。

Hi (account名)! You've successfully authenticated, but GitHub does not provide shell access.

無事接続できてますね 🎉

リポジトリを clone する

インスタンスの中で GitHub と接続できたので、こちらのリポジトリを SSH でクローンしてみます。

github.com

git clone git@github.com:osushinekotan/gcp-pytorch-project.git

/gcp-pytorch-project が作られたので、docker をインストールをしたのち Dev Container を起動しコンテナに入ってみます。

cd gcp-pytorch-project
sh gcp/install_docker.sh

docker のインストールが終われば Reopen in Container などでコンテナに入ることができます。コンテナ内で再度 GitHub との接続を確認してみます。

ssh -T git@github.com

Hi (account名)! You've successfully authenticated, but GitHub does not provide shell access.

完璧ですね 🙌

コンテナ内の変更を GitHub に push する

コンテナないで Git を使うことができ、さらに GitHub との接続も確認することができました。最後に vscode で Manage Unsafe Repositories をポチッとしましょう。

user name と email を設定し、てきとうなファイルを作成して push までしてみます。

git config --global user.email "you@example.com"
git config --global user.name "Your Name"

touch test_push.txt
git add test_push.txt
git commit -m "test"
git push origin main

見事 push に成功しました 🚀

ここでは、コンテナ内で git のタブ候補を使えるように設定していないかつ個人的に好きというのもあり、私はよく vscode の GUI でポチポチして git 操作をしています。もちろんGUI操作でも問題なく push まですることができます。

おわりに

前回の記事に引き続き環境構築についてでした。インスタンス内でのコードの変更と管理に Git / GitHub を使うことで、ローカルや別の環境と同期をはかることができます。

環境構築には Dev Container を使い、コードは Git / GitHub で管理することで複数のマシンや複数人での開発や実験における差異を減らすことができるのではないでしょうか。 *3

*1:GitHubとGCEで同じ鍵を使い回しています。これは推奨される方法ではないと思いますが、便宜上このようにしています

*2:--apple-load-keychain を使うのと同じらしい

*3:今回使用した ssh-agent まわりについてはころんびあ (@colum2131) / X さんに教えていただきました。ありがとうございました!

2023-10-01

Google Cloud (GCP) を使った kaggle の環境構築メモ

はじめに

GCE (Google Compute Engine) で kaggle 用の環境構築をしたいと思い、自分なりの環境構築をしてみました。その際にいくつかハードルがあったので備忘録としてこの記事を書きました。 kaggle 用とありますが、kaggle docker image などは特に使わずなので、その辺りは目的・用途に合わせて適当に変更ください。

今回は以下のようなイメージの環境を作りたいと思っています。

instance 内で vscode の devcontainer を使って環境を作る
poetry を使う
pytorch を GPU で動かす
kaggle からのデータのロードとデータセットのアップロードは kaggle api を使う
学習済みモデルやその他データは全て GCS (google cloud storage) におく

インスタンスの作成

最初にインスタンスの作成をします。今回はGPUを使いたいので、事前に「GPUの割り当て申請」を行う必要があります。こちらの記事などが参考になるかと思います。 zenn.dev

1. GCP に入り、 Compute Engine から インスタンスの作成 を実行する

インスタンス名は適当に変更して下さい。ここではデフォルトの instance-1 が設定されています。また今回は asia-northeast1-a に NVIDIA T4 マシンをスポットで借りました。スポットの方がお財布に優しいですしね。

2. ブートディスクの選択

Deep Learning VM with CUDA 11.8 を選択しました。nvidia driver などの GPU使用時に必要なものが全て入っているので、手間が省けて楽です。使いたい pytorch が必要としている cuda のバージョンを確認から選択するのが吉です。私は pytorch=2.0.0 を使っているので、こちらを選択しています。サイズはデフォルト 50GB ですが、dirver などが入るとすぐパンパンになるので余裕を持たせて 100GB にしました。

3. API とファイアウォールの設定

めんどくさいのでとりあえず全許可でいきます。。必須なのは Storage へのフルアクセス権なのでそれ以外はよしなに設定下さい。

4. 詳細設定

詳細設定はネットワークインターフェースとセキュリティ部分だけ設定します。ネットワークインターフェースは外部 IPv4 アドレスを エフェメラル (インスタンスを立ち上げるごとに値が変わる) に設定します。静的IPアドレスを予約することで値が変わることはなくなりますが、以下の点からここではエフェメラルに設定しました。

お金がかかる
静的IPアドレスを設定すると kaggle api が使えない

二点目に関して、kaggle api でのアクセス時にエラーが発生してしまいます。どうにかすればなんとかできそうですが、お金もかかるということもあり静的 IP は不採用としました。

今回はローカルのPCから SSH 接続でインスタンスにアクセスするので、ここで SSH 公開鍵を設定します。プロジェクト全体の SSH 認証鍵 でも問題なく接続できるようなのですが、当時の私の設定方法が悪かったのか失敗したので、ここで鍵を設定しています。(今ならできるのかな？)

SSH でインスタンスに接続する

インスタンスを作成し開始すると、以下のようになります。緑のチェックマークが起動中のサインですね。起動中は課金が発生するので、停止忘れには注意が必要です。

vscode からこのインスタンに接続しますが、vscode に Dev Containers (ms-vscode-remote.remote-containers) と Remote SSH (ms-vscode-remote.remote-ssh) の拡張機能を入れておく必要があります (Dev Containers を入れれば Remote SSH もついてくる?) また、~/.ssh/config に設定を書いておきましょう。なければ作成して下さい。

Host {適当な名前: instance-1など}
    Hostname {外部IPアドレス}
    User {SSH鍵のユーザー名}
    IdentityFile {秘密鍵の場所: ~/.ssh/id_ed25519 など}

記載する内容 (Hostname や User ) は GCP のコンソールに書いてあると思います。 config ファイルを書いて保存し、vscode を開くと以下のようにアクセスできる形になっています。

ただ初回接続時には nvidia-driver をインストールするかどうか聞かれるためか何故か vs code からだとうまく行きませんでした。ターミナルから ssh instance-1 で接続し、nvidia-driver のインストールを実行できます。

Would you like to install the Nvidia driver? [y/n] y

インストール完了後 nvida-smi を実行すると無事GPUを認識できます。また、sudo /opt/deeplearning/install-driver.sh で再インストールも可能です。あとは、docker compose を使えるように公式サイトの手順通りにインストールします。コピペ＆コピペでOKです。 docs.docker.com

Dev Container で環境構築

インスタンスに無事入ることができたので、dev container で環境を作ります。 dev container についてはこちらの記事などが参考になります。

blog.kinto-technologies.com

1. Dockerfile と compose.yml の作成

まず Dockerfile ですが、今回はとても簡単に以下のようにしました。python は 3.11 を、 poetry は 1.6 を指定しているだけです。

FROM python:3.11

WORKDIR /workspace

RUN pip install poetry==1.6.0

compose.yml はこちらです。

version: "3"
services:
  workspace:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - .:/workspace
      - /workspace/.venv
    ports:
      - 8888:8888
    tty: true
    environment: 
      - NVIDIA_VISIBLE_DEVICES=all
      - NVIDIA_DRIVER_CAPABILITIES=all
    deploy:
      resources:
        reservations:
          devices:
          - driver: nvidia
            capabilities: [gpu]

deply で GPUをコンテナ内で認識するようにしています。この辺りの書き方には特に自信がないため参考程度に見て下さい。

devcontainer.json の作成

次に devcontainer.json を作ります。これは devcontainer として vscode の拡張機能などを含めた環境を作るための設計図となるものですね。 devcontainer/devcontainer.json を作り、中身を記述してみましょう。

{
  "name": "gcp_pytorch_project",
  "dockerComposeFile": ["../compose.yml"], 
  "service": "workspace",
  "workspaceFolder": "/workspace",
  "runServices": ["workspace"],
  "containerEnv": {
    "TZ": "Asia/Tokyo"
  }
}

実際には、使いたい拡張機能やフォーマッターの設定などを全てここに書くことができます。ここを書かないと devcontainer を使う意味がだいぶ薄れちゃいますが、今回は長くなるのでシンプルにこれだけ書いています。書き方や内容に関してはこちらが参考になります。

tech.isid.co.jp

GCS をマウントする

さて、今回作成したい環境の要件として 学習済みモデルやその他データは全て GCS (google cloud storage) におく というものがありました。これを簡単に実現するために GCSFUSE を使って GCS のバケットをマウントし、ストレスなくモデルやデータの保存をしたいです。

実行するスクリプトは以下のような感じです。

MOUNT_DIR="./data"
PROJECT_ID=YOUR_PROJECT_ID
BUCKET_NAME="gcp-pytorch-project"

gcloud config set project $PROJECT_ID
gcloud auth login

# バケットがなければ「作成する
if ! gsutil ls gs://$BUCKET_NAME; then
  gcloud storage buckets create gs://$BUCKET_NAME --location=us-central1
fi

# install gcsfuse 
export GCSFUSE_REPO=gcsfuse-`lsb_release -c -s`
echo "deb http://packages.cloud.google.com/apt $GCSFUSE_REPO main" | sudo tee /etc/apt/sources.list.d/gcsfuse.list
curl https://packages.cloud.google.com/apt/doc/apt-key.gpg | sudo apt-key add -
sudo apt-get update
sudo apt-get install -y fuse gcsfuse

sudo gcsfuse -o allow_other -file-mode=777 -dir-mode=777 $BUCKET_NAME $MOUNT_DIR

MOUNT_DIR , PROJECT_ID, BUCKET_NAME をそれぞれ指定する必要があります。MOUNT_DIR は適当なディレクトリを作成し、そのパスを指定すればOKです。今回は gcp-pytorch-project バケットをインスタンス上の ./data にマウントします。マウントを解除したい場合は sudo fusermount -u {mountpoint: ここでは data} でできます。

マウントした data フォルダを devcontainer でさらにマウントすることで、生成物を GCS に保存するようにします。

コンテナに入る

前準備は終わったので、ついにコンテナに入って作業してみましょう！コマンドパレットから Dev Containers: Reopen in Container などを使うとコンテナに入ることができます。devcontainer.json に書いた内容 (拡張機能や formatter などの設定) が反映された環境がすでに出来上がっています。私の場合、python の black や ruff などの設定が時々範囲されないのでリロードする場合がありました。

GPUの確認と poetry コマンドの使用が確認できたら pytorch をインストールして GPU を認識できるかみてみます。

poetry init 
poetry add torch=">=2.0.0, !=2.0.1"

ここで torch=">=2.0.0, !=2.0.1" このように指定している理由はこちらですが、正直深く考えず使っちゃっています。。

>>> import torch
>>> torch.cuda.is_available()
True

良さそうですね！🙌

kaggle api でデータをダウンロードする

最後に kaggle api を使って何かデータをダウンロードしてみましょう。マウントが成功していれば、ダウンロードしたデータはインスタンスのディスクではなく GCS に保存されるはずです。まず kaggle をインストールし、認証情報の設定をします。その後 titanic のデータをダウンロードし保存してみます。

poetry add kaggle

kaggle api の使い方に関してはこちらの記事などが参考になるかと思います。

atmarkit.itmedia.co.jp

www.kaggle.com

認証情報は kaggle.json として保存し使うこともできますが、実は環境変数として使うこともできます。KAGGLE_USERNAME と KAGGLE_KEY をそれぞれ設定すればOKです。

from kaggle import KaggleApi

client = KaggleApi()
client.authenticate()
client.competition_download_files(
    competition="titanic",
    path="./data",
    quiet=False,
)

こちらのコードを実行すると、GCS の指定したバケットにデータが保存されます。

おわりに

以上で作りたい環境を作れました！Dockerfile や devcontainer などをカスタムしてオリジナルの設定を反映した環境を作ることももちろん可能です。devcontainer を使うことで複数のインスタンスで同じ環境を簡単に作り、GCSにデータをおくことで共有も簡単にすることができるようになったと思います。

今回使用したコードはこちらにあります

github.com

2023-09-29

HuMob Challenge 2023 に参加しました！

HuMob Challenge 2023 とは

The Human Mobility Prediction Challenge (HuMob Challenge) 2023 is a competition aiming at testing state-of-the-art computational models for the prediction of human mobility patterns, using an open source, urban scale (100K individuals), longitudinal (90 days) trajectory dataset.

HuMob Challenge 2023 は SIGSPATIAL という国際学会のワークショップの一環として行われたコンペティションです。

2023年7月10日から 2023年9月15日の約2ヶ月間開催されました。上位TOP10 の参加者は 2023年11月にドイツで開催予定の SIGSPATIAL のワークショップに招待され解法等を発表し、TOP3 には何やらPRIZEも用意されているようです。

コンペティション詳細についてはこちらを参照ください。

コンペ概要

このコンペティションのタスクはいわゆる「Next Place Prediction」と呼ばれるものです。ある人物がある時点においてどこにいるかを予測するものですね。

また、今回のコンペティションでは task1 と task2 の2種類のデータセットが与えられます。それぞれ平常時とコロナ禍における緊急事態時のもので、それぞれの期間における Next Place Prediction の精度で最終的な評価が行われます。

中間評価はあるもののリーダボードは存在せず、最終評価は 1submission で結果が決まるコンペティションでした。

データ

使用するデータについて簡単に説明します。データセットの詳細についてはこちらを参照ください。

日本のとある中規模都市において、ある期間の複数の人物の移動が 500m x 500m のメッシュかつ 30分単位で記録されています。具体的には以下のようなテーブルを想定できます。

user ID	day	timeslot	x	y
1	1	13	10	13
1	1	18	11	15
...	...	...	...	...
2	3	15	31	19
2	3	28	35	33
...	...	...	...	...
99999	74	10	999	999
99999	74	15	999	999
99999	74	20	999	999

user ID : 匿名化された個人
day : カレンダーはわからないが、開始時点を 0 としたときの日付 (0 ~ 74のラベルが与えられる)
timeslot : 0 をある day の 0時としたときの 30分単位のラベル (0~47のラベルが振られる)
x, y : それぞれメッシュの座標を表す (正解データには 1~200 のラベル、予測対象には 999 が与えられている)。

メッシュの座標というのは、以下の図で表すことができます。

左上から順にx, y 方向それぞれに対して番号が振られる形ですね。1メッシュ500mなので、対象の地域は全体は 10km 四方の正方形ということになります。どこかは不明ですが、日本の中規模都市の 10km x 10km エリアにおける人々の移動を表すデータになります。

このコンペでは学習データとテストデータのような区別はなく、予測対象の user ID と day における x, y が 999 としてマスクされています。task1、task2 それぞれの予測対象は以下の通りです。

次に PoI Features についてです。こちらは以下のようなデータです。

x	y	POI category (dim)	# of POIs
1	1	13	10
1	1	18	11
1	1	24	11
1	1	27	12
...	...	...	...
2	2	15	31
2	2	28	35
2	2	12	35

x, y : メッシュを表す座標
POI category : 匿名化された PoI (レストランや公園などを表すラベル 0~84)
# of POIs : あるメッシュに存在する PoI の数

このコンペでは、個人情報保護のため PoI Feature と真の PoI のマッピングは提供されていません。誰がいつどこに行ったのかを隠すためですね。ここが開示されていればより面白いと思いますが、個人情報絡むのでちょっと難しいでしょうか。

与えられたデータセットは以上になります。

参考までに、 task1 における user ごとの x, y の line plot です。横軸が時間、縦軸が座標となっています。規則正しい人もいればそうではない人もいるのがわかって面白いですね。

評価指標

次に評価指標についてです。このコンペでは GEO-BLEU と DTW という二つの評価指標で最終的な順位を決めます。

まず GEO-BLEU ですが、これは、機械翻訳や文章生成タスクの出力を評価するための指標であるBLEU (Bilingual Evaluation Understudy) の geo 版という感じです。

user ID ごとの x, y それぞれの時間方向のシーケンスの n-gram の一致を基にスコアをつけているのだと思います。詳しくはこちらを参照ください。今回のコンペでは 0~1 の値をとり、大きいほど良いスコアということになります。

次に DTW (Dynamic Time Warping) についてですが、これは時系列で馴染み深い指標かと思います。時系列データ同士の距離・類似度を測る際に用いる手法ですね。

DTW は2つの時系列の各点の距離を総当たりで全て求め、2つの時系列が最短となるパスを見つけ、これの累積をとります。

画像はこちらから拝借しました。今回のコンペでは、0以上の値をとり、小さいほど良いスコアということになります。

この二つの指標はそれぞれ user ID 単位で計算し、最後に平均をとり、それを最終的な指標としています。

以下まとめです。

task1 (通常時) と task2 (緊急時) の日本のある地域におけるメッシュ単位での人々の移動を予測する
不完全なパネルデータである
各メッシュにおける匿名化された PoI の数は与えられている
評価指標は GEO-BLEU と DTW である

解法紹介

コンペ概要とデータの説明が済んだので、弊チームの解法を紹介したいと思います。最初にボツ解法を紹介し、最後に最終サブミッションとして選んだ解法を紹介しようと思います。特にひねりのない解放になってしまった事を最初に言っておきますね。

モデルベース

一番時間をかけて取り組みましたが、最終的なサブミッションには選ばなかったものです。後述するルールベースのものが最終サブになったので、こちらでは機械学習ベースの解法を紹介したいと思います。全体の流れは下の図のような感じです。

いわゆる seq2seq ですね。day 60~74 の範囲の目的変数 (x, y) を予測する際、day 0~59 の特徴量を LSTM Encoder に、day 60~74 の特徴量を LSTM Decoder に渡し、Encoder で得られた状態を引き継いだ Decoder が最終的な予測シーケンスを出力する算段です。LSTM 以外にも Transformer や GraphLSTM なども試したりしました。全て同じように seq2seq で系列を一発で出力するようにしています。

Encoder に渡す特徴量と Decoder に渡す特徴量はそれぞれリークがないように作っています。

Encoder に渡す特徴量としては、図にある通り、x, y, day time slot などの生の値や、x y を集約したものなどを使っています。この集約時にtime slot や曜日、週末祝日フラグなどを組み合わせています。提供されたデータには曜日や祝日などの情報はありませんが、生データからリバースエンジニアリングしました。また、PoI feature をマージする事で、地理的な特徴を捉えることを期待しています。

Decoder に渡す特徴量としては、目的変数の範囲外 (day 0~59) のデータを使い集約した特徴量を使っています。例えば、day 0~59 のデータを使い、user id ごとに各曜日の各時間で存在する座標の平均値や中央値などを集計し、それを day 60~74 にマージすることで特徴量としています。

また Target Engineering つまり目的変数の x, y もいじっています。まず、今回は分類ではなく回帰で解いています。この時、regression の目的変数に対して day 0~59 の範囲で集約した user id ごとの x , y それぞれの中央値を引き、標準偏差で割る処理を施しました。つまり中央値と分散が一定であるという仮定を置いています。

全体的な流れのお気持ちとしては、全ての情報をいい感じに使い、一発で系列を出力し、中央値かからあまり外れないような予測をしてほしいという感じです。一発で系列を出力して欲しかった理由は、t が比較的長いかつそこまでやれなかったからですね。

結果としては、ルールベースに及ばずでした...あとでルールベースのものとの精度比較を行いますが、まあまあしょぼかったです。理由としては以下が考えれるかなと思っています。

ハイパラチューニングをしなかった：時間的な余裕がなかったのもありますが、ほぼきめうちのハイパラで実験していました。
loss の工夫：評価指標である GEO-BLEU や DTW を考慮できる loss (があるか調べていないですが)は使わず、とりあえず RMSE で行っていました。比較的相関があったのでまあいいかなと思って使い続けていました。

もう少し丁寧に作れれば、ルールベースに負けず劣らずになったと信じたいです。

以上が機械学習ベースの解法になります。

ルールベース

以下が採用したルールになります。

この処理でまず完全なパネルデータを作ります。user ID x t x t_label x weekend 分のレコードを持つ欠損のないパネルデータを作るイメージですね。 predict 対象において欠損の部分だけ欠損値補完をすればいいのですが、めんどくさかったので完全パネルデータを作りました。こうして作成された欠損のないパネルデータと predict 対象のデータをマージする (必要な部分だけを抽出する) ことで最終的なサブミッションフォーマットに整えています。ハイパラである T は手動で軽くチューニングしたものを使いました。

結果

task1 だけですが手元の結果を載せておきます。

	ルールベース	モデルベース
geobleu	0.291	0.116
dtw	33.935	40.356

テキトウなサンプルで予測を可視化してみるとこんな感じになりました。task 1 に関しては人々の移動はかなり規則正しいです。余談ですが、task2 だと task1 と同様のルールを使ってもスコアが全然低い結果となります。やはり緊急事態時には通常時とは異なる動き方をしているのでしょうね。task2 だとモデルベースの方が dtw に関してはルールベースよりも良い結果をもたらしていました。

理由はあれど、最後にルールベースのサブミッションを作るだけ作り、私はこのコンペティションから逃走しました。ですので、アンサンブルやハイパラチューニングを詰めるといったことをせずでした。それでもTOP10 に残れたのは運が良かっただけだと思います。ドイツのワークショップは今回は残念ながら見送ることにしましたが、HuMob Challenge 2024 が開催されればまた参加したいですね！

さいごに

今回は HuMob Challenge 2023 参加記として、コンペの概要と解法の紹介を行いました。Next Place Prediction は大学の時から興味ある分野だったので、コンペとして触れることができよかったですし楽しく取り組むことができました。欲を言えばリーダーボードが欲しかったですね。また、PoI の開示や user ごとのデモグラフィックデータなどあるとより面白いのではないかと思っています。

提供されたデータは将来的にはオープンになるらしいので、機会があれば是非といったところです。

コードはこちらにあります (汚いのはご了承ください)

github.com