Pathway 实战：将 Jupyter Notebook 迁移到 Docker 部署的完整指南

本文以 Pathway 官方文档 Notebook-to-Docker Conversion 为核心，系统讲解如何把在 Jupyter Notebook 中交互式开发的 Pathway 数据管道，完整转换为可构建、可运行的 Docker 部署形态。读完后，你应能独立完成：编写基于 Pathway 官方镜像的 Dockerfile、将 Notebook 中的依赖安装与 shell 命令迁移到镜像构建阶段、把 .ipynb 重构为生产级 .py 脚本（含切换到 streaming 模式），以及最终的构建与运行操作。

Jupyter Notebook 与 Docker 是运行 Pathway 代码的两种互补方式：前者适合探索与交互式开发，后者适合部署。难点在于 Notebook 中 shell 命令、代码和说明文字交织在一起——尤其 !pip install、!wget 这类以感叹号开头的 shell 单元格在普通 Python 文件中无法执行，必须抽取出来交给 Docker 处理。

迁移总览：五个步骤

官方文档将转换流程归纳为五步：

1. 创建 Dockerfile：定义构建镜像的指令；
2. 在 Dockerfile 中添加依赖：声明代码所需的全部库；
3. 自定义 Dockerfile（可选）：为特定需求追加额外的 shell 命令；
4. 重构代码：移除 Notebook 特有的交互代码与 shell 命令，导出为 .py；
5. 使用 Docker 运行：构建镜像并启动容器。

下面逐步展开，每一步都会结合仓库中的真实示例与源码加以佐证。

第一步：创建 Dockerfile

Docker 部署的核心是 Dockerfile——包含 Docker 构建容器镜像所需的全部指令。Pathway 自带官方 Docker 镜像（pathwaycom/pathway），其中已包含运行框架所需的全部依赖。你只需创建一个简单的 Dockerfile，用 FROM 指定该镜像：

FROM pathwaycom/pathway:latest

COPY . .

CMD [ "python", "./your-script.py" ]

如果你的代码只使用 Pathway 本身、没有引入其他第三方库，甚至可以不需要 requirements.txt（见 Docker 部署文档 的说明）。更完整的写法会加入 WORKDIR 与依赖安装：

FROM pathwaycom/pathway:latest

# Set working directory
WORKDIR /app

# Copy requirements file and install dependencies
COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

# Copy the rest of the application code
COPY . .

# Command to run the Pathway script
CMD [ "python", "./your-script.py" ]

备选：使用标准 Python 镜像

Pathway 完全兼容 Python，也可以用标准 Python 镜像加 pip install pathway 来部署（详细文档）：

FROM --platform=linux/x86_64 python:3.10

WORKDIR /app

COPY requirements.txt ./
RUN pip install --no-cache-dir -r requirements.txt

COPY . .

CMD [ "python", "./your-script.py" ]

注意适用前提：Pathway 不支持 Windows，要求 Python 3.10+，且出于兼容性考虑应使用 x86_64 架构的 Linux 容器。仓库中真实示例 from_jupyter_to_deploy/part4_deployment/Dockerfile 采用的就是这种极简形态：

FROM python:3.11

RUN pip install pathway
COPY . .

单脚本场景：免 Dockerfile 直接运行

对于单文件项目，官方文档还提供了跳过 Dockerfile 的方式——直接挂载当前目录用官方镜像运行脚本：

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

第二步：迁移依赖到 Dockerfile

在 Jupyter Notebook 中，依赖通常通过带感叹号的单元格安装，例如安装 langchain 生态时：

!pip install langchain
!pip install langchain_community
!pip install lanchain_openai

这些行在普通 Python 文件中无法工作，必须删除并改由 Dockerfile 安装。文档给出了两种管理依赖的方案。

方案一：直接用 pip install 命令

依赖较少时，直接在 Dockerfile 中列出安装指令：

FROM pathwaycom/pathway:latest

RUN pip install langchain
RUN pip install langchain_community
RUN pip install lanchain_openai

COPY . .

CMD [ "python", "./your-script.py" ]

将示例中的包名替换为你代码实际使用的库即可。

方案二：使用 requirements.txt

依赖较多时，创建 requirements.txt 清单：

langchain
langchain_community
langchain_openai

然后更新 Dockerfile，先从该文件安装依赖再拷贝其余代码——这样依赖变更不会破坏镜像缓存：

FROM pathwaycom/pathway:latest

# Copy requirements file and install dependencies
COPY requirements.txt ./
RUN pip install -r ./requirements.txt

COPY . .

CMD [ "python", "./your-script.py" ]

按项目复杂度选择合适的方式即可。

第三步：迁移其他 shell 命令

除了依赖安装，Notebook 中还可能散落着其他 shell 命令。例如用如下单元格下载数据：

!wget -nc https://your-data-add.com/data

这一行在 Notebook 作为普通文件执行时同样会失效。正确做法是删除该行，并把命令（去掉感叹号）加入 Dockerfile：

FROM pathwaycom/pathway:latest

# Copy requirements file and install dependencies
COPY requirements.txt ./
RUN pip install -r ./requirements.txt

RUN wget -nc https://your-data-add.com/data

COPY . .

CMD [ "python", "./your-script.py" ]

注意命令已经不再带感叹号前缀。请对 Notebook 中的每一条 shell 命令重复此操作。

第四步：重构代码

从 .ipynb 导出为 .py

在 JupyterLab 中通过菜单 File -> Save and Export Notebook as... -> Executable Script 直接导出可执行脚本。

清理交互式专用代码

导出后需要：

• 删除所有仅服务于交互环境的代码（如即时可视化打印）；
• 删除全部 shell 命令行。

官方部署教程 From Jupyter to Deploy 补充了一个容易踩的坑：导出的脚本中，原 shell 单元格会被转换成 get_ipython() 开头的语句，这些行同样需要注释或移除。此外，若脚本中包含 Panel 可视化，pw.run() 需替换为在独立线程启动 Web 服务的写法：

viz_thread = viz.show(threaded=True, port=8080)

try:
    pw.run(monitoring_level=pw.MonitoringLevel.ALL)
finally:
    viz_thread.stop()

仓库中的 part4_deployment/dashboard.py 正是这样部署的，容器通过端口映射 8080:8080 暴露该 Web 服务。

（可选）从 static 切换到 streaming

若要在容器中运行流式处理而非批处理，需要三处改动：

1. 移除所有 pw.debug 引用；
2. 确认所有连接器处于 streaming 模式（可通过 mode="streaming" 显式设置）；
3. 在末尾添加 pw.run() 启动流式计算。

关于"从 static 到 streaming"的平滑过渡，Pathway 提供了 pw.demo.replay_csv 这一静态转流式的桥梁函数。从源码 python/pathway/demo/init.py 可以看到它的签名与实现：

def replay_csv(
    path: str | PathLike,
    *,
    schema: type[pw.Schema],
    input_rate: float = 1.0,
) -> pw.Table:

它内部通过 pw.io.python.read 按 input_rate（每秒读取的行数，默认 1.0）逐行回放 CSV，并用 time.sleep(1.0 / input_rate) 控制节奏。这意味着你在 Notebook 里用 pw.io.csv.read(fname, schema=schema, mode="static") 开发的逻辑，可以直接替换为 pw.demo.replay_csv(fname, schema=schema, input_rate=1000) 来验证 streaming 行为——官方教程 Part 2 正是这样从静态探索切换到实时仪表盘的（见 from_jupyter_to_deploy 教程）。

第五步：构建并运行

Dockerfile 与 Python 文件就绪后，执行构建与运行：

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

扩展：多进程/多线程并行

从 Docker 部署文档 看，Pathway 提供 pathway spawn CLI 来启动多进程/多线程作业。线程间通信更快，而重 Python 负载可能需要多进程绕过 GIL。将 CMD 替换为如下形式即可用 2 进程、3 线程运行：

CMD ["pathway", "spawn", "--processes", "2", "--threads", "3", "python", "./your-script.py"]

仓库实证：from_jupyter_to_deploy 项目

仓库中 examples/projects/from_jupyter_to_deploy 提供了一个完整的迁移范例：part1（静态探索）→ part2（streaming 仪表盘）→ part3（Kafka 接入）→ part4_deployment（Docker 部署）。其中 part4_deployment/docker-compose.yml 展示了生产化的组织方式：

• zookeeper + kafka 服务提供消息源，kafka 启动时通过 command 自动创建 tickers topic；
• dashboard 容器基于上文的最小 Dockerfile 构建，端口映射 8080:8080，用 sleep 10 && python dashboard.py 确保晚于 Kafka 启动；
• data-streamer 容器负责把 CSV 数据以流的形式写入 Kafka topic。

启动方式：

docker compose -f "docker-compose.yml" build
docker compose -f "docker-compose.yml" up

这验证了本文前述各步骤的组合形态：Notebook 代码导出为 dashboard.py / kafka-data-streamer.py，! shell 命令全部移除，依赖交给 Dockerfile，可视化改为 viz.show(threaded=True, port=8080)。

迁移自检清单

检查项	依据
所有 !pip install 已移入 Dockerfile 的 RUN 指令	本文第二步
所有其他 ! shell 命令（如 wget）已去前缀移入 Dockerfile	本文第三步
Notebook 已导出为 .py，get_ipython() 残留已清理	本文第四步
交互式专用代码（打印、临时可视化）已删除	本文第四步
streaming 场景：无 pw.debug、连接器为 mode="streaming"、末尾有 pw.run()	本文第四步
基础镜像满足约束：官方镜像，或 x86_64 Linux + Python 3.10+	Docker 部署文档
需要高吞吐时用 pathway spawn --processes N --threads M 替换 CMD	Docker 部署文档

掌握以上流程后，你在 Jupyter 中探索出的任何 Pathway 管道——无论是静态分析、流式仪表盘还是接入 Kafka 的生产管道——都能以可复现的容器形态交付。更复杂的云端部署场景可继续参阅 cloud deployment 文档。