Spaces:
Sleeping
Sleeping
| title: Local Bridge API | |
| emoji: 🌉 | |
| colorFrom: blue | |
| colorTo: green | |
| sdk: docker | |
| pinned: false | |
| app_port: 7860 | |
| # Local Bridge — Backend API | |
| 외국인 근로자를 위한 AI 기반 노동권익 보호 플랫폼 **Local Bridge**의 FastAPI 백엔드입니다. | |
| Hugging Face Spaces (CPU Basic) 위에서 동작하며, Flutter 앱과 `/chat` 엔드포인트로 통신합니다. | |
| --- | |
| ## 엔드포인트 | |
| | Method | Path | 설명 | | |
| |--------|------|------| | |
| | GET | `/` | 서버 상태 확인 | | |
| | GET | `/health` | 헬스체크 | | |
| | POST | `/chat` | 메인 에이전트 호출 | | |
| ### POST `/chat` — 요청 | |
| ```json | |
| { | |
| "session_id": "uuid-v4", | |
| "message": "주휴수당이 뭐예요?", | |
| "image_base64": "...(선택, 계약서 이미지)", | |
| "language": "ko", | |
| "location": { "lat": 37.2636, "lng": 127.0286 } | |
| } | |
| ``` | |
| ### POST `/chat` — 응답 | |
| ```json | |
| { | |
| "session_id": "uuid-v4", | |
| "reply": "주휴수당은 ...", | |
| "warning_cards": [ | |
| { "title": "최저임금 미달", "content": "...", "severity": "high", "law": "최저임금법 제6조" } | |
| ], | |
| "map_pins": [ | |
| { "name": "수원시외국인복지센터", "address": "...", "lat": 37.27, "lng": 127.01, "phone": "031-..." } | |
| ], | |
| "next_actions": ["고용노동부 1350에 전화하세요"] | |
| } | |
| ``` | |
| --- | |
| ## 파이프라인 | |
| ``` | |
| POST /chat | |
| └─ DLP 마스킹 (PII 제거) | |
| └─ 계약서 이미지 전처리 (이미지 첨부 시, Gemini Vision) | |
| └─ Gemini 3.1 Pro 단일 에이전트 + Function Calling 루프 (최대 8회) | |
| ├─ search_labor_law(query) → ChromaDB 벡터 검색 | |
| ├─ find_nearby_centers(lat, lng) → 수원시 기관 거리 계산 | |
| └─ get_center_info(type) → 기관 목록 조회 | |
| └─ ChatResponse 반환 | |
| ``` | |
| --- | |
| ## 환경변수 (HF Spaces Secrets) | |
| Space 설정 → **Variables and secrets** 에서 아래 항목을 Secret으로 등록하세요. | |
| | 변수명 | 필수 | 설명 | | |
| |--------|------|------| | |
| | `GEMINI_API_KEY` | ✅ | Google AI Studio API 키 | | |
| | `GOOGLE_MAPS_API_KEY` | 선택 | Maps API (미설정 시 maps_tool 비활성) | | |
| | `GOOGLE_CLOUD_PROJECT_ID` | 선택 | Cloud DLP 사용 시 필요 | | |
| > `VECTOR_DB_PATH`는 Dockerfile에서 `/data/chromadb`로 자동 설정됩니다. | |
| > 첫 실행 시 `labor_law_chunks.json`에서 자동 시딩되며, `/data`에 저장되어 재시작 시 유지됩니다. | |
| --- | |
| ## 로컬 실행 | |
| ```bash | |
| cd backend | |
| cp ../.env.example .env # 환경변수 설정 | |
| pip install -r requirements.txt | |
| uvicorn app:app --reload --host 0.0.0.0 --port 8000 | |
| ``` | |
| Flutter 에뮬레이터에서 접근할 때는 `http://10.0.2.2:8000` 을 사용하세요. | |
| --- | |
| ## 기술 스택 | |
| - **Runtime**: Python 3.11 / FastAPI / Uvicorn | |
| - **AI**: Gemini 3.1 Pro (Function Calling), `text-embedding-004` | |
| - **Vector DB**: ChromaDB (persistent, `/data/chromadb`) | |
| - **PII**: Google Cloud DLP (선택) / regex fallback | |
| - **배포**: Hugging Face Spaces — Docker SDK, CPU Basic (2 vCPU / 16 GB RAM) | |