OpenAI와 Google LLM API의 일관성 없는 설계와 개발자 부담

핵심 요약

OpenAI와 Google의 LLM API가 내부 조직 구조를 반영하듯 일관성 없는 엔드포인트와 스키마 형식을 제공하여 개발자들에게 불필요한 분석 부담을 주고 있다.

배경

OpenAI의 chat/completions와 신규 responses 엔드포인트 간의 미묘한 스키마 차이와 Google Gemini API의 스키마 처리 오류를 발견하고 이러한 API 설계의 불일치가 개발자에게 전가되는 문제를 지적하기 위해 작성됐다.

의미 / 영향

현재 LLM API 시장은 표준화보다 기능 경쟁에 치우쳐 있어 개발자가 각 플랫폼의 고유한 예외 상황을 직접 관리해야 한다. 향후 안정적인 프로덕션 환경 구축을 위해서는 API 추상화 계층을 두어 이러한 플랫폼별 기벽을 격리하는 설계가 권장된다.

커뮤니티 반응

많은 개발자가 유사한 경험을 공유하며 공감하고 있으며 특히 대형 AI 기업들의 API 설계 미숙함과 문서화 부실에 대해 비판적인 시각이 지배적이다.

주요 논점

01중립소수

빠르게 변화하는 조직에서 기능 출시 속도를 맞추다 보면 발생하는 불가피한 현상이다.

02반대다수

API 설계의 불일치는 단순한 실수가 아니라 개발자 경험을 저해하는 심각한 기술 부채이며 조직적 문제이다.

합의점 vs 논쟁점

합의점

현재 주요 LLM API들의 문서화 수준이 실제 구현 속도를 따라가지 못하고 있다.
API 엔드포인트 간의 미묘한 차이가 개발 및 유지보수 비용을 증가시킨다.

논쟁점

이러한 API 설계의 차이가 의도적인 벤더 록인(Lock-in) 전략인지 아니면 단순한 조직적 관리 미흡인지에 대한 의견이 갈린다.

실용적 조언

OpenAI API 사용 시 문서에만 의존하지 말고 공식 Python SDK의 소스 코드를 참고하여 실제 데이터 구조를 확인하라.
Gemini API 사용 시 복잡한 JSON 스키마가 거부될 경우 최신 SDK 업데이트를 확인하거나 수동 스키마 변환을 고려하라.

전문가 의견

콘웨이의 법칙에 따라 조직의 소통 구조가 API 엔드포인트의 파편화로 나타나고 있다.
빠른 기능 출시(Fast-moving)가 API의 일관성보다 우선시되면서 개발자 경험(DX)이 저해되고 있다.

언급된 도구

OpenAI API중립링크

텍스트 생성 및 구조화된 데이터 출력 서비스 제공

Gemini API중립링크

Google의 멀티모달 LLM 서비스 제공

섹션별 상세

OpenAI의 엔드포인트 중복과 스키마 불일치가 확인됐다. chat/completions와 responses 엔드포인트는 텍스트 생성과 도구 호출 등 유사한 기능을 수행하지만 구조화된 출력(Structured Outputs)을 위한 JSON 스키마 정의 방식이 미묘하게 다르다. 작성자는 이러한 차이가 기술적 이유보다는 조직 내 소통 구조를 반영하는 콘웨이의 법칙(Conway's Law)의 결과물일 수 있다고 의심한다.

공식 문서의 부실함으로 인해 소스 코드 분석이 강제되는 상황이다. OpenAI의 공식 문서는 엔드포인트 간의 차이를 명확히 설명하지 않으며 제공된 예제 중 일부는 오류를 포함하고 있다. 개발자는 정확한 구현 방식을 파악하기 위해 문서를 넘어 Python 패키지의 소스 코드를 직접 읽어야 하는 부담을 안게 된다.

Google Gemini API에서도 스키마 검증 문제와 SDK의 임시방편적 해결책이 발견됐다. Gemini API는 표준 JSON 스키마인 array 형식을 특정 상황에서 거부하는 결함이 존재한다. 이를 해결하기 위해 Google의 공식 Python 패키지 팀은 백엔드 수정 대신 클라이언트 측에서 스키마를 강제로 재작성하여 전송하는 방식을 택하고 있으며 이는 조직 내 부서 간의 불협화음을 시사한다.

빠른 기능 출시 경쟁이 개발자에게 비용을 전가하고 있다. AI 기업들이 경쟁적으로 기능을 출시하면서 API의 일관성과 품질 관리가 뒷전으로 밀리는 경향이 나타난다. 이러한 작은 기벽(quirks)들은 결국 이를 사용하는 개발자들이 일일이 대응하고 디버깅해야 하는 운영 비용과 심리적 부담으로 이어진다.

실무 Takeaway

OpenAI의 서로 다른 엔드포인트 간 JSON 스키마 형식이 일관되지 않아 마이그레이션과 통합에 혼선을 준다.
공식 문서의 예제 오류나 설명 부족으로 인해 개발자가 라이브러리 소스 코드를 직접 분석해야 하는 경우가 발생한다.
Google Gemini API의 경우 백엔드의 스키마 검증 오류를 클라이언트 SDK에서 임시로 수정해 처리하는 등 내부적인 기술 부채가 관찰된다.
빠른 혁신 속도 속에서 API 설계의 일관성 결여는 고스란히 외부 개발자의 구현 부담으로 전이된다.