refactor: GPU 서버 재구성 + ChromaDB→Qdrant 마이그레이션

- embed_to_chroma.py → embed_to_qdrant.py 리라이트 (bge-m3 + Qdrant REST API) - auto_classify.scpt: embed_to_qdrant.py 경로 변경 + sourceChannel 덮어쓰기 버그 수정 - requirements.txt: chromadb/schedule 제거, qdrant-client/flask/gunicorn 추가 - credentials.env.example: GPU_SERVER_IP 항목 추가 - GPU 서버 재구성 계획서 (docs/gpu-restructure.md) + dev-roadmap/commands 통합 - CLAUDE.md, README.md, deploy.md 현행화 GPU 서버 변경사항 (이미 적용됨): - Ollama: qwen3.5:9b, id-9b 제거 → bge-m3 + bge-reranker-v2-m3 - Surya OCR 서비스 (:8400, systemd) - Docker + NFS + Komga 이전 (:25600) - tk-ai-service: Ollama API → OpenAI API 전환 (MLX 35B) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-30 13:19:31 +09:00
parent 35062145ed
commit 45cabc9aea
11 changed files with 2068 additions and 277 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,21 +1,68 @@
 # DEVONThink PKM 시스템 — Claude Code 작업 가이드

+> 마지막 업데이트: 2026-03-29
+> 개발 현황: Phase 1 초기 구축 완료 → Phase 1.5 GPU 서버 재구성 + Phase 2 인프라 수정 병행 중
+
 ## 프로젝트 개요

 Mac mini M4 Pro(64GB, 4TB) 기반 개인 지식관리(PKM) 시스템.
-DEVONthink 4를 중앙 허브로, Ollama AI 자동 분류 + 법령 모니터링 + 일일 다이제스트를 자동화한다.
+DEVONthink 4를 중앙 허브로, MLX AI 자동 분류 + 법령 모니터링 + 일일 다이제스트를 자동화한다.

 ## 핵심 문서 (반드시 먼저 읽을 것)

 1. `docs/architecture.md` — 전체 시스템 아키텍처 (DB 구조, 태그, AI, 자동화 전체)
 2. `docs/industrial-safety-blueprint.md` — 04_Industrial Safety DB 상세 설계
-3. `docs/claude-code-commands.md` — 단계별 작업 지시서
+3. `docs/claude-code-commands.md` — 단계별 작업 지시서 (현재 진행 상황 포함)
+4. `docs/dev-roadmap.md` — 개발 로드맵 (Phase 1.5~6)
+5. `docs/deploy.md` — Mac mini 배포 가이드 + 트러블슈팅
+6. `docs/gpu-restructure.md` — GPU 서버 재구성 상세 계획 (Phase 1.5)
+
+## 개발 현황 요약
+
+```
+[Phase 1: 초기 구축] ██████████████████░░ 90% — 코드 작성 완료, 인프라 일부 미해결
+
+  ✅ 1단계: 프로젝트 구조          — 완료
+  ✅ 2단계: AI 분류 프롬프트        — MLX Qwen3.5 OpenAI 호환 전환 완료
+  ✅ 3단계: AppleScript            — auto_classify + omnifocus_sync 완료
+  ⚠️ 4단계: 법령 모니터링          — 외국(US/JP/EU) OK, 한국 API IP 미등록
+  ❌ 5단계: MailPlus 수집          — IMAP Connection refused
+  ⚠️ 6단계: Daily Digest          — 코드 완성, 실행 테스트 미진행
+  ✅ 7단계: DEVONagent 가이드       — 완료
+  ❌ 8단계: 전체 테스트            — 미진행
+  ✅ 추가:  PKM API 서버           — 기본 동작, 개선 필요
+
+[Phase 1.5: GPU 서버 재구성] ░░░░░░░░░░░░░░░░░░░░ 0% — 계획 완료, 실행 대기
+  → docs/gpu-restructure.md 참조
+  → GPU 모델 교체, Surya OCR, Komga 이전, Qdrant 통합, RAG 파이프라인
+
+[Phase 2: 인프라 + 버그 픽스] ░░░░░░░░░░░░░░░░░░░░ 0% — Phase 1.5와 병행 착수 대기
+  → docs/dev-roadmap.md 참조
+```
+
+## 알려진 이슈 (현재)
+
+```
+[P1 — 인프라]
+- 한국 법령 API: open.law.go.kr에 Mac mini 공인IP 등록 필요
+- MailPlus IMAP: 993 포트 Connection refused — Synology DSM에서 IMAP 활성화 확인
+- requirements.txt: flask 누락, chromadb→qdrant-client 교체, schedule 미사용
+- launchd: plist 파일은 있으나 실제 등록 여부 미확인
+- GPU 서버: 중복 LLM 모델 제거 + Surya OCR/Komga 이전 필요 → gpu-restructure.md
+
+[P2 — 코드 버그]
+- JP 번역: MLX thinking 출력이 번역 결과에 오염 ("Wait, I'll check...")
+- API 서버: /devonthink/stats → 500 에러, 한글 쿼리 인코딩 400 에러
+- AppleScript: 경로 하드코딩 + sourceChannel 이중 설정 버그 (73행)
+- embed_to_chroma.py: GPU_SERVER_IP 미설정으로 미작동 → Qdrant 리라이트 예정
+```

 ## 네트워크 환경

 ```
 Mac mini (운영 서버):
-  - Ollama: http://localhost:11434
+  - MLX 서버: http://localhost:8800/v1/chat/completions (Qwen3.5-35B-A3B)
+  - PKM API: http://127.0.0.1:9900 (Flask, GUI 세션 필수)
  - DEVONthink: 로컬 실행 중
  - OmniFocus: 로컬 실행 중

@@ -24,11 +71,12 @@ Synology NAS (DS1525+):
  - Tailscale IP: 100.101.79.37
  - 포트: 15001
  - WebDAV: webdav.hyungi.net/Document_Server/DEVONThink/
-  - MailPlus IMAP: mailplus.hyungi.net:993 (SSL)
+  - MailPlus IMAP: mailplus.hyungi.net:993 (SSL) ← 현재 연결 불가

-GPU 서버 (RTX 4070 Ti Super):
-  - 역할: 임베딩(nomic-embed-text), 비전(Qwen2.5-VL-7B), 리랭킹(bge-reranker)
-  - Tailscale IP: 별도 확인 필요
+GPU 서버 (RTX 4070 Ti Super, 192.168.1.186):
+  - 현재: Ollama(11434) + qwen3.5:9b + id-9b, Plex(32400)
+  - 계획: bge-m3(임베딩) + bge-reranker(리랭킹) + Surya OCR(:8400) + Komga(:25600)
+  - → docs/gpu-restructure.md 참조

 TKSafety: tksafety.technicalkorea.net (설정만, 나중에 활성화)
 ```
@@ -38,6 +86,7 @@ TKSafety: tksafety.technicalkorea.net (설정만, 나중에 활성화)
 - 위치: `~/.config/pkm/credentials.env`
 - 템플릿: `./credentials.env.example`
 - 스크립트에서 python-dotenv로 로딩
+- 필수 키: LAW_OC, MAILPLUS_HOST/PORT/USER/PASS, NAS_DOMAIN, GPU_SERVER_IP

 ## DEVONthink DB 구조 (13개)

@@ -80,46 +129,112 @@ manual       — 직접 추가                     → dataOrigin = work (기본

 ```
 Tier 1 (Mac mini, 상시):
-  mlx-community/Qwen3.5-35B-A3B-4bit — 태그 생성, 문서 분류, 요약
+  mlx-community/Qwen3.5-35B-A3B-4bit — 태그 생성, 문서 분류, 요약, JP 번역
  → http://localhost:8800/v1/chat/completions (OpenAI 호환 API)
  → MLX 서버로 실행 중 (Ollama 아님)
+  ※ thinking 모드 주의: /nothink 명시 또는 JSON 추출 후처리 필요

 Tier 2 (Claude API, 필요시):
  claude-sonnet — 복잡한 분석, 장문 처리
-  → CLAUDE_API_KEY 사용
+  → CLAUDE_API_KEY 사용 (아직 미연동)

-Tier 3 (GPU 서버, 특수):
-  nomic-embed-text  — 벡터 임베딩
-  Qwen2.5-VL-7B    — 이미지/도면 OCR
-  bge-reranker-v2-m3 — RAG 리랭킹
+Tier 3 (GPU 서버, 특수) — ※ 재구성 예정 (gpu-restructure.md 참조):
+  현재: qwen3.5:9b-q8_0, id-9b (제거 예정)
+  변경 후:
+    bge-m3           — 벡터 임베딩 (1024차원, Ollama)
+    bge-reranker-v2-m3 — RAG 리랭킹 (Ollama)
+    Surya OCR        — 이미지/스캔 문서 OCR (FastAPI, 포트 8400)
+```
+
+## 파일 구조 (현재)
+
+```
+./
+├── CLAUDE.md                       ← 이 파일 (Claude Code 작업 가이드)
+├── README.md                       ← 프로젝트 설명
+├── requirements.txt                ← Python 패키지 (flask 추가 필요!)
+├── .gitignore
+├── credentials.env.example         ← 인증 정보 템플릿
+├── scripts/
+│   ├── pkm_utils.py                ← 공통 유틸 (로깅, 인증, LLM, AppleScript)
+│   ├── law_monitor.py              ← 법령 모니터링 (한국+US/JP/EU)
+│   ├── mailplus_archive.py         ← MailPlus 이메일 수집
+│   ├── pkm_daily_digest.py         ← 일일 다이제스트 생성
+│   ├── pkm_api_server.py           ← REST API 서버 (Flask, 포트 9900)
+│   ├── embed_to_chroma.py          ← ChromaDB 벡터 임베딩 (→ embed_to_qdrant.py로 교체 예정)
+│   └── prompts/
+│       └── classify_document.txt   ← AI 분류 프롬프트 템플릿
+├── applescript/
+│   ├── auto_classify.scpt          ← Inbox 자동 분류 Smart Rule
+│   └── omnifocus_sync.scpt         ← OmniFocus 연동 Smart Rule
+├── launchd/
+│   ├── net.hyungi.pkm.law-monitor.plist
+│   ├── net.hyungi.pkm.mailplus.plist
+│   └── net.hyungi.pkm.daily-digest.plist
+├── data/
+│   ├── law_last_check.json         ← 법령 마지막 확인 시점
+│   └── laws/                       ← 수집된 법령 문서 (16건 수집 완료)
+├── logs/                           ← 실행 로그
+├── docs/
+│   ├── architecture.md             ← 시스템 아키텍처
+│   ├── industrial-safety-blueprint.md
+│   ├── claude-code-commands.md     ← 단계별 작업 지시서
+│   ├── deploy.md                   ← Mac mini 배포 가이드
+│   ├── devonagent-setup.md         ← DEVONagent 검색 세트 가이드
+│   ├── dev-roadmap.md              ← 개발 로드맵 (Phase 1.5~6)
+│   └── gpu-restructure.md          ← GPU 서버 재구성 상세 계획
+├── tests/
+│   └── test_classify.py            ← AI 분류 테스트 (5종 문서)
+└── venv/                           ← Python 가상환경
 ```

 ## 작업 순서

-docs/claude-code-commands.md의 단계를 순서대로 진행:
+### Phase 1 (완료): 초기 구축
+docs/claude-code-commands.md의 1~7단계 → 코드 작성 완료

-1. **프로젝트 구조** — README.md, deploy.md 작성 (구조는 이미 생성됨)
-2. **Ollama 테스트** — 분류 프롬프트 최적화 → scripts/prompts/에 저장
-3. **AppleScript** — auto_classify.scpt, omnifocus_sync.scpt
-4. **법령 모니터링** — scripts/law_monitor.py + launchd plist
-5. **이메일 수집** — scripts/mailplus_archive.py + launchd plist
-6. **Daily Digest** — scripts/pkm_daily_digest.py + launchd plist
-7. **DEVONagent 가이드** — docs/devonagent-setup.md (수동 설정 가이드)
-8. **테스트** — tests/ + docs/test-report.md
+### Phase 1.5 (계획 완료): GPU 서버 재구성
+docs/gpu-restructure.md 참조:
+1. GPU 모델 교체 (LLM 제거, bge-m3/reranker 설치)
+2. Docker + NFS + Komga 이전
+3. Surya OCR 설치
+4. PKM 코드 갱신 (Qdrant 통합, embed 스크립트, AppleScript)
+5. RAG 파이프라인 구축 (후순위)
+
+### Phase 2 (진행 중): 인프라 수정 + 버그 픽스
+docs/dev-roadmap.md 참조 (Phase 1.5와 병행):
+1. requirements.txt 수정 ← Phase 1.5와 합산 (qdrant-client, flask)
+2. 한국 법령 API IP 등록
+3. MailPlus IMAP 연결 수정
+4. JP 번역 thinking 오염 필터링
+5. API 서버 한글 인코딩 + stats 500 에러 수정
+6. AppleScript 하드코딩 경로 변수화 ← Phase 1.5와 합산
+7. launchd 등록 및 확인
+
+### Phase 3~4: API 서버 개선 + 테스트
+- gunicorn 전환 + launchd plist 추가
+- 엔드포인트 추가 (/law-monitor/status, /digest/latest)
+- 모듈별 + E2E 통합 테스트 → docs/test-report.md
+
+### Phase 5~6: 운영 안정화
+- 로그 로테이션, Synology Chat 알림, 문서 보완

 ## 코딩 규칙

- Python 3.11+ (Mac mini 기본)
+- Python 3.11+ (Mac mini 기본, 현재 3.14 확인됨)
 - 인증 정보는 반드시 credentials.env에서 로딩 (하드코딩 금지)
 - AppleScript는 DEVONthink/OmniFocus와 연동 (osascript로 호출)
 - 로그는 ~/Documents/code/DEVONThink_my\ server/logs/에 저장
 - launchd plist는 launchd/ 디렉토리에 생성, Mac mini에서 심볼릭 링크로 등록
+- LLM 호출 시 pkm_utils.llm_generate() 사용 (thinking 후처리 포함)
 - 한글 주석 사용

 ## 배포 방법

 ```
 MacBook Pro (개발) → Gitea push → Mac mini에서 git pull
+또는 Cowork 모드에서 직접 파일 수정 → git push
+
 Mac mini에서:
  cd ~/Documents/code/DEVONThink_my\ server/
  git pull
@@ -132,6 +247,8 @@ Mac mini에서:

 - credentials.env는 git에 올리지 않음 (.gitignore에 포함)
 - DEVONthink, OmniFocus는 Mac mini에서 GUI로 실행 중이어야 AppleScript 작동
- 법령 API (LAW_OC)는 승인 대기 중 — 스크립트만 만들고 실제 호출은 승인 후
+- PKM API 서버도 GUI 세션에서 실행 필수 (AppleScript 중계)
+- 법령 API (LAW_OC): 키 발급 완료, Mac mini 공인IP 등록 필요
 - TKSafety 연동은 설계만 완료, 구현은 나중에
 - GPU 서버 Tailscale IP는 별도 확인 후 credentials.env에 추가
+- MLX 서버 thinking 모드: 번역/분류 시 /nothink 프리픽스 또는 후처리 필수