fenic: Hugging Face Hub에서 데이터 읽기

fenic: Hugging Face Hub에서 데이터 읽기

fenic은 프로덕션 AI 및 에이전틱(agentic) 애플리케이션 구축을 위해 설계된 PySpark 영감의 DataFrame 프레임워크예요. Hugging Face Hub에서 데이터셋을 직접 읽는 것을 지원합니다.

출처: 문서

본문

fenic은 프로덕션 AI 및 에이전틱 애플리케이션 구축을 위해 설계된 PySpark 영감의 DataFrame 프레임워크입니다. fenic은 Hugging Face Hub에서 데이터셋을 직접 읽는 기능을 제공해요.

시작하기 (Getting Started)

시작하려면 fenic을 pip 설치하세요:

pip install fenic

세션 만들기 (Create a Session)

기본 구성으로 fenic 세션을 인스턴스화하세요(데이터셋 읽기와 기타 비-시맨틱 연산에 충분합니다):

import fenic as fc

session = fc.Session.get_or_create(fc.SessionConfig())

개요 (Overview)

fenic은 의견이 반영된(opiniated) 데이터 처리 프레임워크로 다음을 결합합니다:

  • DataFrame API: 익숙한 데이터 조작을 위한 PySpark 영감의 연산
  • Semantic Operations: 시맨틱 함수, 임베딩, 클러스터링을 포함한 내장 AI/LLM 연산
  • Model Integration: AI 제공자(Anthropic, OpenAI, Cohere, Google)의 네이티브 지원
  • Query Optimization: 논리적 플랜 변환을 통한 자동 최적화

Hugging Face Hub에서 읽기 (Read from Hugging Face Hub)

fenic은 hf:// 프로토콜을 사용해 Hugging Face Hub에서 데이터셋을 직접 읽을 수 있어요. 이 기능은 fenic의 DataFrameReader 인터페이스에 내장되어 있습니다.

지원 포맷 (Supported Formats)

fenic은 Hugging Face에서 다음 포맷을 읽는 것을 지원합니다:

  • Parquet 파일 (.parquet)
  • CSV 파일 (.csv)

데이터셋 읽기 (Reading Datasets)

Hugging Face Hub에서 데이터셋을 읽으려면:

import fenic as fc

session = fc.Session.get_or_create(fc.SessionConfig())

# Read a CSV file from a public dataset
df = session.read.csv("hf://datasets/datasets-examples/doc-formats-csv-1/data.csv")

# Read Parquet files using glob patterns
df = session.read.parquet("hf://datasets/cais/mmlu/astronomy/*.parquet")

# Read from a specific dataset revision
df = session.read.parquet("hf://datasets/datasets-examples/doc-formats-csv-1@~parquet/**/*.parquet")

스키마 관리로 읽기 (Reading with Schema Management)

# Read multiple CSV files with schema merging
df = session.read.csv("hf://datasets/username/dataset_name/*.csv", merge_schemas=True)

# Read multiple Parquet files with schema merging
df = session.read.parquet("hf://datasets/username/dataset_name/*.parquet", merge_schemas=True)

Note: fenic에서 스키마는 컬럼 이름과 데이터 타입의 집합을 뜻해요. merge_schemas를 켜면 fenic은 누락된 컬럼을 null로 채우고 가능한 곳에서 타입을 넓히는 방식으로 파일 간 차이를 조정하려고 합니다. 일부 레이아웃은 여전히 병합할 수 없어요—CSV 스키마 병합 한계와 Parquet 스키마 병합 한계에 대한 fenic 문서를 확인하세요.

인증 (Authentication)

비공개 데이터셋을 읽으려면 Hugging Face 토큰을 환경 변수로 설정해야 합니다:

export HF_TOKEN="your_hugging_face_token_here"

경로 포맷 (Path Format)

fenic의 Hugging Face 경로 포맷은 다음 구조를 따릅니다:

hf://{repo_type}/{repo_id}/{path_to_file}

데이터셋 리비전이나 버전도 지정할 수 있어요:

hf://{repo_type}/{repo_id}@{revision}/{path_to_file}

기능:

  • glob 패턴(*, **) 지원
  • @ 표기법을 사용한 데이터셋 리비전/버전:
    • 특정 커밋: @d50d8923b5934dc8e74b66e6e4b0e2cd85e9142e
    • 브랜치: @refs/convert/parquet
    • 브랜치 별칭: @~parquet
  • 비공개 데이터셋에는 HF_TOKEN 환경 변수 필요

데이터 소스 혼합 (Mixing Data Sources)

fenic은 단일 읽기 연산에서 여러 데이터 소스를 결합할 수 있어요. 서로 다른 프로토콜을 혼합하는 것도 포함합니다:

# Mix HF and local files in one read call
df = session.read.parquet([
    "hf://datasets/cais/mmlu/astronomy/*.parquet",
    "file:///local/data/*.parquet",
    "./relative/path/data.parquet"
])

이 유연성 덕분에 데이터 처리 파이프라인에서 Hugging Face Hub와 로컬 파일을 매끄럽게 결합할 수 있어요.

Hugging Face 데이터 처리 (Processing Data from Hugging Face)

Hugging Face에서 불러온 뒤에는 fenic의 전체 DataFrame API를 사용할 수 있습니다:

기본 DataFrame 연산 (Basic DataFrame Operations)

import fenic as fc

session = fc.Session.get_or_create(fc.SessionConfig())

# Load IMDB dataset from Hugging Face
df = session.read.parquet("hf://datasets/imdb/plain_text/train-*.parquet")

# Filter and select
positive_reviews = df.filter(fc.col("label") == 1).select("text", "label")

# Group by and aggregate
label_counts = df.group_by("label").agg(
    fc.count("*").alias("count")
)

AI 기반 연산 (AI-Powered Operations)

시맨틱 및 임베딩 연산을 사용하려면 SessionConfig에서 언어 모델과 임베딩 모델을 구성하세요. 구성하고 나면:

import fenic as fc

# Requires OPENAI_API_KEY to be set for language and embedding calls
session = fc.Session.get_or_create(
    fc.SessionConfig(
        semantic=fc.SemanticConfig(
            language_models={
                "gpt-4o-mini": fc.OpenAILanguageModel(
                    model_name="gpt-4o-mini",
                    rpm=60,
                    tpm=60000,
                )
            },
            embedding_models={
                "text-embedding-3-small": fc.OpenAIEmbeddingModel(
                    model_name="text-embedding-3-small",
                    rpm=60,
                    tpm=60000,
                )
            },
        )
    )
)

# Load a text dataset from Hugging Face
df = session.read.parquet("hf://datasets/imdb/plain_text/train-00000-of-00001.parquet")

# Add embeddings to text columns
df_with_embeddings = df.select(
    "*",
    fc.semantic.embed(fc.col("text")).alias("embedding")
)

# Apply semantic functions for sentiment analysis
df_analyzed = df_with_embeddings.select(
    "*",
    fc.semantic.analyze_sentiment(
        fc.col("text"),
        model_alias="gpt-4o-mini",  # Optional: specify model
    ).alias("sentiment")
)

예시: MMLU 데이터셋 분석 (Example: Analyzing MMLU Dataset)

import fenic as fc

# Requires OPENAI_API_KEY to be set for semantic calls
session = fc.Session.get_or_create(
    fc.SessionConfig(
        semantic=fc.SemanticConfig(
            language_models={
                "gpt-4o-mini": fc.OpenAILanguageModel(
                    model_name="gpt-4o-mini",
                    rpm=60,
                    tpm=60000,
                )
            },
        )
    )
)

# Load MMLU astronomy subset from Hugging Face
df = session.read.parquet("hf://datasets/cais/mmlu/astronomy/*.parquet")

# Process the data
processed_df = (df
    # Filter for specific criteria
    .filter(fc.col("subject") == "astronomy")
    # Select relevant columns
    .select("question", "choices", "answer")
    # Add difficulty analysis using semantic.map
    .select(
        "*",
        fc.semantic.map(
            "Rate the difficulty of this question from 1-5: {{question}}",
            question=fc.col("question"),
            model_alias="gpt-4o-mini"  # Optional: specify model
        ).alias("difficulty")
    )
)

# Show results
processed_df.show()

리소스 (Resources)

더 알아보기 (Learn more)

hf:// 프로토콜을 쓰면 fenic 하나로 Hub 데이터셋 읽기부터 시맨틱 분석까지 이어지는 파이프라인을 만들 수 있어요. 비공개 데이터셋을 다룰 때는 HF_TOKEN 설정을 잊지 말고, MMLU 예시처럼 fc.semantic.embed와 fc.semantic.map을 조합해 품질 분석 워크플로를 바로 구성해 보세요.