가상환경 패키지 보존 수칙부터 ComfyUI GGUF/LTX 모델 오류, Ollama 400 Bad Request 상대경로 패치까지 실전에서 검증된 1줄 즉각 해결 매뉴얼
증상: 잘 되던 패키지들이 갑자기 사라지고 스크립트 실행 시 ModuleNotFoundError가 연달아 발생함.
원인: venv는 '시작' 명령어가 아니라 '신규 생성(초기화)' 명령어입니다. 기존 가상환경 폴더에 다시 치면 패키지가 백지화됩니다. (단, Ollama 및 ComfyUI 모델은 다른 폴더에 위치하므로 100% 안전하게 보존됨)
해결: venv 재실행은 영구 금지하고, 작업 진입 시에는 반드시 활성화 스크립트만 실행합니다. 증발한 라이브러리는 pip 재설치로 즉시 복원됩니다.
# 작업 진입 표준 루틴 (앞으로는 이 2줄만 사용)
Set-Location "C:\ai_workspace"
.\ai_env\Scripts\activate
# 증발한 핵심 패키지 즉각 복원
python -m pip install docling chromadb sentence-transformers langchain-text-splitters증상: py extract_images.py 실행 시 docling 모듈이 없다고 에러 발생.
원인: 윈도우 py 런처가 가상환경 내부가 아닌 윈도우 전역 파이썬을 가리켰거나 가상환경 내에 패키지가 미설치된 상태입니다.
해결: 가상환경 활성화 (ai_env) 상태에서 docling을 설치하고, py 대신 python으로 실행합니다.
python -m pip install docling
python extract_images.py증상: FLUX VAE 로드 시 safetensors 헤더가 너무 크다며 노드 연산 중단.
원인: HuggingFace 비로그인 상태에서 라이선스 동의 리포지토리를 curl로 받아 HTML 로그인 에러 웹페이지(수 KB)가 모델 파일로 저장됨.
해결: 손상된 가짜 파일을 삭제하고, 인증이 필요 없는 공개 미러(camenduru)에서 정상 335MB 가중치를 다운로드합니다.
Remove-Item -Force "C:\ComfyUI_windows_portable\ComfyUI\models\vae\ae.safetensors"
curl.exe -L --progress-bar -o "C:\ComfyUI_windows_portable\ComfyUI\models\vae\ae.safetensors" "https://huggingface.co/camenduru/FLUX.1-dev/resolve/main/ae.safetensors"증상: FLUX GGUF 로드 시 헤더 인식 불가 에러 발생.
원인: 원본 리포지토리에 존재하지 않는 flux1-dev-Q4_K_M.gguf를 curl로 다운로드하여 0바이트 파일이 생성되었기 때문입니다.
해결: 0바이트 파일을 삭제하고 실제 존재하는 flux1-dev-Q4_0.gguf (약 6.79GB)를 내려받아 노드에서 선택합니다.
Remove-Item -Force "C:\ComfyUI_windows_portable\ComfyUI\models\unet\flux1-dev-Q4_K_M.gguf"
curl.exe -L --progress-bar -o "C:\ComfyUI_windows_portable\ComfyUI\models\unet\flux1-dev-Q4_0.gguf" "https://huggingface.co/city96/FLUX.1-dev-gguf/resolve/main/flux1-dev-Q4_0.gguf"증상: 캔버스에서 더블 클릭 후 Unet Loader (GGUF)를 검색해도 노드가 검색되지 않음.
원인: ComfyUI 내장 파이썬 환경(python_embeded)에 gguf 패키지가 누락되어 커스텀 노드가 로드에 실패함.
해결: ComfyUI 내장 파이썬을 이용해 직접 gguf 라이브러리를 설치합니다.
Set-Location "C:\ComfyUI_windows_portable"
.\python_embeded\python.exe -m pip install gguf
.\run_nvidia_gpu.bat --lowvram증상: LTX-Video 커스텀 노드가 (IMPORT FAILED) 상태로 구동되지 않음.
원인: 최신 kornia 버전에서 내부 함수 임포트 경로가 변경되어 발생한 비호환 이슈입니다.
해결: ComfyUI 내장 파이썬에 안정 버전인 kornia==0.8.2를 강제 설치합니다.
Set-Location "C:\ComfyUI_windows_portable"
.\python_embeded\python.exe -m pip install "kornia==0.8.2"
.\run_nvidia_gpu.bat --lowvram증상: TTS 실행 시 voices 파일을 로드할 수 없다며 크래시 발생.
원인: kokoro-onnx가 NumPy 바이너리 파일(np.load)을 필요로 하는데 텍스트 JSON 파일을 로드하여 발생함.
해결: 공식 릴리스의 사전 컴파일 바이너리인 voices.bin을 다운로드하여 연결합니다.
Invoke-WebRequest -Uri "https://github.com/thewh1teagle/kokoro-onnx/releases/download/model-files/voices.bin" -OutFile "C:\ai_workspace\voices.bin"증상: 음성 생성 시 지정한 보이스가 없다고 에러 발생.
원인: af_heart는 v1.0 프리셋이며, kokoro-v0_19 바이너리에는 af_bella, af_sarah 등이 포함되어 있습니다.
해결: 기본 음성을 voice="af_bella"로 변경하고 코드가 사용 가능한 음성 목록을 동적으로 확인하도록 설정합니다.
증상: ollama create 실행 시 400 Bad Request 에러 발생.
원인: Modelfile의 절대 경로 콜론(C:) 파싱 버그이거나 Unsloth의 자동 GGUF 폴더 생성 규칙(_gguf 접미사) 불일치 때문입니다.
해결: 대상 폴더로 직접 이동(Set-Location)한 후 FROM ./llama-3.2-3b-instruct.Q4_K_M.gguf 상대경로로 생성합니다.
Set-Location "C:\ai_workspace\models\distilled_student_gguf"
# Modelfile 첫 줄을 FROM ./llama-3.2-3b-instruct.Q4_K_M.gguf 로 작성 후 실행
ollama create student -f .\Modelfile증상: Ollama 설치를 마쳤는데 터미널에서 명령어가 작동하지 않음.
원인: 기존에 열려 있던 터미널 세션에 Windows 전역 환경변수(PATH)가 갱신되지 않은 상태입니다.
해결: 열려 있는 모든 PowerShell 창을 완전히 닫고 새로 열면 즉시 인식됩니다.
증상: 모델 파인튜닝 또는 양자화 로드 시 torch 모듈 속성 에러 발생.
원인: 최신 torchao가 개발 중인 PyTorch 2.6+ 속성을 호출하여 발생한 버전 비호환입니다.
해결: 안정 검증 버전인 torchao==0.7.0으로 고정 설치합니다.
python -m pip install "torchao==0.7.0"증상: 파이썬 AI 컴파일 DLL이나 실행 파일 구동 시 작업 표시줄 알림으로 실행 차단.
원인: 오픈소스 바이너리에 마이크로소프트 공식 디지털 서명이 없어 SAC가 악성코드로 오인 차단함.
해결: Windows 보안 → 앱 및 브라우저 컨트롤 → 스마트 앱 컨트롤을 '꺼짐(Off)'으로 전환하고 개발자 모드를 켭니다.
증상: 그래픽카드가 장착되어 있는데도 GPU를 찾을 수 없다는 에러 발생.
원인: Unsloth나 triton 설치 중 의존성 해결 과정에서 CPU 전용 PyTorch로 강제 다운그레이드됨.
해결: CUDA 12.1 버전의 GPU 전용 PyTorch를 강제 재설치(force-reinstall)합니다.
python -m pip install --force-reinstall --no-cache-dir torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121증상: 패키지 설치 중 빨간색 의존성 경고 및 학습 시 fsspec 에러 발생.
원인: 최신 fsspec 버전과 Hugging Face datasets 간의 호환성 버그 및 불필요한 xformers 충돌 때문입니다.
해결: fsspec 버전을 2025.9.0 이하로 고정하고 xformers를 깔끔하게 제거합니다.
python -m pip install "fsspec<=2025.9.0"
python -m pip uninstall -y xformers증상: 생성된 이미지가 순백색으로 타버리거나 색상이 심하게 왜곡됨.
원인: KSampler의 cfg 수치를 기존 SD 1.5 방식처럼 7.0~8.0으로 높게 주었기 때문입니다.
해결: FLUX 모델은 반드시 cfg: 1.0으로 고정하고, 프롬프트 강도는 FluxGuidance 노드의 guidance(3.5 권장)로만 조절합니다.
증상: KSampler 연산 완료 후 VAEDecode 단계에서 텐서 크기가 맞지 않는다며 에러 발생.
원인: 너비/높이가 32의 배수가 아니거나 비디오 길이가 (8n + 1) 프레임 규칙을 벗어났기 때문입니다.
해결: 해상도는 768×512, 비디오 길이는 65(8×8+1 = 25fps 기준 2.6초)로 엄격히 맞춥니다.
장애 발생 시 가상환경 활성화 상태에서 아래 스크립트를 실행하여 GPU 인식, 패키지 버전, C++ 가속 엔진을 한 번에 검증할 수 있습니다.
python -c "
import torch
print('=== 로컬 AI 시스템 환경 종합 진단 ===')
print('1. PyTorch 버전:', torch.__version__)
print('2. CUDA 사용 가능 여부:', torch.cuda.is_available())
if torch.cuda.is_available():
print('3. 감지된 GPU:', torch.cuda.get_device_name(0))
print('4. 총 VRAM 용량:', round(torch.cuda.get_device_properties(0).total_memory / (1024**3), 2), 'GB')
try:
import bitsandbytes as bnb
print('5. 4-bit 가속 모듈 (bitsandbytes): 정상 로드')
except Exception as e:
print('5. bitsandbytes 로드 실패:', e)
try:
import docling
print('6. IBM Docling OCR 엔진: 정상 로드')
except Exception as e:
print('6. Docling 로드 실패:', e)
print('=====================================')
"