프로덕션 운영 모범 사례

이 가이드는 프로토타입을 프로덕션으로 전환할 때 필요한 모범 사례를 폭넓게 다룹니다. 숙련된 머신러닝 엔지니어부터 이제 막 머신러닝에 관심을 갖기 시작한 분까지, 누구나 프로덕션 환경에서 OpenAI 플랫폼을 활용하는 방법을 익힐 수 있습니다. API 접근을 안전하게 관리하는 방법부터 대량의 트래픽을 처리할 수 있는 안정적인 아키텍처를 설계하는 방법까지 살펴보고, 이를 바탕으로 애플리케이션을 원활하고 효과적으로 배포할 계획을 세우세요.

프로덕션 전환 모범 사례를 더 자세히 알아보려면 Developer Day 발표를 시청하세요.

조직 설정

OpenAI 계정에 로그인하면 조직 설정에서 조직 이름과 조직 ID를 확인할 수 있습니다. 조직 이름은 사용자 인터페이스에 표시되는 이름입니다. 조직 ID는 API 요청에서 조직을 지정할 때 사용할 수 있는 고유 식별자입니다.

여러 조직에 속한 사용자는 헤더를 전달해 API 요청에 사용할 조직을 지정할 수 있습니다. 해당 요청의 사용량은 지정한 조직의 할당량에 반영됩니다. 헤더를 생략하면 기본 조직에 요금이 청구됩니다. 기본 조직은 사용자 설정에서 변경할 수 있습니다.

팀 페이지에서 조직에 새 구성원을 초대할 수 있습니다. 구성원에게는 Reader 또는 소유자 역할을 부여할 수 있습니다.

Reader의 권한은 다음과 같습니다.

• API 요청을 보낼 수 있습니다.
• 조직의 기본 정보를 볼 수 있습니다.
• 별도 안내가 없는 한 조직 내 리소스(예: 어시스턴트)를 생성, 업데이트, 삭제할 수 있습니다.

소유자의 권한은 다음과 같습니다.

• Reader의 모든 권한을 갖습니다.
• 결제 정보를 수정할 수 있습니다.
• 조직 구성원을 관리할 수 있습니다.

청구 한도 관리

결제 정보를 입력하면 OpenAI가 조직에 허용되는 사용 한도를 설정합니다. 플랫폼 사용량이 늘어 다음 사용 등급으로 올라가면 할당량도 자동으로 증가합니다. 현재 사용 한도는 계정 설정의 한도 페이지에서 확인할 수 있습니다.

한도 페이지에서 지출 알림을 설정하면 사용 금액이 달러 단위로 지정한 기준을 초과할 때 알림을 받을 수 있습니다. 월 지출에 상한을 적용하려면 강제 지출 한도를 설정하세요. 집계된 지출액이 한도에 도달하면 해당 한도가 적용되는 API 트래픽이 중단되므로, 프로덕션에서 활성화하기 전에 지출 한도 가이드를 확인하세요.

API 키

OpenAI API는 인증에 API 키를 사용합니다. API 키 페이지에서 요청에 사용할 API 키를 확인하세요.

애플리케이션이 API에 인증할 때는 개발자 개인의 키에 의존하지 말고 프로젝트 서비스 계정을 사용하세요. 인증 정보를 선택하고 프로젝트 및 키 관리를 자동화하는 방법은 API 키 및 서비스 계정을 참고하세요.

API 키는 접근을 제어하는 비교적 간단한 수단이지만, 키를 안전하게 관리하려면 주의가 필요합니다. 코드나 공개 레포지토리에 API 키를 노출하지 말고 안전한 위치에 보관하세요. 환경 변수나 시크릿 관리 서비스를 통해 애플리케이션에 키를 제공하면 코드베이스에 키를 하드코딩할 필요가 없습니다. 자세한 내용은 API 키 보안 모범 사례를 참고하세요.

프로젝트 API 키를 만들 때 만료일을 설정하고 키를 정기적으로 교체하는 절차를 마련할 것을 강력히 권장합니다. 키가 만료되기 전에 새 키를 생성하고 애플리케이션이 새 키를 사용하도록 업데이트하세요. 새 키가 정상적으로 작동하는지 확인한 후 기존 키를 폐기하세요.

관리자는 플랫폼 설정에서 조직 또는 프로젝트별로 API 키의 최대 유효 기간을 지정할 수 있습니다. 새 키는 설정한 기간 안에 만료되어야 하므로 무기한 유효한 상태로 남지 않습니다. 프로젝트의 최대 유효 기간은 조직에서 설정한 기간을 초과할 수 없습니다.

플랫폼 설정의 API 키 거버넌스 섹션에서 조직 및 프로젝트 관리자는 생성할 수 있는 API 키의 유형을 제한할 수 있습니다. 서비스 계정 키만 허용하거나, 사용자 소유의 프로젝트 키만 허용하거나, 새 API 키 생성을 전면 차단할 수 있습니다. 조직 수준의 제한이 항상 우선합니다. 프로젝트 설정에서 제한을 추가할 수는 있지만 조직에서 설정한 제한을 완화할 수는 없습니다. 이러한 설정은 새 키를 생성할 때만 적용되며 기존 API 키에는 영향을 주지 않습니다.

추적을 활성화하면 사용량 페이지에서 API 키 사용량을 모니터링할 수 있습니다. 2023년 12월 20일 전에 생성한 API 키는 기본적으로 추적이 비활성화되어 있습니다. API 키 관리 대시보드에서 추적을 활성화하면 그 시점부터 사용량이 기록됩니다. 2023년 12월 20일이 지난 뒤 생성한 모든 API 키는 추적이 활성화되어 있습니다. 이전에 추적되지 않은 사용량은 대시보드에 Untracked로 표시됩니다.

스테이징 프로젝트

서비스 규모가 커지면 스테이징 환경과 프로덕션 환경에 각각 별도의 프로젝트를 만드는 방안을 고려하세요. 대시보드에서 프로젝트를 분리하면 개발 및 테스트 작업 중에 운영 중인 애플리케이션에 실수로 영향을 주는 일을 방지할 수 있습니다. 프로덕션 프로젝트에 대한 사용자 접근을 제한하고 프로젝트별로 요청 한도와 지출 한도를 설정할 수도 있습니다.

솔루션 아키텍처 확장

OpenAI API를 사용하는 애플리케이션이나 서비스를 프로덕션용으로 설계할 때는 트래픽 수요에 맞춰 어떻게 확장할지 고려해야 합니다. 어떤 클라우드 서비스 제공업체를 선택하든 다음 사항을 검토하세요.

• 수평 확장: 여러 곳에서 들어오는 요청을 처리하기 위해 애플리케이션을 수평으로 확장할 수 있습니다. 예를 들어 서버나 컨테이너를 추가로 배포해 부하를 분산할 수 있습니다. 이 방식을 선택한다면 여러 노드를 지원하도록 아키텍처를 설계하고 노드 간에 부하를 고르게 분산할 수단을 마련하세요.
• 수직 확장: 단일 노드에서 사용할 수 있는 리소스를 늘려 애플리케이션을 수직으로 확장할 수도 있습니다. 이 경우 추가 부하를 처리할 수 있도록 서버의 성능을 높입니다. 이 방식을 선택한다면 애플리케이션이 추가된 리소스를 활용할 수 있도록 설계하세요.
• 캐싱: 자주 접근하는 데이터를 저장해 두면 API를 반복해서 호출하지 않고도 응답 시간을 단축할 수 있습니다. 가능하면 캐시된 데이터를 사용하고 새 정보가 추가되면 캐시를 무효화하도록 애플리케이션을 설계하세요. 예를 들어 애플리케이션 특성에 따라 데이터베이스, 파일 시스템 또는 인메모리 캐시에 데이터를 저장할 수 있습니다.
• 로드 밸런싱: 사용 가능한 서버에 요청이 고르게 분산되도록 로드 밸런싱 기법을 검토하세요. 서버 앞에 로드 밸런서를 배치하거나 DNS 라운드 로빈 방식을 사용할 수 있습니다. 부하를 분산하면 성능을 높이고 병목 현상을 줄이는 데 도움이 됩니다.

요청 본문 압축

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

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

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

API는 요청을 처리하기 전에 본문의 압축을 풉니다. 압축하면 네트워크로 전송하는 바이트 수가 줄어듭니다. 토큰 사용량이나 모델의 컨텍스트 한도에는 영향을 주지 않습니다.

압축된 본문과 압축을 푼 본문은 각각 128 MiB 이하여야 합니다. 또한 압축을 푼 본문의 크기는 압축된 크기의 100배 이하여야 합니다. 요청이 이 한도 중 하나라도 초과하면 API는 HTTP 413을 반환합니다. API가 HTTP 400을 반환하는 경우는 zstd 데이터가 유효하지 않거나 불완전할 때입니다. 다른 요청 제한도 그대로 적용됩니다.

WebSocket 메시지 압축

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

요청 한도 관리

OpenAI API를 사용할 때는 요청 한도를 파악하고 이를 고려해 계획을 세우세요.

지연 시간 단축

지연 시간은 요청을 처리하고 응답을 반환하기까지 걸리는 시간입니다. 이 섹션에서는 텍스트 생성 모델의 지연 시간에 영향을 미치는 요인과 지연 시간을 줄이는 방법을 살펴봅니다.

완성 요청의 지연 시간은 주로 모델과 생성되는 토큰 수에 따라 달라집니다. 완성 요청은 다음과 같은 과정을 거칩니다.

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

기본 원리: 프롬프트 토큰이 완성 요청의 지연 시간에 미치는 영향은 작습니다. 반면 완성 토큰은 한 번에 하나씩 생성되므로 훨씬 많은 시간이 걸립니다. 출력이 길수록 각 토큰을 생성하는 데 걸리는 시간이 누적되어 지연 시간이 늘어납니다.

지연 시간에 영향을 미치는 주요 요인과 완화 방법

지연 시간에 영향을 주는 요인을 대체로 영향이 큰 것부터 살펴보겠습니다.

모델

OpenAI API는 복잡도와 범용성이 다양한 모델을 제공합니다. gpt-6-astra처럼 성능이 뛰어난 모델은 더 복잡하고 다양한 완성 결과를 생성할 수 있지만, 질의를 처리하는 데 시간이 더 걸립니다. gpt-5.6-terra 및 gpt-5.6-luna 같은 모델은 더 빠르고 저렴하게 응답을 생성할 수 있습니다. 복잡한 작업까지 여유 있게 처리할 기본 모델이 필요하다면 gpt-6-astra가 더 적합합니다. 사용 사례에 맞게 속도, 비용, 품질 간의 균형을 고려해 모델을 선택하세요.

완성 토큰 수

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

• 최대 토큰 수 줄이기: 생성되는 토큰 수가 비슷한 요청이라면 max_tokens 매개변수 값이 낮을수록 지연 시간이 짧습니다.
• 중단 시퀀스 추가하기: 불필요한 토큰 생성을 막으려면 중단 시퀀스를 추가하세요. 예를 들어 중단 시퀀스를 사용하면 목록의 항목 수를 지정할 수 있습니다. 11.을 중단 시퀀스로 사용하면 항목이 10개인 목록을 생성할 수 있습니다. 11.에 도달하는 순간 생성이 중단되기 때문입니다. 구체적인 사용 방법은 중단 시퀀스 도움말을 참고하세요.
• 완성 결과 수 줄이기: 가능하면 n과 best_of 값을 낮추세요. n은 프롬프트마다 생성할 완성 결과 수를 지정하고, best_of는 후보 중 토큰당 로그 확률이 가장 높은 결과를 선택하는 데 사용합니다.

n과 best_of가 모두 기본값인 1이면 생성되는 토큰 수는 최대 max_tokens입니다.

n(반환할 완성 결과 수) 또는 best_of(후보로 생성할 완성 결과 수)가 > 1이면 요청마다 여러 출력이 생성됩니다. 이 경우 생성되는 토큰 수를 [ max_tokens * max (n, best_of) ]로 추산할 수 있습니다.

스트리밍

요청에 stream: true를 설정하면 모델이 전체 토큰 시퀀스를 생성할 때까지 기다리지 않고 토큰이 준비되는 대로 반환하기 시작합니다. 모든 토큰을 받기까지 걸리는 시간은 같지만 첫 번째 토큰을 더 빨리 받을 수 있습니다. 생성 중인 내용을 사용자에게 보여 주거나 생성을 도중에 중단하려는 애플리케이션에서는 사용자 경험을 개선할 수 있으므로 스트리밍을 시험해 보세요.

배치 처리

사용 사례에 따라 배치 처리가 도움이 될 수 있습니다. 같은 엔드포인트에 여러 요청을 보내고 있다면 프롬프트를 묶어 하나의 요청으로 전송할 수 있습니다. 이렇게 하면 요청 횟수가 줄어듭니다. 프롬프트 매개변수에는 서로 다른 프롬프트를 최대 20개까지 담을 수 있습니다. 이 방식이 효과적인지 직접 테스트해 보세요. 경우에 따라 생성되는 토큰 수가 늘어 응답이 느려질 수도 있습니다.

비용 관리

계정에서 알림 기준을 설정하면 사용량이 지정한 기준을 초과할 때 이메일 알림을 받아 비용을 모니터링할 수 있습니다. 사용량 추적 대시보드에서 현재 및 이전 청구 기간의 토큰 사용량을 확인하세요.

텍스트 생성

프로토타입을 프로덕션으로 전환할 때 고려해야 할 과제 중 하나는 애플리케이션 운영 비용을 예측해 예산을 세우는 것입니다. OpenAI는 사용량 기반 요금제를 제공하며, 요금은 토큰 1,000개(약 750단어) 단위로 책정됩니다. 비용을 추산하려면 예상 토큰 사용량을 계산해야 합니다. 트래픽 규모, 사용자의 애플리케이션 이용 빈도, 처리할 데이터양 등을 고려하세요.

비용을 줄일 방법을 찾을 때는 총비용을 결정하는 두 요소인 토큰 수와 토큰당 비용을 살펴보세요. 이를 바탕으로 두 가지 접근법을 고려할 수 있습니다. 첫째, 일부 작업에 더 작은 모델을 사용해 토큰당 비용을 낮출 수 있습니다. 둘째, 필요한 토큰 수를 줄일 수 있습니다. 예를 들어 프롬프트를 짧게 작성하거나, 모델을 파인튜닝하거나, 자주 들어오는 사용자 질의를 캐싱해 반복해서 처리하지 않도록 할 수 있습니다.

대화형 토크나이저 도구로 다양한 입력을 시험해 비용을 추산할 수 있습니다. API와 Playground에서도 응답에 포함된 토큰 수를 확인할 수 있습니다. 가장 성능이 뛰어난 모델로 원하는 결과를 얻었다면 다른 모델로도 더 짧은 지연 시간과 더 낮은 비용으로 같은 결과를 얻을 수 있는지 확인해 보세요. 자세한 내용은 토큰 사용량 도움말을 참고하세요.

MLOps 전략

프로토타입을 프로덕션으로 전환할 때는 MLOps 전략 수립을 고려해 보세요. MLOps(머신러닝 운영)는 머신러닝 모델의 전체 수명 주기를 관리하는 과정을 뜻합니다. OpenAI API로 파인튜닝하는 모델도 관리 대상에 포함됩니다. MLOps 전략을 설계할 때는 다음 사항을 고려하세요.

• 데이터 및 모델 관리: 모델 학습이나 파인튜닝에 사용하는 데이터를 관리하고 버전과 변경 사항을 추적합니다.
• 모델 모니터링: 시간에 따른 모델 성능을 추적하고 잠재적인 문제나 성능 저하를 감지합니다.
• 모델 재학습: 데이터나 요구 사항의 변화에 맞춰 모델을 최신 상태로 유지하고 필요에 따라 재학습하거나 파인튜닝합니다.
• 모델 배포: 모델과 관련 아티팩트를 프로덕션에 배포하는 과정을 자동화합니다.

애플리케이션을 운영할 때 이러한 사항을 충분히 고려하면 시간이 지나도 모델이 요구 사항에 부합하고 좋은 성능을 유지하는 데 도움이 됩니다.

보안 및 규정 준수

프로토타입을 프로덕션으로 전환할 때는 애플리케이션에 적용될 수 있는 보안 및 규정 준수 요건을 파악하고 충족해야 합니다. 이를 위해 어떤 데이터를 취급하는지 살펴보고, OpenAI API의 데이터 처리 방식을 이해하고, 준수해야 할 규정을 확인하세요. 가장 포괄적인 최신 문서는 OpenAI의 보안 관행 및 신뢰 및 규정 준수 포털에서 확인할 수 있습니다. 개인정보 보호 정책과 이용약관도 참고하세요.

일반적으로 검토해야 할 사항에는 데이터 저장, 전송, 보존이 있습니다. 가능한 경우 암호화나 익명화 같은 개인정보 보호 조치를 구현해야 할 수도 있습니다. 또한 입력값 정제, 적절한 오류 처리 등 안전한 코딩을 위한 모범 사례를 따르세요.

안전 모범 사례

OpenAI API로 애플리케이션을 만들 때는 안전하게 개발하고 성공적으로 운영할 수 있도록 안전 모범 사례를 검토하세요. 이 권장 사항에서는 제품을 충분히 테스트하고 잠재적인 문제에 선제적으로 대응하며 오용 가능성을 줄이는 것이 중요하다고 강조합니다.

비즈니스 고려 사항

AI 프로젝트를 프로토타입에서 프로덕션으로 전환할 때는 AI로 좋은 제품을 만드는 방법과 그 제품이 핵심 사업에 어떻게 기여하는지 함께 고려해야 합니다. 모든 상황에 맞는 답이 있는 것은 아니지만, OpenAI 고객들과 이 주제를 깊이 있게 논의한 Developer Day 발표가 좋은 출발점이 될 수 있습니다.