diff --git a/CLAUDE.md b/CLAUDE.md index ca33844..51b4b90 100644 --- 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 프리픽스 또는 후처리 필수 diff --git a/README.md b/README.md index 4325e0b..9f71565 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,91 @@ # DEVONThink PKM System -Mac mini M4 Pro 기반 개인 지식관리 자동화 시스템 +Mac mini M4 Pro 기반 개인 지식관리(PKM) 자동화 시스템 -## 구성 요소 +## 시스템 구성 -- **DEVONthink 4** — 중앙 지식 허브 (13개 DB) -- **Ollama** — AI 자동 분류/태깅 (Qwen3.5-35B-A3B) -- **법령 모니터링** — 산업안전보건법 등 변경 추적 -- **일일 다이제스트** — PKM 전체 변화 요약 -- **OmniFocus 연동** — 액션 아이템 자동 생성 +``` +┌─────────────────── Mac mini M4 Pro (허브) ───────────────────┐ +│ │ +│ DEVONthink 4 ◄── DEVONagent Pro │ +│ (13개 DB) (자동 검색) │ +│ │ │ +│ ┌────┴─────── 자동화 레이어 ────────────────────────┐ │ +│ │ auto_classify.scpt 법령 모니터링 이메일 수집 │ │ +│ │ omnifocus_sync.scpt 일일 다이제스트 PKM API │ │ +│ └──────────────────────────────────────────────────┘ │ +│ │ │ +│ OmniFocus 4 MLX Qwen3.5-35B-A3B (AI 분류/번역) │ +│ (작업 관리) localhost:8800 │ +│ │ +└──────────────────────────┬─────────────────────────────────────┘ + │ Tailscale VPN + ┌────────────────┼────────────────┐ +┌─────────▼──────────┐ ┌────────────▼─────────────┐ +│ Synology DS1525+ │ │ GPU 서버 (RTX 4070 Ti S) │ +│ Gitea · MailPlus │ │ 임베딩 · OCR · 리랭킹 │ +│ WebDAV 동기화 │ │ Plex │ +└────────────────────┘ └──────────────────────────┘ +``` -## 설치 +## 핵심 기능 + +**AI 자동 분류** — DEVONthink Inbox에 들어온 문서를 MLX Qwen3.5가 분석하여 13개 DB 중 적합한 곳으로 자동 이동, 태그와 메타데이터를 자동 부여 + +**법령 모니터링** — 산업안전보건법, 중대재해처벌법 등 7개 한국 법령 + US OSHA, JP 厚労省, EU-OSHA 해외 법령 변경을 매일 자동 추적 + +**이메일 아카이브** — Synology MailPlus에서 IMAP으로 이메일을 수집하여 DEVONthink Archive DB에 자동 보관 + +**일일 다이제스트** — DEVONthink 변화, OmniFocus 진행 상황, 법령 변경 등을 종합한 일일 보고서 자동 생성 + +**OmniFocus 연동** — Projects DB의 TODO 패턴을 감지하여 OmniFocus에 작업 자동 생성, DEVONthink 역링크 포함 + +**REST API** — DEVONthink/OmniFocus 상태를 HTTP로 조회 (내부 모니터링용) + +## 디렉토리 구조 + +``` +scripts/ Python 스크립트 + pkm_utils.py 공통 유틸 (로깅, 인증, LLM 호출) + 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 벡터 임베딩 + prompts/ AI 프롬프트 템플릿 + +applescript/ DEVONthink/OmniFocus 연동 + auto_classify.scpt Inbox 자동 분류 Smart Rule + omnifocus_sync.scpt OmniFocus 작업 생성 Smart Rule + +launchd/ macOS 스케줄 실행 + net.hyungi.pkm.law-monitor.plist 매일 07:00 + net.hyungi.pkm.mailplus.plist 매일 07:00, 18:00 + net.hyungi.pkm.daily-digest.plist 매일 20:00 + +docs/ 문서 + architecture.md 시스템 아키텍처 + deploy.md 배포 가이드 + 트러블슈팅 + claude-code-commands.md 개발 작업 지시서 + dev-roadmap.md 개발 로드맵 + devonagent-setup.md DEVONagent 검색 세트 가이드 + industrial-safety-blueprint.md 산업안전 DB 설계 + +data/ 데이터 + laws/ 수집된 법령 문서 + law_last_check.json 마지막 확인 시점 + +tests/ 테스트 + test_classify.py AI 분류 정확도 테스트 +``` + +## 빠른 시작 ```bash # Mac mini에서 -git clone [gitea-repo-url] -cd DEVONThink_my\ server -python3 -m venv venv -source venv/bin/activate +git clone https://git.hyungi.net/hyungi/devonthink_home.git "DEVONThink_my server" +cd "DEVONThink_my server" +python3 -m venv venv && source venv/bin/activate pip install -r requirements.txt # 인증 정보 설정 @@ -29,12 +97,22 @@ chmod 600 ~/.config/pkm/credentials.env 자세한 배포 방법은 `docs/deploy.md` 참조 -## 디렉토리 구조 +## 실행 환경 + +| 구성 요소 | 요구사항 | +|-----------|---------| +| macOS | 14+ (Sonoma) | +| Python | 3.11+ | +| DEVONthink | 4.x, GUI 실행 중 | +| OmniFocus | 4.x, GUI 실행 중 | +| MLX 서버 | Qwen3.5-35B-A3B, localhost:8800 | +| Tailscale | NAS/GPU 서버 접근용 | + +## 개발 ``` -scripts/ Python 스크립트 (법령모니터, 메일수집, 다이제스트) -applescript/ DEVONthink/OmniFocus 연동 AppleScript -launchd/ macOS 스케줄 실행 plist -docs/ 설계 문서, 가이드 -tests/ 테스트 코드 +개발 흐름: +MacBook Pro (또는 Cowork) → git push → Gitea (NAS) → Mac mini에서 git pull ``` + +개발 현황과 다음 작업은 `docs/dev-roadmap.md` 참조 diff --git a/applescript/auto_classify.scpt b/applescript/auto_classify.scpt index 66a6e6e..057a977 100644 --- a/applescript/auto_classify.scpt +++ b/applescript/auto_classify.scpt @@ -70,7 +70,6 @@ except: add custom meta data sourceChannel for "sourceChannel" to theRecord add custom meta data dataOrigin for "dataOrigin" to theRecord add custom meta data (current date) for "lastAIProcess" to theRecord - add custom meta data "inbox_route" for "sourceChannel" to theRecord -- 7. 대상 도메인 DB로 이동 set targetDatabase to missing value @@ -89,7 +88,7 @@ except: -- 8. GPU 서버 벡터 임베딩 비동기 전송 set embedScript to (POSIX path of (path to home folder)) & "Documents/code/DEVONThink_my server/venv/bin/python3" - set embedPy to (POSIX path of (path to home folder)) & "Documents/code/DEVONThink_my server/scripts/embed_to_chroma.py" + set embedPy to (POSIX path of (path to home folder)) & "Documents/code/DEVONThink_my server/scripts/embed_to_qdrant.py" do shell script embedScript & " " & quoted form of embedPy & " " & quoted form of docUUID & " &> /dev/null &" on error errMsg diff --git a/credentials.env.example b/credentials.env.example index ee7ecb0..ac0633a 100644 --- a/credentials.env.example +++ b/credentials.env.example @@ -24,6 +24,9 @@ MAILPLUS_PASS= # ─── Synology Chat 웹훅 (나중에 추가) ─── #CHAT_WEBHOOK_URL= +# ─── GPU 서버 (임베딩/OCR) ─── +GPU_SERVER_IP=192.168.1.xxx + # ─── TKSafety API (나중에 활성화) ─── #TKSAFETY_HOST= #TKSAFETY_PORT= diff --git a/docs/claude-code-commands.md b/docs/claude-code-commands.md index c9a8b54..24f3b07 100644 --- a/docs/claude-code-commands.md +++ b/docs/claude-code-commands.md @@ -1,18 +1,19 @@ # Claude Code 실행 명령어 — PKM 시스템 구축 > 작업 위치: MacBook Pro ~/Documents/code/DEVONThink_my server/ -> Claude Code를 이 디렉토리에서 실행 +> 또는 Cowork 모드에서 마운트된 폴더 > 완성 후 Gitea에 push → Mac mini에서 pull ``` 개발/배포 흐름: -MacBook Pro (Claude Code) +MacBook Pro (Claude Code / Cowork) ~/Documents/code/DEVONThink_my server/ → 스크립트/설정 파일 작성 → git commit & push │ ▼ Gitea (Synology NAS) + https://git.hyungi.net/hyungi/devonthink_home.git │ ▼ Mac mini (git pull → 실행) @@ -20,272 +21,478 @@ MacBook Pro (Claude Code) --- -## 0단계: 프로젝트 구조 생성 + credentials.env 복사 +# Phase 1: 초기 구축 (완료) -Claude Code 실행 전에 먼저: +> 2026-03-26 ~ 03-27 작업. 총 15 커밋. + +## 0단계: 프로젝트 구조 생성 + credentials.env ✅ 완료 ```bash -# MacBook Pro에서 -cd ~/Documents/code/DEVONThink_my\ server/ - -# credentials.env를 프로젝트에 복사 (gitignore 필수!) -cp ~/.config/pkm/credentials.env ./credentials.env.example -# example은 값을 비운 템플릿용, 실제 파일은 Mac mini에서 직접 생성 - -# Mac mini에서 (SSH 접속 후) +# Mac mini에서 mkdir -p ~/.config/pkm nano ~/.config/pkm/credentials.env -# → 실제 인증 정보 입력 chmod 600 ~/.config/pkm/credentials.env ``` +## 1단계: 프로젝트 구조 + requirements.txt ✅ 완료 + +생성된 파일: README.md, requirements.txt, .gitignore, credentials.env.example, 전체 디렉토리 구조 + +## 2단계: AI 분류 프롬프트 ✅ 완료 + +- MLX 서버(localhost:8800) OpenAI 호환 API로 전환됨 +- Qwen3.5 thinking 모드 대응 완료 (JSON 추출 후처리) +- 프롬프트: scripts/prompts/classify_document.txt + +## 3단계: AppleScript ✅ 완료 + +- applescript/auto_classify.scpt — Inbox 자동 분류 +- applescript/omnifocus_sync.scpt — OmniFocus 작업 생성 + +## 4단계: 법령 모니터링 ⚠️ 부분 완료 + +- scripts/law_monitor.py 작성 완료 +- 외국 법령 (US OSHA 1건, JP 厚労省 10건, EU-OSHA 5건) 수집 성공 +- ❌ 한국 법령 API: IP 등록 미완 → Phase 2에서 해결 + +## 5단계: MailPlus 이메일 수집 ❌ 연결 실패 + +- scripts/mailplus_archive.py 코드 완성 +- ❌ IMAP 접속 실패 (Connection refused) → Phase 2에서 해결 + +## 6단계: Daily Digest ⚠️ 미테스트 + +- scripts/pkm_daily_digest.py 코드 완성 +- 실행 테스트 미진행 → Phase 2 이후 테스트 + +## 7단계: DEVONagent 가이드 ✅ 완료 + +- docs/devonagent-setup.md — 9개 검색 세트 설정 가이드 + +## 8단계: 전체 테스트 ❌ 미진행 + +- tests/test_classify.py 작성 완료 +- docs/test-report.md 미생성 → Phase 4에서 진행 + +## 추가: PKM API 서버 (계획 외 생성) + +- scripts/pkm_api_server.py — Flask REST API (포트 9900) +- DEVONthink + OmniFocus 상태 조회용 +- 기본 동작 확인됨, 버그 있음 → Phase 2에서 수정 + --- -## 1단계: 프로젝트 구조 + requirements.txt +# Phase 1.5: GPU 서버 재구성 (Phase 2와 병행) + +> 상세 계획: docs/gpu-restructure.md 참조 +> GPU 서버 SSH 작업 + PKM 프로젝트 코드 수정 + +## GPU-1단계: GPU 서버 Ollama 모델 교체 + +```bash +# GPU 서버에서 실행 (ssh 192.168.1.186) + +# 1. 기존 LLM 모델 제거 +ollama rm qwen3.5:9b-q8_0 +ollama rm id-9b + +# 2. 임베딩/리랭킹 모델 설치 +ollama pull bge-m3 +ollama pull bge-reranker-v2-m3 + +# 3. no-think proxy 비활성화 +sudo systemctl disable --now ollama-proxy + +# 4. Ollama systemd 환경 조정 +sudo systemctl edit ollama +# Environment="OLLAMA_MAX_LOADED_MODELS=2" +# Environment="OLLAMA_KEEP_ALIVE=30m" +sudo systemctl daemon-reload && sudo systemctl restart ollama + +# 5. 검증 +ollama list # → bge-m3, bge-reranker만 존재 +curl localhost:11434/api/embed -d '{"model":"bge-m3","input":["테스트"]}' # → 1024차원 벡터 +``` + +## GPU-2단계: tk-ai-service 코드 수정 (Mac Mini) ``` -이 프로젝트의 디렉토리 구조를 만들고 기본 설정 파일들을 생성해줘. -작업 디렉토리: 현재 디렉토리 (~/Documents/code/DEVONThink_my server/) +tk-ai-service의 ollama_client.py를 OpenAI API 호환으로 리팩터링해줘. -프로젝트 구조: -./ -├── README.md ← 프로젝트 설명 -├── requirements.txt ← Python 패키지 목록 -├── .gitignore ← credentials.env, venv, logs, __pycache__ 등 제외 -├── credentials.env.example ← 인증 정보 템플릿 (값은 비움) -├── scripts/ -│ ├── law_monitor.py -│ ├── mailplus_archive.py -│ ├── pkm_daily_digest.py -│ ├── embed_to_chroma.py -│ └── prompts/ -│ └── classify_document.txt -├── applescript/ -│ ├── auto_classify.scpt -│ └── omnifocus_sync.scpt -├── launchd/ -│ ├── net.hyungi.pkm.law-monitor.plist -│ ├── net.hyungi.pkm.mailplus.plist -│ └── net.hyungi.pkm.daily-digest.plist -├── docs/ -│ ├── devonagent-setup.md -│ └── deploy.md ← Mac mini 배포 방법 -└── tests/ - └── test_classify.py +변경 대상: + ~/docker/tk-factory-services/ai-service/services/ollama_client.py + → generate_text(): /api/chat → /v1/chat/completions + → check_health(): /api/tags → /v1/models + → generate_embedding(): 변경 없음 (GPU Ollama 유지) -requirements.txt에 넣을 패키지: -- chromadb -- requests -- python-dotenv -- schedule -- markdown +docker-compose.yml 환경변수: + OLLAMA_BASE_URL=http://host.internal:8800 (MLX) + OLLAMA_TEXT_MODEL=mlx-community/Qwen3.5-35B-A3B-4bit + OLLAMA_EMBED_URL=http://192.168.1.186:11434 (GPU) -.gitignore에 반드시 포함: -- credentials.env -- venv/ -- logs/ -- __pycache__/ -- *.pyc -- .DS_Store +검증: docker compose build && docker compose up -d + curl http://localhost:30400/health → 모두 connected +``` -deploy.md에는 Mac mini에서의 설치 절차 작성: -1. git pull -2. python3 -m venv venv && source venv/bin/activate -3. pip install -r requirements.txt -4. credentials.env는 ~/.config/pkm/credentials.env에 별도 관리 -5. launchd plist 심볼릭 링크 등록 방법 +## GPU-3단계: Docker + NFS + Komga 이전 -네트워크 환경: -- NAS 도메인: ds1525.hyungi.net (Tailscale: 100.101.79.37, 포트: 15001) -- MailPlus: mailplus.hyungi.net:993 (IMAP SSL) -- WebDAV: webdav.hyungi.net/Document_Server/DEVONThink/ -- TKSafety: tksafety.technicalkorea.net (나중에 활성화) +```bash +# GPU 서버에서 실행 (ssh 192.168.1.186) + +# 1. Docker 설치 +sudo apt-get update +sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin +sudo usermod -aG docker hyungi + +# 2. NFS 마운트 +sudo apt install nfs-common +sudo mkdir -p /mnt/comic +echo '192.168.1.227:/volume1/Comic /mnt/comic nfs4 ro,nosuid,noexec,nodev,soft,timeo=15 0 0' | sudo tee -a /etc/fstab +sudo mount -a +ls /mnt/comic # 확인 + +# 3. Komga 컨테이너 시작 +sudo mkdir -p /opt/komga && cd /opt/komga +# docker-compose.yml 생성 (gpu-restructure.md Phase 1.5-3 참조) +docker compose up -d + +# Mac Mini에서: +docker stop komga && docker rm komga +# nginx-ssl.conf: komga_backend upstream → 192.168.1.186:25600 +docker restart home-service-proxy + +# 검증 +curl https://komga.hyungi.net # → GPU 서버 경유 접근 +``` + +## GPU-4단계: Surya OCR 설치 + +```bash +# GPU 서버에서 실행 (ssh 192.168.1.186) + +# 1. PyTorch CUDA 확인 +python3 -c "import torch; print(torch.cuda.is_available())" +# False면: pip install torch --index-url https://download.pytorch.org/whl/cu124 + +# 2. Surya OCR 설치 +sudo mkdir -p /opt/surya-ocr && cd /opt/surya-ocr +python3 -m venv venv +source venv/bin/activate +pip install surya-ocr fastapi uvicorn python-multipart + +# 3. server.py 작성 (FastAPI 래퍼, gpu-restructure.md Phase 2-2 참조) + +# 4. systemd 등록 +# /etc/systemd/system/surya-ocr.service (gpu-restructure.md Phase 2-3 참조) +sudo systemctl daemon-reload +sudo systemctl enable --now surya-ocr + +# 검증 +curl -F "file=@test.pdf" http://localhost:8400/ocr +``` + +## GPU-5단계: Qdrant 통합 + PKM 코드 갱신 + +``` +PKM 프로젝트 코드를 GPU 서버 재구성에 맞게 갱신해줘. + +1. scripts/embed_to_chroma.py → scripts/embed_to_qdrant.py 리라이트 + - chromadb → qdrant-client + - nomic-embed-text → bge-m3 (GPU 서버 192.168.1.186:11434) + - /api/embed 사용 (배치 지원) + - 텍스트 청킹 (500토큰, 50오버랩) + - 기존 embed_to_chroma.py는 git rm + +2. applescript/auto_classify.scpt 수정 + - Step 0: OCR 감지 + Surya OCR 호출 추가 + - Step 4: embed_to_qdrant.py 호출로 변경 + - 버그 픽스: 73행 sourceChannel 이중 설정 삭제 + - baseDir 변수 사용 (12단계와 합산) + +3. requirements.txt 업데이트 (9단계와 합산) + - chromadb, schedule 제거 + + qdrant-client, flask, gunicorn 추가 + +4. credentials.env.example: GPU_SERVER_IP 추가 +5. Qdrant에 pkm_documents 컬렉션 생성 (1024차원, cosine) + +검증: python3 scripts/embed_to_qdrant.py <테스트UUID> → Qdrant 벡터 저장 +``` + +## GPU-6단계: architecture.md 대규모 갱신 + +``` +docs/architecture.md를 GPU 서버 재구성에 맞게 전체 갱신해줘. + +변경 규모: ChromaDB 28건, nomic-embed 12건, VL-7B 5건 — 문맥별 수정 필요 + +주요 변경: +- Tier 3 모델: nomic-embed-text → bge-m3, Qwen2.5-VL-7B → Surya OCR +- 벡터 DB: ChromaDB → Qdrant (모든 언급) +- VRAM 다이어그램: ~11.3GB → ~7-8GB +- Smart Rule 설계: embed_to_chroma → embed_to_qdrant, OCR 단계 추가 +- 3-Tier AI 라우팅 전략 표 갱신 +- 코드 예시 내 경로/모델명 + +※ 단순 치환 불가, 전체 문서를 통독하며 문맥에 맞게 수정할 것 +※ 별도 커밋으로 분리 +``` + +## GPU-7단계: RAG 파이프라인 구축 (후순위) + +``` +pkm_api_server.py에 RAG 엔드포인트를 추가해줘. + +추가 엔드포인트: + POST /rag/query — 질문 → bge-m3 임베딩 → Qdrant 검색 → 리랭킹 → MLX 답변 + POST /devonthink/embed — 단일 문서 임베딩 트리거 + POST /devonthink/embed-batch — 배치 임베딩 + +docstring 갱신: "범위: DEVONthink + OmniFocus + RAG 검색" + +scripts/ocr_preprocess.py 신규 작성: + DEVONthink UUID → AppleScript로 파일 경로 추출 → Surya API(GPU:8400) 호출 + +검증: curl -X POST localhost:9900/rag/query -d '{"q":"산업안전 법령"}' ``` --- -## 2단계: Ollama 모델 확인 + 분류 프롬프트 테스트 +# Phase 2: 인프라 수정 + 버그 픽스 (Phase 1.5와 병행) + +> dev-roadmap.md Phase 2~3 해당 +> ※ requirements.txt, AppleScript 경로, credentials.env는 GPU-5단계와 합산 진행 + +## 9단계: requirements.txt 수정 ← GPU-5단계와 합산 ``` -Ollama가 정상 동작하는지 확인하고, PKM 문서 분류용 프롬프트를 테스트해줘. +requirements.txt에 flask가 빠져있어. pkm_api_server.py에서 사용 중이니까 추가해줘. +GPU 서버 재구성에 따라 chromadb→qdrant-client 교체도 함께 진행. +gunicorn도 추가해 (프로덕션 WSGI 서버용). +schedule 패키지는 현재 미사용 — 제거할지 유지할지 판단해줘. +anthropic 패키지는 향후 Tier 2 연동용이니 유지. -1. ollama list로 현재 모델 확인 -2. qwen3.5:35b-a3b 계열 모델이 있는지 확인 (없으면 알려줘) -3. 테스트 프롬프트 실행 — 아래 내용으로 분류 테스트: +수정할 파일: requirements.txt -테스트 문서: "산업안전보건법 시행규칙 일부개정령안 입법예고 - 고용노동부는 위험성평가에 관한 지침을 개정하여..." +추가: ++ flask>=3.0.0 ++ gunicorn>=21.2.0 -기대 응답 JSON: -{ - "tags": ["위험성평가", "법령개정", "고용노동부"], - "domain_db": "04_Industrial safety", - "sub_group": "10_Legislation/Notice", - "sourceChannel": "inbox_route", - "dataOrigin": "external" -} +확인: +- schedule>=1.2.0 → 사용처 없으면 제거 +``` -도메인 DB 선택지: -00_Note_BOX, 01_Philosophie, 02_Language, 03_Engineering, -04_Industrial safety, 05_Programming, 07_General Book, -97_Production drawing, 99_Reference Data, 99_Technicalkorea +## 10단계: JP 번역 thinking 오염 수정 -sourceChannel 값: tksafety, devonagent, law_monitor, inbox_route, email, web_clip, manual -dataOrigin 값: work (자사 업무), external (외부 참고) +``` +법령 모니터링에서 일본어 번역 시 MLX Qwen3.5의 thinking 출력이 결과에 섞이는 문제를 수정해줘. -프롬프트를 최적화해서 ~/Documents/code/DEVONThink_my server/scripts/prompts/ 디렉토리에 저장해줘. +현재 문제: +로그에서 "Wait, I'll check if..." 같은 thinking 텍스트가 번역 결과에 포함됨. + +위치: scripts/law_monitor.py의 JP 번역 호출부 + +수정 방향: +1. 번역 프롬프트에 /nothink 모드 명시 강화 +2. llm_generate() 응답에서 thinking 패턴 필터링 추가 + - "Wait,", "Let me", "I'll check", "Hmm," 등으로 시작하는 줄 제거 + - "Final Output:" 이후 텍스트만 추출하는 로직 +3. 또는 pkm_utils.py의 llm_generate()에 strip_thinking=True 옵션 추가 + +테스트: JP RSS 항목 하나로 번역 테스트하여 깨끗한 한글 출력 확인 +``` + +## 11단계: API 서버 버그 수정 + +``` +PKM API 서버의 두 가지 버그를 수정해줘. + +위치: scripts/pkm_api_server.py + +버그 1: /devonthink/stats → 500 Internal Server Error +- AppleScript 쿼리가 실패하는 것으로 추정 +- 에러 로그 확인: logs/pkm-api.error.log +- AppleScript에서 DB 이름이나 property 접근 방식 수정 필요 + +버그 2: 한글 쿼리 파라미터 인코딩 에러 +- /devonthink/search?q=산업안전 → 400 Bad request syntax +- Flask의 request.args는 UTF-8을 지원하므로, 클라이언트 측 문제일 가능성 +- 서버 측에서도 방어 코드 추가: URL 디코딩 처리 + +추가 개선: +- /omnifocus/overdue 엔드포인트가 404였다가 나중에 추가됨 — 코드 확인 +- / (루트) 접근 시 404 → /health로 리다이렉트 또는 엔드포인트 목록 반환 +``` + +## 12단계: AppleScript 경로 변수화 ← GPU-5단계와 합산 + +``` +AppleScript 파일들의 하드코딩된 경로를 변수로 교체해줘. +GPU-5단계의 embed_to_qdrant.py 변경, OCR 단계 추가, sourceChannel 버그 픽스도 함께 진행. + +현재 하드코딩: + ~/Documents/code/DEVONThink_my server/scripts/prompts/classify_document.txt + ~/Documents/code/DEVONThink_my server/venv/bin/python3 + ~/Documents/code/DEVONThink_my server/scripts/embed_to_chroma.py + +수정 대상: + applescript/auto_classify.scpt + applescript/omnifocus_sync.scpt + +수정 방향: +- 스크립트 상단에 property baseDir 정의 +- 모든 경로를 baseDir 기반으로 조합 +- 또는 환경변수 PKM_HOME을 읽어서 사용 + +※ AppleScript에서 환경변수 읽기: + set pkmHome to do shell script "echo $PKM_HOME" + 또는 property로 직접 지정하는 게 안정적 ``` --- -## 3단계: DEVONthink Smart Rule + AppleScript 배포 +# Phase 3: API 서버 개선 + +## 13단계: gunicorn 전환 + launchd 등록 ``` -DEVONthink 4 Smart Rule용 AppleScript 모듈들을 만들어줘. -Mac mini에서 DEVONthink가 실행 중이야. +PKM API 서버를 Flask development server에서 gunicorn으로 전환하고, +launchd plist를 만들어 Mac mini 로그인 시 자동 시작되도록 해줘. -모듈 A: Ollama 연동 자동 분류 (~/Documents/code/DEVONThink_my server/applescript/auto_classify.scpt) -- DEVONthink Inbox DB에 새 문서가 들어오면 실행 -- Ollama qwen3.5 35B에 문서 텍스트 전송 -- 응답에서 tags, domain_db, sub_group, sourceChannel, dataOrigin 파싱 -- DEVONthink 태그 설정 + 커스텀 메타데이터(sourceChannel, dataOrigin, lastAIProcess) 설정 -- 해당 도메인 DB의 하위 그룹으로 문서 이동 -- GPU 서버(Tailscale IP)로 벡터 임베딩 비동기 전송 +1. gunicorn 설정: + gunicorn -w 2 -b 127.0.0.1:9900 pkm_api_server:app + ※ AppleScript 실행 때문에 GUI 세션에서 실행해야 함 + ※ launchd의 LimitLoadToSessionType = Aqua 또는 LoginwindowUI -모듈 B: OmniFocus 연동 (~/Documents/code/DEVONThink_my server/applescript/omnifocus_sync.scpt) -- Projects DB에 새 문서 추가 시 TODO 패턴 감지 -- OmniFocus에 작업 생성 (DEVONthink 링크 포함) -- 커스텀 메타데이터에 omnifocusTaskID 저장 +2. launchd plist 생성: + launchd/net.hyungi.pkm.api-server.plist + - 로그인 시 자동 시작 + - KeepAlive: true (크래시 시 재시작) + - WorkingDirectory: ~/Documents/code/DEVONThink_my server/ + - StandardOutPath/StandardErrorPath: logs/pkm-api.log, logs/pkm-api.error.log -프롬프트 파일 위치: ~/Documents/code/DEVONThink_my server/scripts/prompts/ -인증 정보: ~/.config/pkm/credentials.env -GPU 서버 Tailscale IP는 별도 확인 필요 (나중에 추가) +3. deploy.md에 API 서버 관련 내용 추가 +``` + +## 14단계: API 엔드포인트 추가 + +``` +PKM API 서버에 모니터링/상태 확인용 엔드포인트를 추가해줘. + +추가할 엔드포인트: +1. GET /law-monitor/status + - data/law_last_check.json 읽어서 마지막 확인 시간 반환 + - logs/law_monitor.log 최근 에러 건수 + +2. GET /digest/latest + - DEVONthink 00_Note_BOX/Daily_Digest/에서 최신 다이제스트 조회 + - 또는 data/ 아래에 최근 다이제스트 캐시 + +3. GET / → 전체 엔드포인트 목록 반환 (현재 404) + +4. GET /health 확장 + - MLX 서버 상태 (localhost:8800 연결 가능 여부) + - DEVONthink 실행 상태 + - 각 launchd job 상태 ``` --- -## 4단계: 법령 모니터링 스크립트 +# Phase 4: 테스트 + +## 15단계: 모듈별 테스트 실행 ``` -한국 법령 변경 모니터링 스크립트를 만들어줘. +Mac mini에서 각 모듈의 동작을 확인해줘. -스크립트: ~/Documents/code/DEVONThink_my server/scripts/law_monitor.py -인증: ~/.config/pkm/credentials.env의 LAW_OC 값 사용 -API: open.law.go.kr OpenAPI +1. AI 분류 테스트 (tests/test_classify.py) + cd ~/Documents/code/DEVONThink_my\ server/ + source venv/bin/activate + python tests/test_classify.py + → 5종 문서 분류 정확도 확인 -기능: -1. 산업안전보건법, 중대재해처벌법, 관련 시행령/시행규칙/고시 변경 추적 -2. 변경 감지 시: - - 법령 본문(XML) 다운로드 → ~/Documents/code/DEVONThink_my server/data/laws/에 저장 - - DEVONthink 04_Industrial Safety/10_Legislation/ 하위에 자동 임포트 (AppleScript 호출) - - 커스텀 메타데이터: sourceChannel=law_monitor, dataOrigin=external - - 로그: ~/Documents/code/DEVONThink_my server/logs/law_monitor.log -3. launchd plist 생성: 매일 07:00 실행 - ~/Documents/code/DEVONThink_my server/launchd/net.hyungi.pkm.law-monitor.plist - → ~/Library/LaunchAgents/에 심볼릭 링크 +2. 법령 모니터링 (Phase 2 인프라 수정 후) + python scripts/law_monitor.py + → 한국 법령 API 정상 응답 확인 + → 외국 법령 수집 재확인 -※ 법령 API 승인 대기중이라 스크립트만 만들고 실제 테스트는 승인 후에 -※ 해외 법령(US OSHA, JP, EU)은 나중에 추가 예정 +3. MailPlus 이메일 수집 (Phase 2 연결 수정 후) + python scripts/mailplus_archive.py + → IMAP 접속 + 이메일 가져오기 확인 + +4. Daily Digest + python scripts/pkm_daily_digest.py + → 다이제스트 MD 파일 생성 확인 + +5. API 서버 (Phase 2 버그 수정 후) + python scripts/pkm_api_server.py & + curl http://localhost:9900/health + curl http://localhost:9900/devonthink/stats + curl http://localhost:9900/devonthink/inbox-count + curl "http://localhost:9900/devonthink/search?q=safety&limit=3" + curl http://localhost:9900/omnifocus/stats +``` + +## 16단계: E2E 통합 테스트 + +``` +PKM 시스템 End-to-End 테스트를 진행해줘. + +시나리오 1: Inbox → 자동분류 플로우 + 1. DEVONthink Inbox에 테스트 문서 추가 + 2. Smart Rule 트리거 → auto_classify.scpt 실행 확인 + 3. 태그, 커스텀 메타데이터(sourceChannel, dataOrigin, lastAIProcess) 확인 + 4. 올바른 도메인 DB + 하위 그룹으로 이동 확인 + +시나리오 2: 법령 → 다이제스트 플로우 + 1. law_monitor.py 수동 실행 + 2. data/laws/에 파일 생성 + DEVONthink 04_Industrial Safety 임포트 확인 + 3. pkm_daily_digest.py 실행 → 법령 변경 건 포함 확인 + +시나리오 3: OmniFocus 연동 + 1. Projects DB에 TODO 패턴 문서 추가 + 2. omnifocus_sync.scpt 트리거 확인 + 3. OmniFocus Inbox에 작업 생성 + DEVONthink 링크 확인 + 4. 커스텀 메타데이터 omnifocusTaskID 확인 + +시나리오 4: launchd 스케줄 확인 + launchctl list | grep pkm + → 3개(+API 서버) 등록 확인 + +각 항목 pass/fail 리포트 → docs/test-report.md ``` --- -## 5단계: MailPlus → DEVONthink 이메일 수집 +# Phase 5: 운영 안정화 (나중에) + +## 17단계: 로그 로테이션 + 알림 ``` -MailPlus 이메일을 DEVONthink Archive DB로 자동 수집하는 스크립트를 만들어줘. +운영 안정성을 위한 설정을 추가해줘. -스크립트: ~/Documents/code/DEVONThink_my server/scripts/mailplus_archive.py -인증: ~/.config/pkm/credentials.env +1. Python 로그 로테이션 + - pkm_utils.py의 setup_logger()에 RotatingFileHandler 적용 + - maxBytes=10MB, backupCount=5 -접속 정보: -- IMAP 서버: mailplus.hyungi.net:993 (SSL) -- 계정: hyungi +2. Synology Chat 알림 (CHAT_WEBHOOK_URL 설정 후) + - 법령 변경 감지 시 알림 + - 에러 발생 시 알림 + - Daily Digest 요약 알림 -기능: -1. IMAP으로 MailPlus 접속 -2. 마지막 동기화 이후 새 메일 가져오기 -3. DEVONthink Archive DB에 임포트 (AppleScript 호출) -4. 커스텀 메타데이터: sourceChannel=email -5. 안전 관련 키워드 감지 시 dataOrigin 자동 판별 - -launchd: 매일 07:00 + 18:00 실행 -~/Documents/code/DEVONThink_my server/launchd/net.hyungi.pkm.mailplus.plist +3. 에러 모니터링 + - pkm_daily_digest.py에 이미 에러 카운트 로직 있음 + - 임계값 초과 시 Chat 알림 추가 ``` ---- - -## 6단계: Daily Digest 시스템 +## 18단계: 문서 보완 ``` -PKM 일일 다이제스트를 자동 생성하는 스크립트를 만들어줘. +프로젝트 문서를 보완해줘. -스크립트: ~/Documents/code/DEVONThink_my server/scripts/pkm_daily_digest.py -인증: ~/.config/pkm/credentials.env - -기능: -1. DEVONthink에서 오늘 추가/수정된 문서 집계 (AppleScript로 쿼리) - - DB별 신규 건수 - - sourceChannel별 구분 -2. law_monitor 로그에서 법령 변경 건 파싱 -3. OmniFocus 오늘 완료/추가/기한초과 집계 (AppleScript) -4. 상위 뉴스 3건 요약 (Ollama 35B 호출) -5. MD 파일 생성 → DEVONthink 00_Note_BOX/Daily_Digest/에 저장 - 파일명: YYYY-MM-DD_digest.md -6. OmniFocus 액션 자동 생성 (법령변경, overdue, Inbox 미처리 등) -7. 90일 지난 다이제스트 → 90_Archive 이동 (Smart Rule 대체) - -launchd: 매일 20:00 실행 -~/Documents/code/DEVONThink_my server/launchd/net.hyungi.pkm.daily-digest.plist - -※ Synology Chat 웹훅 알림은 나중에 추가 (CHAT_WEBHOOK_URL 설정 후) -``` - ---- - -## 7단계: DEVONagent 검색 세트 (수동 가이드) - -``` -DEVONagent Pro에서 안전 분야 자동 검색 세트를 설정하는 가이드를 만들어줘. - -총 9개 검색 세트 (7 안전 + 2 기술): -1. 국내 산업안전 뉴스 (kosha, moel, safetynews 등) -2. 국내 중대재해 뉴스 -3. KOSHA 가이드/지침 -4. 국내 산업안전 학술/논문 -5. US OSHA / Safety+Health Magazine -6. JP 厚生労働省 / 安全衛生 -7. EU-OSHA -8. 기술 뉴스 (AI/서버/네트워크) -9. 프로그래밍 기술 동향 - -각 세트별로: -- 검색 키워드/연산자 -- 사이트 제한 -- 스케줄 (매일/주간) -- 수량 제한 (주간 합계 50~85건 수준) -- 결과 → DEVONthink Inbox로 전송 설정 방법 - -이건 DEVONagent GUI에서 수동 설정해야 하니까, -단계별 가이드 문서를 ~/Documents/code/DEVONThink_my server/docs/devonagent-setup.md로 만들어줘. -``` - ---- - -## 8단계: 전체 테스트 - -``` -PKM 시스템 전체 End-to-End 테스트를 진행해줘. - -테스트 항목: -1. Ollama 분류 테스트 — 5종 문서(법령, 뉴스, 논문, 메모, 이메일) 분류 정확도 -2. DEVONthink Smart Rule — Inbox에 테스트 문서 추가 → 자동 분류 확인 -3. sourceChannel/dataOrigin 메타데이터가 정상 설정되는지 -4. OmniFocus 연동 — TODO 패턴 문서 → 작업 자동 생성 -5. MailPlus IMAP 접속 테스트 -6. launchd 스케줄 등록 확인 (launchctl list | grep pkm) -7. Daily Digest 수동 실행 테스트 - -각 항목 pass/fail 리포트를 ~/Documents/code/DEVONThink_my server/docs/test-report.md로 저장해줘. +1. README.md — 아키텍처 다이어그램, 기능 목록, 시작 가이드 확장 +2. deploy.md — API 서버 배포, 트러블슈팅 섹션, macOS 요구사항 추가 +3. docs/troubleshooting.md — 자주 발생하는 문제와 해결 방법 ``` --- @@ -295,8 +502,29 @@ PKM 시스템 전체 End-to-End 테스트를 진행해줘. ``` Mac mini 접속: SSH (MacBook Pro → Mac mini) NAS 도메인: ds1525.hyungi.net (Tailscale: 100.101.79.37, 포트: 15001) -MailPlus: mailplus.hyungi.net:993 (IMAP SSL) +MailPlus: mailplus.hyungi.net:993 (IMAP SSL) ← 현재 연결 불가, 확인 필요 WebDAV: webdav.hyungi.net/Document_Server/DEVONThink/ TKSafety: tksafety.technicalkorea.net (나중에 활성화) 내부 네트워크: Tailscale VPN 연결됨 +Gitea: https://git.hyungi.net/hyungi/devonthink_home.git +``` + +## 참고: Git 커밋 히스토리 + +``` +3506214 fix(law_monitor): US 타입 필터 제거 + JP RDF 네임스페이스 수정 +c8e30b5 fix: AppleScript POSIX path 변수 방식 + 단일 -e 실행으로 따옴표 문제 해결 +f13b998 fix: AppleScript 행별 -e 분할 실행 — 파일 방식 인코딩 문제 회피 +735c072 fix: AppleScript를 임시 파일로 실행 — osascript -e 이스케이프 문제 해결 +446963c fix(law_monitor): AppleScript f-string 제거 + EU 파일명 고유화 +0b950a4 fix(law_monitor): AppleScript 따옴표 이스케이프 수정 +6a44b10 fix(law_monitor): JP/EU RSS URL 수정 — news.rdf + rss.xml, RDF 네임스페이스 대응 +9dc0694 feat(law_monitor): 외국 법령 지원 추가 — US OSHA, JP 厚労省(MLX 번역), EU-OSHA +ec6074d fix(law_monitor): API 에러 응답 로깅 추가 — 인증 실패 시 조용히 넘어가던 문제 +aca4a02 fix: LLM thinking 허용 + 마지막 유효 JSON 추출 방식으로 변경 +49c39a1 fix: LLM thinking 출력 대응 — max_tokens 증가 + JSON 추출 강화 +948be16 fix: Qwen3.5 /nothink 모드 + json_mode 파라미터 추가 +a774771 fix: MLX 서버(localhost:8800) 대응 — Ollama API → OpenAI 호환 변경 +084d3a8 feat: 전체 PKM 스크립트 일괄 작성 — 분류/법령/메일/다이제스트/임베딩 +bec9579 chore: 프로젝트 구조 + 설계 문서 초기 커밋 ``` diff --git a/docs/deploy.md b/docs/deploy.md index beeac4e..c0e65c1 100644 --- a/docs/deploy.md +++ b/docs/deploy.md @@ -1,5 +1,17 @@ # Mac mini 배포 가이드 +> 마지막 업데이트: 2026-03-29 +> 대상: Mac mini M4 Pro (macOS, Python 3.11+) + +## 요구사항 + +- macOS 14+ (Sonoma 이상) +- Python 3.11+ (Homebrew 설치 권장) +- DEVONthink 4 — 실행 중이어야 AppleScript 동작 +- OmniFocus 4 — 실행 중이어야 AppleScript 동작 +- MLX 서버 — Qwen3.5-35B-A3B, localhost:8800에서 실행 중 +- Tailscale — NAS 및 GPU 서버 접근용 + ## 1. 초기 설치 ```bash @@ -22,9 +34,44 @@ nano ~/.config/pkm/credentials.env chmod 600 ~/.config/pkm/credentials.env ``` -credentials.env.example을 참고하여 실제 값 입력. +credentials.env.example을 참고하여 실제 값 입력: -## 3. launchd 스케줄 등록 +``` +# 필수 +LAW_OC=<법령API키> +MAILPLUS_HOST=mailplus.hyungi.net +MAILPLUS_PORT=993 +MAILPLUS_USER=hyungi +MAILPLUS_PASS=<비밀번호> +NAS_DOMAIN=ds1525.hyungi.net +NAS_TAILSCALE_IP=100.101.79.37 +NAS_PORT=15001 + +# 선택 (향후) +CLAUDE_API_KEY=<키> +#CHAT_WEBHOOK_URL= +#GPU_SERVER_IP= +``` + +## 3. 한국 법령 API IP 등록 + +법령 API 호출 전에 Mac mini의 공인 IP를 등록해야 합니다. + +```bash +# Mac mini에서 공인 IP 확인 +curl -s ifconfig.me + +# open.law.go.kr → 로그인 → 마이페이지 → 인증키 관리 +# 위에서 확인한 IP를 서버 IP로 등록 +# ※ Tailscale IP(100.x.x.x)가 아니라 실제 공인 IP + +# 등록 후 테스트 +source venv/bin/activate +python scripts/law_monitor.py +# → "법령 API 에러" 없이 정상 동작 확인 +``` + +## 4. launchd 스케줄 등록 ```bash # 심볼릭 링크 생성 @@ -41,7 +88,38 @@ launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.daily-digest.plist launchctl list | grep pkm ``` -## 4. 수동 테스트 +## 5. PKM API 서버 실행 + +```bash +# 개발 모드 (수동 실행) +cd ~/Documents/code/DEVONThink_my\ server/ +source venv/bin/activate +python scripts/pkm_api_server.py + +# 프로덕션 모드 (gunicorn, Phase 3 이후) +# gunicorn -w 2 -b 127.0.0.1:9900 scripts.pkm_api_server:app + +# 동작 확인 +curl http://localhost:9900/health +curl http://localhost:9900/devonthink/inbox-count +``` + +API 서버는 GUI 세션에서 실행해야 합니다 (AppleScript가 DEVONthink/OmniFocus GUI에 접근). + +## 6. DEVONthink Smart Rule 설정 + +1. DEVONthink → Preferences → Smart Rules +2. 새 Rule: **"AI Auto Classify"** + - Event: On Import + - Database: Inbox + - Condition: Tags is empty + - Action: Execute Script → External → `applescript/auto_classify.scpt` +3. 새 Rule: **"OmniFocus Sync"** + - Event: On Import + - Database: Projects + - Action: Execute Script → External → `applescript/omnifocus_sync.scpt` + +## 7. 수동 테스트 ```bash cd ~/Documents/code/DEVONThink_my\ server/ @@ -51,31 +129,26 @@ source venv/bin/activate python3 scripts/law_monitor.py python3 scripts/mailplus_archive.py python3 scripts/pkm_daily_digest.py + +# AI 분류 테스트 +python3 tests/test_classify.py ``` -## 5. DEVONthink Smart Rule 설정 - -1. DEVONthink → Preferences → Smart Rules -2. 새 Rule: "AI Auto Classify" - - Event: On Import - - Database: Inbox - - Condition: Tags is empty - - Action: Execute Script → External → `applescript/auto_classify.scpt` -3. 새 Rule: "OmniFocus Sync" - - Event: On Import - - Database: Projects - - Action: Execute Script → External → `applescript/omnifocus_sync.scpt` - -## 6. 업데이트 +## 8. 업데이트 ```bash cd ~/Documents/code/DEVONThink_my\ server/ git pull source venv/bin/activate pip install -r requirements.txt + +# launchd 재로드 (plist가 변경된 경우만) +launchctl unload ~/Library/LaunchAgents/net.hyungi.pkm.law-monitor.plist +launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.law-monitor.plist +# (나머지도 동일) ``` -## 7. 로그 확인 +## 9. 로그 확인 ```bash # 스크립트 로그 @@ -83,14 +156,94 @@ tail -f logs/law_monitor.log tail -f logs/mailplus.log tail -f logs/digest.log -# launchd 로그 -tail -f logs/law_monitor_launchd.log +# API 서버 로그 +tail -f logs/pkm-api.log +tail -f logs/pkm-api.error.log + +# launchd 시스템 로그 +log show --predicate 'process == "python3"' --last 1h +``` + +## 10. 일일 운영 점검 + +```bash +# 1. launchd 작업 상태 +launchctl list | grep pkm + +# 2. 오늘의 로그 에러 확인 +grep -c ERROR logs/law_monitor.log +grep -c ERROR logs/mailplus.log + +# 3. 법령 마지막 확인 시간 +cat data/law_last_check.json | python3 -m json.tool + +# 4. DEVONthink Inbox 미처리 건수 (API 서버 실행 중이면) +curl -s http://localhost:9900/devonthink/inbox-count + +# 5. MLX 서버 상태 +curl -s http://localhost:8800/v1/models | python3 -m json.tool ``` ## 실행 스케줄 | 스크립트 | 시간 | 용도 | |---------|------|------| -| law_monitor.py | 매일 07:00 | 법령 변경 모니터링 | -| mailplus_archive.py | 매일 07:00, 18:00 | 이메일 수집 | -| pkm_daily_digest.py | 매일 20:00 | 일일 다이제스트 | +| law_monitor.py | 매일 07:00 | 법령 변경 모니터링 (한국+US/JP/EU) | +| mailplus_archive.py | 매일 07:00, 18:00 | MailPlus 이메일 수집 | +| pkm_daily_digest.py | 매일 20:00 | 일일 다이제스트 생성 | +| pkm_api_server.py | 상시 (수동/launchd) | REST API (포트 9900) | + +## 트러블슈팅 + +### 법령 API "사용자 정보 검증 실패" + +``` +원인: Mac mini 공인 IP가 open.law.go.kr에 등록되지 않음 +해결: +1. curl -s ifconfig.me 로 현재 공인 IP 확인 +2. open.law.go.kr → 마이페이지 → 인증키 관리 → IP 등록 +3. IP가 변경되면 다시 등록 필요 (고정 IP 아닌 경우) +``` + +### MailPlus IMAP Connection refused + +``` +확인 순서: +1. Synology DSM → MailPlus Server → 서비스 상태 확인 +2. IMAP 활성화: DSM → MailPlus Server → 메일 전송 → IMAP 탭 +3. 포트: 993(SSL) vs 143(STARTTLS) +4. 방화벽: Synology 방화벽에서 993 포트 확인 +5. Tailscale 직접: + python3 -c "import imaplib; m=imaplib.IMAP4_SSL('100.101.79.37', 993); print('OK')" +``` + +### AppleScript 실행 오류 + +``` +확인: +1. DEVONthink, OmniFocus가 GUI로 실행 중인지 확인 +2. 접근성 권한: 시스템 설정 → 개인정보 보호 → 접근성 → python/osascript 허용 +3. 수동 테스트: + osascript -e 'tell application "DEVONthink 3" to get name of databases' +``` + +### MLX 서버 응답 없음 + +``` +확인: +1. MLX 서버 프로세스 확인: ps aux | grep mlx +2. 포트 확인: lsof -i :8800 +3. 모델 로드 확인: curl http://localhost:8800/v1/models +4. 재시작 필요 시: (MLX 서버 시작 명령어 실행) +``` + +### Daily Digest에 데이터가 비어있음 + +``` +확인: +1. DEVONthink이 실행 중인지 확인 +2. OmniFocus가 실행 중인지 확인 +3. 로그 확인: tail -20 logs/digest.log +4. AppleScript 직접 테스트: + osascript -e 'tell application "DEVONthink 3" to get count of databases' +``` diff --git a/docs/dev-roadmap.md b/docs/dev-roadmap.md new file mode 100644 index 0000000..bb2e372 --- /dev/null +++ b/docs/dev-roadmap.md @@ -0,0 +1,399 @@ +# PKM 시스템 개발 로드맵 + +> 작성일: 2026-03-29 (GPU 서버 재구성 계획 통합: 2026-03-29) +> 현재 상태: Phase 1 코드 작성 완료(90%), 인프라 일부 미해결 → Phase 1.5(GPU 재구성) + Phase 2 진행 중 + +--- + +## 현재 완료된 것 + +| 단계 | 항목 | 상태 | 비고 | +|------|------|------|------| +| 1 | 프로젝트 구조 | ✅ 완료 | README, deploy.md, .gitignore | +| 2 | AI 분류 프롬프트 | ✅ 완료 | MLX(Qwen3.5) OpenAI 호환 API 전환 완료 | +| 3 | AppleScript | ✅ 완료 | auto_classify + omnifocus_sync | +| 4 | 법령 모니터링 | ⚠️ 부분 | 외국(US/JP/EU) OK, 한국 API 인증 실패 | +| 5 | MailPlus 수집 | ❌ 연결 실패 | IMAP Connection refused | +| 6 | Daily Digest | ⚠️ 미테스트 | 코드 완성, 실행 기록 없음 | +| 7 | DEVONagent 가이드 | ✅ 완료 | docs/devonagent-setup.md | +| 8 | 전체 테스트 | ❌ 미진행 | test_classify.py만 존재 | +| 추가 | PKM API 서버 | ⚠️ 부분 | 한글 인코딩, stats 500 에러 | + +--- + +## Phase 1.5: GPU 서버 재구성 (Phase 2와 병행) + +> 상세 계획: docs/gpu-restructure.md 참조 + +GPU 서버(RTX 4070Ti Super)의 역할을 LLM 추론에서 임베딩/OCR 특화로 전환한다. +Mac Mini와 중복되는 LLM 모델을 제거하고, Surya OCR + bge-m3를 배치한다. + +### 1.5-A. GPU 서버 정리 (SSH 작업) + +``` +작업 내용: +1. Ollama 모델 제거: qwen3.5:9b-q8_0, id-9b +2. 새 모델 설치: bge-m3 (임베딩), bge-reranker-v2-m3 (리랭킹) +3. no-think proxy(11435) 비활성화 +4. paperless-gpt 처리 방침 결정 +5. tk-ai-service 코드 수정 (Ollama API → OpenAI API 전환) + +검증: ollama list → bge-m3, bge-reranker만 존재 +검증: tk-ai-service /health → MLX(text), GPU(embed) 모두 connected +``` + +### 1.5-B. Docker + NFS + Komga 이전 + +``` +작업 내용: +1. GPU 서버에 Docker Engine 설치 +2. NAS NFS 마운트 설정 (192.168.1.227:/volume1/Comic → /mnt/comic, ro) +3. Komga Docker 컨테이너를 GPU 서버로 이전 (포트 25600 유지) +4. Mac Mini nginx upstream 변경 → GPU 서버 +5. Mac Mini Komga 제거 (Docker VM 메모리 1.23GB 회수) + +검증: curl https://komga.hyungi.net → GPU 서버 경유 접근 확인 +``` + +### 1.5-C. Surya OCR 설치 + +``` +작업 내용: +1. PyTorch CUDA 런타임 확인/설치 +2. Surya OCR FastAPI 서버 구성 (/opt/surya-ocr/, 포트 8400) +3. systemd 서비스 등록 + +검증: curl -F "file=@test.pdf" http://192.168.1.186:8400/ocr → OCR 텍스트 반환 +``` + +### 1.5-D. PKM 코드 갱신 (Phase 2와 겹치는 항목 포함) + +``` +작업 내용: +1. embed_to_chroma.py → embed_to_qdrant.py 리라이트 (Qdrant + bge-m3) +2. auto_classify.scpt: Step 0(OCR) 추가 + Step 4 Qdrant + sourceChannel 버그 픽스 +3. requirements.txt: chromadb→qdrant-client, flask/gunicorn 추가 ← Phase 2 1-1과 합산 +4. credentials.env: GPU_SERVER_IP=192.168.1.186 추가 +5. architecture.md 대규모 갱신 (ChromaDB 28건, nomic 12건, VL-7B 5건) + +검증: python3 scripts/embed_to_qdrant.py <테스트UUID> → Qdrant 벡터 저장 확인 +``` + +### 1.5-E. RAG 파이프라인 + OCR 연동 (후순위) + +``` +작업 내용: +1. pkm_api_server.py에 RAG 엔드포인트 추가 (/rag/query, /devonthink/embed) +2. DEVONthink Smart Rule에 OCR 전처리 단계 추가 +3. ocr_preprocess.py 신규 작성 + +검증: curl -X POST localhost:9900/rag/query -d '{"q":"산업안전 법령"}' → 답변 반환 +``` + +--- + +## Phase 2: 인프라 수정 (Phase 1.5와 병행) + +Mac mini에서 직접 확인/수정이 필요한 항목들. +※ Phase 1.5(GPU 재구성)과 병행하여 진행. 겹치는 항목(requirements.txt, credentials.env, AppleScript)은 합산. + +### 1-1. requirements.txt 수정 ← Phase 1.5-D와 합산 진행 + +``` +현재 문제: +- flask 누락 (pkm_api_server.py에서 사용 중) +- schedule 패키지 미사용 (제거 고려) +- chromadb → qdrant-client 교체 (GPU 재구성에 따라) + +수정 내용: ++ flask>=3.0.0 ++ gunicorn>=21.2.0 (프로덕션 WSGI) ++ qdrant-client>=1.7.0 +- chromadb>=0.4.0 +- schedule>=1.2.0 (미사용 확인 후 제거) +``` + +### 1-2. 한국 법령 API 인증 해결 + +``` +현재 에러: +"사용자 정보 검증에 실패하였습니다. + OPEN API 호출 시 사용자 검증을 위하여 정확한 서버장비의 IP주소 및 도메인주소를 등록해 주세요." + +조치: +1. open.law.go.kr 접속 → 마이페이지 → 인증키 관리 +2. Mac mini의 외부 IP 확인: curl ifconfig.me +3. 해당 IP를 API 호출 서버 IP로 등록 +4. Tailscale IP(100.x.x.x)가 아니라 실제 공인 IP여야 함 +5. 등록 후 law_monitor.py 재실행하여 확인 +``` + +### 1-3. MailPlus IMAP 연결 수정 + +``` +현재 에러: [Errno 61] Connection refused (mailplus.hyungi.net:993) + +확인 순서: +1. Synology DSM → MailPlus Server → 서비스 상태 확인 +2. IMAP 활성화 여부: DSM → MailPlus Server → 메일 전송 → IMAP 탭 +3. 포트 확인: 993(SSL) vs 143(STARTTLS) +4. 방화벽: Synology 방화벽에서 993 포트 개방 확인 +5. DNS 확인: nslookup mailplus.hyungi.net → 올바른 IP? +6. Tailscale 경유 시: 100.101.79.37:993으로 직접 테스트 + python3 -c "import imaplib; m=imaplib.IMAP4_SSL('100.101.79.37', 993); print('OK')" +7. credentials.env에 MAILPLUS_HOST 값 확인 +``` + +### 1-4. launchd 등록 상태 확인 및 등록 + +```bash +# Mac mini에서 확인 +launchctl list | grep pkm + +# 미등록 시 심볼릭 링크 생성 +ln -sf ~/Documents/code/DEVONThink_my\ server/launchd/net.hyungi.pkm.law-monitor.plist ~/Library/LaunchAgents/ +ln -sf ~/Documents/code/DEVONThink_my\ server/launchd/net.hyungi.pkm.mailplus.plist ~/Library/LaunchAgents/ +ln -sf ~/Documents/code/DEVONThink_my\ server/launchd/net.hyungi.pkm.daily-digest.plist ~/Library/LaunchAgents/ + +# 로드 +launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.law-monitor.plist +launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.mailplus.plist +launchctl load ~/Library/LaunchAgents/net.hyungi.pkm.daily-digest.plist +``` + +--- + +## Phase 2: 버그 픽스 (코드 수정) + +### 2-1. JP 번역 thinking 오염 문제 + +``` +현재: MLX Qwen3.5가 번역 시 "Wait, I'll check if..." 같은 thinking을 출력에 포함 +위치: scripts/law_monitor.py의 JP 번역 호출부 + +수정 방향: +- 번역 프롬프트에 /nothink 모드 명시 강화 +- llm_generate() 호출 시 thinking 출력 후처리 추가 +- "Wait,", "Let me", "I'll check" 등 패턴 필터링 +- 또는 번역 결과에서 첫 번째 유효 문장만 추출 +``` + +### 2-2. PKM API 서버 한글 인코딩 + +``` +현재: /devonthink/search?q=산업안전 → 400 Bad request syntax +위치: scripts/pkm_api_server.py + +수정: +- Flask 자체는 UTF-8 지원하므로, 클라이언트 측 URL 인코딩 문제일 가능성 +- curl 호출 시 --data-urlencode 사용 또는 퍼센트 인코딩 필요 +- 서버 측에서도 request.args.get('q', '') 기본 인코딩 확인 +``` + +### 2-3. /devonthink/stats 500 에러 수정 + +``` +현재: GET /devonthink/stats → 500 Internal Server Error +위치: scripts/pkm_api_server.py + +원인 추정: AppleScript 실행 시 DB 이름이나 경로 문제 +수정: 에러 로그 확인 후 AppleScript 쿼리 수정 +``` + +### 2-4. AppleScript 하드코딩 경로 개선 + +``` +현재: +- ~/Documents/code/DEVONThink_my server/scripts/prompts/ 하드코딩 +- venv 경로 하드코딩 + +수정: +- 스크립트 상단에 BASE_DIR 변수 정의 +- 또는 환경변수 PKM_HOME으로 통일 +``` + +### 2-5. requirements.txt 정리 + +``` +추가: flask>=3.0.0, gunicorn>=21.2.0 +유지: anthropic (향후 Tier 2용) +검토: schedule (미사용이면 제거) +``` + +--- + +## Phase 3: API 서버 개선 + +### 3-1. 프로덕션 서빙 + +``` +현재: Flask development server +변경: gunicorn + launchd로 안정 운영 + +launchd plist 추가: + net.hyungi.pkm.api-server.plist + → gunicorn -w 2 -b 127.0.0.1:9900 pkm_api_server:app +``` + +### 3-2. 엔드포인트 보완 + +``` +현재 엔드포인트: + GET /health + GET /devonthink/stats ← 500 에러 수정 필요 + GET /devonthink/search + GET /devonthink/inbox-count + GET /omnifocus/stats + GET /omnifocus/today + GET /omnifocus/overdue + +추가 고려: + GET /law-monitor/status ← 마지막 실행 결과, 다음 실행 시간 + GET /digest/latest ← 최근 다이제스트 조회 + POST /classify ← 수동 분류 요청 (테스트용) +``` + +### 3-3. 간단한 인증 추가 (선택) + +``` +localhost 전용이면 불필요하지만, Tailscale 내부에서 접근할 경우: +- Bearer token 방식 (credentials.env에 API_TOKEN 추가) +- 또는 IP 화이트리스트 (127.0.0.1 + Tailscale 대역) +``` + +--- + +## Phase 4: 테스트 & 검증 + +### 4-1. 개별 모듈 테스트 + +```bash +# Mac mini에서 실행 + +# 1. AI 분류 테스트 (5종 문서) +cd ~/Documents/code/DEVONThink_my\ server/ +source venv/bin/activate +python tests/test_classify.py + +# 2. 법령 모니터링 (한국 API 인증 후) +python scripts/law_monitor.py + +# 3. MailPlus (IMAP 수정 후) +python scripts/mailplus_archive.py + +# 4. Daily Digest +python scripts/pkm_daily_digest.py + +# 5. API 서버 +python scripts/pkm_api_server.py & +curl http://localhost:9900/health +curl http://localhost:9900/devonthink/stats +curl http://localhost:9900/devonthink/inbox-count +curl "http://localhost:9900/devonthink/search?q=safety&limit=3" +``` + +### 4-2. E2E 통합 테스트 + +``` +시나리오 1: Inbox → 자동분류 플로우 + 1. DEVONthink Inbox에 테스트 문서 추가 + 2. Smart Rule 트리거 → auto_classify.scpt 실행 확인 + 3. 태그, 메타데이터, DB 이동 확인 + +시나리오 2: 법령 → 다이제스트 플로우 + 1. law_monitor.py 수동 실행 + 2. data/laws/에 파일 생성 확인 + 3. DEVONthink 04_Industrial Safety 확인 + 4. pkm_daily_digest.py 실행 → 법령 변경 건 포함 확인 + +시나리오 3: OmniFocus 연동 + 1. Projects DB에 TODO 패턴 문서 추가 + 2. omnifocus_sync.scpt 트리거 확인 + 3. OmniFocus Inbox에 작업 생성 확인 +``` + +### 4-3. 테스트 리포트 작성 + +``` +→ docs/test-report.md +각 항목별 pass/fail + 스크린샷/로그 첨부 +``` + +--- + +## Phase 5: 운영 안정화 (선택) + +### 5-1. 모니터링 + +``` +- 로그 로테이션 (logrotate 또는 Python RotatingFileHandler) +- Synology Chat 웹훅 알림 연동 (CHAT_WEBHOOK_URL 설정 후) +- 에러 발생 시 즉시 알림 +``` + +### 5-2. 백업 + +``` +- Gitea 리포지토리 자동 백업 (이미 NAS에 있으므로 OK) +- credentials.env 백업 (Vaultwarden에 보관?) +- Qdrant 데이터 백업 (pkm_documents + tk_qc_issues 컬렉션) +``` + +### 5-3. 문서 보완 + +``` +- README.md 상세화 (아키텍처 다이어그램, 기능 목록) +- 트러블슈팅 가이드 추가 +- deploy.md에 API 서버 + 업데이트 절차 추가 +``` + +--- + +## 작업 순서 요약 + +``` +[GPU] Phase 1.5: GPU 서버 재구성 (Phase 2와 병행) + 1.5-A. GPU 서버 정리 (모델 교체, proxy 제거) ← SSH 작업 + 1.5-B. Docker + NFS + Komga 이전 ← SSH 작업 + 1.5-C. Surya OCR 설치 ← SSH 작업 + 1.5-D. PKM 코드 갱신 (Qdrant, 임베딩) ← 코드 수정 후 push + 1.5-E. RAG + OCR 연동 ← 후순위 + +[즉시] Phase 2: 인프라 수정 + 1-1. requirements.txt 수정 ← Phase 1.5-D와 합산 + 1-2. 한국 법령 API IP 등록 ← Mac mini에서 공인IP 확인 + 1-3. MailPlus IMAP 확인 ← Synology DSM 확인 + 1-4. launchd 등록 ← Mac mini에서 실행 + +[코드] Phase 3: 버그 픽스 + 2-1. JP 번역 thinking 필터링 ← 코드 수정 후 push + 2-2~3. API 서버 수정 ← 코드 수정 후 push + 2-4. AppleScript 경로 변수화 ← Phase 1.5-D와 합산 + 2-5. requirements.txt 정리 ← Phase 1.5-D와 합산 + +[개선] Phase 4: API 서버 개선 + 3-1. gunicorn 전환 + launchd plist ← 코드 작성 후 push + 3-2~3. 엔드포인트 추가 ← 필요시 + +[검증] Phase 5: 테스트 + 4-1~2. 모듈별 + E2E 테스트 ← Mac mini에서 실행 + 4-3. 테스트 리포트 ← 결과 기반 작성 + +[안정] Phase 6: 운영 안정화 ← 여유 있을 때 +``` + +--- + +## 예상 소요 시간 + +| Phase | 예상 시간 | 비고 | +|-------|-----------|------| +| Phase 1.5-A~C | 3~4시간 | GPU 서버 SSH 작업 (모델 교체, Docker, Surya) | +| Phase 1.5-D | 3~4시간 | PKM 코드 갱신 (Qdrant, architecture.md 대규모 수정) | +| Phase 1.5-E | 2~3시간 | RAG + OCR 연동 (후순위) | +| Phase 2 | 1~2시간 | 인프라 설정 확인 작업 | +| Phase 3 | 2~3시간 | 버그 픽스 코드 수정 | +| Phase 4 | 1~2시간 | gunicorn 전환 중심 | +| Phase 5 | 2~3시간 | Mac mini에서 테스트 실행 | +| Phase 6 | 필요시 | 운영하면서 점진적 | +| **합계** | **~18시간** | 4~5일 분량 | diff --git a/docs/gpu-restructure.md b/docs/gpu-restructure.md new file mode 100644 index 0000000..60a18d7 --- /dev/null +++ b/docs/gpu-restructure.md @@ -0,0 +1,460 @@ +# GPU 서버 재구성 + PKM 프로젝트 연계 계획 + +## Context + +GPU 서버(RTX 4070Ti Super)에서 Mac Mini와 중복되는 LLM 모델(qwen3.5:9b, id-9b)을 제거하고, +대신 Surya OCR + bge-m3 임베딩 서비스를 배치하여 역할을 명확히 분리한다. +추가로 Komga(만화 서버)를 Mac Mini에서 GPU 서버로 이전하여 Surya OCR과 로컬 연동 가능하게 한다. + +기존 PKM 프로젝트(`~/Documents/code/DEVONThink_my server/`)와 연계하여: +- ChromaDB → Qdrant 마이그레이션 +- nomic-embed-text → bge-m3 통일 +- Qwen2.5-VL-7B 비전 OCR → Surya OCR 전용 대체 +- architecture.md, embed 스크립트, AppleScript 등 관련 코드/문서 일괄 갱신 + +PKM 프로젝트는 현재 Phase 1 완료(90%), Phase 2(인프라 수정+버그 픽스) 착수 대기 상태. +이번 GPU 서버 재구성은 Phase 2와 병행하여 인프라 변경을 반영한다. + +--- + +## 현재 상태 요약 + +### GPU 서버 (192.168.1.186) +- Ryzen 7 7800X3D / 30GB RAM / RTX 4070Ti Super 16GB VRAM +- **서비스**: Ollama(11434) + no-think proxy(11435), Plex(32400) +- **Ollama 모델**: qwen3.5:9b-q8_0(10GB), id-9b(10GB) ← **제거 확정** +- CUDA 드라이버 580.x 설치됨, nvcc(CUDA toolkit) 미설치 +- Docker 미설치, Python 3.12 +- NAS SMB/NFS 마운트 미설정 + +### Mac Mini (192.168.1.122) +- M4 Pro / 64GB / MLX Qwen3.5-35B(8800), Ollama bge-m3(11434) +- **Docker**: Qdrant(6333), Komga(25600), NanoClaw(9801), tk-ai-service(30400) 등 +- **PKM 프로젝트**: `~/Documents/code/DEVONThink_my server/` + - `embed_to_chroma.py` → GPU 서버 nomic-embed-text + ChromaDB ← **Qdrant + bge-m3로 변경** + - `auto_classify.scpt` → MLX localhost:8800으로 분류, Step 4에서 embed_to_chroma.py 호출 + - `pkm_api_server.py` → Flask 9900번 포트 (stats 500 에러, 한글 인코딩 버그 있음) + - `architecture.md` → GPU Tier 3에 nomic-embed + VL-7B + reranker 계획 ← **갱신 필요** +- **DEVONthink 4**: 13개 DB, Smart Rule 3개 설계 완료 + +### 영향받는 외부 서비스 +- `tk-ai-service` docker-compose.yml: `OLLAMA_TEXT_MODEL=qwen3.5:9b-q8_0` → **변경 필요** +- `paperless-gpt`: `qwen3:8b` 참조 → docker-compose 존재하나 **현재 미실행** (docker ps에 없음), Phase 1에서 처리 방침 결정 필요 + +### NAS IP 참고 +- NAS LAN IP: `192.168.1.227` (nginx-ssl.conf upstream에서 확인됨) +- NAS Tailscale IP: `100.101.79.37` +- NFS 마운트는 **LAN 직결 (192.168.1.227)** 사용 (성능상 최적) + +--- + +## 변경 계획 + +### Phase 1: GPU 서버 정리 (선행) + +**1-1. Ollama 모델 제거** +```bash +ssh 192.168.1.186 +ollama rm qwen3.5:9b-q8_0 +ollama rm id-9b +``` + +**1-2. 새 모델 설치** +```bash +ollama pull bge-m3 # 임베딩 (1024차원, 한국어 우수) +ollama pull bge-reranker-v2-m3 # RAG 리랭킹 +``` +- 임베딩 모델: `nomic-embed-text`(768차원) 대신 `bge-m3`(1024차원)으로 통일 + - 이유: Mac Mini Ollama에서 이미 bge-m3 사용 중, 한국어 성능 우수, Qdrant tk_qc_issues 컬렉션도 1024차원 + +**1-3. Ollama no-think proxy(11435) 비활성화** +- LLM 모델 제거 후 think:false 주입이 불필요 +- `sudo systemctl disable --now ollama-proxy` + +**1-4. Ollama systemd 환경 조정** +```ini +# /etc/systemd/system/ollama.service [Service] 섹션에 추가 +Environment="OLLAMA_MAX_LOADED_MODELS=2" +Environment="OLLAMA_KEEP_ALIVE=30m" +``` + +**1-5. paperless-gpt 처리** +- 현재 미실행 상태 (docker ps에 없음) +- docker-compose.yml에 `qwen3:8b` 참조 → GPU 서버 모델 제거 시 사용 불가 +- 옵션: (a) MLX 35B로 전환 (b) 당분간 비활성 유지 (c) 폐기 +- Paperless-ngx 자체가 활발히 사용 중인지 확인 후 결정 + +**1-6. tk-ai-service 코드 + 설정 변경** (Mac Mini 유지, 코드 수정 필수) + +tk-ai-service는 Ollama 네이티브 API(`/api/chat`, `/api/embeddings`)를 사용 중. +MLX 서버는 OpenAI API(`/v1/chat/completions`)만 지원하므로 코드 수정 필요. + +**a) `ollama_client.py` → `llm_client.py` 리팩터링** +- `generate_text()`: `/api/chat` → `/v1/chat/completions` (OpenAI 형식) + - 요청: `{"model":"...","messages":[...],"stream":false}` + - 응답: `response.json()["choices"][0]["message"]["content"]` +- `generate_embedding()`: 변경 없음 (GPU Ollama `/api/embeddings` 그대로) +- `check_health()`: text URL `/api/tags` → `/v1/models` 또는 단순 GET 체크 +- 클래스명/파일명 변경 고려 (OllamaClient → LLMClient) + +**b) docker-compose.yml 환경변수 변경** +```yaml +# ~/docker/tk-ai-service/docker-compose.yml +- OLLAMA_BASE_URL=http://host.internal:8800 # Mac Mini MLX 서버 (OpenAI API) +- OLLAMA_TEXT_MODEL=mlx-community/Qwen3.5-35B-A3B-4bit +- OLLAMA_EMBED_URL=http://192.168.1.186:11434 # GPU 서버 Ollama (임베딩) +- OLLAMA_EMBED_MODEL=bge-m3 # 변경 없음 +``` + +**c) config.py 주석 갱신** +```python +# Mac Mini MLX (텍스트 생성) — OpenAI 호환 API +OLLAMA_BASE_URL: str = "http://host.internal:8800" +# GPU 서버 Ollama (임베딩) +OLLAMA_EMBED_URL: str = "http://192.168.1.186:11434" +``` + +### Phase 1.5: GPU 서버 Docker + NFS + Komga 이전 + +**1.5-1. Docker 설치** (GPU 서버) +```bash +# Docker Engine (Ubuntu) +sudo apt-get update +sudo apt-get install docker-ce docker-ce-cli containerd.io docker-compose-plugin +sudo usermod -aG docker hyungi +# nvidia-container-toolkit (Surya OCR Docker化 시 필요, 당장은 불필요) +``` + +**1.5-2. NAS NFS 마운트 설정** + +Synology NAS 측: +- DSM → 제어판 → 파일 서비스 → NFS 활성화 (v4.1) +- 공유 폴더(Comic) → NFS 권한: `192.168.1.186` 단일 IP, 읽기 전용, root_squash + +GPU 서버 측: +```bash +sudo apt install nfs-common +sudo mkdir -p /mnt/comic +# /etc/fstab 추가: +192.168.1.227:/volume1/Comic /mnt/comic nfs4 ro,nosuid,noexec,nodev,soft,timeo=15 0 0 +sudo mount -a +``` + +**1.5-3. Komga Docker 이전** + +GPU 서버에 docker-compose.yml 생성: +```yaml +# /opt/komga/docker-compose.yml +services: + komga: + image: gotson/komga + container_name: komga + ports: + - "25600:25600" + volumes: + - /mnt/comic:/data/comics:ro # NFS 마운트 (읽기 전용) + - ./config:/config # Komga 설정/DB + environment: + - TZ=Asia/Seoul + restart: unless-stopped +``` + +**1.5-4. Mac Mini 측 변경** +- Mac Mini Komga 컨테이너 중지: `docker stop komga && docker rm komga` +- nginx upstream 변경: + ``` + # nginx-ssl.conf + upstream komga_backend { + server 192.168.1.186:25600; # GPU 서버로 변경 + } + ``` +- nginx 재시작: `docker restart home-service-proxy` +- Mac Mini Docker VM 메모리 **1.23GB 회수** + +**1.5-5. Komga 설정 마이그레이션** +- Mac Mini의 Komga config/DB를 GPU 서버로 복사 (라이브러리 메타데이터, 사용자 설정 유지) +- 경로: Mac Mini `~/docker/Komga/` → GPU `scp`로 전송 +- **주의**: Komga 내부 DB(H2)에 라이브러리 절대경로가 저장되어 있음 + - Mac Mini: `/data/comics` (Docker 내부 마운트 경로) + - GPU 서버: `/data/comics` (동일하게 Docker 마운트하면 경로 변경 불필요) + - Docker 내부 경로를 동일하게 맞추면 DB 마이그레이션 문제 없음 + - 만약 경로가 달라지면 Komga UI에서 라이브러리 경로 재설정 또는 전체 재스캔 필요 + +### Phase 2: Surya OCR 설치 + +**2-1. PyTorch CUDA 런타임 확인** (GPU 서버) +- Surya OCR은 PyTorch에 의존 → PyTorch 설치 시 CUDA 런타임이 번들됨 +- 별도 `nvidia-cuda-toolkit` 설치가 **불필요할 수 있음** (nvcc는 직접 CUDA 코드 컴파일 시만 필요) +- GPU 서버에서 확인: +```bash +# PyTorch CUDA 지원 확인 +python3 -c "import torch; print(torch.cuda.is_available())" +# 안 되면 CUDA 번들 포함 PyTorch 설치 +pip install torch --index-url https://download.pytorch.org/whl/cu124 +``` + +**2-2. Surya OCR 서비스 구성** +``` +/opt/surya-ocr/ + venv/ # Python venv (surya-ocr, fastapi, uvicorn, python-multipart) + server.py # FastAPI 래퍼 +``` + +서버 엔드포인트: +- `POST /ocr` — 파일 업로드 → OCR 텍스트 + 바운딩박스 반환 +- `POST /ocr/layout` — 레이아웃 분석 포함 +- `GET /health` — 상태 확인 + +**2-3. systemd 서비스 등록** +```ini +# /etc/systemd/system/surya-ocr.service +[Unit] +Description=Surya OCR Service +After=network-online.target + +[Service] +ExecStart=/opt/surya-ocr/venv/bin/uvicorn server:app --host 0.0.0.0 --port 8400 +WorkingDirectory=/opt/surya-ocr +Restart=always +RestartSec=5 + +[Install] +WantedBy=multi-user.target +``` + +**VRAM 예산 (변경 후)** + +| 컴포넌트 | VRAM | 비고 | +|----------|------|------| +| Plex HW 트랜스코드 | ~1-2GB | 활성 시 | +| Surya OCR | ~2-3GB | 활성 시 | +| bge-m3 임베딩 | ~1.5GB | 상시 | +| bge-reranker | ~1GB | 온디맨드 | +| **합계 (피크)** | **~7-8GB / 16GB** | 여유 충분 | + +### Phase 3: 벡터 DB 통합 (ChromaDB → Qdrant) + PKM 코드 갱신 + +**결정: Qdrant로 통일, ChromaDB 폐기** +- Qdrant가 이미 Mac Mini Docker에서 운영 중 (tk_qc_issues 컬렉션) +- ChromaDB는 embed_to_chroma.py에서만 계획/사용 +- 2개 벡터 DB 운영은 불필요한 복잡성 + +**3-1. Qdrant에 pkm_documents 컬렉션 생성** +``` +dimension: 1024 (bge-m3) +distance: cosine +payload 필드: uuid, title, database, tags, source_channel +``` + +**3-2. `scripts/embed_to_chroma.py` → `scripts/embed_to_qdrant.py` 리라이트** +- `chromadb` → `qdrant-client` 교체 +- GPU 서버 임베딩 모델: `nomic-embed-text` → `bge-m3` +- Ollama API: `/api/embed` 사용 (배치 지원, `{"model":"bge-m3","input":["텍스트"]}`) + - 현재 auto_classify.scpt에서 문서 단건 호출이므로 단일/배치 모두 가능 + - 향후 embed-batch 엔드포인트에서 배치 활용 가능 +- 텍스트 청킹 추가 (500토큰, 50토큰 오버랩) +- `pkm_utils.load_credentials()`에서 GPU_SERVER_IP 로드 +- **기존 `embed_to_chroma.py`는 `git rm`으로 삭제** (GPU_SERVER_IP 미설정으로 실행된 적 없음, 실 데이터 없음) + +**3-3. `applescript/auto_classify.scpt` Step 4 수정 + 버그 픽스** +- 현재: `do shell script "python3 ~/scripts/embed_to_chroma.py " & docUUID & " &"` +- 변경: `embed_to_qdrant.py` 호출로 교체 + baseDir 변수 사용 +- **버그 픽스**: 73행 `add custom meta data "inbox_route" for "sourceChannel"` 삭제 + - 70행에서 AI 분류 결과로 설정한 sourceChannel을 "inbox_route"로 덮어쓰는 버그 + +**3-4. requirements.txt 업데이트** (dev-roadmap 9단계와 합산, 단일 커밋) +``` +- chromadb>=0.4.0 +- schedule>=1.2.0 # 미사용 확인 후 제거 ++ qdrant-client>=1.7.0 ++ flask>=3.0.0 # dev-roadmap 9단계 ++ gunicorn>=21.2.0 # dev-roadmap 9단계 + anthropic>=0.40.0 # 유지 (향후 Tier 2용) +``` + +**3-5. credentials.env + credentials.env.example 업데이트** +``` +# credentials.env (Mac mini) +GPU_SERVER_IP=192.168.1.186 + +# credentials.env.example (git 추적) +GPU_SERVER_IP=192.168.1.xxx +``` + +**3-6. `docs/architecture.md` 대규모 갱신** (별도 커밋) +- **변경 규모**: ChromaDB 28건, nomic-embed 12건, VL-7B 5건 — 문맥별 수정 필요 (단순 치환 불가) +- 주요 변경 영역: + - AI 통합 아키텍처 다이어그램 (Tier 3 모델 목록: nomic→bge-m3, VL-7B→Surya OCR) + - VRAM 배분 다이어그램 (~11.3GB → ~7-8GB) + - 자동화 파이프라인 / Smart Rule 설계 (ChromaDB→Qdrant, embed 스크립트 경로) + - AI 결과물 저장 전략 표 (ChromaDB→Qdrant) + - 임베딩 이전 근거 테이블 (nomic→bge-m3 반영) + - 3-Tier AI 라우팅 전략 표 + - 코드 예시 내 경로/모델명 +- 이 작업은 **별도 시간을 잡아서** 전체 문서를 통독하며 진행 + +### Phase 4: DEVONthink OCR 연동 + +**4-1. `scripts/ocr_preprocess.py` 신규 작성** +- DEVONthink UUID → AppleScript로 파일 경로 추출 → Surya API(GPU:8400) 호출 → OCR 텍스트 반환 +- `pkm_utils.run_applescript_inline()` 재사용 +- 반환값: OCR 텍스트 (plain text) — DEVONthink 본문에 병합용 + +**4-2. `applescript/auto_classify.scpt` Smart Rule 수정** +- architecture.md의 Rule 1 설계에 따라 Step 0(OCR) 추가: + ``` + 현재: Step 1(MLX 분류) → Step 2(태그 파싱) → Step 3(DB 이동) → Step 4(임베딩) → Step 5(메타) + 변경: Step 0(OCR 감지+처리) → Step 1(MLX 분류) → ... → Step 4(Qdrant 임베딩) + ``` +- OCR 대상 감지 조건 (단순 텍스트 길이 < 50 대신 정교한 판별): + - `type of theRecord` = PDF **AND** `plain text of theRecord` = "" (텍스트 레이어 없음) + - 또는 `type of theRecord` ∈ {JPEG, PNG, TIFF} (이미지 파일) + - DEVONthink 자체가 PDF 텍스트 레이어를 읽으므로, OCR이 필요한 건 **텍스트가 완전히 비어있는 경우**뿐 +- Surya OCR 호출 → `set plain text of theRecord to ocrText` 로 본문 병합 +- 기존 Qwen2.5-VL-7B 비전 OCR 계획 → Surya 전용 OCR로 대체 (정확도 + ABBYY 대체) + +**4-3. `docs/architecture.md` Rule 1 갱신** +- "이미지/스캔 문서 → GPU 서버 VL-7B로 OCR" → "Surya OCR(:8400)으로 OCR" + +### Phase 5: RAG 파이프라인 (PKM API 확장) + +**5-1. pkm_api_server.py에 RAG 엔드포인트 추가** +- 현재 docstring(7행): "범위: DEVONthink + OmniFocus 전용. 이 이상 확장하지 않을 것." +- RAG는 DEVONthink 문서 검색 기반이므로 동일 범위의 확장으로 간주 +- docstring을 "범위: DEVONthink + OmniFocus + RAG 검색" 으로 갱신 +``` +POST /rag/query # 질문 → 임베딩 → Qdrant 검색 → 리랭킹 → LLM 답변 +POST /devonthink/embed # 단일 문서 임베딩 트리거 +POST /devonthink/embed-batch # 배치 임베딩 +``` + +**5-2. RAG 쿼리 플로우** +``` +질문 텍스트 + → GPU 서버 bge-m3로 쿼리 임베딩 (192.168.1.186:11434) + → Mac Mini Qdrant에서 유사도 검색 (localhost:6333, top-20) + → GPU 서버 bge-reranker로 리랭킹 (top-5) + → Mac Mini MLX Qwen3.5-35B로 답변 생성 (localhost:8800) + → DEVONthink 링크(x-devonthink-item://UUID) 포함 응답 +``` + +### Phase 6: NanoClaw + Komga 연동 (후순위, 별도 계획) + +Phase 5 완료 후 별도 문서로 상세 계획 수립. 현재는 방향만 기록: + +- **NanoClaw RAG**: PKM API `/rag/query` 엔드포인트 호출 → 시놀로지 Chat에서 "@이드 [질문]" → 문서 기반 답변 +- **Komga OCR**: Komga REST API → Surya OCR → Qdrant `komga_manga` 컬렉션 +- dev-roadmap.md에는 "향후 계획" 수준으로만 언급 + +--- + +## 변경 후 아키텍처 + +``` +┌─ Mac Mini M4 Pro ─────────────────────┐ ┌─ GPU 서버 (4070Ti) ─────────┐ +│ │ │ │ +│ MLX Qwen3.5-35B (:8800) — LLM 추론 │ │ Ollama (:11434) │ +│ MLX Proxy (:8801) — Synology 연동 │◄───►│ ├─ bge-m3 (임베딩) │ +│ Ollama (:11434) — bge-m3 로컬 폴백 │ │ └─ bge-reranker (리랭킹) │ +│ Qdrant (:6333) — 벡터 검색 │ │ │ +│ PKM API (:9900) — RAG 오케스트레이션 │ │ Surya OCR (:8400) │ +│ NanoClaw (:9801) — AI 어시스턴트 │ │ Plex (:32400) — HW 트랜스코드│ +│ DEVONthink — 문서 허브 │ │ Komga (:25600) — 만화 서버 │ +│ nginx proxy (:443) — 리버스 프록시 │ │ └─ NFS → NAS /Comic (ro) │ +│ │ │ │ +└────────────────────────────────────────┘ │ [제거됨] │ + ▲ │ ├─ qwen3.5:9b-q8_0 │ + │ ┌─ NAS ──────┐ │ ├─ id-9b │ + └──────────────│ 문서/미디어 │────────│ └─ no-think proxy (:11435)│ + └────────────┘ └──────────────────────────────┘ +``` + +## 수정 대상 파일 목록 + +### GPU 서버 +| 파일 | 변경 | +|------|------| +| Ollama 모델 | `rm qwen3.5:9b-q8_0`, `rm id-9b` / `pull bge-m3`, `pull bge-reranker-v2-m3` | +| `/etc/systemd/system/ollama.service` | 환경변수 추가 (MAX_LOADED_MODELS, KEEP_ALIVE) | +| `/etc/systemd/system/ollama-proxy.service` | **비활성화** (disable --now) | +| `/opt/surya-ocr/server.py` | **신규** — FastAPI OCR 서버 | +| `/etc/systemd/system/surya-ocr.service` | **신규** — systemd 유닛 | +| Docker Engine | **신규 설치** | +| `/etc/fstab` | NFS 마운트 추가 (NAS Comic → /mnt/comic, ro) | +| `/opt/komga/docker-compose.yml` | **신규** — Komga 컨테이너 | + +### PKM 프로젝트 (`~/Documents/code/DEVONThink_my server/`) +| 파일 | 변경 | +|------|------| +| `scripts/embed_to_chroma.py` | → `scripts/embed_to_qdrant.py` 리라이트 (chromadb→qdrant-client, nomic→bge-m3) | +| `scripts/ocr_preprocess.py` | **신규** — Surya OCR 호출 헬퍼 | +| `scripts/pkm_api_server.py` | RAG 엔드포인트 추가 (/rag/query, /devonthink/embed) | +| `scripts/pkm_utils.py` | 변경 없음 (`load_credentials()`에 이미 GPU_SERVER_IP 지원, 74행) | +| `applescript/auto_classify.scpt` | Step 0(OCR 감지) 추가 + Step 4 embed_to_qdrant.py로 변경 | +| `requirements.txt` | `chromadb` → `qdrant-client`, `flask` 추가 (dev-roadmap 9단계 합산) | +| `docs/architecture.md` | Tier 3 모델, VRAM 다이어그램, ChromaDB→Qdrant, Smart Rule 전체 갱신 | +| `docs/dev-roadmap.md` | GPU 서버 재구성 Phase 반영 | +| `docs/claude-code-commands.md` | GPU 서버 관련 단계 추가 | +| `credentials.env` (Mac mini) | `GPU_SERVER_IP=192.168.1.186` 추가 | +| `credentials.env.example` | GPU_SERVER_IP 항목 추가 | + +### Mac Mini 기타 +| 파일 | 변경 | +|------|------| +| `~/docker/tk-ai-service/docker-compose.yml` | BASE_URL → MLX :8800, EMBED_URL → GPU :11434 | +| `~/docker/tk-factory-services/ai-service/services/ollama_client.py` | Ollama API → OpenAI API 전환 (generate_text, check_health) | +| `~/docker/tk-factory-services/ai-service/config.py` | 주석 갱신 | +| `~/docker/home-service-proxy/nginx-ssl.conf` | `komga_backend` upstream → `192.168.1.186:25600` | +| Mac Mini Komga 컨테이너 | **중지 및 제거** (1.23GB Docker VM 메모리 회수) | + +## 검증 방법 + +1. **Phase 1.5 검증**: + - `ssh GPU "docker ps"` → komga 컨테이너 실행 중 + - `ssh GPU "ls /mnt/comic"` → NAS 만화 파일 목록 확인 + - `curl http://192.168.1.186:25600` → Komga 웹 UI 접근 + - `curl https://komga.hyungi.net` → nginx 프록시 경유 접근 확인 + - Mac Mini: `docker ps | grep komga` → 없음 (제거 완료) +2. **Phase 1 검증**: + - `ssh GPU "ollama list"` → bge-m3, bge-reranker만 존재 + - `ssh GPU "systemctl status ollama-proxy"` → inactive + - `ssh GPU "curl localhost:11434/api/embed -d '{\"model\":\"bge-m3\",\"input\":[\"test\"]}'` → 1024차원 벡터 반환 + - Qdrant 차원 확인: `curl localhost:6333/collections/tk_qc_issues` → vector size=1024 확인 (bge-m3와 일치) + - tk-ai-service 코드 수정 후: `docker compose build && docker compose up -d` + - `curl http://localhost:30400/health` → ollama_text(MLX), ollama_embed(GPU) 모두 connected + - `curl -X POST http://localhost:30400/api/chat -d '{"message":"테스트"}'` → MLX 35B 응답 확인 +2. **Phase 2 검증**: `curl -F "file=@test.pdf" http://192.168.1.186:8400/ocr` → OCR 텍스트 반환 +3. **Phase 3 검증**: + - `curl http://localhost:6333/collections/pkm_documents` → 컬렉션 존재 + - `python3 scripts/embed_to_qdrant.py <테스트UUID>` → Qdrant에 벡터 저장 확인 + - `git diff` → embed_to_chroma.py 삭제, embed_to_qdrant.py 생성 확인 +4. **Phase 4 검증**: DEVONthink Inbox에 스캔 PDF(텍스트 없는) 추가 → Smart Rule → OCR 텍스트 병합 → 분류 완료 +5. **Phase 5 검증**: `curl -X POST localhost:9900/rag/query -d '{"q":"산업안전 법령"}'` → 관련 문서 + 답변 반환 +6. **Phase 6**: 후순위, 별도 계획 시 검증 방법 수립 + +## 실행 순서 + +``` +Phase 1 (GPU 정리 + 모델 교체) ──┐ +Phase 1.5(Docker + NFS + Komga) ──┼── GPU 서버 작업 (SSH) +Phase 2 (Surya OCR 설치) ────────┘ + +Phase 3 (Qdrant 통합 + PKM 코드) ──┐── PKM 프로젝트 코드 수정 +Phase 4 (DEVONthink OCR 연동) ─────┘ → git commit & push + → Mac mini에서 git pull +Phase 5 (RAG 파이프라인) ──────── PKM API 확장 +Phase 6 (NanoClaw/Komga OCR) ─── 후순위 +``` + +Phase 1~2는 GPU 서버 SSH 작업, Phase 3~4는 PKM 프로젝트 코드 수정. +Phase 1 완료 시점에 tk-ai-service docker-compose도 함께 변경. +각 Phase는 독립적으로 검증 가능. + +**PKM dev-roadmap과의 관계:** +- 이 계획의 Phase 3~4 = dev-roadmap Phase 2의 일부 (인프라 수정) +- requirements.txt, AppleScript 경로, credentials.env 변경이 겹침 → 합쳐서 진행 + +**문서 통합 전략:** +- `docs/dev-roadmap.md`: GPU 서버 재구성 Phase를 기존 Phase 2 앞에 "Phase 1.5: GPU 서버 재구성" 으로 삽입, Phase 2 항목에서 겹치는 변경(requirements.txt, credentials.env) 연결 +- `docs/claude-code-commands.md`: Phase 2 섹션에 GPU 서버 관련 실행 단계 추가 (SSH 명령, Surya 설치, Qdrant 컬렉션 생성 등) +- 이 계획서는 `docs/gpu-restructure.md`로 정식 문서화 (아키텍처 결정 근거 기록으로 보존) diff --git a/requirements.txt b/requirements.txt index de77c32..703488c 100644 --- a/requirements.txt +++ b/requirements.txt @@ -1,6 +1,7 @@ -chromadb>=0.4.0 +qdrant-client>=1.7.0 requests>=2.31.0 python-dotenv>=1.0.0 -schedule>=1.2.0 markdown>=3.5.0 anthropic>=0.40.0 +flask>=3.0.0 +gunicorn>=21.2.0 diff --git a/scripts/embed_to_qdrant.py b/scripts/embed_to_qdrant.py new file mode 100644 index 0000000..d06112e --- /dev/null +++ b/scripts/embed_to_qdrant.py @@ -0,0 +1,114 @@ +#!/usr/bin/env python3 +""" +벡터 임베딩 스크립트 +- DEVONthink 문서 UUID로 텍스트 추출 +- GPU 서버(bge-m3)로 임베딩 생성 +- Qdrant에 저장 +""" + +import sys +import uuid as uuid_mod +import requests +from pathlib import Path + +sys.path.insert(0, str(Path(__file__).parent)) +from pkm_utils import setup_logger, load_credentials, run_applescript_inline + +logger = setup_logger("embed") + +QDRANT_URL = "http://localhost:6333" +COLLECTION = "pkm_documents" + + +def get_document_text(doc_uuid: str) -> tuple[str, str]: + """DEVONthink에서 UUID로 문서 텍스트 + 제목 추출""" + script = f''' + tell application id "DNtp" + set theRecord to get record with uuid "{doc_uuid}" + set docText to plain text of theRecord + set docTitle to name of theRecord + return docTitle & "|||" & docText + end tell + ''' + result = run_applescript_inline(script) + parts = result.split("|||", 1) + title = parts[0] if len(parts) > 0 else "" + text = parts[1] if len(parts) > 1 else "" + return title, text + + +def get_embedding(text: str, gpu_server_ip: str) -> list[float] | None: + """GPU 서버의 bge-m3로 임베딩 생성""" + url = f"http://{gpu_server_ip}:11434/api/embed" + try: + resp = requests.post(url, json={ + "model": "bge-m3", + "input": [text[:8000]] + }, timeout=60) + resp.raise_for_status() + embeddings = resp.json().get("embeddings") + return embeddings[0] if embeddings else None + except Exception as e: + logger.error(f"임베딩 생성 실패: {e}") + return None + + +def store_in_qdrant(doc_uuid: str, title: str, text: str, embedding: list[float]): + """Qdrant에 저장""" + # UUID 문자열을 정수 ID로 변환 (Qdrant point ID) + point_id = uuid_mod.uuid5(uuid_mod.NAMESPACE_URL, doc_uuid).int >> 64 + + payload = { + "uuid": doc_uuid, + "title": title, + "text_preview": text[:500], + "source": "devonthink", + } + + resp = requests.put( + f"{QDRANT_URL}/collections/{COLLECTION}/points", + json={ + "points": [{ + "id": point_id, + "vector": embedding, + "payload": payload, + }] + }, + timeout=30, + ) + resp.raise_for_status() + logger.info(f"Qdrant 저장: {doc_uuid} ({title[:30]})") + + +def run(doc_uuid: str): + """단일 문서 임베딩 처리""" + logger.info(f"임베딩 처리 시작: {doc_uuid}") + + creds = load_credentials() + gpu_ip = creds.get("GPU_SERVER_IP") + if not gpu_ip: + logger.warning("GPU_SERVER_IP 미설정 — 임베딩 건너뜀") + return + + try: + title, text = get_document_text(doc_uuid) + if not text or len(text) < 10: + logger.warning(f"텍스트 부족 [{doc_uuid}]: {len(text)}자") + return + + embedding = get_embedding(text, gpu_ip) + if embedding: + store_in_qdrant(doc_uuid, title, text, embedding) + logger.info(f"임베딩 완료: {doc_uuid}") + else: + logger.error(f"임베딩 실패: {doc_uuid}") + + except Exception as e: + logger.error(f"임베딩 처리 에러 [{doc_uuid}]: {e}", exc_info=True) + + +if __name__ == "__main__": + if len(sys.argv) < 2: + print("사용법: python3 embed_to_qdrant.py ") + sys.exit(1) + run(sys.argv[1]) diff --git a/scripts/pkm_api_server.py b/scripts/pkm_api_server.py new file mode 100644 index 0000000..95c7136 --- /dev/null +++ b/scripts/pkm_api_server.py @@ -0,0 +1,239 @@ +#!/usr/bin/env python3 +""" +PKM Host API Server +DEVONthink + OmniFocus AppleScript 중계용 경량 HTTP 서버. +NanoClaw 컨테이너에서 호출. LaunchAgent(GUI 세션)로 실행 필수. + +범위: DEVONthink + OmniFocus 전용. 이 이상 확장하지 않을 것. +""" + +import json +import subprocess +import sys +from flask import Flask, request, jsonify + +app = Flask(__name__) + + +def run_applescript(script: str, timeout: int = 120) -> str: + result = subprocess.run( + ['osascript', '-e', script], + capture_output=True, text=True, timeout=timeout + ) + if result.returncode != 0: + raise RuntimeError(result.stderr.strip()) + return result.stdout.strip() + + +# --- DEVONthink --- + +@app.route('/devonthink/stats') +def devonthink_stats(): + try: + script = ( + 'tell application id "DNtp"\n' + ' set today to current date\n' + ' set time of today to 0\n' + ' set stats to {}\n' + ' repeat with db in databases\n' + ' set dbName to name of db\n' + ' set addedCount to 0\n' + ' set modifiedCount to 0\n' + ' repeat with rec in children of root of db\n' + ' try\n' + ' if creation date of rec >= today then set addedCount to addedCount + 1\n' + ' if modification date of rec >= today then set modifiedCount to modifiedCount + 1\n' + ' end try\n' + ' end repeat\n' + ' if addedCount > 0 or modifiedCount > 0 then\n' + ' set end of stats to dbName & ":" & addedCount & ":" & modifiedCount\n' + ' end if\n' + ' end repeat\n' + ' set AppleScript\'s text item delimiters to "|"\n' + ' return stats as text\n' + 'end tell' + ) + result = run_applescript(script) + stats = {} + if result: + for item in result.split('|'): + parts = item.split(':') + if len(parts) == 3: + stats[parts[0]] = {'added': int(parts[1]), 'modified': int(parts[2])} + total_added = sum(s['added'] for s in stats.values()) + total_modified = sum(s['modified'] for s in stats.values()) + return jsonify(success=True, data={ + 'databases': stats, + 'total_added': total_added, + 'total_modified': total_modified + }) + except Exception as e: + return jsonify(success=False, error=str(e)), 500 + + +@app.route('/devonthink/search') +def devonthink_search(): + q = request.args.get('q', '') + limit = int(request.args.get('limit', '10')) + if not q: + return jsonify(success=False, error='q parameter required'), 400 + try: + script = ( + 'tell application id "DNtp"\n' + f' set results to search "{q}"\n' + ' set output to {}\n' + f' set maxCount to {limit}\n' + ' set i to 0\n' + ' repeat with rec in results\n' + ' if i >= maxCount then exit repeat\n' + ' set recName to name of rec\n' + ' set recDB to name of database of rec\n' + ' set recDate to modification date of rec as text\n' + ' set end of output to recName & "||" & recDB & "||" & recDate\n' + ' set i to i + 1\n' + ' end repeat\n' + ' set AppleScript\'s text item delimiters to linefeed\n' + ' return output as text\n' + 'end tell' + ) + result = run_applescript(script) + items = [] + if result: + for line in result.split('\n'): + parts = line.split('||') + if len(parts) == 3: + items.append({'name': parts[0], 'database': parts[1], 'modified': parts[2]}) + return jsonify(success=True, data=items, count=len(items)) + except Exception as e: + return jsonify(success=False, error=str(e)), 500 + + +@app.route('/devonthink/inbox-count') +def devonthink_inbox_count(): + try: + script = ( + 'tell application id "DNtp"\n' + ' set inboxDB to database "Inbox"\n' + ' return count of children of root of inboxDB\n' + 'end tell' + ) + count = int(run_applescript(script)) + return jsonify(success=True, data={'inbox_count': count}) + except Exception as e: + return jsonify(success=False, error=str(e)), 500 + + +# --- OmniFocus --- + +@app.route('/omnifocus/stats') +def omnifocus_stats(): + try: + script = ( + 'tell application "OmniFocus"\n' + ' tell default document\n' + ' set today to current date\n' + ' set time of today to 0\n' + ' set completedCount to count of (every flattened task whose completed is true and completion date >= today)\n' + ' set addedCount to count of (every flattened task whose creation date >= today)\n' + ' set overdueCount to count of (every flattened task whose completed is false and due date < today and due date is not missing value)\n' + ' return (completedCount as text) & "|" & (addedCount as text) & "|" & (overdueCount as text)\n' + ' end tell\n' + 'end tell' + ) + result = run_applescript(script) + parts = result.split('|') + return jsonify(success=True, data={ + 'completed': int(parts[0]) if len(parts) > 0 else 0, + 'added': int(parts[1]) if len(parts) > 1 else 0, + 'overdue': int(parts[2]) if len(parts) > 2 else 0 + }) + except Exception as e: + return jsonify(success=False, error=str(e)), 500 + + +@app.route('/omnifocus/overdue') +def omnifocus_overdue(): + try: + script = ( + 'tell application "OmniFocus"\n' + ' tell default document\n' + ' set today to current date\n' + ' set time of today to 0\n' + ' set overdueTasks to every flattened task whose completed is false and due date < today and due date is not missing value\n' + ' set output to {}\n' + ' repeat with t in overdueTasks\n' + ' set taskName to name of t\n' + ' set dueDate to due date of t as text\n' + ' set projName to ""\n' + ' try\n' + ' set projName to name of containing project of t\n' + ' end try\n' + ' set end of output to taskName & "||" & projName & "||" & dueDate\n' + ' end repeat\n' + ' set AppleScript\'s text item delimiters to linefeed\n' + ' return output as text\n' + ' end tell\n' + 'end tell' + ) + result = run_applescript(script) + tasks = [] + if result: + for line in result.split('\n'): + parts = line.split('||') + tasks.append({ + 'name': parts[0], + 'project': parts[1] if len(parts) > 1 else '', + 'due_date': parts[2] if len(parts) > 2 else '' + }) + return jsonify(success=True, data=tasks, count=len(tasks)) + except Exception as e: + return jsonify(success=False, error=str(e)), 500 + + +@app.route('/omnifocus/today') +def omnifocus_today(): + try: + script = ( + 'tell application "OmniFocus"\n' + ' tell default document\n' + ' set today to current date\n' + ' set time of today to 0\n' + ' set tomorrow to today + 1 * days\n' + ' set todayTasks to every flattened task whose completed is false and ((due date >= today and due date < tomorrow) or (defer date >= today and defer date < tomorrow))\n' + ' set output to {}\n' + ' repeat with t in todayTasks\n' + ' set taskName to name of t\n' + ' set projName to ""\n' + ' try\n' + ' set projName to name of containing project of t\n' + ' end try\n' + ' set end of output to taskName & "||" & projName\n' + ' end repeat\n' + ' set AppleScript\'s text item delimiters to linefeed\n' + ' return output as text\n' + ' end tell\n' + 'end tell' + ) + result = run_applescript(script) + tasks = [] + if result: + for line in result.split('\n'): + parts = line.split('||') + tasks.append({'name': parts[0], 'project': parts[1] if len(parts) > 1 else ''}) + return jsonify(success=True, data=tasks, count=len(tasks)) + except Exception as e: + return jsonify(success=False, error=str(e)), 500 + + +@app.route('/health') +def health(): + return jsonify(success=True, service='pkm-api', endpoints=[ + '/devonthink/stats', '/devonthink/search?q=', + '/devonthink/inbox-count', '/omnifocus/stats', '/omnifocus/overdue', '/omnifocus/today' + ]) + + +if __name__ == '__main__': + port = int(sys.argv[1]) if len(sys.argv) > 1 else 9900 + print(f'PKM API Server starting on port {port}') + app.run(host='127.0.0.1', port=port)