# 멀티 에이전트 LLM 운용 설계서 — 최종본 v3.1
## 작성: 2026-03-29

---

# 1. 최종 채택 모델

## 1.1 채택 목록
| 역할 | 모델 | 포트 | 컨텍스트 | 상태 | 비고 |
|------|------|------|----------|------|------|
| 메인/플래너/전처리/Analyst | Qwen3.5-35B-A3B-Claude-Opus-Distilled | 8080 | 262K | 상시 | 메인 fallback 포함 |
| Coder | Qwen3-Coder-Next-Q3_K_M | 8081 | 64K | 상시 | 코딩 전용 |
| QA | Qwen3.5-9B-Uncensored-HauhauCS-Aggressive | 8082 | 64K | 상시 | 코딩 검증 전용 |
| 특수 작업 | Qwen3.5-122B-A10B-MoE-IQ3_XXS | 8083 | 32K | 수동 | 필요 시만 로드 |
| Vision | Qwen3VL-8B-Uncensored-Q4_K_M | 8084 | 32K | 상시 | OCR/스크린샷/UI 이해 |
| 테스트 | (임시) | 8089 | - | 수동 | 모델 테스트용 |

## 1.2 선택 이유
- 35B: 전체 오케스트레이션/플래닝/분석에 가장 균형이 좋음
- Coder Next Q3: 상시 코딩 실행기로 VRAM 효율이 좋음
- 9B HauhauCS: QA 전용으로 가볍고 빠름
- 122B MoE: 고품질 특수 작업용, 상시는 비효율적이라 수동 로드
- Vision HauhauCS 8B: OCR/비전 비교에서 최종 승자

---

# 2. 에이전트 운용 아키텍처

## 2.1 핵심 원칙
| 원칙 | 설명 |
|------|------|
| 유료 토큰 절약 | 로컬 모델이 전처리/요약 → 유료는 최종 판단만 |
| 컨텍스트 계층 | 메인(전체) > 플래너(요약) > 실행기(지시만) |
| 시퀀셜 vs 병렬 | 메인↔플래너는 시퀀셜, 실행기는 병렬 |
| QA 루프 | 코딩 작업만 Coder↔QA 반복 |
| 특수 모델 분리 | 122B는 상시가 아니라 수동 로드 |

## 2.2 전체 구조
```text
사용자
  ↓
메인 (유료 또는 35B fallback)
  ↓
플래너 (35B)
  ↓
├─ Coder (Q3)
├─ QA (9B)
├─ Analyst (35B)
├─ WebQ (35B)
└─ Vision (Qwen3VL-8B-Uncensored)
```

---

# 3. 에이전트별 정의

## 3.1 메인 / 플래너 / Analyst / WebQ
- 모델: Qwen3.5-35B-A3B-Claude-Opus-Distilled
- 포트: 8080
- 컨텍스트: 262K
- 역할:
  1. 메인 fallback
  2. 플래너
  3. 전처리/압축
  4. Analyst
  5. WebQ

## 3.2 Coder
- 모델: Qwen3-Coder-Next-Q3_K_M
- 포트: 8081
- 컨텍스트: 64K
- 역할:
  1. 플래너 TODO 수신
  2. 자체 서브플랜 작성
  3. 코드 생성/수정
  4. 파일 반영
  5. 완료 보고

## 3.3 QA
- 모델: Qwen3.5-9B-Uncensored-HauhauCS-Aggressive
- 포트: 8082
- 컨텍스트: 64K
- 역할:
  1. 코드 실행 검증
  2. TODO 기준 PASS/FAIL 확인
  3. QA 리포트 반환

## 3.4 Vision
- 모델: Qwen3VL-8B-Uncensored-Q4_K_M
- 포트: 8084
- 컨텍스트: 32K
- 역할:
  1. OCR
  2. 스크린샷 분석
  3. UI 이해
  4. 시각 기반 판단 보조
- mmproj:
  - `mmproj-Qwen3VL-8B-Instruct-Q8_0.gguf`

## 3.5 특수 작업 모델
- 모델: Qwen3.5-122B-A10B-MoE-IQ3_XXS
- 포트: 8083
- 컨텍스트: 32K
- 역할:
  1. 복잡 설계 판단
  2. 고품질 코드 초안
  3. 장문 분석
  4. 다른 모델 실패 시 해결 카드

---

# 4. 작업 플로우

## 4.1 일반 대화
```text
사용자 → 메인 → 직접 응답
```

## 4.2 코딩 작업
```text
사용자 → 메인 → 플래너(35B)
  ↓
플래너 → TODO 작성
  ↓
Coder(Q3) → 구현
  ↓
QA(9B) → 검증
  ├─ PASS → 완료
  └─ FAIL → Coder 재작업
```

## 4.3 분석 작업
```text
사용자 → 메인 → 플래너
  ↓
Analyst(35B) → 분석/리포트
  ↓
메인 → 사용자 전달
```

## 4.4 비전 작업
```text
사용자 → 메인
  ↓
Vision(8084) → OCR / 스크린샷 분석 / UI 이해
  ↓
메인 → 사용자 전달
```

---

# 5. VRAM 시나리오

| 시나리오 | 로드 모델 | VRAM |
|----------|----------|------|
| 기본 상시 | 35B + Coder + QA + Vision | 약 76% |
| 분석 중심 | 35B + QA + Vision | 약 38% |
| 특수 작업 | 35B + 122B | 약 71% |

### 122B 사용 규칙
- Coder 결과가 최소 품질 기준 미달이거나 QA가 반복 FAIL 하면 122B 전환을 검토한다.
- 122B 로드 전에는 최소 Coder off
- 권장: **Coder + Vision off 후 122B 로드**
- 아주 무거운 작업이면 QA도 off 가능
- 전환 스크립트:
  - `~/llama.cpp/download/switch_to_122b.sh`
- 작업 종료 후:
  - QA까지 완료
  - 122B drop
  - Coder + Vision 재실행
  - 기본 상시 구성 복귀
- 복구 스크립트:
  - `~/llama.cpp/download/restore_default_workers.sh`

---

# 6. 설정 참고

## 6.1 모델 포트 매핑
| 포트 | 모델 | 용도 |
|------|------|------|
| 8080 | Qwen3.5-35B-A3B-Claude-Opus-Distilled | 메인/플래너/전처리/Analyst/WebQ |
| 8081 | Qwen3-Coder-Next-Q3_K_M | Coder |
| 8082 | Qwen3.5-9B-Uncensored-HauhauCS-Aggressive | QA |
| 8083 | Qwen3.5-122B-A10B-MoE-IQ3_XXS | 특수 작업 (수동 로드) |
| 8084 | Qwen3VL-8B-Uncensored-Q4_K_M | 비전 전용 |
| 8089 | (임시) | 테스트 |

## 6.2 서버 시작 명령어
```bash
# 35B main
cd ~/llama.cpp/download
nohup ../build/bin/llama-server \
  -m ./Qwen3.5-35B-MoE-Claude-Q4_K_M.gguf \
  -ngl 999 --flash-attn on \
  --cache-type-k q8_0 --cache-type-v q8_0 \
  --ctx-size 262144 \
  --port 8080 --host 0.0.0.0 --jinja &

# coder
nohup ../build/bin/llama-server \
  -m ./Qwen3-Coder-Next-Q3_K_M.gguf \
  -ngl 999 --flash-attn on \
  --cache-type-k q8_0 --cache-type-v q8_0 \
  --ctx-size 65536 \
  --port 8081 --host 0.0.0.0 --jinja &

# qa
nohup ../build/bin/llama-server \
  -m ./Qwen3.5-9B-Uncensored-HauhauCS-Q4_K_M.gguf \
  -ngl 999 --flash-attn on \
  --cache-type-k q8_0 --cache-type-v q8_0 \
  --ctx-size 65536 \
  --port 8082 --host 0.0.0.0 --jinja &

# vision
nohup ../build/bin/llama-server \
  -m ./Qwen3VL-8B-Uncensored-Q4_K_M.gguf \
  --mmproj ./mmproj-Qwen3VL-8B-Instruct-Q8_0.gguf \
  -ngl 999 --flash-attn on \
  --cache-type-k q8_0 --cache-type-v q8_0 \
  --ctx-size 32768 \
  --port 8084 --host 0.0.0.0 --jinja &
```

## 6.3 다운로드된 최종 모델 파일
```text
~/llama.cpp/download/
├── Qwen3.5-35B-MoE-Claude-Q4_K_M.gguf ← 메인
├── Qwen3-Coder-Next-Q3_K_M.gguf ← Coder
├── Qwen3.5-9B-Uncensored-HauhauCS-Q4_K_M.gguf ← QA
├── Qwen3.5-122B-MoE-IQ3_XXS.gguf ← 특수 작업
├── Qwen3VL-8B-Uncensored-Q4_K_M.gguf ← 비전 메인
└── mmproj-Qwen3VL-8B-Instruct-Q8_0.gguf ← 비전 프로젝터
```

## 6.4 모델별 --ctx-size
| 모델 | --ctx-size | 비고 |
|------|------------|------|
| Qwen3.5-35B-A3B-Claude-Opus-Distilled | 262144 (262K) | 메인/fallback |
| Qwen3-Coder-Next-Q3_K_M | 65536 (64K) | Coder |
| Qwen3.5-9B-Uncensored-HauhauCS-Aggressive | 65536 (64K) | QA |
| Qwen3VL-8B-Uncensored-Q4_K_M | 32768 (32K) | Vision |
| Qwen3.5-122B-A10B-MoE-IQ3_XXS | 32768 (32K) | 특수 작업 |

---

# 7. 운영 메모
- HuggingFace 다운로드는 `hf` CLI 우선 사용
- SSH 작업은 가능하면 sshterminal MCP 세션 우선 사용
- 벤치/탈락 모델 정보는 `benchmark_model.md` 참고