Upload howtorun.md

vllm/howtorun.md

@@ -0,0 +1,94 @@
+# Solon-MoE vLLM 실행 상세 가이드 (한글)
+
+
+## 0. 사전 조건
+
+- merged 모델 디렉토리 (예: `/media/models/solon_moe_p6/merged`) — 안에 `modeling_solon_moe.py`와 `config.json`(auto_map 포함)이 있어야 합니다
+- **`generation_config.json`에 eos_token_id 106 포함** (이미 패치하셨지만, 새 merge마다 재확인):
+
+```bash
+grep 106 /media/models/solon_moe_p6/merged/generation_config.json
+# 안 나오면: eos_token_id 리스트에 106(<turn|>) 추가 — 없으면 응답이 멈추지 않고 퇴행 반복
+```
+
+## 1. 서빙 플러그인 설치 (최초 1회)
+
+vLLM은 커스텀 아키텍처(`SolonMoEForCausalLM`)를 모르므로, 층 선택 shim을 entry-point로 등록해야 `vllm serve`가 자동 인식합니다:
+
+```bash
+mkdir -p ~/solon_vllm_plugin && cd ~/solon_vllm_plugin
+cp /media/models/layer_exp3/vllm_solon_moe.py .      # 신식 서명 최종본이어야 함
+# pyproject.toml 작성 (릴리즈 패키지 vllm/pyproject.toml 그대로)
+pip install -e .
+```
+
+설치 확인:
+
+```bash
+python3 -c "from vllm import ModelRegistry; import vllm_solon_moe; vllm_solon_moe.register(); print('SolonMoEForCausalLM' in ModelRegistry.get_supported_archs())"
+# True 나와야 정상
+```
+
+## 2. 서버 기동
+
+```bash
+SOLON_LAMBDA=0.10 CUDA_VISIBLE_DEVICES=0 \
+vllm serve /media/models/solon_moe_p6/merged \
+    --trust-remote-code \
+    --max-model-len 8192 \
+    --gpu-memory-utilization 0.85 \
+    --max-num-seqs 32 \
+    --attention-backend TRITON_ATTN \
+    --port 8000
+```
+
+각 인자의 이유:
+
+| 인자 | 이유 |
+|---|---|
+| `SOLON_LAMBDA=0.10` | 체크포인트의 λ는 학습값 0.15 — 추론 규약 0.10을 로드 시점에 덮어씀 (사본 생성 불필요). **빼먹으면 0.15로 돌아 품질 열화** |
+| `--trust-remote-code` | modeling shim 로드에 필수 |
+| `--attention-backend TRITON_ATTN` | Blackwell(sm120)에서 FlashInfer decode 커널이 이 head 구성 미지원(`max_mma_kv: 0` 크래시). 환경변수 `VLLM_ATTENTION_BACKEND`는 현 버전에서 **제거됨** — CLI 인자만 유효 |
+| `--max-num-seqs 32` | FlashInfer workspace 한계(394MiB) 회피 + 개인 서빙 적정 동시성 |
+| `CUDA_VISIBLE_DEVICES=0` | 단일 GPU 원칙 (듀얼 풀부하 금지 규칙) |
+
+## 3. 기동 로그 검증 3종
+
+1. `SolonMoEForCausalLM` 인식 — "old-style model class" 경고가 **없어야** 함 (뜨면 구버전 shim — 신식 서명본으로 교체)
+2. 가중치 786텐서 로드 완료 (~42.5GiB)
+3. **`[solon_moe] SOLON_LAMBDA=0.1 applied to 15 layer(s)`** — 이 줄이 λ 적용 증거. 없으면 학습값으로 돌고 있는 것
+
+첫 기동은 torch.compile 워밍업으로 몇 분 걸리고, 이후엔 캐시로 빨라집니다.
+
+## 4. 호출
+
+```bash
+curl http://localhost:8000/v1/chat/completions -H "Content-Type: application/json" -d '{
+  "model": "/media/models/solon_moe_p6/merged",
+  "messages": [{"role": "user", "content": "질문 내용"}],
+  "max_tokens": 2048,
+  "temperature": 0,
+  "stop_token_ids": [106]
+}'
+```
+
+- `stop_token_ids: [106]`은 generation_config에 106이 있으면 생략 가능하지만, **보험으로 넣기를 권장**합니다. 문자열 `"stop": ["<turn|>"]`은 특수 토큰이 텍스트에서 벗겨져 매칭이 빗나갈 수 있으니 토큰 ID 방식이 확실합니다.
+- 정상 응답 판정: `"finish_reason": "stop"`, `"stop_reason": 106` — 이 둘이 찍히면 첫 블록에서 깔끔하게 종결된 것입니다. `finish_reason: "length"`가 나오면 stop 설정이 안 먹은 것(0장의 grep부터 재확인).
+- OpenAI SDK 사용 시에도 동일: `extra_body={"stop_token_ids": [106]}`.
+
+## 5. 자주 만나는 문제
+
+| 증상 | 원인 → 조치 |
+|---|---|
+| `missing argument: vllm_config` | shim이 구버전(투과 서명) → 신식 서명본으로 교체 후 `~/solon_vllm_plugin`에도 복사 |
+| `Unsupported max_mma_kv: 0` | FlashInfer 경로로 돎 → `--attention-backend TRITON_ATTN` 확인 (env 아닌 CLI) |
+| workspace 버퍼 에러 (394MiB 초과) | `--max-num-seqs 32` 확인, 그래도 나면 더 축소 |
+| 응답이 반복·폭주 | stop 미설정 → generation_config 106 + 요청 stop_token_ids |
+| 응답에 "thought" 낱말이 섞임 | 정상 현상의 흔적 — 모델이 새 턴을 시작한 것, stop만 잡으면 사라짐 |
+| unknown architecture | plugin 미설치/미등록 → 1장 재수행 |
+
+## 6. 운영 메모
+
+- λ 값을 바꿔 실험하려면 서버 재시작 시 `SOLON_LAMBDA`만 바꾸면 됩니다 (0.10 외 값은 검증상 비권장).
+- 응답에는 thought 채널 내용(추론 과정)이 포함됩니다 — 사용자에게 결론만 보여주려면 클라이언트에서 마지막 정형 결론부(`**정답**`, `\boxed{}` 등)를 파싱하는 후처리를 붙이세요.
+- 장시간 운용 중 이상(응답 정지, CUDA 에러) 시 `dmesg | grep -i xid` 확인 — Xid 8이면 하드웨어 규칙(§6) 참조.