프로젝트 소개

이 저장소는 Gemini나 OpenAI와 같은 특정 LLM 제공자에 대한 직접적인 의존성을 추상화하도록 설계된 제공자 중립적 FastAPI 게이트웨이를 제공합니다. 애플리케이션은 'gemini-3.5-flash' 또는 'gpt-5.6-terra'와 같은 모델 이름을 하드코딩하는 대신, 'fast', 'reasoning', 'cheap' 또는 'embedding'과 같은 안정적인 별칭을 통해 기능을 요청합니다. 게이트웨이는 제공자 선택, 지수 백오프 및 지터(jitter)를 포함한 재시도 로직, 폴백 라우팅, 타임아웃 강제 적용, 오류 정규화, 토큰 사용량 추적, 비용 추정 및 SQLite를 통한 사용 이벤트의 지속적 저장을 처리합니다. 주요 기능은 다음과 같습니다: - 순서가 지정된 폴백 체인을 통한 모델 별칭 기반 라우팅 - Gemini 및 OpenAI용 제공자 어댑터 - JSON Schema 제약 조건을 사용한 구조화된 JSON 출력 - 정규화된 메타데이터를 포함한 텍스트 임베딩 - 요청 ID 전파 및 지연 시간 헤더 - 비용 추정을 위한 구성 가능한 가격 카탈로그 - 제공자/모델별 세부 내역이 포함된 사용량 분석 엔드포인트 - 비동기 테스트, Docker 지원 및 GitHub Actions CI/CD - 운영 환경에서의 API 키 인증을 포함한 보안 제어 이 아키텍처는 애플리케이션 로직과 LLM 제공자의 복잡성 사이에 명확한 분리를 강제합니다. 요청 컨텍스트를 위한 미들웨어, 타입이 지정된 Pydantic 응답 및 상세 로깅이 포함되어 있습니다. 운영 투명성을 유지하기 위해 실패한 시도는 성공한 시도와 함께 저장됩니다. 시스템은 확장 가능하지만, 핵심 추상화와 신뢰성에 집중하기 위해 JWT 인증, 스트리밍 또는 분산 속도 제한과 같은 고급 기능은 의도적으로 제외되었습니다. 설정 과정은 저장소 복제, 가상 환경 생성, 종속성 설치, API 키를 포함한 .env 구성, 그리고 uvicorn 또는 Docker를 통한 실행으로 이루어집니다. Swagger 문서는 /docs에서 확인할 수 있습니다. 이 프로젝트는 코드 품질과 보안을 위해 Ruff, pytest, CodeQL 및 Dependabot을 사용합니다. 상세한 NOTES.md 파일에는 설계 결정 사항과 AI 엔지니어링 프로젝트를 위한 학습 목표가 설명되어 있습니다.