モデルインポート API - OSS からファインチューニング済みモデルをインポート | Model Studio - Alibaba Cloud Model Studio

ファインチューニングされたモデルファイルを OSS から Model Studio にインポートします。この API では、インポートタスクの作成、クエリ、一覧表示、削除が可能です。

概要

ファインチューニングされたモデルファイルを OSS から Model Studio にインポートし、デプロイメント作成 API を使用して呼び出し可能なサービスとしてデプロイします。全パラメータファインチューニング (full) と LoRA ファインチューニング (lora) の 2 種類のモデルタイプがサポートされています。

ワークフロー：インポートタスクの作成 → タスクステータスのポーリング → インポート成功後のモデルのデプロイ。完了したタスクの管理には、一覧取得 API と削除 API を使用します。

モデルインポート API は現在、シンガポールリージョンでのみ利用できます。別のリージョンをご利用の場合は、そのリージョンの Model Studio コンソールからモデルをインポートしてください。

前提条件

Model Studio API キーが設定されています。詳細については、「API キーを取得する」をご参照ください。
OSS バケットを作成し、Model Studio に OSS へのアクセスを承認済みである必要があります。詳細については、「モデルのインポート」の前提条件をご参照ください。
モデルファイルが OSS バケットにアップロードされ、モデルのインポートに準拠しています。

共通リクエストヘッダー

すべてのオペレーションで以下の HTTP ヘッダーが必要です。

ヘッダー	説明
Authorization	`Bearer ${DASHSCOPE_API_KEY}`。 API キーの取得方法については、「API キーの取得」をご参照ください。
Content-Type	`application/json`

カスタムモデルオブジェクト

カスタムモデルオブジェクトは、インポートタスクを表します。 Create an import task API で作成し、Query import task details API または List import tasks API で取得し、Create a deployment API でモデルをデプロイします。

オブジェクトフィールド

パラメーター	型	説明
request_id	String	リクエスト ID です。
output.job_id	String	インポートタスク ID です。タスクのクエリまたは削除に使用します。
output.model_name	String	システムによって生成されるモデル識別子です。ベースモデル名とタイムスタンプサフィックスで構成されます。
output.display_name	String	インポートされたモデルの表示名です。
output.source	String	インポート元。大文字の `OSS` を返します。
output.weight_type	String	ファインチューニングのタイプです。
output.storage_info	Object	`bucket_name` と `object_key` を含む移行元ストレージ情報をインポートします。
output.status	String	タスクのステータスです。有効な値については、「タスクステータス」をご参照ください。
output.gmt_create	String	ISO 8601 形式のタスク作成時刻です。例: `2024-01-01T12:00:00.000+00:00`。

タスクステータス

インポートタスクのステータス：

ステータス	説明
PENDING	送信済みで、処理を待機している状態です。
RUNNING	モデルファイルの検証とインポートを実行中です。
SUCCEEDED	インポートが成功しました。 Create a deployment API を使用してモデルをデプロイしてください。
FAILED	インポートに失敗しました。タスク詳細で`error_code`を確認してください。

インポートタスクの作成

モデルインポートタスクを送信します。システムは、インポート前にモデルファイルの構造とセキュリティを検証します。

エンドポイント

POST https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import

リクエスト例

curl -X POST "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json" \
    --data '{
        "model_name": "qwen3-32b",
        "display_name": "My LoRA fine-tuned model",
        "source": "oss",
        "weight_type": "lora",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        }
    }'

リクエストパラメーター

パラメーター	型	位置	必須	説明
model_name	String	body	はい	ベースモデル名。コンソールの [ベースモデル] に対応します。サポートされているモデルについては、「モデルのインポート」をご参照ください。例： `qwen3-32b`。
display_name	String	body	いいえ	インポートされたモデルの表示名。コンソールの [モデル名] に対応します。最大 50 文字。デフォルトはベースモデル名です。
source	String	body	はい	インポート元。コンソールの [インポート元] に対応します。`oss` のみサポートされています。レスポンスでは大文字の `OSS` が返されます。
weight_type	String	body	はい	ファインチューニングのタイプ。`full`: フルパラメータファインチューニングモデル。`lora`: LoRA でファインチューニングされたモデル。
storage_info	Object	body	はい	インポート元のストレージ情報。
storage_info.bucket_name	String	body	はい	OSS バケット名。コンソールの [バケット] に対応します。
storage_info.object_key	String	body	はい	モデルファイルの OSS パスプレフィックス。`/` で終わる必要があります。例： `models/qwen3-32b-lora/`。

レスポンス例

{
    "request_id": "6c6b****-3fea-****-bc26-c9e2********",
    "output": {
        "job_id": "937b****-2a4f-****-8abe-c2fa********",
        "model_name": "qwen3-32b-offline-20240101-abc1",
        "display_name": "My LoRA fine-tuned model",
        "source": "OSS",
        "weight_type": "lora",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        },
        "status": "PENDING",
        "gmt_create": "2024-01-01T12:00:00.000+00:00"
    }
}

レスポンスパラメーター

パラメーター	型	説明
request_id	String	リクエスト ID。
output.job_id	String	インポートタスク ID。「インポートタスク詳細のクエリ」、「インポートタスクの一覧表示」、「インポートタスクの削除」の各 API で使用します。
output.model_name	String	システムによって生成されるモデル識別子。ベースモデル名とタイムスタンプサフィックスで構成されます。
output.display_name	String	インポートされたモデルの表示名。
output.source	String	インポート元。大文字の `OSS` を返します。
output.weight_type	String	ファインチューニングのタイプ。
output.storage_info	Object	インポート元のストレージ情報。`bucket_name` と `object_key` を含みます。
output.status	String	タスクステータス。有効な値については、「タスクステータス」をご参照ください。
output.gmt_create	String	ISO 8601 形式のタスク作成時刻。例： `2024-01-01T12:00:00.000+00:00`。

インポートタスク詳細の照会

インポートタスクのステータスと詳細を照会します。

エンドポイント

GET https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/{job_id}

リクエスト例

curl "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/937b****-2a4f-****-8abe-c2fa********" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

リクエストパラメーター

パラメーター	型	位置	必須	説明
job_id	String	path	必須	インポートタスクの ID。「インポートタスクの作成」または「インポートタスクの一覧表示」API から取得します。

レスポンス例

{
    "request_id": "ca21****-b91b-****-bd35-c41c********",
    "output": {
        "job_id": "937b****-2a4f-****-8abe-c2fa********",
        "model_name": "qwen3-32b-offline-20240101-abc1",
        "display_name": "My LoRA fine-tuned model",
        "source": "OSS",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        },
        "status": "RUNNING",
        "gmt_create": "2024-01-01T12:00:00.000+00:00"
    }
}

レスポンスパラメーター

「インポートタスクの作成」と同じレスポンスパラメーターですが、 weight_type は省略されます。失敗したタスクには、追加で error_code フィールドが含まれます。

インポートタスクの一覧表示

現在のワークスペース内のインポートタスクをページネーションで一覧表示します。

エンドポイント

GET https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import

リクエスト例

curl "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import?page_no=1&page_size=10" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

ステータスによるフィルタリング：

curl "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import?page_no=1&page_size=10&status=SUCCEEDED" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

リクエストパラメーター

パラメーター	タイプ	位置	必須	説明
page_no	Integer	query	任意	ページ番号。デフォルト： 1。
page_size	Integer	query	任意	ページあたりのエントリ数。デフォルト： 10。最大： 100。
status	文字列	query	任意	フィルタリングに使用するタスクステータス。有効な値：タスクステータス。
model_name	文字列	query	任意	フィルタリングに使用するモデル名 (システムが生成した名前との完全一致) 。

レスポンス例

{
    "request_id": "ca21****-b91b-****-bd35-c41c********",
    "output": {
        "total": 2,
        "page_no": 1,
        "page_size": 10,
        "list": [
            {
                "job_id": "937b****-2a4f-****-8abe-c2fa********",
                "model_name": "qwen3-32b-offline-20240101-abc1",
                "display_name": "My LoRA fine-tuned model",
                "status": "SUCCEEDED",
                "source": "OSS",
                "storage_info": {
                    "bucket_name": "my-model-bucket",
                    "object_key": "models/qwen3-32b-lora/"
                },
                "gmt_create": "2024-01-01T12:00:00.000+00:00"
            },
            {
                "job_id": "edb0****-39ac-****-9859-8b1e********",
                "model_name": "qwen3-32b-offline-20240102-xyz4",
                "display_name": "My full-parameter fine-tuned model",
                "status": "FAILED",
                "source": "OSS",
                "storage_info": {
                    "bucket_name": "my-model-bucket",
                    "object_key": "models/qwen3-32b-full/"
                },
                "error_code": "Failed to retrieve files from OSS. Please check the files in OSS.",
                "gmt_create": "2024-01-02T09:00:00.000+00:00"
            }
        ]
    }
}

レスポンスパラメーター

パラメーター	タイプ	説明
request_id	文字列	リクエスト ID。
output.total	Integer	一致するタスクの総数。
output.page_no	Integer	現在のページ番号。
output.page_size	Integer	ページあたりのエントリ数。
output.list	配列	インポートタスクのリスト。各要素には、インポートタスクの作成レスポンスと同じフィールドが含まれますが、`weight_type` は省略されます。失敗したタスクには、追加の `error_code` フィールドが含まれます。

インポートタスクの削除

インポートタスクとそれに関連するモデルファイルを削除します。SUCCESSED または FAILED のタスクのみ削除できます。削除されたタスクの詳細を返します。

エンドポイント

DELETE https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/{job_id}

リクエスト例

curl -X DELETE "https://dashscope-intl.aliyuncs.com/api/v1/custom_models/import/937b****-2a4f-****-8abe-c2fa********" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

リクエストパラメーター

パラメーター	型	場所	必須	説明
job_id	String	path	はい	インポートタスク ID。インポートタスクの作成 API またはインポートタスクの一覧 API から取得します。

レスポンス例

{
    "request_id": "e22b****-b20a-****-bf23-9b53********",
    "output": {
        "job_id": "937b****-2a4f-****-8abe-c2fa********",
        "model_name": "qwen3-32b-offline-20240101-abc1",
        "display_name": "My LoRA fine-tuned model",
        "source": "OSS",
        "storage_info": {
            "bucket_name": "my-model-bucket",
            "object_key": "models/qwen3-32b-lora/"
        },
        "status": "SUCCESSED",
        "gmt_create": "2024-01-01T12:00:00.000+00:00"
    }
}

レスポンスパラメーター

パラメーター	型	説明
request_id	String	リクエスト ID。
output	オブジェクト	削除されたタスクの詳細。インポートタスクの作成レスポンスと同じフィールドですが、`weight_type` は省略されます。

エラーレスポンス

エラーレスポンスのフォーマットは次のとおりです。

{
    "request_id": "ca21****-b91b-****-bd35-c41c********",
    "code": "OperationDenied",
    "message": "The import job is currently running and cannot be deleted."
}

エラーコード

エラーコード	説明
InvalidParameter	無効なリクエストパラメーターです。必須フィールドの欠落、不正なフォーマット、または無効な値が考えられます。
NotFound	リソースが見つかりません。無効な`job_id`、不十分なアクセス権限、またはサポートされていないベースモデルが原因である可能性があります。
OperationDenied	操作が拒否されました。例：`RUNNING`状態のタスクの削除。
InvalidApiKey	API キーが無効か、欠落しています。
InternalError	内部システムエラーです。後でもう一度お試しください。