컴플리션 API (Completions)

채팅 완성 API가 메시지 형식을 자동으로 잡아주는 데 비해, 모델에 보내는 프롬프트를 정확히 직접 제어해야 할 때가 있어요. 그럴 때 쓰는 게 컴플리션(completions) API예요. 메시지 포매팅 없이 원시(raw) 텍스트 생성만 하기 때문에, 프롬프트 템플릿을 완전히 통제해야 하는 경우에 적합해요.

출처: https://docs.fireworks.ai/guides/completions-api

언제 쓰면 좋을까

컴플리션 API는 커스텀 프롬프트 템플릿을 써야 하거나, 인스트럭트/챗 변형이 아닌 베이스 모델(base model)을 다룰 때, 토큰 단위의 세밀한 제어가 필요하거나, 기존 레거시 애플리케이션이 원시 완성 형식에 의존할 때 좋아요. 다만 대부분의 경우에는 채팅 완성 API를 쓰는 게 낫다는 점을 기억해 두세요. 채팅 완성은 메시지 형식을 자동으로 처리하고 인스트럭트 튜닝 모델과도 더 잘 맞아요.

기본 사용법

Fireworks SDK로 간단하게 요청을 보내면 돼요. 모델에 prompt를 전달하고 반환된 choices[0].text를 읽으면 완성 결과를 얻어요.

from fireworks import Fireworks

client = Fireworks()

response = client.completions.create(
  model="accounts/fireworks/models/deepseek-v3p1",
  prompt="Once upon a time"
)

print(response.choices[0].text)

대부분의 모델은 프롬프트 앞에 시작 문장 토큰(BOS, 예: <s>)을 자동으로 붙여요. 이 동작을 확인하고 싶다면 raw_output 파라미터를 쓰면 돼요.

커스텀 프롬프트 템플릿이 필요할 때, 예를 들어 few-shot 감성 분류 템플릿을 만들 때도 prompt에 그대로 넣으면 동작해요.

주요 파라미터

채팅 완성 파라미터가 컴플리션에도 그대로 적용돼요.

temperature: 랜덤성 제어(0~2)
max_tokens: 출력 길이 제한
top_p, top_k, min_p: 샘플링 파라미터
stream: 토큰 단위 스트리밍
frequency_penalty, presence_penalty: 반복 줄이기

완전한 파라미터 문서는 API 레퍼런스를 참고하세요.

배포에서 쓰기

컴플리션 API도 전용 배포(on-demand deployment)와 함께 쓸 수 있어요. 이때는 모델 대신 배포 식별자(accounts/<ACCOUNT_ID>/deployments/<DEPLOYMENT_ID>)를 지정해요.

더 알아보기

채팅 완성: 대부분의 경우 채팅 완성을 사용
스트리밍: 실시간 UX를 위한 스트리밍 응답
API 레퍼런스: 컴플리션 API 전체 문서