AIRGAP StudioAIRGAP Studio

LLM 서버 트러블슈팅

llama-server 가 동작하지 않을 때 진단/해결 방법

AIRGAP Studio 의 AI 엔진은 내장된 llama-server 프로세스로 동작합니다. AI 응답이 오지 않거나, 채팅 패널이 비어 있는 등의 문제가 발생했을 때 아래 절차로 진단하세요.

1. AI 엔진 헬스체크

llama-server 는 기본 포트 11434 에서 동작합니다. /health 엔드포인트가 HTTP 200 을 반환하면 정상입니다.

PowerShell

Invoke-WebRequest http://127.0.0.1:11434/health -UseBasicParsing

curl

curl http://127.0.0.1:11434/health

정상 응답:

HTTP/1.1 200 OK
{"status":"ok"}

응답이 없거나 연결 거부 오류가 발생하면 Launcher 가 llama-server 를 띄우지 못한 상태입니다. Launcher 를 재시작하고, 그래도 같은 증상이면 Launcher 로그를 확인하세요 (섹션 7).

2. Compatibility Proxy 헬스체크

Mistral 및 일부 모델은 모델별 chat-format 호환성을 위해 Compatibility Proxy (포트 11433) 를 경유합니다. 프록시는 Launcher 가 자동 기동/관리합니다.

curl http://127.0.0.1:11433/health

정상 응답이 없으면 Launcher 를 재시작합니다. Launcher 가 llama-server 헬스체크 200 OK 를 받은 직후에만 프록시를 띄우므로, /health (11434) 가 먼저 정상이어야 합니다.

프록시는 loopback (127.0.0.1) 으로만 동작하며 외부에서 접근할 수 없습니다.

3. 포트 충돌 진단

AIRGAP Studio 가 사용하는 주요 포트:

포트용도
11434llama-server (AI 엔진)
11433Compatibility Proxy
9222VSCodium Chrome DevTools (디버그 시)

다른 프로그램이 같은 포트를 점유 중이면 Launcher 가 기동되지 않습니다.

# 11434 포트를 점유 중인 프로세스 확인
Get-NetTCPConnection -LocalPort 11434 | Select-Object LocalAddress, LocalPort, State, OwningProcess

# OwningProcess 의 PID 로 어떤 프로그램인지 확인
Get-Process -Id <PID>

점유 중인 프로그램을 종료하거나, 해당 프로그램의 포트 설정을 변경한 뒤 Launcher 를 다시 실행합니다.

4. VRAM 4GB 미만 — 자동 CPU 폴백

AIRGAP Studio 는 시스템 VRAM 을 측정해 4096MB (4GB) 미만 이면 자동으로 CPU 추론 모드로 전환합니다. 별도 설정은 필요 없습니다.

증상

  • AI 응답이 정상적으로 오지만 속도가 매우 느립니다 (CPU 추론).
  • Launcher 로그에 GPU/CPU 폴백 관련 메시지가 기록됩니다.

해결 방법

  • VRAM 이 더 큰 그래픽카드로 업그레이드합니다 (4GB 이상 권장, 8GB 이상이면 쾌적).
  • 혹은 더 작은 모델을 선택합니다:
    • Qwen3 1.7B — 가장 가벼움, CPU 에서도 빠른 응답
    • Granite 4.0 Micro — 영문 코드 작성에 최적화

모델 변경은 AIRGAP: Select LLM Model 명령으로 수행합니다 (섹션 9).

5. OOM (Out-Of-Memory)

모델 로딩 또는 추론 중 VRAM/RAM 부족이 발생하면 Launcher 가 자동으로 더 작은 모델 또는 CPU 모드로 폴백합니다.

증상

  • 처음에는 동작했지만 긴 컨텍스트 입력 후 응답이 중단됩니다.
  • Launcher 로그에 OOM, out of memory, failed to allocate 등의 메시지가 기록됩니다.

해결 방법

  1. Launcher 로그 (섹션 7) 에서 OOM 메시지를 확인합니다.
  2. 더 작은 모델로 전환합니다.
  3. 다른 GPU 사용 프로그램 (게임, 브라우저 가속 등) 을 종료합니다.

6. 모델 .gguf 파일 미발견

AI 엔진은 설치 시 같이 포함되는 .gguf 모델 파일이 있어야 동작합니다.

증상

  • Launcher 가 기동되지만 즉시 "No model found" 또는 비슷한 에러로 종료됩니다.
  • AI 응답이 영구히 오지 않습니다.

확인 방법

설치 경로 아래 models/ 디렉토리에 .gguf 파일이 1개 이상 있는지 확인합니다.

  • 개발 빌드: build/vscodium/models/
  • 설치본: %LOCALAPPDATA%\AIRGAP\models\ (설치 경로에 따라 다를 수 있음)

해결 방법

Modelpack 인스톨러를 별도로 실행하여 모델 파일을 추가 설치하세요. AIRGAP Studio 인스톨러는 다음 3종으로 분리되어 있습니다:

  • Full — Studio + Modelpack (한 번에 설치)
  • IDE-Only — Studio 만 (모델 없음)
  • Modelpack — 모델 파일만 (IDE 가 이미 설치된 경우)

IDE-Only 만 설치한 경우 Modelpack 인스톨러도 추가로 실행해야 합니다.

7. Launcher 로그 위치

문제 진단에 가장 중요한 정보는 Launcher 로그에 있습니다.

환경로그 경로
설치본 (prod)%LOCALAPPDATA%\AIRGAP\logs\launcher.log
개발 빌드 (dev)phase3/scripts/dev-launcher.log

로그 마지막 100 줄에서 다음 키워드를 검색하면 원인 파악에 도움이 됩니다:

  • health check failed — 헬스체크 실패
  • port .* in use — 포트 충돌
  • VRAM / GPU / CPU fallback — GPU/CPU 폴백
  • OOM / out of memory — 메모리 부족
  • model not found — 모델 파일 미발견
# PowerShell 로 로그 끝 100 줄 보기
Get-Content "$env:LOCALAPPDATA\AIRGAP\logs\launcher.log" -Tail 100

8. 채팅 webview 검은 화면

AI 응답 자체는 정상이나 채팅 패널이 검은 화면으로 보이는 경우가 있습니다.

원인

VSCodium 의 webview 는 OOP (Out-Of-Process) iframe 으로 렌더링되며, 일시적인 렌더링 이슈로 검은 화면이 나타날 수 있습니다. AI 엔진/네트워크 문제와는 무관합니다.

해결 방법

VSCodium 을 재시작합니다:

  1. Command Palette (Ctrl+Shift+P) → Developer: Reload Window
  2. 혹은 Launcher 에서 IDE 종료 → 다시 실행

대부분의 경우 한 번의 재시작으로 해결됩니다. 반복되면 GPU 드라이버 업데이트 또는 다른 GPU 사용 프로그램 종료를 시도하세요.

9. 모델 변경 후 응답 없음

AIRGAP: Select LLM Model 명령으로 모델을 전환한 직후 AI 응답이 오지 않는 경우.

정상 동작 흐름

  1. Command Palette → AIRGAP: Select LLM Model → 모델 선택
  2. Launcher 가 llama-server 를 자동으로 재시작 (수 초 ~ 수십 초 소요)
  3. 새 모델 로드 완료 후 AI 응답 재개

확인 방법

Launcher 로그 (섹션 7) 에 다음 라인이 보이는지 확인합니다:

Starting llama-server with model <모델명>

이 라인이 보이지 않거나, 보였지만 그 뒤로 헬스체크 200 OK 가 안 나타나면:

  1. Launcher 를 재시작합니다.
  2. 그래도 해결되지 않으면 더 작은 모델로 다시 전환을 시도합니다 (메모리 부족 가능성).
  3. Launcher 로그를 첨부해 지원팀에 문의합니다.

관련 문서