기능 프로필

model 에 feature:<이름> 을 쓰면 모델·기본값·폴백을 게이트웨이에서 정합니다.

무엇인가

model 에 실제 모델 이름 대신 feature:wi-extract 처럼 기능 이름을 쓰면, 운영자가 그 기능에 정해 둔 모델과 기본값이 적용됩니다. 모델을 바꿀 때 앱 코드를 고치고 다시 배포할 필요가 없습니다.

요청

curl https://ai.cubion.kr/v1/chat/completions \
  -H "Authorization: Bearer $GATEWAY_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"feature:wi-extract","messages":[{"role":"user","content":"…"}]}'

실제로 처리한 모델은 응답 헤더 X-Gateway-Model 로 확인할 수 있습니다(요청 추적 헤더). 기능은 운영자가 관리 화면에서 만듭니다 — 필요한 기능 이름과 설정을 운영자에게 요청하세요.

기능에 정할 수 있는 것

항목	동작
모델	이 기능이 부를 실제 모델.
시스템 프롬프트	요청에 `system` 메시지가 없을 때만 맨 앞에 넣습니다.
`temperature`	요청에 없을 때만 적용합니다.
`max_tokens`	요청에 `max_tokens`·`max_completion_tokens` 가 둘 다 없을 때만 적용합니다.
`response_format`	요청에 없을 때만 적용합니다(JSON 출력 강제 등).
타임아웃	상위 호출 한 번의 제한 시간(5–600초, 기본 120초). 긴 문서 추출처럼 오래 걸리는 기능에 씁니다.
폴백 모델	주 모델의 제공사가 전부 실패(한도·크레딧 소진·장애·인증)하면 차례로 시도할 모델.

요청에 적은 값이 항상 이깁니다

기능 설정은 "비어 있을 때의 기본값"입니다. 특정 호출에서만 다르게 하고 싶으면 요청에 값을 적으면 됩니다.

폴백 모델

먼저 같은 모델을 다른 키로 다시 보냅니다(게이트웨이에 같은 제공사 키가 여러 개 있을 때). 그래도 전부 실패하면 폴백 모델로 넘어갑니다.
요청 자체가 잘못된 오류(400 등)에는 넘어가지 않습니다 — 모델을 바꿔도 같은 이유로 실패하고, 원래 원인이 가려지기 때문입니다.
폴백 모델도 이 키가 쓸 수 있는 모델이어야 합니다. 허용되지 않은 폴백 모델은 건너뜁니다.
폴백이 일어났는지는 X-Gateway-Model(실제 모델)과 X-Gateway-Attempts(시도 횟수)로 알 수 있습니다.

임베딩

/v1/embeddings 에도 feature: 이름을 쓸 수 있습니다. 모델 이름만 바뀌고, 폴백 모델은 쓰지 않습니다 — 모델마다 벡터 차원이 달라 색인과 섞이면 검색이 조용히 망가지기 때문입니다.

알아 둘 점

키에 허용 모델을 정해 두었다면, 기능이 가리키는 실제 모델도 허용되어 있어야 합니다. 아니면 403 model_not_allowed 가 옵니다.
등록되지 않았거나 꺼진 기능 이름은 모델이 없는 것으로 처리되어 실패합니다.
Claude 계열 모델은 OpenAI 호환 방식에서 response_format 과 도구의 strict 를 무시합니다. 스키마가 꼭 지켜져야 하는 추출에는 GPT 계열 모델을 쓰고, 받은 JSON 은 앱에서 한 번 더 검증하세요.

사용량은 실제 모델 이름으로 집계됩니다. 기능별 비용을 따로 보려면 기능마다 키를 나눠 쓰세요.

이전모델 목록 다음오류 처리