Pathway 模板（Templates）运行实战：从克隆、YAML 配置到本机、Docker 与云部署

Pathway Live Data Framework（以下简称 Pathway）的 Templates（模板）是一批开箱即用、面向实时 AI 与 ETL 场景的流水线骨架。它们用 YAML 声明式配置组装输入源、文档解析、向量索引与问答组件，让开发者不必从头写管线代码，就能在几分钟内跑起 RAG、实时 ETL 或文档问答应用。本篇基于仓库内的模板运行指南与配套示例工程，完整讲解模板如何获取、如何选择、如何用 YAML 自定义，以及本机、Docker 与云端三种运行方式的差异，帮助你把自己的数据接入一条可交付、可扩展的实时流水线。

Pathway 模板体系：文档与源码中的位置

仓库中模板相关内容主要分布在两处：

• 模板文档与索引：位于 docs/2.developers/7.templates/1.index.md，这里按 ETL 与 RAG 两条主线收录各模板的技术文章；运行方法的主文档即 Run a Template，YAML 配置语法可参见 YAML 配置教程。
• 可运行示例工程：仓库的 examples/projects 目录下内置了一批与模板文档对应的完整示例，例如 question-answering-rag/、kafka-ETL/、twitter/、best-movies-example/ 等。以 examples/projects/question-answering-rag 为例，一个模板工程通常只包含一个主入口脚本（main.py）加一份 README.md，结构非常轻量。

从模板文档的划分可以看出，Pathway 模板覆盖了两大类常见诉求：一类是实时 ETL/ELT（对接 Kafka、数据库、Airbyte、Delta Lake 等，见 docs/2.developers/7.templates/ETL 目录），另一类是 RAG / LLM 应用（文档索引、问答、多模态、私有化 RAG 等，见 docs/2.developers/7.templates/rag 目录）。模板的设计目标是由「开发者与非开发者」都能通过改 YAML 完成部署与定制，这也是后面配置章节的核心前提。

运行前置条件

在动手之前，确认本机满足以下条件：

• Git：用于克隆仓库并同步后续更新。
• LLM API Key：如果模板涉及向量化与生成模型（例如 OpenAI 或 Hugging Face），需要准备对应的 API Key；纯 ETL 模板通常不需要。
• 运行环境二选一：
  1. Docker（推荐）：会自动安装全部依赖，无需手工维护 Python 环境；
  2. Python 3.8+ + Pathway：适合本地开发调试。

若选择本地运行 RAG 类流水线，需要安装包含 LLM xpack 在内的完整发行包：

pip install pathway[all]

非 Docker 场景下还建议安装 Streamlit（UI 展示）以及用 pip 管理依赖。官方安装步骤可参考仓库文档中对安装指南的指引（见 Run a Template），本地安装后即可像使用普通 Python 库一样 import pathway as pw。

获取模板：克隆对应的仓库

Pathway 将模板按适用场景拆分存放，克隆时按需选择：

• ETL 类模板：克隆 Pathway 主仓库

  git clone https://github.com/pathwaycom/pathway.git
  

• RAG / LLM 类模板：这些模板通常依赖独立的 LLM 应用仓库，需要单独克隆对应的应用仓库（例如 llm-app 仓库下的 question_answering_rag、adaptive_rag、private_rag 等模板）。

提示：在当前仓库的 examples/projects 中已经内置了一批与模板一一对应的示例工程，例如 question-answering-rag 就是一个可直接 cd 进入运行的 RAG 参考实现，适合先跑通再对照正式模板。

克隆完成后，进入所选模板的目录。以 question_answering_rag 为例：

cd llm-app/templates/question_answering_rag

选择模板：从索引到范例

模板索引页 docs/2.developers/7.templates/1.index.md 以「ArticlesFromPath」的方式把全部模板文章聚合展示。选择时建议关注两点：

1. 按数据源与场景筛选：需要把文件/Google Drive/SharePoint 变成可检索知识库就选 RAG 系列（文档索引、问答）；需要对接消息队列、数据库做实时清洗与回填就选 ETL 系列；
2. 按技术栈确认：部分模板（如 adaptive RAG、multimodal RAG、private RAG）的 Python 代码完全相同，差异仅在 YAML 配置，因此选定一个熟悉的主模板后，改 YAML 即可快速得到另一形态的应用。

正式模板的用法往往由各模板自带的 README 或随附文章给出；当前仓库中 examples/projects/question-answering-rag/README.md 就是一个范例，它描述了从安装、.env 环境变量配置到发起请求的完整流程，可以作为你阅读任意模板 README 的参照。

配置模板：理解 YAML 声明式语法

绝大多数模板都可以不改一行 Python，仅通过 YAML 文件完成配置。Pathway 为模板定制了一套 YAML 解析器，其核心语法在 YAML 配置教程 中有系统讲解，以下是必须掌握的三个要点。

Mapping 标签：用 ! 引用 Python 对象

在 YAML 中，给键值映射打上 ! 前缀的标签，就能引用 Pathway 的 Python 对象：提供一个 mapping 时，该对象会被调用（构造），mapping 内容即参数。典型例子是定义一个文件系统输入源：

source: !pw.io.fs.read
  path: data
  format: binary
  with_metadata: true

由于类本身也是可调用对象，同样语法可用于初始化 LLM 客户端：

llm: !pw.xpacks.llm.llms.OpenAIChat
  model: "gpt-3.5-turbo"
  retry_strategy: !pw.udfs.ExponentialBackoffRetryStrategy
    max_retries: 6
  cache_strategy: !pw.udfs.DefaultCache {}
  temperature: 0.05
  capacity: 8

两个细节值得注意：

• 若想让一个无参可调用对象在读取 YAML 时真正被调用，需要传入空映射 {}（如上例的 cache_strategy: !pw.udfs.DefaultCache {}）；
• 若希望直接把对象当作值使用而不调用（典型是枚举），则不写映射。例如 BruteForceKnnFactory 的 metric 参数要求传入 pw.indexing.BruteForceKnnMetricKind 枚举成员：

retriever_factory: !pw.indexing.BruteForceKnnFactory
  reserved_space: 1000
  embedder: $embedder
  metric: !pw.indexing.BruteForceKnnMetricKind.COS
  dimensions: 1536

上述标签不仅能引用 pathway 包内组件，也可用于导入你自己的函数与类——这正是模板「在 YAML 层完成全部定制」的扩展点。

变量：用 $ 复用配置块

以 $ 开头的标识符表示配置文件中后续复用的变量，可将同一策略（如重试与缓存策略）在多处共享：

$retry_strategy: !pw.udfs.ExponentialBackoffRetryStrategy
  max_retries: 6

llm: !pw.xpacks.llm.llms.OpenAIChat
  model: "gpt-3.5-turbo"
  retry_strategy: $retry_strategy
  cache_strategy: !pw.udfs.DefaultCache {}
  temperature: 0.05
  capacity: 8

embedder: !pw.xpacks.llm.embedders.OpenAIEmbedder
  model: "text-embedding-ada-002"
  retry_strategy: $retry_strategy
  cache_strategy: !pw.udfs.DefaultCache {}

环境变量注入：大写标识符自动回退到环境

仅由大写字母与下划线组成的 $ 标识符会被当作环境变量引用。例如把问答服务端口交由外部注入：

port: $PATHWAY_PORT

运行前设置好 PATHWAY_PORT 环境变量即可。若环境变量取值符合 YAML 语法（合法整数、浮点数或布尔值）会被自动解析，否则以字符串返回。注意：当同名变量同时存在于 YAML 文件与环境变量中时，YAML 中的定义优先级更高。

一个完整的问答 RAG 模板示例

下面是一份来自问答模板 app.yaml 的完整配置骨架，它串起了「文件输入 → 解析 → 切分 → 向量检索 → LLM 问答」的整条链路：

$sources:
  - !pw.io.fs.read
    path: data
    format: binary
    with_metadata: true

$llm: !pw.xpacks.llm.llms.OpenAIChat
  model: "gpt-3.5-turbo"
  retry_strategy: !pw.udfs.ExponentialBackoffRetryStrategy
    max_retries: 6
  cache_strategy: !pw.udfs.DiskCache
  temperature: 0.05
  capacity: 8

$embedder: !pw.xpacks.llm.embedders.OpenAIEmbedder
  model: "text-embedding-ada-002"
  cache_strategy: !pw.udfs.DiskCache

$splitter: !pw.xpacks.llm.splitters.TokenCountSplitter
  max_tokens: 400

$parser: !pw.xpacks.llm.parsers.UnstructuredParser

$retriever_factory: !pw.stdlib.indexing.BruteForceKnnFactory
  reserved_space: 1000
  embedder: $embedder
  metric: !pw.stdlib.indexing.BruteForceKnnMetricKind.COS
  dimensions: 1536

$document_store: !pw.xpacks.llm.document_store.DocumentStore
  docs: $sources
  parser: $parser
  splitter: $splitter
  retriever_factory: $retriever_factory

question_answerer: !pw.xpacks.llm.question_answering.BaseRAGQuestionAnswerer
  llm: $llm
  indexer: $document_store

# Change host and port by uncommenting these lines
# host: "0.0.0.0"
# port: 8000

# Cache configuration
# with_cache: true

# If `terminate_on_error` is true then the program will terminate whenever any error is encountered.
# Defaults to false, uncomment the following line if you want to set it to true
# terminate_on_error: true

问答模板要求 YAML 中必须出现 question_answerer，并允许通过顶层键覆盖 host、port、with_cache 与 terminate_on_error 的取值（默认注释即默认值）。基于这份骨架，你可以做三类最常见的定制：

1. 追加数据源：在 $sources 列表中追加新的输入连接器即可让同一份代码接入更多来源。官方 YAML 已预留 Google Drive、SharePoint 等连接器注释块，去掉注释、填好 object_id / service_user_credentials_file 等参数即可生效。
2. 更换模型提供方：把 $llm 换成本地可跑的 LiteLLMChat（指向本地 api_base）、$embedder 换成 SentenceTransformerEmbedder，就能得到不依赖外部服务的本地 RAG，这与私有化 RAG 模板的思路一致。
3. 升级检索能力：将单一向量索引替换为 HybridIndexFactory（向量索引 BruteForceKnnFactory + 全文检索 TantivyBM25Factory 的组合），以同时获得语义与关键词检索能力。

更细的语法、变量与各类输入源示例可在 YAML 配置教程、数据源示例 与 RAG 配置示例 中查阅。对于不使用 YAML 的模板，其配置与用法步骤以各模板自带 README 和随附文章为准。

运行模板的三种方式

方式一：本机直接运行（Self-hosting，手动）

手动运行就是直接执行模板的主 Python 文件（通常叫 main.py）。这种方式需要你手工安装依赖并准备好环境变量。以仓库内置示例 examples/projects/question-answering-rag 为例，其 README 给出了完整流程：克隆后在 examples/projects/question-answering-rag/ 下执行

pip install pathway[xpack-llm] python-dotenv

创建 .env 并写入 OPENAI_API_KEY=your_openai_api_key_here，然后

python main.py

启动后用 curl 发一条查询：

curl --data '{ "messages": "What is the value of X?"}' http://localhost:8011

从 main.py 的源码可以看到，该示例通过 pw.io.http.PathwayWebserver(host="0.0.0.0", port=8011) 暴露 REST 接口，默认端口为 8011（可自行修改）；pipeline() 函数（main.py）内部依次完成「文件读取 → 构建 DocumentStore → 接收查询 → 检索 → 拼装 prompt → LLM 生成 → 回写响应 → pw.run()」的编排，最终整个流程以**实时（live）**方式运行——每当 data/ 目录中的文档发生变化，索引会自动更新，无需重启。这与 Pathway 增量引擎的行为一致。

方式二：Docker 自动化运行（推荐）

如果模板附带了 docker-compose.yml，推荐用 Docker 方式运行，依赖自动装好、环境可复现：

docker compose up

仓库中有大量可供参考的 compose 配置，例如 examples/projects/debezium-postgres-example/docker-compose.yml 展示了「postgres + zookeeper + kafka + debezium + pathway」多服务编排的写法；examples/projects/twitter/docker-compose 中则用不同 compose 文件区分「全量回放」「流式回放」「给定 topic 的流」等多种启动形态。实际使用哪个 compose 文件、是否需 --build 重新构建镜像，以各模板 README 说明为准。

方式三：云端部署

本地与 Docker 的运行方式无法满足所有规模化诉求，而主流云平台普遍对 Docker 容器或 Python 部署有良好支持，可以把模板项目平滑迁上云。在云上部署时可以考虑：

• 将模板容器化后发布到云容器服务，由平台负责扩缩容；
• 需要分布式多机部署、原生支持 Kubernetes 与 Helm 时，可关注 Pathway Enterprise（面向端到端数据处理与实时智能分析的企业级方案），它采用有状态 StatefulSet 部署模式，要求全部 Pod 在线协作，其支持能力与集群运维整合可参阅 云端部署指南。具体按云厂商分的部署教程（GCP、AWS Fargate、Azure ACI 等）也在该文档目录 docs/2.developers/7.templates/60.deploy 下逐一列出。

实践建议小结

• 先本地、后容器、再上云：调试阶段用 python main.py 最快看到日志与结果；确认无误后切换 docker compose up 固化依赖；规模化需求再考虑云端与 Enterprise 方案。
• 优先通过 YAML 定制：数据源、LLM 提供方、切分与检索策略大多可在 YAML 层完成替换，尽量不改 Python，这样升级模板时可低成本合并。
• 善用仓库内的现成素材：仓库根目录下 examples/projects 的示例工程与 docs/2.developers/7.templates 的模板文章一一对应，是理解模板目录结构、compose 编排与 REST 接入方式的最佳对照物。