Pathway 入门指南：用 Python API + Rust 引擎构建实时流式 ETL 与 RAG 管道

Pathway 入门指南：用 Python API + Rust 引擎构建实时流式 ETL 与 RAG 管道

【免费下载链接】pathwayPython ETL framework for stream processing, real-time analytics, LLM pipelines, and RAG.项目地址: https://gitcode.com/GitHub_Trending/pa/pathway

本文基于 Pathway 官方开发者文档首页 welcome.md 展开，系统介绍 Pathway Live Data Framework 的定位、安装方式与全部 11 项核心特性，并结合仓库中的pyproject.toml、Python API 入口与 Rust 引擎源码逐条佐证其实现依据。读完本篇，你将掌握 Pathway 的完整安装与依赖分组、首个实时管道代码的运行方式，以及每一项框架特性在源码中的落点。

一、什么是 Pathway Live Data Framework

Pathway Live Data Framework 是一个面向数据流（data streams）的 Python 数据处理框架，专为分析与 AI 管道设计。文档首页给出的定位非常明确：

• 它是流式处理场景的理想选择：适用于实时流式 ETL（streaming ETL）、面向非结构化数据的 RAG 管道等实时处理用例；
• 项目描述将其概括为：用于流处理、实时分析、LLM 管道与 RAG 的 Python ETL 框架（见 README.md）。

也就是说，你用惯常的 Python 写法声明“读取数据 → 转换 → 写出结果”，而数据更新、乱序补算、增量维护这些流式框架最麻烦的部分，由底层引擎自动处理。仓库中 README.md 进一步说明了它的三个工程承诺：同一份代码可同时用于本地开发、CI/CD 测试、批处理作业、流回放与实时流；计算全量驻留内存，便于用 Docker/Kubernetes 部署；Python 代码实际由 Rust 引擎驱动执行，从而实现多线程、多进程乃至分布式计算。

二、快速安装：pip install pathway及其依赖分组

文档首页给出的最简安装方式就是一条命令：

pip install pathway

README.md 中推荐带升级标志的等价形式：pip install -U pathway。它会安装运行管道所需的全部基础依赖，包括 Rust 引擎本体。

2.1 运行环境前提

• Python 版本：pyproject.toml 声明requires-python = ">=3.10"，即要求 Python 3.10 及以上；
• 操作系统：官方仅在macOS 与 Linux上提供支持（README.md 与 Installation 文档 均有提示），Windows 用户需借助 WSL、Docker 或虚拟机；
• 安装完成后，import pathway as pw即可使用，无需额外服务。

2.2 可选依赖组（extras）

Installation 文档 将依赖拆分为若干组以便按需安装，pyproject.toml 的[project.optional-dependencies]表是这些分组的权威定义。常用分组如下：

从 pyproject.toml 可以确认：xpack-llm组实际包含 openai、litellm、langchain、llama-index-core/retrievers、instructor、google-generativeai 等，并附带大量版本上限与兼容性注释；xpack-sharepoint组仅新增Office365-REST-Python-Client一个依赖。多个分组可一次性安装，例如pip install "pathway[xpack-llm, airbyte]"。

基础依赖方面，pyproject.toml 还声明了 pandas、numpy、pyarrow、pydantic、boto3、sqlalchemy/deltalake，以及OpenTelemetry 全家桶（opentelemetry-api / sdk / exporter-otlp-proto-grpc）——这正是文档首页声称“fully compatible with OpenTelemetry”的直接依赖依据。

三、第一个实时管道：从 README 示例开始运行

README.md 给出了一段最小可运行的实时计算示例——实时统计输入中非负值的总和：

import pathway as pw # Define the schema of your data (Optional) class InputSchema(pw.Schema): value: int # Connect to your data using connectors input_table = pw.io.csv.read( "./input/", schema=InputSchema ) #Define your operations on the data filtered_table = input_table.filter(input_table.value>=0) result_table = filtered_table.reduce( sum_value = pw.reducers.sum(filtered_table.value) ) # Load your results to external systems pw.io.jsonlines.write(result_table, "output.jsonl") # Run the computation pw.run()

这段代码体现了 Pathway 的三段式心智模型：connector 读入 → Table 变换（filter/reduce/join/groupby…）→ connector 写出，最后用一行pw.run()启动计算。仓库中 python/pathway/init.py 证实了 API 面的完整性：顶层导出了run、groupby、join系列（inner/left/right/outer）、reducers、Schema、udf/apply_async等原语，以及stateful、statistical、temporal、graphs、indexing、ml等标准库模块。

3.1 启动方式

• 直接当作普通 Python 脚本运行：$ python main.py；
• 或使用官方 CLI：$ pathway spawn python main.py，该命令入口在 pyproject.toml 中注册为pathway = "pathway.cli:main"，对应实现见 python/pathway/cli.py；
• Pathway 原生支持多线程，指定线程数即可并行化：$ pathway spawn --threads 3 python main.py；
• 运行时自带监控仪表盘（web dashboard），可查看各 connector 的消息数、系统延迟与日志，对应源码目录 python/pathway/web_dashboard。

3.2 开箱模板

文档首页的“Try Our Templates”卡片指向 RAG 与 ETL 两类可直接运行的模板；在本仓库中，examples/templates 提供了模板骨架，examples/notebooks（45 个 notebook）与 examples/projects 收录了完整示例工程，可作为“跑通自己的数据”的起点。

四、核心特性逐条解析：文档声明与源码证据

文档首页列出了 11 项 Key Features。下面逐条对照仓库源码，说明每一项“从哪里来”。

4.1 易用的纯 Python API

声明：“Pathway fully compatible with Python. Use your favorite Python tools and ML libraries.”

从 python/pathway/init.py 可见，框架不要求你学习新语言：任何 Python 函数都可以通过udf/apply注入管道，udfs模块还提供 pandas、polars 等库的预置包装器（如pandas_transformer、AsyncTransformer）。pyproject.toml 中 pandas、numpy、scikit-learn、networkx 等作为硬依赖预装，即官方预期你会在管道内直接调用主流 Python/ML 生态。

4.2 可扩展的 Rust 引擎（无 JVM、无 GIL 限制）

声明：“your Python code is run by a powerful Rust engine with multithreading and multiprocessing. No JVM and no GIL!”

仓库结构直接印证了这一点：

• 顶层 src/ 目录是 Rust 引擎源码：src/lib.rs 为 crate 入口，另有engine/（计算引擎）、persistence/（状态持久化）、python_api/（Python 绑定）、connectors/（Rust 侧连接器）、async_runtime.rs（异步运行时）等模块；
• pyproject.toml 的[tool.maturin]段声明module-name = "pathway.engine"，即 Python 端的pathway.engine是一个由 maturin 构建的 Rust 扩展模块——这就是“Python 代码交给 Rust 引擎执行”的物理载体；
• 引擎的算法内核 Differential Dataflow 与调度内核 Timely Dataflow 以源码形式内嵌在仓库 external/differential-dataflow 与 external/timely-dataflow 目录中（约 260 个 Rust 源文件），可直接阅读。

4.3 有状态算子与增量计算

声明：“use stateful and temporal operations such as groupby and windows” 以及 “using Differential Dataflow, Pathway takes care of out-of-order data points for you, in real time.”

• Python 侧：pw.groupby、GroupedTable在 python/pathway/init.py 中导出；pathway.stdlib提供stateful（状态化变换）、temporal（时间窗口）、statistical、ordered等模块，覆盖 groupby/窗口/排序类需求；
• 引擎侧：Differential Dataflow 的差分（difference）语义是增量计算的根基——数据到达时只计算“变化量”而非全量重算，因此迟到的、乱序的数据点会在到达时触发结果更新。README.md 对一致性的表述是：Pathway 帮你管理时间（time management），late/out-of-order 数据到来时系统会更新既有结果。

4.4 批与流一体（Batch and streaming alike）

声明：“use the same pipeline on static data and live data streams.”

同一管道代码既消费静态文件（如示例中的pw.io.csv.read("./input/")），也消费持续变化的数据源。README 强调同一份代码可用于“local development, CI/CD tests, running batch jobs, handling stream replays, and processing data streams”。仓库中还有专门文档展开这两种模式的区别：Streaming and Static Modes 与 Batch Processing。

关于一致性等级需要区分两个文档口径：文档首页在特性列表中将“Exactly once consistency（批/流结果一致）”列为核心能力；而 README.md 的 Features 一节表述更精确——免费版提供 at-least-once 一致性，企业版提供 exactly-once 一致性。在评估生产部署时应以后者为准。

4.5 内存数据处理与低延迟

声明：“In-memory data processing: real-time updates, reduced latency, and higher throughput.”

README.md 说明“all the pipeline is kept in memory”，整个管道状态常驻内存，更新以增量方式在内存中完成，这是低延迟实时更新的直接原因。

4.6 部署：Docker / Kubernetes / OpenTelemetry

声明：“Easy to deploy with Docker or Kubernetes. The Pathway Live Data Framework comes with an orchestrator and is fully compatible with OpenTelemetry.”

• Docker：官方镜像pathwaycom/pathway可用如下 Dockerfile 构建应用（摘自 README.md）：

FROM pathwaycom/pathway:latest WORKDIR /app COPY requirements.txt ./ RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [ "python", "./your-script.py" ]

docker build -t my-pathway-app . docker run -it --rm --name my-pathway-app my-pathway-app

对于单文件脚本，也可直接挂载执行：

docker run -it --rm --name my-pathway-app -v "$PWD":/app pathwaycom/pathway:latest python my-pathway-app.py

仓库中 examples/projects 收录了多个带 Dockerfile 的示例工程，可参考其实际写法。

• OpenTelemetry：依赖层面由 pyproject.toml 中固定的 opentelemetry api/sdk/grpc-exporter 三件套保证；Python API 层还有set_monitoring_config用于配置监控（在 python/pathway/init.py 中导出）。
• Kubernetes/云：README 说明容器化后的应用适合 K8s 部署，企业版支持分布式 K8s 部署与外部持久化；仓库中 integration_tests/ 下还有 kafka、airbyte、s3、iceberg 等方向的集成测试，可视为各连接器在真实环境中的验收用例。

4.7 持久化与回填（Persistence and backfilling）

声明：“save the state of the computation to quickly resume after a failure or a pipeline update.”

该能力在仓库中有清晰的双层实现：Python 侧 python/pathway/persistence 模块封装持久化 API，Rust 侧 src/persistence 目录负责状态存储的具体实现。README 将其定位为“pipeline 在更新或崩溃后可重启”的保障机制。注意文档首页对“exactly once”与“persistence”是并列为两项特性：前者关注批/流结果一致性，后者关注故障后免重放恢复。

4.8 LLM 工具链（Live AI）

声明：“online ML, RAG pipelines, vector indexes... your ML pipeline works on fresh data.”

• 代码落点：python/pathway/xpacks/llm 模块承载 LLM 封装、解析器、嵌入器、切分器与内存向量索引等工具，xpacks/connectors则承载相关连接器；
• 依赖落点：xpack-llm分组（见 2.2 节）安装 OpenAI、LiteLLM、LangChain、LlamaIndex 等，xpack-llm-docs安装 docling/unstructured/paddleocr 等文档解析栈，xpack-llm-local支持本地推理（sentence-transformers/transformers）；
• 仓库内还包含面向 LLM 评测的集成测试目录 integration_tests/rag_evals，可看到 RAG 评测管线的组织方式。

4.9 连接器生态：内置 40+ 原生连接器，Airbyte 扩展至 350+

声明：“comes with 350+ connectors, including SharePoint. Or implement your own.”

从源码结构看，python/pathway/io 目录下包含40 个原生连接器子包，覆盖：

• 消息队列/流：kafka、kinesis、pulsar、nats、mqtt、redpanda、rabbitmq、pubsub、leann、logstash；
• 数据库/数据仓库：postgres、mysql、mssql、mongodb、sqlite、clickhouse、questdb、duckdb、bigquery、dynamodb、elasticsearch；
• 文件与对象存储：csv、jsonlines、plaintext、fs、s3、minio、gdrive、deltalake、iceberg、pyfilesystem；
• 向量库（服务 RAG）：qdrant、milvus、weaviate、chroma、pinecone；
• 其他：airbyte（桥接数百种外部数据源）、debezium（CDC）、http、slack、python（自定义连接器基础）。

“350+”这一数字来自文档首页的表述，主要经由 Airbyte 连接器扩展获得（README 口径为“300+”）；SharePoint 连接器属于需免费 license key 的高级连接器（见 5 节）。如果现有连接器不满足需求，可基于pw.io.python自定义——这正是文档中“implement your own”的落点。

4.10 其余特性的对应关系小结

五、许可证与 License Key

• 软件许可证：Pathway Live Data Framework 采用BSL 1.1许可（见 LICENSE.txt 与 README.md）：允许无限非商业使用，以及多数商业用途且免费；仓库代码在 4 年后自动转为 Apache 2.0 开源许可；Pathway 旗下的配套公共仓库（示例、库、连接器）则以 MIT 许可开源。
• License Key：文档首页明确说明，监控（monitoring）与部分高级连接器（如 SharePoint）等特性需要一个免费 license key，通过 Pathway 官网注册即可获取。结合 Installation 文档，企业版 license 可通过两种方式使用：
  1. 环境变量：PATHWAY_LICENSE_KEY=file:///path/to/license.lic（或内联 license 文件内容）；
  2. Python 代码中：pw.set_license_key("file:///path/to/license.lic")后再调用pw.run()。
• 更完整的许可说明可参考仓库内 Licensing Guide。

六、下一步学习路径

文档首页“What's next”给出的学习路线，在本仓库中均有对应文档，建议按以下顺序阅读（路径均为仓库相对路径）：

1. Installation — 安装与依赖分组细节；
2. Pathway Overview — Live Data Framework 整体概览；
3. First realtime app — 第一个实时应用；
4. Core concepts — Table、Stream、时间戳等核心概念；
5. Why Pathway — 设计动机与取舍；
6. Streaming and Static Modes 与 Batch Processing — 两种运行模式；
7. Licensing Guide — 许可与 license key 细则。

配套资源方面：examples/notebooks 提供 45 个可交互 notebook；examples/projects 收录带 Dockerfile、CI 配置的完整示例工程；integration_tests/ 覆盖 kafka、airbyte、s3、iceberg、gdrive、db_connectors 等方向的端到端集成测试；Rust 引擎与 Differential/Timely Dataflow 内核源码分别位于 src/、external/differential-dataflow、external/timely-dataflow，欢迎克隆仓库深入阅读并贡献代码。

【免费下载链接】pathwayPython ETL framework for stream processing, real-time analytics, LLM pipelines, and RAG.项目地址: https://gitcode.com/GitHub_Trending/pa/pathway