Azure REST API documentation update: Update model typespec in Foundry project SDKは、単なる表記修正ではなく、Microsoft FoundryのProject SDKで使われるModels関連のTypeSpec、OpenAPI出力、SDK生成設定に関わる更新です。結論から言うと、直接Azure REST APIを呼び出しているチーム、OpenAPI/TypeSpecから社内SDKを生成しているチーム、Foundryでモデルのアップロード・バージョン作成・LoRAアダプター管理を扱うチームは、リクエスト/レスポンスの形とSDKメソッド名を確認すべきです。一方、Azureポータルや既存の安定版SDKを通常利用しているだけであれば、まずは影響範囲の有無を確認するところからで問題ありません。
この更新は、Azure REST API仕様の正本にあたるAzure/azure-rest-api-specs上のPRをもとに確認するのが重要です。同リポジトリはMicrosoft AzureのREST API仕様のcanonical sourceと説明されており、仕様完成後にSDKやAPIリファレンス生成へつながる位置づけです。対象PRは「Update model typespec in Foundry project SDK」として、feature/foundry-stagingへのマージを目指すOpenなPRとして表示されています。(GitHub)
Azure REST API documentation updateでまず押さえるべきこと
今回の「Azure REST API documentation update: Update model typespec in Foundry project SDK」は、PR説明文だけを見るとテンプレート選択用の文言が残っており、変更内容を読み取るには不十分です。実務上は、PRのファイル差分、コミット履歴、レビューコメントを確認する必要があります。PRにはdata-planeとTypeSpecのラベルが付いており、対象は主にFoundryのdata plane APIです。(GitHub)
TypeSpecは、クラウドサービスAPIを記述し、OpenAPI仕様、クライアントコード、サービスコード、ドキュメントなどを生成するための言語です。Azure向けのTypeSpecライブラリは、Azure APIガイドラインに沿った仕様・SDK・ドキュメント生成を支援するために使われます。つまり、TypeSpecの変更は「ドキュメントだけ」ではなく、生成されるOpenAPI、SDKの型、メソッド名、リクエスト/レスポンスの検証にも影響する可能性があります。(Azure)
変更の全体像：Foundry Project SDKのModels関連が中心
PRのファイルツリーを見ると、主な変更はspecification/ai-foundry/data-plane/Foundry配下に集中しています。client.csharp.tsp、client.java.tsp、client.tsp、main.tsp、src/models/models.tsp、src/models/routes.tsp、OpenAPI v1とvirtual-public-previewのJSONなどが対象です。あわせてmachinelearningservices/data-plane/ModelDataplane配下の変更も含まれていますが、PRのタイトルは最終的にFoundry project SDKのModel TypeSpec更新へ絞られています。(GitHub)
| 確認領域 | 変更の見方 | 実務上のポイント |
|---|---|---|
| Foundry ModelsのTypeSpec | ModelVersionや関連モデルの定義が追加・整理されている | モデル作成、モデル更新、LoRA、警告情報を扱うコードに影響しやすい |
| Modelsのルート定義 | createAsync、startPendingUpload、getCredentialsなどの操作が定義されている | 直接REST呼び出しやSDK生成時に、メソッド・パス・HTTPメソッドを確認する |
| SDKクライアント設定 | C#、Java、Python/JavaScript向けクライアント設定にModelsルートが取り込まれている | 生成SDKのメソッド名やサブクライアント構成が変わる可能性がある |
| OpenAPI出力 | v1とvirtual-public-previewのOpenAPI JSONが対象 | OpenAPIから社内クライアントを生成するCIでは差分確認が必須 |
| Pending Upload関連 | TemporaryBlobReferenceなどアップロード関連型が見直されている | モデル/データセットのアップロード処理でデシリアライズエラーが起きないか確認する |
影響を受けやすいチーム
今回のAzure REST API更新で最も注意すべきなのは、FoundryのModels APIをアプリケーションや社内基盤から直接扱っているチームです。特に、モデル成果物をBlobに置き、モデルバージョンとして登録し、SDKから参照・削除・資格情報取得を行うようなワークフローでは、TypeSpecの変更がビルドや実行時の挙動に出やすくなります。
| 利用パターン | 対応の優先度 | 確認すべきこと |
|---|---|---|
curl、az rest、独自HTTPクライアントでFoundry REST APIを呼ぶ | 高 | パス、HTTPメソッド、必須フィールド、202応答、Locationヘッダー |
| OpenAPI/TypeSpecから社内SDKを生成している | 高 | 生成後の型名、列挙値、メソッド名、破壊的変更の有無 |
Python/JavaScriptのazure-ai-projects系SDKを追従している | 中〜高 | modelsサブクライアントやメソッド名の変更 |
| C#またはJava SDK生成設定を管理している | 中 | src/models/routes.tspの取り込みによる生成結果 |
| Foundryをポータル中心で使っている | 低〜中 | すぐにコード修正するより、利用SDKのリリースノート確認を優先 |
Microsoft LearnのFoundry RESTリファレンスでは、APIバージョンとしてv1が示され、認証スコープにhttps://ai.azure.com/.default、Projectエンドポイント形式にhttps://{ai-services-account-name}.services.ai.azure.com/api/projects/{project-name}が示されています。直接REST APIを使っている場合は、今回のTypeSpec差分だけでなく、認証、エンドポイント、api-versionの指定もあわせて再確認してください。(Microsoft Learn)
確認すべき主な変更点
ModelVersionのスキーマが拡張されている
src/models/models.tspでは、ModelVersionにblobUri、weightType、baseModel、source、loraConfig、artifactProfile、warningsなどが定義されています。loraConfigはCreate/Readの可視性を持ち、説明上はweightTypeがLoRAの場合に必要で、adapter_config.jsonから自動補完される可能性がある項目です。artifactProfileやwarningsはRead側の情報として扱われ、サービス側が算出する警告や成果物プロファイルを表す位置づけです。(GitHub)
実装で注意すべきなのは、リクエストに送るべき項目と、レスポンスで読むだけの項目を混同しないことです。たとえばwarningsのようなサーバー計算項目をクライアント側で作って送信する設計にしていると、SDK生成後に型チェックやバリデーションで扱いにくくなる可能性があります。
Models操作にcreateAsync、startPendingUpload、getCredentialsが追加・整理されている
src/models/routes.tspでは、ModelsインターフェースがVersionedOperationsを拡張し、カスタム操作としてcreateAsync、startPendingUpload、getCredentialsを定義しています。createAsyncはPOST /models/{name}/versions/{version}/createAsyncで、202 Acceptedとポーリング用のLocationヘッダーを返す非同期作成として記述されています。(GitHub)
実務では、次の観点でテストしてください。
| 操作 | 確認ポイント | 失敗しやすい例 |
|---|---|---|
createAsync | 202応答、Locationヘッダー、ポーリング処理 | 200応答前提の実装になっている |
startPendingUpload | PendingUploadRequestの型、アップロードID、接続名 | 旧形式のアップロード種別を固定値で送っている |
getCredentials | blobUriを含む資格情報リクエスト | モデル資産ではなくデータセット用の型を流用している |
createOrUpdate系 | PATCHの有無、バックエンド実装との一致 | Swagger上はあるがサービス側にハンドラーがない可能性を見落とす |
SDKメソッド名も確認対象になる
client.tspでは、Modelsサブクライアントの短いメソッド名として、list、listVersions、get、delete、createOrUpdate、pendingUpload、getCredentialsなどが設定されています。SDKを自動生成している場合、RESTのパスだけでなく、生成後のメソッド名、言語別の命名規則、既存コードとの互換性を確認する必要があります。(GitHub)
特にPythonやJavaScriptでは、client.tspがPythonクライアントazure-ai-projectsとJavaScriptクライアント@azure/ai-projectsの生成に使われる旨をコメントしています。また、Modelsルートはclient.tsp上でプレビュー系の操作群に含まれているため、プレビュー機能のオプトインヘッダーやSDK側の扱いも確認してください。(GitHub)
PendingUploadTypeの変更はデータセット利用者にも注意が必要
src/datasets/models.tspでは、PendingUploadTypeにTemporaryBlobReferenceが定義され、PendingUploadRequestとPendingUploadResponseのpendingUploadTypeもTemporaryBlobReferenceを使う形になっています。これはモデルのアップロード処理だけでなく、共有型を通じてデータセット側の処理にも影響しうる点です。(GitHub)
レビューコメントでも、BlobReferenceからTemporaryBlobReferenceへの変更がDatasetsとModelsの双方に関係し、Datasetsサービス側がまだBlobReferenceを返す場合、再生成されたSDKがTemporaryBlobReferenceを期待してデシリアライズに失敗する可能性が指摘されています。これは「仕様上の文字列変更だから軽微」と見てはいけないポイントです。(GitHub)
移行・設定確認の進め方
今回のようなAzure REST API仕様更新では、いきなり本番SDKを更新するのではなく、仕様差分、生成差分、実行差分の3段階で確認するのが安全です。
| 手順 | 作業内容 | 合格基準 |
|---|---|---|
| 仕様差分を見る | models.tsp、routes.tsp、OpenAPI JSONの変更を確認する | 追加・変更されたフィールド、列挙値、HTTPメソッドを説明できる |
| SDKを一度だけ再生成する | 開発ブランチでPython、JavaScript、C#、Javaなど対象言語のSDK生成を試す | 既存コードのコンパイルエラーと公開API差分が洗い出せている |
| RESTのスモークテストを行う | createAsync、startPendingUpload、getCredentials相当の呼び出しを検証する | ステータスコード、レスポンスボディ、ヘッダー、エラー時レスポンスを記録できている |
| デシリアライズを確認する | TemporaryBlobReference、loraConfig、warningsを含むレスポンスをテストする | SDKが例外なく読み取れる |
| 社内ドキュメントを更新する | モデル作成、アップロード、資格情報取得の手順を反映する | 開発者が旧メソッド名や旧enum値を参照しなくなる |
差分確認では、次のような検索をローカルで行うと、影響箇所を早く見つけられます。
grep -R "loraConfig\|TemporaryBlobReference\|createAsync\|startPendingUpload\|getCredentials" \
specification/ai-foundry/data-plane/FoundrySDK生成をCIに組み込んでいる場合は、生成物の差分だけでなく、アプリケーション側の単体テストも必ず動かしてください。OpenAPI上の追加プロパティは「後方互換」に見える場合がありますが、列挙値や必須/任意、readOnly/writeOnly、PATCH可否が変わると、実行時の失敗につながります。
PR未確定の段階で特に注意したいレビュー指摘
このPRでは、レビューコメントとして複数の重要な懸念が挙げられています。代表的なものは、PATCH /models/{name}/versions/{version}がSwagger上に定義される一方でサービス側にPATCHハンドラーがない可能性、loraConfigがTypeSpecに定義されているのにコンパイル済みOpenAPIに出ていない可能性、allowedDeploymentTemplatesをstable 1.0.0へ追加したことに対するバージョン管理上の懸念です。(GitHub)
また、レビューコメントでは対応案として、PATCH不一致の解消、共有Datasets型でのBlobReference変更の見直し、loraConfigを含めたOpenAPI再生成、stable 1.0.0へのプロパティ追加に対するAPIバージョン更新または承認が推奨されています。(GitHub)
ここで重要なのは、PRの差分を「すでに製品仕様として確定した変更」として扱わないことです。OpenなPRやステージングブランチ向けの変更は、レビューで修正される可能性があります。社内ドキュメントやSDK更新の判断では、マージ先、マージ済みかどうか、生成された公式リファレンスに反映済みかどうかを必ず確認してください。
現場で起きやすい失敗と回避策
| 失敗しやすいポイント | 起きる問題 | 回避策 |
|---|---|---|
| PRタイトルだけで影響なしと判断する | TypeSpec変更によるSDK生成差分を見落とす | ファイル差分とOpenAPI出力を確認する |
createAsyncを同期作成として扱う | 202応答やLocationヘッダー処理を実装しておらず失敗する | 非同期処理としてポーリング設計を確認する |
loraConfigを任意のメタデータ程度に扱う | LoRAモデル作成時に必要情報が不足する | weightTypeがLoRAのケースを専用テストにする |
TemporaryBlobReferenceを固定値変更だけと見る | 既存Dataset処理のデシリアライズが壊れる | ModelsとDatasetsの両方でレスポンス検証を行う |
| 生成SDKのメソッド名変更を確認しない | 既存コードがコンパイルエラーになる | 生成後のpublic API差分をレビューする |
| stable APIへのプロパティ追加を軽視する | バージョニングや互換性チェックでCIが落ちる | breaking changeチェックとAPIバージョン方針を確認する |
次に取るべき行動
まず、自社のコードがFoundryのModels API、モデルバージョン作成、Pending Upload、LoRA関連メタデータ、OpenAPI/TypeSpecベースのSDK生成のどれに関係しているかを切り分けてください。該当しない場合は、公式SDKやMicrosoft Learnの更新を待って確認するだけで十分です。
該当する場合は、次の順序で対応するのが現実的です。最初にPR差分をローカルで確認し、次に開発ブランチでSDKを再生成し、最後にcreateAsync、startPendingUpload、getCredentialsを中心にスモークテストを行います。特にTemporaryBlobReferenceとloraConfigは、型定義だけでなく実際のレスポンスをSDKが正しく読み取れるかまで確認してください。
今回のAzure REST API更新は、Foundry Project SDKのModels機能を強化する方向の変更ですが、レビュー指摘を見る限り、移行時にはサービス実装との整合性、OpenAPI再生成、バージョニング、共有型の影響を丁寧に確認する必要があります。公開・更新情報を追うだけで終わらせず、実際に自社のSDK生成・REST呼び出し・モデル登録フローに影響があるかを小さなテストで確認することが、最も安全な対応です。
コメント