Zillion：给数据分析师的 AI 语义层工具

你是否有这样的经历：业务方扔给你一个需求——"帮我看看Q2各区域的营收和线索数，按月份拆一下，同时对比去年同期"——然后你就开始吭哧吭哧写 SQL，在 Excel 里反复折腾，最后产出的报表还不一定能回答老板的下一个追问。这种"需求翻译"工作占据了数据分析的相当大一部分精力，而 Zillion 正是为解决这个痛点而生的。

Zillion 是一个 Python 原生的语义数据建模与分析工具，GitHub 获星 208 颗（统计截至 2026 年 7 月），项目处于 Alpha 阶段，核心定位是：在你的数据库之上架设一层"语义抽象层"，让你用简洁的 API 定义指标与维度，然后让 Zillion 自动生成跨数据源的 SQL 查询，最后返回可直接分析的 Pandas DataFrame。如果你是数据分析从业者，或者你需要搭建 BI 系统的基础数据层，Zillion 值得重点关注。

图 1：Zillion 项目在 GitHub 上的 Star 数量

背景故事：从 SQL 泥潭中脱身

Zillion 的作者是 GitHub 用户 totalhack（Kurt），项目的诞生意图非常朴素——不想每次做报表都写一堆重复的 SQL JOIN 语句。在他经手的实际业务场景中，数据往往分散在 MySQL、PostgreSQL、SQLite 等多个数据库中，还有大量 Excel、CSV 和 JSON 格式的文件。传统 BI 工具要么价格高昂、要么部署复杂、要么对数据源的接入能力有限。Zillion 因此诞生：做一个轻量级的语义层，Python-first，通过 SQLAlchemy Core 连接现有数据库基础设施，不需要任何额外的数据仓库或 ETL 管道，直接在原有数据上跑分析。

在 Reddit 的讨论中，用户对 Zillion 的定位做出了精准总结："There's a separate demo UI and web API which is very much usable, but not what many would consider production-grade at enterprise scale."——换句话说，Zillion 目前更偏向数据工程师/分析师的个人工具，而不是面向企业级 BI 平台。但对于个人和小团队来说，它的性价比相当高。

核心概念：指标（Metrics）和维度（Dimensions）

Zillion 的使用哲学围绕两个核心概念展开：指标（Metrics） 和 维度（Dimensions）。如果你是数据仓库的老手，这两个词应该不陌生；如果你是新手，理解起来也非常直观。

维度（Dimensions） 通常是相对静态的、分类型的属性，比如时间（年、月、日）、地区（省、市、区）、产品类别等。维度决定了"报表从哪个角度切分数据"，类似于 Excel 透视表中的行标签。

指标（Metrics） 则是可以聚合计算的数值，比如营收、线索数、UV 访问量、转化率等。指标回答"数量是多少"的问题。

在 Zillion 中，你只需要告诉它"我要看营收和线索数，按日期维度分组"，它就能自动生成对应的 SQL：

• dimensions → GROUP BY 字段
• metrics → SUM() / COUNT() 聚合函数
• criteria → WHERE 过滤条件

这种映射关系由 Zillion 在内部处理，对用户完全透明。

跨数据源查询：Drill-Across 的实现

Zillion 最有技术含量的特性之一是 drill-across（跨数据源钻取）。在一个真实业务场景中，营收数据可能存在 MySQL 的 sales 表，而线索数据在 PostgreSQL 的 leads 表，两者都通过 partner_id 关联到合作伙伴维度表。如果你要出一个"各合作伙伴的营收 vs 线索"对比报表，传统做法需要先在各自数据库分别查询，再在应用层合并。

Zillion 的做法是：在 DataSource 层分别生成最优的 SQL，然后在 Combined 层（默认是内存中的 SQLite）进行跨源 JOIN 和聚合，最终输出统一的 DataFrame。这套机制在代码中由 warehouse.py 的 Warehouse 类统一调度，查询计划由 core.py 的查询引擎负责生成。

值得注意的是，Combined 层默认使用内存 SQLite，对于百万级数据量完全够用；对于更大规模数据，Zillion 建议将 Combined 层配置为独立数据库（如 DuckDB 或 PostgreSQL）来获得更好的性能。

AI Agent 自然语言查询：最有野心的功能

Zillion 还配备了一个实验性的 AI Agent 模块（需要安装 zillion[agent] 依赖），支持用自然语言向数据仓库提问。例如：

result = warehouse.execute_text("revenue and leads by date last month")
print(result.df)

背后依赖 OpenAI 的 agents SDK（默认模型为 GPT-5.4，可配置），Agent 会自动规划查询计划：先通过工具函数了解仓库中有哪些指标和维度，再生成对应的 execute() 参数，最终返回结果。

这个功能的实现方式很有意思：Agent 并不是直接生成原始 SQL，而是生成 Zillion 的 API 调用参数，这意味着自然语言查询的输出天然具有 Zillion 报表系统的所有能力——维度选择、指标聚合、过滤条件等。这比直接让 LLM 生成 SQL（容易出错且难以约束输出格式）要稳健得多。

不过，这个功能目前被标记为"实验性"，使用前需要：

1. 安装 pip install zillion[agent]
2. 配置 OPENAI_API_KEY
3. 可选：运行 Qdrant 向量数据库来支持字段语义嵌入（Warehouse.init_embeddings()）

部署与安装：Python 工程师零门槛上手

Zillion 的安装非常简单：

pip install zillion              # 核心包
pip install zillion[agent]      # AI agent 扩展
pip install zillion[mysql]       # MySQL 数据源支持
pip install zillion[postgres]   # PostgreSQL 数据源支持
pip install zillion[duckdb]     # DuckDB 数据源支持

项目需要 Python 3.10 及以上版本，核心依赖包括 SQLAlchemy（数据库连接）、Pandas（数据处理）、NetworkX（图计算，支撑数据源关系建模）、YAML 配置解析等。没有 C 扩展或系统级依赖，跨平台体验良好。

项目中提供了 docker-compose.yml，预置了 MySQL 8.0 和 PostgreSQL 15 的测试环境，一行命令启动：

docker-compose up

可以立即连接测试数据库开始体验，而不需要在自己的机器上安装配置数据库。项目的 dev_config.yml 也给出了完整的配置模板，包含各数据源的连接参数和测试账号。

快速上手门槛：极低。 只要你会 pip install 和写 Python，就能在 10 分钟内跑通第一个示例。

项目架构：清晰的模块分层

Zillion 的代码结构非常清晰，源码在 zillion/ 目录下，核心模块如下：

模块	职责
warehouse.py	核心入口，Warehouse 类管理所有数据源，执行报表查询，协调各层工作
datasource.py	封装 SQLAlchemy 连接，支持 MySQL/PostgreSQL/SQLite/DuckDB/Excel/CSV/JSON 等数据源
core.py	查询引擎，SQL 生成，配置加载，是系统核心逻辑所在地
report.py	Report 类，封装查询结果，生成 DataFrame
field.py	指标和维度的定义、类型推导、字段管理器
model.py	数据库 ORM 模型，报表规格的持久化
agent.py	AI Agent 模块，OpenAI agents SDK 集成，自然语言查询规划
configs.py	YAML 配置解析器
dialects/	各数据库方言适配器（负责生成各数据库原生 SQL）

这套架构的优点是关注点分离清晰：datasource 层负责连接，core 层负责逻辑，report 层负责输出，agent 层负责 AI 交互，四个模块各司其职，耦合度低，扩展性强。

数据源支持：覆盖常见分析场景

Zillion 支持的数据源类型相当全面：

SQL 数据库：通过 SQLAlchemy Core 连接，官方测试覆盖了 MySQL 8.0、PostgreSQL 15、SQLite、DuckDB。理论上任何 SQLAlchemy 支持的数据库（如 SQL Server、Oracle）都能接入。

文件数据源：直接支持 CSV、Excel（.xlsx/.xls）、JSON、HTML 表格文件。可以从本地路径或远程 URL（GitHub Raw、HTTP）读取数据文件，非常适合接入公开数据集或小型业务数据文件。

Ad-Hoc 数据表：Zillion 还支持动态创建临时数据表，不需要预先配置，适合一次性分析场景。

需要注意的是，Zillion 目前不支持多对多关系建模，这对某些复杂业务场景可能构成限制。项目作者在文档中明确说明了这一点，并建议通过引入中间关联表来解决。

局限与挑战：不回避的问题

坦诚地说，Zillion 目前并非完美，存在以下几个需要关注的局限：

1. 实验性 AI 功能：自然语言查询模块标记为 Alpha，生产环境使用需要谨慎。OpenAI API 依赖也意味着使用成本不可忽视。

2. 大规模数据处理：Combined 层默认内存 SQLite，适合中小数据量；百GB以上数据建议切换到 PostgreSQL 或 ClickHouse。

3. 不支持多对多关系：这在某些业务场景下是硬限制，无法绕开。

4. 企业级安全特性缺失：没有细粒度的权限控制、审计日志、多租户隔离，更适合个人或小团队内部使用。

5. Alpha 状态：API 尚未稳定，大版本升级可能存在破坏性变更。

行业意义：轻量语义层的价值

近年来，数据分析领域出现了一个趋势：在大数据平台（Snowflake/BigQuery）之外，越来越多团队需要一种"轻量级语义层"，来桥接业务人员的数据需求和技术人员的数据模型。Metabase、Apache Superset、Cube.dev 等工具都是这个方向的探索者。

Zillion 的差异化在于纯 Python 原生——不需要额外部署服务，不依赖特定的 BI 前端，直接嵌入数据分析工作流。对于已经用 Python 做数据分析的团队，Zillion 的学习曲线几乎为零。这使得它更像是一个"给 Python 数据分析师用的 dbt"，但比 dbt 更轻、更专注于查询和分析，而不是数据转换。

总结

Zillion 是一款面向 Python 数据分析师和小型数据团队的语义数据建模工具，核心价值在于：让你用简单 API 定义指标和维度，自动生成跨数据源的 SQL 查询，并支持可选的 AI 自然语言查询。

它的优势是轻量、Python 原生、支持多种数据源、部署门槛低；局限是 AI 功能实验性、不支持多对多关系、尚未达到企业级安全标准。

如果你正在寻找一个轻量级的语义层工具来提升报表开发效率，或者想探索 AI 辅助的数据分析，Zillion 是一个值得在本地尝试的开源项目。

图 2：Zillion 在 PyPI 上的下载量

基本信息

项目	内容
编程语言	Python
GitHub Stars	208（截至 2026-07）
默认分支	master
License	MIT
Python 版本	>= 3.10
主要依赖	SQLAlchemy, Pandas, NetworkX, OpenAI agents SDK
AI 功能	实验性（需要 zillion[agent]）
部署难度	简单（pip 一键安装）