# Windows 기반 대규모 언어 모델(LLM) API 서버 구축 보고서

해당 문서는 VRAM이 제한적인 환경(12GB)에서 수십~수백억 단위의 파라미터를 가진 MoE(Mixture of Experts) 모델을 오프로딩 기법을 통해 원활하게 추론하기 위한 최적화 및 구축 내역을 록킹한 문서입니다.

## 1. 하드웨어 환경 및 목표
* **GPU**: NVIDIA RTX 3060 (VRAM 12GB) 1대 (총 12GB VRAM 제약 환경)
* **CPU RAM**: 96GB (충분한 오프로딩 용량 보유)
* **목표**: Ollama를 사용하지 않고, OpenAI API 규격과 100% 호환되는 Llama.cpp 독립 추론망을 구축하여 35B~122B급의 모델을 구동 및 성능(30-40 t/s) 확보.

## 2. 파일 및 환경 구성 내역 `Desktop\variet-llm`
* **Python 구동 환경**: `C:\ProgramData\miniforge3\envs\variet-llm`
* **엔진**: `llama_bin_run` 디렉토리에 가장 최적화된 최신 버전의 `llama-server.exe` (CUDA 12.4 CUBLAS 가속 지원) 설치 완료.
* **모델 파일 적재 (`models/`)**: 
  - `gemma-4-26B-A4B-it-Q4_K_M.gguf` (약 16.7GB)
  - `Qwen3.5-35B-A3B-Q4_K_M.gguf` (약 22GB)
  - `Q4_K_M/Qwen3.5-122B-A10B-Q4_K_M` 분할 패키지 (약 76GB)

## 3. 적용된 핵심 최적화 세팅 (12GB VRAM 특화)
12GB VRAM에서 OOM(Out of Memory)을 방지하고 Qwen 35B의 MoE 아키텍처에서 30 t/s 이상의 쾌적한 속도를 내기 위해 다음 튜닝을 기입했습니다.
1. **GPU 레이어 분할 적재 (`--n-gpu-layers 20`)**:
   모든 모델을 VRAM 구겨 넣으려다 터지는 것을 막기 위해, 최적의 효율을 내는 주의력 레이어 위주로 VRAM에 올리고, 거대한 FFN/Expert 텐서는 방대한 96GB 시스템 램으로 병렬 오프로딩합니다.
2. **Flash Attention 활성화 (`-fa on`)**:
   256K와 같은 방대한 컨텍스트(문맥) 주입 시 하드웨어 연산 레지스터를 초과해 뻗는 것을 막고 처리 속도를 비약적으로 가속합니다.
3. **KV Cache 4비트 양자화 (`--cache-type-k q4_0 --cache-type-v q4_0`)**:
   문맥 데이터를 저장하는 VRAM Cache 용량을 최대 80% 압축시킵니다.
4. **MoE 배치 통신 해제 (`-ub 512 -b 512`)**:
   CPU 램 오프로딩 시 필연적으로 발생하는 CPU-GPU간 텐서 교환 대기(병목) 지연을 줄이기 위해 물리적/논리적 배치 묶음 사이즈를 튜닝했습니다.
   
## 4. 실행 및 테스트 방법
모든 배치파일은 한글 인코딩 깨짐 에러를 방지하기 위해 영문 호환 코드로 작성되었습니다.

1. **서버 시작**: 
   - `start_qwen_35b_api.bat` (Qwen 35B 구동 시) 
   - `start_qwen_122b_api.bat` (Qwen 122B 구동 시)
   - `start_gemma4_26b_api.bat` (Gemma 26B 구동 시)
2. **성능 테스트 검증**:
   서버 도스창이 `listening on http://0.0.0.0:8000`를 띄우면,
   - `run_test.bat` (또는 `perf_test.py`)를 실행하여 인위적인 대규모 프롬프트 테스트 트래픽을 API로 주입하고, 서버 도스창 하단의 `t/s (Tokens Per Second)` 출력 속도를 모니터링하여 검증합니다.
