내 AI API가 계속 실패하던 이유 — 간단한 클라이언트를 만들기 전까지

지난달 저는 사이드 프로젝트를 위해 콘텐츠 요약기를 만들고 있었습니다. 텍ran 덩어리들을 AI API에 입력하고 요약본을 받아와야 했습니다. 간단해 보였죠, 그렇지 않나요? 하지만 첫 50번의 요청 안에 Rate Limit (속도 제한), 503 에러, 그리고 Timeout (시간 초과)을 마주했습니다. 제가 선택한 제공업체의 공식 SDK가 이 중 일부를 처리해주긴 했지만, 그것은 Black Box (블랙박스)였습니다. 저는 Retry (재시도) 로직을 제어하거나 상세한 에러 메시지를 볼 수 없었습니다. 그리고 (가격 변동 때문에) 제공업체를 변경했을 때는 코드의 절반을 다시 작성해야 했습니다.

저는 특정 벤더에 종속되지 않고(Vendor lock-in 없이) 어떤 AI API든 호출할 수 있는 가볍고 신뢰할 수 있는 방법이 필요했습니다. 일주일간의 시행착오 끝에 배운 내용을 공유합니다.

내가 시작했던 엉망진창이었던 방식

저의 첫 번째 시도는 서류상으로는 깔끔했습니다. 단순한 try-except와 함께 requests를 사용하는 것이었죠. 하지만 저는 프로덕션 환경의 AI API가 로컬 데이터베이스만큼 신뢰할 수 없다는 것을 빠르게 깨달았습니다. API는 Throttling (스로틀링)을 걸고, 429 에러를 반환하며, 요청 하나에 30초가 걸리기도 하고, 때로는 응답 중간에 충돌이 발생하기도 합니다. 제 코드는 Retry Decorator (재시도 데코레이터), Token Counter (토큰 카운터), 그리고 Hardcoded URL (하드코딩된 URL)이 뒤엉킨 엉망진창이 되었습니다.

# 제가 피하고 싶었던 모습입니다:
def call_openai(prompt):
    headers = {"Authorization": f"Bearer {OPENAI_KEY}"}
...

모든 제공업체는 각자만의 Auth Scheme (인증 방식), Endpoint (엔드포인트), 그리고 Error Format (에러 형식)을 가지고 있었습니다. 저는 실제 앱 로직보다 SDK에 적응하는 데 더 많은 시간을 소비했습니다.

실제로 효과가 있었던 방법

저는 모든 것을 하나의 범용 클라이언트로 축소했습니다. 이 클라이언트는 Configuration Object (설정 객체)를 받아들이며, 재시도를 위해 Exponential Backoff (지수 백오프) + Jitter (지터)를 사용합니다. SDK 없이 오직 requests와 json만 사용합니다. 핵심 통찰은 AI API를 예측 가능한 인터페이스(보통 prompt가 포함된 JSON Body와 choices가 포함된 응답)를 가진 Black-box HTTP Endpoint (블랙박스 HTTP 엔드포인트)로 취급하는 것이었습니다.

제가 최종적으로 완성한 핵심 코드는 다음과 같습니다:

import requests
import time
import random
...

이 방식의 한계점

이 접근 방식은 단순한 텍스트 생성에는 매우 효과적이지만, 다음과 같은 한계가 있습니다:

• 스트리밍 (Streaming): 제 클라이언트는 전체 응답이 올 때까지 차단(block)됩니다. 실시간 스트리밍 (SSE)을 구현하려면 aiohttp나 전용 스트림 파서 (stream parser) 같은 것이 필요할 것입니다.
• 토큰 관리 (Token management): 토큰 사용량을 추적하거나 제한을 강제하지 않습니다. 토큰 카운터를 추가할 수는 있지만, 이는 제공자(provider)마다 추가적인 로직이 필요합니다.
• 비표준 API (Non-standard APIs): 일부 서비스 (Anthropic 또는 Cohere와 같은)는 서로 다른 응답 스키마 (response schemas)를 사용합니다. 제공자별로 파싱 (parsing) 로직을 조정해야 합니다.
• 보안 (Security): 페이로드 헤더 (payload header)에 API 키를 넣는 것도 괜찮지만, 프로덕션 (production) 환경에서는 환경 변수 (environment variables)나 비밀 관리자 (secrets manager)를 사용하십시오.

다음에 제가 다르게 할 일들

1. 환경 기반 설정 (environment-based configuration)으로 시작하기. 엔드포인트 (endpoints)를 하드코딩하지 마세요.
2. 첫날부터 구조화된 로깅 (structured logging) 추가하기. 저는 재시도 (retries)가 왜 발생하는지 추측해야만 했습니다.
3. 재시도 로직을 요청 함수 (request function)에서 분리하기. 재사용 가능한 @retry 데코레이터 (decorator)를 만들 것입니다.
4. 개발 중에 API를 모킹 (Mock)하기. 실제 네트워크 호출을 기다리느라 몇 시간을 허비했습니다.

요약 (The Takeaway)

최신 AI API와 통신하기 위해 무거운 SDK가 반드시 필요한 것은 아닙니다. 지수 백오프 (exponential backoff) 기능이 포함된 작고 설정 가능한 HTTP 클라이언트 (HTTP client)만으로도 사용 사례의 90%를 처리할 수 있습니다. 이는 디버깅이 더 쉽고, 제공자 간 이식성이 높으며, 기저에 깔린 프로토콜 (protocol)을 이해하도록 강제합니다.

이제 궁금해지네요. 여러분은 프로젝트에서 AI API의 신뢰성을 어떻게 처리하시나요? 직접 클라이언트를 만드시나요, 아니면 SDK를 고수하시나요?