18 バンドルとCI/CD(プレビュー)
バンドルでは、Oracle AI Data Platform Workbenchリソースが、ワークスペースおよび環境間でパッケージ化、バージョニング、共有およびデプロイされる方法を定義します。
ジョブおよびエージェントのバンドルを作成できます。バンドル・ファイルをコミットしてGitリポジトリにプッシュできるように、バンドルはGitフォルダに作成されます。バンドルに含めるリソースは、ワークスペース内の任意の場所から取得できます。選択したリソースが、ノートブック、スクリプト、コンピュートなどのサポート・ファイルまたは依存関係を参照する場合、それらの参照はバンドルに含まれているため、リソースは、同じコンポーネントを手動で再作成せずに別の環境にデプロイできます。
ワークスペースからバンドルを作成し、作成時に含めるOracle AI Data Platform Workbenchリソースを選択します。既存のバンドルを変更して、リソースを追加または削除できます。リソースをバンドルすると、関連するジョブとエージェントをグループ化し、依存関係をそのまま他の環境にデプロイできます。
Gitフォルダを使用して、バンドルをコミットしてGitリポジトリにプッシュできます。その後、ユーザーはバンドルを独自の環境にプルしてデプロイできます。バンドル・ファイルへの変更は、変更がコミットされてGitリポジトリにプッシュされた後、他の環境で使用できます。ユーザーがGitリポジトリから更新されたバンドルをプルするたびに、最新のコミット済リソース・ファイルを受け取ります。
バンドルの概念
| コンセプト | 意味 | ユーザー・アクション |
|---|---|---|
| Gitフォルダ | Gitリポジトリおよびブランチに接続されたAI Data Platformフォルダ。バンドルはGitフォルダでのみ作成できます。 | バンドルを作成する前に、Gitフォルダを作成または開きます。 |
| Bundle | 選択したリソースとその依存関係を定義する、デプロイ可能なパッケージ。 | ワークスペースからバンドルを作成し、ジョブやエージェント・フローなどのリソースを選択します。 |
| バンドルのコンテンツ | デプロイメントに必要なリソース、変数、ターゲット設定およびアーティファクトを記述する生成済ファイル。 | 作成または同期後に生成されたコンテンツをレビューします。準備ができたら、バンドルをコミットしてGit経由でプッシュします。 |
| Target | ソース環境の外部にバンドルをデプロイするときに使用される環境またはワークスペースの構成。 | ワークスペース・キー、資格証明名、トークン・キー、パラメータのデフォルトなど、環境によって変更する必要がある値を指定します。 |
| デプロイ済項目 | ターゲット・ワークスペースのバンドル・デプロイメントによって作成または更新されたリソース。 | 「デプロイメント」タブを使用して、デプロイ済アイテムのデプロイ、確認、ジョブの実行およびデプロイ済リソースのパージを必要に応じて行います。 |
| 同期 | バンドル・リソースおよび依存関係を最新のソース・リソースからリフレッシュするバンドル・アクション。 | バンドル・リソースの変更後に同期を実行し、リフレッシュしたバンドル・ファイルをGitにコミットします。 |
はじめに
- Git資格証明と、バンドル・ファイルに使用されるリポジトリおよびブランチを指すGitフォルダを作成します。
- バンドルを作成または同期する前に、ソース・リソースがワークスペースに存在し、保存されていることを確認します。
- 環境間デプロイメントの場合は、ターゲット・ワークスペースに必要な権限およびコンピュート容量があることを確認します。
- シークレットを使用するジョブまたはノートブックの場合、ターゲット資格証明ストアで必要な名前付き資格証明を作成します。バンドル・ファイルは、シークレット値を含まない名前または変数で資格証明を参照する必要があります。
- バンドルを作成または同期した後、バンドル・ファイルの変更をコミットおよびプッシュして、他の環境で最新のバンドル定義をプルできるようにします。
バンドル作成後に生成される内容(プレビュー)
バンドル作成後、Oracle AI Data Platformによって生成されたファイルがバンドル・フォルダに書き込まれます。
正確なファイル名はリソース・タイプによって異なりますが、作成されたバンドルには通常、最上位のバンドル・マニフェスト、リソース定義、アーティファクト・フォルダおよびオプションのオーバーライド・ファイルが含まれます。
| 生成済品目 | 説明 |
|---|---|
aidp_workbench.yaml |
バンドル・マニフェスト。デプロイメント時に使用されるバンドル、含まれるリソース、変数およびターゲット・セクションを識別します。 |
.aidp/resource_origins.yaml |
リソースを定義します。ジョブ、ノートブック・タスク、コンピュート参照、エージェント・フローなどのリソースの説明。 |
.aidp/overrides.yaml |
ファイルまたはターゲット・セクションをオーバーライドします。ワークスペース識別子、パラメータ・デフォルト、資格証明名、トークン・キーなど、環境によって異なる値を保持します。 |
.aidp/aidp.state.json |
バンドルからデプロイされたリソースを追跡します。将来のデプロイおよびパージ操作で使用されます。 |
jobs/ |
ジョブ記述子およびジョブの依存性。 |
agentflows/ |
エージェント記述子とエージェントの依存関係。 |
artifacts/ |
アーティファクト・フォルダ。コード、ノートブックおよびサポート・ファイル・アーティファクトがコピーされました。 |
バンドルの同期(プレビュー)
バンドルを同期して、最新の変更でバンドルのリソースおよび依存関係を更新できます。
Syncでは、バンドルの記録されたオリジン・メタデータを使用して、バンドルの作成時に取得されたソース・ジョブおよびエージェント・フローからバンドルを再構築します。ソース・メタデータは.aidp/resource_origins.yamlに格納され、リクエストされたインスタンスおよびワークスペースと一致する必要があります。この操作は、バンドル・アイデンティティおよびランタイム・メタデータを保持しながら、ソース制御バンドル・コンテンツをリフレッシュします。
同期中、サービスは、リフレッシュされたバンドル・スナップショットをバンドル.aidpディレクトリにステージングし、既存の記述子とステージングされた記述子を比較し、既存の変数別名を保持し、可能な場合は参照をオーバーライドし、既存のマニフェストのデフォルト変数をマージしてから、リフレッシュされたソース制御ファイルをバンドル・ルートに戻します。
同期は、.aidp/overrides.yamlや.aidp/aidp.state.jsonなどの環境固有のデプロイメント・ランタイム・ファイルを保持します。これらのファイルは、リフレッシュされたソース・スナップショットで置き換えられません。
- ソース・ワークスペースで、バンドルされたノートブック、ジョブ、エージェント・フロー、コンピュート参照、パラメータまたは依存関係が変更されました。
- バンドル・ジョブが別のノートブックを指すようになったか、タスク・パラメータが更新されました。
- エージェント構成、プロンプト・パラメータ、モデル設定またはAIコンピュート依存性が変更されました。
- 別の環境にプッシュする前に、Gitフォルダに最新の生成されたバンドル・ファイルが含まれている必要があります。
- ワークスペースで同期するバンドルに移動します。
- 「アクション」をクリックします。
- 「Sync」をクリックします。同期が完了すると通知されます。
バンドルの推奨プロモーション・ワークフロー
Oracle AI Data PlatformのGitバンドルの開発、パッケージ化、バージョン管理、プル、構成、デプロイおよび検証のワークフローに従うことをお薦めします。
| フェーズ | アクション | 結果 |
|---|---|---|
| 開発 | ソース・ワークスペースでノートブック、ジョブ、コンピュート設定またはエージェント・フローを作成または更新します。 | ソース・リソースには、最新の意図した動作が含まれています。 |
| パッケージ | バンドルを作成するか、既存のバンドルで同期を実行します。 | 生成されたバンドルファイルには、現在のソースリソースと依存関係が反映されます。 |
| Version | バンドル・フォルダを確認してコミットし、Gitフォルダにプッシュします。 | リモート・リポジトリには、デプロイ可能なバンドル定義が含まれます。 |
| プル | ターゲット・ワークスペースで、Gitフォルダの変更をプルします。 | ターゲット・ワークスペースには最新のバンドル・ファイルがあります。 |
| 構成 | ワークスペース・キー、パラメータ・デフォルト、資格証明名、トークン・キー、ランタイム設定などのターゲット固有の値を設定します。 | バンドルはターゲット環境の準備ができています。 |
| デプロイ | バンドルの「デプロイメント」タブを開き、「デプロイ」をクリックします。 | ワークベンチは、デプロイされたリソースを作成または更新します。 |
| Validate | デプロイされたジョブを実行するか、デプロイされたエージェント・フローをテストし、ログまたは出力を検査します。 | ターゲット環境は、昇格が続行される前に検証されます。 |
バンドル変数(プレビュー)
バンドルで、リソース定義を編集せずにすべてのターゲット環境で変更できるデプロイ時の値が必要な場合は、バンドル変数を使用します。
バンドルでの変数の使用を開始するには、バンドルのaidp_workbench.yamlファイルで変数名をデフォルト値で定義し、必要に応じて環境固有のオーバーライドを定義する必要があります。次に、生成された定義ファイルからこれらの変数を参照します。
変数のワークフローの例
aidp_workbench.yamlのdefaults > variablesの下に変数名を定義します。- オプションで、環境固有の値を
targets > <environment> > variablesの同じaidp_workbench.yamlファイルに定義します。 - ターゲット・オーバーライドを使用して、開発リージョン、QAリージョン、本番リージョン、スキーマ名、資格証明名、トークン・キー、パラメータのデフォルトなどのデプロイ時の値を設定します。
- 一致するターゲット環境が見つからない場合、Oracle AI Data Platformはaidp_workbench.yamlのデフォルト変数値を使用します。
- ジョブ定義、コンピュート定義、タスク定義、その他のYAML定義ファイルなど、生成された定義ファイルで変数を使用します。
- 変数を${var.<<variable_name>>}で参照し、<<variable_name>>をaidp_workbench.yamlで定義された実際の変数名に置き換えます。
- UIで名前付きプレースホルダが想定される場合は、エージェント・プロンプトやツール定義などの場所でリソース固有のプレースホルダ構文を使用します。
- 一時的なデプロイメントのみの変更の場合は、.aidp/overrides.yamlを作成し、そこに変数値を定義します。
バンドル変数の構文
変数定義は、aidp_workbench.yamlに記述する必要があります。その他のバンドル定義ファイルは、変数名のみを参照する必要があります。
| 定義 | 構文 | 例 |
|---|---|---|
aidp_workbench.yamlの変数定義
|
|
|
aidp_workbench.yamlのターゲット固有のオーバーライド |
|
|
| 定義ファイル内の変数参照 | ${var.<<variable_name>>} |
value: "${var.deployment_region}" |
| エージェント・プロンプトまたはツール・フィールドの名前付きプレースホルダ | {{variable_name}} |
Generate a summary about {{topic}}. |
例: ジョブ・パラメータ変数
bundle:
name: namedVariableJobDemo
resources:
jobs:
- namedVariableJobDemo
defaults:
variables:
job_param_value_default: "cloud data governance"
jobs:
namedVariableJobDemo:
tasks:
- taskKey: Task_956691
parameters:
- name: param_key
value: "${var.job_param_value_default}" ノートブック・タスクでは、ジョブで使用されるパラメータ名を使用して解決された値を読み取ることができます:
param_value = odiUtils.parameters.getParameter("param_key", "fallback value")
print(param_value)例: aidp_workbench.yaml変数の定義
aidp_workbench.yamlの変数agent_topic_defaultを定義します。デフォルト値は、一致するターゲット環境が見つからない場合、または選択した環境または一時オーバーライドによって変数が提供されない場合に適用されます。各ターゲットは、そのワークスペースの同じ変数名をオーバーライドできます。defaults:
variables:
agent_topic_default: "Oracle AI Data Platform"
targets:
dev:
- aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampledev"
workspace_key: "6271b138-6f2c-4e8c-a9e5-013e17079955"
variables:
agent_topic_default: "AIDP Dev Workspace"
qa:
- aidp_ocid: "ocid1.aidataplatformdev.oc1.iad.exampleqa"
workspace_key: "daa0e9b5-f8d7-4ae8-b728-2984e68a74c0"
variables:
agent_topic_default: "AIDP QA Workspace"
prod:
- aidp_ocid: "ocid1.aidataplatform.oc1.iad.exampleprod"
workspace_key: "83be5b8c-bb8d-4ec4-a8fb-16b50b0e4d4c"
variables:
agent_topic_default: "AIDP Production Workspace" バンドル変数をサポートするバンドル定義ファイルは、同じ変数名を参照できます。たとえば:
tasks/agentTopic.task.yaml
parameters:
- name: topic
value: "${var.agent_topic_default}"例: ファイル名と解像度
testNamedVarBundleJob/
aidp_workbench.yaml
jobs/
namedVariableJobDemo.job.json
artifacts/
namedVarNotebookDemo.ipynb| File | 内容 | 変数または解決済の値 |
|---|---|---|
aidp_workbench.yaml |
「デフォルト」→「変数」およびオプションのターゲット・オーバーライドで変数を定義します。 | 変数: job_param_value_default。
|
jobs/namedVariableJobDemo.job.json |
この変数をジョブ・パラメータparam_keyの値として使用します。 | 参照: ${var.job_param_value_default}。
|
artifacts/namedVarNotebookDemo.ipynb |
実行時に解決されたジョブ・パラメータを読み取ります。 | ノートブックは、解決後にparam_keyを読み取ります。
|
aidp_workbench.yamlでデフォルトおよびターゲット・オーバーライドを定義できます。defaults:
variables:
job_param_value_default: "cloud data governance"
targets:
dev:
variables:
job_param_value_default: "space tourism"
qa:
variables:
job_param_value_default: "data quality validation"
prod:
variables:
job_param_value_default: "customer operations"ジョブ定義では、jobs/namedVariableJobDemo.job.jsonで同じ変数名を使用できます。同じ構文をジョブ定義、コンピュート定義、タスク定義、およびバンドル変数をサポートするその他の生成されたYAML定義ファイルで使用できます。
"parameters": [
{
"name": "param_key",
"value": "${var.job_param_value_default}"
}
]| デプロイ・ターゲット | 変数解決 | ノートブック受信 |
|---|---|---|
| 一致するターゲットがありません | helpp_workbench.yamlからデフォルトを使用します。 | param_key = cloud data governance
|
| dev | 開発ターゲット・オーバーライドを使用します。 | param_key = space tourism
|
| qa | qaターゲット・オーバーライドを使用します。 | param_key = data quality validation |
| 本番 | 製品ターゲット・オーバーライドを使用します。 | param_key = customer operations |
解決順序
.aidp/overrides.yamlが変数値を指定する場合、AI Data Platformは次のデプロイメントにその一時値を使用します。それ以外の場合は、AIデータ・プラットフォームによって、選択したターゲットから最初に変数が解決されます。一致するターゲット環境が見つからないか、選択したターゲットが変数をオーバーライドしない場合、AIデータ・プラットフォームはaidp_workbench.yamlのdefaults > variablesにフォールバックします。参照される変数に使用可能な値がない場合、ノートブック・フォールバック値が使用される前にデプロイメントまたはジョブの実行が失敗する可能性があります。
次のデプロイメントの一時オーバーライド
通常のバンドル・プロモーションでは、aidp_workbench.yamlの定義で十分です。ユーザーが変数を一時的にオーバーライドする必要がある場合は、バンドル・フォルダに.aidp/overrides.yamlを作成し、そこに変数値を定義します。AIデータ・プラットフォームでは、次のデプロイメント時にこれらの値が使用されます。
.aidp/
overrides.yamlvariables:
agent_topic_default: "tuesday"| File | 値の例 | 使用時 |
|---|---|---|
aidp_workbench.yaml defaults
|
Oracle AI Data Platform | 一致するターゲットまたはオーバーライド・ファイルが変数を提供しない場合に使用されます。 |
aidp_workbench.yaml target dev |
AIDP開発ワークスペース | 開発にデプロイする場合に使用され、一時オーバーライドは存在しません。 |
.aidp/overrides.yaml |
tuesday | 次のデプロイメント中に一時的な値として使用されます。 |
ノート:
一時デプロイメント値には.aidp/overrides.yamlを使用します。aidp_workbench.yamlに恒久的なデフォルト値および環境固有の値を保持して、バンドルをGitを介して再現できるようにします。
例: エージェント・プロンプト変数
名前付きプレースホルダをサポートするエージェント・フロー・プロンプト・テキストまたはツール定義の場合は、変数名を二重中カッコで囲みます。
Prompt text:
You are a demo assistant. For the given {{topic}}, generate 3 short bullet points explaining why it matters.
Tool parameter:
Name: /{{topic}}
Default value: sunday ノート:
ベスト・プラクティスとして、デプロイメント間で変更されることが予想される値に変数を使用する必要があります。変数がかわりに値を保持できる場合は、環境固有の値をノートブック、ジョブまたはエージェント・フロー・テキストに直接埋め込まないでください。例: コンピュートなしのワークフロー
デプロイメントの一部としてコンピュート・クラスタを自動的に作成しないワークフローのバンドルを作成できます。まず、aidp_workbench.yamlに変数を作成します。
defaults:
variables:
job_compute_key: "select_compute"jobs/フォルダで、ジョブ・ファイル<JobName>.job.jsonを見つけます。ジョブ・ファイルを編集し、"clusterKey"値を新しく作成した変数に置き換えます。"clusterKey" : "${var.job_compute_key}",バンドル変数および資格証明ストア(プレビュー)
バンドルされたジョブまたはノートブックが実行時にシークレットを検索する必要がある場合、資格証明ストアで変数を使用できます。
変数には、資格証明名とトークン・キーが必要です。実際のシークレット値は、ターゲット資格証明ストアにとどまる必要があり、Gitにコミットしないでください。
ワークフローの例: 資格証明ストアでの変数の使用
- 資格証明ストアに資格証明およびトークン・キーを作成します。
- 資格証明名およびトークン・キーの変数を定義します。
- これらの変数をパラメータとしてジョブまたはノートブックに渡します。
- 実行時に、ノートブックはパラメータを読み取り、資格証明APIをコールしてシークレットを取得します。資格証明名、トークン・キーまたは権限が間違っている場合、ジョブは資格証明検索エラーで失敗する可能性があります。
ノート:
バンドル・ファイル内のシークレット値をドキュメント化またはコミットしないでください。バンドル構成は、資格証明名、トークン・キーおよびターゲット変数を参照する必要があります。資格証明ストアはシークレット・マテリアルのソースのままです。例: 資格証明名およびトークン・キー変数
bundle:
name: credentialVariableDemoBundle
resources:
jobs:
- credentialLookupJob
defaults:
variables:
cred_key: default_credential_name
token_key: default_token_key
targets:
dev:
workspace_key: dev_workspace
variables:
cred_key: dev_credential_store_entry
token_key: dev_token
qa:
workspace_key: qa_workspace
variables:
cred_key: qa_credential_store_entry
token_key: qa_token
prod:
workspace_key: prod_workspace
variables:
cred_key: prod_credential_store_entry
token_key: prod_token
jobs:
credentialLookupJob:
tasks:
- taskKey: Task_854239
parameters:
- name: cred_key
value: "${var.cred_key}"
- name: token_key
value: "${var.token_key}" ノートブックはパラメータ値を読み取り、それらを使用して資格証明ストアからシークレットを検索します:
cred_name = odiUtils.parameters.getParameter("cred_key", "defaultCredValue")
token_name = odiUtils.parameters.getParameter("token_key", "defaultTokenValue")
secret = aidpUtils.secrets.get(name=cred_name, key=token_name)
if secret:
print("Credential lookup succeeded")
else:
raise Exception("Credential lookup failed")| 環境 | cred_key値 | token_key値 | 資格証明ストアの要件 |
|---|---|---|---|
| dev | 開発_資格証明_ストア_エントリ | 開発トークン | キーdev_tokenを使用してdev_credential_store_entryを作成します。 |
| qa | 個人情報保護方針 | トークン | キーqa_tokenを使用してqa_credential_store_entryを作成します。 |
| 本番 | プロッド資格証明ストア・エントリ | prodトークン | prod_tokenキーを使用してprod_credential_store_entryを作成します。 |
バンドルのパージ(プレビュー)
デプロイされたバンドルをパージして、ワークスペースからバンドル・リソースを削除できます。
- ワークスペース内のリソースをパージするバンドルに移動します。
- 「Deployment」タブをクリックします。
- 「パージ」をクリックします。
- プロンプトに「パージ」と入力します。「パージ」をクリックします。
バンドルのトラブルシューティング(プレビュー)
Gitバンドルを作成および管理するときに問題が発生した場合は、次の問題のリストで解決策を確認してください。
| 症状 | 発生の可能性 | 推奨処理 |
|---|---|---|
| バンドルの作成が使用できないか、バンドルを作成できません。 | ユーザーがGitフォルダにいないか、必要なワークスペース権限がありません。 | Gitフォルダに移動し、ユーザーがワークスペース・リソースを作成できることを確認します。 |
| 同期は完了しますが、別の環境では更新は表示されません。 | リフレッシュされたバンドル・ファイルは、コミット、プッシュまたはターゲットGitフォルダにプルされませんでした。 | ソースGitフォルダをコミットしてプッシュしてから、デプロイする前にターゲット・ワークスペースをプルします。 |
| 「デプロイメント」タブには、デプロイ済アイテムが表示されません。 | バンドルがまだデプロイされていないか、デプロイメントが正常に完了しませんでした。 | 「デプロイ」をクリックし、完了通知を待ちます。デプロイメントが失敗した場合は、ログを確認します。 |
| デプロイされたジョブが資格証明参照エラーで失敗します。 | ターゲット資格証明名、トークン・キーまたはアクセス権限がバンドル構成と一致しません。 | ターゲット資格証明ストアに資格証明を作成するか、ターゲット変数を更新してから再デプロイしてください。 |
| エージェント・フローのデプロイメントが失敗するか、非アクティブ・コンピュートで開始します。 | ターゲット環境には、互換性のあるAIコンピュート、リージョン、モデルまたは依存関係の設定がない場合があります。 | ターゲットのオーバーライド、計算ステータス、モデルの可用性およびデプロイメント・ログを確認します。 |
| ソース・ノートブックまたはエージェント・フローへの変更は、デプロイメント後に反映されません。 | バンドルは、最初に更新されたソース・リソースから同期せずにデプロイされました。 | バンドルで同期を実行し、リフレッシュしたバンドル・ファイルをコミットしてプッシュし、ターゲットにプルしてから、再度デプロイします。 |