instance-classifier — 프로세스 인스턴스 자동분류 · Top List

민원 자동 그룹화 · Top List 프로토타입(원본)을 ProcessGPT 마이크로서비스로 이식한 것. 프로세스 인스턴스가 생성되면 첫 워크아이템의 폼 입력값(사용자 요청 내용) 을 폴링으로 인제스천하여 유사 인스턴스로 분류하고, 프로세스 정의별 Top 요청 리스트를 제공한다. 또 워크아이템 핸들러가 유사 과거 인스턴스의 처리결과를 참고할 수 있도록 API 로 노출한다.

핵심 개념 (원본 계승)

• 벡터 DB(pgvector)는 그룹화를 하지 않는다. 저장 + 유사도 검색(ANN) + SQL 집계만.
• 그룹화(클러스터링)는 BERTopic(임베딩 → UMAP → HDBSCAN → c-TF-IDF)이 배치로 한다.
• 온라인(폴링 인제스천) 은 새 인스턴스를 기존 그룹에 kNN 다수결로 매칭한다(원본 match.py).
• 배치(재클러스터링) 는 축적된 인스턴스를 다시 그룹화해 토픽을 (재)생성한다(원본 pipeline.py).

bpm_proc_inst 신규 → 첫 workitem 폼 output → 요청 텍스트
   → 임베딩(OpenAI 프록시 / BGE-M3) → pgvector kNN 매칭 → voc_instances 적재
   → Top List(GROUP BY) / 유사 인스턴스+처리결과(<=> 검색)
주기적 배치: BERTopic 재클러스터링 → voc_topics 갱신

원본 대비 달라진 점

원본	여기
합성 민원 CSV 생성	ProcessGPT bpm_proc_inst/todolist 를 폴링
BGE-M3 SentenceTransformer 고정	기본 OpenAI 호환 임베딩(LLM 프록시), BGE-M3 옵트인
Claude(anthropic) 명명	OpenAI 호환 챗(LLM 프록시) 명명 + 키워드 폴백
독립 pgvector 컨테이너	공유 supabase-db(pgvector) 에 voc_* 테이블
CLI 배치 실행	FastAPI + 백그라운드 asyncio 폴러
전역 topic_id	프로세스 정의(proc_def_id)별 토픽 네임스페이스

동작 방식

1. 폴러(app/poller.py): POLLING_INTERVAL(기본 10s)마다 bpm_proc_inst 에서 최근 인스턴스를 훑고, 아직 인제스천 안 된 것만 처리한다.
2. 인제스천(app/ingest.py): 인스턴스의 첫(시작) 워크아이템을 찾아 todolist.output 폼 값 + form_def.fields_json 라벨로 요청 텍스트를 만든다(비면 description/변수/이름으로 폴백). 임베딩 후 같은 정의의 기존 인스턴스에 kNN 다수결로 topic 을 배정하고 voc_instances 에 적재.
3. 자동 클러스터링: 한 정의의 인스턴스가 RECLUSTER_MIN_INSTANCES 를 넘고 아직 토픽이 없으면 BERTopic 배치를 자동 1회 실행한다. 이후엔 POST /recluster 로 수동 재학습.

API

메서드	경로	설명
GET	/health	헬스체크
GET	/proc-defs	적재된 프로세스 정의 목록 + 건수
GET	/toplist?proc_def_id=	Top List(유형별 건수/비율)
GET	/topics/{proc_def_id}/{topic_id}/instances	특정 유형의 인스턴스
GET	/similar?proc_inst_id=… 또는 ?text=…&proc_def_id=…	유사 인스턴스 top-k + 각 처리결과(done_outputs)
POST	/ingest {proc_inst_id, force}	인스턴스 즉시 인제스천
POST	/recluster {proc_def_id, …}	배치 재클러스터링

게이트웨이(nginx)에서 /instance-classifier/* 로 프록시된다(프리픽스 STRIP). 예) 프론트엔드는 /instance-classifier/toplist?proc_def_id=leave_request_process 를 호출.

로컬 실행

cd services/instance-classifier
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env   # DB_*, OPENAI_* 채우기
python main.py          # http://localhost:8000

컨테이너

compose/docker-compose.yml 의 instance-classifier 서비스로 기동한다.

./start-all-services.sh instance-classifier

파일 구조

app/
  config.py         설정(.env/env)
  db.py             supabase-db psycopg 접속 + voc_* 스키마 보장
  source_reader.py  bpm_proc_inst/todolist/form_def 읽기 → 요청 텍스트/처리결과
  embed.py          임베딩(OpenAI 프록시 기본, BGE-M3 옵트인)  [원본 embed.py]
  cluster.py        BERTopic 그룹화                          [원본 cluster.py]
  naming.py         LLM 유형명 + 키워드 폴백                  [원본 naming.py]
  store.py          voc_* 적재/kNN/TopList  [원본 store_pgvector+match+toplist]
  ingest.py         인스턴스 단건 인제스천/분류               [원본 match.py]
  recluster.py      배치 재클러스터링                        [원본 pipeline.py]
  poller.py         백그라운드 폴링 루프
  server.py         FastAPI 엔드포인트
main.py             uvicorn 엔트리포인트
sql/schema.sql      voc_topics / voc_instances (+HNSW)