README.md

---
title: CertWeb Reranker API
sdk: docker
app_port: 7860
---

# Reranker API (무료 · Colab 불필요)

CertWeb RAG용 Cross-Encoder 리랭커를 **Hugging Face Spaces 무료**로 서빙합니다.  
Colab을 켜 둘 필요 없이, 한 번 배포해 두면 요청 시 자동으로 깨웁니다.

## 1. 모델을 HF Hub에 올리기

1. [Hugging Face](https://huggingface.co) 로그인 후 **New model** 생성.
2. Colab에서 만든 `fine_tuned_reranker` 폴더 내용을 업로드:
   - `config.json`, `model.safetensors`, `tokenizer.json`, `tokenizer_config.json` 등
3. 모델 repo 이름 확인 (예: `your-username/certweb-reranker`).

## 2. 이 Space 만들기

1. **New Space** → 이름 예: `certweb-reranker`, **SDK: Docker** 선택.
2. 이 폴더 파일들을 Space repo에 넣기:
   - `app.py`, `requirements.txt`, `Dockerfile`, `README.md`
3. Space **Settings** → **Repository secrets** 또는 **Variables**:
   - 이름: `HF_MODEL_ID`
   - 값: `your-username/certweb-reranker` (위 1번 모델 repo)
4. Space가 빌드·실행되면 **App** URL이 생깁니다.  
   예: `https://your-username-certweb-reranker.hf.space`

## 3. CertWeb 백엔드에 연결

로컬 또는 Render `.env`:

```env
RAG_USE_CROSS_ENCODER_RERANKER=true
RAG_CROSS_ENCODER_MODEL=https://your-username-certweb-reranker.hf.space
```

끝에 슬래시 없이 URL만 넣으면 됩니다.

## API 규약

- **POST /**  
  Body: `{"query": "질문", "passages": ["문단1", "문단2", ...]}`  
  Response: `{"scores": [0.9, 0.2, ...]}`

## 참고

- 무료 CPU Basic: 16GB RAM. **MiniLM 기반** 파인튜닝 모델 권장 (2GB급 대형 모델은 OOM 가능).
- 슬립 후 첫 요청은 **콜드스타트 30초~1분** 걸릴 수 있음. 백엔드 타임아웃 60초 이상 권장.