Hub

API docs

Join the Hugging Face community

and get access to the augmented documentation experience

Collaborate on models, datasets and Spaces

Faster examples with accelerated inference

Switch between documentation themes

to get started

fenic

fenicは、PySparkに着想を得たDataFrameフレームワークで、本番環境向けのAIおよびエージェント型アプリケーションの構築を目的としています。fenicは、Hugging Face Hubからデータセットを直接読み込むことをサポートしています。

はじめる

始めるには、fenicをpipでインストールします:

pip install fenic

セッションの作成

デフォルトの構成でfenicセッションをインスタンス化します（データセットの読み取りなど、セマンティックでない操作には十分です）：

import fenic as fc

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

概要

fenicは、次の要素を組み合わせた、独自の設計思想を持つデータ処理フレームワークです：

DataFrame API: PySparkに触発された、馴染みのあるデータ操作のための演算
セマンティック操作: セマンティック関数、埋め込み、クラスタリングを含む組み込みのAI/LLM操作
モデル統合: AIプロバイダー（Anthropic、OpenAI、Cohere、Google）へのネイティブサポート
クエリ最適化: 論理プランの変換による自動最適化

Hugging Face Hubから読み取る

fenic は hf:// プロトコルを使用して、Hugging Face Hub からデータセットを直接読み込むことができます。この機能は、fenic の DataFrameReader インターフェースに組み込まれています。

サポートされている形式

fenicは、Hugging Faceから以下の形式の読み取りをサポートしています:

Parquetファイル（.parquet）
CSVファイル（.csv）

データセットの読み込み

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")

スキーマ管理による読み取り

# 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)

注: fenic において、スキーマとはカラム名とそのデータ型の集合を指します。merge_schemas を有効にすると、fenic は欠損カラムを null で埋め、可能な範囲で型を拡張することで、ファイル間の差分を調整しようとします。ただし、マージできないレイアウトも存在します。CSV スキーマのマージに関する制限およびParquet スキーマのマージに関する制限については、fenic のドキュメントを参照してください。

認証

プライベートなデータセットを読み取るには、Hugging Face トークンを環境変数として設定する必要があります:

export HF_TOKEN="your_hugging_face_token_here"

パス形式

fenicにおけるHugging Faceパス形式は、以下の構造に従います:

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

データセットのリビジョンやバージョンを指定することもできます:

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

機能:

globパターン(*、**)をサポート
Dataset のリビジョン/バージョンを指定するには、 @ 記法を使用します:
- 特定のコミット: @d50d8923b5934dc8e74b66e6e4b0e2cd85e9142e
- ブランチ: @refs/convert/parquet
- ブランチエイリアス: @~parquet
プライベートなデータセットにはHF_TOKEN環境変数が必要です

データソースの混合

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からのデータ処理

Hugging Faceから読み込んだ後、fenicの完全なDataFrame APIを使用できます:

基本的なDataFrame操作

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駆動の運用

セマンティック操作と埋め込み操作を使用するには、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 データセットの分析

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()

リソース

Update on GitHub

←Embedding Atlas FiftyOne→