Sparkling Water

|mvn-badge| |apache-2-0-license| |由 H2O.ai 提供支持|

Sparkling Water 将 H2O-3 <https://github.com/h2oai/h2o-3/>__ 这一快速可扩展的机器学习引擎与 Apache Spark <https://spark.apache.org/>__ 集成。它提供了：

• 用于将 Spark 数据结构（RDD、DataFrames、Datasets）发布为 H2O-3 的数据帧，反之亦然的工具。
• 一种 DSL，允许将 Spark 数据结构用作 H2O 算法的输入。
• 构建基于 Spark 和 H2O API 的机器学习应用的基本组件。
• Python 接口，使用户可以直接从 PySpark 中使用 Sparkling Water。

开始使用

用户文档

`阅读 Spark 3.5 版本的文档 <http://docs.h2o.ai/sparkling-water/3.5/latest-stable/doc/index.html>`__（或
`3.4 <http://docs.h2o.ai/sparkling-water/3.4/latest-stable/doc/index.html>`__，
`3.3 <http://docs.h2o.ai/sparkling-water/3.3/latest-stable/doc/index.html>`__，
`3.2 <http://docs.h2o.ai/sparkling-water/3.2/latest-stable/doc/index.html>`__，
`3.1 <http://docs.h2o.ai/sparkling-water/3.1/latest-stable/doc/index.html>`__，
`3.0 <http://docs.h2o.ai/sparkling-water/3.0/latest-stable/doc/index.html>`__，
`2.4 <http://docs.h2o.ai/sparkling-water/2.4/latest-stable/doc/index.html>`__，
`2.3 <http://docs.h2o.ai/sparkling-water/2.3/latest-stable/doc/index.html>`__）

下载二进制文件

下载适用于 Spark 3.5 的最新版本 <http://h2o-release.s3.amazonaws.com/sparkling-water/spark-3.5/latest.html>（或 3.4 <http://h2o-release.s3.amazonaws.com/sparkling-water/spark-3.4/latest.html>， 3.3 <http://h2o-release.s3.amazonaws.com/sparkling-water/spark-3.3/latest.html>， 3.2 <http://h2o-release.s3.amazonaws.com/sparkling-water/spark-3.2/latest.html>， 3.1 <http://h2o-release.s3.amazonaws.com/sparkling-water/spark-3.1/latest.html>， 3.0 <http://h2o-release.s3.amazonaws.com/sparkling-water/spark-3.0/latest.html>， 2.4 <http://h2o-release.s3.amazonaws.com/sparkling-water/spark-2.4/latest.html>， 2.3 <http://h2o-release.s3.amazonaws.com/sparkling-water/spark-2.3/latest.html>）

每个 Sparkling Water 发布版本也会被发布到 Maven Central（详情见下文）。

---

尝试 Sparkling Water！

Sparkling Water 以 Spark 应用程序库的形式分发，任何 Spark 应用程序都可以使用它。此外，我们还提供了一个包含库和 Shell 脚本的 ZIP 分发包。

有几种使用 Sparkling Water 的方式：

• Sparkling Shell（内置 Sparkling Water 的 Spark Shell）
• Sparkling Water 驱动程序（内置 Sparkling Water 的 Spark Submit）
• 使用 Spark Shell 并通过 --jars 或 --packages 选项引入 Sparkling Water 库
• 使用 Spark Submit 并通过 --jars 或 --packages 选项引入 Sparkling Water 库
• PySpark 结合 PySparkling

运行 Sparkling Shell

Sparkling Shell 封装了普通的 Spark Shell，并通过 ``--jars`` 选项将 Sparkling Water 库添加到类路径中。Sparkling Shell 支持创建 H2O-3 集群并执行 H2O-3 算法。

1. 下载或构建 Sparkling Water。
2. 配置 Spark 集群的位置：

   .. code:: bash

      export SPARK_HOME="/path/to/spark/installation"
      export MASTER="local[*]"


   在这种情况下，``local[*]`` 指向一个嵌入式的单节点集群。
   
3. 运行 Sparkling Shell：

   .. code:: bash

      bin/sparkling-shell

   Sparkling Shell 接受常见的 Spark Shell 参数。例如，要增加每个 executor 分配的内存，可以使用 ``spark.executor.memory`` 参数：``bin/sparkling-shell --conf "spark.executor.memory=4g"``

4. 初始化 H2OContext

   .. code:: scala

      import ai.h2o.sparkling._
      val hc = H2OContext.getOrCreate()

   ``H2OContext`` 会在 Spark 集群之上启动 H2O 服务，并提供在 H2O-3 和 Spark 数据结构之间进行转换的原语。


在 PySpark 中使用 Sparkling Water

Sparkling Water 也可以直接从 PySpark 中使用，这种集成被称为 PySparkling。

请参阅 PySparkling README <http://docs.h2o.ai/sparkling-water/3.5/latest-stable/doc/pysparkling.html>__ 了解有关 PySparkling 的更多信息。

通过 Spark Packages 使用 Sparkling Water

要了解如何将 Sparkling Water 作为 Spark 包使用，请参阅 `作为 Spark 包使用 <http://docs.h2o.ai/sparkling-water/3.5/latest-stable/doc/tutorials/use_as_spark_package.html>`__。

在 Windows 环境中使用 Sparkling Water

请参阅 Windows 教程 <http://docs.h2o.ai/sparkling-water/3.5/latest-stable/doc/tutorials/run_on_windows.html>__，了解如何在 Windows 环境中使用 Sparkling Water。

Sparkling Water 示例

要查看如何运行 Sparkling Water 的示例，请参阅 `运行示例 <http://docs.h2o.ai/sparkling-water/3.5/latest-stable/doc/devel/running_examples.html>`__。

Maven 包
~~~~~~~~~~~~~~

每个 Sparkling Water 发布版本都会被发布到 Maven Central，坐标如下：

- ``ai.h2o:sparkling-water-core_{{scala_version}}:{{version}}`` - 包含 Sparkling Water 核心
- ``ai.h2o:sparkling-water-examples_{{scala_version}}:{{version}}`` - 包含示例应用程序
- ``ai.h2o:sparkling-water-repl_{{scala_version}}:{{version}}`` - 将 Spark REPL 集成到 H2O Flow UI 中
- ``ai.h2o:sparkling-water-ml_{{scala_version}}:{{version}}`` - 基于 H2O 的转换扩展了 Spark ML 包
- ``ai.h2o:sparkling-water-scoring_{{scala_version}}:{{version}}`` - 包含评分逻辑和 Sparkling Water MOJO 模型定义的库。
- ``ai.h2o:sparkling-water-scoring-package_{{scala_version}}:{{version}}`` - 轻量级 Sparkling Water 包，仅包含使用 H2O-3 和 DAI MOJO 模型进行评分所需的依赖项。
- ``ai.h2o:sparkling-water-package_{{scala_version}}:{{version}}`` - 包含模型训练和评分所需所有依赖项的 Sparkling Water 包。此包设计用于通过 ``--packages`` 选项作为 Spark 包使用。

   **注意：** ``{{version}}`` 指的是 Sparkling Water 的发布版本，而 ``{{scala_version}}`` 指的是 Scala 的基础版本。

已发布的完整包列表可在
`这里 <http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22ai.h2o%22%20AND%20a%3Asparkling-water*>`__ 查看。

--------------

Sparkling Water 后端
------------------------

Sparkling Water 支持两种后端/部署模式——内部和外部。Sparkling Water 应用程序与所选后端无关。可以在创建 ``H2OContext`` 之前指定后端。

有关内部或外部后端的更多详细信息，请参阅
`后端 <http://docs.h2o.ai/sparkling-water/3.5/latest-stable/doc/deployment/backends.html>`__。

--------------

常见问题解答
---

所有常见问题的列表可在 `FAQ <http://docs.h2o.ai/sparkling-water/3.5/latest-stable/doc/FAQ.html>`__ 中找到。

--------------

开发
-----------

完整的开发文档可在 `开发文档 <http://docs.h2o.ai/sparkling-water/3.5/latest-stable/doc/devel/devel.html>`__ 中查阅。

构建 Sparkling Water
~~~~~~~~~~~~~~~~~~~~~

如需了解如何构建 Sparkling Water，请参阅 `构建 Sparkling Water <http://docs.h2o.ai/sparkling-water/3.5/latest-stable/doc/devel/build.html>`__。

使用 Sparkling Water 开发应用程序

使用 Sparkling Water 的应用程序本质上是常规的 Spark 应用程序，只需将 Sparkling Water 库打包进去即可。Sparkling Water 提供了一个示例应用的 Droplet，详情请见 此处 <https://github.com/h2oai/h2o-droplets/tree/master/sparkling-water-droplet>__。

贡献

只需向我们提交一个 Pull Request 即可！您可以参考我们的 `问题列表 <https://github.com/h2oai/sparkling-water/issues/new/choose>`__ 获取灵感，也可以随时创建一个新的问题。

提交 Bug 报告和功能请求

您可以在 GitHub Issues 中直接提交 Bug 报告或功能请求：GitHub Issues <https://github.com/h2oai/sparkling-water/issues/new/choose>__。

有疑问吗？

我们也会在 `Stack Overflow <https://stackoverflow.com/questions/tagged/sparkling-water>`__ 上回复带有 sparkling-water 和 h2o 标签的问题。

变更日志
~~~~~~~~~~~

变更日志可在 `变更日志 <http://docs.h2o.ai/sparkling-water/3.5/latest-stable/doc/CHANGELOG.html>`__ 中查看。

---------------

.. |加入 https://gitter.im/h2oai/sparkling-water 的聊天室| image:: https://badges.gitter.im/Join%20Chat.svg
   :target: https://gitter.im/h2oai/sparkling-water?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge
.. |mvn-badge| image:: https://maven-badges.herokuapp.com/maven-central/ai.h2o/sparkling-water-core_2.12/badge.svg
   :target: http://search.maven.org/#search%7Cgav%7C1%7Cg:%22ai.h2o%22%20AND%20a:%22sparkling-water-core_2.12%22
.. |apache-2-0-license| image:: https://img.shields.io/badge/License-Apache%202-blue.svg
   :target: LICENSE
.. |由 H2O.ai 提供支持| image:: https://img.shields.io/badge/powered%20by-h2oai-yellow.svg
   :target: https://github.com/h2oai/

Sparkling Water 快速上手指南

Sparkling Water 将高性能机器学习引擎 H2O-3 与大数据处理框架 Apache Spark 无缝集成。它允许开发者在 Spark 生态中直接使用 H2O 的算法，并实现 Spark 数据结构（RDD/DataFrame）与 H2O Frame 之间的双向转换。

1. 环境准备

在开始之前，请确保您的开发环境满足以下要求：

• Java: JDK 8 或更高版本。
• Apache Spark: 已安装并配置好 Spark 集群（支持 Standalone, YARN, Mesos 或本地模式）。
  • 注意：请下载与您 Spark 版本对应的 Sparkling Water 版本（如 Spark 3.5 对应 Sparkling Water for Spark 3.5）。
• Scala/Python:
  • Scala 用户：需匹配 Spark 对应的 Scala 版本（通常为 2.12 或 2.13）。
  • Python 用户：需安装 pyspark 和 h2o Python 包。

前置依赖检查： 确保环境变量 SPARK_HOME 已正确指向 Spark 安装目录。

export SPARK_HOME="/path/to/spark/installation"

2. 安装步骤

您可以通过以下两种主要方式使用 Sparkling Water：直接下载二进制包或使用 Maven/SBT 依赖管理。

方式一：下载二进制包（推荐用于快速试用）

访问官方发布页面下载与您 Spark 版本匹配的最新压缩包：

• Spark 3.5: 下载链接
• Spark 3.4: 下载链接
• (其他版本请访问 H2O 官方文档获取对应链接)

下载后解压即可使用内置的脚本。

方式二：通过 Maven 坐标引入（用于项目开发）

如果您使用 Maven 构建项目，请在 pom.xml 中添加以下依赖（以 Spark 3.5 和 Scala 2.12 为例）：

<dependency>
    <groupId>ai.h2o</groupId>
    <artifactId>sparkling-water-package_2.12</artifactId>
    <version>3.40.0.1-1-3.5</version> <!-- 请替换为最新具体版本号 -->
</dependency>

或者在提交任务时通过 --packages 参数动态加载：

--packages ai.h2o:sparkling-water-package_2.12:3.40.0.1-1-3.5

3. 基本使用

场景 A：使用 Sparkling Shell (Scala)

这是最快速的体验方式，内置了 Spark Shell 并自动加载了 Sparkling Water 库。

1. 配置运行模式（以本地模式为例）：

   export MASTER="local[*]"
   

2. 启动 Sparkling Shell： 进入解压后的目录，执行：

   bin/sparkling-shell
   

   提示：如需增加 Executor 内存，可添加参数：bin/sparkling-shell --conf "spark.executor.memory=4g"

3. 初始化 H2O 上下文： 在 Scala REPL 中输入以下代码启动 H2O 服务并连接 Spark：

   import ai.h2o.sparkling._
   val hc = H2OContext.getOrCreate()
   

   成功初始化后，您即可将 Spark DataFrame 转换为 H2O Frame 并调用 H2O 算法。

场景 B：在 PySpark 中使用 (PySparkling)

Python 用户可以通过 pysparkling 直接在 PySpark 环境中使用。

1. 安装 Python 依赖：

   pip install h2o pysparkling
   

2. 编写 Python 脚本 (example.py)：

   from pyspark.sql import SparkSession
   from pysparkling import H2OContext
   import h2o
   
   # 1. 创建 Spark Session
   spark = SparkSession.builder.appName("SparklingWaterDemo").getOrCreate()
   
   # 2. 初始化 H2OContext
   hc = H2OContext.getOrCreate(spark)
   
   # 3. 创建示例数据并转换为 H2O Frame
   data = [(1, 2.0), (2, 3.0), (3, 4.0)]
   df = spark.createDataFrame(data, ["id", "value"])
   
   # Spark DataFrame -> H2O Frame
   h2o_frame = hc.as_h2o_frame(df)
   
   print(h2o_frame.head())
   
   # 4. 运行 H2O 算法 (例如：GBM)
   from h2o.estimators.gbm import H2OGradientBoostingEstimator
   gbm = H2OGradientBoostingEstimator()
   # 注意：实际训练需要指定 x, y 列，此处仅为演示流程
   # gbm.train(x=["value"], y="id", training_frame=h2o_frame) 
   
   # 关闭上下文
   hc.stop()
   

3. 提交运行：

   spark-submit --packages ai.h2o:sparkling-water-package_2.12:3.40.0.1-1-3.5 example.py
   

   (请根据实际环境调整 package 坐标和版本)

---

注：生产环境中建议根据集群规模选择 Internal（内部）或 External（外部）后端模式，详细配置请参考官方部署文档。