From 6d8d2076692c08568cd7a615e83a253f1e01e314 Mon Sep 17 00:00:00 2001 From: Hyungi Ahn Date: Tue, 12 May 2026 15:03:52 +0900 Subject: [PATCH] docs(readme): refresh stack/features/infra to 2026-05 reality MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - AI: Qwen3.5-35B → gemma-4 26B MLX / 4B triage / bge-m3 / TEI reranker / Surya OCR / MLX Whisper - infra: Mac mini Docker Compose → GPU 서버 메인 / Mac mini = MLX inference + STT - features: 아침 브리핑, Phase 4 Digest, library, memos, events, study, audio/video, marker - inventory authoritative 안내 (README 가 stale 진실 대신 inventory 우선) - gpu-server/ deprecated 표기 --- README.md | 118 +++++++++++++++++++++++++++++++++++++----------------- 1 file changed, 81 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 5be274d..5ede7f1 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,108 @@ # hyungi_Document_Server -Self-hosted 개인 지식관리(PKM) 웹 애플리케이션 +Self-hosted 개인 지식관리(PKM) + 다국 뉴스 비교 분석 웹 애플리케이션. + +> 모델 이름·엔드포인트·머신 정보는 운영 상태에 따라 변하므로 README 에 박지 않습니다. +> 운영 단일 진실 소스(SSOT): `~/.claude/projects/-Users-hyungiahn/memory/infra_inventory.md`. +> 모델/엔드포인트/포트/SSH 어디서든 README 와 inventory 가 충돌하면 **inventory 가 정답**입니다. ## 기술 스택 -- **백엔드**: FastAPI + SQLAlchemy (async) -- **데이터베이스**: PostgreSQL 16 + pgvector + pg_trgm -- **프론트엔드**: SvelteKit -- **문서 파싱**: kordoc (HWP/HWPX/PDF → Markdown) -- **AI**: Qwen3.5-35B-A3B (MLX), nomic-embed-text, Claude API (폴백) -- **인프라**: Docker Compose, Caddy, Synology NAS +- **백엔드**: FastAPI + SQLAlchemy 2.0 async, APScheduler cron +- **DB**: PostgreSQL 16 + pgvector + pg_trgm (단일 `pkm` DB) +- **프론트엔드**: SvelteKit 5 (runes mode) + Tailwind CSS 4 +- **문서 파싱**: kordoc 마이크로서비스 (HWP/HWPX/PDF → Markdown), LibreOffice headless (오피스), marker (PDF → markdown Phase 1B) +- **AI 파이프라인** (역할별, 자세한 모델 매핑은 inventory): + - 분류/요약 본체: Mac mini MLX 26B (primary) + - Triage / fallback / chat: GPU Ollama 4B + - Embedding: GPU Ollama `bge-m3` (1024d) + - Reranker: GPU TEI 컨테이너 `bge-reranker-v2-m3` + - OCR: docker compose `ocr-service` (Surya OCR GPU) + - STT: Mac mini MLX Whisper large-v3 + - Premium (수동 trigger): Anthropic Claude (`require_explicit_trigger`) +- **인증**: JWT (access) + HttpOnly cookie (refresh) + TOTP 2FA +- **인프라**: Docker Compose, Caddy (HTTP only, 앞단 home-caddy 가 HTTPS 종료), Synology NAS NFS ## 주요 기능 -- 문서 자동 분류/태그/요약 (AI 기반) -- 전문검색 + 벡터 유사도 검색 -- HWP/PDF/Markdown 문서 뷰어 -- 법령 변경 모니터링 (산업안전보건법 등) -- 이메일 자동 수집 (MailPlus IMAP) -- 일일 다이제스트 -- CalDAV 태스크 연동 (Synology Calendar) +- **문서 자동 분류/태그/요약** — Triage(4B) → Deep summary(26B) tier 분리, 백로그 guard / 텍스트 슬라이스 / inconsistency 감지 +- **하이브리드 검색** — pgvector 벡터 + pg_trgm 전문검색 + reranker (bge-reranker-v2-m3) + Ask pipeline (HyDE / evidence_service) +- **다국어 OCR** — Surya OCR GPU (한/영/일/중/독/불 등), NFC/NFD 경로 정규화 +- **음성/영상 전사** — MLX Whisper large-v3, `/audio` `/video` 라우트 + direct play +- **법령 변경 모니터링** — `law_monitor` cron, freshness decay (365일 반감기) +- **이메일 자동 수집** — MailPlus IMAP, NFS 저장 +- **Phase 4 Global Digest** — 매일 04:00 KST 7일 rolling 뉴스 country×topic 2-level 비교 (`/digest`) +- **야간 뉴스 브리핑** — 매일 05:10 KST KST 자정~05:00 5시간 윈도우, topic×country 비교 분석 1페이지 카드 (`/news`) +- **자료실 (Library)** — 카테고리 facet 분류 + AI 제안 1-click 승인 +- **메모/이벤트/공부** — 5초 행동 기록 메모, 일정/할 일/회고 events 도메인, 가스기사 학습 워크스페이스 (274 개념 + 2,100 기출) +- **마크다운 canonical layer** — extracted_images NAS 저장 + `document_images` 메타 + 단기 토큰 인증 (`?token=`) ## Quick Start ```bash -git clone https://git.hyungi.net/hyungi/hyungi_document_server.git hyungi_Document_Server -cd hyungi_Document_Server +git clone https://git.hyungi.net/hyungi/hyungi_document_server.git +cd hyungi_document_server -# 인증 정보 설정 +# 인증 정보 (DB 비밀번호, JWT secret, Claude API key 등) cp credentials.env.example credentials.env -nano credentials.env # 실제 값 입력 +$EDITOR credentials.env -# 실행 -docker compose up -d +# AI 모델 / 엔드포인트 / 경로 +$EDITOR config.yaml # inventory 참조하면서 채움 +$EDITOR .env # POSTGRES_PASSWORD, MAC_MINI_HOST, NAS_NFS_PATH 등 + +docker compose up -d --build ``` -`http://localhost:8000/docs` 에서 API 문서 확인 +운영 도메인 (GPU 서버 배포 기준): `https://document.hyungi.net` +API 문서: `https://document.hyungi.net/docs` ## 디렉토리 구조 ``` -├── app/ FastAPI 백엔드 (API, 워커, AI 클라이언트) -├── frontend/ SvelteKit 프론트엔드 -├── services/kordoc/ 문서 파싱 마이크로서비스 (Node.js) -├── gpu-server/ GPU 서버 배포 (AI Gateway) -├── migrations/ PostgreSQL 스키마 -├── docs/ 설계 문서, 배포 가이드 -└── tests/ 테스트 코드 +├── app/ FastAPI 백엔드 +│ ├── api/ 라우터 (documents, search, briefing, digest, memos, events, study, …) +│ ├── workers/ APScheduler / queue (briefing_worker, digest_worker, classify_worker, …) +│ ├── services/ 도메인 로직 (briefing/, digest/, search/, clustering_common, …) +│ ├── ai/client.py AIClient (call_triage / call_primary / call_fallback, parse_json_response) +│ ├── prompts/ *.txt 프롬프트 (분류, 요약, briefing_comparative, digest_topic, …) +│ ├── policy/ AI envelope + prompt_render +│ └── models/ SQLAlchemy ORM +├── frontend/ SvelteKit 5 (runes mode) + Tailwind +│ └── src/routes/ /news (아침 브리핑) /library /memos /audio /video /study /digest /ask … +├── services/ +│ ├── kordoc/ HWP/HWPX/PDF 파싱 (Node.js) +│ ├── ocr/ Surya OCR GPU 서비스 (FastAPI) +│ └── marker/ PDF → markdown Phase 1B +├── migrations/ 255+ SQL migrations (schema_migrations 추적) +├── docs/ 설계 문서 +└── tests/ pytest ``` -## 인프라 구성 +`gpu-server/` 폴더는 v1 잔재로 deprecated (현재 AI Gateway 는 `~/home-gateway/` 별 repo). -| 서버 | 역할 | -|------|------| -| Mac mini M4 Pro | Docker Compose (FastAPI, PostgreSQL, kordoc, Caddy) + MLX AI | -| Synology NAS | 파일 원본 저장, Synology Office/Drive/Calendar/MailPlus | -| GPU 서버 | AI Gateway, 벡터 임베딩, OCR, 리랭킹 | +## 인프라 구성 (운영 기준) + +| 머신 | 역할 | +|---|---| +| **GPU 서버** (메인) | Docker Compose (fastapi, frontend, postgres pkm, kordoc, ocr-service, marker-service, reranker(TEI), caddy), Ollama (`bge-m3`, 4B chat), home-gateway 별 compose | +| **Mac mini** | MLX 26B primary 추론 + MLX Whisper STT (HTTP 추론 endpoint only, ingress 역할 0) | +| **Synology NAS** | 파일 원본 (`/volume4/Document_Server/PKM/`), Synology Office/Drive/Calendar/MailPlus, NFS export → GPU | +| **VPS-2** (OVH) | 메일 relay (`relay.hyungi.net:587` SASL+TLS+DKIM+LE), Gitea bare mirror, Secondary MX | + +상세 IP / 모델 / 컨테이너 / drift / verify 명령은 `infra_inventory.md` 참조. + +## 운영 변경 정책 + +1. inventory 먼저 갱신 +2. `config.yaml` / `credentials.env` 갱신 +3. deploy (commit → push Gitea → GPU `git pull && docker compose up -d --build`) +4. verify (smoke endpoints, postgres count, 모니터링) + +순서를 어기면 drift. drift 발견 시 `infra_inventory.md` 의 Drift Log 에 등록 후 정정. ## 문서 -- [아키텍처](docs/architecture.md) — 전체 시스템 설계 -- [배포 가이드](docs/deploy.md) — Docker Compose 배포 방법 -- [개발 단계](docs/development-stages.md) — Phase 0~5 개발 계획 +- [아키텍처](docs/architecture.md) — DB 스키마, AI 전략, UI 설계 +- [배포 가이드](docs/deploy.md) — Docker Compose 배포 +- [개발 단계](docs/development-stages.md) — Phase 별 roadmap (Phase 4 Global Digest / 야간 브리핑 등 신규 phase 는 inventory + plan 파일 우선)