Hub documentation
fenic
fenic
fenic 是一个受 PySpark 启发的 DataFrame 框架，旨在构建生产级 AI 和智能体应用。fenic 支持直接从 Hugging Face Hub 读取数据集。
入门
要开始使用，请通过 pip 安装 fenic：
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 中，模式（schema）是指列名及其数据类型的集合。启用
merge_schemas后，fenic 会尝试通过为缺失的列填充 null 值并在可能的情况下扩展数据类型来协调不同文件之间的差异。某些布局仍然无法合并——请参阅 fenic 文档中关于 CSV 模式合并限制 和 Parquet 模式合并限制 的内容。
身份验证
要读取私有数据集，您需要将 Hugging Face token 设置为环境变量：
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 模式（
*、**） - 使用
@表示法来指定数据集的版本/修订：- 特定提交：
@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()