「Jupyter APIを使用してノートブックをスケジュールして呼び出す」

Using Jupyter API to schedule and call notebooks

サーバーレスクラウドサービス、例えばGCP CloudRunnerやCloud Functionsのおかげで、ノートブックをデプロイし定期的に実行するために、高価な仮想マシンやサーバーを管理する必要はありません。Jupyter APIを使用することで、ノートブックをクラウドに移行し、Webサービスに変換し、スケジューリングと統合することができます。

ただし、最も一般的に使用されるアプローチ（Vertex AIやSageMakerのようなクラウドネイティブサービスを使用していない限り）は、nbconvertを使用してノートブックをPythonコードに変換し、それを新しくブートストラップされたTornadoまたはFlaskのカスタムWebアプリケーションに追加することです。

これにはいくつかのコーディングと外部ライブラリが含まれますが、良いニュースは、Jupyter開発コンテナにコードを残しておいて、Jupyter Rest APIを使用して直接トリガーできるということです。

Web APIを介してノートブックにアクセスする

Jupyter APIの使用方法の詳細に入る前に、アーキテクチャがどのように機能するかを示します。まず、テストに使用する簡単なノートブックを取り上げましょう。

• ジェネレーティブAIアプリケーションを構築するための最高のPythonツール チートシート
• 「RBIは、Conversational AIとオフライン決済の使用をUPIで採用する」
• 「最もテクノロジー志向のある米国の都市は、自動運転車について疑問を抱いています」

Jupyterを使用してローカルで実行するための最も簡単な方法は、Jupyter Labコンテナで実行することです：

# テストワークブックのダウンロードwget https://raw.githubusercontent.com/tfoldi/vizallas/main/notebooks/JupyterAPI_Test.ipynb# トークン認証を使用して新しいJupyter Labインスタンスを生成します（XSRFなし）docker run -it --rm -p 8888:8888 \  -e JUPYTER_TOKEN=ab30dd71a2ac8f9abe7160d4d5520d9a19dbdb48abcdabcd \  --name testnb -v "${PWD}":/home/jovyan/work jupyter/base-notebook \  jupyter lab --ServerApp.disable_check_xsrf=true

サービスが開始されると、JUPYTER_TOKEN環境変数で渡されたトークンを使用して、http://127.0.0.1:8888/lab/tree/workでノートブックにアクセスできるようになります。

コマンドラインからノートブックを呼び出す

コマンドラインからは、この小さなスクリプトをダウンロードすることができます（requestsとwebsocket-clientパッケージが必要です）またはDockerコンテナを介して実行することができます：

# 以前に開始した「testnb」コンテナのIPアドレスを確認しますdocker inspect testnb | grep IPAddress            "SecondaryIPAddresses": null,            "IPAddress": "172.17.0.2",                    "IPAddress": "172.17.0.2",# ノートブックを呼び出します。以下のIPアドレスを前の手順で取得したものに置き換えてください。docker run -it --rm \  -e JUPYTER_TOKEN=ab30dd71a2ac8f9abe7160d4d5520d9a19dbdb48abcdabcd \  tfoldi/jupyterapi_nbrunner 172.17.0.2:8888 /work/JupyterAPI_Test.ipynbhttp://172.17.0.2:8888/api/kernelsに新しいカーネルが作成されました各セルに対して実行リクエストを送信します{'data': {'text/plain': '15'}, 'execution_count': 3, 'metadata': {}}処理が終了しました。WebSocket接続を閉じますカーネルを削除します

このスクリプトは、新しく作成したJupyterLabサーバーに接続し、ノートブックを実行し、最後のセルの結果を返し、その後終了します。ノートブックのコードや追加のライブラリの修正は必要ありませんで、Webプロトコルを介して手順全体が行われます。

内部機構

残念ながら、Jupyter APIにはノートブックを完全に実行するための単一のエンドポイントはありません。まず、新しいカーネルを初期化するか（または既存のカーネルを使用するか）、ノートブックのメタデータを取得し、すべてのコードセルを取得し、それぞれに対してexecute_requestを送信する必要があります。

結果を取得するためには、WebSocketチャネルでの受信メッセージを監視する必要があります。すべてのコードの実行が終了する「すべてのコードの実行終了」メッセージがないため、実行に送ったコードブロックの数と実際に完了した数を手動で追跡する必要があります。これは、execute_replyタイプのメッセージを数えることで行います。すべての実行が完了した後、カーネルを停止するか、将来の実行のためにアイドル状態にしておくことができます。

次の図は完全なフローを示しています：

認証された状態を維持するために、すべてのHTTPおよびWebSocketの呼び出しにAuthorizationヘッダーを渡す必要があります。

ノートブックを実行するためにやや冗長な手順のように感じるかもしれませんが、理解します。Jupyter Server内に複雑さを減らすための高レベルの関数を実装することは有用であると思います。

完全なスクリプトはこちらにあり、アプリケーションで使用する準備ができています。

GCPでワークブックを無料（ほぼ無料）でスケジュールする

ノートブックをホストするための多くのオプションがありますが、最も費用対効果の高い方法はGoogle CloudのCloud Runサービスを活用することです。Cloud Runでは、ジョブの実行時間のみを支払うため、頻繁にトリガーされないタスクや追加のパッケージや追加のSaaSベンダー（Google以外）を必要としない場合には、コスト効率の良い選択肢となります。また、一行のコードも書かずに済みます。

アーキテクチャと呼び出しのフローは次のようになります：

まず、GCP Cloud Runにノートブックをデプロイする必要があります。Cloud Runサービスにファイルを追加するための複数の方法がありますが、最も簡単な方法の1つは、ノートブックをDockerコンテナにコピーすることです。

# Jupyter Server上でノートブックをホストするためのシンプルなDockerfileFROM jupyter/base-notebookCOPY JupyterAPI_Test.ipynb /home/jovyan/workspaces/

ビルドしてコンテナをCloud Runで利用できるようにするには、gcloud run deployで--sourceオプションを指定し、ノートブックとDockerfileが保存されているディレクトリを指定するだけです。

# JupyterノートブックとDockerfileのソースコードを取得するgit clone https://github.com/tfoldi/jupyterapi_nbrunner.git# テストノートブックをjupyter/base-notebookコンテナにデプロイする # DockerfileとJupyterAPI_Test.ipynbファイルはtests/test_notebookフォルダにありますgcloud run deploy test-notebook --region europe-west3 --platform managed \  --allow-unauthenticated --port=8888 \  --source tests/test_notebook \  --set-env-vars=JUPYTER_TOKEN=ab30dd71a2ac8f9abe7160d4d5520d9a19dbdb48abcdabcd   [...]Service [test-notebook] revision [test-notebook-00001-mef] has been deployed and is serving 100 percent of traffic.Service URL: https://test-notebook-fcaopesrva-ey.a.run.app

JupyterLabはサービスURLで利用可能です。Google Cloud RunはSSL証明書と、要求に応じて展開を開始または一時停止するメカニズムを提供します。

Cloud Schedulerから新しくデプロイされたノートブックをトリガーするためには、PubSubトピックに紐づけられたCloud Functionを作成する必要があります。次のコマンドは、このリポジトリからmain.pyとrequirements.txtをデプロイします。 main.pyは、以前にコマンドラインからコードをトリガーするために使用したスクリプトと同じです。

# https://github.com/tfoldi/jupyterapi_nbrunner.gitのコンテンツをクローンしたディレクトリと同じディレクトリにいることを確認してください gcloud functions deploy nbtrigger --entry-point main --runtime python311 \  --trigger-resource t_nbtrigger --trigger-event google.pubsub.topic.publish \  --timeout 540s --region europe-west3 \  --set-env-vars=JUPYTER_TOKEN=ab30dd71a2ac8f9abe7160d4d5520d9a19dbdb48abcdabcd

次は、適切なパラメータを持つメッセージをt_nbtriggerトピックに送信して、新しいCloud Functionをテストしてみましょう。コマンドラインと同様に行います。

gcloud pubsub topics publish t_nbtrigger \  --message="test-notebook-fcaopesrva-ey.a.run.app:443        /workspaces/JupyterAPI_Test.ipynb --use-https"

nbtrigger Cloud Functionのログを確認すると、トピックへのレコードの送信がノートブックの実行をトリガーしたことがわかるかもしれません。

最後のステップは、指定した時間に実行されるスケジュールを作成することです。この場合、ノートブックを毎時実行します。

gcloud scheduler jobs create pubsub j_hourly_nbtrigger \  --schedule "0 * * * *" --topic t_nbtrigger --location europe-west3 \  --message-body "test-notebook-fcaopesrva-ey.a.run.app:443 /workspaces/JupyterAPI_Test.ipynb --use-https --verbose"   

準備完了です-最初のJupyter Notebookをサーバーレスでスケジュールしました。

私たちのノートブックは1日にわずか数セントしか消費せず、このデプロイ方法はGoogle Cloudで最も費用効果の高い方法の1つです。

結論

以前は、JupyterノートブックをPythonコードに変換してクラウドネイティブツールで利用したり、Vertex AIやSageMakerのようなより複雑で高価なサービスを利用する必要がありました。しかし、Jupyter Rest APIを利用してノートブックとその「開発環境」をデプロイすることで、余分な手順を省略し、ノートブックに対してWebサービス呼び出しやスケジューリングを可能にすることができます。

このアプローチは、大規模なプロジェクトやコンピュートに重い長時間実行のノートブックには適していませんが、ホームオートメーションや趣味のプロジェクトなどでは、インフラストラクチャに(過)多額の費用をかけずに十分に利用できます。

We will continue to update VoAGI; if you have any questions or suggestions, please contact us!