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 é um framework de DataFrame inspirado no PySpark, projetado para o desenvolvimento de aplicações de IA e agênticas em produção. O fenic oferece suporte para a leitura de conjuntos de dados diretamente do Hugging Face Hub.

Começando

Para começar, instale o fenic com pip:

pip install fenic

Criar uma Sessão

Instancie uma sessão fenic com a configuração padrão (suficiente para ler conjuntos de dados e outras operações não semânticas):

import fenic as fc

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

Visão geral

fenic é um framework de processamento de dados com uma abordagem definida que combina:

API de DataFrame: operações inspiradas no PySpark para manipulação de dados familiar
Operações semânticas: Operações de IA/LLM integradas, incluindo funções semânticas, embeddings e clustering
Integração de modelos: Suporte nativo para provedores de IA (Anthropic, OpenAI, Cohere, Google)
Otimização de consultas: Otimização automática por meio de transformações de plano lógico

Ler do Hugging Face Hub

fenic pode ler conjuntos de dados diretamente do Hugging Face Hub usando o protocolo hf://. Essa funcionalidade está integrada à interface DataFrameReader do fenic.

Formatos Suportados

fenic suporta a leitura dos seguintes formatos do Hugging Face:

Arquivos Parquet (.parquet)
Arquivos CSV (.csv)

Lendo Conjuntos de Dados

Para ler um conjunto de dados do 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")

Lendo com Gerenciamento de Esquema

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

Observação: No fenic, um schema é o conjunto de nomes de colunas e seus tipos de dados. Quando você habilita merge_schemas, o fenic tenta reconciliar diferenças entre arquivos preenchendo colunas ausentes com nulos e alargando tipos quando possível. Alguns layouts ainda não podem ser mesclados — consulte a documentação do fenic sobre limitações de mesclagem de schema CSV e limitações de mesclagem de schema Parquet.

Autenticação

Para ler conjuntos de dados privados, você precisa definir seu token do Hugging Face como uma variável de ambiente:

export HF_TOKEN="your_hugging_face_token_here"

Formato do caminho

O formato de caminho do Hugging Face no fenic segue esta estrutura:

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

Você também pode especificar revisões ou versões do conjunto de dados:

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

Recursos:

Suporta padrões glob (*, **)
Revisões/versões de datasets usando @ notação:
- Commit específico: @d50d8923b5934dc8e74b66e6e4b0e2cd85e9142e
- Branch: @refs/convert/parquet
- Alias de branch: @~parquet
Exige a variável de ambiente HF_TOKEN para conjuntos de dados privados

Misturando Fontes de Dados

fenic permite combinar várias fontes de dados em uma única operação de leitura, incluindo a mistura de diferentes protocolos:

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

Essa flexibilidade permite combinar dados do Hugging Face Hub e arquivos locais de forma transparente em seu pipeline de processamento de dados.

Processando dados do Hugging Face

Uma vez carregado do Hugging Face, você pode usar a API completa de DataFrame do fenic:

Operações básicas de 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")
)

Operações com IA

Para usar operações semânticas e de incorporação, configure os modelos de linguagem e de incorporação em seu SessionConfig. Uma vez configurado:

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

Exemplo: Analisando o Conjunto de Dados 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()

Recursos

Update on GitHub

←Atlas de Embeddings FiftyOne→