FreeLLMAPI

FreeLLMAPI란?

FreeLLMAPI는 여러 LLM 제공자의 무료 티어 액세스를 단일 API 엔드포인트 뒤로 통합하는 OpenAI 호환 프록시 서버입니다. 각 제공자별로 별도 SDK를 설정하거나 다른 속도 제한을 처리하는 대신, OpenAI 호환 클라이언트를 프록시에 연결하고 하나의 엔드포인트로 요청을 보냅니다.

이 프로젝트는 개인 실험용으로 설계되었습니다. ~14개 제공자의 키를 집계(제공자 어댑터経由)하고, 각 요청을 사용 가능한 모델로 라우팅하며, 제공자가 속도 제한되거나 오류 발생 시 자동 failover를 수행합니다.

주요 기능

• OpenAI 호환 엔드포인트: POST /v1/chat/completions와 GET /v1/models를 구현하여 OpenAI SDK 및 기타 OpenAI 호환 클라이언트가 base_url만 변경하면 작동합니다.
• 스트리밍 지원: stream: true일 때 서버가 **Server-Sent Events (SSE)**로 응답을 반환; 그렇지 않으면 표준 JSON 응답을 반환합니다.
• 도구 호출 패스스루: OpenAI 스타일 tools / tool_choice 요청을 지원하고, 어시스턴트 tool_calls와 후속 tool 역할 메시지를 제공자 어댑터로 전달합니다.
• 자동 failover 및 재시도: 선택된 제공자가 429, 5xx를 반환하거나 타임아웃 시, 라우터가 해당 키를 일시적으로 사용할 수 없음으로 표시하고 대체 체인의 다음 제공자로 최대 20회 재시도합니다.
• 키별 사용량 추적(제공자 한도 대비): (platform, model, key)별 RPM, RPD, TPM, TPD를 추적하고 무료 티어 한도 미만 키를 선택합니다.
• 스티키 멀티턴 라우팅: 대화 중 모델 스위치를 줄이기 위해 30분 동안 동일 모델 유지.
• 암호화 키 저장: 상위 제공자 키를 AES-256-GCM으로 암호화한 후 SQLite에 저장; 사용 직전 메모리 내 복호화.
• 통합 프록시 인증: 클라이언트가 상위 제공자 키 대신 단일 freellmapi-... 베어러 토큰으로 프록시에 인증.
• 헬스 체크 및 관리 제어: 주기적 프로브로 키를 healthy/속도 제한/유효하지 않음/오류로 라벨링; 포함된 관리 대시보드(React + Vite)로 키 관리, 대체 우선순위 재정렬, 분석 검사, 프롬프트 플레이그라운드 실행.

FreeLLMAPI 사용 방법

1. 필수 요구사항 설치: **Node.js 20+**와 npm 사용.
2. 클론 및 설치:
   • git clone https://github.com/tashfeenahmed/freellmapi.git
   • cd freellmapi
   • npm install
3. 환경 설정:
   • 예제 env 복사: cp .env.example .env
   • .env에 ENCRYPTION_KEY 생성하여 입력(리포지토리가 랜덤 32바이트 hex 키 출력 명령 제공).
4. 프록시 시작: 리포지토리 빠른 시작 / README에 설명된 대로 서버 실행(페이지 콘텐츠 발췌에 설정 단계 포함, 리포지토리 문서에 정확한 시작 명령).
5. OpenAI 호환 클라이언트 설정:
   • 클라이언트 base_url을 로컬 FreeLLMAPI 서버로 설정.
   • 프록시 베어러 토큰(freellmapi-...)으로 인증하고 POST /v1/chat/completions 호출(stream: true 옵션).

사용 사례

• 하나의 코드베이스에서 제공자 간 채팅 테스트: 기존 OpenAI 호환 앱(또는 라이브러리)을 프록시에 연결해 별도 제공자 SDK 관리 없이 여러 모델 실험.
• 수동 속도 제한 실패 감소: 429/5xx/타임아웃 응답 제공자를 자동 failover로 건너뛰고 설정된 대체 순서의 다음 모델로 요청 계속.
• 도구 사용 채팅 흐름: tool_calls와 도구 결과 메시지가 동일한 프록시 흐름으로 라우팅되는 OpenAI 스타일 도구 호출 요청 실행.
• 장기 대화 일관성: 활성 사용 중 동일 모델 유지(30분 스티키 세션)하면서 제공자 미사용 시 대체 혜택.
• 암호화 키 처리 로컬 실험: 클라이언트 앱이 제공자 키 노출하지 않도록 프록시 내 상위 키 중앙화 및 저장 시 암호화.

자주 묻는 질문

• FreeLLMAPI가 전체 OpenAI API를 지원하나요? 아니요. 채팅 완성 및 모델 목록(/v1/chat/completions, /v1/models)에 초점. 임베딩, 이미지, 오디오/음성, 멀티모달 입력은 지원하지 않으며, 레거시 /v1/completions, moderation, 요청당 다중 완성도 미지원.

• FreeLLMAPI가 속도 제한을 어떻게 처리하나요? 키별 사용량 카운터(RPM/RPD/TPM/TPD)를 추적하고 한도 미만 키 선택. 제공자가 여전히 429(또는 5xx/타임아웃) 반환 시 대체 체인의 다음 제공자로 재시도.

• 내 클라이언트에서 스트리밍이 작동하나요? 네. 채팅 엔드포인트에서 stream: true 시 SSE를 통한 스트리밍 지원.

• 기존 OpenAI 호환 라이브러리를 사용할 수 있나요? 공식 OpenAI SDK 및 기타 OpenAI 호환 클라이언트를 프록시 base_url로 가리키면 작동하도록 의도.

• 프로덕션 사용을 위한 건가요? 리포지토리가 “개인 실험 전용”이라고 명시.

대안

• 단일 제공자를 직접 사용: 많은 서비스가 일관된 의미론의 자체 API를 제공하지만, 다중 제공자 집계, 자동 페일오버, 단일 엔드포인트에서의 무료 티어 스태킹을 얻을 수 없습니다.
• 자체 라우터/페일백 레이어 구축: 커스텀 프록시는 페일오버와 키 로테이션을 구현할 수 있지만, 제공자별 SDK, 제한, 오류 처리를 직접 관리해야 합니다.
• 다중 LLM 백엔드를 지원하는 오케스트레이션 프레임워크 사용: 일부 도구는 요청을 다른 모델 제공자로 라우팅하지만, 워크플로가 다를 수 있으며(여기 설명된 동일한 OpenAI 호환 /v1/chat/completions 프록시 동작을 제공하지 않을 수 있음), 차이가 있을 수 있습니다.
• 수동 키 및 모델 전환: 애플리케이션에서 제공자를 수동으로 선택할 수 있지만, FreeLLMAPI가 제공하는 자동 재시도/페일오버와 키별 사용량 추적을 잃게 됩니다.