sap-hana-ml

SAP HANA ML Python 客户端（hana-ml）

相关技能

• sap-dependency-security：用于在与 HANA ML 技术栈配合使用的 Python／辅助工具中安全地固定依赖项和执行升级工作流

何时使用此技能

在使用 hana-ml Python 客户端构建机器学习工作流、使用 PAL/APL 算法、查询 HANA DataFrame、在数据库内训练或评分模型、使用 AutoML、可视化模型输出，或排查 Python 与 HANA ML 之间的连接问题时，请使用此技能。

常见问题

问题	首要检查项
连接失败	检查 HANA 主机、端口、TLS／加密设置、用户权限和网络允许列表。
缺少 PAL/APL 算法	确认 HANA 系统已安装并获得所需 AFL/PAL/APL 库的许可。
DataFrame 收集速度慢	将筛选和投影操作下推到 HANA，并避免将大型数据帧收集到 Python 中。

软件包版本：2.22.241011
最后验证时间：2025-11-27

目录

• 安装与设置
• 快速入门
• 核心库
• 常见模式
• 最佳实践
• 捆绑资源

---

安装与设置

pip install hana-ml

要求：Python 3.8+、SAP HANA 2.0 SPS03+ 或 SAP HANA Cloud

---

快速入门

连接与 DataFrame

from hana_ml import ConnectionContext

# Connect
conn = ConnectionContext(
    address='<hostname>',
    port=443,
    user='<username>',
    password='<password>',
    encrypt=True
)

# Create DataFrame
df = conn.table('MY_TABLE', schema='MY_SCHEMA')
print(f"Shape: {df.shape}")
df.head(10).collect()

PAL 分类

from hana_ml.algorithms.pal.unified_classification import UnifiedClassification

# Train model
clf = UnifiedClassification(func='RandomDecisionTree')
clf.fit(train_df, features=['F1', 'F2', 'F3'], label='TARGET')

# Predict & evaluate
predictions = clf.predict(test_df, features=['F1', 'F2', 'F3'])
score = clf.score(test_df, features=['F1', 'F2', 'F3'], label='TARGET')

APL AutoML

from hana_ml.algorithms.apl.classification import AutoClassifier

# Automated classification
auto_clf = AutoClassifier()
auto_clf.fit(train_df, label='TARGET')
predictions = auto_clf.predict(test_df)

模型持久化

from hana_ml.model_storage import ModelStorage

ms = ModelStorage(conn)
clf.name = 'MY_CLASSIFIER'
ms.save_model(model=clf, if_exists='replace')

---

核心库

PAL（预测分析库）

• 100 多种算法，在数据库内执行
• 类别：分类、回归、聚类、时间序列、预处理
• 主要类：UnifiedClassification、UnifiedRegression、KMeans、ARIMA
• 完整列表请参阅：references/PAL_ALGORITHMS.md

APL（自动化预测库）

• AutoML 功能，包含自动特征工程
• 主要类：AutoClassifier、AutoRegressor、GradientBoostingClassifier
• 详情请参阅：references/APL_ALGORITHMS.md

DataFrame

• 惰性求值——直到调用 collect() 才会构建 SQL
• 数据库内处理，以实现最佳性能
• 完整 API 请参阅：references/DATAFRAME_REFERENCE.md

可视化工具

• EDA 图表、模型解释、指标
• SHAP 集成，用于模型可解释性
• 14 个可视化模块请参阅：references/VISUALIZERS.md

---

常见模式

训练集与测试集拆分

from hana_ml.algorithms.pal.partition import train_test_val_split

train, test, val = train_test_val_split(
    data=df,
    training_percentage=0.7,
    testing_percentage=0.2,
    validation_percentage=0.1
)

特征重要性

# APL models
importance = auto_clf.get_feature_importances()

# PAL models
from hana_ml.algorithms.pal.preprocessing import FeatureSelection
fs = FeatureSelection()
fs.fit(train_df, features=features, label='TARGET')

流水线

from hana_ml.algorithms.pal.pipeline import Pipeline
from hana_ml.algorithms.pal.preprocessing import Imputer, FeatureNormalizer

pipeline = Pipeline([
    ('imputer', Imputer(strategy='mean')),
    ('normalizer', FeatureNormalizer()),
    ('classifier', UnifiedClassification(func='RandomDecisionTree'))
])

---

最佳实践

1. 使用惰性求值——操作会构建 SQL，直到调用 collect() 才会执行
2. 利用数据库内处理——为提升性能，将数据保留在 HANA 中
3. 使用 Unified 接口——在不同算法间保持 API 一致
4. 保存模型——使用 ModelStorage 进行持久化
5. 解释预测结果——使用 SHAP 解释器增强可解释性
6. 监控 AutoML——对长时间运行的作业使用 PipelineProgressStatusMonitor

---

捆绑资源

参考文件

• references/DATAFRAME_REFERENCE.md（479 行）

  • ConnectionContext API、DataFrame 操作、SQL 生成

• **references/PAL_ALGORITHMS.md****（869 行）

  • 完整的 PAL 算法参考（100 多种算法）
  • 分类、回归、聚类、时间序列、预处理

• references/APL_ALGORITHMS.md（534 行）

  • AutoML 功能、自动特征工程
  • AutoClassifier、AutoRegressor、GradientBoosting 类

• references/VISUALIZERS.md（704 行）

  • 14 个可视化模块（EDA、SHAP、指标、时间序列）
  • 图表类型、配置、导出选项

• references/SUPPORTING_MODULES.md（626 行）

  • 模型存储、空间分析、图算法
  • 文本挖掘、统计、错误处理

---

错误处理

from hana_ml.ml_exceptions import Error

try:
    clf.fit(train_df, features=features, label='TARGET')
except Error as e:
    print(f"HANA ML Error: {e}")

---

Documentation

• Official Docs: https://help.sap.com/doc/1d0ebfe5e8dd44d09606814d83308d4b/2.0.07/en-US/hana_ml.html
• PyPI Package: https://pypi.org/project/hana-ml/