feat: local AI server scaffolding (FastAPI, RAG, embeddings). Port policy (>=26000), README/API docs, scripts.

2025-08-13 07:24:06 +09:00
commit 72d889f5ef
15 changed files with 2486 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,206 @@
+### 로컬 AI 서버 (Mac mini M4 Pro 64GB)
+
+이 저장소는 Apple Silicon(M4 Pro, RAM 64GB) 환경에서 로컬 AI 모델을 실행해 API 서버로 활용하기 위한 기본 구성과 가이드를 제공합니다.
+
+## 현재 설치 상태
+
+- **러너**: Ollama 0.11.4 확인됨
+- **Ollama 로컬 모델**:
+  - qwen2.5:1.5b
+  - mistral:7b
+- **LM Studio 로컬 모델**:
+  - gemma-3-4b-it
+
+## 하드웨어 요약 (권장 기준)
+
+- **칩셋**: Apple M4 Pro (Metal/ANE 가속 활용 가능)
+- **메모리**: 64GB 통합 메모리
+- **권장 동시성**: 1–3 세션(프롬프트 길이에 따라 조절)
+
+## 권장 모델 (M4 Pro 64GB)
+
+- **일반 대화/업무**
+  - Llama 3.1 8B Instruct: 품질·속도 밸런스 좋음, 긴 문서 요약/대화에 적합
+  - Qwen2.5 7B Instruct: 정보 회수/한글 대응 우수, 속도 양호
+  - Mistral 7B Instruct: 경량/속도 지향, 기본 품질 안정적
+  - Gemma 2 9B IT: 간결한 답변과 대화 품질 균형
+
+- **코딩 보조**
+  - Qwen2.5-Coder 7B: 코드 생성/수정/해설에 실용적, 메모리 요구도 낮음
+  - DeepSeek-Coder 6.7B 또는 16B(Lite): 코드 품질 강점, 16B는 속도·메모리 여유 필요
+
+- **초경량**
+  - Phi-3.5/3.1 Mini(3–4B): 간단 질의응답/요약, 서버 부하가 낮음
+
+- 참고: 14–32B급도 구동 가능하나(예: Qwen2.5 14B/32B), 긴 컨텍스트/동시성 시 메모리 여유가 적어질 수 있음. 70B급은 64GB 환경에서 가능하더라도 속도·안정성 상 비권장.
+
+## 설치 (Ollama)
+
+아래 명령으로 권장 모델을 내려받을 수 있습니다. 태그는 상황에 따라 업데이트될 수 있으니 `ollama run <model>` 시 안내를 확인하세요.
+
+```bash
+# 일반 대화
+ollama pull llama3.1:8b-instruct
+ollama pull qwen2.5:7b-instruct
+ollama pull mistral:7b
+ollama pull gemma2:9b-instruct
+
+# 코딩 보조
+ollama pull qwen2.5-coder:7b
+ollama pull deepseek-coder:6.7b
+
+# 초경량
+ollama pull phi3:mini
+```
+
+이미 설치된 모델 확인:
+
+```bash
+ollama list
+```
+
+모델 실행(대화형 테스트):
+
+```bash
+ollama run qwen2.5:7b-instruct
+```
+
+## REST API로 바로 쓰기 (Ollama 내장 서버)
+
+Ollama는 기본적으로 `http://localhost:11434`에서 API를 제공합니다.
+
+```bash
+# 단발성 텍스트 생성
+curl http://localhost:11434/api/generate \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "qwen2.5:7b-instruct",
+    "prompt": "한국어로 이 모델의 장점을 3가지로 요약해줘",
+    "stream": false
+  }'
+
+# Chat 형식
+curl http://localhost:11434/api/chat \
+  -H "Content-Type: application/json" \
+  -d '{
+    "model": "llama3.1:8b-instruct",
+    "messages": [
+      {"role": "user", "content": "로컬 LLM 서버 운영 팁을 알려줘"}
+    ],
+    "stream": false
+  }'
+```
+
+TIP: 긴 문서를 다루려면 `num_ctx`(컨텍스트 길이)와 `num_thread`를 모델/하드웨어에 맞춰 조정하세요. 과도하게 늘리면 속도와 메모리 사용량이 크게 증가합니다.
+
+## 포트 정책
+
+- **AI 서버 표준 포트**: 26000 이상 사용 권장 (예: 26000)
+- 환경 변수 `AI_SERVER_PORT`로 조정 가능. 기본값 26000.
+
+개발 서버 실행 스크립트(`scripts/dev_server.sh`)는 위 정책을 따릅니다.
+
+## API 개요 (Paperless/시놀로지 연동)
+
+- 기본 베이스 모델(24/7): `BASE_MODEL` (기본: `qwen2.5:7b-instruct`)
+- 온디맨드 부스팅 모델: `BOOST_MODEL` (기본: `qwen2.5:14b-instruct`)
+- 임베딩(RAG): `EMBEDDING_MODEL` (기본: `nomic-embed-text`), 인덱스 파일 `INDEX_PATH` (기본: `data/index.jsonl`)
+- 문서화: `http://localhost:26000/docs` (FastAPI 자동 문서)
+
+### 헬스체크
+
+```bash
+curl -s http://localhost:26000/health
+```
+
+### 검색(Search, RAG용)
+
+```bash
+curl -s -X POST http://localhost:26000/search \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "query": "질문 내용",
+    "top_k": 5
+  }'
+```
+
+### 채팅(Chat, RAG/부스팅 자동)
+
+```bash
+curl -s -X POST http://localhost:26000/chat \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "messages": [
+      {"role": "user", "content": "문서 내용 기반으로 요약해줘"}
+    ],
+    "use_rag": true,
+    "top_k": 5,
+    "force_boost": false,
+    "options": {"num_ctx": 32768, "temperature": 0.3}
+  }'
+```
+
+필드 설명:
+- `use_rag`: 인덱스(`INDEX_PATH`)에서 상위 청크를 검색해 시스템 프롬프트로 주입
+- `force_boost`: 강제로 부스팅 모델 사용(고난도/장문)
+- `options`: Ollama 옵션(예: `num_ctx`, `temperature` 등)
+
+### 인덱스 갱신(Upsert)
+
+Paperless/시놀로지에서 추출한 본문 텍스트를 직접 인덱스에 추가합니다.
+
+```bash
+curl -s -X POST http://localhost:26000/index/upsert \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "rows": [
+      {"id": "paperless:123", "text": "문서 본문 텍스트", "source": "paperless"}
+    ],
+    "embed": true
+  }'
+```
+
+### 인덱스 리로드
+
+```bash
+curl -s -X POST http://localhost:26000/index/reload
+```
+
+### Paperless 훅(Webhook) 자리표시자
+
+```bash
+curl -s -X POST http://localhost:26000/paperless/hook \
+  -H 'Content-Type: application/json' \
+  -d '{"document_id": 123, "title": "문서제목", "tags": ["finance"]}'
+```
+
+해당 훅은 문서 도착을 통지받는 용도로 제공됩니다. 실제 본문 텍스트는 Paperless API로 조회해 `/index/upsert`로 추가하세요.
+
+## 시놀로지 메일/오피스 연동 가이드(요약)
+
+- **검색/QA 호출 엔드포인트**: `http://<AI서버IP>:26000/search`, `http://<AI서버IP>:26000/chat`
+- **권장 흐름**:
+  - 메일/문서 본문 → `/index/upsert`로 인덱스 추가(임베딩 생성)
+  - 사용자 질의 → `/chat` 호출(`use_rag=true`) → 관련 청크 Top-k 주입 후 응답
+- **모델 라우팅**:
+  - 기본: 베이스 모델(7B/8B)
+  - 장문/고난도: `force_boost=true` 또는 메시지 길이에 따라 자동 부스팅(14B)
+
+## 환경 변수
+
+- `AI_SERVER_PORT`(기본 26000): 서버 포트
+- `OLLAMA_HOST`(기본 `http://localhost:11434`): Ollama API 호스트
+- `BASE_MODEL`(기본 `qwen2.5:7b-instruct`)
+- `BOOST_MODEL`(기본 `qwen2.5:14b-instruct`)
+- `EMBEDDING_MODEL`(기본 `nomic-embed-text`)
+- `INDEX_PATH`(기본 `data/index.jsonl`)
+- `PAPERLESS_BASE_URL`, `PAPERLESS_TOKEN`(선택): Paperless API 연동 시 사용
+
+## 이 저장소 사용 계획
+
+1) Ollama API를 감싸는 경량 서버(Express 또는 FastAPI) 추가
+2) 표준화된 엔드포인트(`/v1/chat/completions`, `/v1/completions`) 제공
+3) 헬스체크/모델 선택/리밋/로깅 옵션 제공
+
+우선 본 문서로 설치/선택 가이드를 정리했으며, 다음 단계에서 서버 스켈레톤과 샘플 클라이언트를 추가할 예정입니다.
+