本文介绍在 polars 中处理流式逐行数据生成场景的最佳实践，重点对比列表累积、vstack 拼接等传统方式，推荐使用 lazyframe + `sink_csv` 的流式写入方案，并提供可直接复用的向量化批处理与自定义分解函数集成方法。
在实时数据采集、日志解析或模型推理等场景中，常需从生成器（generator）逐行获取原始数据，并经 decompose() 等逻辑提取结构化特征后，持续写入磁盘。此时若采用“每行建 DataFrame → vstack 拼接”或“Python 列表累积 → 定期转 DataFrame”，不仅内存开销大、性能差，还违背 Polars 的列式计算设计哲学。
✅ 最优解：LazyFrame 流式构建 + sink_csv 批量落盘
Polars 原生支持从可迭代对象（如生成器）直接构建 LazyFrame，并可通过 .sink_csv() 实现真正的流式、分块（batched）磁盘写入——无需将全部数据载入内存，且自动优化 I/O 与类型推断：
import polars as pl
def generation_mechanism():
for x in range(1_000_000):
yield (x, x + 1)
# 直接从生成器构建 LazyFrame（零拷贝、惰性求值）
lf = pl.LazyFrame(generation_mechanism(), schema=["feature_a", "feature_b"])
# 流式写入 CSV，每 100 行刷盘一次（batch_size 控制内存峰值）
lf.sink_csv("output.csv", batch_size=100)该方案优势显著：
- ✅ 内存恒定：仅缓存一个 batch（如 100 行）于内存；
- ✅ 零中间 DataFrame：避免 vstack 的重复内存分配与列对齐开销；
- ✅ 类型安全：schema 参数显式声明列类型，规避运行时推断错误；
- ✅ 可扩展：后续可无缝接入 .filter()、.with_columns() 等链式转换。
? 当 decompose() 逻辑复杂时：用 map_batches 向量化封装
若 decompose(row) 不是简单解包（如需调用外部 API、条件分支或状态依赖），可将其封装为 map_batches 的批处理函数。注意：务必设置 streamable=True 以启用流式执行：
def decompose(row):
# 示例：对元组做非向量化变换（实际中应尽量向量化）
a, b = row
return a * 2, b ** 2
lf = (
pl.LazyFrame({"raw": generation_mechanism()})
.map_batches(
lambda df: df.select(
pl.col("raw").map_elements(
decompose,
return_dtype=pl.Struct({"feature_a": pl.Int64, "feature_b": pl.Int64})
)
),
streamable=True
)
.select(pl.col("raw").struct.unnest()) # 展开 struct 为独立列
)
lf.sink_csv("output.csv", batch_size=100)⚠️ 不推荐的方案及原因
- ❌ vstack 循环拼接：每次 vstack 触发深拷贝与内存重分配，时间复杂度 O(n²)，10 万行即明显卡顿；
- ❌ Python 列表累积：虽比 vstack 快，但仍需一次性构造全量 DataFrame，丧失流式优势，且类型推断不可控；
- ❌ itertools.batched + map_elements：适用于轻量级批处理，但 map_elements 默认非向量化（Python 回调开销大），仅作备选。
? 关键建议
- 优先向量化 decompose：改用 Polars 表达式（如 pl.col().str.extract()、pl.when().then()）替代 Python 函数；
- 显式声明 schema：避免隐式类型推断导致的精度丢失（如 float→int 截断）；
- 监控 batch_size：根据单行内存占用（pl.datatypes.* 查看）设为 50–1000 行，平衡 I/O 效率与内存占用；
- 生产环境加异常防护：sink_csv 支持 include_header=True（首行写列名），并建议配合 try/except 处理写入失败。
综上，Polars 的 LazyFrame + sink_* 系列 API 是处理流式数据生成任务的官方推荐、性能最优、内存最省的范式。放弃“模拟 Pandas 式循环构建”，拥抱惰性计算与流式落盘，方能真正释放 Polars 的高性能潜力。
