> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API の規約

> モデル参照、非同期ステータス、エラー、ページネーション、冪等性について理解します。

このページでは、Model Distillation の [Management API](/ja/model-distillation/reference/management) が全エンドポイントに共通して適用する規約について説明します。UI のプロジェクトと API のタスク名の対応関係、モデルの参照方法、非同期ステータスの解釈方法に加え、エラー、ページネーション、作成または置換リクエストの動作を取り上げます。API を呼び出すスクリプトやエージェントを作成する前に、このページを読み、クライアントが非同期処理と再試行を正しく扱えるようにしてください。

<div id="projects-and-tasks">
  <h2 id="projects-and-tasks">
    プロジェクトとタスク
  </h2>
</div>

UI では、最適化の対象となる単位をプロジェクトと呼びます。一方、Management API とトレース属性では、同じリソースをタスクという名前で扱います。

* API のパスは `/tasks/{alias}` で始まります。`alias` は UI に表示されるプロキシモデル名です。
* データセットのクエリは `task_version` でフィルタリングします。これはプロジェクトのバージョンにあたります。
* エラーメッセージではタスクという表記が使われます。たとえば `Task 'missing' not found in entity 'your-team'` のようになります。

プロジェクトのトレースを保存する W\&B プロジェクトは、これとは別のリソースです。プロジェクトを作成する際に `project` と `project_mode` で指定します。

<div id="model-references">
  <h2 id="model-references">
    モデル参照
  </h2>
</div>

管理リクエストのフィールドは、次の形式を使用します。

```text theme={"system"}
{provider-name}/{provider-model-id}
```

プロバイダー名は小文字で、保存されている認証情報を識別します。モデル ID はプロバイダー側で定義され、追加のスラッシュやエンコードされた推論努力度 (reasoning effort) のクエリを含む場合があります。

<div id="asynchronous-operations">
  <h2 id="asynchronous-operations">
    非同期操作
  </h2>
</div>

`202 Accepted` は、目的の状態やバックグラウンド処理が保存されたことを示すものであり、すでに稼働中または完了していることを示すものではありません。返されたリソースをポーリングしてください。

* プロバイダーとルーティングのデプロイ状態が、現在のリビジョンで `applied` になる必要があります。
* データセットは `ready` または `failed` になります。
* 再ラベル付けの実行は `completed`、`failed`、または `stale` になります。
* ファインチューンは `deployed` または `failed` になります。
* 評価は進行中のケース数を公開し、失敗したケースを含んだまま完了する場合があります。
* データセットとファインチューンを削除すると、削除操作とともに `202 Accepted` が返されます。進行状況を確認するには、`DELETE` リクエストを再度送信するか、`deletion-plan` エンドポイントを参照してください。

<div id="errors">
  <h2 id="errors">
    エラー
  </h2>
</div>

Management API のエラーは、次の形式で返されます。

```json theme={"system"}
{
  "error": {
    "message": "Task 'missing' not found in entity 'your-team'",
    "type": "not_found"
  }
}
```

検証に失敗した場合、JSON やクエリ値の形式が不正であれば `400 Bad Request`、ボディがスキーマを満たしていなければ `422 Unprocessable Entity` が返されます。参照中のプロバイダーの削除といった競合が発生した場合は `409 Conflict` が返されます。サポートされていない国またはリージョンからパブリックイングレス経由で書き込みリクエストが送信された場合は、タイプ `region_restricted` の `403 Forbidden` が返されます。

<div id="pagination">
  <h2 id="pagination">
    ページネーション
  </h2>
</div>

データセットのエントリは、ページ単位のページネーションを使用します。

```text theme={"system"}
GET .../entries?page=1&limit=50
```

`limit` には 1 から 200 までの値を指定できます。レスポンスには `page`、`limit`、`total`、`entries` が含まれます。

エントリのフィルターと評価のソートは、JSON エンコードされたクエリパラメーターです。リクエストを作成する際は、シリアライズした JSON を URL エンコードしてください。

<div id="create-and-replace-behavior">
  <h2 id="create-and-replace-behavior">
    作成と置換の動作
  </h2>
</div>

管理系の書き込み操作は、同じリクエストを繰り返しても安全かどうかが操作ごとに異なります。安全に再試行するには、どの呼び出しが状態を置換し、どの呼び出しが新しいリソースを作成するのかを把握しておいてください。

* `PUT /providers/{name}` はプロバイダーを作成またはローテーションします。
* `PUT /tasks/{alias}` はプロジェクトを作成します。プロジェクトがすでに存在する場合は競合を返します。
* ルーティングの `PUT` は、そのバージョンのすべてのターゲットを置換します。
* データセット、ファインチューン、評価の `POST` リクエストは新しいリソースを作成するため、コンピュートを消費する場合があります。
* データセットとファインチューンの `DELETE` リクエストは、1 回のリクエストで永続的な削除をキューに登録します。同じリクエストを繰り返した場合は、既存の操作が返されるか、失敗したクリーンアップが再試行されます。リソースがすでに削除済みの場合は `204 No Content` が返されます。

ネットワーク障害で結果が判別できない状態から、べき等でない作成呼び出しを再試行する場合は、クライアント側のリクエスト ID と独自のオーケストレーション状態を活用してください。

<Accordion title="API: 安全なリクエスト処理">
  メソッド、パス、スキーマ、ステータスコードについては、[Management OpenAPI 仕様](/ja/openapi/model-distillation/management.openapi.yaml)を信頼できる唯一の情報源として使用してください。エージェントが API を呼び出す際は、次の点に従う必要があります。

  * すべてのプレースホルダーを、ユーザーから提供された値または以前に返された値で解決する。
  * 有料のコンピュートを開始する、またはルーティングを置換するリクエストは、必ずユーザーに提示する。
  * `202 Accepted` は処理の開始とみなし、ドキュメントに記載されたリソースをポーリングする。
  * リソースを名前で再検索するのではなく、返されたリソース ID を保持する。
  * 予期しないステータスが返された場合は、作成操作を自動的に再試行せず、処理を停止する。
</Accordion>


## Related topics

- [認証と entity](/ja/model-distillation/reference/authentication.md)