🟧 Spaces에서 Label Studio 사용하기

🟧 Spaces에서 Label Studio 사용하기

Label Studio는 여러 데이터 유형을 라벨링·어노테이션·탐색하는 오픈소스 데이터 라벨링 플랫폼이에요. 또한 Label Studio는 새 모델 학습, 액티브 러닝, 지도 학습 등 여러 학습 기법에 쓸 수 있는 강력한 머신러닝 인터페이스를 포함해요.

출처: 문서

본문

이 가이드는 Hugging Face Hub 안에서 데이터 라벨링·어노테이션용 Label Studio를 배포하는 법을 가르쳐줘요. 데모·평가 목적으로 Docker로 Hub에 완전히 호스팅된 독립 애플리케이션인 Label Studio의 기본 구성을 쓸 수도 있고, 자신의 데이터베이스와 클라우드 스토리지를 연결해 Spaces에 호스팅된 풀 프로덕션 애플리케이션을 구축할 수도 있어요.

⚡️ Spaces에 Label Studio 배포하기

몇 번의 클릭만으로 Spaces에 Label Studio를 배포할 수 있어요.

Spaces에서 정의해야 할 것들:

• Owner(소유자): 개인 계정 또는 소속된 조직.
• Space name(이름): 계정 안의 Space 이름.
• Visibility(공개 여부): 나나 조직만 보이게 하려면 private, 다른 사용자나 Label Studio API를 쓰는 애플리케이션에 보이게 하려면 public(권장).

🚀 기본 구성 사용하기

기본적으로 Label Studio는 애플리케이션 데이터베이스에 로컬 스토리지를 사용해 구성, 계정 자격 증명, 프로젝트 정보를 저장하는 구성으로 Spaces에 설치돼요. 라벨링 작업과 데이터 항목도 로컬 스토리지에 보관돼요.

[!WARNING] Hugging Face Spaces의 스토리지는 기본적으로 임시예요. 재시작 후에도 데이터를 유지하려면 Storage Bucket을 연결하세요 — 아래 persistence 섹션을 참고하세요.

Label Studio를 실행하면 표준 로그인 화면이 나타나요. 이메일 주소로 새 계정을 만들고 새 자격 증명으로 로그인하면 됩니다. 로그인 후 주기적으로 Label Studio가 스토리지가 임시이고 Space가 재시작되면 데이터가 유실될 수 있다고 경고해요. 도움이 되는 Label Studio 마스코트 Heidi가 데이터 라벨링을 시작할 새 프로젝트를 만들라고 프롬프트도 보여줘요. 시작하려면 감성 분석 어노테이션 인터페이스 구축 가이드가 있는 "Zero to One" 튜토리얼을 확인하세요.

🛠️ 프로덕션 준비 Label Studio 인스턴스 구성하기

Space를 프로덕션 준비 상태로 만들려면 세 가지 구성 변경이 필요해요:

• 새 계정의 무제한 생성을 비활성화한다.
• Storage Bucket 또는 외부 데이터베이스를 연결해 영속성을 켠다.
• 선택적으로, 라벨링 작업용 클라우드 스토리지를 연결한다.

새 계정 무제한 생성 비활성화

Label Studio의 기본 구성은 앱 URL이 있는 모든 사람이 무제한으로 새 계정을 만들 수 있게 해요. Space Settings에 다음 구성 시크릿을 추가해 가입을 제한할 수 있어요.

• LABEL_STUDIO_DISABLE_SIGNUP_WITHOUT_LINK: true로 설정하면 무제한 계정 생성을 비활성화해요.
• LABEL_STUDIO_USERNAME: Label Studio Space에서 첫 사용자로 쓸 계정의 사용자 이름. 유효한 이메일 주소여야 해요.
• LABEL_STUDIO_PASSWORD: 첫 사용자 계정과 연결될 비밀번호.

이 설정을 적용하려면 Space를 재시작하세요. 로그인 화면에서 새 계정을 만드는 기능이 비활성화돼요. 새 계정을 만들려면 Label Studio 앱의 Organization 설정에서 새 사용자를 초대해야 해요.

HF Storage Buckets로 영속성 켜기

기본적으로 이 Space는 모든 프로젝트 구성과 데이터 어노테이션을 SQLite로 로컬 스토리지에 저장해요. Space가 리셋되면 Space의 모든 구성과 어노테이션 데이터가 유실돼요.

영속성을 켜는 가장 간단한 방법은 Storage Bucket을 연결하는 거예요. 영구 객체 스토리지를 Space에 직접 마운트해요. Label Studio가 SQLite 데이터베이스와 미디어 업로드를 마운트된 버킷에 쓰므로 프로젝트와 어노테이션이 재시작 후에도 살아남아요.

1. 버킷 만들기:

   hf buckets create <your-namespace>/label-studio-data
   

2. Space Settings → Storage Buckets에서 연결하고 마운트 경로를 /data로 설정한다.
3. 두 개의 Space 변수 설정:

   LABEL_STUDIO_BASE_DATA_DIR=/data
   STORAGE_PERSISTENCE=1
   

4. Space를 Factory rebuild한다.

[!TIP] 재시작 후에도 사용자 세션을 유지하려면 SECRET_KEY Space Secret을 설정하세요. 없으면 Label Studio가 부팅할 때마다 임의의 키를 생성해 재시작 시 모든 사용자가 로그아웃돼요.

코딩 에이전트가 대신 하게 하기

Space 설정을 직접 클릭하고 싶지 않다면 huggingface_hub에 접근할 수 있는 코딩 에이전트에게 Space를 프로비저닝하게 할 수 있어요. Space ID와 버킷 이름을 알려주면 다음에 해당하는 작업을 실행할 수 있어요:

from huggingface_hub import HfApi, Volume

api = HfApi()
space_id = "<your-namespace>/<your-space>"

# Attach the bucket at /data
api.set_space_volumes(
    space_id,
    volumes=[
        Volume(type="bucket", source="<your-namespace>/label-studio-data", mount_path="/data"),
    ],
)

# Tell Label Studio to write its SQLite DB and media into the mounted bucket
api.add_space_variable(space_id, "LABEL_STUDIO_BASE_DATA_DIR", "/data")
api.add_space_variable(space_id, "STORAGE_PERSISTENCE", "1")

# Optional: set a stable SECRET_KEY so sessions survive restarts
api.add_space_secret(space_id, "SECRET_KEY", "<random-string>")

# Factory rebuild so the new mount and variables take effect
api.restart_space(space_id, factory_reboot=True)

huggingface_hub로 Space와 볼륨 마운트를 관리하는 방법은 manage-spaces 가이드를 참고하세요.

Postgres로 영속성 켜기

더 무거운 다중 사용자 배포는 외부 Postgres 데이터베이스를 Space에 연결해 프로젝트·어노테이션 설정이 모두 보존되도록 할 수 있어요.

자신이 호스팅하는 Postgres 인스턴스에 맞게 다음 시크릿 변수를 설정하세요. 이 값들은 데이터베이스 서비스에 대한 정보가 Space 정의에서 공개로 새지 않도록 시크릿으로 설정하는 것을 강력히 권장해요.

• DJANGO_DB: default로 설정.
• POSTGRE_NAME: Postgres 데이터베이스 이름으로 설정.
• POSTGRE_USER: Postgres 사용자 이름으로 설정.
• POSTGRE_PASSWORD: Postgres 사용자 비밀번호로 설정.
• POSTGRE_HOST: Postgres 데이터베이스가 실행 중인 호스트로 설정.
• POSTGRE_PORT: Postgres 데이터베이스가 실행 중인 포트로 설정.
• STORAGE_PERSISTENCE: 임시 스토리지 경고를 없애기 위해 1로 설정.

이 설정을 적용하려면 Space를 재시작하세요. 사용자, 프로젝트, 어노테이션 정보가 데이터베이스에 저장되고, Space가 재시작·리셋되면 Label Studio가 다시 불러와요.

클라우드 스토리지 켜기

기본적으로 이 Space에서 활성화된 유일한 데이터 스토리지는 로컬이에요. Space가 리셋되면 모든 데이터가 유실돼요. 영구 저장을 켜려면 클라우드 스토리지 커넥터를 활성화해야 해요. 적절한 클라우드 커넥터를 선택하고 그 시크릿을 구성하세요.

Amazon S3

• STORAGE_TYPE: s3로 설정.
• STORAGE_AWS_ACCESS_KEY_ID: <YOUR_ACCESS_KEY_ID>
• STORAGE_AWS_SECRET_ACCESS_KEY: <YOUR_SECRET_ACCESS_KEY>
• STORAGE_AWS_BUCKET_NAME: <YOUR_BUCKET_NAME>
• STORAGE_AWS_REGION_NAME: <YOUR_BUCKET_REGION>
• STORAGE_AWS_FOLDER: 빈 문자열로 설정.

Google Cloud Storage

• STORAGE_TYPE: gcs로 설정.
• STORAGE_GCS_BUCKET_NAME: <YOUR_BUCKET_NAME>
• STORAGE_GCS_PROJECT_ID: <YOUR_PROJECT_ID>
• STORAGE_GCS_FOLDER: 빈 문자열로 설정.
• GOOGLE_APPLICATION_CREDENTIALS: /opt/heartex/secrets/key.json으로 설정.

Azure Blob Storage

• STORAGE_TYPE: azure로 설정.
• STORAGE_AZURE_ACCOUNT_NAME: <YOUR_STORAGE_ACCOUNT>
• STORAGE_AZURE_ACCOUNT_KEY: <YOUR_STORAGE_KEY>
• STORAGE_AZURE_CONTAINER_NAME: <YOUR_CONTAINER_NAME>
• STORAGE_AZURE_FOLDER: 빈 문자열로 설정.

🤗 다음 단계, 피드백, 지원

Label Studio를 시작하려면 예제 감성 분석 어노테이션 프로젝트를 안내하는 "Zero to One" 튜토리얼을 확인하세요. Label Studio 홈페이지에서 Label Studio와 커뮤니티에 대한 전체 리소스를 찾을 수 있어요. 여기에는 전체 문서, 어노테이션 인터페이스를 시험해 볼 대화형 플레이그라운드, Label Studio Slack 커뮤니티 가입 링크가 포함돼요.

더 알아보기 (Learn more)

• Storage Bucket으로 데이터 영속성을 구성해 보세요.
• Label Studio 문서에서 어노테이션 기능을 익혀 보세요.