Model import - Alibaba Cloud Model Studio - Centre de documentation Alibaba Cloud

L'API d'importation de modèles de Model Studio fournit des interfaces complètes pour créer, interroger, lister et supprimer des tâches d'importation. Elle permet d'importer des fichiers de modèles affinés depuis OSS vers Model Studio.

Vue d'ensemble

L'API d'importation de modèles permet d'importer dans Model Studio des fichiers de modèles affinés stockés dans OSS. Une fois l'importation terminée, vous pouvez déployer le modèle en tant que service appelable via l'API de création de déploiement. Deux types de modèles sont pris en charge : l'affinage complet des paramètres (full) et l'affinage LoRA (lora).

Le workflow complet d'importation se déroule comme suit : création d'une tâche d'importation → interrogation des détails de la tâche (vérification de l'état) → création d'un déploiement après réussite de la tâche → liste et suppression des tâches inutiles.

L'API d'importation de modèles est actuellement disponible uniquement dans la région de Singapour. Si vous utilisez une autre région, utilisez la console Model Studio de cette région pour importer vos modèles.

Prérequis

Vous avez configuré votre clé API Model Studio. Pour plus d'informations, consultez Obtenir une clé API.
Vous avez créé un bucket OSS et autorisé Model Studio à y accéder. Pour plus d'informations, reportez-vous aux prérequis décrits dans Importation de modèles.
Les fichiers du modèle ont été téléchargés dans le bucket OSS et respectent les contraintes décrites dans Importation de modèles.

En-têtes de requête courants

Toutes les opérations API nécessitent les champs suivants dans l'en-tête HTTP :

En-tête	Description
Authorization	`Bearer ${DASHSCOPE_API_KEY}`. Pour savoir comment obtenir une clé API, consultez Obtenir une clé API.
Content-Type	`application/json`

Objet de modèle personnalisé

Un objet de modèle personnalisé contient toutes les informations relatives à une tâche d'importation. Il est créé via l'API Créer une tâche d'importation et peut être récupéré grâce aux API Interroger les détails d'une tâche d'importation et Lister les tâches d'importation. Après l'importation, vous pouvez déployer le modèle via l'API Créer un déploiement. Voici les champs contenus dans un objet de modèle personnalisé :

Champs de l'objet

Paramètre	Type	Description
request_id	String	ID de la requête.
output.job_id	String	ID de la tâche d'importation, utilisé pour interroger l'état de la tâche ou la supprimer.
output.model_name	String	Identifiant du modèle généré par le système, composé du nom du modèle de base suivi d'un suffixe horodaté.
output.display_name	String	Nom d'affichage du modèle importé.
output.source	String	Source de l'importation. La valeur retournée est `OSS` en majuscules.
output.weight_type	String	Type d'affinage.
output.storage_info	Object	Informations de stockage de la source d'importation, incluant `bucket_name` et `object_key`.
output.status	String	État de la tâche. Pour plus d'informations, consultez États des tâches.
output.gmt_create	String	Date de création de la tâche au format ISO 8601. Exemple : `2024-01-01T12:00:00.000+00:00`.

États des tâches

Une tâche d'importation peut présenter les états suivants au cours de son cycle de vie :

État	Description
PENDING	Tâche soumise, en attente de traitement.
RUNNING	Tâche en cours d'exécution. Le système valide et importe les fichiers du modèle.
SUCCESSED	Tâche terminée avec succès. Le modèle a été importé et peut être déployé via l'API Créer un déploiement.
FAILED	Échec de l'exécution de la tâche. Interrogez les détails de la tâche pour obtenir le code `error_code` expliquant la raison de l'échec.

Créer une tâche d'importation

Soumettez une tâche d'importation de modèle. Le système valide la structure et la sécurité des fichiers du modèle afin de garantir leur bon déploiement.

Endpoint

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

Exemple de requête

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/"
        }
    }'

Paramètres de la requête

Paramètre	Type	Position	Obligatoire	Description
model_name	String	body	Oui	Nom du modèle de base. Correspond au champ Base Model dans la console. Pour connaître les modèles pris en charge, consultez Importation de modèles. Exemple : `qwen3-32b`.
display_name	String	body	Non	Nom d'affichage du modèle importé. Correspond au champ Model Name dans la console. 50 caractères maximum. Par défaut, le nom du modèle de base est utilisé si aucune valeur n'est spécifiée.
source	String	body	Oui	Source de l'importation. Correspond au champ Import Source dans la console. Actuellement, seule la valeur `oss` (importation depuis OSS) est prise en charge. La réponse retourne `OSS` en majuscules.
weight_type	String	body	Oui	Type d'affinage. La valeur `full` désigne un modèle avec affinage complet des paramètres. La valeur `lora` désigne un modèle avec affinage LoRA.
storage_info	Object	body	Oui	Informations de stockage de la source d'importation.
storage_info.bucket_name	String	body	Oui	Nom du bucket OSS. Correspond au champ Bucket dans la console.
storage_info.object_key	String	body	Oui	Préfixe de chemin OSS des fichiers du modèle. Doit se terminer par `/`. Exemple : `models/qwen3-32b-lora/`.

Exemple de réponse

{
    "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"
    }
}

Paramètres de la réponse

Paramètre	Type	Description
request_id	String	ID de la requête.
output.job_id	String	ID de la tâche d'importation, utilisable avec les API Interroger les détails d'une tâche d'importation, Lister les tâches d'importation et Supprimer une tâche d'importation.
output.model_name	String	Identifiant du modèle généré par le système, composé du nom du modèle de base suivi d'un suffixe horodaté.
output.display_name	String	Nom d'affichage du modèle importé.
output.source	String	Source de l'importation. La valeur retournée est `OSS` en majuscules.
output.weight_type	String	Type d'affinage.
output.storage_info	Object	Informations de stockage de la source d'importation, incluant `bucket_name` et `object_key`.
output.status	String	État de la tâche. Pour plus d'informations, consultez États des tâches.
output.gmt_create	String	Date de création de la tâche au format ISO 8601. Exemple : `2024-01-01T12:00:00.000+00:00`.

Interroger les détails d'une tâche d'importation

Interrogez l'état actuel et les détails d'une tâche d'importation spécifique.

Endpoint

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

Exemple de requête

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"

Paramètres de la requête

Paramètre	Type	Position	Obligatoire	Description
job_id	String	path	Oui	ID de la tâche d'importation, obtenu via l'API Créer une tâche d'importation ou Lister les tâches d'importation.

Exemple de réponse

{
    "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"
    }
}

Paramètres de la réponse

Les paramètres de la réponse sont en grande partie identiques à ceux de l'API Créer une tâche d'importation, à l'exception du champ weight_type qui n'est pas inclus. En cas d'échec de la tâche, la réponse contient un champ supplémentaire error_code indiquant la raison de l'échec.

Lister les tâches d'importation

Interrogez la liste paginée des tâches d'importation dans l'espace de travail actuel.

Endpoint

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

Exemple de requête

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"

Filtrage par état :

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"

Paramètres de la requête

Paramètre	Type	Position	Obligatoire	Description
page_no	Integer	query	Non	Numéro de page. Valeur par défaut : 1.
page_size	Integer	query	Non	Nombre d'entrées par page. Valeur par défaut : 10. Valeur maximale : 100.
status	String	query	Non	Filtre selon l'état de la tâche. Pour plus d'informations, consultez États des tâches.
model_name	String	query	Non	Filtre selon le nom du modèle. Vous devez fournir le nom généré par le système retourné dans la réponse (correspondance exacte).

Exemple de réponse

{
    "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"
            }
        ]
    }
}

Paramètres de la réponse

Paramètre	Type	Description
request_id	String	ID de la requête.
output.total	Integer	Nombre total de tâches correspondant aux critères de requête.
output.page_no	Integer	Numéro de la page actuelle.
output.page_size	Integer	Nombre d'entrées par page.
output.list	Array	Liste des tâches d'importation. Chaque élément contient les mêmes champs que les paramètres de réponse de Créer une tâche d'importation, hormis le champ `weight_type` qui n'est pas inclus. Un champ supplémentaire `error_code` apparaît lorsque la tâche échoue.

Supprimer une tâche d'importation

Supprimez une tâche d'importation spécifique ainsi que ses fichiers de modèle associés. Seules les tâches dont l'état est SUCCESSED ou FAILED peuvent être supprimées. Après une suppression réussie, les détails de la tâche supprimée sont retournés.

Endpoint

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

Exemple de requête

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"

Paramètres de la requête

Paramètre	Type	Position	Obligatoire	Description
job_id	String	path	Oui	ID de la tâche d'importation, obtenu via l'API Créer une tâche d'importation ou Lister les tâches d'importation.

Exemple de réponse

{
    "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"
    }
}

Paramètres de la réponse

Paramètre	Type	Description
request_id	String	ID de la requête.
output	Object	Détails de la tâche supprimée. Les champs sont en grande partie identiques à ceux des paramètres de réponse de Créer une tâche d'importation, à l'exception du champ `weight_type` qui n'est pas inclus.

Réponses d'erreur

Lorsqu'une erreur survient, l'API retourne une réponse d'erreur au format suivant :

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

Codes d'erreur

Code d'erreur	Description
InvalidParameter	Paramètre de requête non valide. Par exemple, un paramètre obligatoire est manquant, le format du paramètre est incorrect ou la valeur du paramètre n'est pas valide.
NotFound	La ressource spécifiée n'existe pas. Cela peut signifier que le job_id n'existe pas, que l'utilisateur n'y a pas accès ou que le modèle de base ne prend pas en charge l'importation.
OperationDenied	L'opération est refusée. Par exemple, tentative de suppression d'une tâche dont l'état est RUNNING.
InvalidApiKey	La clé API est non valide ou n'a pas été fournie.
InternalError	Une erreur interne du système s'est produite. Veuillez réessayer ultérieurement.