10장 실제 AI API를 선택적으로 연결한다
기본 실습은 mock으로 완결된다. 실제 모델을 쓰려면 키와 모델을 환경 변수로 지정한다. 모델 이름을 원고에 고정하지 않은 이유는 계정과 시점에 따라 사용 가능한 모델이 달라질 수 있기 때문이다. 공식 모델 페이지에서 현재 권장 모델을 확인한다.
export OPENAI_API_KEY="사용자 환경의 비밀값"
export OPENAI_MODEL="사용 가능한 모델 ID"
export AI_MODE="live"
npm start
PowerShell:
$env:OPENAI_API_KEY="사용자 환경의 비밀값"
$env:OPENAI_MODEL="사용 가능한 모델 ID"
$env:AI_MODE="live"
npm start
AI_MODE=live로 시작한 서버는 의뢰 상세 API에서 analyzeWithOpenAI를 실제로 호출한다. 기본값 mock은 비용과 네트워크 없이 동작한다. 실제 어댑터는 새 프로젝트에 권장되는 Responses API를 호출하고 store: false를 지정한다. API 키는 브라우저 코드에 넣지 않는다. 서버가 비밀값을 보관하고 필요한 필드만 모델에 전달한다. SDK의 output_text 편의 속성에 기대지 않고 REST 응답의 output[].content[]에서 output_text 항목을 꺼낸 뒤 JSON을 파싱한다. test/domain.test.mjs의 가짜 응답 테스트가 이 실제 wire 형식을 고정한다.
상세 카드를 열 때마다 실 API 호출이 한 번 발생할 수 있다. 실습 뒤에는 서버를 종료하고 AI_MODE를 해제한다. 운영 제품에서는 결과 캐시, 호출 한도, 사용자별 비용 정책과 실패 시 mock이 아닌 명시적 수동 검토 경로를 설계한다.
타임아웃, 429, 5xx는 서로 다른 정책이 필요하다. 429와 일시적 5xx는 지수 백오프와 최대 재시도 횟수를 둔다. 400 계열 계약 오류는 재시도하지 말고 코드와 요청을 고친다. 응답 원문과 개인정보를 통째로 로그에 남기지 않는다.