モデルのインポート - Alibaba Cloud Model Studio - Alibaba Cloud ドキュメントセンター

概要

モデルインポート API を使用すると、OSS に保存されているファインチューニング済みモデルファイルを Model Studio にインポートできます。インポート後、デプロイメント作成 API を使用して、モデルを呼び出し可能なサービスとしてデプロイできます。モデルインポートは、全パラメータファインチューニング (full) と LoRA ファインチューニング (lora) の 2 つのモデルタイプをサポートしています。

モデルインポートの完全なワークフローは次のとおりです：インポートタスクの作成 → インポートタスク詳細のクエリ (タスクステータスのポーリング) → タスク成功後のデプロイメント作成 → 不要になったタスクの一覧表示と削除。

前提条件

Model Studio API キーが設定されていること。詳細については、「API キーの取得」をご参照ください。
OSS バケットが作成され、Model Studio に OSS へのアクセスが許可されていること。詳細については、モデルのインポートの前提条件をご参照ください。
モデルファイルが OSS バケットにアップロードされており、インポートの要件と制限に準拠していること。

共通リクエストヘッダー

すべての API 操作では、HTTP ヘッダーに次のフィールドが必要です。

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

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

カスタムモデルオブジェクトは、インポートタスクの完全な情報を記述します。このオブジェクトは、インポートタスクの作成 API を通じて作成され、インポートタスク詳細の照会およびインポートタスクの一覧表示 API で取得できます。インポート後、デプロイメントの作成 API を通じてモデルをデプロイできます。カスタムモデルオブジェクトに含まれるフィールドは次のとおりです。

オブジェクトフィールド

パラメーター	タイプ	説明
request_id	文字列	リクエスト ID。
output.job_id	文字列	インポートタスク ID。タスクステータスの照会やタスクの削除に使用されます。
output.model_name	文字列	システムが生成したモデル識別子。ベースモデル名にタイムスタンプのサフィックスを付加した形式です。
output.display_name	文字列	インポートされたモデルの表示名。
output.source	文字列	インポート元。戻り値は大文字の `OSS` です。
output.weight_type	文字列	ファインチューニングのタイプ。
output.storage_info	オブジェクト	インポート元のストレージ情報。`bucket_name` と `object_key` が含まれます。
output.status	文字列	タスクステータス。詳細については、「タスクステータス」をご参照ください。
output.gmt_create	文字列	ISO 8601 フォーマットのタスク作成時刻。例: `2024-01-01T12:00:00.000+00:00`。

タスクステータス

インポートタスクは、そのライフサイクルにおいて、次のいずれかのステータスになります。

ステータス	説明
PENDING	タスクが送信され、処理待ちの状態です。
RUNNING	タスクが実行中です。システムがモデルファイルの検証とインポートを行っています。
SUCCEEDED	タスクが正常に完了しました。モデルはインポートされており、デプロイメントの作成 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	はい	ベースモデルの名前。コンソールの [Base Model] フィールドに対応します。サポートされているモデルについては、「サポートされているベースモデル」をご参照ください。例： `qwen3-32b`。
display_name	String	body	いいえ	インポートされたモデルの表示名。コンソールの [Model Name] フィールドに対応します。最大 50 文字です。指定しない場合、デフォルトでベースモデル名が使用されます。
source	String	body	はい	インポートソース。コンソールの [Import Source] フィールドに対応します。現在、`oss` (OSS からのインポート) のみがサポートされています。レスポンスでは、大文字の `OSS` が返されます。
weight_type	String	body	はい	ファインチューニングのタイプ。`full` は、フルパラメータファインチューニング済みモデルを示します。`lora` は、LoRA ファインチューニング済みモデルを示します。
storage_info	Object	body	はい	インポートソースのストレージ情報。
storage_info.bucket_name	String	body	はい	OSS バケット名。コンソールの [Bucket] フィールドに対応します。
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、「インポートタスクの一覧表示」API、および「インポートタスクの削除」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	文字列	パス	はい	インポートタスク ID。インポートタスクの作成 API またはインポートタスクの一覧表示 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 フィールドが含まれない点を除き、インポートタスクの作成 API とほぼ同じです。タスクが失敗した場合、レスポンスには失敗理由を示す 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=SUCCESSED" \
    --header "Authorization: Bearer $DASHSCOPE_API_KEY" \
    --header "Content-Type: application/json"

リクエストパラメーター

パラメーター	タイプ	場所	必須	説明
page_no	Integer	query	いいえ	ページ番号。デフォルト値： 1。
page_size	Integer	query	いいえ	ページあたりのエントリ数。デフォルト値： 10。最大値： 100。
status	String	query	いいえ	タスクステータスでフィルタリングします。詳細については、「タスクステータス」をご参照ください。
model_name	String	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": "SUCCESSED",
                "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	String	リクエスト ID。
output.total	Integer	クエリ条件に一致するタスクの総数。
output.page_no	Integer	現在のページ番号。
output.page_size	Integer	ページあたりのエントリ数。
output.list	Array	インポートタスクのリストです。各要素はインポートタスクの作成のレスポンスパラメーターと同じフィールドを持ちますが、`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	文字列	パス	はい	インポートタスクの作成 API またはインポートタスクの一覧表示 API から取得できるインポートタスク ID です。

レスポンス例

{
    "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	文字列	リクエスト ID です。
output	オブジェクト	削除されたタスクの詳細です。フィールドは、`weight_type` フィールドが含まれない点を除き、インポートタスクの作成のレスポンスパラメーターとほぼ同じです。

エラーレスポンス

エラーが発生した場合、API は次のフォーマットでエラーレスポンスを返します。

{
    "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	内部システムエラーが発生しました。しばらくしてからもう一度お試しください。