API 규칙 - CoreWeave Docs

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

프로젝트와 task

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로 지정하세요.

모델 레퍼런스

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

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

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

비동기 오퍼레이션

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

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

오류

Management API 오류는 다음 형식을 사용합니다:

{
  "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을 반환합니다.

페이지 매김

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

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

limit은 1부터 200까지 지정할 수 있습니다. 응답에는 page, limit, total, entries가 포함됩니다. 항목 필터와 평가 정렬은 JSON으로 인코딩된 쿼리 매개변수입니다. 요청을 구성할 때 직렬화된 JSON을 URL 인코딩하세요.

생성 및 교체 동작

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

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

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

API: 안전한 요청 처리

메서드, 경로, 스키마, 상태 코드는 Management OpenAPI 사양을 기준으로 삼으세요. 에이전트가 API를 호출할 때는 다음을 따라야 합니다.

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

​프로젝트와 task

​모델 레퍼런스

​비동기 오퍼레이션

​오류

​페이지 매김

​생성 및 교체 동작

프로젝트와 task

모델 레퍼런스

비동기 오퍼레이션

오류

페이지 매김

생성 및 교체 동작