NPU 워커 인터페이스 명세서 v1.0

박씨 양산 자동화 = NPU + ZipVoice 단일 트랙. GPU 0.

오늘(2026-05-07~08) 본진 e2e 3회 실패 분석에서 도출한 streaming 응답 필수 설계.

0. 박힌 결정 (재확인)

• 학습 가중치(.pth) 폐기 / 박씨 음성 데이터(1~2분) 재활용
• 워커 = HTTP (sovits_worker.py와 동일 구조)
• 호출자 인터페이스 = `tts_engine.py`가 환경변수 하나로 워커 base 갈아끼움
• voice MCP `lecture_timeline`은 **long-blocking 응답 금지** — 슬라이드별 streaming 응답

1. 진단 — 왜 streaming이 필수인가

본진 e2e 3회 실패 패턴

voice MCP.lecture_timeline (단일 SSE 세션)
  → 슬라이드 1 추론 (12s)
  → 슬라이드 2 추론 (12s)
  ...
  → 슬라이드 N 추론
  → 39슬라이드 끝나면 한 번에 sections+wav_paths 반환

문제:

• mcp 라이브러리 RPC default timeout ≈ 7분
• CPU 워커 39슬라이드 ≈ 8~26분 (텍스트 길이에 따라)
• 15슬라이드 처리 후 RPC 끊김 (재현 3회, 일관됨)
• pipeline 측 `sse_read_timeout` 늘려도 무용 (mcp 자체 timeout 따로)
• NPU 가도 cold start + 39슬라이드 = 1~2분 + 발열 가능 → 마진 충분히 줘야 함

해법 — 슬라이드별 진행 보고

voice MCP.lecture_timeline (streaming 응답)
  → progress event 1: {idx: 0, status: "synth", text: "..."}
  → progress event 1: {idx: 0, status: "ok", wav_path: "...", duration: 4.3}
  → progress event 2: {idx: 1, status: "synth", ...}
  ...
  → final: {sections: [...], wav_paths: [...]}

각 progress event = mcp 측 keepalive 역할 + pipeline.py가 즉시 다음 단계(actor 녹화 등) 병렬 시작 가능.

2. NPU 워커 HTTP 인터페이스

2.1 기본 정보

	항목	값
	기본 포트	`7768` (sovits_worker=7766 + 2)
	환경변수	`NPU_WORKER_HOST`, `NPU_WORKER_PORT`
	서버	`ThreadingHTTPServer` (sovits_worker와 동일)
	백엔드	ZipVoice ONNX + onnxruntime-qnn (1차) / Coqui XTTS (백업)
	박씨 레퍼런스	`~/parksy-audio/voice_models/parksy_ref/parksy_ref_30s.wav` (예정)

2.2 엔드포인트

`GET /health` — 워커 상태

{
  "status": "ok",
  "loaded": true,
  "load_seconds": 8.2,
  "backend": "zipvoice-onnx",
  "device": "qnn",
  "ref_wav": "/home/dtsli/parksy-audio/voice_models/parksy_ref/parksy_ref_30s.wav",
  "version": "v1.0"
}

• `device`: `"qnn"` | `"cpu"` | `"cuda"` (qnn 실패 시 자동 fallback)
• 추론 중에도 즉시 응답 (ThreadingHTTPServer 보장)

`POST /synth` — 단일 합성 (sovits_worker 호환)

요청:

{
  "text": "안녕하세요. 박씨 음성 합성 테스트입니다.",
  "lang": "ko",
  "output_path": "/tmp/parksy_air/.../s00.wav",
  "speed_factor": 1.0,
  "ref_wav": null
}

응답:

{
  "status": "ok",
  "output": "/tmp/parksy_air/.../s00.wav",
  "wav_path": "/tmp/parksy_air/.../s00.wav",
  "duration_sec": 4.32,
  "sample_rate": 24000,
  "elapsed_sec": 1.8,
  "rtf": 0.42,
  "engine": "zipvoice-onnx",
  "device": "qnn"
}

• `tts_engine.py`의 `_generate_via_worker()` 인터페이스와 100% 호환
• `ref_wav` 미지정 시 워커 default 박씨 레퍼런스 사용

`POST /synth_batch` — 슬라이드별 streaming (NEW)

요청:

{
  "sections": [
    {"idx": 0, "text": "...", "output_path": "/tmp/.../s00.wav"},
    {"idx": 1, "text": "...", "output_path": "/tmp/.../s01.wav"},
    ...
  ],
  "lang": "ko",
  "speed_factor": 1.0,
  "ref_wav": null,
  "stream": true
}

응답: Content-Type: application/x-ndjson (NDJSON streaming)

{"event":"start","total":39,"backend":"zipvoice-onnx","device":"qnn"}
{"event":"progress","idx":0,"status":"synth"}
{"event":"progress","idx":0,"status":"ok","wav_path":"/tmp/.../s00.wav","duration_sec":4.32,"elapsed_sec":1.8}
{"event":"progress","idx":1,"status":"synth"}
{"event":"progress","idx":1,"status":"ok","wav_path":"/tmp/.../s01.wav","duration_sec":3.10,"elapsed_sec":1.5}
...
{"event":"progress","idx":38,"status":"ok",...}
{"event":"done","total":39,"ok_count":39,"fail_count":0,"elapsed_total_sec":78.5}

핵심 약속:

• **각 라인 = 즉시 flush** (TCP NODELAY, `wfile.flush()` 강제)
• 클라이언트는 line 단위로 stream 파싱 → keepalive + 진행률 표시 가능
• `event=done` 받으면 종료
• `event=error` 발생 시 `idx`/`error` 포함, 다음 슬라이드 계속 시도 (전체 중단 X)

`POST /synth_batch?async=1` — polling 모드 (백업)

streaming 안 되는 환경(예: Cloudflare/proxy buffering)을 위한 polling 대안.

응답:

{"job_id": "abc123", "status": "queued", "total": 39}

GET /jobs/abc123/status →

{
  "job_id": "abc123",
  "status": "running",
  "done": 12,
  "total": 39,
  "ok": 12,
  "fail": 0,
  "current_idx": 12,
  "elapsed_sec": 14.2
}

GET /jobs/abc123/result (완료 후) →

{
  "job_id": "abc123",
  "status": "done",
  "sections": [...],
  "wav_paths": [...],
  "elapsed_total_sec": 78.5
}

2.3 에러 응답 표준

{
  "status": "fail",
  "error": "ModelLoadError: ZipVoice ONNX 모델 로드 실패",
  "traceback": "...",
  "fallback": "cpu"
}

HTTP 상태:

• 200 — 정상 (응답 body의 `status`로 판정)
• 400 — 잘못된 요청 (text/output_path 누락 등)
• 500 — 워커 내부 오류 (모델 로드 실패 등)
• 503 — 워커 부팅 중 (`loaded: false`)

3. tts_engine.py 변경 (최소)

# 환경변수 하나로 백엔드 갈아끼움
_WORKER_BASE = os.environ.get(
    "TTS_WORKER_BASE",
    f"http://{_WORKER_HOST}:{_WORKER_PORT}",  # 기본 sovits 7766
)

# /synth 호출은 동일 — 응답 포맷 호환
# /synth_batch 새 헬퍼만 추가

TTS_WORKER_BASE=http://127.0.0.1:7768 설정만으로 NPU 워커로 전환.

4. voice MCP 측 streaming 클라이언트 헬퍼

parksy_voice/streaming_client.py (신설 예정) — lecture_timeline 내부에서 호출:

async def synth_batch_streaming(
    sections: list[dict],
    on_progress: Callable[[int, dict], None] | None = None,
) -> dict:
    """NDJSON streaming으로 슬라이드별 progress 받음."""
    body = json.dumps({"sections": sections, "stream": True}).encode("utf-8")
    req = urllib.request.Request(f"{_WORKER_BASE}/synth_batch",
                                 data=body, headers={"Content-Type": "application/json"})
    results = []
    with urllib.request.urlopen(req, timeout=3600) as resp:
        for raw_line in resp:
            line = raw_line.decode("utf-8").strip()
            if not line:
                continue
            event = json.loads(line)
            if event["event"] == "progress" and event.get("status") == "ok":
                results.append(event)
                if on_progress:
                    on_progress(event["idx"], event)
            elif event["event"] == "done":
                break
            elif event["event"] == "error":
                # 개별 슬라이드 실패는 결과에만 기록, 전체 중단 X
                if on_progress:
                    on_progress(event.get("idx", -1), event)
    return {"sections": results, "wav_paths": [r["wav_path"] for r in results]}

핵심: urlopen(...)이 line iterator 지원 → 각 NDJSON 라인이 들어올 때마다 즉시 처리. mcp RPC default timeout 회피.

5. 마이그레이션 순서

1. ✅ 인터페이스 명세 (이 문서)

2. NEXT — npu_worker.py 스켈레톤 + sovits_worker fallback (ZipVoice 통합 전이라도 동일 인터페이스로 sovits 호출)

3. streaming_client.py 작성 + 단위 테스트

4. voice MCP lecture_timeline 내부를 batch streaming 호출로 교체

5. phone_aider DeepSeek 결과 받아 ZipVoice ONNX 모델 통합

6. onnxruntime-qnn EP 추가 (qnn 실패 시 cpu fallback)

7. 본진 39슬라이드 e2e v4 → 풀 통과 검증

6. 인터페이스 안정성 약속

이 문서가 박힌 후 변경 시 v2 별도 명세서로 만든다. v1 호환성 유지.

	항목	안정성
	`/synth` 요청/응답 schema	🔒 sovits_worker와 영구 호환
	`/synth_batch` NDJSON event 포맷	🔒 v1 고정 (event/idx/status/wav_path 필드 영구)
	`TTS_WORKER_BASE` 환경변수	🔒 영구
	새 backend 추가	✅ device 필드만 늘리면 됨

7. 박씨 헌법 일치 검증

	헌법	충족
	양산 자동화 (박씨 시간 0)	✅ batch streaming으로 39슬라이드 무인 처리
	GPT-SoVITS 박씨 음색	✅ ZipVoice 검증 통과 시 / 부족 시 1회 파인튜닝
	GPU 0 (양산)	✅ NPU 직행 / Vast.ai는 1회성 파인튜닝만
	강박적 redundancy 금지	✅ 단일 트랙 (sovits → npu 전환). 사용 중 백엔드 1개
	edge-tts 양산 금지	✅ NPU 워커는 박씨 음색 only, edge-tts fallback X

---

작성: 2026-05-08

관련 커밋: 02f2650 (sovits_worker 베이스), bcf1e6d (pipeline timeout)

다음 작업: npu_worker.py 스켈레톤 (Task #8)

← Back to Document Library · PARKSY Audio