lumingya/universal-web-api

Universal Web API – AI 웹 UI를 OpenAI/Anthropic 호환 로컬 API로 연결

개요

• 로컬에서 실행되는 서비스로, Chromium 브라우저를 제어하여 AI 채팅 사이트(ChatGPT, Gemini, Claude 등)에 로그인하고 웹 UI를 표준 OpenAI 호환(/v1/chat/completions, /v1/models) 및 Anthropic 호환(/v1/messages) 엔드포인트로 다시 노출합니다.
• 디버그/브리지 계층 역할: 자체 클라이언트는 익숙한 OpenAI/Anthropic HTTP API를 호출하고, 서비스는 요청을 실제 웹 페이지로 전달하고 DOM 또는 네트워크 트래픽을 파싱하여 JSON 또는 Server-Sent Events를 반환합니다.

주요 기능

• OpenAI 및 Anthropic 호환성 – 채팅 완성, 모델 목록, 토큰 수, 스트리밍 SSE, 도구 호출, 멀티모달 입력, 실험적 /v1/responses 지원.
• 다중 사이트 지원 – ChatGPT, DeepSeek, Gemini, Claude, Kimi, Qwen, Grok, Doubao, AI Studio, Arena AI에 사전 구성되어 있으며, DOM 규칙 생성을 통해 새 사이트를 추가하는 UI 제공.
• 라우팅 유연성 – 자동 모델 기반 라우팅, 명시적 사이트 기반 URL, 탭 인덱스 라우팅, URL 토큰 라우팅, 그룹 라우팅.
• 탭 풀 관리 – 브라우저 탭 풀을 유지하며 각 탭을 요청에 할당하고 수명, 상태, 로그를 모니터링합니다.
• 로컬 제어판 – 웹 대시보드(http://127.0.0.1:8199/)에서 브라우저 상태, 요청 기록, 로그를 확인하고 sites.json 또는 프리셋을 즉시 편집할 수 있습니다.
• 보안 옵션 – 선택적 bearer-token / API-key 인증, CORS 제어, 강화된 토큰 요구 사항이 있는 선택적 공개 바인딩, 서비스 노출 시 방화벽/TLS에 대한 명확한 지침 제공.
• 확장 가능한 구성 – 환경 변수(.env), JSON 사이트 규칙, 프록시 지원, 예약 재시작, 프로필 정리 등.

작동 방식(높은 수준 흐름)

1. 클라이언트 → FastAPI 엔드포인트(app/api).
2. FastAPI는 탭 풀(app/core/tab_pool)에 사용 가능한 브라우저 탭을 요청합니다.
3. 탭은 DrissionPage(Chromium 드라이버)(app/core/workflow)로 제어됩니다.
4. 사이트별 파서(app/core/parsers)가 네트워크 응답 또는 DOM을 읽어 AI 모델의 답변을 추출합니다.
5. 서비스는 답변을 JSON 또는 SSE로 형식화하여 클라이언트에 반환합니다.

빠른 시작

# 1. 릴리스를 다운로드하고 영어 전용 경로의 폴더에 압축을 풉니다.
# 2. Windows: start.bat을 더블 클릭
#    macOS/Linux: python3 start.py   # 또는 python main.py (자동 검사 없음)
# 3. 스크립트가 Python 종속성을 설치하고 제어되는 Chromium 프로필을 시작하며 http://127.0.0.1:8199/에서 대시보드를 엽니다.
# 4. 제어되는 브라우저에서 대상 AI 사이트에 로그인합니다.
# 5. 자체 클라이언트를 http://127.0.0.1:8199/v1로 지정하고 GET /v1/models에서 모델을 선택합니다.

API 호출 예시(OpenAI 스타일)

curl http://127.0.0.1:8199/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"你好"}],"stream":false}'

• 인증이 활성화된 경우 -H "Authorization: Bearer <TOKEN>" 또는 -H "X-API-Key: <TOKEN>"를 추가하세요.
• SSE 출력을 위해 "stream": true로 설정하세요.

구성 하이라이트

변수	기본값	용도
APP_HOST	127.0.0.1	바인딩 주소(인증 및 방화벽이 있는 경우에만 0.0.0.0 사용).
APP_PORT	8199	API, 대시보드, 튜토리얼용 포트.
AUTH_ENABLED / AUTH_TOKEN	false / 비어 있음	bearer-token / API-key 보호 전환.
CORS_ENABLED / CORS_ORIGINS	true / 비어 있음	교차 출처 액세스 제어.
BROWSER_PATH	자동 감지	Chrome/Edge/Brave 바이너리 경로.
BROWSER_PROFILE_DIR	프로젝트 폴더	격리를 위한 별도 Chromium 프로필.
SITES_CONFIG_FILE	config/sites.json	사이트 규칙, 프리셋, 라우팅 그룹을 정의하는 JSON 파일.

일반적인 사용 사례

• 웹 전용 AI 서비스에만 액세스할 수 있는 경우 OpenAI 호환 클라이언트의 로컬 개발.
• 공식 API 키 없이 Claude, Gemini 또는 기타 웹 기반 모델에 대한 도구 호출 통합 테스트.
• 기본 DOM을 검사하여 멀티모달 상호 작용(이미지 업로드, 파일 붙여넣기) 디버깅.

제한 사항 / 주의 사항

• 단일 머신 디버깅용으로 설계되었으며, 다중 테넌트 프로덕션 게이트웨이용이 아닙니다.
• 제어되는 브라우저에 로그인 상태를 유지해야 합니다. 로그인 문제, CAPTCHA 또는 계정 잠금이 발생하면 브리지가 중단됩니다.
• 서비스를 공개적으로 노출하려면 강력한 인증, CORS 제한, 방화벽 규칙, 그리고 가능하면 TLS가 있는 리버스 프록시가 필요합니다.
• 이 도구는 대상 AI 웹사이트의 이용 약관을 위반할 수 있습니다. 사용자는 모든 위험을 감수합니다.

라이선스

• AGPL-3.0(LICENSE 참조).

지원

• GitHub에 이슈를 열거나 QQ 그룹 1073037753에 가입하여 커뮤니티 지원을 받으세요.

---

위의 모든 세부 사항은 저장소의 README에서 직접 가져온 것이며 추가 기능은 추론되지 않았습니다.