10.3. 문제 해결 (Troubleshooting)¶

Backend.AI GO 사용 중 발생할 수 있는 문제들에 대한 상세한 해결 방법을 안내합니다.

1. 설치 및 실행¶

앱을 실행했는데 아무 반응이 없습니다¶

프로세스 확인: 이전 세션의 프로세스가 완전히 종료되지 않았을 수 있습니다. 작업 관리자(Windows)나 활성 상태 보기(macOS)에서 backend-ai-go 또는 llama-server 프로세스를 강제 종료하세요.
재설치: 설치 파일이 손상되었을 수 있습니다. 최신 버전을 다시 설치해 보세요.

"손상된 앱이라 열 수 없습니다" (macOS)¶

App Store 외부에서 다운로드한 앱에 대해 macOS가 표시하는 일반적인 보안 경고입니다.

해결책: 앱 아이콘을 우클릭한 후 열기를 선택하세요. 대화 상자에서 다시 열기를 클릭하면 실행됩니다.
터미널 해결: 위 방법이 안 되면 터미널에서 다음 명령어를 실행하세요:
```
xattr -cr /Applications/Backend.AI\ GO.app
```

"확인되지 않은 개발자" 경고 (macOS)¶

Mac App Store 외부에서 다운로드한 앱의 경우, macOS Gatekeeper가 개발자를 확인할 수 없다는 메시지를 표시하며 앱 실행을 차단할 수 있습니다.

Apple 메뉴 () > 시스템 설정 > 개인 정보 보호 및 보안으로 이동하세요.
보안 섹션까지 스크롤을 내리면 차단된 앱에 대한 메시지가 표시됩니다.
"어쨌든 열기"를 클릭하세요.
로그인 비밀번호를 입력하고 확인하세요.

시간 제한

"어쨌든 열기" 버튼은 처음 앱이 차단된 시점으로부터 약 1시간 동안만 표시됩니다. 버튼이 더 이상 보이지 않는다면 앱을 다시 열어 시도하면 1시간 제한이 초기화됩니다.

자세한 내용은 Apple 공식 안내를 참고하세요: https://support.apple.com/guide/mac-help/mchleab3a043/mac

"Windows의 PC 보호" (SmartScreen)¶

Windows SmartScreen은 Microsoft에 충분한 평판 점수가 쌓이지 않은 게시자의 앱을 차단합니다.

SmartScreen 대화 상자에서 "추가 정보"를 클릭하세요.
"어쨌든 실행"을 클릭하여 설치를 진행하세요.

왜 이 경고가 나타나나요?

SmartScreen은 평판 시스템을 사용합니다. 서명된 소프트웨어의 새 릴리스도 충분히 많은 사용자가 설치·실행할 때까지 이 경고가 표시될 수 있습니다. Backend.AI GO의 경우 이 경고는 정상적인 것으로 무시하고 진행해도 안전합니다.

설치 후 백신 프로그램이 파일을 삭제하거나 격리함 (Windows)¶

일부 백신 프로그램이 추론 엔진 바이너리(llama-server-x86_64-pc-windows-msvc.exe)를 악성 소프트웨어로 잘못 탐지하는 경우가 있습니다. 이는 알려진 오탐(false positive)입니다.

해결 단계:

백신 프로그램 대시보드를 열어 격리 또는 위협 기록 섹션으로 이동하세요.
가능하다면 격리된 파일을 복원하세요.
백신 설정에서 다음 경로를 제외(예외) 목록에 추가하세요:
- %LOCALAPPDATA%\Programs\backend.ai.go\
- %LOCALAPPDATA%\backend.ai.go\engines\
- %APPDATA%\backend.ai.go\
제외 경로 추가 후 공식 릴리스에서 Backend.AI GO를 다시 설치하세요.

오탐 신고하기

백신 업체에 오탐 신고를 제출하면 빠른 해결에 도움이 됩니다. 대부분의 업체(Windows Defender, Avast, Bitdefender 등)는 공식 웹사이트에 오탐 제출 포털을 운영하고 있습니다.

Visual C++ 런타임 누락 (Windows)¶

VCRUNTIME140.dll을 찾을 수 없습니다 또는 MSVCP140.dll을 찾을 수 없습니다 오류와 함께 앱이 실행되지 않으면, Microsoft Visual C++ 재배포 가능 패키지가 없거나 오래된 버전입니다.

해결 방법:

Microsoft 다운로드 센터에서 최신 Visual C++ 재배포 가능 패키지(x64)를 다운로드하여 설치하세요.

설치 후 컴퓨터를 재시작하고 Backend.AI GO를 다시 실행해 보세요.

GPU 가속을 위한 CUDA 드라이버 요구사항 (Windows)¶

Windows에서 NVIDIA GPU 가속을 사용하려면 CUDA 12.x 이상이 필요합니다.

명령 프롬프트에서 nvidia-smi를 실행하세요. 명령이 실패하면 드라이버가 오래되었거나 설치되지 않은 것입니다.
nvidia.com/drivers에서 최신 Game Ready 또는 Studio 드라이버를 다운로드하세요.
드라이버 설치 후 컴퓨터를 재시작하세요.
Backend.AI GO에서 설정 > 엔진으로 이동하여 CUDA 지원 엔진이 선택되어 있는지 확인하세요.

AppImage가 실행되지 않음 (Linux)¶

AppImage를 더블클릭해도 반응이 없거나 터미널에서 실행 시 권한 오류가 발생하는 경우:

1단계 — 실행 권한 추가:

chmod +x Backend.AI-GO.AppImage
./Backend.AI-GO.AppImage

2단계 — FUSE 설치 (앱이 여전히 실행되지 않는 경우):

AppImage는 대부분의 Linux 배포판에서 FUSE 2가 필요합니다.

# Ubuntu 22.04 이하 / Debian
sudo apt update && sudo apt install libfuse2

# Ubuntu 24.04 (noble) — FUSE 2는 universe 저장소에 있음
sudo apt update && sudo apt install libfuse2t64

# Fedora
sudo dnf install fuse

# Arch Linux
sudo pacman -S fuse2

FUSE 설치 후 AppImage를 다시 실행하세요.

공유 라이브러리 누락 (Linux)¶

libwebkit2gtk-4.1.so.0: cannot open shared object file과 같은 오류와 함께 Backend.AI GO가 시작되지 않으면, 필요한 의존 패키지를 설치하세요:

# Ubuntu / Debian
sudo apt update
sudo apt install libwebkit2gtk-4.1-0 libgtk-3-0 libayatana-appindicator3-1

# Fedora
sudo dnf install webkit2gtk4.1 gtk3 libayatana-appindicator

# Arch Linux
sudo pacman -S webkit2gtk-4.1 gtk3

누락된 라이브러리 확인 방법

터미널에서 AppImage를 실행하면 정확한 라이브러리 오류 메시지를 확인할 수 있습니다. 출력에 누락된 .so 파일 목록이 표시되어 배포판에 맞는 패키지를 쉽게 찾을 수 있습니다.

Linux GPU 드라이버 설정¶

NVIDIA CUDA:

드라이버가 로드되어 있는지 확인하세요: nvidia-smi
명령이 없다면 배포판 패키지 관리자 또는 nvidia.com/drivers에서 드라이버를 설치하세요.
```
# Ubuntu
sudo apt install nvidia-driver-570
```
재부팅 후 nvidia-smi에서 CUDA 버전이 표시되는지 확인하세요.

AMD ROCm:

rocm.docs.amd.com의 공식 ROCm 설치 가이드를 따르세요.
사용자를 render 및 video 그룹에 추가하세요:
```
sudo usermod -aG render,video $USER
```
로그아웃 후 다시 로그인하고 rocminfo로 확인하세요.

실행 즉시 앱이 꺼집니다¶

설정 초기화: 설정 파일이 손상되었을 수 있습니다. 설정 폴더를 삭제하거나 이름을 변경해 보세요:
- Windows: %APPDATA%\backend.ai.go
- macOS: ~/Library/Application Support/backend.ai.go
- Linux: ~/.config/backend.ai.go

UI 레이아웃이 이상하거나 예상과 다르게 동작함¶

UI 상태 초기화: 사이드바 위치, 탭 선택, 스크롤 위치 등이 이상하게 보인다면 모든 UI 환경설정을 초기화할 수 있습니다:
1. 설정 > UI로 이동하세요
2. UI 상태 섹션을 찾으세요
3. UI 상태 초기화를 클릭하여 기본 레이아웃으로 복원하세요

"Port 8000/8001 is already in use" 오류¶

Backend.AI GO는 API 서버용으로 8000번, 관리용으로 8001번 포트를 사용합니다.

충돌 확인: 로컬 웹 서버나 다른 AI 도구가 이 포트를 사용 중일 수 있습니다. 해당 프로그램을 종료하고 다시 시도하세요.

"바이너리를 찾을 수 없음" 또는 "추론 엔진을 찾을 수 없음" (Windows)¶

추론 엔진(llama-server)을 찾을 수 없을 때 발생하는 오류입니다. 다음과 같은 원인이 있을 수 있습니다:

백신 프로그램 간섭: 일부 백신 프로그램이 llama-server-x86_64-pc-windows-msvc.exe 파일을 위협으로 오인하여 격리하거나 삭제할 수 있습니다.
- 해결책: 백신 프로그램 설정에서 Backend.AI GO 설치 디렉토리를 예외로 추가하세요.
- 예외 추가할 경로:
  - %LOCALAPPDATA%\Programs\backend.ai.go\
  - %LOCALAPPDATA%\backend.ai.go\engines\
  - %APPDATA%\backend.ai.go\
불완전한 설치: 설치가 중단되었을 수 있습니다.
- 해결책: 공식 릴리스에서 Backend.AI GO를 다시 설치하세요.
엔진 없음: 번들된 엔진이 없을 수 있습니다. Backend.AI GO는 이제 다운로드 가능한 엔진을 지원합니다.
- 해결책: 설정 > 엔진으로 이동하여 시스템에 맞는 추론 엔진을 다운로드하세요.
파일 권한 문제: Windows 보안 정책으로 인해 바이너리에 접근할 수 없을 수 있습니다.
- 해결책: 앱을 한 번 관리자 권한으로 실행하거나 폴더 권한을 확인하세요.

문제 해결 단계:

알림 센터에서 "추론 엔진을 찾을 수 없음" 메시지를 확인하세요
"엔진 다운로드"를 클릭하여 엔진 페이지로 이동하세요
호환되는 엔진(예: CUDA 또는 CPU 지원 llama-cpp)을 다운로드하세요
모델 로드를 다시 시도하세요

디버그 정보: 오류 메시지에 예상되는 바이너리 이름과 검색된 경로가 표시되어 엔진이 있어야 할 위치를 확인하는 데 도움이 됩니다.

macOS에서 "시스템이 지원되지 않음" 메시지¶

Intel Mac: Backend.AI GO는 Apple Silicon (M1/M2/M3/M4/M5)을 필수적으로 요구합니다. Intel 기반 Mac은 지원되지 않습니다. Intel Mac에서 AI를 사용해야 한다면 클라우드 통합 기능을 활용해 보세요.

2. 모델 다운로드 및 관리¶

다운로드가 0%에서 멈춤¶

방화벽: 방화벽이나 백신 프로그램이 Hugging Face 접속을 차단하고 있는지 확인하세요.
프록시: 사내망을 사용하는 경우 HTTP_PROXY 및 HTTPS_PROXY 환경변수가 올바르게 설정되었는지 확인하세요.

"다운로드 실패" 오류¶

이어받기: 재시도 버튼을 누르세요. 이어받기를 지원합니다.
디스크 공간: 디스크 용량이 충분한지 확인하세요. 공간 부족 오류가 네트워크 오류로 표시될 때가 있습니다.

다운로드 속도가 너무 느림¶

미러 사이트: 일부 지역에서는 Hugging Face 접속이 느릴 수 있습니다.
외부 다운로드: 브라우저나 다운로드 매니저로 .gguf 파일을 직접 다운로드한 후, 앱의 가져오기 기능을 사용하세요.

다운로드한 모델이 라이브러리에 없음¶

새로고침: 라이브러리 상단의 새로고침 아이콘을 클릭하세요.
확장자: 파일 확장자가 .gguf인지 확인하세요.
위치: 파일이 올바른 models 디렉토리(설정에서 확인 가능)에 있는지 확인하세요.

모델 삭제 불가 (파일 잠김)¶

언로드: 해당 모델이 현재 로드되어 있다면 먼저 언로드하세요.
앱 재시작: 앱을 완전히 종료했다가 다시 켜면 파일 잠금(Lock)이 해제됩니다.

멀티파트 모델에 "불완전" 배지가 표시됨¶

대용량 모델(70B+ 파라미터)은 여러 파일로 분할되어 있는 경우가 많습니다(예: model.gguf-00001-of-00006.gguf). 모델 카드에 "불완전(Incomplete)" 경고 배지가 표시된다면:

누락된 파트 확인: 배지에 마우스를 올리면 어떤 파트가 누락되었는지 확인할 수 있습니다 (예: "Missing parts: 2, 3, 5 of 6").
다운로드 재개: 다운로드 탭에서 일시 중지되거나 실패한 다운로드를 재개하세요.
수동 다운로드: 다운로드가 중단된 경우 Hugging Face에서 누락된 파트를 다시 다운로드해야 할 수 있습니다.
파일 확인: 모든 파트 파일이 같은 디렉토리에 있고 model.gguf-NNNNN-of-NNNNN.gguf 형식의 이름을 따르는지 확인하세요.
로드 불가: 불완전한 멀티파트 모델은 모든 파트가 있을 때까지 로드할 수 없습니다. 로드 버튼이 비활성화됩니다.

3. 모델 로딩 및 추론¶

로딩 중 앱이 멈춤 (Freeze)¶

대용량 모델: Solar-Open-100B나 gpt-oss-120B 모델 등을 RAM에 올리는 데는 2-3분이 걸릴 수 있습니다. 조금만 기다려주세요.
시스템 RAM: 실제 물리 RAM보다 큰 모델을 로드하면 OS가 스와핑(Swapping)을 시작하여 컴퓨터가 매우 느려질 수 있습니다.

"Out of Memory (OOM)" 오류¶

컨텍스트 줄이기: 모델 설정에서 Context Length를 줄여보세요 (예: 8192 -> 4096).
GPU 오프로딩 조절: VRAM이 부족하다면 GPU 레이어 수를 줄이고, 시스템 RAM이 부족하다면 GPU 레이어 수를 늘려보세요.
양자화 변경: Q8_0 대신 더 작은 Q4_K_M을 사용하세요.

GPU를 사용하지 않고 CPU만 사용함¶

설정 확인: 모델 설정에서 GPU Layers가 0이 아닌지 확인하세요. Max 또는 -1로 설정하세요.
드라이버:
- Windows: 최신 NVIDIA 드라이버를 설치하세요.
- Linux: CUDA 툴킷이 설치되어 있고 nvidia-smi가 작동하는지 확인하세요.

MLX 모델 로드 실패 (macOS)¶

칩 호환성: MLX는 Apple Silicon(M1/M2/M3/M4/M5)을 필요로 합니다. Intel Mac에서는 작동하지 않습니다.
운영체제 버전: macOS 13.0 (Ventura) 이상인지 확인하세요.

모델이 이상한 문자만 출력함¶

반복 페널티: 같은 단어를 반복한다면 Frequency Penalty를 높이세요.
온도: 횡설수설한다면 Temperature를 낮추세요 (예: 0.7).
템플릿: 채팅 템플릿이 맞지 않을 수 있습니다. 설정에서 올바른 템플릿(ChatML, Llama 3 등)을 수동으로 선택해 보세요.

생성 속도가 너무 느림 (낮은 TPS)¶

전원 모드: 노트북이 전원에 연결되어 있는지 확인하세요.
백그라운드 앱: 웹 브라우저나 메신저 등을 종료하여 메모리 대역폭을 확보하세요.

4. 채팅 및 기능¶

엔터 키를 눌러도 메시지가 전송되지 않음¶

로딩 상태: 모델이 로딩 중이거나 답변을 생성 중인지 확인하세요.
생성 중: AI가 답변하는 도중에는 메시지를 보낼 수 없습니다. 중지 버튼을 먼저 누르세요.

대화 기록이 사라짐¶

로컬 저장: 대화 기록은 로컬에 저장됩니다. 앱 데이터를 삭제하거나 클린 설치를 했다면 기록이 삭제되었을 수 있습니다.
검색: 사이드바 검색창을 사용해 보세요. 목록 아래로 스크롤되어 안 보이는 것일 수 있습니다.

이미지 첨부 실패¶

모델 지원: 멀티모달(Multimodal) 모델(Llama-3.2-Vision, Qwen2-VL 등)을 사용 중인지 확인하세요. 일반 텍스트 모델은 이미지를 볼 수 없습니다.

"사고 블록"이 안 보임¶

모델 지원: 추론 모델(DeepSeek-R1, Qwen3-Thinking)만 사고 과정을 출력합니다. 일반 모델은 바로 답변을 줍니다.

툴 콜링 오류¶

모델 성능: 모델이 툴 콜링을 지원하는지 확인하세요. 작은 모델(< 7B)은 도구 형식을 잘 지키지 못할 수 있습니다.
권한: 권한 요청을 거부했는지 확인하세요. 채팅창에 권한 승인 버튼이 있는지 확인하세요.

한국어로 질문했는데 영어로 대답함¶

시스템 프롬프트: "항상 한국어로 대답해 줘"라는 시스템 프롬프트를 추가하세요.
모델 편향: 일부 모델은 영어 데이터 위주로 학습되어 있습니다. 한국어 파인튜닝 모델을 사용하거나 더 큰 모델을 사용해 보세요.

5. 클라우드 및 연동¶

"Invalid Key" 오류¶

공백 확인: API 키 앞뒤에 공백이 포함되지 않았는지 확인하세요.
쿼터: 공급자(OpenAI, Anthropic)의 사용량 한도나 크레딧이 남아있는지 확인하세요.

클라우드 모델 목록이 안 보임¶

새로고침: 목록을 가져오는 데 시간이 걸릴 수 있습니다.
권한: API 키가 모델 목록 조회 권한을 가지고 있는지 확인하세요.

원격 vLLM 연결 실패¶

네트워크: 서버 IP로 ping이 되는지 확인하세요.
방화벽: 원격 서버의 8000번 포트가 열려 있는지 확인하세요.
CORS: vLLM 실행 시 --cors-allow-origins "*" 옵션을 주었는지 확인하세요.

클라우드 서비스 연결 오류 확인하기¶

클라우드 서비스 연결에 실패하거나 오류가 발생하면 로그 패널에서 상세한 오류 로그를 확인할 수 있습니다:

사이드바에서 로그 패널을 여세요
API 소스로 필터링하여 서비스 관련 메시지를 확인하세요
다음과 같은 오류 항목을 찾아보세요:
- 연결 실패 (타임아웃, 호스트 접근 불가)
- 인증 오류 (401, 403)
- 요청 제한 (429)
- 서버 오류 (5xx)

자격 증명 보호

연결 오류 로그는 URL에서 내장된 자격 증명을 자동으로 제거하여 API 키가 로그 파일에 노출되지 않도록 합니다.

기능이나 사용법에 대한 일반적인 질문은 FAQ 페이지를 방문해 주세요.

여전히 문제가 해결되지 않나요? Discord 커뮤니티에 가입하거나 GitHub에 이슈를 남겨주세요.