문서 / 설치와 문제 해결
문제 해결
내 Mac에서 돌아갈까요? 모든 Apple Silicon Mac의 메모리, 칩, 디스크, 렌더링 시간을 한 페이지에 모았어요.
Phosphene이 렌더링을 거부하면 이유와 해결 방법을 알려 줘요. 여기 있는 메시지는 사람들이 실제로 자주 보는 것들이에요. Install이나 Update 중 문제(Pinokio의 FATAL error: 줄, 디스크 공간 부족)는 설치, 업데이트, 디스크 공간을 보세요.
메모리와 이 Mac의 등급
헤더의 상태 칩에서 메모리를 한눈에 볼 수 있어요. 칩을 클릭하면 등급, 메모리, 헬퍼, 모델, 대기열, 렌더링 행이 보여요. 등급을 클릭하면 이 Mac에서 무엇을 실행할 수 있는지 알 수 있어요.
- “Helper killed by the OS - out of memory”: macOS가 렌더링을 중단시켰어요. 메모리를 많이 쓰는 앱(브라우저, Slack, iOS 시뮬레이터)을 닫고 다시 시도하거나, 품질을 메모리를 절반 정도만 쓰는 Quick으로 바꾸세요.
- “Image pre-flight: … needs a N GB Mac”: 그 이미지 엔진은 이 Mac에서 실행할 수 없어요. 16GB 이하 Mac에서는 설정의 엔진이 더 큰 Mac을 요구하면 자동이 설정은 그대로 두고 FLUX.2 [klein] 4B를 써요. 이 방식은 참조 이미지 없는 렌더링에서만 작동해요. 참조 이미지를 지우면 자동이 Klein을 쓸 수 있고, 설정에서 더 가벼운 엔진을 골라도 돼요. *”… needs ~N GB free”*는 엔진은 맞지만 지금 메모리가 사용 중이라는 뜻이에요. 이 검사는 이제 macOS가 비워 줄 수 있는 메모리와 자동이 실제로 필요한 메모리까지 계산해요.
- “Training needs at least 24 GB of memory”: 이 Mac에서는 캐릭터 학습을 할 수 없어요.
16~60GB Mac의 Hailuo H3
H3의 전체 엔진은 60GB가 필요해요. 16GB부터는 컴팩트 Q8 엔진으로 실행하는데, 이 엔진은 Mac에서 한 번 빌드해요(36GB 미만에서는 렌더링하는 동안 드라이브에서 모델을 읽어요).
- H3가 아직 설치되지 않았다면: Pinokio 사이드바에서 Phosphene을 열고 Install Hailuo H3 (second video engine, ~75 GB)를 클릭하세요. 설치가 끝날 때 컴팩트 엔진도 자동으로 빌드해요(약 5분 더 걸려요).
- H3는 설치됐지만 컴팩트 엔진이 없다면 (“Hailuo H3 runs on this Mac - on its reduced-RAM lane … it is not built here yet”): 같은 사이드바의 Build Hailuo H3 compact engine을 클릭하세요(약 5분, 다운로드 없음).
두 항목 모두 패널이 실행 중일 때 사이드바에 표시돼요.
그런 다음 설정 → Hailuo H3 모델 → 자동 또는 컴팩트를 고르세요. 16GB 미만에서는 H3를 쓸 수 없어요. 모든 모드를 지원하는 LTX로 렌더링하세요.
모델이나 부가 기능이 다운로드되지 않았어요
- *“Enhance needs its language model, Gemma 3 (8.1 GB)“*와 어댑터에 대한 같은 메시지: 새로 설치하면 첫 Start 후 백그라운드에서 다운로드돼요. 메시지에 다운로드 중인지, 대기 중인지, 디스크 공간을 기다리는지 표시돼요. Download now를 누르면 바로 받아요.
- “Extend needs the LTX-2.5 High add-on (the Q8 model), which isn’t downloaded on this Mac yet”: 키프레임과 High 품질도 마찬가지예요. 모델 창에서 설치하세요(상태 칩을 클릭한 다음 모델).
- “Upscale & Face Fix needs the LTX-2.5 Pixel Spatial Upscaler adapter”: 모델 창에서 다운로드한 뒤 다시 렌더링하세요.
- “Stopped before rendering - the model weights are incomplete”: 다운로드가 중간에 끊겼어요. 모델 창을 열고 이어 받으세요. 설정 → Verify model files는 모든 파일을 검사하고, 손상된 파일은 다시 받을 수 있게 해 줘요.
업데이트가 바로 멈춰요
일부 Mac에서는 4.19.7 이전 버전의 Pinokio Update가 시작 1초 만에 멈췄어요. Pinokio 터미널이 업데이트 명령어 자체에 들어 있는 “error:“라는 글자를 실패로 읽었기 때문이에요(#114). Pinokio는 이미 설치된 버전의 업데이트 스크립트를 실행하므로, 수정은 한 번 업데이트한 뒤에야 적용돼요.
대신 Phosphene 안에서 한 번 업데이트하세요. 업데이트 배너(또는 헤더의 버전 알약)에서 지금 업데이트를 클릭하고, 업데이트가 끝났다고 나올 때까지 기다린 다음 다시 시작하세요. 또는 Phosphene 폴더(~/pinokio/api/<your Phosphene folder>)에서 터미널을 열고 git pull을 실행한 뒤 Pinokio에서 Update를 다시 누르세요. 그러면 수정된 새 스크립트가 실행돼요. 그 후에는 버튼이 정상적으로 작동해요.
“Click Update”: 패널보다 오래된 엔진
“This install’s vendored engine predates LTX-2.5’s text encoder … Click Update - and if the first click only moves the panel, click it once more.”
패널은 업데이트됐지만 그 아래의 엔진은 그렇지 않은 상태예요. Pinokio의 Phosphene 사이드바에서 Update를 클릭하세요. 아무 변화가 없는 것 같으면 한 번 더 클릭하세요. 이전 버전이 시작한 업데이트는 먼저 자기 자신을 업데이트해요. H3의 경우 *“the installed Hailuo H3 runner is behind this panel”*은 Install Hailuo H3를 다시 실행하라는 뜻이에요. 디스크에 있는 가중치는 모두 그대로 유지돼요.
업데이트했는데도 패널이 이전 버전처럼 동작한다면 아직 이전 코드가 실행 중이에요. 그럴 때는 헤더의 버전 알약에 Restart Phosphene이 표시돼요. 그걸 클릭하거나, Pinokio에서 Stop을 누른 다음 Start를 누르세요.
GPU 워치독
“the macOS GPU watchdog killed a Metal command buffer”: 너무 오래 걸린 GPU 작업을 macOS가 직접 중단시켰어요. 드라이버 수준에서 강제 종료한 것이라 Phosphene의 버그가 아니고, M1과 M2 Mac에서 가장 흔해요. Phosphene은 같은 작업을 짧은 GPU 단계(더 작은 GPU 작업 단위라 조금 느려요)로 즉시 한 번 다시 렌더링하고, 그 크기를 기억해요. 이 Mac에서 다음 렌더링은 짧은 단계로 시작하고 대기열 행에 그렇게 표시해요. 짧은 단계에서도 macOS가 중단시키면 그 크기는 이 Mac에서 24시간 동안(또는 다음 업데이트까지) 일시 중지되고, 카드에 작게 다시 시도가 나타나요. 계속 발생하면 메시지에 GitHub 이슈 링크가 표시돼요. 칩, macOS 버전, 크래시 로그가 가장 도움이 돼요.
캐릭터 학습이 실패했어요
“training exited with code 1”: 학습기가 끝나기 전에 멈췄어요. 실제 이유는 로그 탭에서 확인하세요. 메모리 부족으로 종료됐거나(RAM이 더 큰 Mac을 쓰거나, 있다면 더 작은 프리셋을 쓰세요), LTX-2.3 학습 파일이 다운로드되지 않았거나(학습 탭의 사전 점검 카드에서 받을 수 있어요), 매우 긴 캡션에서 캡션 인코딩 시간이 초과된 경우예요. 24GB 미만에서는 학습이 항상 실패해요. 그런 Mac에서는 학습을 실행할 수 없어요.
패널이 오프라인이라고 나와요
*“Phosphene offline”*이 표시되고 생성을 눌러도 아무 일도 일어나지 않아요. 패널 프로세스가 응답하지 않는 상태예요. 입력하던 내용은 사라지지 않아요. 프롬프트는 그대로 남아 있고, 패널이 다시 실행되면 페이지가 스스로 다시 연결돼 대기열을 이어 가요. 몇 초 안에 돌아오지 않으면 Pinokio의 Phosphene 사이드바에서 시작하세요.
대기열이 스스로 멈췄어요
“Queue paused: the last N renders failed the same way”: 렌더링 세 개가 연속으로 같은 문제로 실패하면, 다시 시도해도 해결되지 않는 문제로 나머지 대기열을 계속 소모하지 않도록 Phosphene이 멈춰요. 메시지가 알려 주는 원인을 고친 다음 다시 시작을 누르세요. 또는 대기열 비우기로 나머지를 지우고 처음부터 시작하세요.
재시작 후의 대기열
패널을 다시 시작하면 대기열도 이어져요. 패널이 멈출 때 일시 중지돼 있던 대기열은 저절로 다시 시작하고, 로그에 그렇게 기록돼요.
로그 읽기
아래쪽 패널의 로그 탭에 렌더링 로그가 표시돼요. 렌더링이 중단되면 step:으로 시작하는 마지막 줄이 도달한 단계를 알려 줘요. 신고할 때 가장 유용한 정보가 바로 이 줄이에요. Pinokio의 터미널에서도 같은 출력을 볼 수 있어요.
문제 신고하기
헤더의 버그 아이콘을 누르면 버그 신고가 열려요. What happened? 아래에 한두 문장을 적으세요(최소 10자가 필요해요. 무슨 일을 봤는지는 로그가 알려 줄 수 없으니까요). 그러면 버전, Mac 정보, 최근 로그가 채워지고(오류 줄이 일반 줄보다 먼저 와요), 새 탭에서 GitHub 이슈가 열려 마무리할 수 있어요. 거기서 제출하기 전에는 아무것도 전송되지 않아요. 이슈는 github.com/mrbizarro/phosphene/issues에서 볼 수 있어요.
출처: webapp/docs/troubleshooting.md (공개 저장소). 공개 전에 이 웹사이트용으로 검토했어요. 영어 원문에서 번역했어요. 수정 제안하기.