# 🟧 Spaces의 Label Studio

[Label Studio](https://labelstud.io)는 다양한 데이터 유형을 라벨링, 주석 및 탐색할 수 있는 [오픈소스 데이터 라벨링 플랫폼](https://github.com/heartexlabs/label-studio)입니다. 또한 Label Studio에는 새로운 모델 학습, 능동 학습, 지도 학습 및 기타 다양한 학습 기법을 위해 사용할 수 있는 강력한 [머신러닝 인터페이스](https://labelstud.io/guide/ml.html)가 포함되어 있습니다.

이 가이드에서는 Hugging Face Hub 내에서 데이터 라벨링 및 주석을 위해 Label Studio를 배포하는 방법을 안내합니다. 데모 및 평가 목적으로 Docker를 사용하여 Hub에 완전히 호스팅되는 자체 완결형 애플리케이션으로 Label Studio의 기본 구성을 사용할 수 있으며, 자체 데이터베이스와 클라우드 스토리지를 연결하여 Spaces에 호스팅되는 완전한 기능을 갖춘 프로덕션급 애플리케이션을 구축할 수도 있습니다.

## ⚡️ Spaces에 Label Studio 배포

Label Studio를 Spaces에 몇 번의 클릭만으로 배포할 수 있습니다:

  

Spaces는 다음을 정의하도록 요구합니다:

* **Owner**: 개인 계정 또는 소속된 조직

* **Space 이름**: Space를 생성하려는 계정 내에서 해당 Space에 부여할 이름입니다.

* Space를 본인 또는 조직에서만 볼 수 있도록 하려면 **Visibility**: _private_, Label Studio API를 사용하는 다른 사용자나 애플리케이션에서도 볼 수 있도록 하려면 _public_을 선택합니다(권장).

## 🚀 기본 구성 사용

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

> [!WARNING]
> Hugging Face Spaces의 스토리지는 기본적으로 일시적입니다. 재시작 후에도 데이터를 유지하려면 [Storage Bucket](./storage-buckets)을 연결하세요. 자세한 내용은 아래 [지속성 섹션](#enable-persistence-with-hf-storage-buckets)을 참고하세요.

Label Studio를 실행하면 표준 로그인 화면이 표시됩니다. 이메일 주소를 사용하여 새 계정을 만들고 새 자격 증명으로 로그인하여 시작할 수 있습니다. 로그인 후 주기적으로 Label Studio가 스토리지가 일시적(ephemeral)이며 Space가 재시작되면 데이터가 손실될 수 있다고 경고합니다. 또한, 데이터 라벨링을 시작하기 위해 새 프로젝트를 만들라는 Label Studio의 친절한 마스코트인 Heidi의 프롬프트가 미리 설정되어 있습니다. 시작하려면, 감정 분석을 위한 어노테이션 인터페이스를 구축하는 방법을 안내하는 Label Studio ["Zero to One" 튜토리얼](https://labelstud.io/blog/introduction-to-label-studio-in-hugging-face-spaces/)을 확인해 보세요.

## 🛠️ 프로덕션 환경에 적합한 Label Studio 인스턴스 구성

Space를 프로덕션 환경에 맞게 준비하려면 세 가지 구성 변경이 필요합니다:

* 새 계정 생성을 제한 없이 허용하지 않도록 설정합니다.

* [Storage Bucket](./storage-buckets) 또는 외부 데이터베이스를 연결하여 지속성을 활성화합니다.

* 선택적으로 라벨링 작업에 클라우드 스토리지를 연결합니다.

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

Label Studio의 기본 구성은 애플리케이션 URL을 가진 누구나 새 계정을 자유롭게 만들 수 있도록 허용합니다. Space의 **Settings**에 다음 구성 시크릿을 추가하여 [회원가입을 제한](https://labelstud.io/guide/signup.html#Restrict-signup-for-local-deployments)할 수 있습니다.

* `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](./storage-buckets)을 연결하는 것입니다. 이를 통해 영구 객체 스토리지가 Space에 직접 마운트됩니다. Label Studio는 마운트된 버킷에 SQLite 데이터베이스와 미디어 업로드를 기록하므로, 재시작 후에도 프로젝트와 주석이 유지됩니다.

1. **버킷 생성:**

   ```bash
   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와 버킷 이름을 알려주면, 에이전트가 다음과 동등한 작업을 실행할 수 있습니다:

```python
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`를 통해 스페이스 및 볼륨 마운트를 관리하는 방법에 대한 자세한 내용은 [`manage-spaces` 가이드](/docs/huggingface_hub/guides/manage-spaces)를 참고하세요.

### Postgres를 사용하여 영속성 활성화

더 무거운 다중 사용자 배포 환경에서는 [외부 Postgres 데이터베이스를 스페이스에 연결](https://labelstud.io/guide/storedata.html#PostgreSQL-database)하여 지속성을 활성화할 수 있으며, 이를 통해 모든 프로젝트 및 주석 설정이 보존됨을 보장합니다.

다음 시크릿 변수를 설정하여 자체 호스팅된 Postgres 인스턴스와 일치하도록 하세요. Spaces 정의에서 데이터베이스 서비스에 대한 정보가 공개로 누출되는 것을 방지하기 위해, 이러한 값을 시크릿으로 설정하는 것을 강력히 권장합니다.

* `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가 리셋되면 모든 데이터가 손실됩니다. 영구 저장을 활성화하려면 [클라우드 저장소 커넥터](https://labelstud.io/guide/storage.html)를 활성화해야 합니다. 적절한 클라우드 커넥터를 선택하고 해당 시크릿을 구성하세요.

#### 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를 시작하려면, 감성 분석 어노테이션 프로젝트 예시를 단계별로 안내하는 Label Studio ["Zero to One" 튜토리얼](https://labelstud.io/blog/introduction-to-label-studio-in-hugging-face-spaces/)을 확인해 보세요. Label Studio 및 Label Studio 커뮤니티에 대한 전체 리소스는 [Label Studio 홈 페이지](https://labelstud.io)에서 찾을 수 있습니다. 여기에는 [전체 문서](https://labelstud.io/guide/), 다양한 어노테이션 인터페이스를 테스트할 수 있는 [인터랙티브 플레이그라운드](https://labelstud.io/playground/), 그리고 [Label Studio Slack 커뮤니티](https://slack.labelstudio.heartex.com/?source=spaces)에 가입할 수 있는 링크가 포함되어 있습니다.