⛩️

【Kaggle API】 VSCode で Kaggle する

2024/03/31に公開

機械学習

Kaggle

tech

今回はKaggle APIを使用して、0からVSCodeでKaggleするところまでを解説します。
主に以下の公式リファレンスのまとめです。

0. 目標

VSCodeからnotebookの push(Save & Run All) や pull ができるところまで
※Kaggleと同じ環境の構築は別で記事にする予定です。

1. インストール

初めに以下のコマンドでKaggleのパッケージをインストールします。

$ pip install kaggle

macやlinuxで途中でエラーが出た場合、上記の代わりに以下を実行します。

$ pip install --user kaggle

2. APIトークンの取得

Kaggle APIを使用するには、APIトークンを発行する必要があります。

User Profileから「Create New Key」を選択します。
これにより資格情報を含むkaggle.jsonファイルが取得できます。

jsonファイルを好きな場所に保存して、VSCodeのターミナルで以下を実行し、環境変数を設定します。

$ export KAGGLE_CONFIG_DIR=[jsonファイルを保存したディレクトリのpath]

※[]は不要

次に以下のコードで権限を設定します。

$ chmod 600 [jsonファイルを保存したディレクトリのpath]

これでAPIのセットアップは完了です。

この設定はログアウトすると消去されてしまいます。毎回設定するのが面倒だという方は、/Users/ユーザー名の.zshrcファイルに上記のexportコマンドを記述しておきましょう。
コマンドライン立ち上げ時に自動で実行してくれます。
※chmodは一度実行すれば大丈夫です。.zshrcにchmodを記述すると権限エラーになるので注意しましょう。

3. CLI

この章はKaggle APIの解説です。
結論から知りたい方は4章に飛んで、後で確認しても問題ありません。

では試しにCLIからKaggle APIを使用してみましょう。以下のコードで開催中のコンペの情報を取得できます。

・開催中コンペの取得

$ kaggle competitions list

・出力(開催中コンペ)

# ref                                                                              deadline             category            reward  teamCount  userHasEntered  
# -------------------------------------------------------------------------------  -------------------  ---------------  ---------  ---------  --------------  
# https://www.kaggle.com/competitions/llm-prompt-recovery                          2024-04-16 23:59:00  Featured          $200,000       1691           False  
# https://www.kaggle.com/competitions/home-credit-credit-risk-model-stability      2024-05-27 23:59:00  Featured          $105,000       1266           False  
# https://www.kaggle.com/competitions/pii-detection-removal-from-educational-data  2024-04-23 23:59:00  Featured           $60,000       1658            True  
# https://www.kaggle.com/competitions/hms-harmful-brain-activity-classification    2024-04-08 23:59:00  Research           $50,000       2655            True  
# https://www.kaggle.com/competitions/image-matching-challenge-2024                2024-06-03 23:59:00  Research           $50,000        113           False  
# https://www.kaggle.com/competitions/data-assistants-with-gemma                   2024-04-14 23:59:00  Analytics          $50,000          0           False  
# https://www.kaggle.com/competitions/playground-series-s4e3                       2024-03-31 23:59:00  Playground            Swag       2055           False  
# https://www.kaggle.com/competitions/planttraits2024                              2024-06-15 22:00:00  Research         Knowledge         47           False  
# https://www.kaggle.com/competitions/geolifeclef-2024                             2024-05-24 23:59:00  Research         Knowledge         28           False  
# https://www.kaggle.com/competitions/titanic                                      2030-01-01 00:00:00  Getting Started  Knowledge      16037            True  
# https://www.kaggle.com/competitions/house-prices-advanced-regression-techniques  2030-01-01 00:00:00  Getting Started  Knowledge       4504           False  
# https://www.kaggle.com/competitions/spaceship-titanic                            2030-01-01 00:00:00  Getting Started  Knowledge       2613           False  
# https://www.kaggle.com/competitions/digit-recognizer                             2030-01-01 00:00:00  Getting Started  Knowledge       1799           False  
# https://www.kaggle.com/competitions/nlp-getting-started                          2030-01-01 00:00:00  Getting Started  Knowledge       1100           False  
# https://www.kaggle.com/competitions/store-sales-time-series-forecasting          2030-06-30 23:59:00  Getting Started  Knowledge        737           False  
# https://www.kaggle.com/competitions/connectx                                     2030-01-01 00:00:00  Getting Started  Knowledge        209           False  
# https://www.kaggle.com/competitions/gan-getting-started                          2030-07-01 23:59:00  Getting Started  Knowledge        111           False  
# https://www.kaggle.com/competitions/contradictory-my-dear-watson                 2030-07-01 23:59:00  Getting Started  Knowledge         52           False  
# https://www.kaggle.com/competitions/tpu-getting-started                          2030-06-03 23:59:00  Getting Started  Knowledge         49           False  
# https://www.kaggle.com/competitions/predict-energy-behavior-of-prosumers         2024-04-30 23:59:00  Featured           $50,000       2731            True

以下は使用できるCLIコマンドの一覧です。
・コマンド一覧

$ kaggle competitions {list, files, download, submit, submissions, leaderboard}
$ kaggle datasets {list, files, download, create, version, init, metadata, status}
$ kaggle kernels {list, init, push, pull, output, status}
$ kaggle models {get, list, init, create, delete, update}
$ kaggle models instances {get, init, create, delete, update}
$ kaggle models instances versions {init, create, download, delete}
$ kaggle config {view, set, unset}

・コンペ関連
・データセット関連
・カーネル(ノートブック)関連
・モデル関連
・設定
の操作を行う事ができます。

数が多いので、主要なコマンドのみを紹介します。

3.1 コンペ関連

コンペ関連のコマンドを紹介します。

3.1.1 提供ファイルのダウンロード

提供ファイルをダウンロードします。

簡単に
kaggle competitions download [コンペURLの末尾]で、カレントディレクトリにコンペのファイルが全てダウンロードされます。
・例
```
# 提供ファイルのダウンロード
$ kaggle competitions download titanic
```

詳しく
ダウンロードの際に以下のオプションが設定できます。

  コマンド: kaggle competitions download [-h] [-f FILE_NAME] [-p PATH] [-w] [-o]
                                        [-q]
                                        [competition]
  
  オプションの引数:
    -h, --help            ヘルプ
    competition           取得したいコンペURLの末尾。("kaggle competitions list"で確認可能)
                          空の場合デフォルトコンペが選択される。("kaggle config set competition"でデフォルトを変更できる)
    -f FILE_NAME, --file FILE_NAME
                          取得したいファイルを指定。空の場合は全データが取得される
                          (ファイル名は"kaggle competitions files -c <competition>"で確認可能)
    -p PATH, --path PATH  ファイルのダウンロード先。空の場合はカレントディレクトリ
    -w, --wp              カレントディレクトリにファイルをダウンロードする
    -o, --force           すでにダウンロードしたファイルが最新かどうかの確認をスキップし、強制的にダウンロードを実行する
    -q, --quiet           ダウンロード進行状況を表示しない

3.1.2 Submit

Submitします。
kaggle competitions submit [コンペURLの末尾] -f "FILE_NAME" -m "MESSAGE"でSubmitできます。
・例

# Submit
$ kaggle competitions submit titanic -f sample_submission.csv.7z -m "My submission message"

※[コンペURLの末尾]は省略可能。その場合、"kaggle config set competition"で設定したコンペが自動選択されます。

3.1.3 Submissionの確認

Submissionを確認します。
kaggle competitions submissions [コンペURLの末尾]で自分の提出ファイルとスコアを確認できます。
・例

# Submissonの確認
$ kaggle competitions submissions titanic

3.1.4 LBの確認

LBを確認します。
kaggle competitions leaderboard [コンペURLの末尾] -sでLBを確認できます。
・例

# LBの確認
$ kaggle competitions leaderboard titanic -s | head -n 10

3.2 データセット関連

データセット関連のコマンドを紹介します。

3.2.1 データセットのダウンロード

データセットをダウンロードします。
kaggle datasets download <owner>/<dataset-name>でデータセットをダウンロードできます。
・例

# データセットのダウンロード
$ kaggle datasets download zillow/zecon

--unzipを追加するとzipファイルをダウンロード後に解凍できます。

3.2.2 新しいデータセットの作成

データセットを作成します。
・例

# データセットの作成 -p　ディレクトリパス
$ kaggle datasets create -p /path/to/dataset

--publicを追加すると公開データセットになります。

ディレクトリにはdataset-metadata.jsonが必要です。
・例

dataset-metadata.json

{
    "title": "My_Dataset",
    "description": "My awesomest description",
    "id": "username/my-dataset", 
    "licenses": [{"name": "unknown"}]
  }

3.2.3 データセットのバージョンアップ

データセットをバージョンアップします。
・例

$ kaggle datasets version -p /path/to/dataset -m "Updated data"

3.3 カーネル(ノートブック)関連

カーネル(ノートブック)関連のコマンドを紹介します。

3.3.1 カーネルの確認

特定ユーザーが作成したカーネルを確認します。
・例

# カーネルの確認
$ kaggle kernels list --competition [コンペURLの末尾] --user [ユーザ名] --page-size 100 --sort-by dateRun

ユーザ名はプロフィールから確認可能で、表示名とは異なります。

3.3.2 カーネルのPush

作成したカーネルをPushして実行します。
・例

# カーネルの実行
$ kaggle kernels push -p /path/to/folder

kernel-metadata.jsonを含むディレクトリを指定します。詳細
initコマンドでディレクトリを指定してkernel-metadata.jsonを作成できます。

kaggle kernels init -p .

・例

kernel-metadata.json

{
  "id": "timoboz/my-awesome-kernel",
  "id_no": 12345,
  "title": "My Awesome Kernel",
  "code_file": "my-awesome-kernel.ipynb",
  "language": "python",
  "kernel_type": "notebook",
  "is_private": "false",
  "enable_gpu": "false",
  "enable_internet": "false",
  "dataset_sources": ["timoboz/my-awesome-dataset"],
  "competition_sources": [],
  "kernel_sources": [],
  "model_sources": []
}

手動でも作成できますが、500: internal server errorが発生する場合はinitコマンドでjsonファイルを作成してみて下さい。

3.3.3 カーネルのPull

カーネルをPullします。
kaggle kernels pull <owner>/<kernel-name> -mでカーネルを取得できます。
-mでメタデータ(kaggle.json)を含めて取得します。
・例

# カーネルの取得
$ kaggle kernels pull rtatman/list-of-5-day-challenges -m

3.3.4 カーネル実行状況の取得

kaggle kernels status <owner>/<kernel-name>でカーネルが実行中、完了、失敗のいずれかを取得できます。
・例

$ kaggle kernels status mrisdal/exploring-survival-on-the-titanic

3.4 設定関連

設定関連のコマンドを紹介します。

3.4.1 現在の設定を取得

現在の設定を取得します。
・例

# 現在の設定を取得
$ kaggle config view

・出力(現在の設定)

# - username: ----
# - path: None
# - proxy: None
# - competition: None

3.4.2 設定の変更

設定を変更します。
kaggle config set -n [NAME] -v [VALUE]で設定を変更できます。
・例

$ kaggle config set -n competition -v titanic

3.4.3 設定の初期化

設定を初期化します。
・例

# 設定の初期化
$ kaggle config unset -n competition

以上でCLIのコマンド紹介は終わりです。
より詳細には[Kaggle API GitHub](https://github.com/Kaggle/kaggle-api#competitions を確認してください。
)

4. 実際に使ってみる

ここからは具体的な使い方を紹介します。

4.1 カーネル(ノートブック)の作成/取得

VSCodeで新規にpythonファイルを作成するか、既存のカーネルを取得します。

新規作成する場合
VSCodeでcommand + shift + Pもしくはcommand + Pを入力、Create: New Jupyter Notebbokを選択。
VSCode右上のKernelを選択、Python3に設定
カーネルを取得する場合
試しに以下のカーネルを取得してみましょう。
```
# カーネルとメタデータを取得
$ kaggle kernels pull cdeotte/efficientnetb0-starter-lb-0-43 -m
```
VSCodeターミナルから、以下を実行してカーネルを開きます。
```
# カーネルを開く
$ code efficientnetb0-starter-lb-0-43.ipynb
```
※code実行時にmac等でエラーが出る場合は command + shift + P を押して、Shell Command: Install 'code' command in PATHを入力してください。

4.2 Push & Run

では新規作成したカーネル実行してみましょう。
※カーネルをpullで取得した方は、以下のpushのコードのみを実行して下さい。

4.2.1 提出ファイルの作成

以下のディレクトリとファイルを準備して下さい。

# ディレクトリ構成
test/
├── test.ipynb
└── kernel-metadata.json

実行ファイル(test.ipynb)

test.ipynb

# テスト用カーネル
print('test')

メタデータ(kernel-metadata.json)
以下のコマンドでjsonファイルの雛形が作成されます。
```
$ kaggle kernels init -p test
```
kernel-metadata.json
```
{
  "id": "[ユーザ名]/test-notebook-1",
  "title": "TEST NOTEBOOK 1",
  "code_file": "test.ipynb",
  "language": "python",
  "kernel_type": "notebook",
  "is_private": "true",
  "enable_gpu": "false",
  "enable_tpu": "false",
  "enable_internet": "true",
  "dataset_sources": [],
  "competition_sources": [],
  "kernel_sources": [],
  "model_sources": []
}
```
※ユーザ名は、Kaggleプロフィールの自分の表示名の上に小さく表示されています。

メタデータの解説

id: ノートブックのURL末尾
title: ノートブックのタイトル
code_file: コード本体
language: 使用言語 {python,r,rmarkdown}
kernel_type: コードの種類 {script,notebook}
is_private: ノートブックの公開可否
enable_gpu: GPUの使用可否
enable_tpu: TPUの使用可否
enable_internet: カーネルがインターネットに接続できるかどうか

以下はカーネルで外部データを使用する際のsourceを記述(任意)。
※複数指定可、slugはURL末尾の意
dataset_sources: ex. "username/dataset-slug"
competition_sources: ex. "competition-slug"
kernel_sources: ex. "username/kernel-slug"
model_sources: ex. "username/model-slug/framework/variation-slug/version-number"

4.2.2 Push(Save & Run All)

Push(Save & Run All)
Pushは以下のコマンドで行います。
```
# Push
$ kaggle kernels push -p test
```
正常にPushできれば、Kernel version 1 successfully pushed.と表示されます。
ステータスの確認
実行まで完了しているかどうか、次のコマンドで確かめてみましょう。
```
# 実行ステータスを取得
$ kaggle kernels status [ユーザ名]/test-notebook-1
```
[ユーザ名]/test-notebook-1 has status "complete"となっていれば実行が完了しています。
もし失敗していた場合は、VSCode右上のKernelが正しくPython3になっているか確認して下さい。

以上で作成したファイルの実行は完了です！
以降は、同じようにpushすることでnotebookのversionが更新されていきます。

ひとまずここまで出来れば、VSCode上でKaggleに取り組めるのではないでしょうか。

まとめ

今回はKaggle APIを使用して、VSCodeからKaggleする方法を解説しました。
今後はDockerを利用して簡単にKaggleと同じ環境を構築する方法や、他のCLIコマンドなども記述する予定です。

2024/04/01 追記: Kaggle環境構築編を公開しました。

参考

How to use Kaggle API
Kaggle API GitHub