예측(Prediction) 만들기 — Replicate API로 모델 실행하기

예측(Prediction) 만들기 — Replicate API로 모델 실행하기

Replicate에서 모델을 실행하는 행위는 전부 '예측(prediction)을 만든다'고 표현해요. API 한 번 호출로 예측을 만들고, 그 결과를 기다리는 방식은 크게 두 가지인데요. 결과를 바로 돌려받는 동기(sync) 방식과, 나중에 결과를 확인하는 비동기(async) 방식이에요. API 엔드포인트가 모델 종류에 따라 셋으로 갈라지니, 이 글에서 그 차이까지 함께 정리해요.

출처: Replicate Docs — Create a prediction

예측을 만드는 세 엔드포인트

실행하려는 모델 종류에 따라 예측 생성 API가 달라져요.

  • 커뮤니티 모델 — predictions.create
  • 공식 모델 — models.predictions.create
  • 배포(Deployment) — deployments.predictions.create

엔드포인트가 달라도 예측을 만드는 방식 자체는 같아요. 동기·비동기 두 모드의 차이부터 볼게요.

  • 동기(sync) 모드: 빠른 응답에 최적화. 예측 출력을 응답에 직접 담아 돌려줘요. 실시간 애플리케이션이나 결과가 곧바로 필요한 경우에 좋고, 짧고 빠른 연산에 적합해요.
  • 비동기(async) 모드(기본): 긴 작업에 적합. 예측 ID와 함께 바로 응답이 오고, 나중에 상태를 확인하고 결과를 가져와요. 백그라운드 처리나 시간이 오래 걸리는 예측에 낫죠.

속도와 단순함이 필요하면 동기, 유연성과 오래 걸리는 예측 관리가 필요하면 비동기를 고르면 돼요.

동기 모드

동기 모드는 모델 출력을 최대한 빨리 돌려주도록 설계됐고, 실시간 애플리케이션이나 즉시 결과가 필요할 때 적합해요. 몇 초 안에 끝나는 모델에 가장 잘 맞아요.

동기 예측은 요청을 지정된 시간 동안 열어두는데, 기본값은 60초예요. 이 시간 안에 모델이 끝나면 응답에 output 필드가 채워진 예측 객체가 담겨 와요.

동기 모드는 요청에 Prefer: wait HTTP 헤더를 넣어 켜요.

팁: 이 페이지 예제는 cURL로 적었지만, Replicate의 JavaScript·Python 클라이언트로도 동일하게 예측을 만들 수 있어요.

cURL 예제입니다.

curl -s -X POST \
  -H 'Prefer: wait' \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", "input": {"text": "Alice"}}' \
  https://api.replicate.com/v1/predictions

응답은 예측 객체고, output 필드에 모델 결과가 채워지며 status는 보통 종결 상태(terminal state)예요.

{
  "id": "gm3qorzdhgbfurvjtvhg6dckhu",
  "model": "replicate/hello-world",
  "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "input": {
    "text": "Alice"
  },
  "output": "Hello Alice",
  "logs": "",
  "error": null,
  "status": "successful",
  "created_at": "2023-09-08T16:19:34.765994657Z",
  "completed_at": "2023-09-08T16:20:34.765994657Z",
  "metrics": {
    "predict_time": 58.5,
    "total_time": 60.0
  },
  "urls": {
    "web": "https://replicate.com/p/gm3qorzdhgbfurvjtvhg6dckhu",
    "cancel": "https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu/cancel",
    "get": "https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu"
  }
}

타임아웃 시간

동기 모드의 기본 대기 시간은 60초지만, 헤더로 다른 타임아웃을 지정할 수 있어요. 예를 들어 Prefer: wait=5는 5초를 기다려요.

지정 시간 안에 모델이 끝나지 않으면, 요청은 status가 starting이나 processing인 불완전한 예측 객체를 돌려줘요. 이후 Location 헤더의 URL이나 비동기 모드처럼 urls.get 필드로 예측을 다시 조회하면 돼요.

동기 모드에서 파일 출력

파일을 출력으로 만드는 모델은 모든 파일이 준비되는 즉시 Replicate가 응답해요. 이 경우 output 필드에 파일 출력이 모두 담겨 있지만, status는 여전히 processing 상태일 수 있고 completed_at과 metrics는 아직 채워지지 않을 수도 있어요.

참고: 차단(blocking) API를 쓰기 싫다면 폴링(polling) 모드를 쓸 수 있어요. 연결을 오래 붙잡지 않으면서 예측을 비동기로 처리하고 싶을 때 유용해요. 폴링 모드로 쓰려면 언어별 run() 메서드에 해당 인자를 넘기면 되고, 자세한 내용은 Output files 문서를 참고하세요.

비동기 모드(기본)

비동기 모드는 출력이 곧바로 필요 없을 때, 또는 출력이 커서 요청을 막고 싶지 않을 때 좋아요. 별도 헤더나 파라미터를 설정할 필요 없이, API의 기본 동작이 비동기 모드예요.

비동기 모드는 예측 ID와 불완전한 예측 객체를 곧바로 돌려줘요. 나중에 webhook으로 결과를 받는 요청 예시를 볼게요.

요청 본문입니다.

{
  "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "input": { "text": "Alice" },
  "webhook": "https://my.server.com/webhooks/replicate",
  "webhook_events_filter": ["completed"]
}

cURL 요청입니다.

curl -s -X POST \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa", "input": {"text": "Alice"}, "webhook": "https://my.server.com/webhooks/replicate", "webhook_events_filter": ["completed"]}' \
  https://api.replicate.com/v1/predictions

응답은 starting 상태의 예측입니다.

{
  "id": "gm3qorzdhgbfurvjtvhg6dckhu",
  "model": "replicate/hello-world",
  "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "input": {
    "text": "Alice"
  },
  "output": null,
  "logs": "",
  "error": null,
  "status": "starting",
  "created_at": "2023-09-08T16:19:34.765994657Z",
  "urls": {
    "web": "https://replicate.com/p/gm3qorzdhgbfurvjtvhg6dckhu",
    "cancel": "https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu/cancel",
    "get": "https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu"
  },
  "webhook": "<https://my.server.com/webhooks/replicate>",
  "webhook_events_filter": ["completed"]
}

예측이 완료되면 지정한 webhook URL로 최종 예측 데이터가 호출돼요.

{
  "id": "gm3qorzdhgbfurvjtvhg6dckhu",
  "model": "replicate/hello-world",
  "version": "5c7d5dc6dd8bf75c1acaa8565735e7986bc5b66206b55cca93cb72c9bf15ccaa",
  "input": {
    "text": "Alice"
  },
  "output": "Hello Alice",
  "logs": "",
  "error": null,
  "status": "successful",
  "created_at": "2023-09-08T16:19:34.765994657Z",
  "completed_at": "2023-09-08T16:20:34.765994657Z",
  "urls": {
    "web": "https://replicate.com/p/gm3qorzdhgbfurvjtvhg6dckhu",
    "cancel": "https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu/cancel",
    "get": "https://api.replicate.com/v1/predictions/gm3qorzdhgbfurvjtvhg6dckhu"
  },
  "metrics": {
    "predict_time": 0.582630675,
    "total_time": 60.0
  }
}

폴링

webhook 대신 쓸 수 있는 방법이 폴링이에요. 예측이 종결 상태(succeeded 또는 failed)에 도달할 때까지 반복해서 API를 조회하는 방식이에요. webhook 핸들러를 두기 어려운 상황에서 유용해요.

폴링 순서는 이렇게 돼요.

  1. 예측을 만들고 예측 URL을 얻는다.
  2. 그 예측 URL로 GET 요청을 보낸다.
  3. 예측이 완료되지 않았다면(status가 succeeded나 failed가 아니라면) 잠시(예: 1~2초) 기다린다.
  4. 예측이 완료될 때까지 2~3을 반복한다.

이 방식으로 정해진 간격마다 예측 상태를 확인할 수 있어요. 자세한 내용은 predictions.get 문서를 확인해 보세요.

예측 데드라인

예측이 지정 시간 안에 끝나지 않으면 자동으로 취소하도록 데드라인을 설정할 수 있어요.

데드라인은 예측을 만들 때 Cancel-After 헤더로 지정해요. 유효한 값은 5초에서 24시간 사이예요. 시간 단위를 이렇게 표현할 수 있어요.

  • 정수(초로 해석): 30
  • 정수 뒤 s(초): 30s
  • 정수 뒤 m(분): 5m
  • 정수 뒤 h(시간): 2h

전체 세부 사항은 API 참조의 Cancel-After 헤더 설명을 참고하세요.

예제입니다.

curl -X POST \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
  -H "Cancel-After: 1m30s" \
  -H "Content-Type: application/json" \
  -d $'{
    "input": {
      "prompt": "The sun rises slowly between tall buildings. [Ground-level follow shot] Bicycle tires roll over a dew-covered street at dawn. The cyclist passes through dappled light under a bridge as the entire city gradually wakes up."
    }
  }' \
  https://api.replicate.com/v1/models/bytedance/seedance-1-pro/predictions

데드라인과 동기 모드 대기 시간의 차이

예측 데드라인과 동기 모드 대기 시간은 서로 달라요.

  • 예측 데드라인(Cancel-After 헤더): 예측 자체를 언제 취소할지
  • 동기 모드 대기(Prefer: wait 헤더): HTTP 요청이 결과를 기다리며 얼마나 열려 있을지

둘을 함께 쓸 수 있어요. 예를 들어 2분 데드라인을 두면서 Prefer: wait=10으로 HTTP 연결은 10초만 유지할 수 있죠. 동기 대기 시간이 끝났는데 예측이 아직 돌고 있다면 불완전한 예측 객체를 받아요. 예측은 종료되거나 2분 데드라인에 닿을 때까지 계속 실행돼요. 자세한 내용은 Prediction lifecycle 문서를 보세요.

예측의 웹 URL

모든 예측에는 브라우저에서 예측을 바로 볼 수 있는 urls.web 속성이 있어요. 이 웹 URL로 이런 것들이 가능해요.

  • 예측 디버깅: 로그·입력·출력·메트릭을 보기 편한 화면에서 확인
  • 결과 공유: 팀원이나 고객에게 링크를 보내 모델 출력을 보여주기
  • 진행 모니터링: API를 폴링하는 대신 상태를 시각적으로 확인

프로그래밍 방식으로 웹 URL을 쓰는 예시입니다. cURL과 jq로 계정의 가장 최근 예측 웹 URL을 얻어 브라우저로 여는 코드예요.

curl -s \
  -H "Authorization: Bearer $REPLICATE_API_TOKEN" \
  "https://api.replicate.com/v1/predictions" \
  | jq ".results[0].urls.web" \
  | xargs open

웹 URL 구조는 https://replicate.com/p/{prediction_id} 패턴이에요.

{
  "urls": {
    "web": "https://replicate.com/p/cky59275mdrm80cpw83rcn3ej0",
    "get": "https://api.replicate.com/v1/predictions/cky59275mdrm80cpw83rcn3ej0",
    "stream": "https://stream.replicate.com/v1/files/bcwr-3afcgaxf5opqtgeq5ababozl3erroi6ody73lpkwklvnu7bwtmrq",
    "cancel": "https://api.replicate.com/v1/predictions/cky59275mdrm80cpw83rcn3ej0/cancel"
  }
}

웹 URL은 예측을 만들자마자 바로 사용할 수 있고, 완료 후에도 계속 접근 가능해요. 실시간 모니터링과 완료 후 분석 두 용도 모두에 쓸 수 있죠.

더 알아보기