HuggingFace 모델 예제 생성

HuggingFace 모델 URL을 받아 실행 가능한 Python 예제 + 샘플 출력 + RTF 측정 + REPORT.md를 한 세트로 생성하는 실험 스킬. TTS·음성·오디오 모델이 주 타겟.

상태: 실험 단계 (contrib/experimental/huggingface-model-example/). 자동 등록된 슬래시 커맨드 없음 → 에이전트가 SKILL.md 절차로 호출한다. 승격 기준 충족 시 skills/domain/huggingface-model-example/로 이동.

1. 무엇을 하는 스킬인가

사용자 메시지에 huggingface.co/... URL과 "예제/샘플/데모 만들어줘" 류 요청이 함께 있을 때 트리거. 다음을 한 세트로 생성한다.

1. 자기완결 Python 스크립트 — 공식 경로로 모델 로딩, 대표 기능 1개 호출
2. 실제 샘플 출력 — out/*.wav (최소 1개, 0바이트 아님)
3. RTF 측정 — wall-clock 기반, gen_sec / audio_sec
4. REPORT.md — 모델 정보 + 추론 상세(verbatim) + 스트리밍 가능성

범위 밖: 배포, 대규모 벤치마크, 모델 비교 보고.

2. 작업 공간 (HF_EXAM_DIR)

산출물은 레포 바깥의 별도 작업 공간에 둔다. 환경 변수로 지정.

export HF_EXAM_DIR=/path/to/your/hf_model_exam_workspace

• 기본값 없음 — 미설정이면 에이전트가 경로를 사용자에게 묻는다.
• 구조:

  $HF_EXAM_DIR/
    _ref/                       # 공용 레퍼런스 자산 (모델 간 재사용)
      ref_spk_a.wav
      ref_spk_b.wav
      prompt.txt                # 레퍼런스 전사 (포맷은 스크립트가 파싱)
    <model-name>/               # HF URL 의 model 부분 그대로
      <feature>.py
      REPORT.md
      out/
        <sample>.wav
  

• 레퍼런스 경로는 절대경로로 하드코딩 — os.environ["HF_EXAM_DIR"] 같은 런타임 참조 금지. 재현성 우선.

레퍼런스 자산 슬롯 (권장)

작업 공간을 처음 꾸밀 때 준비하면 좋은 것들 (파일명은 자유).

레퍼런스 언어는 작업 공간이 다루는 주력 언어에 맞추면 됨. 스킬 자체는 언어를 가정하지 않는다.

3. 폴더명 규칙

• 기본: HF URL 의 model 부분을 풀네임 그대로.
  • Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign → Qwen3-TTS-12Hz-1.7B-VoiceDesign/
  • OpenMOSS-Team/MOSS-TTSD-v1.0 → MOSS-TTSD-v1.0/
• 사용자가 명시한 경우만 지정값 사용 (예: "orpheus 폴더에").
• 줄임말·별칭은 사용자가 직접 요청하지 않는 한 만들지 않는다.

같은 계열의 다른 체크포인트(-VoiceDesign vs -CustomVoice)가 한 작업 공간에서 충돌하지 않도록 풀네임 유지가 기본.

4. 작업 흐름 (요약)

1. HF_EXAM_DIR 확인 + _ref/ 자산 점검
       │
       ▼
2. 모델 카드 + (필요 시) GitHub 원본 코드 수집
       │
       ▼
3. 자매 폴더 스타일 답습
       │
       ▼
4. 대표 기능 1개 선정 (스크립트당 1 기능)
       │
       ▼
5. 꼭 필요한 입력만 사용자에게 질의
       │
       ▼
6. 스크립트 작성 (절대경로 + perf_counter 측정)
       │
       ▼
7. Python 환경 선택 (transformers 버전 매칭)
       │
       ▼
8. 실행 → out/*.wav + RTF stdout
       │
       ▼
9. REPORT.md 작성 (verbatim, 꾸며내지 않음)

상세 절차·예시는 SKILL.md 참조.

5. Python 환경 매칭

모델 코드가 import 하는 transformers API 를 근거로 선택. 사용자의 환경 관리자 (conda/venv/uv/poetry)는 스킬이 결정하지 않음.

애매하면 최신 호환 버전부터 시도. ImportError 발생 시 한 단계 낮춤.

6. RTF 해석 가이드

주의: 카드·코드에 스트리밍 지원이 명시돼 있지 않으면 "RTF 는 낮으나 공식 스트리밍 API 는 확인 안 됨" 식으로 구분 표기.

7. REPORT.md 핵심 원칙

리포트는 재현성이 최상위 가치.

• 수치는 실측값 — 모르면 - 또는 (카드 미기재). 꾸며내지 말 것.
• 추론 상세는 verbatim — 프롬프트·대화·special token·ChatML messages 전부 원문 그대로 코드펜스에 박는다. 길어도 잘라 쓰지 말 것.
• 알 수 없는 값은 (확인 불가) — black-box 캡슐화로 외부에서 확정 불가한 경우 명시.
• 경로는 절대경로.

리포트 필수 섹션: 모델 기본정보 / 특장점 / 저자·라이선스 / 샘플 생성 결과(RTF 포함) / 추론 상세 / 스트리밍 가능성 / 재현 방법 / 함정. 템플릿 전문은 SKILL.md.

8. 자주 만나는 함정

9. 사용 안 되는 경우

• "모델 X 어떻게 써?" 류의 구체적 예제 요청 없는 일반 질문
• HuggingFace 가 아닌 다른 경로의 모델
• 폴더명만 받았을 뿐 HF URL 이 없는 요청

10. 승격 기준 (experimental → skills/)

• 최소 3개 서로 다른 아키텍처 모델에서 무인 완주 성공 (스크립트+샘플+리포트).
• 팀원 2명 이상이 자신의 HF_EXAM_DIR로 재현 성공.
• 리포트 템플릿 필드가 실측값으로 80% 이상 채워짐.
• 승격 시 skills/domain/huggingface-model-example/ 로 이동 + PR 리뷰.

11. 관련 자원