Communitygithub.com

nynuz/ml-serving-skills

머신러닝 모델 서빙을 위한 에이전트 스킬 모음, API 백엔드부터 프론트엔드까지.

ml-serving-skills란 무엇인가요?

이 스킬은 Hugging Face 모델 ID를 입력받아 프로덕션 등급의 FastAPI 프로젝트를 자동 생성합니다. 텍스트 분류, 토큰 분류(NER), 텍스트 임베딩, 이미지 생성의 네 가지 태스크 패밀리를 지원하며, 각 태스크에 맞는 추론 엔드포인트, 입력/출력 검증, 헬스 체크, 에러 처리를 포함한 완전한 프로젝트 구조를 생성합니다. 모델은 한 번만 로드되어 재사용되며, 배치 처리 크기와 입력 길이에 명시적인 제한을 두어 리소스 사용을 제어합니다. 로컬 환경에서 uvicorn으로 실행되며, Docker나 클라우드 배포, 프론트엔드 코드는 생성하지 않습니다. 사용자는 생성된 프로젝트에서 pip install과 uvicorn 실행만으로 즉시 API 서버를 운영할 수 있습니다.

지원 대상~Claude Code~Codex CLI~Cursor
npx skills add nynuz/ml-serving-skills

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

HF Model → FastAPI Builder

이 스킬이 하는 일

Hugging Face model_id를 입력받아 자체 포함된 로컬 프로덕션 등급 FastAPI 프로젝트를 생성합니다: 계층화된 앱 구조, 시작 시 한 번 로드되는 모델(요청마다 로드하지 않음), 태스크에 적합한 추론 엔드포인트, 명시적 상한이 있는 배치 처리, 입력/출력 검증, 헬스 및 준비 프로브, 구조화된 에러 처리, 선택적 평가/벤치마크 스크립트를 포함합니다.

다음 네 가지 태스크 패밀리를 지원하며, 각 패밀리는 서로 다른 엔드포인트 형태와 기반 라이브러리를 사용합니다:

태스크 패밀리HF 개념라이브러리참조 파일
텍스트 분류AutoModelForSequenceClassificationtransformersreferences/text-classification.md
토큰 분류(NER)AutoModelForTokenClassificationtransformersreferences/token-classification-ner.md
텍스트 임베딩문장 임베딩 모델sentence-transformersreferences/embeddings.md
이미지 생성확산 파이프라인diffusersreferences/image-generation.md

범위 경계 — 시작하기 전에 읽으세요

  • 로컬 전용. Docker, Kubernetes, 클라우드 배포(Railway, AWS 등)는 없습니다. 출력물은 사용자가 자신의 머신에서 uvicorn으로 실행하는 프로젝트입니다.
  • 백엔드 전용. 프론트엔드/클라이언트 코드(React, Next.js, fetch 호출 등)를 절대 생성하지 마십시오. 사용자가 API를 호출할 UI를 원한다면, 이는 별도의 문제라고 알리고 API 경계에서 멈추십시오. 로컬 CORS를 허용적으로 설정하여 나중에 프론트엔드 개발 서버가 API를 호출할 수 있도록 하는 것은 괜찮습니다 — 이는 백엔드 구성 문제이지 프론트엔드 코드가 아닙니다.
  • 서빙, 학습이 아님. 사용자가 모델을 미세 조정하거나 학습시키려는 경우, 이 스킬은 적절한 도구가 아닙니다 — 그렇게 말하십시오.
  • 로컬 단일 사용자 위협 모델. 생성된 서비스는 인증 및 속도 제한이 없습니다 — 이는 localhost에서 실행되도록 설계되었습니다. 그러나 입력 비용 상한(배치 크기, 문자열당 길이, 생성 파라미터, 요청 본문 크기 제한 → 413)을 강제합니다. 사용자에게 인증, 속도 제한, 강화된 CORS 정책을 먼저 추가하지 않고 서비스를 0.0.0.0에 바인딩하거나 localhost 너머로 노출하지 말라고 항상 알리십시오 — 이러한 작업은 이 스킬의 범위를 벗어납니다.
  • 묻지 않고 설치하거나 실행하지 마십시오. 프로젝트를 스캐폴딩하고 사용자에게 정확한 실행 명령을 제공하십시오. 사용자가 명시적으로 작동 확인을 요청한 경우에만 직접 pip install하거나 uvicorn을 시작하십시오 — 일부 종속성(torch, diffusers)은 다운로드 크기가 큽니다.

워크플로우

1단계: 입력 수집

다음이 필요합니다:

  • model_id (필수) — Hugging Face Hub ID, 예: distilbert-base-uncased-finetuned-sst-2-english.
  • 출력 디렉토리 (주어지지 않으면 물어보고, 기본값은 현재 작업 디렉토리의 ./<모델-이름-슬러그>-api).
  • 선택 사항: 작은 레이블이 있는 평가 데이터셋 경로(나중에 정확성 평가용), 포트(기본값 8000).

사용자가 노트북에서 수행한 작업만 설명하는 경우("pipeline(...)으로 로드하고 감정 분류합니다"), 정확한 model_id가 명시되지 않았다면 물어보십시오 — 모든 하위 작업이 이에 의존합니다.

2단계: 모델 검사

번들된 검사기를 실행하십시오 — 이는 공개 HF Hub API만 호출하며, 모델 가중치를 다운로드하지 않습니다:

python scripts/inspect_model.py <model_id>

이 명령은 task_family, pipeline_tag, library_name, architectures, id2label(사용 가능한 경우), num_labels, 대략적인 파라미터 수, 장치 권장 사항을 포함한 JSON을 출력합니다.

  • task_family가 지원되는 네 가지 패밀리 중 하나이면 진행합니다.
  • "unknown"으로 반환되거나 추측이 틀렸다고 생각되면(일부 저장소의 메타데이터가 누락/잘못됨), 사용자에게 네 가지 태스크 패밀리 중 어떤 것이 적용되는지 물어보십시오 — 조용히 잘못 추측하지 마십시오. 엔드포인트 형태가 이에 전적으로 의존합니다.
  • 스크립트가 not_found_or_gated를 보고하면, HF의 공개 API가 401/403/404를 반환한 것입니다 — 이는 model_id가 잘못되었거나(오타/잘못된 네임스페이스) 저장소가 게이트/비공개임을 의미합니다. 어느 쪽인지 알 수 없습니다. 먼저 사용자와 정확한 model_id를 재확인하십시오(오타와 잘못된 조직 네임스페이스가 가장 흔한 원인). 확인된 경우에만 게이트된 것으로 간주하고 사용자에게 모델 페이지에서 라이선스를 수락하고 인증하도록 요청하십시오. HF_TOKEN 환경 변수(HF_TOKEN=hf_xxx python scripts/inspect_model.py <model_id>) 또는 huggingface-cli login을 통해 토큰을 전달하는 것을 선호하십시오. --token 플래그는 명령줄 기록과 프로세스 목록에 토큰이 유출되므로 피하십시오.

3단계: 해당 참조 파일 읽기

스캐폴딩하기 전에, 2단계의 태스크 패밀리에 대한 references/<task-family>.md를 읽으십시오. 여기에는 정확한 파이프라인/모델 로딩 코드, 요청/응답 스키마, 태스크별 주의사항(예: 분류의 레이블 매핑, NER의 엔티티 집계, 임베딩의 풀링 전략, 생성의 이미지 인코딩)이 포함되어 있습니다. 또한 세션당 한 번씩 references/architecture.md를 훑어보십시오 — 이 문서는 네 가지 태스크 패밀리 모두에 동일한 부분(수명 로딩, 헬스 프로브, CORS, 에러 처리)을 다루므로 매번 다시 유도할 필요가 없습니다.

참조 파일이 다루지 않는 모델 로딩, 토크나이제이션, 장치 배치(CPU/CUDA/MPS), dtype 선택에 대해서는 이미 설치된 transformers-huggingface 스킬을 사용하십시오 — 이 스킬은 transformers 라이브러리 자체에 대한 권위 있는 패턴을 가지고 있습니다.

4단계: 프로젝트 스캐폴딩

2단계에서 얻은 태스크 패밀리와 레이블/구성 정보를 사용하여 생성기를 실행하십시오:

python scripts/scaffold_project.py \
  --model-id "<model_id>" \
  --task <text-classification|token-classification|embeddings|image-generation> \
  --output-dir "<output_dir>" \
  --id2label-json "<json-파일-경로-또는-인라인-json>"   # 선택 사항, 분류/NER만 해당

python scripts/scaffold_project.py --help를 실행하여 모든 플래그(포트, 최대 배치 크기, 최대 입력 길이/이미지 크기 등)를 확인하고 — 2단계에서 학습한 관련 값을 기본값 대신 전달할 수 있으면 전달하십시오.

이 명령은 다음을 생성합니다:

<output_dir>/
├── app/
│   ├── main.py            # FastAPI() + 수명(모델 한 번 로드, 워밍업), CORS, 라우터 마운트
│   ├── core/
│   │   ├── config.py      # pydantic-settings: MODEL_ID, DEVICE, MAX_BATCH_SIZE 등 환경 변수에서
│   │   └── model.py       # load_model() / 선택한 태스크 패밀리의 추론 함수
│   ├── api/
│   │   └── routes.py      # 태스크 엔드포인트 + /health/live + /health/ready + /v1/info
│   └── schemas.py         # Field 제약 조건이 있는 Pydantic 요청/응답 모델
├── tests/
│   ├── test_health.py
│   └── test_inference.py  # 정상 경로 + 유효성 검사 오류 사례
├── requirements.txt       # 이 태스크 패밀리에만 필요한 것
├── .env.example
├── README.md              # 실행 지침, 엔드포인트 문서, CORS 참고 사항
└── .gitignore

스캐폴더는 프로그래밍 방식으로 결정할 수 있는 것(모델 ID, 태스크 패밀리, 전달한 경우 레이블)을 채웁니다. 생성된 app/core/model.py와 app/schemas.py를 3단계의 참조 파일과 비교하여 여전히 검토해야 합니다 — 스캐폴더는 모델을 호출하지 않으므로 --id2label-json을 전달하지 않은 경우 정확한 레이블 집합이나 NER 모델이 aggregation_strategy="simple"을 필요로 하는지 알 수 없습니다. 남겨진 # TODO 표시를 채우십시오.

5단계: 교차적인 프로덕션 고려 사항 확인

생성된 모든 프로젝트에는 다음이 모두 있어야 합니다 — 명시적으로 확인하십시오. 생성된 코드를 수동 편집할 때 조용히 빠뜨리기 쉽습니다:

  • 모델이 lifespan에서 로드되고, 임포트 시점이나 요청별로 로드되지 않음(app/main.py)
  • 로드 직후 워밍업 호출(더미 추론 한 번) — 첫 번째 실제 요청이 느리지 않도록 함 — references/architecture.md 참조
  • /health/live(프로세스 활성, 종속성 검사 없음)는 /health/ready(모델 로드 확인)와 다른 함수여야 함 — 이를 혼동하면 재시작 연쇄가 발생합니다. references/architecture.md 참조
  • 모든 추론 응답에는 모델 ID/버전이 포함되어야 함 — 협상 불가, 나중에 "어떤 모델이 이 결과를 생성했는지" 디버깅하는 방법입니다.
  • 배치 입력에는 서버가 강제하는 최대 길이/크기가 있어야 함(Field(..., max_length=...)) — 경계 없는 배치는 무제한 GPU/CPU 소비입니다. 스캐폴더는 각 개별 문자열도 제한합니다(StringConstraints(max_length=...), --max-chars-per-text로 조정) 그리고 main.py의 413 미들웨어를 통해 과도한 크기의 요청 본문을 거부합니다(--max-request-mb) — 수동 편집 후에도 두 가지 모두 유지되었는지 확인하십시오. 본문 크기 검사는 페이로드가 메모리에 파싱되기 전에 발동되는 유일한 방어 장치이기 때문입니다.
  • CPU/GPU 바운드 추론은 anyio.to_thread.run_sync(...)를 통해 실행되어야 하며, 절대 async def 핸들러에서 직접 실행하지 않음 — 그렇지 않으면 다른 모든 진행 중인 요청에 대해 이벤트 루프를 차단합니다.
  • 유효성 검사 오류는 유용한 메시지와 함께 422를 반환하고; 모델/런타임 오류는 캐치되어 유형화된 HTTP 오류로 매핑되며, 처리되지 않은 500과 스택 추적이 클라이언트에 유출되지 않아야 합니다.

기본적으로 사용되는 배치 배열 패턴과 (로컬 단일 사용자 설정의 경우 드물게) 동적 마이크로 배칭이 추가 복잡성을 감수할 가치가 있는 경우는 references/batching.md를 참조하십시오.

6단계: 테스트

스캐폴더는 fastapi.testclient.TestClient를 사용하여 tests/test_health.py와 tests/test_inference.py를 생성합니다(references/testing-and-evaluation.md 참조). 이를 읽고 샘플 입력/예상 형태를 실제 모델에 맞게 조정한 후 사용자에게 실행을 지시하십시오:

pytest

7단계: 평가 및 벤치마킹(선택 사항, 사용자가 원하는 경우에만)

두 개의 독립적인 스크립트가 번들되어 있습니다 — 생성된 프로젝트의 디렉토리에 복사하십시오(FastAPI 앱 자체의 일부가 아니라 실행 중인 서버를 호출하는 도구입니다):

  • scripts/evaluate.py — 정확성: 레이블이 있는 데이터셋(CSV/JSONL)을 실행 중인 API에 대해 실행하고 정확도/F1(분류, NER) 또는 코사인 유사성 검사(임베딩)를 보고합니다. 사용자의 레이블 데이터가 필요합니다 — 경로를 요청하거나 사용자에게 아직 데이터가 없으면 건너뜁니다.
  • scripts/benchmark.py — 성능: 실행 중인 API에 동시 요청을 보내고 p50/p95/p99 지연 시간과 처리량을 보고합니다. 레이블 데이터가 필요하지 않으며, 몇 가지 예제 입력만 있으면 됩니다.

정확한 사용법과 출력 해석 방법은 references/testing-and-evaluation.md를 참조하십시오.

8단계: 마무리

사용자에게 로컬에서 실행할 정확한 명령을 제공하십시오:

cd <output_dir>
python -m venv .venv && source .venv/bin/activate   # Windows의 경우 .venv\Scripts\activate
pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

대화형 테스트를 위해 /docs(FastAPI의 자동 OpenAPI UI)를 안내하십시오. 수행하지 않은 작업을 명시적으로 밝히십시오: Docker 이미지 없음, 클라우드 배포 없음, 프론트엔드 코드 없음. 사용자가 이러한 작업을 다음에 원한다면, 이 스킬의 범위를 벗어납니다.

문제 해결

  • inspect_model.py가 task_family: unknown을 반환함: 저장소의 메타데이터가 불완전합니다. 사용자에게 직접 네 가지 패밀리 중 어떤 것인지 물어보고, 스캐폴더에 --task를 명시적으로 전달하십시오.
  • 모델에 trust_remote_code=True / 사용자 정의 코드가 필요함: 스캐폴딩 전에 사용자에게 이를 알리십시오 — 이는 Hub의 임의 코드가 로컬에서 실행됨을 의미합니다. 해당 플래그를 설정하는 프로젝트를 생성하기 전에 명시적 확인을 받으십시오.
  • 사용자가 표에 없는 태스크 패밀리를 원함(예: 음성, 번역, VQA): 이 스킬이 현재 나열된 네 가지 패밀리만 지원한다고 명확히 말하고, 네 가지 참조 파일 중 하나에 억지로 맞추는 대신 references/architecture.md의 동일한 아키텍처 패턴을 사용하여 FastAPI 래퍼를 수동으로 구축하겠다고 제안하십시오.
  • 생성된 requirements.txt 설치가 느리거나 큼: torch와 diffusers는 큽니다. 태스크 패밀리가 이를 가져오는 경우 사용자가 pip install을 실행하기 전에 경고하십시오.

관련 스킬