Home > EulerWeave > Tutorials > 튜토리얼 09: 원격 입력 (Remote Inputs)

튜토리얼 09: 원격 입력 (Remote Inputs)

이 튜토리얼에서는 HuggingFace, HTTPS, S3 등 원격 소스에서 데이터를 가져와 파이프라인을 실행하는 방법을 배운다.

사전 요구 사항

# HuggingFace Dataset / Hub
pip install eulerweave[hf]

# S3
pip install eulerweave[s3]

# HTTPS — 기본 포함 (추가 설치 불필요)

개념: Fetcher와 Extractor의 분리

eulerweave는 Fetcher와 Extractor를 분리하여 설계한다:

이 분리 덕분에 기존의 JSONL/CSV/Parquet 등 Extractor를 그대로 재사용하면서, 데이터 소스만 HF/S3/HTTPS로 교체할 수 있다.

매니페스트 fetch 섹션

원격 입력을 사용하려면 inputs 섹션에 fetch 블록을 추가한다:

inputs:
  - type: jsonl          # Extractor 타입 (로컬 파일과 동일)
    fetch:
      type: hf_dataset   # Fetcher 타입
      dataset: "tatsu-lab/alpaca"
      split: "train"
      streaming: true
      limit: 1000

fetch가 있으면 uri는 생략할 수 있다. Fetcher가 데이터를 로컬 캐시로 다운로드한 후, 기존 Extractor가 캐시 파일을 읽는다.

예시 1: HuggingFace Dataset

version: 1
track: sft
inputs:
  - type: jsonl
    fetch:
      type: hf_dataset
      dataset: "tatsu-lab/alpaca"
      split: "train"
      streaming: true
      limit: 1000

pipeline:
  - id: norm1
    type: normalize_text
    slot: normalize
    input_type: TextDocument
    output_type: TextDocument
  - id: exp1
    type: export_jsonl
    slot: export
    input_type: TextDocument
    output_type: ExportedDataset

exports:
  - type: jsonl
    path: out/alpaca_result.jsonl

hf_dataset Fetcher 옵션

옵션 필수 기본값 설명
dataset 예 -- HuggingFace 데이터셋 ID (예: tatsu-lab/alpaca)
split 아니오 train 데이터셋 split
config 아니오 -- 데이터셋 config/subset 이름
streaming 아니오 false 스트리밍 모드 사용 여부
limit 아니오 -- 가져올 최대 레코드 수
token_env 아니오 HF_TOKEN HF 토큰이 저장된 환경 변수 이름

실행

eulerweave run hf_manifest.yaml
# 출력:
# Fetch: hf_dataset
# Running pipeline: hf_manifest.yaml
# Run ID: abc12345
# Status: completed
# Records processed: 1000
# Records output: 1000

예시 2: HuggingFace Hub (단일 파일)

HF Hub에 업로드된 특정 파일을 다운로드하려면 hf_hub Fetcher를 사용한다:

inputs:
  - type: jsonl
    fetch:
      type: hf_hub
      repo: "username/my-dataset"
      filename: "data/train.jsonl"
      revision: "main"

hf_hub Fetcher 옵션

옵션 필수 기본값 설명
repo 예 -- HuggingFace 저장소 ID
filename 예 -- 다운로드할 파일 경로
revision 아니오 -- Git 리비전 (branch, tag, commit)
repo_type 아니오 dataset 저장소 유형 (dataset, model, space)

예시 3: HTTPS

공개 URL에서 데이터 파일을 다운로드한다:

inputs:
  - type: csv
    fetch:
      type: https
      url: "https://example.com/data/train.csv"
    options:
      text_column: content
      delimiter: ","

https Fetcher 옵션

옵션 필수 기본값 설명
url 예 -- 다운로드할 파일 URL
headers 아니오 {} 요청 헤더. $VAR_NAME 형식으로 환경 변수 참조 가능

헤더에서 환경 변수를 사용하는 예시:

fetch:
  type: https
  url: "https://api.example.com/data.jsonl"
  headers:
    Authorization: "Bearer $MY_API_TOKEN"

예시 4: S3

AWS S3 버킷에서 파일을 다운로드한다:

inputs:
  - type: jsonl
    fetch:
      type: s3
      bucket: "my-data-bucket"
      key: "datasets/train.jsonl"
      region: "us-east-1"

s3 Fetcher 옵션

옵션 필수 기본값 설명
bucket 예 -- S3 버킷 이름
key 예 -- S3 오브젝트 키
region 아니오 -- AWS 리전

필수 환경 변수

export AWS_ACCESS_KEY_ID=your_key
export AWS_SECRET_ACCESS_KEY=your_secret

로컬 + 원격 혼합 입력

하나의 매니페스트에서 로컬 파일과 원격 소스를 함께 사용할 수 있다:

inputs:
  - type: jsonl
    uri: data/local_train.jsonl
  - type: jsonl
    fetch:
      type: hf_dataset
      dataset: "tatsu-lab/alpaca"
      split: "train"
      limit: 500

캐시

Fetcher가 다운로드한 파일은 ~/.cache/eulerweave/fetch/{scheme}/{hash}.jsonl 경로에 캐시된다. 동일한 fetch 설정으로 재실행하면 캐시된 파일을 재사용한다.

캐시 키는 fetch 섹션의 내용(단, streaming 키는 제외)으로부터 SHA-256 해시의 앞 16자를 사용하여 생성된다.

Credential 확인

eulerweave plugins doctor로 Fetcher의 credential 상태를 확인할 수 있다:

eulerweave plugins doctor
# Plugin diagnostics:
#   All plugins loaded successfully.
#   No name conflicts detected.
#   Fetcher 'hf_dataset': credentials ok
#   Fetcher 's3': credentials missing (AWS_ACCESS_KEY_ID)

사용 가능한 Fetcher 확인

eulerweave plugins list
# ...
# Fetchers:
#   hf_dataset  scheme: hf_dataset   credentials: ok
#   hf_hub      scheme: hf_hub       credentials: ok
#   https       scheme: https        credentials: ok
#   s3          scheme: s3           credentials: missing

자주 발생하는 에러

에러 메시지 원인 해결 방법
Compilation error: unknown fetcher type 'xxx' 등록되지 않은 fetcher pip install eulerweave[hf] 등 추가 의존성 설치
Compilation error: fetch ... missing required field 'dataset' hf_dataset에 필수 필드 누락 fetch 섹션에 dataset 필드 추가
Validation error: InputSpec must have either 'uri' or 'fetch' uri와 fetch 모두 없음 둘 중 하나 이상 추가
FetchError: AWS credentials not configured S3 환경 변수 미설정 AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY 설정

다음 단계

← Prev Back to List Next →