Fix README frontmatter: backend entry = app_backend.py (was incorrectly app.py — UI launched instead of backend)

README.md

@@ -1,266 +1,56 @@
 ---
-title: 개인정보보호법 미니 상담 (KPAA)
-emoji: ⚖️
-colorFrom: blue
-colorTo: green
+title: KPAA Backend - 개인정보보호법 RAG 추론 API
+emoji: 🧠
+colorFrom: green
+colorTo: blue
 sdk: gradio
 sdk_version: "5.20.0"
-app_file: app.py
+app_file: app_backend.py
 pinned: false
-short_description: 한국 개인정보보호법 RAG 상담 챗봇 (Gemma 4 E2B + 법제처 OPEN API)
+short_description: KPAA RAG 추론 백엔드 (OpenAI 호환 API)
 hardware: zero-a10g
 license: mit
 ---
 
-# 개인정보보호법 미니 상담 챗봇 (KPAA)
+# KPAA Backend
 
-> 개인 · 소상공인 · 작은 병원을 위한 한국 개인정보보호법 안내 챗봇.
-> 법제처 OPEN API + 개인정보보호위원회 상담사례 1,745건을 근거로
-> 작은 모델(Gemma 4 E2B)이 한국어 평문으로 답합니다.
+한국 개인정보보호법 RAG 백엔드. **OpenAI 호환 API**를 노출합니다.
 
-- **법제처 OPEN API**(MCP 레이어 없이 Python으로 직접 호출, 15개 카테고리 SDK)
-- **개인정보보호위원회 상담사례** 1,745건 로컬 SQLite FTS5 인덱스
-- **RAG 사전조회** — 룰 라우터로 법조문/사례/PIPC결정/해석례 병렬 fan-out → Gemma는 그 컨텍스트만 보고 답변
-- **모든 답변에 인용 + 면책 자동 부착**
+이 Space는 **추론 백엔드 전용**입니다. UI는 별도 Space([scvcoder/korean-privacy-ai-assistant](https://huggingface.co/spaces/scvcoder/korean-privacy-ai-assistant))에서 Open WebUI로 제공됩니다.
 
----
-
-## 두 가지 사용 경로
-
-### 🤗 한 번 클릭으로 체험 — Hugging Face Spaces 데모
-
-배포된 Space 링크에 접속해서 바로 채팅. 별도 설치·키 발급 불필요.
-ZeroGPU(A100) 가속으로 빠른 응답.
-
-> Space 가 잠시 휴면(sleep) 상태일 수 있습니다 — 첫 방문 시 wake-up 5–10초 대기.
-
-### 💻 노트북에서 직접 돌리기 (권장 — SMB·장기 사용자)
-
-GitHub clone → `pip install` → 자기 데이터/키로 운영. 외부 의존 없음 (법제처
-OPEN API 호출 외 모든 것이 로컬). 아래 "사전 조건" 부터 따라가세요.
-
----
-
-## 사전 조건
-
-- Python **3.11 이상** (Win/Mac/Linux 공통) — 또는 Docker Desktop
-- 8GB 이상 여유 RAM (Gemma 4 E2B Q4_K_M ~3.2GB + KV cache + 백엔드)
-- **법제처 OPEN API 키 (LAW_OC) 무료 발급** — https://open.law.go.kr 가입 후 마이페이지에서 ID(이메일 @ 앞부분) 확인
-
----
-
-## 빠른 시작
-
-`.env`에 OC 키부터 입력:
-
-```bash
-git clone https://github.com/sz1-kca/korean-privacy-ai-assistant
-cd korean-privacy-ai-assistant
-
-# Mac/Linux
-cp .env.example .env
-# Windows PowerShell
-copy .env.example .env
-
-# 편집기로 .env 열어 LAW_OC=<발급받은_id> 입력
-```
-
-이후 두 가지 경로 중 하나.
-
-### 경로 A — 네이티브 (권장, Docker 불필요)
-
-```bash
-# 의존성 + 패키지 설치
-pip install -e ".[dev,llm]"
-
-# (1) 백엔드 — RAG + LLM (FastAPI :8000)
-python -m kpaa serve
-
-# (2) 새 터미널에서 Open WebUI (한 번만 설치)
-pip install open-webui
-open-webui serve     # http://localhost:8080
-```
-
-Open WebUI에서 Settings → Connections → **OpenAI API** → `+ Add Connection`:
-- URL: `http://localhost:8000/v1`
-- Key: `local`
-- 모델 드롭다운에서 **`kpaa-privacy-ko`** 선택
-
-첫 `kpaa serve` 실행 시 Gemma 4 E2B GGUF (~3.2GB)을 자동 다운로드합니다 (~5–15분, 한 번만).
-
-### 경로 B — Docker Compose
-
-```bash
-docker compose up -d
-# → http://localhost:3000 (Open WebUI 자동 연결)
-# 첫 가동 시 backend가 모델 다운로드, 5–15분 소요
-docker compose logs -f backend   # 진행 확인
-```
-
-`docker-compose.yml`이 Open WebUI에 OpenAI 커넥션을 미리 주입하므로 UI에서 별도 설정 없이 즉시 `kpaa-privacy-ko` 모델로 채팅 가능합니다.
-
----
-
-## 🔐 인증 모드 (개인용 vs 다중 사용자)
-
-**기본값 — 즉시 사용 모드 (`WEBUI_AUTH=false`).** `manage.sh` / `Dockerfile.ui` / `docker-compose.yml` 모두 이 값을 주입하므로 첫 부팅 시 `admin@localhost`/`admin` 관리자 계정이 자동 생성되어 가입·로그인 화면 없이 바로 채팅 화면이 뜹니다. **개인 PC 로컬 (`127.0.0.1`) 단독 사용 가정**.
-
-⚠️ **공용/원격 노출 시 위험**: 이 모드에서는 호스트:포트에 접근 가능한 누구나 admin 권한으로 들어옵니다. LAN/공용 서버로 노출(0.0.0.0 바인딩, 포워딩, 리버스 프록시) 시 반드시 아래 인증 모드로 전환하세요.
+## 아키텍처
 
-**인증 모드 — 본인 이메일/비밀번호 사용.** 환경변수만 바꾸고 재시작:
-
-```bash
-# 네이티브 (manage.sh):
-export KPAA_OPENWEBUI_WEBUI_AUTH=true
-./manage.sh restart
 ```
-
-Docker 사용자는 [`Dockerfile.ui:16`](Dockerfile.ui#L16) / [`docker-compose.yml`](docker-compose.yml) 의 `WEBUI_AUTH` 를 `true` 로 바꿔 재빌드.
-
-전환 후 첫 부팅에서 가입 화면이 뜨고, 본인 이메일/비밀번호로 admin 등록 → 이후 매 세션 로그인 + 비밀번호 자유 변경 가능. **즉시 사용 모드의 `admin@localhost`/`admin` 계정에서 비밀번호를 바꾸려고 시도하면 자동 로그인이 깨져 잠기므로** 본인 비밀번호 운영을 원하면 처음부터 인증 모드로 시작하세요.
-
-| 모드 | 화면 마찰 | 비밀번호 자유도 | 권장 환경 |
-|---|---|---|---|
-| `WEBUI_AUTH=false` (기본) | 0 (즉시 채팅) | 고정 `admin/admin` | 개인 PC 로컬 |
-| `WEBUI_AUTH=true` | 매 세션 로그인 | 자유 | LAN/공용 서버 |
-
----
-
-## 사용 예 (CLI)
-
-```bash
-# 법제처 SDK 단독 호출 (LLM 없음)
-python -m kpaa law search "개인정보보호법"
-python -m kpaa law text 270351 --jo "24의2"
-python -m kpaa pipc search "동의 철회"
-python -m kpaa expc search "개인정보 수집"
-
-# 상담사례 검색 (로컬 SQLite, ms 단위)
-python -m kpaa cases search "병원 환자 동의"
-
-# RAG 컨텍스트만 빌드 (LLM 호출 없음, 빠름)
-python -m kpaa retrieve "매장 CCTV 안내문구 어떻게 써요?"
-
-# RAG + LLM 종단
-python -m kpaa smoke "매장 CCTV 안내문구 어떻게 써요?"
-
-# 상담사례 갱신 (privacy.go.kr 재스크래이프 ~2분)
-python -m kpaa refresh-cases
-python -m kpaa refresh-cases --since 2025-01-01    # 증분
+사용자 브라우저
+    ↓ (UI 접속)
+[Open WebUI Space]
+    ↓ (OpenAI API 호출)
+[이 Space — KPAA Backend]
+    ↓ (RAG 검색 + Gemma 4 추론)
+법제처 OPEN API + 상담사례 SQLite + ZeroGPU
 ```
 
----
-
-## OS별 주의사항
-
-KPAA 는 *장비별 자동 선택* 으로 GPU 가속 여부를 결정합니다.
-사용자가 `KPAA_N_GPU_LAYERS` 를 명시하지 않으면 다음 규칙:
+## Endpoints
 
-| 플랫폼 | llama-cpp 빌드 | 자동 결과 |
+| Method | Path | 설명 |
 |---|---|---|
-| Windows / Linux | GPU 빌드 (CUDA·ROCm·Vulkan 등) | `-1` (모든 레이어 GPU) |
-| Windows / Linux | CPU 빌드 (기본 `pip install`) | `0` (CPU) |
-| macOS (Apple Silicon / Intel) | Metal 빌드 / 일반 | `0` (CPU, opt-in) |
-
-### Windows
-- PowerShell 한글 깨짐 방지: `chcp 65001` + `PYTHONUTF8=1` (CLI 진입 시 자동 UTF-8 reconfigure 적용)
-- NVIDIA GPU 사용 시 (CUDA Toolkit 설치 후):
-  ```powershell
-  $env:CMAKE_ARGS = "-DGGML_CUDA=on"
-  pip install --force-reinstall --no-cache-dir llama-cpp-python
-  ```
-  재설치 후엔 자동으로 GPU 모드로 동작 (`KPAA_N_GPU_LAYERS` 명시 불필요).
+| POST | `/v1/chat/completions` | OpenAI 호환 chat (`stream=true` 지원) |
+| GET | `/v1/models` | 사용 가능 모델 (`kpaa-privacy-ko`) |
+| GET | `/healthz` | liveness check |
+| GET | `/info` | 상세 정보 + Swagger UI |
+| GET | `/gradio` | Gradio 상태 페이지 |
 
-### macOS (Apple Silicon / Intel)
-- **기본 CPU 추론** — Gemma 4 E2B Q4_K_M + Metal 조합 segfault 회귀 회피
-  (라이브 검증 2026-05-01: `n_gpu_layers=-1` 시 모델 로드 직후 프로세스
-  silently die, `n_gpu_layers=12` 시 응답 hang. 안정성 미확정).
-- 노트북 *팬 소음* 이 거슬리면 스레드 수를 더 줄이세요:
-  ```bash
-  KPAA_N_THREADS=4 python -m kpaa serve   # 16코어 M3 Max → 4 만 사용
-  ```
-  반대로 빠른 추론을 원하면 늘리거나 (속도 ↑ 발열·소음 ↑):
-  ```bash
-  KPAA_N_THREADS=12 python -m kpaa serve
-  ```
-- Apple Silicon Metal GPU 가속 *opt-in* (segfault 우려, 자기 책임):
-  ```bash
-  KPAA_N_GPU_LAYERS=-1 python -m kpaa serve
-  ```
-  segfault 등 호환성 이슈가 보이면 변수 제거 (자동 CPU 환원).
-- 정부 사이트 SSL 인증서: `truststore` 가 시스템 신뢰 저장소 자동 사용 (별도 설정 불필요).
+## Open WebUI 연결 (UI Space에서 자동 설정)
 
-### Linux
-- NVIDIA GPU 사용 시:
-  ```bash
-  CMAKE_ARGS="-DGGML_CUDA=on" pip install --force-reinstall --no-cache-dir llama-cpp-python
-  ```
-  재설치 후 자동 감지. `KPAA_N_GPU_LAYERS` 명시 불필요.
-- ROCm: `CMAKE_ARGS="-DGGML_HIPBLAS=on"`, Vulkan: `CMAKE_ARGS="-DGGML_VULKAN=on"` — 동일 패턴.
-
----
-
-## 환경변수 (`.env`)
-
-| 변수 | 기본 | 설명 |
-|---|---|---|
-| `LAW_OC` | (필수) | 법제처 OPEN API 인증 ID (이메일 @ 앞부분) |
-| `KPAA_N_GPU_LAYERS` | (자동) | GPU offload 레이어 수 — 미지정 시 *플랫폼·빌드 자동 감지* (위 표). 강제 override: `-1`=모두 / `0`=CPU / 정수=일부 |
-| `KPAA_N_THREADS` | (자동) | CPU 추론 스레드 수 — *플랫폼별 자동*: macOS=`cpu/3` (4~6 cap, 노트북 발열·소음 절제), Linux/Win=`cpu/2` (4~8 cap). 빠른 추론 원하면 늘리고 더 조용히 원하면 줄임 |
-| `KPAA_MODEL_DIR` | (자동) | GGUF 캐시 경로 — 미지정 시 `platformdirs.user_cache_dir/kpaa/models` |
-| `KPAA_HOST` / `KPAA_PORT` | `127.0.0.1` / `8000` | FastAPI 바인딩 |
-| `KPAA_LLM_BACKEND` | (자동) | LLM 백엔드 선택 — `llama_cpp`(로컬 GGUF) 또는 `zerogpu`(HF Spaces transformers). 미지정 시 `SPACE_ID` 환경변수로 자동 분기 |
-| `KPAA_HF_MODEL_REPO` | `google/gemma-4-E2B-it` | ZeroGPU 백엔드용 transformers repo |
-| `KPAA_HF_GPU_DURATION` | `120` | `@spaces.GPU` 함수당 GPU 점유 한도(초) |
-| `KPAA_OPENWEBUI_WEBUI_AUTH` | `false` | `true` 로 두면 OpenWebUI 가입/로그인 화면 활성화 (본인 이메일·비밀번호). 자세히는 위 "🔐 인증 모드" |
-
----
-
-## 🤗 Hugging Face Spaces 직접 배포하기
-
-본 리포는 **HF Spaces 의 Gradio + ZeroGPU 환경에서 그대로 동작**한다.
-저장소를 fork 하거나 자체 Space 에 클론해 자기 도메인으로 운영 가능.
-
-### 절차
-1. https://huggingface.co/new-space — Space 생성. SDK = **Gradio**, Hardware = **ZeroGPU** (Pro 무료) 또는 CPU upgrade.
-2. **Persistent Storage** 활성화 (Pro: 20GB 무료) — transformers 모델이 한 번만 받아짐.
-3. **Settings → Variables and secrets**:
-   - Secret: `LAW_OC` = 본인 법제처 OPEN API ID
-   - Variable: `HF_HOME=/data/.huggingface` (persistent storage 위에 모델 캐시)
-4. 본 리포를 Space 에 push (`git remote add hf https://huggingface.co/spaces/<user>/<space>` → `git push hf main`).
-5. 첫 빌드 10–15분 (torch + transformers + 모델 다운로드). 이후 재시작 즉시 부팅.
-6. 채팅 테스트.
-
-### 로컬에서 Gradio UI 미리보기
 ```bash
-pip install -e ".[dev,llm,hf]"
-KPAA_LLM_BACKEND=llama_cpp python app.py     # 로컬 GGUF + Gradio UI
-# → http://127.0.0.1:7860
+OPENAI_API_BASE_URL=https://scvcoder-kpaa.hf.space/v1
+OPENAI_API_KEY=any-value
+DEFAULT_MODELS=kpaa-privacy-ko
 ```
 
-### 듀얼 모드 정리
-
-| 환경 | 진입점 | LLM 백엔드 | UI |
-|---|---|---|---|
-| 로컬 노트북 (장기 사용·SMB) | `python -m kpaa serve` | `llama_cpp` (GGUF, CPU/Metal/CUDA) | FastAPI `/chat` (자체 SSE) 또는 Open WebUI |
-| HF Spaces 데모 (대중 체험) | `python app.py` (자동) | `zerogpu` (transformers + `@spaces.GPU`) | Gradio Blocks |
-| 로컬 Gradio 미리보기 | `KPAA_LLM_BACKEND=llama_cpp python app.py` | `llama_cpp` (강제) | Gradio Blocks |
-
-같은 RAG 파이프라인(법제처 호출, 라우팅, 인용·면책 부착) 을 양쪽이 공유.
-
----
-
-## 데이터 출처 / 라이선스
-
-- **법제처 OPEN API** (https://open.law.go.kr) — 1인 1키 무료. 응답 데이터는 공공누리 표시 후 사용 가능.
-- **개인정보 상담사례** (https://www.privacy.go.kr) — 약 1,745건, 공공누리 제1유형 추정. 본 리포의 [`data/cases.sqlite`](data/cases.sqlite)는 시점 스냅샷이며 갱신은 `kpaa refresh-cases` 또는 월 1회 GitHub Actions 자동 PR.
-- **Gemma 4** — [Gemma Terms of Use](https://ai.google.dev/gemma/terms) + Apache 2.0. GGUF (로컬용): [`bartowski/google_gemma-4-E2B-it-GGUF`](https://huggingface.co/bartowski/google_gemma-4-E2B-it-GGUF). transformers (HF Spaces 용, 같은 가중치): [`google/gemma-4-E2B-it`](https://huggingface.co/google/gemma-4-E2B-it).
-- 본 프로젝트 코드: **MIT** ([LICENSE](LICENSE), [NOTICE](NOTICE))
-
-로컬 사용자: 채팅 기록은 Open WebUI 로컬 SQLite 또는 자체 `/chat` UI 의 브라우저 메모리에만. HF Spaces 데모: Gradio 세션 종료 시 휘발. 외부 텔레메트리 없음.
-
----
-
-## 면책
+## Secrets / Hardware
+- **Secret** `LAW_OC` — 법제처 OPEN API ID (필수)
+- **Hardware** ZeroGPU (zero-a10g) — Pro 무료
 
-본 챗봇 답변은 **일반적 정보 제공**이며 법률 자문이 아닙니다. 구체적 사안은 개인정보보호위원회(privacy.go.kr) 또는 변호사 상담을 권합니다. 신고: KISA 개인정보침해신고센터 국번없이 **118**.
+## 라이선스
+MIT (코드) · 답변 데이터는 PIPC/privacy.go.kr 출처표시