• 人工智能
• 机器学习
• 后端
• 编译器

SQLFlow 是连接 SQL 与人工智能的翻译器，它把标准的 SQL 程序编译为分布式机器学习任务，但完整运行需要 MySQL、SQLFlow Server、Jupyter Notebook 以及海量的训练镜像等组件。为了免去繁琐的环境配置，官方把全部依赖打包成虚拟机镜像（VM Box），本文基于 doc/sqlflow.org_cn/install_sqlflow_vm_box.cn.md 展开，详细讲解镜像选择、VirtualBox 导入、登录启动与问题排查的完整流程，并深入剖析镜像内部的组件构成与启动原理，帮助你在一台普通电脑上最快跑通 SQLFlow 的「训练—预测—解释」全链路。

为什么选择 VM Box：把复杂依赖封装成一台虚拟机

SQLFlow 的运行依赖大量组件。从仓库的 docker 目录可以看出，一套可运行的 SQLFlow 环境至少包含：

• MySQL 数据库容器：内置样例数据集，负责存放训练数据与模型（docker/mysql/Dockerfile）；
• SQLFlow Server 容器：提供 gRPC 服务，解析 SQL 程序并生成训练、预测、解释任务（docker/server/Dockerfile）；
• Jupyter Notebook 容器：提供用户交互界面与%%sqlflowmagic 命令插件（docker/jupyter/Dockerfile）；
• step 容器：工作流中真正执行每一步的二进制（docker/step/Dockerfile）。

自行组装这些容器并处理版本、网络、镜像加速问题并不轻松。VM Box 方案将这些全部预装到一台虚拟机镜像里，用户只需安装 Oracle VirtualBox、导入一个.ova镜像文件并双击启动，即可获得开箱即用的 SQLFlow 体验环境。这是除 在 Kubernetes 中安装 SQLFlow、使用 Docker 运行 SQLFlow 之外的第三条、也是最省心的本地安装路径。

安装准备：VirtualBox 与镜像版本选择

安装 VirtualBox

在 VirtualBox 官网 下载并安装 VirtualBox，官方推荐v6.1.6 版本。VirtualBox 是跨平台的免费虚拟机软件，支持 Windows、macOS 与主流 Linux 发行版，它负责加载、运行和管理后续导入的 SQLFlow 虚拟机镜像。

两种镜像版本对比

SQLFlow 提供两个预置镜像，两者的差别在于是否携带运行所需的 Docker 镜像：

镜像下载地址如下：

http://cdn.sqlflow.tech/latest/SQLFlowPlaygroundBare.ova http://cdn.sqlflow.tech/latest/SQLFlowPlaygroundFull.ova

建议：如果所在网络拉取 Docker Hub 镜像较慢，直接选择完整版，避免首次启动时长时间等待镜像下载。

完整安装步骤

第一步：导入虚拟机镜像

1. 启动 VirtualBox；
2. 点击菜单管理 -> 导入虚拟机；
3. 选择下载好的.ova文件；
4. 等待导入完成，在虚拟机列表中双击该镜像启动虚拟机。

.ova是 VirtualBox 标准的虚拟机打包格式，一个文件即包含虚拟磁盘、硬件配置与系统镜像，导入后无需再做任何手工配置。

第二步：登录虚拟机

虚拟机启动后，在窗口中以默认账号密码登录：

账号：root 密码：sqlflow

如果你熟悉 shell 工具，也可以在宿主机上通过 SSH 登录（虚拟机默认将宿主机的 2222 端口映射到虚拟机的 SSH 端口）：

ssh -p2222 root@127.0.0.1 root@127.0.0.1's password: sqlflow

第三步：运行启动脚本

登录后，在root用户的主目录下可以看到一个start.bash脚本，运行它即可启动 SQLFlow 系统：

./start.bash

第四步：访问 SQLFlow 用户界面

运行启动脚本后会输出一系列日志，当出现类似下面的提示时，说明系统已经启动完成：

Access Jupyter NoteBook at: http://127.0.0.1:8888/...

在浏览器中打开该链接，即可进入 SQLFlow 的 Jupyter Notebook 用户界面，从中选择一个教程案例（例如鸢尾花分类、泰坦尼克号生存预测）开始运行。

深入理解：VM Box 启动时发生了什么

虽然对用户来说只是双击 + 一个脚本，但理解启动过程有助于排查问题。VM Box 镜像本质上把 docker/mysql/start.bash 的初始化逻辑与三个核心容器打包在了一起：

1. 数据库初始化与数据集灌入

镜像内的 MySQL 首次启动时会执行初始化：创建root用户、启动mysqld服务，并循环执行/datasets目录下的所有 SQL 文件，将官方样例数据集批量写入数据库：

echo "Populate datasets ..." for f in /datasets/*; do mysql -uroot -proot < "$f" done

这些数据集脚本位于仓库的 doc/datasets 目录，包括popularize_iris.sql（鸢尾花）、popularize_titanic.sql（泰坦尼克号）、popularize_churn.sql（用户流失）、popularize_boston.sql（波士顿房价）等。启动脚本还会在工作目录写入mysql-inited标记文件，供外部脚本探测初始化是否完成。

2. Jupyter 与 SQLFlow magic 插件

Jupyter 容器内置了 SQLFlow 的 Jupyter 扩展。从 docker/jupyter/install-jupyter.sh 可以看到，镜像在 IPython 启动目录中写入了自动加载逻辑，用户打开 Notebook 即可直接使用%%sqlflowmagic 命令：

get_ipython().magic(u"%reload_ext sqlflow.magic")

同时镜像还安装了 SQLFlow 的 SQL 语法高亮插件（docker/jupyter/js/sqlflow.js），并预置了教程 Notebook 到/workspace目录，这就是你在网页端能看到案例列表的原因。

3. SQLFlow Server 的 gRPC 服务

镜像内的 SQLFlow Server 通过 50051 端口对外提供 gRPC 服务（见 docker/server/Dockerfile 中的EXPOSE 50051）。Jupyter 中的 SQL 语句经由 SQLFlow magic 客户端发送到 Server，由 Server 完成 SQL 解析、中间表示生成与训练/预测/解释任务的编排，这与 SQLFlow 开发入门指引 中描述的「客户端（Jupyter / CLI）— gRPC — SQLFlow Server — 工作流执行」架构完全一致。

安装后的体验路径

环境启动后，你可以按照 快速开始 的指引，在 Notebook 中运行预置案例。推荐的入门路线包括：

• 泰坦尼克号沉船生存预测：完整演示TO TRAIN、TO PREDICT、TO EXPLAIN三类扩展 SQL 语法；
• 信用卡欺诈分析：基于 DNN 的二分类实战；
• 若更习惯命令行，可参考 SQLFlow 命令行工具使用手册 使用sqlflow命令执行同样的语句。

案例中使用的数据集与 SQL 导入脚本均可在仓库的 doc/datasets 目录中找到，例如popularize_titanic.sql。

常见问题排查

1. Docker 镜像下载速度慢

精简版首次启动需要在线拉取运行所需的 Docker 镜像，网络不佳时耗时较长。解决办法有两个：

• 更换 Docker 镜像源为国内加速地址；
• 直接下载完整版（SQLFlowPlaygroundFull.ova），运行时无需再下载镜像。

2. start.bash 脚本异常退出

这通常是由于下载 Docker 镜像超时引起，并非环境损坏。直接重新运行启动脚本即可：

./start.bash

脚本会基于已有的缓存继续执行，多次重跑不影响结果。

3. 脚本正常退出，但无法访问 Web 界面

这种情况多半是相关容器尚在启动中（例如 MySQL 初始化或镜像加载尚未完成）。稍等片刻后重新运行start.bash，待日志出现Access Jupyter NoteBook at: http://127.0.0.1:8888/...提示再访问浏览器。

更多安装方式

VM Box 适合单机快速体验；如果你的场景不同，官方还提供了另外两种安装路径：

• Docker 方式：直接拉取sqlflow/sqlflow、sqlflow/sqlflow:mysql、sqlflow/sqlflow:jupyter三个镜像启动容器，详见 Run SQLFlow Using Docker；
• Kubernetes 方式：基于 MiniKube + Argo Workflows 部署单人或多人模式，支持 GitHub OAuth 登录与 HTTPS，适合多人共享或生产原型，详见 在 Kubernetes 中安装 SQLFlow。

三种方式最终提供的都是同一套 SQLFlow 服务与 Jupyter 交互界面，VM Box 的优势在于把所有依赖（含 Docker 镜像）一次性封装，真正做到「下载一次，随处运行」。

• 人工智能
• 机器学习
• 后端
• 编译器