fenic

fenic 快速入门

一句话卖点：把 LLM 推理变成 DataFrame 的 extract / classify / summarize / embed / semantic join 算子——不用胶水代码，不用手搓 prompt chain，一次写成，可复现、可检查、可复用。

这是什么？适合谁？

fenic 是一个语义 DataFrame 引擎。它把 PySpark/SQL 风格的 DataFrame 操作（select、filter、join、group_by、agg）与 LLM 驱动的语义算子（extract、classify、summarize、embed、semantic join）融合在同一个查询模型中。你定义 Pydantic Schema 描述想要的输出结构，fenic 在 plan time 做类型校验，运行时自动批处理、限速、重试、缓存和成本计量。

与市面上其他”自然语言查 DataFrame”工具的本质区别：fenic 的 LLM 调用是 DataFrame 管道的一部分，不是副作用。pandas-ai 把 LLM 作为对话引擎粘在 pandas 上，Vanna.AI 专注 text-to-SQL，而 fenic 把语义推断提升为带有类型、Schema 和执行计划的一等查询算子。结果是：人类和数据 Agent 共享同一套管道——都能编写、检查、复用。

适合人群：

• 需要频繁从非结构化文本（日志、工单、用户反馈、eval traces）中提取结构化信息的数据工程师
• 希望在 Claude Code / Cursor / Codex 中让 Agent 写出正确 fenic 代码的 AI 开发者（fenic skill install 一键配置）
• 需要把一次性的 prompt 探索固化为可复现、可审计的 DataFrame 管道的团队

当前局限：仍在 v0.x 阶段，单团队维护，社区贡献者有限；语义算子依赖云端 LLM API，国内模型（DeepSeek/Qwen/豆包）未内置适配。

准备工作

1. Python 3.10+ 环境（推荐使用 venv 或 conda 创建虚拟环境）
2. LLM API Key：OpenAI / Anthropic / Google / Cohere / OpenRouter 任一即可
3. 安装 fenic：pip install fenic
4. （可选）配置 Agent 技能：fenic skill install 让 Claude Code / Cursor / Codex 写出正确的 fenic 代码
5. 设置环境变量（如 export OPENAI_API_KEY=sk-xxx）

3步快速上手

第 1 步：安装并配置 Session

pip install fenic

import fenic as fc
from pydantic import BaseModel, Field

# 定义你想要的输出 Schema
class Ticket(BaseModel):
    product: str = Field(description="用户咨询的产品")
    sentiment: str = Field(description="positive / neutral / negative")
    issue: str = Field(description="一句话总结用户问题")

# 创建 Session，绑定 LLM 模型
session = fc.Session.get_or_create(
    fc.SessionConfig(
        app_name="quickstart",
        semantic=fc.SemanticConfig(
            language_models={
                "mini": fc.OpenAILanguageModel(
                    model_name="gpt-4o-mini", rpm=500, tpm=200_000
                )
            },
        ),
    )
)

第 2 步：加载数据并构建语义管道

# 模拟一条非结构化文本
df = session.create_dataframe([
    {"id": 1, "text": "CSV导出功能在上次更新后一直超时"},
    {"id": 2, "text": "新仪表盘很棒，但移动端SSO登录坏了"},
])

# extract 算子：自由文本 → 类型化、可查询的列
tickets = (
    df.select("id", fc.semantic.extract("text", Ticket).alias("t"))
      .unnest("t")
)

第 3 步：运行并查看结果

tickets.show()
# id | product  | sentiment | issue
# 1  | Reports  | negative  | CSV导出超时
# 2  | Auth     | negative  | SSO登录损坏

验证：上述代码运行后，应看到类型化的结构化行输出，而非原始文本或 JSON blob。管道本身是惰性构建的，可以用 tickets.explain() 查看执行计划。

初级用法

1. 探索陌生数据集：拿到一个不熟悉的 CSV 或日志文件后，用 extract(Schema) 快速将自由文本转为类型化列，无需手写正则。
2. 语义分类：用 classify 算子将文本按自定义类别自动打标，比关键词匹配更准确。
3. 批量摘要：用 summarize 算子对长文本列生成一句话摘要，适合工单、用户反馈等场景。
4. 向量嵌入：用 embed 算子将文本列转为向量，直接用于相似度搜索。
5. 语义 Join：用 semantic join 将两个 DataFrame 按语义相似度合并，不依赖精确键匹配。

高级玩法

1. 链式语义管道：extract → filter → classify → agg，像写 PySpark 一样串联语义算子。
2. 提升为 MCP Tool：将 fenic 管道提升为 MCP tool，Agent（Claude Code/Cursor）可直接调用——管道变成可复用的数据服务。
3. Row-Level Lineage：用 lineage() 追踪每行结果来源于哪条原始数据、哪个算子和哪个 LLM 调用。
4. Per-Query Metrics：每次查询自动输出 token 消耗和成本，配合 explain() 做性能优化。
5. Response Caching：相同输入自动缓存 LLM 响应，重复查询零额外 token 消耗。
6. 多模型编排：在一个 Session 中配置多个 LLM 模型（如 GPT-4o-mini 做分类、Claude Sonnet 做摘要），按算子粒度指定模型。

小技巧

1. 先用 df.show() 和 df.schema() 了解数据结构，再构建语义管道——Schema 定义越精确，extract 输出越可靠。
2. 对关键数值字段进行二次验证——LLM 输出存在概率性误差，lineage() 可帮助定位问题来源。
3. 使用 tickets.explain() 在运行前预览执行计划，避免不必要的 LLM 调用。
4. 复杂分析拆分成多个小管道，每个管道只做一件事——比一个大管道更容易调试和复用。
5. fenic check 命令可对管道代码做静态检查，CI 中集成可防止引入错误的算子用法。

常见踩坑

1. API Key 未设置：如果未在环境变量中配置对应 Provider 的 API Key，Session 初始化不会报错但首次调用算子时抛出 AuthenticationError。
2. 大 DataFrame 全量处理：语义算子对每一行都会调用 LLM，10 万行数据会产生 10 万次 API 调用。建议先 filter 缩小范围，或先 group_by 聚合后再处理。
3. Pydantic Schema 设计不当：Field description 写得太模糊会导致 extract 输出不稳定。description 应具体描述期望的内容格式和边界。
4. 多模型 Session 的 Cost 管理：不同模型价格差异大（GPT-4o vs GPT-4o-mini），用 per-query metrics 监控每个算子的实际消耗。
5. 版本兼容：fenic 依赖 pandas 和 pydantic，确保 pip install fenic 时检查依赖版本冲突。推荐在虚拟环境中安装。

常见问题 FAQ

Q1: fenic 和 pandas-ai 有什么区别？

pandas-ai 把 LLM 作为”对话层”粘在 pandas 上——你用自然语言问问题，它翻译成 pandas 代码执行。fenic 的 LLM 推理是 DataFrame 管道的一部分——extract(Schema) 是类型化算子，有 Schema、有执行计划、有 lineage。两者定位不同：pandas-ai 侧重交互式问答，fenic 侧重可复现的语义管道。来源：fenic README

Q2: fenic 支持哪些 LLM？

5 大海外 Provider 开箱即用：OpenAI（GPT-4o / GPT-4o-mini）、Anthropic（Claude Sonnet / Opus）、Google（Gemini）、Cohere（Command R）、OpenRouter（聚合多模型）。国内模型（DeepSeek、Qwen、豆包）需通过 OpenRouter 或自定义 endpoint 接入，暂无内置适配。来源：fenic README

Q3: fenic 是免费的吗？

fenic 本身是 Apache-2.0 开源免费库（本地部署无订阅费），但运行语义算子需要调用 LLM API，这部分按各 Provider 的定价付费（如 GPT-4o-mini：输入 $0.15/M tokens，输出 $0.60/M tokens）。fenic 内置 response caching 和 batching 减少 API 调用次数。来源：fenic LICENSE / OpenAI Pricing

Q4: fenic 能处理多大的数据集？

取决于 LLM 上下文窗口和 API 调用频率。GPT-4o-mini 单次调用可处理数千字文本。对于百万行级数据，建议先 filter 聚合或采样。fenic 内置 rate limiting 和 batching 防止 API 超额。来源：fenic README

Q5: fenic 能替代传统 ETL 工具吗？

fenic 定位是语义数据处理（非结构化→结构化），不是通用 ETL。它适合 ETL 管道中的”语义转换”环节——将自由文本转为类型化字段。传统 ETL 的确定性计算（如数值运算、精确 Join）仍用 pandas/PySpark 更合适。来源：产品定位分析