Google Colab CLIを使ってみた

Colab CLIのセットアップ

ColabCLIのGitHubリポジトリはこちらですgooglecolab/google-colab-cli。 最新情報はリポジトリのREADMEからご確認いただく方が正確です。

まずは実験用のディレクトリを作り、uvを初期化します。

mkdir colab-cli
cd colab-cli
uv init

続いてgoogle-colab-cliをインストールします。

uv tool install google-colab-cli

サンプルスクリプトを作成して、ColabCLI経由で実行してみましょう。 Google ColabはGoogleアカウントの認証を必要とするため、初回実行時には認証が求められます。

次のPythonファイルを作成してください。

# src/colab_cli/sample.py
def main():
    print("Hello Colab CLI")


if __name__ == "__main__":
    main()

このファイルをColabCLI経由で実行します。

# colab のセッションを作成する(ここで初回はGoogle認証が必要)
colab new -s test-session

# セッションと実行ファイルを指定してプログラムを動かす
colab exec -s test-session -f src/colab_cli/sample.py

#> Hello google colab CLI

上記の手順で正しく実行できることが確認できました。

ColabはGoogleの計算リソースを使っています。 そのため使っていないのに長時間セッションを占有するのは紳士的ではないですね☺️

次のコマンドでセッションを終了しましょう。

colab stop -s test-session

ファイルのアップと読み込み

次に、ローカルファイルをColabにアップして、読み込んでみましょう。

colab new -s test-session

次のようなCSVファイルを作ります。 data/names.csvというファイル名で作成します。

name,age
John,20
Jane,21
Jim,22

次にアップロード先のフォルダをリモート側に作成しなければなりません。 colab -hなどをしてもらえればわかりますが、フォルダを作成するAPIは提供されていません。 そこで、colab consoleでリモートシェルに接続してフォルダの作成を行います。

colab console

# リモートに繋がる
ls -la

#> /content# ls -l
#> total 4
#> drwxr-xr-x 1 root root 4096 Oct 17 23:09 sample_data

mkdir data
ls -l
#> total 8
#> drwxr-xr-x 2 root root 4096 Oct 23 05:42 data <--これができた‼️
#> drwxr-xr-x 1 root root 4096 Oct 17 23:09 sample_data

/content/dataにフォルダを作成しました。これでアップロードができます！

それでは先ほど作成したnames.csvをアップロードしてみましょう。

colab upload -s test-session ./data/names.csv  content/data/names.csv

#> [colab] Uploaded './data/names.csv' to 'content/data/names.csv'

colab uploadコマンドではローカルファイルのパスとリモートファイルのパスの両方を渡します。 また、ここでcontent/data/が存在しない場合に親フォルダが自動で作成されるという挙動にはならず、エラーが返される点には注意です。

実際にファイルが上がったかチェックしましょう。

colab ls -s test-session content/data/
#> names.csv

アップできたのでこれをPythonプログラムから読み取れることをチェックします。 次のスクリプトを作成して、実行してみましょう。

# src/colab_cli/file_control.py
def main():
    path = "data/names.csv"
    with open(path, "r") as f:
        print(f.read())


if __name__ == "__main__":
    main()

colab exec -s test-session -f src/colab_cli/file_control.py
#> name,age
#> John,20
#> Jane,21
#> Jim,22

正しく実行結果を得ることができました！ 注意点としてはColabは実行時に/content/を起点にパスが解決される点です。 path = "content/data/names.csv"とするとパス解決に失敗してしまいます。

依存関係の反映

次に、ローカルの依存関係をリモートに反映させる方法についてです。 今回はpandasを利用します。

まずはローカルに追加しましょう。ちなみに、colab install pandasというコマンドを実行するとリモートにだけpandasがインストールすることができます。しかし、実際に開発をしていく上ではuvのパッケージ管理は魅力的です。そのためここではローカル→リモートへの反映として紹介します。

uv add pandas

次にリモートに依存関係を反映します。 colab installコマンドはpyproject.tomlを読み込むことができます。

colab install -s test-session -r pyproject.toml

では実際にpandasを利用して、先ほどアップロードしたnames.csvを読み込んでみましょう。

# src/colab_cli/csv_read.py
import pandas as pd

def main():
    df = pd.read_csv("data/names.csv")
    print(df.head())

if __name__ == "__main__":
    main()

実行します！

colab exec -s test-session -f src/colab_cli/csv_read.py
#>    name  age
#> 0  John   20
#> 1  Jane   21
#> 2   Jim   22

正しくCSVファイルを読み込むことができましたね。

環境変数の設定

次に環境変数を設定したいと思います。 例えば自前の外部APIやLLMのAPIキーなどを設定したいときに有効な手法です。 ローカルではしばしば.envファイルを利用したり、シェル側に設定したりします。ColabCLiではどのように実現するのかをみていきます。

colab execには--envオプションがあります。これを利用することで環境変数を渡すことができます。

次のような環境変数DUMM_ENV_1とDUMM_ENV_2表示するスクリプトを書いて実行してみましょう。

# src/colab_cli/env.py
import os

def main():
    print(os.getenv("DUMM_ENV_1"))
    print(os.getenv("DUMM_ENV_2"))

if __name__ == "__main__":
    main()

colab exec -s test-session \
-f src/colab_cli/env.py \
--env DUMM_ENV_1=dummy_value_1 \
--env DUMM_ENV_2=dummy_value_2
#> dummy_value_1
#> dummy_value_2

正しく環境変数を渡すことができました。

しかし、これでは.envファイルを利用している場合や、環境変数の数が多い場合に少し不便です。 .envを利用している場合には先ほどのcolab uploadコマンドでリモート環境にアップロードして利用することが可能です（その場合python-dotenvなどを利用してローカルで.envファイルを読み込む必要があります） また、アップロードしたくない場合にはシェルコマンドを用いて.envファイルから展開を行うことも可能かと思います。

# .env
DUMM_ENV_1=dummy_value_1
DUMM_ENV_2=dummy_value_2

仮にこのようなファイルがある場合には次のようにすれば展開し実行が可能かと思います！

# .envファイルから引数文字列を作成
env_args=()
while IFS= read -r line; do
  [[ -z $line || $line == \#* ]] && continue
  env_args+=(--env "${line#export }")
done < .env

# 展開した引数を渡して実行
colab exec -s test-session -f src/colab_cli/env.py "${env_args[@]}" 
#> dummy_value_1
#> dummy_value_2

GPUセッションとLLMの動作

次に、私がこの記事を書く動機となったGPUセッションの起動とLLMの動作を確認します。 今までのセッション(test-session)ではGPUをマウントしていないため新しいセッションを起動します。

colab new -s gpu-session --gpu A100

GPUセッションを起動することができたかどうかを確認しましょう。 colab statusまたはcolab sessionsでセッション一覧を確認できます。

colab sessions
#> [gpu-session] xxxxxxxxxxxxxxx | Hardware: A100 | Shape: Standard | Variant: GPU
#> [test-session] yyyyyyyyyyyyyyy | Hardware: CPU | Shape: Standard | Variant: DEFAULT

colab status
#> [test-session] yyyyyyyyyyyyyyy | Hardware: CPU | Shape: Standard | Variant: DEFAULT | Status: IDLE
#>   Last Execution: stdin at YYYY-MM-DD HH:MM:SS
#> [gpu-session] xxxxxxxxxxxxxxx | Hardware: A100 | Shape: Standard | Variant: GPU | Status: IDLE

一部情報は意図的に隠していますが、A100GPUを搭載したセッションが立ち上がっていることを確認できました。

次に、pytorchからこのGPUが利用可能かをチェックしましょう。次のスクリプトを作成してください。

# src/colab_cli/gpu_check.py
    
import torch

def main():
	is_available = torch.cuda.is_available()
	print(f"{is_available=}")

	if is_available:
		name = torch.cuda.get_device_name(0)
		print(f"{name=}")

if __name__ == "__main__":
	main()
	

pytorchをインストールします。

uv add torch
colab install -s gpu-session -r pyproject.toml

#> [colab] Installing packages on gpu-session (preferring uv)...
#> Installation Complete (via uv)!

次のコマンドで実行しましょう：

colab exec -s gpu-session -f src/colab_cli/gpu_check.py
#> is_available=True
#> name='NVIDIA A100-SXM4-40GB'

GPUは正しく接続されており、torchからも利用可能なことが確認できました。

次にLLMを動かしてみましょう。 今回は動作確認だけが目的であるため、パラメータ数の比較的少ないgemma4:e2bを利用します。

# src/colab_cli/llm_check.py
import torch
from transformers import AutoModelForMultimodalLM, AutoProcessor

MODEL_ID = "google/gemma-4-E2B-it"


def main():
	if not torch.cuda.is_available():
		raise SystemExit("GPUが利用できません。")
	print(f"{torch.cuda.get_device_name(0)=}")

	processor = AutoProcessor.from_pretrained(MODEL_ID)
	model = AutoModelForMultimodalLM.from_pretrained(MODEL_ID, dtype="auto", device_map="auto")

	messages = [
		{"role": "system", "content": "You are a helpful assistant."},
		{"role": "user", "content": "Google Colabとは何か、3文で簡潔に説明してください。"},
	]
	inputs = processor.apply_chat_template(
		messages,
		tokenize=True,
		return_dict=True,
		return_tensors="pt",
		add_generation_prompt=True,
		enable_thinking=False,
	).to(model.device)
	input_len = inputs["input_ids"].shape[-1]

	outputs = model.generate(**inputs, max_new_tokens=256)

	new_tokens = outputs[0][input_len:]
	response = processor.decode(new_tokens, skip_special_tokens=True)
	print(f"\n--- Prompt ---\n{messages[-1]['content']}")
	print(f"--- Response ---\n{response.strip()}\n")

if __name__ == "__main__":
	main()

実行のために追加でいくつかライブラリをインストールします。

uv add transformers torchvision
colab install -s gpu-session -r pyproject.toml

次のコマンドで実行しましょう。 初回はモデル重みの取得が走るため、実行には少し時間を要します。そのため--timeoutオプションを指定して20分間の実行を許可します。

colab exec -s gpu-session -f src/colab_cli/llm_check.py --timeout 1200
#> torch.cuda.get_device_name(0)='NVIDIA A100-SXM4-40GB'
#> Loading weights:   0%|          | 0/1951 [00:00<?, ?it/s]
#> --- Prompt ---
#> Google Colabとは何か、3文で簡潔に説明してください。
#> --- Response ---
#> Google Colabは、Googleが提供する無料のクラウドベースのノートブック環境です。これにより、Pythonなどのコードをブラウザ上で実行し、データ分析や機械学習の実験を簡単に行うことができます。特別なソフトウェアのインストールなしに、高性能な計算リソースを利用できるのが大きな特徴です。

上記のようにLLMが応答を返すことが確認できました。 GPUセッションを最後に閉じておきましょう。

colab stop -s gpu-session

また、Colabは無制限に使えるわけではありません。 次のコマンドで残りの使用量を確認することができます。

colab usage

#> Current balance: 388.19 compute units
#> Usage rate: 0.08/hr
#> Active assignments: 1