> ## 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](/ko/model-distillation/reference/management)의 모든 엔드포인트에 공통으로 적용되는 규칙을 설명합니다. UI의 프로젝트가 API의 task 이름에 매핑되는 방식, 모델을 참조하는 방법, 비동기 상태를 해석하는 방법, 그리고 오류, 페이지 매김, 생성 또는 교체(create-or-replace) 요청의 동작 방식을 다룹니다. API용 스크립트를 작성하거나 API를 호출하는 에이전트를 구축하기 전에 이 페이지를 읽고, 클라이언트가 비동기 작업과 재시도를 올바르게 처리하도록 구현하세요.

<h2 id="projects-and-tasks">
  프로젝트와 task
</h2>

UI에서는 최적화 대상 단위를 프로젝트라고 부릅니다. 반면 Management API와 트레이스 속성에서는 같은 리소스를 task라고 부릅니다.

* API 경로는 `/tasks/{alias}`로 시작하며, 여기서 `alias`는 UI에 표시되는 프록시 모델 이름입니다.
* 데이터셋 쿼리는 프로젝트 버전에 해당하는 `task_version`으로 필터링합니다.
* 오류 메시지에서도 task라는 용어를 사용합니다. 예: `Task 'missing' not found in entity 'your-team'`.

프로젝트의 트레이스를 저장하는 W\&B 프로젝트는 별개의 리소스입니다. 프로젝트를 생성할 때 `project`와 `project_mode`로 지정하세요.

<h2 id="model-references">
  모델 레퍼런스
</h2>

관리 요청 필드는 다음 형식을 사용합니다:

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

공급자 이름은 소문자이며 저장된 자격 증명을 식별합니다. 모델 ID는 공급자가 정의하며 추가 슬래시나 인코딩된 추론 노력 쿼리를 포함할 수 있습니다.

<h2 id="asynchronous-operations">
  비동기 오퍼레이션
</h2>

`202 Accepted`는 원하는 상태나 백그라운드 작업이 저장되었다는 의미일 뿐, 이미 서비스 중이거나 완료되었다는 의미는 아닙니다. 반환된 리소스를 폴링하세요.

* 공급자 및 라우팅 배포 상태는 현재 리비전에서 `applied`가 되어야 합니다.
* 데이터셋은 `ready` 또는 `failed` 상태가 됩니다.
* 재레이블링 run은 `completed`, `failed` 또는 `stale` 상태가 됩니다.
* 파인튜닝 모델은 `deployed` 또는 `failed` 상태가 됩니다.
* 평가는 실시간 케이스 수를 제공하며, 일부 케이스가 실패한 상태로 완료될 수 있습니다.
* 데이터셋 및 파인튜닝 모델을 삭제하면 삭제 오퍼레이션과 함께 `202 Accepted`가 반환됩니다. 진행 상황을 확인하려면 `DELETE` 요청을 반복하거나 `deletion-plan` 엔드포인트를 조회하세요.

<h2 id="errors">
  오류
</h2>

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`를 반환합니다. 지원되지 않는 국가나 지역에서 public ingress를 통해 도착한 쓰기 요청은 `region_restricted` 유형과 함께 `403 Forbidden`을 반환합니다.

<h2 id="pagination">
  페이지 매김
</h2>

데이터셋 항목은 페이지 기반 페이지 매김을 사용합니다:

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

`limit`은 1부터 200까지 지정할 수 있습니다. 응답에는 `page`, `limit`, `total`, `entries`가 포함됩니다.

항목 필터와 평가 정렬은 JSON으로 인코딩된 쿼리 매개변수입니다. 요청을 구성할 때 직렬화된 JSON을 URL 인코딩하세요.

<h2 id="create-and-replace-behavior">
  생성 및 교체 동작
</h2>

Management 쓰기 오퍼레이션은 요청을 반복해도 안전한지가 오퍼레이션마다 다릅니다. 안전하게 재시도하려면 어떤 Call이 상태를 교체하고 어떤 Call이 새 리소스를 생성하는지 알아 두어야 합니다.

* `PUT /providers/{name}`은 공급자를 생성하거나 교체합니다.
* `PUT /tasks/{alias}`는 프로젝트를 생성하며, 프로젝트가 이미 있으면 충돌을 반환합니다.
* 라우팅 `PUT`은 해당 버전의 모든 대상을 교체합니다.
* 데이터셋, 파인튜닝 모델, 평가 `POST` 요청은 새 리소스를 생성하며 컴퓨팅 리소스를 소비할 수 있습니다.
* 데이터셋 및 파인튜닝 모델 `DELETE` 요청은 한 번의 요청으로 영구 삭제 작업을 큐에 추가합니다. 같은 요청을 반복하면 기존 오퍼레이션을 반환하거나, 실패한 정리 작업을 재시도하거나, 리소스가 이미 삭제된 경우 `204 No Content`를 반환합니다.

네트워크 장애로 요청 처리 여부가 불분명한 상황에서 멱등성이 없는 생성 Call을 재시도할 때는 클라이언트 측 요청 ID와 자체 오케스트레이션 상태를 활용하세요.

<Accordion title="API: 안전한 요청 처리">
  메서드, 경로, 스키마, 상태 코드는 [Management OpenAPI 사양](/ko/openapi/model-distillation/management.openapi.yaml)을 기준으로 삼으세요. 에이전트가 API를 호출할 때는 다음을 따라야 합니다.

  * 모든 플레이스홀더를 사용자가 제공한 값이나 이전에 반환된 값으로 채웁니다.
  * 유료 컴퓨팅을 시작하거나 라우팅을 교체하는 요청은 사용자에게 먼저 보여 줍니다.
  * `202 Accepted`는 작업이 시작되었다는 의미로 받아들이고, 문서에 명시된 리소스를 폴링합니다.
  * 이름으로 리소스를 다시 찾지 말고 반환된 리소스 ID를 보관해 사용합니다.
  * 예상치 못한 상태 코드가 반환되면 생성 오퍼레이션을 자동으로 재시도하지 말고 중지합니다.
</Accordion>


## Related topics

- [프로젝트와 버전](/ko/model-distillation/concepts/projects-and-versions.md)