프로덕션 모범 사례

프로덕션 모범 사례 (Production best practices)

이 가이드는 프로토타입에서 프로덕션으로 넘어갈 때 도움이 되는 종합적인 모범 사례를 제공해요. 머신러닝 엔지니어든 이제 막 시작한 사람이든, API 접근 보안부터 높은 트래픽을 처리하는 견고한 아키텍처 설계까지, 플랫폼을 프로덕션에서 성공적으로 운영하는 데 필요한 도구를 얻을 수 있어요. 이 가이드로 애플리케이션을 최대한 매끄럽고 효과적으로 배포하는 계획을 세워 보세요.

출처: 문서

본문

프로덕션 진입 모범 사례를 더 탐구하고 싶다면 우리의 Developer Day 발표를 확인하세요: https://www.youtube-nocookie.com/embed/XGJNo8TpuVA

조직 설정하기

로그인하면 조직 설정에서 조직 이름과 ID를 찾을 수 있어요. 조직 이름은 UI에 표시되는 조직의 라벨이고, 조직 ID는 API 요청에서 쓸 수 있는 조직의 고유 식별자예요.

여러 조직에 속한 사용자는 헤더를 전달해 API 요청에 사용할 조직을 지정할 수 있어요. 이 API 요청의 사용량은 지정된 조직의 할당량으로 계산돼요. 헤더가 없으면 기본 조직이 청구돼요. 기본 조직은 사용자 설정에서 바꿀 수 있어요.

Team 페이지에서 조직에 새 멤버를 초대할 수 있어요. 멤버는 reader 또는 owner가 될 수 있어요.

Reader:

  • API 요청을 할 수 있어요.
  • 기본 조직 정보를 볼 수 있어요.
  • 달리 명시되지 않는 한 조직의 리소스(예: Assistants)를 생성·업데이트·삭제할 수 있어요.

Owner:

  • Reader의 모든 권한을 가져요.
  • 청구 정보를 수정할 수 있어요.
  • 조직 내 멤버를 관리할 수 있어요.

청구 한도 관리

청구 정보를 입력하면 OpenAI가 조직에 승인된 사용 한도를 설정해요. 플랫폼 사용량이 늘고 한 사용 티어에서 다음으로 이동하면 할당량 한도가 자동으로 증가해요. 현재 사용 한도는 계정 설정의 limits 페이지에서 확인할 수 있어요.

limits 페이지에서 지출 알림을 설정해 사용량이 특정 달러 금액을 초과하면 알림을 받게 할 수 있어요. 월간 상한을 강제하려면 하드 지출 한도를 설정하세요. 하드 지출 한도는 추적된 지출이 한도에 도달하면 영향을 받는 API 트래픽을 중지시키므로, 프로덕션에서 활성화하기 전에 지출 한도 가이드를 검토하세요.

API 키

OpenAI API는 인증에 API 키를 사용해요. 요청에 사용할 API 키는 API keys 페이지에서 가져올 수 있어요.

이것은 접근을 제어하는 비교적 간단한 방법이지만, 키를 안전하게 보호하는 데 각별히 주의해야 해요. 코드나 공개 저장소에 API 키를 노출하지 말고, 안전한 위치에 저장하세요. 앱에서 하드코딩할 필요가 없도록 환경 변수나 비밀 관리 서비스로 키를 노출하세요. API key 안전 모범 사례에서 더 읽어 보세요.

프로젝트 API 키를 만들 때 만료 날짜를 설정하고 정기적인 키 회전 프로세스를 만드는 것을 강력히 권장해요. 키가 만료되기 전에 교체용을 만들고, 앱이 새 키를 사용하도록 업데이트하고, 교체가 작동하는지 확인한 뒤 기존 키를 취소하세요.

관리자는 Platform settings에서 조직·프로젝트 수준으로 API 키 최대 수명을 강제할 수 있어요. 새 키는 구성된 한도 안에서 만료되어야 하므로 무기한 유효하지 않게 돼요. 프로젝트 한도는 조직 한도를 초과할 수 없어요.

Platform settings의 API Key Governance 섹션을 통해 조직·프로젝트 관리자는 만들 수 있는 API 키 유형을 제한할 수 있어요. 서비스 계정 키만 허용하거나, 사용자 소유 프로젝트 키만 허용하거나, 모든 새 API 키 생성을 비활성화할 수 있어요. 조직 수준 제한이 항상 우선해요. 프로젝트 설정은 제한을 추가할 수 있지만 조직 수준 제한을 완화할 수는 없어요. 이 제어는 새 키 생성에만 적용되고 기존 API 키는 영향을 받지 않아요.

추적이 활성화되면 Usage 페이지에서 API 키 사용량을 모니터링할 수 있어요. 2023년 12월 20일 이전에 생성된 API 키는 기본적으로 추적이 활성화되지 않아요. API key 관리 대시보드에서 향후 추적을 활성화할 수 있어요. 2023년 12월 20일 이후 생성된 모든 API 키는 추적이 활성화돼요. 이전의 추적되지 않은 사용량은 대시보드에 Untracked로 표시돼요.

스테이징 프로젝트

규모가 커지면 스테이징과 프로덕션 환경에 별도의 프로젝트를 만들고 싶을 수 있어요. 대시보드에서 이 프로젝트를 만들어 개발·테스트 작업을 격리해서 라이브 애플리케이션을 실수로 방해하지 않게 할 수 있어요. 프로덕션 프로젝트에 사용자 접근을 제한하고 프로젝트별 사용자 지정 속도·지출 한도를 설정할 수도 있어요.

솔루션 아키텍처 확장

우리 API를 쓰는 애플리케이션·서비스를 프로덕션용으로 설계할 때, 트래픽 수요를 충족하도록 확장할 방법을 고려하는 것이 중요해요. 클라우드 서비스 제공자와 무관하게 몇 가지 핵심 영역을 고려해야 해요.

  • 수평 확장(Horizontal scaling): 여러 소스에서 오는 애플리케이션 요청을 처리하도록 앱을 수평으로 확장할 수 있어요. 로드를 분산하기 위해 추가 서버나 컨테이너를 배포하는 방식이에요. 이 방식을 선택한다면 아키텍처가 여러 노드를 처리하도록 설계되고 그 사이에 로드를 균형 잡는 메커니즘을 갖추었는지 확인하세요.
  • 수직 확장(Vertical scaling): 다른 옵션은 앱을 수직으로 확장하는 것으로, 단일 노드에 사용 가능한 리소스를 늘리는 뜻이에요. 추가 로드를 처리하도록 서버 성능을 업그레이드하는 방식이에요. 이 방식을 선택한다면 앱이 이 추가 리소스를 활용하도록 설계되었는지 확인하세요.
  • 캐싱(Caching): 자주 접근되는 데이터를 저장하면 우리 API에 반복 호출하지 않고 응답 시간을 개선할 수 있어요. 앱은 가능하면 캐시된 데이터를 사용하고 새 정보가 추가되면 캐시를 무효화하도록 설계되어야 해요. 예를 들어 애플리케이션에 가장 적합한 방식에 따라 데이터를 데이터베이스, 파일시스템, 인메모리 캐시에 저장할 수 있어요.
  • 로드 밸런싱(Load balancing): 마지막으로 요청이 사용 가능한 서버에 고르게 분산되도록 로드 밸런싱 기법을 고려하세요. 서버 앞에 로드 밸런서를 두거나 DNS round-robin을 쓰는 방식이에요. 로드를 균형 잡으면 성능이 개선되고 병목이 줄어요.

요청 본문 압축

업로드 크기를 줄이려면 POST /v1/responses를 호출할 때 JSON 요청 본문을 zstd로 압축하세요. Content-Encoding: zstd를 설정하고 Content-Type: application/json을 유지하세요.

zstd -3 -c request.json > request.json.zst

curl https://api.openai.com/v1/responses \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -H "Content-Encoding: zstd" \
  --data-binary @request.json.zst

API는 요청을 처리하기 전에 본문을 압축 해제해요. 압축은 네트워크로 보내는 바이트를 줄여요. 토큰 사용이나 모델 컨텍스트 한도는 바꾸지 않아요.

압축된 본문과 압축 해제된 본문 모두 최대 128 MiB여야 해요. 압축 해제된 본문은 압축 크기의 최대 100배여야 해요. 이 한도를 초과하는 요청은 HTTP 413을 반환해요. API는 유효하지 않거나 불완전한 zstd 데이터에 HTTP 400을 반환해요. 다른 요청 한도는 여전히 적용돼요.

WebSocket 메시지 압축

Responses API WebSocket 모드는 wss://api.openai.com/v1/responses에서 permessage-deflate를 지원해요. 이 WebSocket 확장은 DEFLATE를 사용해 메시지 크기를 줄여요. 연결 전에 WebSocket 클라이언트의 압축 설정에서 활성화하세요.

속도 한도 관리

우리 API를 쓸 때 속도 한도를 이해하고 계획하는 것이 중요해요.

지연 시간 개선

가장 최신의 지연 시간 최적화 가이드를 확인하세요.

지연 시간은 요청이 처리되고 응답이 반환되는 데 걸리는 시간이에요. 이 섹션에서는 텍스트 생성 모델의 지연 시간에 영향을 주는 몇 가지 요인을 논의하고 줄이는 방법을 제안해요.

완료 요청의 지연 시간은 주로 두 요인에 영향을 받아요: 모델과 생성된 토큰 수. 완료 요청의 수명 주기는 이렇게 생겼어요.

  • 최종 사용자에서 API까지 지연
  • 프롬프트 토큰 처리 시간
  • 토큰 샘플링/생성 시간
  • API에서 최종 사용자까지 지연

지연 시간의 대부분은 일반적으로 토큰 생성 단계에서 발생해요.

직관: 프롬프트 토큰은 완료 호출에 지연을 거의 더하지 않아요. 완료 토큰을 생성하는 시간은 훨씬 깁니다. 토큰은 한 번에 하나씩 생성되기 때문이에요. 더 긴 생성 길이는 각 토큰에 필요한 생성 때문에 지연 시간을 누적해요.

지연 시간에 영향을 주는 일반적 요인과 완화 기법

지연 시간의 기초를 살펴봤으니, 영향이 큰 순서에서 작은 순서로 지연 시간에 영향을 줄 수 있는 다양한 요인을 살펴볼게요.

모델

우리 API는 다양한 복잡성과 일반성을 가진 여러 모델을 제공해요. gpt-6-astra 같은 가장 강력한 모델은 더 복잡하고 다양한 완료를 생성할 수 있지만, 쿼리를 처리하는 데도 더 오래 걸려요.

gpt-5.6-terra나 gpt-5.6-luna 같은 모델은 더 빠르고 저렴한 Responses를 생성할 수 있고, gpt-6-astra는 복잡한 작업에 여유를 더 원할 때 더 강력한 기본값이에요. 사용 사례와 속도·비용·품질의 트레이드오프에 가장 잘 맞는 모델을 선택할 수 있어요.

완료 토큰 수

많은 생성 토큰을 요청하면 지연 시간이 늘어날 수 있어요.

  • max tokens 낮추기: 유사한 토큰 생성 수의 요청에서 max_tokens 파라미터가 낮은 요청이 지연이 적어요.
  • 중지 시퀀스 포함: 불필요한 토큰 생성을 막으려면 중지 시퀀스를 추가하세요. 예를 들어 중지 시퀀스로 특정 항목 수의 목록을 생성할 수 있어요. 이 경우 11.을 중지 시퀀스로 쓰면 완료가 11.에 도달할 때 멈추므로 10개 항목의 목록만 생성돼요. 중지 시퀀스 도움말 문서에서 더 읽어 보세요.
  • 완료를 더 적게 생성: 가능하면 n과 best_of 값을 낮추세요. n은 각 프롬프트에 생성할 완료 수, best_of는 토큰당 가장 높은 로그 확률의 결과를 나타내는 데 쓰여요.

n과 best_of가 모두 1(기본값)이면 생성된 토큰 수는 최대 max_tokens와 같아요.

n(반환되는 완료 수)이나 best_of(고려용으로 생성되는 완료 수)가 > 1이면 각 요청이 여러 출력을 만듭니다. 여기서 생성된 토큰 수는 [ max_tokens * max (n, best_of) ]로 볼 수 있어요.

스트리밍

요청에서 stream: true를 설정하면 전체 토큰 시퀀스가 생성될 때까지 기다리는 대신, 토큰이 사용 가능해지는 즉시 반환하기 시작해요. 모든 토큰을 얻는 시간은 바꾸지 않지만, 부분 진행을 보여주거나 생성을 중지하려는 애플리케이션에서 첫 토큰까지의 시간은 줄여줘요. 더 나은 사용자 경험과 UX 개선이 될 수 있으니 스트리밍을 실험해 볼 가치가 있어요.

배칭

사용 사례에 따라 배칭이 도움이 될 수 있어요. 같은 엔드포인트로 여러 요청을 보낸다면 프롬프트를 배치해 같은 요청으로 보낼 수 있어요. 이렇게 하면 만들어야 하는 요청 수가 줄어요. 프롬프트 파라미터는 최대 20개의 고유 프롬프트를 담을 수 있어요. 이 방법을 테스트해 보고 도움이 되는지 확인하길 권장해요. 어떤 경우에는 생성된 토큰 수가 늘어 응답 시간이 느려질 수 있어요.

비용 관리

비용을 모니터링하려면 계정에 알림 임계값을 설정해 특정 사용 임계값을 넘으면 이메일 알림을 받게 할 수 있어요. 사용 추적 대시보드로 현재·이전 청구 주기의 토큰 사용을 모니터링하세요.

텍스트 생성

프로토타입을 프로덕션으로 옮길 때의 어려움 중 하나는 애플리케이션 운영 비용을 예산화하는 것이에요. OpenAI는 1,000 토큰(약 750단어)당 가격의 pay-as-you-go 가격 모델을 제공해요. 비용을 추정하려면 토큰 사용량을 예상해야 해요. 트래픽 수준, 사용자가 앱과 상호작용하는 빈도, 처리할 데이터 양 같은 요인을 고려하세요.

비용 줄이기를 생각하는 유용한 프레임워크 하나는 비용을 토큰 수와 토큰당 비용의 함수로 보는 것입니다. 이 프레임워크로 두 가지 방식으로 비용을 줄일 수 있어요. 첫째, 일부 작업에 더 작은 모델로 전환해 토큰당 비용을 줄일 수 있어요. 둘째, 필요한 토큰 수를 줄일 수 있어요. 더 짧은 프롬프트를 쓰거나, 모델을 fine-tuning하거나, 반복 처리할 필요가 없도록 흔한 사용자 쿼리를 캐싱하는 등 여러 방법으로 할 수 있어요.

비용 추정에 도움이 되는 대화형 토크나이저 도구로 실험할 수 있어요. API와 playground도 응답의 일부로 토큰 수를 반환해요. 가장 강력한 모델로 작업이 되면 다른 모델이 더 낮은 지연·비용으로 같은 결과를 만들 수 있는지 확인해 보세요. 토큰 사용 도움말 문서에서 더 읽어 보세요.

MLOps 전략

프로토타입을 프로덕션으로 옮기면서 MLOps 전략을 개발하는 것을 고려할 수 있어요. MLOps(machine learning operations)는 우리 API로 fine-tuning하는 모델을 포함해 머신러닝 모델의 종단 간 수명 주기를 관리하는 프로세스를 말해요. MLOps 전략을 설계할 때 다음 영역을 고려하세요.

  • 데이터·모델 관리: 모델을 학습·fine-tuning하는 데 쓰는 데이터 관리와 버전·변경 추적.
  • 모델 모니터링: 시간에 따른 모델 성능 추적과 잠재적 문제·성능 저하 감지.
  • 모델 재학습: 데이터 변화나 진화하는 요구사항에 맞춰 모델이 최신 상태를 유지하게 하고, 필요에 따라 재학습·fine-tuning.
  • 모델 배포: 모델과 관련 산출물을 프로덕션에 배포하는 과정 자동화.

애플리케이션의 이 측면들을 생각하면 모델이 시간이 지나도 관련성 있고 성능이 유지될 수 있어요.

보안과 규정 준수

프로토타입을 프로덕션으로 옮기면서 애플리케이션에 적용될 수 있는 보안·규정 준수 요구사항을 평가하고 다뤄야 해요. 처리하는 데이터를 검토하고, 우리 API가 데이터를 처리하는 방식을 이해하며, 준수해야 할 규정을 결정하는 것이 포함돼요. 보안 관행과 신뢰·규정 준수 포털이 가장 포괄적이고 최신 문서를 제공해요. 참고로 개인정보 처리방침과 이용 약관이 있어요.

고려해야 할 흔한 영역에는 데이터 저장, 데이터 전송, 데이터 보유가 있어요. 가능한 곳에서 암호화나 익명화 같은 데이터 프라이버시 보호 조치를 구현해야 할 수도 있어요. 또한 입력 살균과 적절한 오류 처리 같은 안전한 코딩 모범 사례를 따라야 해요.

안전성 모범 사례

우리 API로 애플리케이션을 만들 때 안전성 모범 사례를 고려해 애플리케이션이 안전하고 성공적이게 하세요. 이 권장사항은 제품을 광범위하게 테스트하고, 잠재적 문제에 적극적으로 대응하며, 오용 가능성을 제한하는 것의 중요성을 강조해요.

비즈니스 고려 사항

AI를 쓰는 프로젝트가 프로토타입에서 프로덕션으로 갈 때, AI로 훌륭한 제품을 만드는 방법과 그것이 핵심 비즈니스와 어떻게 연결되는지 고려하는 것이 중요해요. 확실히 모든 답을 갖고 있지는 않지만, 좋은 출발점은 우리 Developer Day에서 일부 고객과 함께 다룬 이 발표예요: https://www.youtube-nocookie.com/embed/knHW-p31R0c

더 알아보기 (Learn more)

관련 문서: 지연 시간 최적화, 속도 제한, 모델 최적화, 안전성 모범 사례 가이드를 함께 보면 좋아요.