---

问题

你编写了一个特征流水线，在本地使用 DuckDB 能正常运行。但当部署到 Snowflake 上时，却不得不重新改写代码。为了缓存中间结果，你又引入了额外的基础设施和结果命名机制。随后，由于需要追踪流水线的变化，你还搭建了一个元数据存储系统。恭喜你，终于将模型上线了！接下来该添加推理服务层了……

然而，仅仅六个月后，你就拥有了五个互不相通的工具，而这条流水线只有你自己才完全理解。

痛点	表现
到处都是胶水代码	每个计算引擎都像孤岛一样独立运作，跨引擎迁移意味着重写而非组合。
运行时反馈不足	使用的是命令式 Python 代码，只有在作业运行时才能发现潜在的错误。
不必要的重复计算	对于哪些部分发生了变化缺乏统一的认知，导致每次都要从头开始执行。
血缘关系不透明	特征逻辑、元数据和血缘关系分散在不同的系统中，调试起来如同考古一般。
“在我机器上能跑”	环境会逐渐漂移，想要复现结果就必须逆向工程别人的配置，并不断调整自己的环境。
有状态的编排工具	重试逻辑、任务状态、失败恢复……这些都需要额外的管理，也增加了出错的可能性。

特征存储、模型注册表、工作流编排工具：这些都是垂直化的孤岛，无法支持需要上下文和技能的自主型流程，而不仅仅是按类别划分。

Xorq

清单 = 上下文。 每次机器学习计算都会被转化为一个结构化、以输入为地址的 YAML 清单。

表达式 = 工具。 它们构成了一个目录，可以被发现；同时也是一个构建系统，能够在任何地方以确定性的方式执行，并支持用户自定义的缓存策略。

模板 = 技能。 提供多种开箱即用的技能，例如 scikit-learn 流水线、特征存储、语义层等。

$ pip install xorq[examples]
$ xorq init -t penguins

---

表达式

编写声明式的 Ibis 表达式，就像使用工具一样轻松运行。Xorq 在 Ibis 的基础上扩展了缓存功能、多引擎执行能力以及用户自定义函数的支持。

import ibis
import xorq.api as xo
from xorq.common.utils.ibis_utils import from_ibis
from xorq.caching import ParquetCache

penguins = ibis.examples.penguins.fetch()

penguins_agg = (
    penguins
    .filter(ibis._.species.notnull())
    .group_by("species")
    .agg(avg_bill_length=ibis._.bill_length_mm.mean())
)

expr = (
    from_ibis(penguins_agg)
    .cache(ParquetCache.from_kwargs())
)

只需在任意节点上调用 .cache() 方法，剩下的工作就由 Xorq 自动完成。无需手动生成或管理缓存键，也不需要编写失效逻辑。

跨引擎组合

一份表达式，可在多个引擎上运行。你的流水线的一部分可以在 DuckDB 上执行，另一部分则利用 Xorq 内置的 DataFusion 引擎，通过 Arrow Flight 执行 UDF。Xorq 以低开销的方式系统化地处理数据传输，告别胶水代码。

expr = from_ibis(penguins).into_backend(xo.sqlite.connect())
expr.ls.backends

(<xorq.backends.sqlite.Backend at 0x7926a815caa0>,
 <xorq.backends.duckdb.Backend at 0x7926b409faa0>)

表达式是工具，Arrow 是管道

Unix 让我们通过标准输出实现小工具之间的组合，而 Xorq 则让你的表达式通过 Arrow 实现组合。

In [6]: expr.to_pyarrow_batches()
Out[6]: <pyarrow.lib.RecordBatchReader at 0x15dc3f570>

---

清单

构建一个表达式，就能得到一份清单。

$ xorq build expr.py
builds/28ecab08754e

$ tree builds/28ecab08754e
builds/28ecab08754e
├── database_tables
│   └── f2ac274df56894cb1505bfe8cb03940e.parquet
├── expr.yaml
├── metadata.json
└── profiles.yaml

无需外部的元数据存储，也不需要单独的血缘追踪工具。构建目录本身就是版本化、可缓存且便于移植的产物。

# 以输入为地址，可组合且便携
# expr.yaml 摘录
nodes:
  '@read_31f0a5be3771':
    op: Read
    name: penguins
    source: builds/28ecab08754e/.../f2ac274df56894cb1505bfe8cb03940e.parquet

  '@filter_23e7692b7128':
    op: Filter
    parent: '@read_31f0a5be3771'
    predicates:
      - NotNull(species)

  '@remotetable_9a92039564d4':
    op: RemoteTable
    remote_expr:
      op: Aggregate
      parent: '@filter_23e7692b7128'
      by: [species]
      metrics:
        avg_bill_length: Mean(bill_length_mm)

  '@cachednode_e7b5fd7cd0a9':
    op: CachedNode
    parent: '@remotetable_9a92039564d4'
    cache:
      type: ParquetCache
      path: parquet

可复现的构建

清单是可往返且机器可写的。你可以用 Git diff 来比较不同版本的流水线，进行代码审查，跟踪 Python 依赖项，甚至仅凭 YAML 文件就能重新构建。

$ xorq uv build expr.py
builds/28ecab08754e/

$ ls builds/28ecab08754e/*.tar.gz
builds/28ecab08754e/sdist.tar.gz  builds/28ecab08754e/my-pipeline-0.1.0.tar.gz

构建过程会捕获所有内容：表达式图、依赖关系以及内存表。分享包含 sdist 的构建文件，就能获得完全一致的结果，不再出现“在我机器上能跑”的情况。

只重新计算发生变化的部分

清单是以输入为地址的：相同的输入会产生相同的哈希值。一旦输入发生改变，就会生成新的哈希值。

expr.ls.get_cache_paths()

(PosixPath('/home/user/.cache/xorq/parquet/letsql_cache-7c3df7ccce5ed4b64c02fbf8af462e70.parquet'),)

这个哈希值就是缓存的键。无需再调试失效逻辑。只要表达式相同，哈希值就相同，缓存自然有效。一旦输入发生变化，就会产生新的哈希值，从而触发重新计算。

传统的缓存机制会问：“这个是否过期了？”而基于输入地址的缓存机制则会问：“这是不是同一份计算？”后者的问题有着确定性的答案。

---

工具

清单提供了上下文，而工具则赋予了具体的技能：目录管理、自我检查、服务提供和执行。

目录

# 添加到目录
$ xorq catalog add builds/28ecab08754e/ --alias penguins-agg
已将构建 28ecab08754e 添加为条目 a498016e-5bea-4036-aec0-a6393d1b7c0f，修订版 r1

# 列出条目
$ xorq catalog ls
别名：
penguins-agg    a498016e-5bea-4036-aec0-a6393d1b7c0f    r1
条目：
a498016e-5bea-4036-aec0-a6393d1b7c0f    r1      28ecab08754e

运行

$ xorq run builds/28ecab08754e -o out.parquet

服务

通过 Arrow Flight 在任何地方提供表达式：

$ xorq serve-unbound builds/28ecab08754e/ \
  --to_unbind_hash 31f0a5be37713fe2c1a2d8ad8fdea69f \
  --host localhost --port 9002

import xorq.api as xo

backend = xo.flight.connect(host="localhost", port=9002)
f = backend.get_exchange("default")

data = {
    "species": ["Adelie", "Gentoo", "Chinstrap"],
    "island": ["Torgersen", "Biscoe", "Dream"],
    "bill_length_mm": [39.1, 47.5, 49.0],
    "bill_depth_mm": [18.7, 14.2, 18.5],
    "flipper_length_mm": [181, 217, 195],
    "body_mass_g": [3750, 5500, 4200],
    "sex": ["male", "female", "male"],
    "year": [2007, 2008, 2009],
}

xo.memtable(data).pipe(f).execute()

     species  avg_bill_length
0     Adelie             39.1
1  Chinstrap             49.0
2     Gentoo             47.5

放心调试

不再需要繁琐的溯源工作。 lineage 被编码在清单中，而不是分散在各个工具中，并且可以通过 CLI 查询。

$ xorq lineage penguins-agg

Lineage for column 'avg_bill_length':
Field:avg_bill_length #1
└── Cache xorq_cached_node_name_placeholder #2
    └── RemoteTable:236af67d399a4caaf17e0bf5e1ac4c0f #3
        └── Aggregate #4
            ├── Filter #5
            │   ├── Read #6
            │   └── NotNull #7
            │       └── Field:species #8
            │           └── ↻ see #6
            ├── Field:species #9
            │   └── ↻ see #5
            └── Mean #10
                └── Field:bill_length_mm #11
                    └── ↻ see #5

无状态的工作流

没有任务状态。只需在失败时重试即可。

Xorq 将表达式作为 Arrow RecordBatch 流来执行。不存在需要检查点的 DAG 任务图，只有数据在算子间流动。如果某处失败，只需从清单重新运行。缓存节点会立即解析，其余部分则会重新计算。

scikit-learn 集成

Xorq 可以将 scikit-learn Pipeline 对象转换为延迟表达式：

from xorq.expr.ml.pipeline_lib import Pipeline

sklearn_pipeline = ...
xorq_pipeline = Pipeline.from_instance(sklearn_pipeline)

---

模板

作为技能的开箱即用代码：

$ xorq init -t <template>

模板	描述
penguins	极简示例：缓存、聚合、多引擎
sklearn	分类流水线，训练与预测分离

人类友好的技能

模板是易于上手的组件，其中包含可与您的数据源组合的现成表达式。

即将推出

• feast — 特征存储集成
• boring-semantic-layer — 指标和维度目录
• dbt — dbt 模型组合
• 特征选择

---

水平堆栈

使用 Python 编写。以 YAML 形式编目。通过 Ibis 在任何地方进行组合。基于 DataFusion 构建的可移植计算引擎。通过 Arrow Flight 实现通用 UDF。

Lineage、缓存和版本控制随清单一起传递；被编目而非锁定在某个供应商的数据库中。

集成： Ibis • scikit-learn • Feast（开发中）• dbt（即将推出）

---

了解更多

• 快速入门教程
• 为什么选择 Xorq？
• scikit-learn 模板

---

1.0 版本之前，可能会有破坏性变更，并提供迁移指南。

Xorq 快速上手指南

Xorq 是一个面向机器学习的计算清单（Manifest）和组合工具集。它基于 Ibis 构建，支持声明式表达式、多引擎执行（如 DuckDB, Snowflake, DataFusion）、自动缓存以及可复现的流水线构建，旨在解决 ML 工程中胶水代码多、环境不一致和血缘不透明等痛点。

环境准备

• 操作系统: Linux, macOS 或 Windows (WSL 推荐)
• Python 版本: Python 3.9 或更高版本
• 前置依赖:
  • pip 包管理工具
  • 建议安装 uv (可选，用于更快的依赖管理和构建)，但非必须。

安装步骤

1. 基础安装

使用 pip 安装核心库及示例依赖：

pip install "xorq[examples]"

提示：国内用户若遇到下载缓慢问题，可使用清华或阿里镜像源加速：

pip install "xorq[examples]" -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 初始化项目

安装完成后，可以使用 xorq 命令行工具初始化一个示例项目（例如经典的企鹅数据集示例）：

xorq init -t penguins

这将生成包含基本表达式逻辑的 expr.py 文件及相关配置。

基本使用

Xorq 的核心工作流分为三个阶段：编写表达式 (Expression) -> 构建清单 (Build) -> 执行/服务 (Run/Serve)。

1. 编写声明式表达式

创建一个 Python 文件（如 expr.py），使用 Ibis 语法定义数据处理逻辑。Xorq 扩展了 Ibis，支持 .cache() 自动缓存和多后端切换。

import ibis
import xorq.api as xo
from xorq.common.utils.ibis_utils import from_ibis
from xorq.caching import ParquetCache

# 获取示例数据
penguins = ibis.examples.penguins.fetch()

# 定义处理逻辑：过滤空值并按物种聚合平均喙长
penguins_agg = (
    penguins
    .filter(ibis._.species.notnull())
    .group_by("species")
    .agg(avg_bill_length=ibis._.bill_length_mm.mean())
)

# 将 Ibis 表达式转换为 Xorq 表达式并启用自动缓存
expr = (
    from_ibis(penguins_agg)
    .cache(ParquetCache.from_kwargs())
)

2. 构建计算清单 (Build)

使用 CLI 将表达式编译为不可变的、版本化的构建产物（Manifest）。该目录包含所有依赖、缓存数据和执行图，确保“一次构建，到处运行”。

xorq build expr.py

输出示例：

builds/28ecab08754e

此时生成的 builds/<hash> 目录即为你的便携式工件，包含 expr.yaml (清单), metadata.json 和缓存数据。

3. 执行与查看结果

直接运行构建好的清单，输出结果到指定文件：

xorq run builds/28ecab08754e -o out.parquet

或者在 Python 中交互式执行：

import xorq.api as xo

# 加载构建好的表达式
expr = xo.load("builds/28ecab08754e")

# 执行并转换为 PyArrow 格式
result = expr.execute()
print(result)

4. 高级功能：跨引擎组合与服务

Xorq 允许同一个表达式在不同后端间无缝切换，或通过 Arrow Flight 提供服务。

切换后端示例：

# 将部分计算卸载到 SQLite，其余在 DuckDB 运行
expr = from_ibis(penguins).into_backend(xo.sqlite.connect())
print(expr.ls.backends)

启动服务 (Serve)： 通过 Arrow Flight 暴露表达式接口，供其他应用调用：

xorq serve-unbound builds/28ecab08754e/ \
  --to_unbind_hash 31f0a5be37713fe2c1a2d8ad8fdea69f \
  --host localhost --port 9002

5. 查看数据血缘

无需查阅分散的文档，直接通过 CLI 查看完整的计算血缘图：

xorq lineage penguins-agg

这将以树状结构展示从原始数据到最终指标的完整转换路径，便于调试和审计。