vaex

Vaex

概述

Vaex 是一个高性能 Python 库，专为惰性计算、外存 DataFrame 设计，可用于处理和可视化无法装入 RAM 的大型表格数据集。Vaex 每秒可处理超过 10 亿行数据，支持对包含数十亿行的数据集进行交互式探索和分析。

安装

安装完整的元包（推荐）：

uv pip install vaex

最小化安装（仅选择所需内容）：

uv pip install vaex-core vaex-viz vaex-hdf5 vaex-ml

vaex 包是一个元包，会引入 vaex-core、vaex-viz、vaex-hdf5、vaex-ml 和其他子包。Arrow 支持已内置于 vaex-core 中（独立的 vaex-arrow 包已弃用）。vaex-distributed 已弃用，建议改用 vaex-enterprise。

版本说明（vaex 4.19.0+）： Python 3.12 和 NumPy v2 要求 vaex >= 4.19.0。在 Windows 上，构建 annoy 依赖项时可能需要 Python 开发头文件。

何时使用此技能

以下情况适合使用 Vaex：

• 处理大于可用 RAM 的表格数据集（GB 到 TB）
• 对海量数据集执行快速统计聚合
• 创建大型数据集的可视化图表和热力图
• 在大数据上构建机器学习流水线
• 在不同数据格式之间转换（CSV、HDF5、Arrow、Parquet）
• 需要惰性计算和虚拟列，以避免内存开销
• 处理天文数据、金融时间序列或其他大规模科学数据集

Vaex 与替代方案对比： 如果数据可装入 RAM，且需要最高的内存内处理速度，请使用 polars。如果需要在集群上分布式处理 pandas/NumPy，请使用 dask。如果需要在单台机器上对超出 RAM 容量的表格数据进行外存分析，请使用 vaex，它通过内存映射 HDF5/Arrow 文件实现这一点。

核心功能

Vaex 提供六大核心功能领域，每个领域的详细说明都在 references 目录中：

1. DataFrame 和数据加载

从多种来源加载并创建 Vaex DataFrame，包括文件（HDF5、CSV、Arrow、Parquet）、pandas DataFrame、NumPy 数组和字典。请参阅 references/core_dataframes.md，了解：

• 高效打开大型文件
• 从 pandas/NumPy/Arrow 转换
• 使用示例数据集
• 了解 DataFrame 结构

2. 数据处理和操作

执行筛选、创建虚拟列、使用表达式，并在不将所有数据加载到内存的情况下进行聚合。请参阅 references/data_processing.md，了解：

• 筛选和选择
• 虚拟列和表达式
• Groupby 操作和聚合
• 字符串操作和日期时间处理
• 处理缺失数据

3. 性能和优化

利用 Vaex 的惰性计算、缓存策略和内存高效操作。请参阅 references/performance.md，了解：

• 了解惰性计算
• 使用 delay=True 批量处理操作
• 按需物化列
• 缓存策略
• 异步操作

4. 数据可视化

为大型数据集创建交互式可视化图表，包括热力图、直方图和散点图。请参阅 references/visualization.md，了解：

• 创建 1D 和 2D 图表
• 热力图可视化
• 使用选择
• 自定义图表和子图

5. 机器学习集成

借助转换器、编码器以及与 scikit-learn、XGBoost 和其他框架的集成，构建机器学习流水线。请参阅 references/machine_learning.md，了解：

• 特征缩放和编码
• PCA 和降维
• K-means 聚类
• 与 scikit-learn/XGBoost/CatBoost 集成
• 模型序列化和部署

6. I/O 操作

以最佳性能高效读写各种格式的数据。请参阅 references/io_operations.md，了解：

• 文件格式建议
• 导出策略
• 使用 Apache Arrow
• 处理大型 CSV 文件
• 服务器和远程数据访问

快速入门模式

对于大多数 Vaex 任务，请遵循以下模式：

import vaex

# 1. Open or create DataFrame
df = vaex.open('large_file.hdf5')  # or .csv, .arrow, .parquet
# OR
df = vaex.from_pandas(pandas_df)

# 2. Explore the data
print(df)  # Shows first/last rows and column info
df.describe()  # Statistical summary

# 3. Create virtual columns (no memory overhead)
df['new_column'] = df.x ** 2 + df.y

# 4. Filter with selections
df_filtered = df[df.age > 25]

# 5. Compute statistics (fast, lazy evaluation)
mean_val = df.x.mean()
stats = df.groupby('category').agg({'value': 'sum'})

# 6. Visualize (df.viz is the recommended accessor since vaex 4.0)
df.viz.heatmap(df.x, df.y, limits='99.7%', show=True)
# Legacy: df.plot1d() and df.plot() still work on the DataFrame

# 7. Export if needed
df.export_hdf5('output.hdf5')

使用参考文档

参考文件包含有关各项功能领域的详细信息。根据具体任务将参考文档加载到上下文中：

• 基本操作：从 references/core_dataframes.md 和 references/data_processing.md 开始
• 性能问题：查看 references/performance.md
• 可视化任务：使用 references/visualization.md
• 机器学习流水线：参考 references/machine_learning.md
• 文件 I/O：查阅 references/io_operations.md

最佳实践

1. 对于大型数据集，使用 HDF5 或 Apache Arrow 格式以获得最佳性能
2. 使用虚拟列代替物化数据，以节省内存
3. 执行多项计算时，使用 delay=True 批量处理操作
4. 导出为高效格式，而不是将数据保留为 CSV
5. 使用表达式执行复杂计算，避免中间存储
6. 使用 df.describe() 和 df.nbytes 分析数据形状和内存用量

常见模式

模式：将大型 CSV 转换为 HDF5

import vaex

# Open large CSV lazily (vaex 4.14+), or use from_csv to convert to HDF5
df = vaex.open('large_file.csv')
# df = vaex.from_csv('large_file.csv', convert='large_file.hdf5')

# Export to HDF5 for faster future access
df.export_hdf5('large_file.hdf5')

# Future loads are instant
df = vaex.open('large_file.hdf5')

模式：高效聚合

# Use delay=True to batch multiple operations
mean_x = df.x.mean(delay=True)
std_y = df.y.std(delay=True)
sum_z = df.z.sum(delay=True)

# Execute all at once
results = vaex.execute([mean_x, std_y, sum_z])

模式：使用虚拟列进行特征工程

# No memory overhead - computed on the fly
df['age_squared'] = df.age ** 2
df['full_name'] = df.first_name + ' ' + df.last_name
df['is_adult'] = df.age >= 18

资源

此技能包含 references/ 目录中的参考文档：

• core_dataframes.md - DataFrame 的创建、加载和基本结构
• data_processing.md - 筛选、表达式、聚合和转换
• performance.md - 优化策略和惰性求值
• visualization.md - 绘图和交互式可视化
• machine_learning.md - 机器学习流水线和模型集成
• io_operations.md - 文件格式和数据导入/导出

Agent 操作流程

1. 检查环境。 确认 Python 环境和库版本（python -c "import pkg; print(pkg.__version__)"），并检查数据的形状、类型和缺失值。
2. 明确输入。 根据数据或用户提供的信息确认格式、标识符和参数。凡是会影响结果的值，都应询问而非猜测。
3. 先运行小规模版本。 先在样本或单个折上运行，并检查运行时间和内存。
4. 使用上述说明和参考文档执行完整任务。
5. 验证结果。 使用留出数据、固定随机种子和适当的指标；检查是否存在数据泄漏；报告不确定性（置信区间、不同随机种子的标准差）。
6. 报告。 说明运行了哪些内容（版本、命令、参数）、检查了什么，以及哪些方面仍不确定。

如果发生以下情况	请执行以下操作
内存不足或执行速度过慢	对数据进行子采样，使用分块或惰性计算，或缩小模型规模，并告知用户所做的更改。
这些说明中提到的函数、标志或端点在已安装版本中不存在	查看已安装版本自带的文档（help()、--help、官方文档），进行适配，并告知用户。切勿编造 API。
必需的输入、标识符或参数含义不明确	询问用户，或在运行前明确说明所采用的假设。

诚信规则

• 切勿编造结果、参数、标识符、引文或统计数据。如果无法运行或验证某项内容，请如实说明。
• 切勿报告本次会话中未计算的指标；应展示生成每个数值的代码路径。
• 此处与特定版本相关的细节可能已经过时：请对照已安装版本的官方文档进行确认。
• 对于会产生费用、占用共享 GPU 或云配额、涉及个人或患者数据，或无法撤销的操作，须先征得用户同意。

相关技能

• polars：用于 Python ETL、分析和 pandas 迁移的高性能 DataFrame 库。
• polars-bio：Python 库 polars-bio，用于在 Polars DataFrame 上执行基因组区间操作，以及生物信息学文件 I/O；基于 Arrow 和 DataFusion 构建。
• dask：用于处理大于内存容量的 pandas/NumPy 工作流的分布式计算库。