Conventions de l’API - CoreWeave Docs

Cette page décrit les conventions que la Management API de Model Distillation applique à l’ensemble de ses points de terminaison. Elle explique comment les projets de l’interface utilisateur correspondent aux noms de tâches de l’API, comment référencer des modèles et comment interpréter le statut asynchrone. Elle précise également le comportement des erreurs, de la pagination et des requêtes de création ou de remplacement. Avant d’écrire des scripts qui utilisent l’API ou de créer un agent qui l’appelle, lisez cette page pour que votre client gère correctement les traitements asynchrones et les nouvelles tentatives.

Projets et tâches

Dans l’interface utilisateur, l’unité que vous optimisez s’appelle un projet. La Management API et les attributs de trace désignent cette même ressource sous le nom de tâche (task) :

Les chemins d’API commencent par /tasks/{alias}, où alias est le nom de modèle proxy affiché dans l’interface utilisateur.
Les requêtes sur les datasets filtrent par task_version, qui correspond à la version du projet.
Les messages d’erreur mentionnent des tâches, par exemple Task 'missing' not found in entity 'your-team'.

Le projet W&B qui stocke les traces d’un projet est une ressource distincte. Définissez-le à l’aide de project et project_mode lors de la création d’un projet.

Références de modèles

Les champs des requêtes de gestion utilisent le format suivant :

{provider-name}/{provider-model-id}

Le nom du fournisseur est en minuscules et permet d’identifier les identifiants d’authentification stockés. L’ID du modèle est défini par le fournisseur et peut contenir des barres obliques supplémentaires ou un paramètre de requête encodé indiquant le niveau d’effort de raisonnement.

Opérations asynchrones

202 Accepted signifie que l’état souhaité ou le traitement en arrière-plan a été enregistré, et non que la ressource est déjà en service ou que le traitement est terminé. Interrogez la ressource renvoyée :

Le statut de déploiement du fournisseur et de l’acheminement doit passer à applied pour la révision actuelle.
Les datasets passent à l’état ready ou failed.
Les runs de réétiquetage passent à l’état completed, failed ou stale.
Les modèles issus du fine-tuning passent à l’état deployed ou failed.
Les évaluations indiquent en temps réel le nombre de cas et peuvent se terminer avec des cas en échec.
Les suppressions de datasets et de modèles issus du fine-tuning renvoient 202 Accepted avec une opération de suppression. Pour suivre sa progression, renvoyez la requête DELETE ou consultez le point de terminaison deletion-plan.

Erreurs

Les erreurs de la Management API utilisent le format suivant :

{
  "error": {
    "message": "Task 'missing' not found in entity 'your-team'",
    "type": "not_found"
  }
}

En cas d’échec de validation, l’API renvoie 400 Bad Request si le JSON ou les valeurs de requête sont mal formés, ou 422 Unprocessable Entity si le corps de la requête n’est pas conforme à son schéma. Les conflits, comme la suppression d’un fournisseur encore référencé, renvoient 409 Conflict. Une requête d’écriture reçue via l’ingress public depuis un pays ou une région non pris en charge renvoie 403 Forbidden avec le type region_restricted.

Pagination

Les entrées de dataset utilisent une pagination par numéro de page :

GET .../entries?page=1&limit=50

La valeur de limit doit être comprise entre 1 et 200. La réponse contient page, limit, total et entries. Les filtres d’entrées et le tri des évaluations sont des paramètres de requête encodés en JSON. Lorsque vous construisez vos requêtes, encodez le JSON sérialisé au format URL.

Comportement de création et de remplacement

Les opérations d’écriture de gestion ne se comportent pas toutes de la même façon lorsqu’une requête est répétée. Pour relancer une requête en toute sécurité, vous devez savoir quels appels remplacent l’état et lesquels créent de nouvelles ressources :

PUT /providers/{name} crée un fournisseur ou le fait pivoter.
PUT /tasks/{alias} crée un projet et renvoie un conflit si le projet existe déjà.
Le PUT d’acheminement remplace toutes les cibles de cette version.
Les requêtes POST de dataset, de fine-tuning et d’évaluation créent de nouvelles ressources et peuvent consommer des ressources de calcul.
Les requêtes DELETE de dataset et de fine-tuning mettent en file d’attente une suppression durable en une seule requête. Une requête répétée renvoie l’opération existante, relance le nettoyage ayant échoué ou renvoie 204 No Content si la ressource n’existe plus.

Lorsque vous relancez des appels de création non idempotents après une défaillance réseau à l’issue incertaine, utilisez des ID de requête côté client ainsi que votre propre état d’orchestration.

API : gestion sécurisée des requêtes

Utilisez la spécification OpenAPI de gestion comme source de référence pour les méthodes, les chemins, les schémas et les codes de statut. Lorsqu’un agent appelle l’API, il doit procéder comme suit :

Résoudre chaque espace réservé à partir de valeurs fournies par l’utilisateur ou renvoyées précédemment.
Présenter à l’utilisateur toute requête qui lance des ressources de calcul payantes ou remplace l’acheminement.
Considérer 202 Accepted comme le début du traitement et interroger la ressource documentée.
Conserver les ID de ressource renvoyés au lieu de rechercher à nouveau les ressources par leur nom.
S’arrêter en cas de statut inattendu plutôt que de relancer automatiquement une opération de création.

​Projets et tâches

​Références de modèles

​Opérations asynchrones

​Erreurs

​Pagination

​Comportement de création et de remplacement