H2O-3 Python 客户端数据接入完全指南：H2OFrame 的 CSV 导入与 Python 原生对象转换-平芜编程栈

机器学习
深度学习
AutoML
大数据
后端

【免费下载链接】h2o-3

H2O is an Open Source, Distributed, Fast & Scalable Machine Learning Platform: Deep Learning, Gradient Boosting (GBM) & XGBoost, Random Forest, Generalized Linear Modeling (GLM with Elastic Net), K-Means, PCA, Generalized Additive Models (GAM), RuleFit, Support Vector Machine (SVM), Stacked Ensembles, Automatic Machine Learning (AutoML), etc.

项目地址：https://gitcode.com/gh_mirrors/h2/h2o-3

点击查看免费下载

导读

H2O 是一个开源的分布式机器学习平台，而 H2OFrame 是 Python 客户端（h2o-py）与 H2O 集群之间数据交互的核心载体。本文以 h2o-py/docs/data.rst 为骨架，系统讲解如何通过import_file/upload_file从 CSV 等外部文件导入数据，以及如何将 tuple、list、dict、numpy.ndarray、pandas.DataFrame 等 Python 原生对象转换为 H2OFrame。读完本文，你将掌握 H2O-3 支持的文件格式与数据源、两种导入方式的选择原则、常用解析参数（表头、分隔符、列类型、缺失值、时区），以及各类 Python 对象转换的底层规则与边界情况。

H2OFrame：指向分布式数据的二维表句柄

H2OFrame 表示一个二维数据数组，其中每一列拥有统一的类型（uniformly typed）。从源码定义看（h2o-py/h2o/frame.py）：

H2OFrame is similar to pandas'DataFrame, or R'sdata.frame. One of the critical distinction is that the data is generally not held in memory, instead it is located on a (possibly remote) H2O cluster, and thusH2OFramerepresents a mere handle to that data.

也就是说：

数据本身不在 Python 进程中，而是驻留在（可能为远程的）H2O JVM 集群中，H2OFrame 只是一个对象指针（object-pointer），指向集群 DKV（Distributed Key-Value store）里的 Frame 对象；
文档中 H2OFrame、Frame、H2O Frame 三者同义，一般情况下语境都指 Python 侧视角。

数据来源有两种大类：

外部文件：从 CSV 文件加载，路径可以是 Python 客户端相对路径（client-relative）、集群相对路径（cluster-relative），也可以是一组 H2OVec 对象；
Python 原生对象：通过 H2OFrame 构造函数或from_python把内存中的 Python 数据结构传上集群。

从 CSV 文件加载数据

import_file 与 upload_file 的选择

H2O-3 提供两个入口（h2o-py/h2o/h2o.py 与 h2o-py/h2o/h2o.py）：

函数	路径语义	传输方式	适用场景
`h2o.import_file`	集群相对路径（cluster-relative）	并行/分布式多线程拉取	文件位于 HDFS、S3、URL、集群各节点共享存储上
`h2o.upload_file`	Python 客户端相对路径（client-relative）	客户端单线程推送（single-threaded push）	文件仅存在于运行 Python 的机器上

核心差异：import_file要求路径对集群中每个节点都可见，若某个节点无法访问该文件，集群会抛出异常；而upload_file先把文件从客户端 POST 上传（底层调用POST /3/PostFile，见 h2o-py/h2o/frame.py），再触发解析。如果 H2O 服务器与 Python 客户端在同一台机器上，两者行为基本一致。

import h2o h2o.init() # 方式一：import_file —— 并行、分布式导入（HDFS 路径示例） trainFrame = h2o.import_file(path="hdfs://192.168.1.10/user/data/data_test.csv") # 方式二：import_file —— 本机/共享路径 trainFrame = h2o.import_file(path="~/data/data_test.csv") # 方式三：upload_file —— 仅存在于 Python 进程本地的文件 iris_df = h2o.upload_file("~/Desktop/repos/h2o-3/smalldata/iris/iris.csv")

注意两点路径细节（源码中已体现）：

upload_file支持~展开：代码会先os.path.expanduser(path)处理波浪号（h2o-py/h2o/h2o.py）；
import_file不支持~相对路径，因为该路径由服务器端解释，代码会直接抛出H2OValueError："Paths relative to a current user (~) are not valid in the server environment. Please use absolute paths if possible."（h2o-py/h2o/h2o.py）。

import_file还有一个懒加载变体：当parse=False时只做导入不解析，返回文件路径列表，其底层通过h2o.lazy_import(path, pattern)调用POST /3/ImportFilesMulti（h2o-py/h2o/h2o.py）。

支持的文件格式与数据源

H2O 的解析器（parser）支持多种格式，来源可以是本地文件、分布式存储或 URL：

支持的文件格式：

ARFF
CSV（数据可由 128 个 ASCII 字符中的任意字符分隔，含 GZipped CSV 支持）
SVMLight
XLS
XLSX
ORC（用于 Hadoop 任务，支持以 ORC 格式保存的 Hive 文件）
Avro 1.8.0 版本（不支持多文件解析与列类型修改）
Parquet

支持的数据源：

NFS / 本地文件 / 文件列表
HDFS
URL
目录（其中包含多个数据文件时要求位于同一层级——不支持递归导入）
S3 / S3N
原生语言数据结构（见下文 Python 对象转换章节）
Google Storage（gs://）

常用解析参数详解

import_file与upload_file共享一套解析参数，源码 docstring 给出了完整定义（h2o-py/h2o/h2o.py）：

header：-1表示第一行是数据，0（默认）表示让 H2O 自动猜测，1表示第一行是表头；
sep：字段分隔符字符，不提供时解析器自动检测；类型断言要求为长度 1 的字符串（assert_is_type(sep, None, I(str, lambda s: len(s) == 1))）；
col_names：列的显式名称列表；
col_types：列类型列表或{列名: 类型}字典。可选值包括：

类型关键字	含义
`"unknown"`	强制整列解析为全 NA
`"uuid"`	列值必须是真正的 UUID，否则解析为 NA
`"string"`	强制解析为字符串
`"numeric"`	强制解析为数值，H2O 会自动选择最优压缩方式
`"enum"`	强制解析为类别（categorical）列
`"time"`	强制解析为时间列，支持`yyyy-MM-dd`、`dd-MMM-yy`、`HH:mm:ss`、`HH.mm.ss`等日期时间格式，且可包含`AM`/`PM`
`"int"`/`"float"`/`"long"`等	数值类型的细化指定

na_strings：需要被解释为缺失值的字符串，可以是字符串列表、按列区分的列表的列表（list of lists），或{列名: 缺失串列表}字典；
skipped_columns：整数列表，指定导入文件中要被跳过、不解析进最终 Frame 的列索引；
force_col_types：若为True，强制列类型为 Parquet schema 或column_types指定的类型（主要作用于数值列），默认False；
custom_non_data_line_markers（仅import_file）：以给定字符串中任一字符开头的行将不会被导入。空字符串表示导入所有行，None表示采用该格式的默认行为；
pattern（仅import_file）：当path是目录时，用于匹配其中文件的正则表达式；
partition_by（仅import_file）：持久化数据集按其进行分区（partitioned）的列名；
quotechar：期望的引号字符提示，仅允许单引号'、双引号"或None（默认，自动检测）；
escapechar：（可选）用于转义其他字符的一个 ASCII 字符；
tz_adjust_to_local（仅import_file）：是否将导入数据的时间从 GMT 调整到集群时区。

时区语义：没有时区的时间戳按 UTC 解析

重要提示：当解析的数据文件包含不带时区的时间戳时，H2O 会将其解释为UTC（GMT）。可以通过h2o.cluster().timezone覆盖解析时区：

h2o.cluster().timezone = "America/Los_Angeles"

该属性在 h2o-py/h2o/backend/cluster.py 中实现：读取时通过(getTimeZone)Rapid 表达式查询集群时区，设置时通过(setTimeZone "%s")写入；list_timezones()则返回 H2O 已知的全部时区列表。另外集群健康状态中同时维护了H2O_cluster_timezone与H2O_data_parsing_timezone两个字段，分别对应集群运行与数据解析两个时区上下文。

从 Python 对象加载数据

要把 Python 数据结构中的数据传输到 H2O，使用H2OFrame 构造函数与python_obj参数；from_python功能相同，但提供更多解析选项。需要说明的是，在当前仓库中from_python已标记为[DEPRECATED]（h2o-py/h2o/frame.py），建议直接使用构造函数H2OFrame(...)。

允许的 python_obj 类型与校验

python_obj允许以下类型（在构造函数中通过isinstance检查，h2o-py/h2o/frame.py）：

tuple()
list[]
dict{}
collections.OrderedDict
numpy.ndarray
pandas.DataFrame
（源码还支持scipy.sparse稀疏矩阵，见 h2o-py/h2o/frame.py）

如果类型不在上述范围内（例如 set、byte array 等），会抛出ValueError。

从底层实现看（h2o-py/h2o/frame.py），Python 对象会被一个"处理器"（handler）先转换成(表头, 数据)结构，再写入一个临时 CSV 文件，最终通过_upload_python_object上传并触发解析。这解释了为什么各类对象的转换规则最终都收敛到"列表的列表（list of lists）"这一统一表示上。

下文讨论每种数据类型的"源表示"（Python 对象）与"目标表示"（H2O 对象），重点覆盖：表头（Headers）、数据类型（Data Types）、行数（Number of Rows）、列数（Number of Columns）、缺失值（Missing Values）。

加载 Python Tuple（元组）

本质而言，tuple 是不可变 list。但这一不可变性不会映射到 H2OFrame 上——生成后的 Frame 是可变的，Python 使用者务必注意。

tuple 的格式为(i1, i2, i3, ..., iN)，N为该列的行数。限制主要落在单个元素iJ的类型上：

若某个iJ是{}（dict），抛出ValueError；
若某个iJ是()或[]，则所有iJ都必须是()或[]，否则抛出ValueError——即不允许混合类型；
只允许单层嵌套：如果iJ是()或[]，且其内部还包含()或[]，抛出ValueError；
若iJ不是()或[]，则必须是 string 或非复数数值类型（float 或 int）；否则抛出ValueError。

可接受的输入示例：

# Example A：单列，3 行 (1, 2, 3) # Example B：3 列（tuple 内嵌 tuple） ((1, 2, 3), (4, 5, 6), ("cat", "dog")) # Example C：tuple 内混合 () 与 [] —— 完全允许 ((1, 2, 3), [4, 5, 6], ["blue", "yellow"], (321.239, "green", "hi")) # Example D：单列，3 行（混合数值与字符串） (3284.123891, "dog", 89)

生成的 H2OFrame 形态：

无嵌套数组（Example A、D）：形状为len(tuple) × 1，即单列 Frame；
有嵌套数组（Example B、C）：列数等于嵌套数组的个数，行数等于最长的子数组：

len(tuple) × max([len(l) for l in tuple])

这一规则天然处理了"参差不齐（ragged）"的子数组——较短的子数组会在末尾以 NA（缺失值）补齐到正确长度。

表头：tuple/list 场景无法指定表头行，H2O 自动生成C1, C2, C3, ..., CN格式的列名。注意这些列名采用1-based 索引（第 0 列叫 "C1"）。

加载 Python List（列表）

适用于 tuple 的原则同样适用于 list。list 是可变对象，因此 H2OFrame 与 list 之间不存在元组那样关于可变性的语义差异。list 的排序方式与 tuple 相同，数据写在方括号内：

frame = h2o.H2OFrame([1, 2, 2.5, -100.9, 0]) # 单列 5 行 frame = h2o.H2OFrame([[1, 'a'], [2, 'b'], [3, 'c']]) # 3 行 2 列，一列数值一列字符串

列表的底层处理由_handle_python_lists完成（h2o-py/h2o/frame.py）：若是"列表的列表"则校验每个内层必须为扁平列表并取最长长度作为列数；若是普通 list/tuple 则视为单列逐元素包装；标量则视为单行单列。header=1时把第一行当作表头并从数据中剥离，否则调用gen_header生成C1..CN。

加载 Python Dict 或 collections.OrderedDict

{}中的每个键值对代表一列。规则如下：

键（列名）必须是字符串，且匹配正则^[a-zA-Z_][a-zA-Z0-9_.]*$：以字母（大小写均可）或_开头，后面跟任意数量的字母、数字、_或.，长度不限（源码中的正则校验见 h2o-py/h2o/frame.py）；
值可以是扁平[]、扁平()，或单个 int、float、string。嵌套的[]/()会抛出ValueError（_handle_python_dicts中会逐值检查并抛出"Values in the dictionary must be flattened!"）；
列序注意：内置dict不保证顺序，因此生成的 H2OFrame 列顺序可能与插入顺序不一致；collections.OrderedDict会保留键值对的插入顺序。

from collections import OrderedDict # 普通 dict —— 列顺序不保证 h2o.H2OFrame({"sepal_len": [5.1, 4.9], "species": ["setosa", "virginica"]}) # OrderedDict —— 保留列顺序 ordered = OrderedDict([("num1", [1, 2, 3]), ("str1", ["a", "b", "c"])]) h2o.H2OFrame(ordered)

加载 numpy.ndarray 或 pandas.DataFrame

numpy.ndarray：一维或二维 ndarray 都可以转换为 H2OFrame。实现上直接调用 ndarray 的tolist()方法（h2o-py/h2o/frame.py），然后套用 list 的转换规则；
pandas.DataFrame：实现上调用 DataFrame 的values方法得到 ndarray，再走 ndarray → list 的转换链（h2o-py/h2o/frame.py）。注意_handle_pandas_data_frame会把 pandas 的columns转为字符串作为表头，并把数据按header=-1处理（即不再把首行当表头）。

import numpy as np import pandas as pd frame = h2o.H2OFrame(python_obj=np.random.randint(-5, 5, (3, 4))) df = pd.DataFrame({"a": [1, 2, 3], "b": ["x", "y", "z"]}) frame = h2o.H2OFrame(python_obj=df)

转换中的两个通用注意点

列类型统一：由于 Frame 每列类型统一，在同一列内混用类型可能导致意料之外的结果（列类型由 H2O parser 按混合列规则推断）。如果对列类型有明确要求，建议使用构造函数 /from_python的column_types参数显式指定，例如：

frame = h2o.H2OFrame( python_obj=[[1, 2, 3], [4, 5, 6], ["a", "b", "c"], [1, 0, 1]], column_names=["num1", "num2", "str1", "enum1"], column_types=["numeric", "numeric", "string", "enum"], na_strings=["NA"], )

空数据检查：若转换结果没有表头或没有数据（col_header is None or data_to_write is None），会抛出H2OValueError("No data to write")（h2o-py/h2o/frame.py）。

设置 S3 凭据

当数据源位于 Amazon S3 且需要认证访问时，h2o.persist.persist模块提供凭据管理 API（h2o-py/h2o/persist/persist.py）：

from h2o.persist import set_s3_credentials, remove_s3_credentials # 设置 S3 凭据（内部创建 S3 client） set_s3_credentials(secret_key_id="YOUR_KEY_ID", secret_access_key="YOUR_SECRET_KEY") # 使用 AWS 临时凭据时，额外传入 session_token set_s3_credentials(secret_key_id="...", secret_access_key="...", session_token="...") # 移除此前设置的凭据（不影响实例变量或其他凭据来源） remove_s3_credentials()

要点：

set_s3_credentials内部调用POST /3/PersistS3，不做任何凭据有效性校验——错误的凭据会在第一次 S3 导入调用时才暴露；
若secret_key_id或secret_access_key为None或空字符串，会抛出H2OValueError；
session_token为可选参数，仅在使用 AWS 临时凭据时需要；
remove_s3_credentials内部调用DELETE /3/PersistS3，只移除通过set_s3_credentials传入的凭据，不影响环境变量或其他凭据来源。

设置完凭据后，即可直接以s3:///s3n://前缀路径调用h2o.import_file导入数据。

常见问题与最佳实践小结

选对导入方式：文件在集群可见（HDFS/S3/URL/共享目录）用import_file获得并行导入性能；文件只在本机用upload_file单线程上传。import_file不要使用~相对路径。
表头与分隔符：不确定时使用header=0（自动猜测）与默认sep=None（自动检测）；CSV 还支持 GZip 压缩。
列类型显式声明：遇到混合类型列、时间列、UUID 列，使用col_types显式指定，避免解析器推断带来的意外；需要跳过某些列时用skipped_columns。
缺失值语义：用na_strings声明你数据中的缺失标记；短列（ragged 子数组）在转换时会在末尾自动以 NA 补齐。
时区一致性：无时区的时间戳默认按 UTC 解释，务必用h2o.cluster().timezone设置与你业务一致的时区；对文件导入还可利用tz_adjust_to_local。
Python 对象转换的边界：tuple/list 只允许单层嵌套且不可混用嵌套与非嵌套；dict 键必须匹配^[a-zA-Z_][a-zA-Z0-9_.]*$，需要稳定列序时使用OrderedDict；ndarray 与 DataFrame 最终都走 list 规则。
权限与凭据：S3 私密数据先set_s3_credentials再导入；凭据错误不会在设置时报错，而是在首次导入时暴露。

深入源码：本文涉及的底层调用链均可回溯到 h2o-py/h2o/frame.py（_upload_python_object、_import_parse、_upload_parse、_parse_raw）、h2o-py/h2o/h2o.py（import_file、upload_file、lazy_import、parse_setup）与 h2o-py/h2o/backend/cluster.py（timezone）。仓库中大量测试用例（如 h2o-py/tests/testdir_parser 下的解析类测试）也验证了上述格式与参数行为。