Snowflake 集成

概述

本文档介绍如何使用 Snowflake 的外部函数功能将 Driverless AI 模型作为 HTTP REST API 端点调用。

若要使用外部函数，必须在 Snowflake 和 Amazon 中进行一些设置和配置。更多信息，请参阅 Snowflake documentation on external functions.

注解

下载 ：

• Download the Driverless AI Snowflake Java UDF.

• Download the Driverless AI Snowflake external function (dai-snowflake-integration.tgz).

Java UDF 的设置流程通常比外部函数更简单。

要求

1. Snowflake 登录凭据

2. Amazon EC2 登录凭据

3. Driverless AI MOJO (pipelineSF.mojo)

• 包含在演示文件中

4. DAIMojoRestServer

• 包含在演示文件中

5. Driverless AI 许可证

• 通过合作伙伴门户提供

• 将许可证复制到 Snowflake_H2Oai 目录中。命名文件 license.sig.

6. Java JDK 1.8

• zip 演示文件中包含了开源 JDK，演示脚本将默认此开源 JDK。若要使用其他 JVM，请参见以下步骤：

  • 执行 “java -version” 以验证您的平台上可用的 JVM 是否已经安装 JDK 1.8。该命令的输出应显示 JDK 1.8，例如：

  java -version
  openjdk version "1.8.0_121"
  

  • 如果输出没有显示 JDK 1.8，可通过以下任一网站为您的环境下载 JDK 1.8。

    • https://www.azul.com/downloads/zulu-community/

    • https://openjdk.java.net/install/

安全性

使用外部函数时，会通过 Snowflake 调用 AWS API Gateway。这要求在 AWS 中对信任关系进行配置，以便可以执行调用。

H2O REST 服务器只接受通过 AWS Gateway 端点执行的调用。将参数 -DSecureModelAllowAgent=”AmazonAPIGateway.*|snowflake.*” 添加到命令行中时，甚至还可以进一步将此参数限制为某个特定 AWS 函数。

启用 -DModelSecureEndPoints=/** 后可以通过要求完全身份验证来保护 Rest 服务器，从而有效地阻止请求。

安装

Downloads

Download the Driverless AI Snowflake Java UDF.

Download the Driverless AI Snowflake external function (dai-snowflake-integration.tgz).

注意，Java UDF 的设置流程通常比外部函数更简单。

以下安装包括 Snowflake、AWS 和 EC2 实例中的步骤，在这些实例中，安装了 H2O REST 服务器。

以下步骤概述了 REST 服务器的安装：

1. 创建 EC2 实例，演示系统应满足以下最低要求：

   • 操作系统：Linux

   • CPU：2

   • 内存：16GB

   • 磁盘空间：500MB

请注意：对于可使用更大数据集的演示系统，可考虑使用更多核心和更大内存。例如，使用 1 百万个行、48 个核心和 64GB 会使得双核系统具有低得多的延迟。

2. 将分发文件复制到 EC2 实例中，并提取文件。

unzip Snowflake_H2Oai_v1.zip

3. 创建数据库。

4. 将样本数据填充到表格中。

5. 验证数据是否可用。

启动 REST 服务器。

按照以下步骤在 EC2 实例上启动 H2O REST 服务器。

1. 确保当前工作目录为 Snowflake-H2Oai/Function。

cd Snowflake-H2Oai/Function
./goServer.sh

2. 按下 ENTER 以在后台运行程序。日志将写入到 nohup.log 中。

3. 几秒钟后 REST 服务器启动。检查是否接收到与以下消息类似的准备就绪消息：

Started DaiMojoRestServer4Application in 4.778 seconds (JVM running for 6.22)

验证 REST 服务器安装

若要验证 REST 服务器和其模型组件是否成功安装，并且服务器是否正确初始化：

1. 确保当前工作目录为 Snowflake-H2Oai/Function

2. 通过单独的终端窗口运行以下脚本：

./goVerifyEndPoint.sh
{ "data":[[1,0.7779838]]}

如果响应与此示例的输出类似，则表示 REST 服务器、模型和许可证已经正确安装。

停止 REST 服务器

若要对 EC2 实例停止的 H2O REST 服务器，可运行以下命令：

cd Snowflake-H2Oai/Function
./stopServer.sh

外部函数示例

以下为外部函数的示例：

create or replace api integration demonstration_external_api_integration_01
api_provider=aws_api_gateway
api_aws_role_arn='arn:aws:iam::nnnnnnnn:role/snowflake'
api_allowed_prefixes=('https://aaaaaaaa.execute-api.us-east-1.amazonaws.com/MojoTest')
enabled=true;

create or replace external function H2OPredict(v varchar, v0 number, v1 varchar, v2 number, v3 number, v4 number, v5 number, v6 varchar, v7 varchar, v8 number, v9 number, v10 number, v11 number)
returns variant
api_integration = demonstration_external_api_integration_01
as 'https://aaaaaaaa.execute-api.us-east-1.amazonaws.com/MojoTest';

函数数据类型

之前的函数会传递 13 个参数（从 v 到 V11）。

• 这里的参数数量与用于创建模型的参数数量相匹配。

• 如果表格中的数据为浮点数，并且函数使用

SQL 示例

配置好 Snowflake 和 AWS Gateway 之后，以下示例 SQL 语句会返回预测结果：

select H2OPredict('Modelname=pipelineSF.mojo’, LOAN_AMNT, TERM, INT_RATE, INSTALLMENT, EMP_LENGTH, ANNUAL_INC, VERIFICATION_STATUS, ADDR_STATE, DTI, DELINQ_2YRS, REVOL_BAL, REVOL_UTIL ) from LENDINGCLUB where ADDR_STATE='NJ' order by ID;

传递运行时参数

以下是用于将特定值传递给 REST 服务器的参数列表：

• 模型名称：REST 服务器 ModelDirectory 中存在的 Driverless AI MOJO 文件名称。此名称默认为 pipeline.mojo.

• 预测：将使用的数值预测。默认值为 0。

样本参数使用方法：

select *, H2OPredict('Modelname=pipelineSF.mojo Prediction=0',LOAN_AMNT, TERM, INT_RATE, INSTALLMENT, EMP_LENGTH, ANNUAL_INC, VERIFICATION_STATUS,
              ADDR_STATE, DTI, DELINQ_2YRS, REVOL_BAL, REVOL_UTIL ) from LENDINGCLUB;

Request: 10625, 36 months,6.62,326.23,4,33000,VERIFIED - income,WA,27.38,0,6290,46.3
Response: ["bad_loan.0 : 0.917305","bad_loan.1 : 0.08269503"]

0.917305

高级设置

Snowflake 外部函数允许自定义 HTTP 标头。在以下示例中，HTTP 标头 modelname 已添加到函数中并被定义为 pipeline.mojo（针对此函数的所有调用）。

create or replace external function H2OPredictHDR(v0 number, v1 varchar, v2 number, v3 number, v4 number, v5 number, v6 varchar, v7 varchar, v8 number, v9 number, v10 number, v11 number)
returns variant
HEADERS=('modelname' = 'pipelineSF.mojo')
api_integration = demonstration_external_api_integration_01
as 'https://aaaaaaaa.execute-api.us-east-1.amazonaws.com/production';

这会允许在不要求任何参数的情况下调用函数。函数本身就足以用于各种模型：

select id, H2OPredictHDR(LOAN_AMNT, TERM, INT_RATE, INSTALLMENT, EMP_LENGTH, ANNUAL_INC, VERIFICATION_STATUS,
              ADDR_STATE, DTI, DELINQ_2YRS, REVOL_BAL, REVOL_UTIL ) from LENDINGCLUB;

如有要求，也可以传递预测结果。否则，会返回概率 0。

构建模型

Snowflake 外部函数功能让您通过 Snowflake 工作表构建 Driverless AI 模型。当请求 Driverless AI 通过工作表构建模型时，在名称为 MODELBUILD 的表格中会更新构建状态，以便于对构建进行监控。

这样会显示所构建的风险模型的不同阶段，从在 Snowflake 中请求特定的表格到最终部署以在 REST 服务器中进行评分。

请注意：当构建完成时，会报告构建实验 UUID，以便于审核。

定义构建函数实例：

create or replace external function H2OBuild(v varchar)
returns variant
api_integration = demonstration_external_api_integration_01
as 'https://bbbbb.execute-api.us-east-1.amazonaws.com/production';

定义 Snowflake 表格

Snowflake 表格用于跟踪模型构建状态。

请求构建示例

使用函数 H2OBuild 更改请求参数：

select H2OBuild('Build --Table=LENDINGCLUB2 --Target=BAD_LOAN --Modelname=custchurn.mojo') ;

更多关于构建请求参数的信息，请参见下表：

构建参数

参数	可选	描述
Table	否	定义用于模型构建的 Snowflake 表格
Target	否	用作模型训练目标的列（特征）名称
Modelname	否	部署时模型的名称
准确度	是	模型准确度设置
Time	是	模型实验时间
Interpretability	是	模型可解释性设置
User	是	访问 Snowflake 表格所需的用户名
Password	是	访问 Snowflake 表格所需的密码
Warehouse	是	Snowflake 数据仓库
Database	是	Snowflake 数据库
Schema	是	Snowflake 模式

部署

模型完成构建后，将被复制到到 REST 服务器，并可供 H2OPredict 评分函数使用。

配置

必须将脚本 buildmodel.py 从 SnowFlake 函数目录复制到用于执行 REST 服务器的位置。此位置默认为 /home/ec2-user/Snowflake-H2Oai/Function.

请注意：必须依据您当前使用的环境更新脚本代码。

Driverless AI Snowflake 配置

Driverless AI 配置使用标准默认设置，但与用户安全相关的设置的除外。请使用最适合您当前所用环境的身份验证方式。更多信息，请参阅 使用 config.toml 文件 和 身份验证方式.

   authentication_method = "local"
   local_htpasswd_file = "/home/ec2-user/dai-1.8.5.1-linux-x86_64/.htpasswd"

This resource must be secured from unauthorized access and use.

若要使用本地身份验证创建用户名和密码：

sudo htpasswd -B -c .htpasswd snowflake
Password yourpassword

要求

构建函数将调用使用 Driverless AI Python 客户端的 Python 程序来创建实验。以下包必须可用：

• sudo yum install httpd

• sudo yum install python3

• sudo pip3 install driverlessai

• sudo pip3 install –upgrade snowflake-connector-python

样本工作簿

以下示例展示了在初始设置完成后如何使用函数。

请注意：为了使以下示例正常工作，必须定义 H2OBuild 和 H2OPredict。

1. 利用 Snowflake 表格 MODELBUILD 的更新跟踪构建状态。

SELECT * FROM MODELBUILD;

2. 使用 Snowflake 表格 LENDINGCLUB2 构建模型，以预测 BAD_LOAN 列。将模型命名为 riskmodel.mojo。

SELECT H2OBuild('Build --Table=LENDINGCLUB2 --Target=BAD_LOAN --Modelname=riskmodel.mojo') ;

3. 部署模型后，立即获取建议的 Snowflake 函数定义。

SELECT H2OBuild('Modelname= riskmodel.mojo Function');

4. 之前的函数提供了建议用于调用模型的 Snowflake SQL 语句。

SELECT H2OBuild('Modelname= riskmodel.mojo SQL') ;

5. 使用 Snowflake 外部函数。

SELECT H2OPredict(LOAN_AMNT,  TERM,  INT_RATE,  INSTALLMENT,  EMP_LENGTH,  HOME_OWNERSHIP,  ANNUAL_INC,  VERIFICATION_STATUS,  ADDR_STATE,  DTI,  DELINQ_2YRS,  INQ_LAST_6MNTHS,  PUB_REC,  REVOL_BAL,  REVOL_UTIL,  TOTAL_ACC ) from LENDINGCLUB;