Modly 이미지-투-3D가 80%에서 멈출 때: 한글 Windows cp949 파이프 데드락 완전 해결 (복붙용 AI 패치 프롬프트 포함)

목차

1. 3줄 요약
2. 초보자를 위한 핵심 용어 사전
3. 증상: 에러도 없이 영원히 80%
4. 3분 진단: 느린 건가, 멈춘 건가
5. 원인 추적: 죽은 스레드가 파이프를 막는다
6. 그런데 왜 하필 80%인가
7. 해결 A: AI에게 맡기기 (복붙용 프롬프트)
8. 해결 B: 손으로 고치기 (5분)
9. 해결 C: 파일을 건드리지 않는 우회법
10. 검증: 제대로 고쳐졌는지 확인하기
11. 롤백과 앱 업데이트 대응
12. 곁들이면 좋은 실전 팁
13. 정리: 이 버그가 남긴 교훈

---

3줄 요약

• 한글 Windows에서 Modly의 이미지-투-3D 생성이 항상 80%에서 무한 정지합니다. 에러도, 타임아웃도, 실패 처리도 없이 상태는 계속 running입니다.
• 원인은 GPU도 모델도 VRAM도 아닙니다. 서브프로세스의 로그를 읽는 스레드가 cp949로 디코딩하다 죽고, 아무도 읽지 않는 파이프 버퍼가 가득 차서 워커가 영원히 블록됩니다.
• Popen에 encoding="utf-8" 한 줄을 넣으면 끝입니다. 무한 정지가 65초로 바뀝니다.

바로 고치고 싶다면 해결 A: AI에게 맡기기로 건너뛰세요. 프롬프트를 복사해서 AI 코딩 도구에 붙여넣기만 하면 됩니다.

검증 환경: Windows 10 Pro 19045 · RTX 3070 8GB · RAM 32GB · Modly 0.3.1 · 확장 hunyuan3d-mini-turbo

---

초보자를 위한 핵심 용어 사전

이 글은 파이썬을 몰라도 따라 할 수 있게 썼지만, 원인을 이해하려면 용어 네 개만 알면 충분합니다.

• 서브프로세스(Subprocess): 프로그램이 자기 안에서 또 다른 프로그램을 별도로 띄우는 것입니다. Modly는 3D 모델을 격리된 환경에서 돌리려고 파이썬을 따로 실행합니다.
• 파이프(Pipe): 부모 프로그램과 서브프로세스가 대화하는 통로입니다. 서브프로세스가 출력한 글자가 이 통로를 타고 부모에게 전달됩니다. 통로의 크기는 보통 64KB 정도로 정해져 있습니다.
• 인코딩(Encoding) / cp949: 컴퓨터가 글자를 숫자로 바꾸는 규칙입니다. cp949는 한글 Windows의 기본 규칙이고, UTF-8은 전 세계 표준입니다. 규칙이 어긋나면 글자가 깨지거나 프로그램이 죽습니다.
• 데드락(Deadlock): 서로 기다리다가 아무도 진행하지 못하는 교착 상태입니다. 이 글의 핵심 증상이 정확히 여기에 해당합니다.

---

증상: 에러도 없이 영원히 80%

Modly에서 이미지를 넣고 3D 생성을 돌리면 이렇게 됩니다.

• 진행률이 Generating 3D shape… 80%에서 멈춘 뒤 몇 시간이 지나도 그대로
• 에러 메시지 없음, 타임아웃 없음, 실패 처리도 안 됨 — 상태는 계속 running
• 다시 시도해도 똑같은 지점에서 100% 재현

가장 나쁜 종류의 버그입니다. 아무것도 알려주지 않으니까요.

솔직히 말하면 저는 처음에 두 가지를 의심했고 둘 다 틀렸습니다.

1. 8GB VRAM이 부족한 것 아닐까 — RTX 3070은 3D 생성 모델에 넉넉한 사양이 아니니 자연스러운 의심이었습니다.
2. 동시에 돌던 다른 작업과 디스크 I/O 경합이 난 것 아닐까 — 마침 다른 창에서 uv 빌드가 돌고 있었습니다.

이 오진에 시간을 꽤 썼습니다. 이 글을 읽는 분은 그 시간을 건너뛰실 수 있습니다.

---

3분 진단: 느린 건가, 멈춘 건가

로그를 열기 전에 이것부터 하세요. “작업이 느린 것”과 “작업이 아예 멈춘 것”은 완전히 다른 문제인데, 화면만 봐서는 구분이 안 됩니다. 3분이면 판별됩니다.

1단계: GPU가 일하고 있는지 본다

PowerShell을 열고 실행합니다.

nvidia-smi --query-gpu=utilization.gpu,memory.used --format=csv,noheader

정지 상태에서 나온 결과입니다.

4 %, 6244 MiB

VRAM은 6.2GB를 붙잡고 있는데 GPU 사용률은 4%. 메모리는 점유했지만 계산은 안 하고 있다는 뜻입니다. 만약 GPU 사용률이 90% 이상이라면 그냥 느린 것이니 기다리면 됩니다. 여기서 갈립니다.

2단계: 프로세스의 누적 CPU 시간을 본다

이게 결정적인 증거입니다. 아래를 PowerShell에 붙여넣으세요.

1..4 | ForEach-Object {
  Get-Process python -ErrorAction SilentlyContinue |
    Sort-Object CPU -Descending | Select-Object -First 1 |
    ForEach-Object { "{0} cpu={1}" -f (Get-Date -Format HH:mm:ss), $_.CPU }
  Start-Sleep -Seconds 10
}

정상이라면 cpu= 숫자가 계속 늘어야 합니다. 그런데 실제 결과는 이랬습니다.

12:30:59 cpu=163.015625
12:31:09 cpu=163.015625
12:31:19 cpu=163.015625

30초 동안 1밀리초도 늘지 않았습니다. 연산이 느린 게 아니라 아예 실행되지 않고 있다는 뜻입니다. 무언가를 기다리며 블록된 상태입니다.

이 두 단계는 Modly 말고도 모든 “멈춘 것 같은 프로그램”에 그대로 쓸 수 있는 진단법입니다. CPU 누적 시간이 멈춰 있으면 성능 문제가 아니라 교착 상태를 의심하세요.

3단계: 이제 로그를 연다

블록됐다는 걸 확인했으니 로그를 봅니다.

Get-Content "$env:APPDATA\Modly\logs\runtime.log" -Tail 60

여기서 범인이 나왔습니다.

Exception in thread Thread-3 (_stderr_loop):
Traceback (most recent call last):
  File "...\api\services\extension_process.py", line 213, in _stderr_loop
    ch = stream.read(1)
         ^^^^^^^^^^^^^^
UnicodeDecodeError: 'cp949' codec can't decode byte 0xc8 in position 1: illegal multibyte sequence

GPU 이야기는 한 줄도 없습니다. 글자 인코딩 문제였습니다.

---

원인 추적: 죽은 스레드가 파이프를 막는다

왜 하필 cp949인가

Modly는 확장(3D 모델)을 격리된 가상환경의 별도 서브프로세스로 띄우고, 파이프로 대화합니다. 문제의 코드는 extension_process.py의 107번째 줄 근처입니다.

self._proc = subprocess.Popen(
    [str(python), str(_RUNNER_PATH)],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,          # ← encoding 지정이 없다
    bufsize=1,
    env=self._build_env(),
)

text=True만 주고 encoding=을 생략하면, 파이썬은 시스템 로케일 인코딩으로 파이프를 해석합니다. 여러분의 PC에서 그게 무엇인지 확인해 보세요.

python -c "import locale; print(locale.getpreferredencoding(False))"

한글 Windows라면 이렇게 나옵니다.

cp949

영어권 개발자 PC에서는 이 값이 utf-8이라 버그가 절대 재현되지 않습니다. 그래서 이 문제가 오래 살아남았습니다.

죽은 스레드 → 막힌 파이프 → 멈춘 워커

연쇄는 이렇게 이어집니다.

1. 3D 생성 워커의 진행률 바(tqdm) 가 █ 같은 UTF-8 블록 문자를 출력합니다.
2. 부모 프로그램이 그 바이트를 cp949로 해석하려다 실패 → 로그 읽는 스레드가 죽습니다.
3. 이제 파이프에서 글자를 꺼내가는 주체가 없습니다.
4. 워커는 진행률 바를 계속 출력하고, 64KB짜리 파이프 버퍼가 가득 찹니다.
5. 버퍼가 꽉 차면 출력 명령 자체가 블록됩니다 → 워커가 작업 도중 영구 정지.

앞서 본 CPU 0%, VRAM 6.2GB 점유가 정확히 이 상태입니다. 워커는 죽지 않았습니다. 글자 한 줄을 출력하려고 영원히 기다리는 중입니다.

이건 subprocess를 쓰는 모든 프로그램의 고전적 함정입니다. 파이프를 만들었으면 반드시 끝까지 읽어야 합니다. 읽다가 죽어도 안 됩니다.

---

그런데 왜 하필 80%인가

여기가 이 버그의 가장 악질적인 부분입니다. 확장의 generator.py 112번째 줄 근처를 보면 이렇습니다.

shape_end = 70 if enable_texture else 82
self._report(progress_cb, 12, "Generating 3D shape…")
stop_evt = threading.Event()
if progress_cb:
    t = threading.Thread(
        target=smooth_progress,
        args=(progress_cb, 12, shape_end, "Generating 3D shape…", stop_evt),
        daemon=True,
    )
    t.start()

smooth_progress는 실제 작업과 아무 상관 없이 12%에서 82%까지 혼자 올라가는 가짜 진행률입니다. 진짜 작업이 첫 줄에서 죽든 끝까지 가든, UI는 똑같이 82%를 향해 기어갑니다.

그러니까 “80%에서 멈춤”은 작업이 80% 지점에서 실패했다는 뜻이 전혀 아닙니다. 가짜 진행률이 천장에 닿은 것뿐이고, 진짜 작업은 훨씬 이전에 블록됐습니다.

이 가짜 진행률이 디버깅을 몇 시간 헤매게 만든 진짜 범인입니다. “80%까지 갔으니 거의 다 된 건데 마지막 단계에서 뭔가 무거운 거겠지”라고 생각하게 만드니까요. 실제로는 시작하자마자 죽어 있었습니다.

교훈: 실제 진행 상황과 연결되지 않은 진행률 바는 사용자를 돕는 게 아니라 속입니다. 최소한 멈췄을 때 멈춘 것처럼 보이기라도 해야 합니다.

---

해결 A: AI에게 맡기기 (복붙용 프롬프트)

Claude Code, Cursor, Codex 같은 AI 코딩 도구를 쓰신다면 아래 블록을 통째로 복사해서 붙여넣으세요. 파일을 찾고, 백업하고, 정확한 위치에 패치하고, 검증까지 알아서 합니다.

프롬프트 1: 진단부터 패치까지 한 번에

한글 Windows(cp949)에서 Modly의 이미지-투-3D 생성이 80%에서 무한 정지하는
버그를 고쳐줘. 원인은 서브프로세스 파이프를 로케일 인코딩(cp949)으로
디코딩하다가 로그 리더 스레드가 UnicodeDecodeError로 죽고, 그 결과
아무도 stderr를 비우지 않아 파이프 버퍼가 가득 차서 워커가 블록되는 것이다.

작업 순서:

1. 아래 경로에서 extension_process.py 를 찾아라.
   C:\Users\<사용자명>\AppData\Local\Programs\Modly\resources\api\services\extension_process.py
   (경로가 다르면 Programs\Modly 아래에서 extension_process.py 를 검색해라)

2. 수정 전에 같은 폴더에 extension_process.py.bak 으로 백업해라.
   이미 .bak 이 있으면 덮어쓰지 말고 .bak2 로 만들어라.

3. 파일 안의 subprocess.Popen(...) 호출을 찾아라.
   text=True 는 있는데 encoding= 인자가 없는 상태일 것이다.
   거기에 아래 두 줄을 추가해라. bufsize=1 보다 앞에 넣어라.

       encoding="utf-8",
       errors="replace",

   추가할 때 아래 주석도 같이 넣어줘:
       # Pin the pipe codec: on non-UTF-8 locales (e.g. cp949 on Korean
       # Windows) the default locale decoder chokes on tqdm's block
       # characters and kills the stderr reader. Once nothing drains
       # stderr the pipe buffer fills and the worker blocks forever.

4. 수정 후 파이썬 문법이 깨지지 않았는지 확인해라:
   python -m py_compile "<파일 경로>"

5. 변경된 부분을 diff 로 보여주고, 다음 단계로
   "Modly를 완전히 종료했다가 다시 실행해야 적용된다"는 점을 알려줘.

주의: Popen 호출이 여러 개면 stdout/stderr 파이프를 여는 것 전부에 적용해라.
이미 encoding= 이 있으면 건드리지 말고 그렇다고 보고해라.

프롬프트 2: 패치가 잘 됐는지 검증만

패치 후 확인만 하고 싶을 때 씁니다.

Modly의 extension_process.py 가 UTF-8 파이프 패치가 적용된 상태인지 확인해줘.

1. C:\Users\<사용자명>\AppData\Local\Programs\Modly\resources\api\services\
   extension_process.py 에서 subprocess.Popen 블록을 보여줘.
2. encoding="utf-8" 과 errors="replace" 가 들어있는지 확인해줘.
3. %APPDATA%\Modly\logs\runtime.log 의 최근 200줄에서
   UnicodeDecodeError 나 "Exception in thread" 가 있는지 세어줘.
4. 결과를 표로 정리해줘: 패치 적용 여부 / 최근 에러 건수 / 판정.

프롬프트 3: 원인만 다시 설명받기

동료에게 공유하거나 이슈를 작성할 때 씁니다.

아래 상황의 근본 원인을 3단계 인과관계로 정리해줘.
비개발자도 이해할 수 있게 쓰되 기술적으로 정확해야 한다.

- 한글 Windows, subprocess.Popen(text=True) 에 encoding 미지정
- 자식 프로세스가 tqdm 진행률 바(UTF-8 블록 문자)를 stderr로 출력
- 부모의 stderr 리더 스레드가 UnicodeDecodeError로 사망
- 이후 자식 프로세스가 CPU 0%, VRAM 점유 상태로 영구 정지

추가로 이 패턴을 예방하는 subprocess 사용 체크리스트 5개도 만들어줘.

AI에게 맡길 때 주의점: <사용자명> 부분은 실제 Windows 계정명으로 바꿔주세요. AI가 파일 경로를 못 찾으면 프롬프트에 실제 경로를 직접 넣어주시면 됩니다.

---

해결 B: 손으로 고치기 (5분)

AI 도구 없이 직접 고치는 방법입니다. 메모장으로도 됩니다.

1단계: 파일 찾기

PowerShell에서 실행하면 정확한 경로가 나옵니다.

Get-ChildItem "$env:LOCALAPPDATA\Programs\Modly" -Recurse -Filter extension_process.py |
  Select-Object -ExpandProperty FullName

보통 이 경로입니다.

C:\Users\<사용자명>\AppData\Local\Programs\Modly\resources\api\services\extension_process.py

2단계: 백업 (건너뛰지 마세요)

$p = "$env:LOCALAPPDATA\Programs\Modly\resources\api\services\extension_process.py"
Copy-Item $p "$p.bak"

3단계: 수정

파일을 열고 subprocess.Popen( 을 찾습니다. 수정 전은 이렇게 생겼습니다.

self._proc = subprocess.Popen(
    [str(python), str(_RUNNER_PATH)],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,
    bufsize=1,
    env=self._build_env(),
)

수정 후입니다. text=True 아래에 두 줄을 추가하면 끝입니다.

self._proc = subprocess.Popen(
    [str(python), str(_RUNNER_PATH)],
    stdin=subprocess.PIPE,
    stdout=subprocess.PIPE,
    stderr=subprocess.PIPE,
    text=True,
    # Pin the pipe codec: on non-UTF-8 locales (e.g. cp949 on Korean
    # Windows) the default locale decoder chokes on tqdm's block
    # characters and kills the stderr reader. Once nothing drains
    # stderr the pipe buffer fills and the worker blocks forever.
    encoding="utf-8",
    errors="replace",
    bufsize=1,
    env=self._build_env(),
)

errors="replace"까지 넣는 이유가 중요합니다. UTF-8이 아닌 바이트가 섞여 들어와도 스레드가 죽는 대신 대체 문자로 넘어가게 하기 위해서입니다. 핵심은 로그 리더가 절대 죽지 않게 만드는 것입니다. 로그를 읽다 죽는 코드가 파이프라인 전체를 멈추는 구조 자체가 위험합니다.

4단계: 문법 확인

python -m py_compile "$env:LOCALAPPDATA\Programs\Modly\resources\api\services\extension_process.py"

아무것도 출력되지 않으면 정상입니다.

5단계: Modly 완전 재시작

창을 닫는 것만으로는 부족합니다. 백엔드 파이썬이 이미 메모리에 올린 모듈을 계속 쓰기 때문입니다. 작업 관리자에서 Modly 관련 프로세스를 모두 종료하거나, 아래로 확실히 정리하세요.

Get-Process | Where-Object { $_.ProcessName -like "*Modly*" } | Stop-Process -Force

같은 text=True를 쓰는 stdout(JSON 프로토콜을 주고받는 쪽)도 동일한 취약점을 안고 있었는데, Popen 한 곳만 고치면 함께 해결됩니다.

---

해결 C: 파일을 건드리지 않는 우회법

설치 폴더를 수정하기 부담스럽다면 시스템 환경변수 하나로도 됩니다.

[Environment]::SetEnvironmentVariable("PYTHONUTF8", "1", "User")

파이썬 UTF-8 모드가 켜지면서 locale.getpreferredencoding(False)가 utf-8을 반환해 같은 효과를 냅니다. 설정 후 로그아웃했다가 다시 로그인하거나 재부팅해야 적용됩니다.

	파일 패치 (해결 A·B)	PYTHONUTF8 (해결 C)
영향 범위	Modly만	PC의 모든 파이썬
앱 업데이트 시	되돌아감, 재적용 필요	그대로 유지
적용 시점	앱 재시작	로그아웃/재부팅
추천 상황	파이썬 환경이 많은 PC	파이썬을 Modly에서만 쓰는 PC

다른 파이썬 프로젝트를 여러 개 돌리는 PC라면 표적 패치(해결 A·B) 쪽이 안전합니다. cp949를 전제로 동작하던 다른 스크립트가 영향을 받을 수 있기 때문입니다.

---

검증: 제대로 고쳐졌는지 확인하기

패치 후 같은 이미지, 같은 설정으로 다시 돌렸습니다.

로그에서 확인할 것

Select-String -Path "$env:APPDATA\Modly\logs\runtime.log" -Pattern "UnicodeDecodeError" |
  Measure-Object | Select-Object -ExpandProperty Count

0이 나와야 합니다.

그리고 예전에 파이프를 막던 바로 그 진행률 바가 이번엔 끝까지 정상적으로 흘렀습니다.

Volume Decoding: 100%|#########9| 4237/4244 [00:25<00:00, 155.81it/s]

결과

항목	값
소요 시간	65초 (모델 로딩 포함)
출력 파일	workspace/Default/1787284060_27486d5c.glb (24.4MB)
정점 / 면	677,255 / 1,358,058
바운딩 박스	약 1.63 × 1.99 × 1.14
watertight	False

무한 정지에서 65초로. 원인은 GPU도, VRAM도, 모델 크기도 아니었습니다. 글자 인코딩 한 줄이었습니다.

---

롤백과 앱 업데이트 대응

되돌리기

문제가 생기면 백업본으로 복구합니다.

$p = "$env:LOCALAPPDATA\Programs\Modly\resources\api\services\extension_process.py"
Copy-Item "$p.bak" $p -Force

앱 업데이트 시 주의

⚠️ 이 파일은 설치 폴더 안에 있어서 Modly를 업데이트하면 원래대로 되돌아갑니다. 업데이트 후 다시 80%에서 멈춘다면 패치가 날아간 것이니 재적용하세요. 앞의 프롬프트 2로 30초면 확인됩니다.

근본적으로는 업스트림에 보고하는 게 맞습니다. 저장소는 github.com/lightningpixel/modly이고, 이 문제는 한글 Windows 사용자 전체가 겪는 사안이라 이슈 제보 가치가 충분합니다. 이슈를 쓰실 때는 앞의 프롬프트 3으로 원인 설명을 정리하면 편합니다.

---

곁들이면 좋은 실전 팁

내 그래픽카드에 맞는 모델 고르기

Modly 공식 레지스트리(lightningpixel/modly-official-extension의 registry.json)에는 확장이 세 개뿐입니다.

확장	요구 VRAM	RTX 3070 8GB
TRELLIS.2-4B	약 24GB	❌ 불가
TripoSG	약 8GB	△ 한계선
Hunyuan3D 2 Mini (+ Turbo)	저사양 대응	✅ 권장

8GB 환경에서는 Hunyuan3D 2 Mini 계열이 사실상 유일한 안정적 선택입니다. Turbo 변형은 guidance-distilled 방식이라 5스텝 내외로 끝나서 빠릅니다.

입력 이미지를 줄여도 빨라지지 않습니다

테스트하면서 입력을 1086×1448 / 1.76MB에서 240×320 / 126KB로 줄여봤습니다. 속도에 거의 영향이 없었습니다. 모델이 내부적으로 고정 해상도로 리사이즈하기 때문입니다.

실제 속도를 결정하는 건 두 가지뿐입니다.

• num_inference_steps — 생성 반복 횟수
• octree_resolution — 형상 해상도

다만 알파 채널이 있는 PNG는 배경 제거 단계에 유리하므로 투명 배경은 살려두세요.

최저 설정인데도 면이 136만 개

octree_resolution=256(최저값)으로 돌렸는데도 면이 135만 개가 나왔습니다. 실사용에는 감면이 필요한데, UI에 노출된 설정으로는 조절할 수 없습니다.

generator.py 152번째 줄 근처를 보면 vertex_count가 있으면 _decimate를 타도록 되어 있는데, 확장 manifest의 params_schema에는 이 항목이 빠져 있습니다. API로 직접 넣으면 동작합니다.

watertight가 False인 것도 Turbo 5스텝에서는 흔한 일입니다. 닫힌 메시가 필요하면 스텝을 10–20으로 올리거나 Modly 내장 mesh-repair 확장을 거치세요.

---

정리: 이 버그가 남긴 교훈

이번 사례에서 챙길 것은 Modly 패치 방법 하나가 아닙니다.

• 가짜 진행률은 사용자를 속입니다. 실제 작업과 연결되지 않은 진행률 바 때문에 “거의 다 됐는데 마지막이 무겁구나”라고 오해했습니다. 실제로는 시작하자마자 죽어 있었습니다. 진행률을 만들 거라면 최소한 멈췄을 때 멈춘 것처럼 보여야 합니다.
• 로케일 버그는 영어권에서 재현되지 않습니다. text=True에 encoding=을 생략하는 습관은 개발자 PC에서 멀쩡히 동작하다가 한글 Windows 사용자에게서만 터집니다. 국내 사용자가 직접 찾아 고치고 보고해야 하는 유형입니다.
• 파이프를 만들었으면 끝까지 읽어야 합니다. subprocess + 아무도 안 읽는 파이프 = 무한 정지. 오래된 함정인데 지금도 계속 재생산됩니다. 로그 읽는 코드에는 errors="replace"를 걸어 절대 죽지 않게 만드세요.
• 로그보다 먼저 CPU 누적 시간을 보세요. “느린 것”과 “블록된 것”을 3분 만에 구분해 줍니다. 이 판별을 먼저 했다면 VRAM을 의심하며 보낸 시간을 아꼈을 겁니다.

같은 증상으로 헤매고 계셨다면, 지금 프롬프트 1을 복사해서 AI 도구에 붙여넣어 보세요. 65초 뒤에 GLB 파일이 나옵니다.