Qoder OpenAI Proxy

built-in 대시보드, 메트릭 및 Docker 지원을 갖춘 qodercli용 OpenAI 호환 API 래퍼입니다.
OpenAI의 API를 위해 설계된 모든 도구나 라이브러리를 통해 Qoder를 사용하세요.

기능 (Features)

• ✅ 🔌 OpenAI 호환: LangChain 및 Open WebUI와 같은 앱을 위한 드롭인(Drop-in) API 대체품
• 💬 전체 채팅 지원: /v1/chat/completions 지원 (시스템 메시지, 다중 턴 기록)
• 🛠 OpenAI Tool Calling: 호환되는 OpenAI API 클라이언트 및 라이브러리를 위한 사용자 정의 도구 정의를 갖춘 OpenAI 스타일 함수 호출 지원
• ⚡ 스트리밍 (Streaming): 지연 없이 실시간 SSE(Server-Sent Events) 응답 스트리밍
• 🔄 스마트 모델 매핑 (Smart Model Mapping): 모든 AI 모델 이름(gpt-4, claude-3.5, 사용자 정의 이름)을 수용하며, 알려지지 않은 모델이 발생해도 충돌하지 않고 우아하게 처리하는 지능형 휴리스틱 폴백(heuristic fallback) 제공
• 📊 관리자 대시보드 (Admin Dashboard): 테스트, 실시간 로그 보기 및 프록시 상태 모니터링을 위한 내장 다크 테마 웹 대시보드
• 🐳 Docker 네이티브: 공개 GHCR 이미지를 통해 클라우드 서비스에 쉽게 배포할 수 있도록 설계된 제로 영속성(Zero-persistence) RAM 전용 아키텍처

🚀 빠른 시작 (Quick Start) (Docker / 클라우드 배포)

이 프록시는 컨테이너화되어 있으며 GitHub Container Registry에서 사용할 수 있습니다. 볼륨이나 영구 스토리지가 필요 없는 완전히 무상태(stateless)로 실행됩니다. 모든 설정은 환경 변수를 통해 이루어집니다.

Docker Run을 통한 배포

TCP를 통해 포트 3000을 노출합니다. 다음 환경 변수를 사용하여 개인 토큰을 안전하게 구성하세요:

docker run -d \
  --name qoder-proxy \
  -p 3000:3000 \
...

환경 변수 (Environment Variables)

• 공개 인터넷에서 실행할 때 강력히 권장됩니다.*

⚠️ 리소스 요구 사항 (Resource Requirements) (알려진 qodercli 스파이크 동작)

이 프록시는 요청당 qodercli를 생성합니다. 활성 생성이 진행되는 동안 CPU와 RAM은 급격히 치솟을 수 있으며, 응답 완료 후에는 다시 낮아집니다. 이는 현재 래퍼(wrapper) 설계에서 예상되는 동작입니다.

일반적으로 관찰되는 패턴:

• 생성 중 CPU 스파이크 (단시간 버스트는 멀티코어 호스트에서 100%를 초과할 수 있음)
• 생성 중 RAM 스파이크 (더 무거운 프롬프트/출력의 경우 약 1 GB에 근접할 수 있음)
• 완료 후 메모리는 기준선 근처로 떨어짐

권장 최소 사양:

리테일 PC (로컬/셀프 호스팅)

• CPU: 물리 코어 4개 권장 (가벼운 테스트를 위한 최소 2 코어)
• RAM: 시스템 RAM 8 GB 권장 (가벼운 테스트를 위한 최소 4 GB)

클라우드 VM / 컨테이너 호스트

• 최소 사양: vCPU 2개 + RAM 2 GB
• 권장 사양: vCPU 4개 + RAM 4 GB
• 동시 트래픽의 경우, 지연 시간 스파이크나 프로세스 종료를 방지하기 위해 대략 vCPU당 활성 요청 1~2개를 계획하세요.

실용적인 안정화 팁:

• 더 큰 출력이 특별히 필요하지 않은 한 QODER_MAX_OUTPUT_TOKENS=16k를 유지하세요.
• 소규모 인스턴스에서 높은 동시성을 피하세요.
• 플랫폼이 엄격한 메모리 제한을 강제하는 경우, SIGKILL 위험을 줄이기 위해 컨테이너 메모리를 늘리세요.

🌐 관리자 대시보드 (The Admin Dashboard)

내장 웹 대시보드는 프록시가 무엇을 하고 있는지 전체적인 가시성을 제공합니다. http://your-server-ip:3000/dashboard/에서 접속할 수 있습니다.

1. 엔드포인트(Endpoints): 도구 통합을 위한 복사 붙여넣기 스니펫을 빠르게 얻을 수 있습니다.
2. 플레이그라운드(Playground): 브라우저에서 API를 실시간으로 테스트하고 사용 가능한 모델 간에 전환할 수 있습니다.
3. 요청 로그(Request Logs): 들어오는 요청, 요청 페이로드, 지속 시간, HTTP 상태, 그리고 조립된 응답 텍스트를 검사합니다.
4. 시스템 로그(System Logs): qodercli에서 발생하는 백그라운드 시스템 오류를 볼 수 있습니다.

참고: 모든 로그는 RAM에 안전하게 저장되며 Docker 컨테이너가 재시작될 때마다 완전히 지워집니다.

🤖 스마트 모델 이름 매핑 (Smart Model Name Mapping)

이 프록시는 다단계 해상도 전략을 사용하여 모델 이름을 Qoder CLI 티어에 지능적으로 매핑합니다:

1. 정확히 일치하는 경우 (Exact match): Qoder의 티어 이름(auto, lite, ultimate)은 변경 없이 그대로 사용됩니다.
2. 알려진 별칭 (Known aliases): gpt-4, claude-3.5-sonnet과 같은 일반적인 이름은 특정 티어로 매핑됩니다.
3. 휴리스틱 매칭 (Heuristic matching): 알 수 없는 모델 이름은 분석됩니다(예: claude-sonnet-4-5 → auto).
4. 우아한 폴백 (Graceful fallback): 인식되지 않은 이름은 로깅과 함께 기본적으로 lite 티어로 설정됩니다.

모든 응답은 Qoder의 모델에서 나옵니다. - 이 매핑은 기존 OpenAI 호환 도구와 통합하기 쉽게 만들기 위함입니다.

참고: 사용자는 OpenAI나 Anthropic이 아닌 Qoder의 AI 모델로부터 응답을 받게 됩니다. 이름 매핑은 표준 모델 이름을 기대하는 도구와의 호환성을 위한 것일 뿐입니다.

🛠 사용 예시 (Usage Examples)

배포 후, 호스트 URL(예: http://localhost:3000/v1 또는 https://my-proxy.com/v1)을 복사하여 OpenAI 스타일의 엔드포인트를 사용하는 모든 앱에 붙여넣고, API 키는 정의한 PROXY_API_KEY로 설정합니다.

Python (OpenAI SDK)

from openai import OpenAI

client = OpenAI(
...

직접 HTTP 호출 (cURL)

curl http://localhost:3000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-custom-key" \
...

🛠 OpenAI 호환 도구 호출 (OpenAI-Compatible Tool Calling)

프록시는 이제 사용자 정의 도구 정의와 함께 **완벽한 OpenAI 스타일의 함수 호출(function calling)**을 지원합니다. 요청에 도구를 정의하면 AI가 언제 호출할지 지능적으로 결정하고, 응답에 구조화된 tool_calls를 반환합니다.

사용자 정의 도구 정의 (Defining Custom Tools)

from openai import OpenAI

client = OpenAI(
...

도구 호출 응답 형식 (Tool Call Response Format)

AI가 도구를 사용하기로 결정하면 다음을 받게 됩니다:

{
  "choices": [{
    "message": {
...

작동 방식 (How It Works)

프록시는 사용자의 OpenAI 도구 정의를 Qoder의 AI가 이해할 수 있는 자연어 지침으로 변환한 다음, 모델의 응답을 다시 OpenAI의 tool_calls 형식으로 구문 분석합니다. 이 기능은 다음과 함께 작동합니다:

• ✅ LangChain - 에이전트 도구 체인(Agent tool chains)
• ✅ 모든 OpenAI SDK - 표준 함수 호출(Standard function calling)
• ⚠️ Cursor IDE / Continue.dev / Zed - 알려진 제한 사항은 아래를 참조하세요.

스트리밍 모드와 비(非)스트리밍 모드가 모두 완벽하게 지원됩니다!

⚠️ 제한 사항 (Limitations)

• 임베딩 (Embeddings): Qoder는 임베딩을 지원하지 않습니다. /v1/embeddings를 호출하면 501 Not Implemented가 반환됩니다.
• 토큰 사용량 (Token usage): 토큰 계산은 사용할 수 없습니다—응답의 usage 필드는 null을 반환합니다.
• 도구 실행 (Tool execution): 프록시는 OpenAI 형식으로 도구 호출 요청을 반환하지만, 자동으로 실행하지는 않습니다. 애플리케이션에서 도구 실행을 처리하고 결과를 다시 전송해야 합니다 (표준 OpenAI 도구 호출 흐름).

❌ 알려진 제한 사항 — 코딩 IDE 미지원

다음 도구들은 테스트되었으나 현재 이 프록시와 호환되지 않습니다:

✅ 검증된 호환성 (Verified Compatible)

프록시는 다음 항목들과 함께 테스트되었으며 작동합니다:

• ✅ OpenAI Python SDK - 모든 표준 기능
• ✅ LangChain - 에이전트 체인 및 도구 호출
• ✅ Open WebUI - 채팅 인터페이스 통합
• ❌ Cursor IDE - 작동 안 함 (위의 알려진 제한 사항 참조)
• ❌ Zed Editor - 작동 안 함 (위의 알려진 제한 사항 참조)
• ❌ Continue.dev - 작동 안 함 (위의 알려진 제한 사항 참조)

라이선스 (License)

MIT