# TrueNAS SCALE GPU passthrough setup
# 1. TrueNAS UI에서 VM/장치 패스스루 활성화
#    System → Advanced →

-   **저장소 위치(Storage Location):** 모델 영속성(persistence)을 위해 스토리지 풀(Storage Pool) 사용 (/mnt/Storage_Pool/models)
-   **구성:** 유형별로 폴더 생성: llm/, embedding/, vision/
-   **버전 관리(Versioning):** 다른 양자화(quantization) 버전을 위해 하위 폴더 사용 (q4_K_M, q5_K_M 등)
-   **심볼릭 링크(Symlinks):** Ollama의 모델 디렉터리를 구성된 스토리지로 연결
-   **백업:** 실험 안전을 위한 모델 데이터셋 스냅샷

### 2. ComfyUI / Automatic1111 (이미지 생성)

#### 왜 Automatic1111보다 ComfyUI인가?

-   **향상된 리소스 제어(Better resource control):** 세밀한 VRAM 관리
-   **워크플로우 기반(Workflow-based):** 재현 가능하고 공유 가능한 생성 파이프라인
-   **낮은 오버헤드(Lower overhead):** 전체 WebUI보다 복잡도가 낮음
-   **API 우선(API-first):** n8n 및 기타 자동화와 통합하기 쉬움
-   **TrueNAS 친화적(TrueNAS-friendly):** 시스템 서비스와의 충돌 가능성이 적음

#### 배포 구성(Deployment Configuration)

#### ComfyUI 모델 구성

-   **체크포인트(Checkpoints):** /mnt/Storage_Pool/comfyui-models/checkpoints/
-   **LoRA:** /mnt/Storage_Pool/comfyui-models/loras/
-   **ControlNet:** /mnt/Storage_Pool/comfyui-models/controlnet/
-   **VAE:** /mnt/Storage_Pool/comfyui-models/vae/
-   **임베딩(Embeddings):** /mnt/Storage_Pool/comfyui-models/embeddings/
-   **업스케일러(Upscalers):** /mnt/Storage_Pool/comfyui-models/upscale/

### 3. LiteLLM (다중 제공자용 프록시/레이어)

#### 왜 LiteLLM을 사용해야 하는가?

-   **제공자 폴백(Provider fallback):** Ollama 실패 시, 로컬 Llama.cpp 또는 원격 API 시도
-   **로드 밸런싱(Load balancing):** 여러 인스턴스로 요청 분산
-   **비용 추적(Cost tracking):** 유료 API의 사용량 및 비용 모니터링
-   **표준 인터페이스(Standardized interface):** 모든 제공자를 위한 OpenAI 호환 엔드포인트
-   **캐시 레이어(Cache layers):** 반복 요청을 위한 Redis 캐싱
-   **보안(Security):** API 키 관리 및 속도 제한(rate limiting)

#### 일반적인 구성(Typical Configuration)

### 4. Qdrant (RAG용 벡터 데이터베이스)

#### Qdrant를 선택해야 하는 이유?

-   **TrueNAS 친화적:** 공식 앱 제공
-   **성능:** 벡터 검색에 최적화됨
-   **확장성:** 수백만 개의 벡터를 효율적으로 처리함
-   **기능:** 필터링, 페이로드(payload) 저장, 하이브리드 검색
-   **쉬운 통합:** LangChain, LlamaIndex, 사용자 지정 코드와 연동됨
-   **백업 친화적:** 스냅샷 및 내보내기가 잘 작동함

#### 배포 및 사용법

### 5. LangFuse (LLM 관측성)

#### LLM을 관측해야 하는 이유?

-   **비용 추적:** 토큰 사용량 및 지출 모니터링
-   **성능:** 지연 시간(latency) 및 처리량(throughput) 측정
-   **품질:** 환각(hallucinations), 오류, 사용자 피드백 추적
-   **디버깅:** 복잡한 체인(chain) 및 에이전트 워크플로우 추적
-   **최적화:** 병목 현상 및 비효율적인 패턴 식별
-   **규정 준수:** 규제 산업을 위한 감사 추적(audit trails)

#### 배포 설정

### 6. N8n (워크플로우 오케스트레이션)

#### AI 워크플로우에 N8n을 사용해야 하는 이유?

-   **시각적 워크플로우:** 이해하고 수정하기 쉬움
-   **수백 개의 통합:** LLM, API, 데이터베이스, 파일 등에 연결 가능
-   **내장 스케줄링:** Cron과 유사한 방식으로 워크플로우 트리거
-   **오류 처리:** 재시도 정책(retry policies), 오류 워크플로우, 알림 기능
-   **사용자 지정 노드:** 전문적인 작업을 위해 JavaScript 또는 Python 작성 가능
-   **웹훅 트리거:** 외부 이벤트로부터 워크플로우 시작
-   **TrueNAS 검증:** TrueNAS 커뮤니티에서 잘 정착됨

#### 예시 AI 워크플로우

## 데이터 관리 및 스토리지 전략

최적의 성능과 신뢰성을 위해 무엇을 어디에 배치해야 하는가:

### NVMe 풀 (고성능)

**사용처:**

- 운영 체제 및 TrueNAS SCALE
- 애플리케이션 컨테이너 및 이미지
- 자주 접근하는 모델 파일 (활성 LLM)
- 벡터 데이터베이스 작업 세트 (Qdrant RAM 캐시 오버플로우)
- 임시 처리 공간
- 빠른 쓰기가 필요한 로그 및 메트릭

**예시 경로:**

-   /mnt/nvme-pool/apps/ - 컨테이너 애플리케이션 데이터
-   /mnt/nvme-pool/models/active/ - 현재 로드된 모델
-   /mnt/nvme-pool/logs/ - 애플리케이션 로그
-   /mnt/nvme-pool/cache/ - Redis, 임시 파일

### 스토리지 풀 (용량 및 신뢰성)

**사용 용도:**

-   모든 모델의 마스터 복사본 (양자화 버전)
-   학습 데이터셋 및 아카이브
-   생성된 출력물 (이미지, 텍스트 등)
-   장기 백업 및 스냅샷
-   벡터 데이터베이스 영구 저장소
-   ComfyUI 워크플로우용 미디어 에셋
-   RAG 시스템용 문서 라이브러리

**예시 경로:**

-   /mnt/Storage_Pool/models/ - 모든 모델 버전
-   /mnt/Storage_Pool/datasets/ - 학습 데이터
-   /mnt/Storage_Pool/generated/ - AI 출력물
-   /mnt/Storage_Pool/qdrant/ - 벡터 DB 저장소
-   /mnt/Storage_Pool/documents/ - 원본 문서
-   /mnt/Storage_Pool/comfyui/ - 입력/출력/미디어

### 백업 전략:

AI 투자를 보호하세요:

-   **모델:** Storage Pool/model 데이터셋 스냅샷 (월별)
-   **데이터:** 문서 라이브러리 스냅샷 (주간)
-   **구성:** 앱 구성 내보내기 및 버전 관리에 저장
-   **생성 콘텐츠:** 출력 디렉토리 스냅샷 (필요에 따라)
-   **벡터 데이터베이스:** Qdrant 스냅샷 + 정기 내보내기
-   **테스트 복원:** 백업 무결성 확인을 위한 분기별 훈련

## 보안 및 접근 제어

AI Ops 플랫폼을 안전하게 유지하는 방법:

### 네트워크 보안:

### 네트워크 보안 (Network Security):

-   **네트워크 분할 (Network segmentation):** AI 서비스를 격리된 VLAN에 배치합니다.
-   **방화벽 규칙 (Firewall rules):** 필요한 포트(프록시용 HTTP/HTTPS)만 허용합니다.
-   **Fail2ban:** 서비스의 무차별 대입 공격(brute-force attempts)을 차단합니다.
-   **CrowdSec:** 커뮤니티 기반 IP 평판 차단 기능을 사용합니다.
-   **NGINX Proxy Manager:** 중앙 집중식 TLS 종료 및 접근 제어를 수행합니다.
-   **내부 통신 (Internal communications):** 사설 네트워크에서 서비스 간 통신을 허용합니다.
-   **원격 접속 (Remote access):** TrueNAS에 내장된 Tailscale/ZeroTier 또는 VPN을 사용합니다.

### 애플리케이션 보안 (Application Security):

-   **컨테이너 격리 (Container isolation):** 각 앱은 자체적으로 격리된 환경에서 실행됩니다.
-   **최소 권한 원칙 (Least privilege):** 가능한 경우 컨테이너를 비(非)루트(non-root)로 실행합니다.
-   **리소스 제한 (Resource limits):** CPU/RAM 제한을 통해 리소스 독점(noisy neighbors)을 방지합니다.
-   **읽기 전용 루트 (Read-only root):** 지원되는 경우 컨테이너 루트를 읽기 전용으로 마운트합니다.
-   **시크릿 관리 (Secrets management):** TrueNAS에 내장된 시크릿 또는 외부 볼트(vault)를 사용합니다.
-   **정기 업데이트 (Regular updates):** 보안 패치를 추적하고 적용합니다.
-   **취약점 스캐닝 (Vulnerability scanning):** 컨테이너 이미지를 주기적으로 스캔합니다.

### 데이터 보안 (Data Security):

-   **저장 시 암호화 (Encryption at rest):** 민감한 데이터셋에 대해 ZFS 네이티브 암호화를 사용합니다.
-   **접근 제어 (Access controls):** 데이터셋에 POSIX 권한 및 ACL(Access Control Lists)을 적용합니다.
-   **감사 로깅 (Audit logging):** 누가 어떤 데이터에 접근했는지 추적합니다.
-   **데이터 분류 (Data classification):** 민감도별로 데이터셋에 레이블을 지정합니다(공개/내부/기밀). 
-   **모델 보안 (Model security):** 다운로드된 모델의 출처(provenance)를 확인합니다.
-   **출력 필터링 (Output filtering):** 생성된 콘텐츠가 부적절한 자료인지 검사합니다.
-   **PII 처리 (PII handling):** 개인 정보를 포함하는 데이터셋에 대한 특별 절차를 마련합니다.