채팅 완료를 위한 산업 등급의 다중 제공업체 API 래퍼.
- 개요 (Overview)
- 기능 (Features)
- 아키텍처 및 디렉토리 구조 (Architecture & Directory Structure)
- 설치 (Installation)
- 구성 (Configuration)
- 애플리케이션 실행 (Running the Application)
- API 엔드포인트 (API Endpoints)
- 테스트 (Testing)
- 데이터베이스 관리 (Database Management)
- 기여 (Contributing)
- 라이선스 (License)
- 연락처 (Contact)
AI4Free API Wrapper는 여러 대규모 언어 모델(LLM) 제공업체에 대한 통합 인터페이스를 제공하도록 설계된 강력하고 프로덕션 준비가 된 API 래퍼입니다. 이 래퍼는 스트리밍 및 비스트리밍 채팅 완료를 모두 지원하며, API 키 관리, 속도 제한 (rate limiting), 상세 사용량 추적, 포괄적인 테스트 스위트와 같은 내장 기능을 포함합니다.
SreejanPersonal이 유지하는 이 저장소는 단일하고 일관된 API를 통해 다양한 LLM과의 원활한 통합이 필요한 애플리케이션을 위한 백엔드 서비스 역할을 합니다. 이는 REST API를 위해 Flask를, 데이터베이스 관리를 위해 PostgreSQL과 SQLAlchemy를, 그리고 속도 제한을 위해 Redis를 활용하여 확장성과 신뢰성을 보장합니다.
다중 제공업체 지원 (Multi-Provider Support): DeepSeek-R1, gpt-4o, o3-mini, DeepSeekV3 등 다양한 LLM 제공업체 간에 원활하게 전환할 수 있습니다. 제공업체 통합은 app/providers 디렉토리에 구현되어 있으며, 각 제공업체는 전용 모듈(예: provider_1.py, provider_2.py)을 가집니다. 동일한 디렉토리의 provider_manager.py가 구성에 따라 제공업체 선택을 조정합니다.
통합 API 인터페이스 (Unified API Interface): OpenAI와 호환되는 API 표준을 준수하여 다양한 제공업체 전반에서 일관된 요청 및 응답 스키마를 누릴 수 있습니다. API 경로는 app/api/routes.py에 정의되어 있으며, 요청/응답 스키마는 app/api/schemas.py에서 정의된 Marshmallow를 사용하여 검증됩니다.
스트리밍 및 비스트리밍 (Streaming & Non-Streaming): Server-Sent Events (SSE)를 사용한 스트리밍 응답과 표준 비스트리밍 완료를 모두 지원합니다. 스트리밍 로직은 app/utils/streaming.py에서 처리되며, API 엔드포인트는 app/api/controllers.py에 있습니다.
클라이언트 요청 헤더를 기반으로 응답 형식을 관리합니다.**강력한 속도 제한(Rate Limiting):**Redis와 Lua 스크립팅을 사용하여 구성 가능한 속도 제한 기능을 통해 서비스를 보호할 수 있습니다. app/services/rate_limit_service.py에 위치한 이 속도 제한 서비스는 효율적인 카운터 관리를 위해 Redis를 사용하고, 원자적(atomic) 작업을 위해 Lua 스크립트를 사용하여 높은 성능을 보장하고 경쟁 조건(race conditions)을 방지합니다.**API 키 관리:**API 키를 안전하게 생성, 검증 및 관리합니다. API 키 생성 및 유효성 검사 로직은 app/services/api_key_service.py에 구현되어 있습니다. API 키는 app/models/api_key.py에서 정의된 SQLAlchemy 모델을 사용하여 데이터베이스에 저장됩니다.**토큰 사용량 및 비용 추적:**프롬프트 토큰, 완료 토큰 및 관련 비용에 대한 상세한 추적이 가능합니다. 사용량 추적은 app/services/usage_service.py에 구현되어 있으며, 사용량 데이터는 app/models/usage.py에서 정의된 SQLAlchemy 모델을 사용하여 저장됩니다. 토큰 계산 유틸리티는 app/utils/token_counter.py에서 사용할 수 있습니다.**Flask 기반 REST API:**마이크로 웹 프레임워크인 Flask를 기반으로 하며, 교차 출처 요청(cross-origin requests)을 위해 CORS가 활성화되어 있습니다. Flask 애플리케이션은 app/__init__.py에서 초기화되며, CORS는 Flask-CORS 확장 기능을 사용하여 구성됩니다.**PostgreSQL 및 SQLAlchemy 통합:**PostgreSQL과 SQLAlchemy를 사용한 신뢰할 수 있는 데이터 영속성(data persistence) 및 ORM 지원을 제공합니다. 데이터베이스 연결 및 SQLAlchemy 설정은 app/extensions.py와 app/config.py에 구성되어 있습니다. 데이터베이스 모델은 app/models 디렉터리에 정의되어 있습니다.**포괄적인 테스트 스위트:**API 엔드포인트, 공급업체 통합(provider integrations), 사용량 측정 지표에 대한 종단 간(end-to-end) 테스트 스크립트는 Testing 디렉터리에 위치합니다. 테스트는 Python의 unittest 프레임워크와 requests 라이브러리를 사용하여 API 호출을 시뮬레이션하여 작성되었습니다.**운영 환경 준비 완료 구성:**빠른 비동기 처리 및 최적의 CPU 리소스 활용을 위해 Gunicorn과 gevent를 사용합니다. Gunicorn 설정은 gunicorn.config.py에 있으며, 비동기 워커(asynchronous workers)로 최적화되어 운영 배포에 적합합니다.
저장소는 애플리케이션 팩토리 패턴(application factory pattern)을 사용하여 업계 모범 사례에 따라 구성되었습니다. 주요 디렉터리는 다음과 같습니다:
app/
app/__init__.py에서 초기화되는 핵심 Flask 애플리케이션이 포함됩니다. 여기에는 app/config.py의 설정 파일, app/extensions.py의 Flask 확장 프로그램 설정, app/api/routes.py에 정의된 API 라우트, app/api/controllers.py의 컨트롤러, app/services/의 서비스, 그리고 app/models/의 데이터베이스 모델이 포함됩니다.providers/
별칭 기반 매핑(alias-based mapping)을 통해 여러 LLM 제공업체를 통합하여 유연성을 보장합니다. 각 제공업체는 app/providers/ 내에 자체 구현 모듈(예: provider_1.py, provider_2.py 등)을 가집니다. 이 디렉터리의 provider_manager.py가 제공업체 선택 및 관리를 담당합니다.services/
API 키 관리(app/services/api_key_service.py), 속도 제한(rate limiting, app/services/rate_limit_service.py), 사용량 기록(app/services/usage_service.py)과 같은 비즈니스 로직을 구현합니다.utils/
데이터베이스 컨텍스트 관리(app/utils/db_utils.py), 토큰 계산(app/utils/token_counter.py), 스트리밍 처리(app/utils/streaming.py), 그리고 헬퍼 메서드(app/utils/helpers.py)를 위한 유틸리티 함수를 포함합니다.data/
제공업체별 및 버전이 지정된 모델 메타데이터를 포함하는 models.json과 같은 중앙 집중식 데이터 파일을 포함합니다.Testing/
API 엔드포인트를 검증하기 위한 테스트 스크립트와 클라이언트 세트입니다. 포괄적인 API 유효성 검사를 위해 API_Endpoint_Testing.py, OpenAI_Client_Testing.py, 그리고 test_api_usage.py를 포함합니다.- 추가 파일:
db_manager.py: 데이터베이스 관리를 위한 CLI 도구(생성, 초기화 등).
run.py: 개발 모드에서 Flask 애플리케이션을 실행하는 스크립트.
gunicorn.config.py: 프로덕션 배포를 위한 Gunicorn 설정 파일.
requirements.txt: Python 의존성 목록.
PostgreSQL: PostgreSQL 데이터베이스를 설치하고 구성합니다. 운영체제별 설치 지침은 PostgreSQL 문서를 참조하십시오.Redis: Redis 서버를 설치하고 구성합니다. 시스템에 맞는 Redis 설치 가이드를 따르십시오.
git clone https://github.com/SreejanPersonal/ai4free-wrapper.git
cd ai4free-wrapper
Using venv
(프로젝트 종속성을 격리하는 데 권장됨):
python -m venv venv
source venv/bin/activate # Windows의 경우: venv\Scripts\activate
Install required Python packages from requirements.txt
:
pip install -r requirements.txt
Environment Variables:
프로젝트 루트에 .env 파일을 생성합니다. 모든 환경 변수의 템플릿과 설명을 보려면 .env.example을 참조하십시오. 주요 구성 항목은 다음과 같습니다:
Provider Base URLs & API Keys:
사용하려는 각 LLM 제공업체에 대한 API 엔드포인트와 키를 설정합니다. 이 변수들은 일반적으로 제공업체 별칭(예: PROVIDER_1_API_KEY, PROVIDER_2_BASE_URL)으로 접두사가 붙습니다.
Local API URL:
LOCAL_API_URL=http://127.0.0.1:5000
(로컬 개발의 기본값)
Database Settings:
DATABASE_URL과 같은 변수를 사용하여 PostgreSQL 연결 세부 정보를 구성합니다. 데이터베이스가 실행 중이고 접근 가능한지 확인하십시오.Redis Settings:
일반적으로 REDIS_URL을 사용하여 Redis 연결 세부 정보를 구성합니다. Redis 서버가 실행 중인지 확인하십시오.Flask Settings:
세션 관리 및 CSRF 보호를 위해 FLASK_SECRET_KEY를 설정합니다. 개발 중 디버그 모드를 사용하려면 FLASK_DEBUG=1로 토글하고(운영 환경에서는 0으로 설정), 시스템 비밀을 설정해야 합니다.
System Secret:
SYSTEM_SECRET 환경 변수는 안전한 API 키 생성 및 관리에 매우 중요합니다. 이 비밀은 강력하게 무작위로 생성된 문자열이어야 합니다.
Model Configuration:
모델과 제공업체 매핑은 data/models.json에 정의되어 있습니다. 이 JSON 파일은 사용 가능한 모델, 해당 제공업체 및 구성을 명시합니다. app/config.py는 모델 구성 및 매핑을 추가로 다듬고 models.json에서 데이터를 로드합니다.
환경 변수와 함께입니다.
Flask 개발 서버를 시작합니다. 이는 로컬 개발 및 테스트에 적합합니다.
python run.py
API는 http://127.0.0.1:5000에서 접근 가능합니다. Flask의 디버그 모드(FLASK_DEBUG=1을 통해 활성화된 경우)는 핫 리로딩과 상세한 오류 메시지를 제공합니다.
운영 환경 배포를 위해서는 제공된 설정으로 Python WSGI HTTP 서버인 Gunicorn을 사용하십시오. Gunicorn은 최적의 성능을 위해 gunicorn.config.py에서 구성됩니다.
gunicorn -c gunicorn.config.py run:app
이 명령어는 gunicorn.config.py에 정의된 설정으로 Gunicorn을 시작하며, run:app을 사용하여 Flask 애플리케이션 인스턴스를 지정합니다. Gunicorn은 비동기 요청 처리를 위해 gevent 워커를 사용하도록 구성되어 CPU 활용률과 처리량(throughput)을 극대화합니다.
이 API는 OpenAI와 호환되도록 설계되었으며, 기존의 OpenAI 클라이언트 및 도구와 쉽게 통합할 수 있습니다. 주요 엔드포인트는 다음과 같습니다:
-
Health Check
GET /health
서비스가 실행 중임을 나타내는 간단한 JSON {"status": "ok"} 을 반환합니다. 모니터링 및 상태 확인에 유용합니다.
-
Chat Completions
POST /v1/chat/completions
스트리밍 및 비스트리밍 채팅 완료를 모두 처리합니다. Bearer 토큰으로 Authorization 헤더에 유효한 API 키가 필요합니다. 요청 본문은 OpenAI 채팅 완료 API 형식을 따라야 합니다. 요청 처리 및 응답 형식 지정은 app/api/controllers.py 를 참조하십시오.
-
List Models
GET/POST /v1/models
data/models.json과 app/config.py 에 정의된 사용 가능한 모델 목록 및 해당 구성을 JSON 형식으로 반환합니다. 클라이언트가 사용 가능한 모델을 검색하는 데 유용합니다. 구현 세부 사항은 app/api/controllers.py 를 참조하십시오.
-
API Key Generation
POST /v1/api-keys
새로운 API 키를 생성합니다. 보안을 위해 X-System-Secret 헤더를 통해 시스템 시크릿 검증이 필요합니다. API 키 생성 로직은 app/api/controllers.py 와 app/services/api_key_service.py 를 참조하십시오.
-
Usage Details
POST /v1/usage
*주어진 API 키에 대한 사용 상세 정보를 반환합니다. 요청 시 Authorization 헤더에 API 키가 필요합니다. 토큰 카운트, 요청 통계 및 비용 지표를 반환합니다. 사용 데이터 검색은 app/api/controllers.py와 app/services/usage_service.py를 참조하십시오.
Uptime 확인****GET/v1/uptime/<model_id>
*특정 모델이 작동하며 응답하는지 검증하기 위해 최소한의 스트리밍 확인을 수행합니다. 지정된 모델로 경량 스트리밍 요청을 시작합니다. Uptime 확인 구현은 app/api/controllers.py를 참조하십시오.
참고: 요청 시에는 app/api/schemas.py에 명시된 코드 주석 및 스키마 검증에 따라 적절한 JSON 페이로드와 헤더를 포함해야 합니다. 대부분의 엔드포인트에서는 Authorization 헤더의 Bearer 토큰을 사용하여 API 키 인증이 강제됩니다.
종합적인 테스트 스크립트 세트는 Testing/ 디렉토리에 위치합니다. 이 스크립트들은 Python의 unittest 프레임워크와 requests 라이브러리를 사용하여 API 기능을 검증합니다.
채팅 완료 테스트:API_Endpoint_Testing.py
: 스트리밍 및 비스트리밍 모드를 포함하여 채팅 완료를 위한 API 엔드포인트를 테스트합니다.OpenAI_Client_Testing.py
: API 호환성을 테스트하기 위해 OpenAI 클라이언트 상호 작용을 시뮬레이션합니다.- 다음 명령어를 사용하여 테스트 실행:
python Testing/API_Endpoint_Testing.py python Testing/OpenAI_Client_Testing.py
API 사용량 테스트:test_api_usage.py
: API 사용 추적 및 보고 엔드포인트를 테스트합니다.- 다음 명령어를 사용하여 테스트 실행:
python Testing/test_api_usage.py
이러한 테스트들은 제공업체 통합, 스트리밍 동작, 비스트리밍 동작, 속도 제한(rate limiting), 그리고 API 키 인증을 검증합니다. 자세한 테스트 케이스 및 설정은 Testing/에서 테스트 스크립트를 검토하십시오.
db_manager.py 스크립트는 PostgreSQL 데이터베이스를 관리하기 위한 CLI 도구를 제공합니다. 이 스크립트는 데이터베이스 상호 작용을 위해 SQLAlchemy를, 구성 설정을 위해 Flask의 애플리케이션 컨텍스트(application context)를 사용합니다.
**데이터베이스 및 테이블 생성:**python db_manager.py create-db
*app/models/에 정의된 대로 PostgreSQL 데이터베이스와 SQLAlchemy 테이블을 생성합니다.
• Clean (Drop) Database Tables: python db_manager.py clean-db<br><small>데이터베이스의 모든 테이블을 삭제합니다. 깨끗한 스키마로 시작할 때 유용합니다.</small>-<br>Reset Database (Drop & Recreate Tables): python db_manager.py reset-db<br><small>모든 데이터베이스 테이블을 삭제하고 재생성합니다. 데이터베이스 스키마와 데이터를 효과적으로 초기화합니다.</small>-<br>List All Tables: python db_manager.py list-tables<br><small>연결된 PostgreSQL 데이터베이스의 모든 테이블 목록을 보여줍니다. 데이터베이스 스키마를 확인하는 데 유용합니다.</small><br>경고: db_manager.py의 데이터베이스 관리 명령어