diff --git a/README.md b/README.md index bdbf6f7..ccc9f43 100644 --- a/README.md +++ b/README.md @@ -1,40 +1,144 @@ -# FOWOCO +# FOWOCO Knowledge & Intent Modeling -E-9 외국인근로자를 고용한 사업장의 반복 HR·행정업무를 구조화하고, -담당자가 다음 행동을 빠뜨리지 않도록 지원하는 업무보조 플랫폼입니다. +FOWOCO는 E-9 외국인근로자를 고용한 사업장의 반복 HR·행정업무를 구조화하고, +담당자가 다음 행동을 놓치지 않도록 지원하는 AI 업무보조 서비스입니다. -이 저장소는 서비스 구성요소를 하나의 저장소에서 관리하는 모노레포입니다. -현재는 Agent가 공통으로 참조할 업무 지식 패키지부터 구축합니다. +이 저장소는 Agent가 참고할 업무 지식과 공식 출처뿐 아니라, HR 발화문을 +`Intent + evidence`로 분류하기 위한 데이터 계약·검수·평가 및 모델 실험 이력을 +함께 관리합니다. 운영 앱과 모델 서버를 구현하는 저장소는 아닙니다. -## Packages +> [!IMPORTANT] +> **🤗 [FOWOCO Hugging Face Model Hub](https://huggingface.co/fowoco)** +> +> 학습 checkpoint, adapter, tokenizer, model card와 공개 가능한 데이터셋은 +> FOWOCO Hugging Face 조직에서 배포합니다. -| 디렉토리 | 역할 | 상태 | +## 목표 + +HR 담당자의 입력에서 다음 7개 Intent를 하나 이상 찾고, 판단 근거가 되는 원문의 +연속 구간을 `evidence`로 반환합니다. + +- `WORKER_ONBOARDING`: 신규 근로자 등록·초기 처리 +- `EXPIRY_RENEWAL`: 체류·계약·고용허가 만료와 갱신 준비 +- `DOCUMENT_REQUEST`: 서류 요청·수령·미제출 추적 +- `PAYROLL_EXPLANATION`: 급여·수당·공제 설명 +- `WORK_INSTRUCTION`: 작업·근무일정·현장 안내 +- `EMPLOYMENT_CHANGE`: 퇴사·결근·사업장 변경 등 고용상태 변동 +- `OUT_OF_SCOPE`: 지원 범위 밖 요청 + +모델은 Intent와 evidence까지만 판단합니다. Workflow 선택, 외부기관 제출, 법적 +판단과 업무 완료는 규칙 검증과 HR 담당자 승인 이후에 처리합니다. + +## 진행 과정 + +| 단계 | 내용 | 저장소 상태 | | --- | --- | --- | -| `fowoco-knowledge` | Intent·Domain·Workflow·공식 출처·검증 데이터 | 개발 중 | -| `fowoco-client` | HR 웹과 근로자 모바일 웹 | 예정 | -| `fowoco-server` | 인증·업무카드·문서·알림 API | 예정 | -| `fowoco-ai` | 분류·추출·Agent 오케스트레이션 | 예정 | -| `fowoco-infra` | 배포·관측·보안 설정 | 예정 | +| 규칙·후보 데이터 | Intent 규칙 v1.1, evidence exact substring, HR 발화문 1,340건 | `main` 반영 | +| A/B 재검수 | 경계 사례 독립 검수와 consensus | [#31](https://github.com/fowoco/knowledge/pull/31), [#35](https://github.com/fowoco/knowledge/pull/35) 검토 중 | +| 모델링 계약 | 유사 템플릿 누수를 막은 Train 1,072건 / Validation 268건 분할 | [#33](https://github.com/fowoco/knowledge/pull/33) 검토 중 | +| 기준 실험 | 수정 전 라벨 baseline과 A.X 테스트 도구 | [#37](https://github.com/fowoco/knowledge/pull/37)이 #33 브랜치에 병합됨 | +| 모델 비교 | A.X-4.0-Light와 KLUE-RoBERTa 실험 | 산출물 반영 예정 | + +## 모델 실험 요약 + +아래 수치는 팀의 최신 Validation 268건 실험 기록입니다. 독립적으로 잠긴 Test +성능이나 운영 성능을 의미하지 않습니다. + +| 모델 | Intent Exact Match | 결론 | +| --- | ---: | --- | +| A.X-4.0-Light Few-shot | 0.7612 | 초기 기준선 | +| A.X-4.0-Light QLoRA | 0.9254 | 복잡한 입력의 보조 모델 후보 | +| KLUE-RoBERTa Full FT | 0.9590 | 메인 모델 후보, 약 186ms | +| KLUE-RoBERTa LoRA | 0.9104 | Full FT보다 낮아 기각 | + +A.X QLoRA는 evidence exact match가 `0.7377`로 Few-shot의 `0.1667`보다 크게 +개선됐습니다. BERT Full FT는 Intent 분류 성능과 응답속도가 가장 좋았습니다. + +## 현재 모델 결론 + +```text +HR 입력 + -> BERT Intent 분류 + -> 복잡도·경계 패턴·예측 margin 검사 + -> 위험하거나 불확실함: A.X로 라우팅 + -> 그 외: BERT 결과 사용 + -> 출력 Schema 검증 + -> Workflow 선택과 HR 승인 +``` + +A.X 라우팅 후보 조건은 다음과 같습니다. + +- 활성 Intent가 3개 이상인 복잡한 문장 +- 완료·상태보고, 급여계좌, 서류 확보 등 검증된 경계 패턴 +- 선택·비선택 Intent 사이의 margin이 `0.76` 미만인 불확실한 예측 -## Quick start +현재 Validation에서는 34.3%가 A.X 라우팅 대상으로 선택됐고, BERT 오답이 모두 +라우팅 조건에 포함됐습니다. 이는 A.X가 모든 오답을 정정했다는 뜻이 아니며, 같은 +Validation에서 만든 규칙이므로 별도 Test에서 다시 검증해야 합니다. + +## 현재 데이터 상태 + +- `main`에는 HR 발화문 후보 데이터 1,340건과 Intent 규칙 v1.1이 있습니다. +- A/B consensus와 고정 split은 아직 `main`에 병합되지 않았습니다. +- consensus 또는 원본이 변경되면 split과 모델 평가는 다시 생성해야 합니다. +- Validation은 모델 개발용이며 최종 성능 주장을 위한 Gold Test가 아닙니다. +- 실제 개인정보와 기업정보는 학습·평가 데이터에 저장하지 않습니다. + +최신 BERT·A.X 학습 checkpoint와 운영 서빙 코드는 아직 `main`에 포함하지 않습니다. + +## Hugging Face Model Hub + +[FOWOCO Hugging Face](https://huggingface.co/fowoco)는 모델 산출물의 공식 공개 +창구입니다. GitHub에는 재현과 검증에 필요한 규칙·계약·코드를, Hugging Face에는 +실제로 배포할 모델 파일과 설명을 둡니다. + +| 위치 | 관리 대상 | +| --- | --- | +| **[Hugging Face](https://huggingface.co/fowoco)** | checkpoint, adapter, tokenizer, model card, 공개 가능한 데이터셋 | +| GitHub | 업무 지식, 라벨 규칙, 데이터 계약, 분할·평가 코드, 실험 기록 | + +현재 Hugging Face 조직에는 공개된 모델·데이터셋이 없습니다. 산출물을 게시할 때는 +학습 데이터 version·SHA-256, 평가 조건, 라이선스와 사용 한계를 model card에 함께 +기록합니다. + +## 남은 과제 + +- 최종 consensus 데이터·manifest와 모델 실험 산출물의 저장소 반영 +- 독립 Gold Test에서 BERT·A.X·Cascade 재평가 +- BERT 경로의 evidence 추출 방식 확정 +- 다중 근로자·다중 지시 문장 보강 +- A.X GPU 서빙과 실제 운영 환경의 속도·자원 측정 +- 학습·서빙 코드는 최종적으로 `fowoco/ai`로 이전 + +## 저장소 구조 + +```text +fowoco-knowledge/ +├── knowledge/ # Intent·Workflow·Guardrail·공식 링크 +├── data/ # Seed·Intent·평가·공공 정규화 데이터 +├── schemas/ # 데이터·모델 출력 계약 +├── src/ # Knowledge 검증·조회 CLI +├── tests/ # Schema·누수·재현성 테스트 +└── docs/ # 라벨·검수·모델링·출처 문서 +``` + +## 실행 ```bash python3.11 -m venv .venv make install -make validate -make test +make check ``` -자세한 사용법은 [`fowoco-knowledge/README.md`](fowoco-knowledge/README.md)를 참고합니다. - -## 원칙 +세부 기준은 다음 문서를 참고합니다. -- 법정기한 계산, 필수값 확인, 상태 전이는 검증 가능한 규칙으로 처리 -- AI는 자연어 분류·정보 추출·모호성 탐지·초안 생성에 사용 -- MVP의 모든 외부 발송과 기관 제출은 HR 담당자 승인 후 수행 -- 개인정보 원문은 학습·품질개선 데이터에 저장하지 않음 -- 공식 절차와 서류 지식은 출처, 검증일, 버전을 함께 관리 +- [Intent 라벨 기준](fowoco-knowledge/docs/INTENT_DATA.md) +- [모델 계획](fowoco-knowledge/docs/MODEL_PLAN.md) +- [공식 데이터 파이프라인](fowoco-knowledge/docs/OFFICIAL_DATA_PIPELINE.md) -## 협업 +## 안전 원칙 -변경 전 [`CONTRIBUTING.md`](CONTRIBUTING.md)의 브랜치·커밋·데이터 검수 규칙을 확인합니다. +- 모델 출력만으로 법률·체류·급여·신고 결론을 확정하지 않습니다. +- 외부기관 제출과 근로자 안내 발송은 HR 승인 후 수행합니다. +- 실제 외국인등록번호, 여권번호, 전화번호, 계좌번호를 저장하지 않습니다. +- 날짜·금액·서류명·제출처·대상자·기한의 누락과 변경을 중점 검증합니다.