Spaces Dev Mode: Spaces에서 매끄러운 개발

Spaces Dev Mode: Spaces에서 매끄러운 개발

[!WARNING] Spaces Dev Mode는 PRO 또는 Team & Enterprise 요금제의 일부예요.

Spaces Dev Mode는 애플리케이션 디버깅을 쉽게 하고 Spaces 반복 작업을 빠르게 만드는 기능이에요.

출처: 문서

본문

Spaces Dev Mode

Space 저장소에 변경사항을 커밋할 때마다 기본 Docker 이미지가 재빌드되고, 새 컨테이너를 호스팅할 새 가상 머신이 프로비저닝돼요.

Dev Mode는 Docker 이미지를 오버라이드해 Space를 훨씬 빠르게 업데이트할 수 있게 해줘요.

Dev Mode Docker 이미지는 애플리케이션을 하위 프로세스로 시작해서, Space 컨테이너 자체를 멈추지 않고 애플리케이션을 재시작할 수 있게 해줘요. 또한 백그라운드에서 SSH 서버(로컬 에디터·터미널용)와 VS Code 서버(제품 내 VS Code Web용)를 시작해 Space에 연결할 수 있게 해줘요.

실행 중인 Space에 연결할 수 있는 능력은 여러 사용 사례를 열어줘요:

  • Space를 매번 재빌드하지 않고 앱 코드를 변경할 수 있어요.
  • 실행 중인 애플리케이션을 디버깅하고 리소스를 실시간 모니터링할 수 있어요.

전체적으로 Docker 이미지 재빌드 단계를 건너뛰어 Spaces 개발·실험을 훨씬 빠르게 해줘요.

인터페이스

Space에서 Dev Mode를 켜면 다음과 같은 모달이 보여요.

코드를 변경해도 애플리케이션은 자동으로 재시작되지 않아요. 변경사항이 Space에 반영되려면 앱을 재시작하는 Refresh 버튼을 사용해야 해요.

Gradio SDK를 쓰거나 애플리케이션이 Python 기반이라면 requirements가 자동으로 설치되지 않는 점에 주의하세요. VS Code나 SSH에서 수동으로 pip install을 실행해야 해요.

연결하기

Dev Mode는 실행 중인 Space를 표준 SSH 호스트로 노출해요. VS Code와 다른 에디터는 같은 SSH 엔드포인트로 연결해요.

SSH

Dev Mode가 실행되면 다음으로 연결하세요:

ssh <space-subdomain>@ssh.hf.space

서브도메인은 Dev Mode 제어 모달에 표시돼요. 프로그래밍 방식으로도 가져올 수 있어요:

from huggingface_hub import HfApi
print(HfApi().space_info("namespace/repo").subdomain)

Hugging Face CLI가 서브도메인을 해석해 세션을 열어 줄 수 있어요:

# SSH into the Space's Dev Mode container
hf spaces ssh username/my-space

# Print the SSH command instead of running it
hf spaces ssh username/my-space --dry-run

# Use a specific identity file
hf spaces ssh username/my-space -i ~/.ssh/id_ed25519

--auto를 전달하면 아직 실행 중이지 않을 때 프롬프트 없이 Dev Mode를 켜요. 전체 옵션 목록은 hf spaces ssh CLI 레퍼런스를 참고하세요.

SSH로 Space에 연결하려면 머신의 SSH 공개 키를 사용자 계정에 추가해야 해요. 자세한 지침은 Git over SSH 문서를 확인하세요.

VS Code

로컬 VS Code 설치로 Space 컨테이너에 연결할 수도 있어요. Remote - SSH 확장을 설치하고 같은 <space-subdomain>@ssh.hf.space 호스트에 연결하면 돼요.

변경사항 유지하기

Dev Mode가 켜진 동안 변경한 내용은 Space 저장소에 자동으로 유지되지 않아요. 기본적으로 Dev Mode가 꺼지거나 Space가 수면 상태가 되면 폐기돼요.

Dev Mode 중 변경한 내용을 유지하려면 Space 컨테이너 안에서(VS Code 또는 SSH로) git을 사용해야 해요. 예:

# Add changes and commit them
git add .
git commit -m "Persist changes from Dev Mode"

# Push the commit to persist them in the repo
git push

Space에 커밋되지 않았거나 푸시되지 않은 변경사항이 있으면 모달이 경고를 표시해요.

Dev Mode 활성화하기

웹 인터페이스 또는 API를 통해 Space에서 Dev Mode를 켤 수 있어요.

API로

프로그래밍 방식으로 Dev Mode를 토글할 수 있어요:

POST https://huggingface.co/api/spaces/{namespace}/{repo}/dev-mode
Content-Type: application/json
Authorization: Bearer ***

{
  "enabled": true
}

웹 인터페이스로

Dev Mode가 켜진 상태로 Space를 만들 수도 있어요.

제한 사항

Dev Mode는 현재 정적 Spaces에서는 사용할 수 없어요. Docker Spaces에도 몇 가지 추가 요구사항이 있어요.

Docker Spaces

Dev Mode는 Docker Spaces를 지원해요. 다만 Dev Mode가 제대로 작동하려면 Space가 다음 규칙을 준수해야 해요.

  1. 다음 패키지가 설치되어 있어야 해요:
  • bash (SSH 연결에 필요)
  • curl, wget, procps (VS Code 서버 프로세스에 필요)
  • git과 git-lfs (Dev Mode 환경에서 변경사항 커밋·푸시에 필요)

  1. Dev Mode 데몬이 변경을 감지할 수 있도록 애플리케이션 코드가 /app 폴더에 있어야 해요.

  2. 코드를 변경할 수 있도록 /app 폴더가 uid 1000의 사용자가 소유해야 해요.

  3. Dockerfile에 시작용 CMD 명령이 있어야 해요. CMD 명령에 대한 자세한 내용은 Docker 문서를 확인하세요.

Dev Mode는 기본 이미지가 debian 기반(예: ubuntu)일 때 잘 작동해요.

더 이국적인 Linux 배포판(예: alpine)은 테스트되지 않았고 Dev Mode가 작동한다는 보장이 없어요.

호환 가능한 Dockerfile 예시

Spaces Dev Mode와 호환되는 Dockerfile 예시예요.

apt-get으로 필요한 패키지를 설치하고, 개발자 편의를 위해 몇 가지 더(top, vim, nano)도 설치해요. 그다음 /app에서 NodeJS 애플리케이션을 시작해요.

FROM node:19-slim

RUN apt-get update && \
    apt-get install -y \
      bash \
      git git-lfs \
      wget curl procps \
      htop vim nano && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /app
COPY --link ./ /app
RUN  npm i 

RUN chown 1000 /app
USER 1000
CMD ["node", "index.js"]

이 조직에 Dev Mode 호환 Docker Spaces의 여러 예시가 있어요. 네임스페이스에 자유롭게 복제하세요!

예제 Python 앱 (FastAPI HTTP server): https://huggingface.co/spaces/dev-mode-explorers/dev-mode-python

예제 Javascript 앱 (Express.js HTTP server): https://huggingface.co/spaces/dev-mode-explorers/dev-mode-javascript

피드백

Spaces Dev Mode에 대한 피드백은 HF Hub에서 바로 공유할 수 있어요: https://huggingface.co/spaces/dev-mode-explorers/README/discussions

더 알아보기 (Learn more)