Merge pull request #46 from Azure/docs-upgrade-keonabut

Docs for Quickstart

Author: konabuta

README.md

@@ -21,11 +21,15 @@ Azure Machine Learning + GitHub を利用した MLOps 実装サンプルコー
 
 ## 🚀 使い方
 - Azure Machine Learning と GitHub の環境を準備します。
+- クライアント環境として下記のいずれかにアクセスします。
+    - Azure Machine Learning のコンピューティングインスタンス
+    - DevContainer 環境
+        - Conda でのパッケージインストールの際にメモリを消費するため、ある程度大きいスペックが必要になります。Codespaces の場合、4-core / 8GB RAM / 32GB storage 以上の Machine Type を選択してください。
 - .env ファイルに環境変数の設定をします。
 - [./scripts](./scripts) フォルダの各シェルスクリプトを実行します。
-- GitHub の Secrets を作成します。
+- GitHub の Secrets を作成し、GitHub Actions を有効化し実行します。
 
-:point_right: **更に詳しい手順や参考資料は [クイックスタート](./docs/quickstart.md) のドキュメントを参照してください。**
+:point_right: **クライアント環境として Azure Machine Learning のコンピューティングインスタンス (Compute Instance) を利用した場合のコードや CI/CD の実行方法は [クイックスタート](./docs/quickstart.md) のドキュメントに記載してあります。**
 
 
 ## 📝 技術条件
@@ -95,7 +99,44 @@ Azure Machine Learning + GitHub を利用した MLOps 実装サンプルコー
 
 ## 📄 ディレクトリ構造
 
->TODO
+```
+.
+├── .devcontainer   # Configuration files for DevContainer
+├── .github
+│   └── workflows   # YAML files for GitHub Actions
+├── .vscode
+├── cli             # YAML files for Azure ML CLI v2
+│   ├── assets
+│   ├── endpoints
+│   └── jobs
+├── data            # Sample data
+│   ├── raw
+│   └── samples
+├── docs            # Documenting quickstart, coding style guide etc
+├── environments    # Python libraries
+├── notebooks       # Jupyter Notebook
+├── pipelines       # Azure ML Pipeline CLI v2
+│   ├── eval
+│   ├── prep
+│   ├── score
+│   └── train
+├── scripts
+│   ├── assets      # Shell scripts for creating assets like data, compute, environment
+│   ├── endpoints   # Shell scripts for scoring model
+│   ├── jobs        # Shell scripts for model training
+│   └── prototyping # Shell scripts for experimental
+├── src
+│   ├── data        # Code for data preparation
+│   ├── deploy      # Code for scoring model
+│   ├── features    # Code for feature engineering
+│   ├── model       # Code for model training
+│   ├── monitor     # Code for monitoing data and model
+│   └── rai         # Code for responsible ai
+├── tests
+│   ├── data_validation # Code for validating data
+│   └── unit            # Code for unit testing
+└── utils           # Code for utilities
+```
 
 ---
 

docs/quickstart.md

@@ -1,29 +1,32 @@
 # クイックスタート
-本リポジトリを動作させる手順を記載します。
+## 1. コード実行
+サンプルコードを動かす手順を紹介します。
 
-## Azure Machine Learning の環境準備
+### Azure Machine Learning の環境準備
 - Azure の Subscription を準備します。
-  ※本リポジトリは所有者権限を持っていることを前提に作成されています。
-- [クイックスタート: Azure Machine Learning の利用を開始するために必要なワークスペース リソースを作成する](https://learn.microsoft.com/ja-jp/azure/machine-learning/quickstart-create-resources) の手順に従って、`ワークスペース` と `コンピューティングインスタンス` を作成します。
-- [Visual Studio Code で Azure Machine Learning コンピューティング インスタンスに接続する (プレビュー)](https://learn.microsoft.com/ja-jp/azure/machine-learning/how-to-set-up-vs-code-remote?tabs=studio) の手順に従って、`コンピューティングインスタンス` にアクセス可能なことを確認します。
+  - Azure のリソースグループに対する所有者権限を持っていることが前提です。
+- [クイックスタート: Azure Machine Learning の利用を開始するために必要なワークスペース リソースを作成する](https://learn.microsoft.com/ja-jp/azure/machine-learning/quickstart-create-resources) の手順に従って、Azure Machine Learning の `ワークスペース` と `コンピューティングインスタンス` を作成します。
+- [Visual Studio Code で Azure Machine Learning コンピューティング インスタンスに接続する (プレビュー)](https://learn.microsoft.com/ja-jp/azure/machine-learning/how-to-set-up-vs-code-remote?tabs=studio#configure-a-remote-compute-instance) の手順に従って、Azure Machine Learning の `コンピューティングインスタンス` にアクセス可能なことを確認します。
 
 
 <br />
 
-## GitHub の環境準備
+### GitHub の環境準備
 - GitHub のアカウントを準備します。
-  ※ Public リポジトリを利用する前提であれば Free (個人向けの基本プラン) で動作しますが、セキュリティ機能などが豊富な Team プランや Enterprise プランの利用を推奨します。
-- 本リポジトリを Fork します。
+  - Public リポジトリを利用する前提であれば Free プラン (個人・組織の基本プラン) の[価格プラン](https://github.com/pricing)で動作しますが、セキュリティ機能などが豊富な Team プランや Enterprise プランの利用を推奨します。
+- 本リポジトリ [Azure/mlops-starter-sklearn](https://github.com/Azure/mlops-starter-sklearn) を自分のアカウント・組織に Fork します。
 - `コンピューティングインスタンス` のターミナル上で、User フォルダ (Users) 配下の自分の個人フォルダに Fork したリポジトリをクローンします。
 
 ```bash
 cd User/<username>
-git clone https://github.com/<github user/org>/mlops-starter-sklearn
+git clone https://github.com/<github user/org>/mlops-starter-sklearn #Fork 先のリポジトリを指定
 ```
 
 <br />
 
-## 環境変数の設定
+### Azure Machine Learning 上での環境変数の設定
+先ほど Fork したコードを実行します。
+
 - `.env.sample` ファイルを `.env` に改名します。
 ```bash
 mv .env.sample .env
@@ -42,18 +45,8 @@ WORKSPACE="azureml"
 LOCATION="japaneast"
 SUBSCRIPTION="xxxxxxxxxxx"
 ```
-## GitHub Actions のシークレット作成
-- GitHub Actions のシークレットを作成します。
-   - GROUP: Azure Machine Learning ワークスペースのリソースグループ名
-   - WORKSPACE: Azure Machine Learning ワークスペースの名前
-   - SUBSCRIPTION: Azure サブスクリプションID
-   - AZURE_CREDENTIAL: Azure の接続情報
-      - Azure Service Principal を利用する想定で書かれています。技術的には OpenID Connect の利用も可能ですが、本ドキュメントやコードは Azure Service Principal を利用することを前提に作成されています。
-      - 資格情報とそれをシークレット AZURE_CREDENTAL に設定する詳細な方法は [Azure Machine Learning で GitHub Actions を使用する - 手順2. Azure での認証](https://learn.microsoft.com/ja-JP/azure/machine-learning/how-to-github-actions-machine-learning?tabs=userlevel#step-2-authenticate-with-azure) をご参照ください。
-
-
 
-## シェルスクリプトの実行
+### シェルスクリプトの実行
 - `コンピューティングインスタンス` のターミナル上で、[scripts](../scripts) フォルダの各シェルスクリプトを実行します。
    - Azure CLI ログイン
       - `az login --use-device` コマンドで Azure CLI 認証を行います。
@@ -79,26 +72,51 @@ SUBSCRIPTION="xxxxxxxxxxx"
       - [deploy-batch-endpoint-custom.sh](../scripts/endpoints/deploy-batch-endpoint-custom.sh): カスタム型モデルのオンラインエンドポイントへのデプロイ
       - [deploy-batch-endpoint-mlflow.sh](../scripts/endpoints/deploy-batch-endpoint-mlflow.sh): MLflow 型モデルのオンラインエンドポイントへのデプロイ
 
-### E2E のスクリプト実行例
+#### E2E のスクリプト実行例
 
 ```bash
-bash ./scripts/setup.sh
+# Azure ログイン認証
 az login --use-device
+
+# Python 環境の構築、Jupyter カーネルの設定、pre-commit 設定、Azure CLI インストール
+bash ./scripts/setup.sh
+
+# 環境変数の読み込みと Azure CLI の設定
 bash ./scripts/configure-workspace.sh
 
+# Notebook の実行
 bash ./scripts/prototyping/run-notebooks.sh
 
+# アセット (計算環境、データアセット、環境) の作成
 bash ./scripts/assets/create-compute.sh
 bash ./scripts/assets/create-data.sh
 bash ./scripts/assets/create-environment.sh
 
+# Job の実行
 bash ./scripts/jobs/train.sh
 
-bash ./scripts/assets/register-model.sh
+# モデルの登録
 bash ./scripts/assets/register-model.sh
 
+# 推論環境の構築
 bash ./scripts/endpoints/deploy-online-endpoint-custom.sh
 bash ./scripts/endpoints/deploy-online-endpoint-mlflow.sh
 bash ./scripts/endpoints/deploy-batch-endpoint-custom.sh
 bash ./scripts/endpoints/deploy-batch-endpoint-mlflow.sh
 ```
+
+---
+
+## 2. CI/CD の実行
+
+### GitHub Actions のシークレット作成
+- GitHub Actions のシークレットを作成します。
+   - GROUP: Azure Machine Learning ワークスペースのリソースグループ名
+   - WORKSPACE: Azure Machine Learning ワークスペースの名前
+   - SUBSCRIPTION: Azure サブスクリプション ID
+   - AZURE_CREDENTIALS: Azure の接続情報
+      - Azure Service Principal を利用する想定で書かれています。技術的には OpenID Connect の利用も可能ですが、本ドキュメントやコードは Azure Service Principal を利用することを前提に作成されています。
+      - 資格情報とそれをシークレット AZURE_CREDENTAL に設定する詳細な方法は [Azure Machine Learning で GitHub Actions を使用する - 手順2. Azure での認証](https://learn.microsoft.com/ja-JP/azure/machine-learning/how-to-github-actions-machine-learning?tabs=userlevel#step-2-authenticate-with-azure) をご参照ください。
+
+### GitHub Actions の有効化と実行
+Fork 先の GitHub のページ内の `Actions` タブにアクセスし、GitHub Actions を有効化します。詳細は [GitHub アクション - ワークフローの無効化と有効化](https://docs.github.com/ja/actions/managing-workflow-runs/disabling-and-enabling-a-workflow) をご確認ください。