콘텐츠로 이동

문제 해결 (Troubleshooting)¶

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

1. 설치 및 실행¶

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

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

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

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

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

"Windows의 PC 보호" (SmartScreen)¶

해결책: 추가 정보(More info)를 클릭한 후 실행(Run anyway) 버튼을 누르세요.

실행 즉시 앱이 꺼집니다¶

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

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

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

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

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

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

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

"다운로드 실패(Network Error)"¶

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

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

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

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

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

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

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

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가 작동하는지 확인하세요.

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

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

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

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

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

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

4. 채팅 및 기능¶

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

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

대화 기록이 사라짐¶

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

이미지 첨부 실패¶

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

"사고 블록(Thinking Block)"이 안 보임¶

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

툴 콜링 오류¶

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

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

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

5. 클라우드 및 연동¶

"Invalid Key" 오류¶

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

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

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

원격 vLLM 연결 실패¶

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

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