Webhook 가이드: Jobs를 사용하여 버킷의 새 파일 처리

Storage Buckets는 시간이 지남에 따라 도착하는 파일에 적합한 저장소입니다. 다른 도구에서 내보낸 파일, 로그, 녹음, 스캔 등이 해당됩니다. 이러한 파일이 유용하게 사용되기 전에 변환, 정제, 전사 등 처리 워크플로가 필요한 경우가 많습니다.

버킷에 대한 웹훅과 Job을 사용하면 서버 없이 이 작업을 자동으로 수행할 수 있습니다. 파일이 변경되면 웹훅이 Job을 시작합니다. Job은 변경된 파일 목록을 받아 처리한 후 종료됩니다. 실행되는 동안에만 비용이 청구됩니다.

이 가이드는 해당 패턴을 설명한 후, 업로드된 CSV 및 JSON 파일을 최적화된 Parquet로 변환하는 한 가지 예시를 통해 설정 방법을 보여줍니다.

작동 방식

file uploaded ──▶ webhook ──▶ Job runs with the event ──▶ result written to a second bucket

Webhook은 URL을 호출하는 대신 Job을 트리거할 수 있습니다. Job을 한 번만 생성하면, 각 webhook 이벤트가 해당 이벤트를 환경에 포함시켜 Job을 다시 실행합니다. 버킷의 경우, WEBHOOK_PAYLOAD에는 변경된 파일 목록이 나열됩니다:

{
  "event": { "action": "update", "scope": "repo.content" },
  "repo": { "type": "bucket", "name": "your-username/my-raw-files", ... },
  "updatedFiles": [
    { "path": "data.csv", "action": "add", "xetHash": "433b53b8...", "size": 10983 }
  ]
}

따라서 Job은 새 파일만 처리하며, 다운로드를 시작하기 전에 각 파일을 어떻게 처리할지 결정할 수 있습니다.

각 실행은 Job의 이미지, 명령, 환경 변수, 하드웨어 flavor 및 timeout을 재사용합니다. Job의 볼륨이나 시크릿은 상속되지 않습니다. 따라서 아래 단계에서는 URL에서 스크립트를 실행하고 토큰을 웹훅에 전달합니다.

Job은 결과를 두 번째 버킷에 기록합니다. 감시하는 버킷에 기록하면 자신의 출력이 웹훅을 다시 트리거하게 됩니다.

예: 업로드를 최적화된 Parquet로 변환

CSV 및 JSON 내보내기는 쿼리가 느리고 공유하기가 불편합니다. 최적화된 Parquet는 필터링 및 스트리밍이 빠르고, Xet 중복 제거 덕분에 업로드 및 다운로드 속도도 빠릅니다. 이 예시에서는 한 버킷에 업로드된 모든 CSV, JSON 또는 Parquet 파일이 다른 버킷에 최적화된 Parquet로 표시됩니다. Job은 uv-scripts의 준비된 스크립트인 optimize-parquet.py를 실행합니다.

선불 크레딧이 있는 Hugging Face 계정과 hf CLI가 필요합니다.

두 개의 버킷을 생성합니다

버킷 하나에는 업로드된 파일이, 다른 버킷에는 Parquet 파일이 저장됩니다:

hf buckets create my-raw-files --private
hf buckets create my-parquet --private

Job 생성

webhook이 실행할 Job을 생성합니다:

hf jobs run --flavor cpu-upgrade --timeout 2h \
    -e OUTPUT_BUCKET=your-username/my-parquet \
    ghcr.io/astral-sh/uv:python3.12-bookworm \
    uv run https://huggingface.co/datasets/uv-scripts/data-processing/raw/main/optimize-parquet.py

hf jobs run를 사용하여 스크립트가 URL에서 실행됩니다. hf jobs uv run은 UV 스크립트를 실행하는 일반적인 방법이지만, 스크립트를 볼륨에 업로드해야 하며 웹훅 실행에서는 이를 사용할 수 없습니다. 이 작업에는 cpu-upgrade가 충분하며, 2시간 타임아웃은 대용량 파일 처리에 여유를 제공합니다.

스크립트는 비공개 버킷 또는 리포지토리에 있을 수도 있습니다. 감시 대상 버킷은 사용하지 마세요. 스크립트를 업로드하면 Job이 시작됩니다. 스크립트를 읽을 수 있는 토큰을 사용하여 --secrets HF_TOKEN을 명령에 추가하세요. 실행이 SyntaxError로 실패하면 토큰이 스크립트를 읽을 수 없다는 뜻입니다. Webhook 실행에는 이 시크릿이 제공되지 않으므로, Webhook의 토큰도 동일한 접근 권한이 필요합니다.

hf jobs run은 Job을 즉시 시작합니다. 이 첫 실행에는 webhook 이벤트가 없으며, optimize-parquet.py는 이벤트가 없으면 아무 동작도 하지 않으므로 Job은 바로 중단됩니다. 출력되는 Job ID를 복사하세요.

Webhook 생성

첫 번째 버킷을 관찰하고 변경 사항이 발생하면 Job을 실행합니다:

hf webhooks create --job-id <job ID> --watch bucket:your-username/my-raw-files \
    --domain repo --secrets HF_TOKEN

--domain repo는 웹훅을 파일 및 설정 변경 사항으로 제한합니다. Buckets는 해당 변경 사항만 전송하므로 이 옵션은 필수적이지는 않지만, 나중에 모델이나 데이터셋을 모니터링할 때 명령이 올바르게 유지되도록 합니다.

--secrets HF_TOKEN은 토큰을 웹훅에 암호화하여 저장합니다. 웹훅이 시작하는 모든 Job은 해당 토큰을 secret으로 수신하여 버킷의 읽기 및 쓰기에 사용합니다. 값은 환경의 HF_TOKEN에서 가져오거나, 로그인에 사용한 토큰에서 가져옵니다. Job에 필요한 권한만 가진 fine-grained token을 사용하는 것이 가장 안전한 선택입니다.

이 파이프라인 전용으로 생성된 토큰을 사용하려면 --secrets HF_TOKEN=hf_…을 통해 값을 명시적으로 전달하거나, 셸 히스토리에 남기지 않도록 파이프를 통해 전달하세요: printf 'HF_TOKEN=hf_…\n' | hf webhooks create … --secrets-file -.

명령은 webhook ID를 출력합니다. 나중에 파이프라인을 중지하려면 hf webhooks delete <webhook ID>를 사용하여 webhook을 삭제하세요.

파일 업로드

hf buckets cp data.csv hf://buckets/your-username/my-raw-files/data.csv

약 1분 후, Jobs 페이지에 Job이 나타납니다. 나타나지 않으면 webhook 설정의 Activity 탭을 열어 전달 내역을 확인하고, hf jobs logs <job ID>를 사용하여 Job의 출력을 읽어 보세요. Job이 완료되면 Parquet 파일은 두 번째 버킷에 있습니다:

hf buckets ls your-username/my-parquet -R

data.csv/README.md
data.csv/data/train-00000-of-00001.parquet

여러 파일을 변환하려면 hf buckets sync로 한 번에 업로드하세요. 함께 업로드된 파일은 보통 하나의 이벤트로 도착하므로, 하나의 Job이 이벤트당 최대 10,000개까지 모든 파일을 변환합니다. 전체 bucket payload와 해당 한도를 초과했을 때의 동작은 Webhooks를 참고하세요.

스크립트가 수행하는 작업

webhook에 특정한 부분은 이벤트를 읽는 것입니다:

event = json.loads(os.environ.get("WEBHOOK_PAYLOAD", "{}"))  # empty when you run the Job yourself
input_bucket = os.environ.get("WEBHOOK_REPO_ID")

for changed_file in event.get("updatedFiles", []):
    if changed_file["action"] != "add":
        continue  # skip deleted files
    path, size = changed_file["path"], changed_file["size"]
    ...  # convert the file (see the full script)

각 새 파일에 대해 스크립트는 datasets를 사용하여 버킷(hf://buckets/...)에서 바로 파일을 로드합니다. 파일 크기가 Job의 사용 가능 디스크의 3분의 1보다 크면 다운로드 대신 스트리밍됩니다. 이후 push_to_hub는 콘텐츠 기반 청킹, 페이지 인덱스, 최대 100 MB의 행 그룹을 사용하여 Parquet 형식으로 출력 버킷에 파일을 작성합니다.

패턴을 자체 작업에 사용하세요

설정은 유지하고 스크립트만 변경하세요. 예를 들어:

• 학습 전에 개인 데이터를 제거하세요. 원시 텍스트를 개인 버킷에 수집하고, GLiNER2 PII filter와 같은 모델로 개인 정보를 마스킹한 뒤, 마스킹된 텍스트만 학습 데이터셋에 푸시하세요.
• 새로운 체크포인트를 평가합니다. 학습 Job은 버킷에 체크포인트를 저장하며, 각 새로운 체크포인트는 평가 Job을 시작합니다. 체크포인트가 여러 부분으로 업로드되는 경우, 이벤트가 순서대로 도착하지 않을 수 있으므로, 마지막에 작성하는 마커 파일이 updatedFiles에 나타날 때만 반응하도록 하세요.
• 새 파일을 전사하거나 임베딩합니다. 새로운 녹음 파일을 전사 텍스트로 변환하거나, 새로운 문서를 검색용 임베딩으로 변환합니다.

WEBHOOK_PAYLOAD가 설정되지 않은 첫 번째 실행에서 스크립트가 수행할 작업을 결정해야 합니다. optimize-parquet.py처럼 종료될 수도 있고, 버킷에 이미 존재하는 파일을 처리하는 것과 같은 실제 작업을 수행할 수도 있습니다. 첫 번째 실행에 토큰이 필요한 경우(예: 버킷 또는 비공개 스크립트 읽기)에는 hf jobs run에 --secrets HF_TOKEN를 추가하세요. Webhook 실행에는 이 시크릿이 제공되지 않습니다. Webhook 실행은 토큰을 Webhook에서 가져옵니다.

Webhook인지 스케줄인지?

Webhook은 각 이벤트마다 Job을 시작하므로, 새 파일은 도착한 지 약 1분 후에 처리됩니다. 그렇게 빠르게 처리할 필요가 없다면 예약된 Job이 대안이 됩니다. 이는 매시간 또는 매일 실행되며, 마지막 실행 이후에 도착한 모든 것을 처리합니다. 이렇게 하면 작업을 더 적은 수의 Job으로 묶을 수 있어 시작에 시간이 오래 걸리는 GPU 작업에 도움이 되며, 24시간당 1,000회라는 Webhook 트리거 한도를 피할 수 있습니다. 이 경우 스크립트가 새 파일을 스스로 찾아야 하며, 예를 들어 입력 및 출력 버킷을 비교하는 방식으로 수행할 수 있습니다.