Azure SDK documentation update: [DRAFT] adding generated and custom code for custom training は、Azure SDK for Python の azure-ai-projects に Training Jobs / CommandJob を扱うための生成コードとカスタムコードを追加するドラフトPRです。結論から言うと、今すぐ本番移行を急ぐ更新ではありません。まず確認すべきなのは、client.beta.training.jobs という新しい操作面、CommandJob の必須項目、プレビュー機能ヘッダー、ローカルコードや入力データの自動アップロード、削除・キャンセルの非同期処理です。PRはドラフトかつオープン状態で、2026年5月5日にも「生成ジョブコード」やmainブランチ追従に関するコミットが追加されています。(GitHub)
Azure AI Foundryや azure-ai-projects SDKで学習ジョブを自動化しているチーム、または azure-ai-ml からFoundry寄りの実装へ移行を検討している開発者は、正式リリースを待つだけでなく、いまのうちにジョブ定義・データ配置・CIテストの見直しを始めると安全です。
Azure SDK documentation updateの要点：custom trainingで何が変わるのか
今回のAzure SDK documentation updateで注目すべき点は、Azure AI Projects SDKからトレーニング用のCommand Jobを扱いやすくする方向に進んでいることです。PRの説明では、同期クライアントは client.beta.training.jobs、非同期クライアントは async_client.beta.training.jobs 配下で、学習ジョブの作成、取得、一覧、更新、キャンセル、削除を扱えるようにする意図が示されています。(GitHub)
ただし、ここでいう「custom training」は、単にモデルのファインチューニングAPIを呼ぶ話ではありません。コンテナ上で実行するコマンド、入力データ、出力先、コンピュート、分散設定、リソース設定などをまとめて定義し、Azure AI Foundryのプロジェクト文脈でトレーニングジョブとして実行する仕組みです。
特に実務で重要なのは、SDK利用者がREST APIの外側にある Job(properties=...) のようなワイヤ形式を直接意識しなくてよい設計が入っている点です。PRでは、呼び出し側が CommandJob をそのまま渡し、SDK側で必要なラップ・アンラップを行う方針が説明されています。(GitHub)
変更点の全体像
| 確認ポイント | 変更内容 | 実務で見るべきこと |
|---|---|---|
| SDKの操作面 | client.beta.training.jobs / async_client.beta.training.jobs でTraining Jobsを扱う | 既存のジョブ作成ラッパーやCI/CDスクリプトをどこに接続するか確認する |
| ジョブモデル | CommandJob を中心に、コマンド、環境イメージ、コンピュート、入出力などを定義 | 必須項目をコードレビューのチェックリストに入れる |
| プレビュー機能 | Foundry-Features: Jobs=V1Preview が関係する | 手動ヘッダー追加が必要か、SDKが自動注入するかを利用バージョンで確認する |
| ローカルパス | code や inputs のローカルファイル・フォルダをデータセット資産として扱う方針 | 誤って不要ファイルや機密ファイルをアップロードしないようにする |
| タイムアウト | CommandJobLimits.timeout で数値秒数や timedelta を扱うカスタム処理 | 「秒」なのか「期間」なのかをチーム内で明確にする |
| 削除・キャンセル | delete / cancel は非同期処理として扱われる | ポーリング、リトライ、監査ログの実装を確認する |
| テスト | 入力検証やヘッダー注入、パス解決などのテストが重要 | 単体テストだけでなく、小さな実データでの検証を入れる |
関連するTypeSpec PRでは、Training Jobs API surfaceがAzure AI Foundry data-plane TypeSpecに追加され、Foundry-Features: Jobs=V1Preview のプレビュー機能として扱われること、SDKでは client.beta.training.jobs から利用する想定であることが説明されています。操作としては list、get、create_or_update、begin_delete、begin_cancel が挙げられています。(GitHub)
対応すべき人と、まだ様子見でよい人
今回の更新で優先的に確認すべきなのは、Azure AI Foundry上で学習ジョブをコードから作成・管理したい開発チームです。特に、ジョブの起動をGitHub Actions、Azure DevOps、社内MLOps基盤、Pythonスクリプトから自動化している場合は影響を受ける可能性があります。
早めに確認すべきケース
azure-ai-projectsを使ってAzure AI Foundryプロジェクトを操作しているazure-ai-mlのCommand Jobに近い操作感でFoundry側へ移行したい- トレーニング用のコードやデータをローカルパスからアップロードしている
- ジョブのキャンセル、削除、一覧取得、状態確認を自動化している
- GPU、分散学習、コンテナイメージ、出力アセット登録をジョブ定義に含めている
いまは影響が小さいケース
エージェント作成、検索インデックス、評価、データセットアップロードだけを使っていて、トレーニングジョブを作成していない場合は、今回のTraining Jobs追加による直接影響は限定的です。ただし azure-ai-projects 全体のバージョンアップ時には、認証、プレビュー機能、モデル定義のimportパスが変わる可能性があるため、依存パッケージの更新を自動で流している環境ではリグレッションテストを残しておくべきです。
CommandJobで確認すべき必須項目
TypeSpec側の説明では、CommandJob の必須項目として command、environmentImageReference、compute が示されています。command はコンテナ内で実行するシェルコマンド、environmentImageReference はACR/MCRなどのDockerイメージ参照、compute はコンピュートリソースIDです。(GitHub)
PRのSDK側説明では、create_or_update の前に name、command、environment_image_reference、compute が空でないことを検証し、不明瞭なHTTP 400ではなく ValueError として早めに返す方針が示されています。(GitHub)
| 項目 | 役割 | 失敗しやすいポイント |
|---|---|---|
name | ジョブ名 | CIで同名ジョブを再実行したときの上書き・衝突 |
command | 実行コマンド | 入力・出力変数の参照ミス、作業ディレクトリ違い |
environment_image_reference | 実行環境のコンテナイメージ | private registryの認証、CUDAやPythonバージョン不一致 |
compute | 実行先コンピュート | GPU SKU不足、権限不足、リージョン不一致 |
inputs | 学習データやパラメータ | ローカルパスとURIの混在、意図しないファイルアップロード |
outputs | モデルや成果物の保存先 | 出力パスの上書き、資産名の命名ルール不統一 |
limits.timeout | 実行時間制限 | 秒数指定と期間指定の取り違え |
ローカルパス自動アップロードは便利だが、運用ルールが必要
今回のPRでは、code または入力の path がローカルファイル・フォルダの場合、SDKがデータセット資産としてアップロードし、リクエスト送信前にデータストアURIへ差し替える設計が説明されています。さらに、name:version や azureai:name:version のような短縮形を既存データセットのURIへ解決する処理も示されています。(GitHub)
これは開発者体験としては大きな改善です。たとえば、手元の ./src と ./data/train.csv を指定して学習ジョブを作る場合、毎回データセット登録やURI取得を手動で行わずに済む可能性があります。
一方で、実務では次の点に注意が必要です。
| 注意点 | 具体例 | 対策 |
|---|---|---|
| 不要ファイルの混入 | .venv、キャッシュ、巨大ログを含むフォルダを指定する | 学習用コードだけを切り出した専用ディレクトリを使う |
| 機密情報の混入 | .env、APIキー、接続文字列を含む | アップロード対象フォルダに秘密情報を置かない |
| データサイズ増加 | 毎回大きなデータを再アップロードする | 本番では登録済みデータセットURIを使う |
| 環境差 | ローカルでは存在する相対パスがCIでは存在しない | CI上の作業ディレクトリとパスを固定する |
| 再現性低下 | name:version の解決先を曖昧に扱う | 本番ジョブではバージョンを明示し、ログに解決後URIを残す |
便利な自動化ほど、検証環境では成功しても本番運用で事故が起きやすくなります。特に学習データやコードを自動アップロードする場合は、「どのファイルがクラウドに送られるか」をレビュー対象に含めるべきです。
プレビュー機能ヘッダーと.betaの扱い
この更新では Foundry-Features: Jobs=V1Preview が重要です。PRでは、Training Jobs関連の操作でこのプレビュー機能ヘッダーをSDK側が自動注入し、利用者がカスタムヘッダーとして手動指定しなくてよい設計が説明されています。(GitHub)
一方、現在のAzure AI Projects APIリファレンスでは、.beta サブクライアントのメソッドはプレビュー扱いであり、.beta という名前に含意されるため allow_preview=True を必ずしも要求しない旨の記述があります。(Microsoft Learn)
ここで混同しやすいのは、.beta と Foundry-Features は同じ概念ではないことです。.beta はSDKのプレビュー操作面を示し、Foundry-Features はサービス側の機能フラグとして使われます。SDKが自動注入する設計であっても、障害調査やAPI差分確認のために、HTTPログやテストでヘッダーの有無を確認できるようにしておくと安心です。
既存のazure-ai-ml利用者が見るべき移行観点
PRの説明では、現在 azure-ai-ml を使っている利用者にとって馴染みのあるパターンやメンタルモデルにすることで、Azure AI Foundryへの移行を小さなステップにする狙いが示されています。(GitHub)
ただし、これは「azure-ai-ml のコードをそのまま置き換えられる」という意味ではありません。移行時は、次のように分解して確認するのが現実的です。
azure-ai-mlで見ていた観点 | azure-ai-projects側で確認する観点 |
|---|---|
| command jobの定義 | CommandJob のフィールド名、必須項目、入出力モデル |
| 環境 | environment_image_reference に指定するコンテナイメージ |
| compute | Foundryプロジェクトで参照できるcompute ID |
| inputs / outputs | URI、ローカルパス、データセット短縮形の扱い |
| limits | CommandJobLimits.timeout の単位と型 |
| 非同期処理 | begin_cancel、begin_delete のポーリング |
| SDKヘルパー | 将来的に追加予定とされる command() ファクトリ関数の有無 |
PRでは、azure-ai-ml のトップレベル command() 関数に近いヘルパーを今後追加する予定も挙げられています。現時点では、正式に入るまでは CommandJob を直接構築する形を前提に検証したほうが安全です。(GitHub)
実装イメージ：まずは小さなジョブで検証する
以下は、今回のPRで示されている考え方をもとにした検証用のイメージです。ドラフトPR段階の内容を含むため、正式リリース後はimport名、引数名、モデル名を必ずAPIリファレンスで確認してください。
import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import (
CommandJob,
CommandJobLimits,
Input,
Output,
AssetTypes,
InputOutputModes,
)
endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
compute_id = os.environ["FOUNDRY_COMPUTE_ID"]
project_client = AIProjectClient(
endpoint=endpoint,
credential=DefaultAzureCredential(),
)
job = CommandJob(
command="python train.py --epochs 3 --output ${{outputs.model_output}}",
environment_image_reference="mcr.microsoft.com/azureml/minimal-ubuntu22.04-py39-cuda11.8-gpu-inference",
compute=compute_id,
display_name="sample-training-job",
code="./src",
inputs={
"training_data": Input(
type=AssetTypes.URI_FILE,
path="./data/train.csv",
mode=InputOutputModes.READ_ONLY_MOUNT,
)
},
outputs={
"model_output": Output(
type=AssetTypes.URI_FOLDER,
mode=InputOutputModes.UPLOAD,
asset_name="sample-trained-model",
)
},
limits=CommandJobLimits(timeout=1800),
)
created_job = project_client.beta.training.jobs.create_or_update(
name="sample-training-job",
body=job,
)
print(created_job.name)この検証で見るべきポイントは、ジョブが成功するかどうかだけではありません。ローカルの ./src と ./data/train.csv がどのような資産として扱われるか、エラー時に ValueError とHTTPエラーのどちらが返るか、ジョブ削除やキャンセルがポーリング前提になるかを確認します。
設定確認のチェックリスト
正式な採用判断の前に、次の順番で確認すると手戻りを減らせます。
| 順番 | 確認項目 | 実施内容 |
|---|---|---|
| 1 | PRの状態 | ドラフトのままか、mainにマージ済みか、リリースノートに反映済みかを見る |
| 2 | パッケージバージョン | pip show azure-ai-projects で導入済みバージョンを確認する |
| 3 | エンドポイント | https://<resource-name>.services.ai.azure.com/api/projects/<project-name> 形式を使っているか確認する |
| 4 | 認証 | DefaultAzureCredential など、利用中の認証方式が対象バージョンでサポートされるか確認する |
| 5 | 必須フィールド | name、command、environment_image_reference、compute を空にしない |
| 6 | ローカルパス | アップロード対象に不要ファイルや秘密情報が入っていないか確認する |
| 7 | 入出力 | uri_file、uri_folder、literalなどの扱いをテストする |
| 8 | タイムアウト | 数値指定時の単位を秒としてチーム内で統一する |
| 9 | 非同期処理 | cancel/delete後のポーリングとログ出力を実装する |
| 10 | 本番移行 | 小さなデータ、短時間ジョブ、単一computeで検証してから拡大する |
Microsoft LearnのAzure AI Projectsクライアントライブラリページでは、azure-ai-projects はMicrosoft Foundry SDKの一部であり、Foundryプロジェクト内のリソースへアクセスするためのライブラリとして説明されています。前提条件としてPython、Azureサブスクリプション、Microsoft Foundryのプロジェクト、Foundryプロジェクトエンドポイントなどが示されています。(Microsoft Learn)
また、Microsoft Foundry SDKの概要では、Foundry SDKが単一のプロジェクトエンドポイントに接続すること、Pythonでは azure-ai-projects>=2.0.0 のインストールが案内されていることが確認できます。(Microsoft Learn)
2026年5月5日時点で特に見るべき差分
PRのファイル差分ページでは、2026年5月5日に adding more changes、merging with main、generating job code というコミットが並んでいます。つまり、この時点では単なるドキュメント記述だけでなく、生成コードやmainブランチ追従を含む作業が継続していたと読めます。(GitHub)
このような状態では、開発チームは次のように判断するのが現実的です。
| 状況 | 判断 |
|---|---|
| 本番環境で安定稼働中 | すぐに置き換えず、正式リリースとCHANGELOGを待つ |
| 新規PoCを開始する | 小さな検証ジョブでAPI形状とデータアップロードを確認する |
azure-ai-ml から移行検討中 | フィールド対応表を作り、差分を洗い出す |
| CI/CDで学習ジョブを回している | cancel/deleteの非同期処理と失敗時リトライを先に設計する |
| GPU学習を使う | compute、SKU、リソース設定、ジョブ制限を重点的に検証する |
関連するTypeSpec PRでは、4月28日に adding gpucount というコミットも確認できます。GPU数やリソース指定に関係する仕様は実務影響が大きいため、GPUワークロードを持つチームは最終的なモデル定義を必ず確認してください。(GitHub)
失敗しやすいポイント
ドラフトPRを正式仕様として扱ってしまう
今回のPRはタイトルに [DRAFT] が付いたオープンPRです。実装方針を読むには有用ですが、正式なSDKリリースや安定APIとして断定するのは危険です。依存パッケージを更新する場合は、PyPI、Microsoft Learn、GitHubのCHANGELOG、リリースノートを合わせて確認してください。
ローカルフォルダをそのままcodeに指定する
code="./" のようにプロジェクトルートを指定すると、不要なファイルをアップロードするリスクがあります。検証では動いても、CIではファイル数やサイズが増えて遅くなることがあります。src/train のようにアップロード対象を明確に分けるのが安全です。
timeout=7200の意味を共有しない
SDK側で数値秒数を受け付ける設計は便利ですが、チーム内で「ミリ秒」「分」「ISO 8601 duration」と混同すると事故につながります。設定ファイルやYAMLで管理する場合は、キー名を timeout_seconds のように明確にしておくとレビューしやすくなります。
name:version短縮形に頼りすぎる
データセットの短縮指定は便利ですが、本番ジョブでは「どのデータで学習したか」を後から追跡できることが重要です。最終的に解決されたURI、データセット名、バージョン、ジョブIDをログやメタデータに残しておきましょう。
cancelやdeleteを同期処理のように扱う
TypeSpec PRでは、削除とキャンセルは非同期で、HTTP 202とLocationヘッダーによるポーリングが関係することが説明されています。削除リクエストを送った直後に「消えた」とみなす実装は避け、完了確認まで含めた処理にしてください。(GitHub)
まず取るべき次のアクション
今回のAzure SDK documentation updateは、Azure AI FoundryでTraining Jobsを扱うためのSDK体験を改善する重要な動きです。ただし、2026年5月5日時点ではドラフトPRの更新内容を含むため、最初にやるべきことは本番コードの置き換えではありません。
まず、現在の学習ジョブ作成フローを棚卸ししてください。次に、CommandJob に対応するフィールド、ローカルパスの扱い、出力アセット、タイムアウト、キャンセル・削除処理を小さなサンプルで検証します。最後に、正式マージ後のSDKバージョン、APIリファレンス、CHANGELOGを確認し、CIテストに「必須フィールド不足」「ローカルパス解決」「非同期キャンセル」「出力登録」のケースを追加します。
この順番で進めれば、ドラフト段階の情報に振り回されず、Azure AI Foundryでのcustom training対応を安全に準備できます。
コメント