基础向量检索

前提条件

已安装Proxima CE包并准备输入表，详情请参见安装Proxima CE包。

使用限制

不支持在已开启租户级别Schema语法开关的项目中执行向量检索任务，否则会出现类似于Schema xxx does not exist的报错。请在未开启租户级别Schema语法开关的项目中执行本文的代码示例。

注意事项

• 如果您已经开通Volume权限，并且成功创建了External Volume，可以在DataWorks或odpscmd中使用Volume方式运行，否则需要输入AK或role_arn作为必要的启动参数，由Proxima CE任务程序化地创建使用。

• 在DataWorks中执行Proxima CE任务时，您需要采用公共调度资源组进行冒烟测试，详情请参见执行冒烟测试。

导入数据至输入表

如果您想先测试整个流程，可以在DataWorks的SQL节点运行以下命令，生成简单的小数据表来运行简单的检索示例。

ALTER TABLE doc_table_float_smoke ADD PARTITION(pt='20221111');
INSERT OVERWRITE TABLE doc_table_float_smoke PARTITION (pt='20221111') VALUES
('1.nid','1~1~1~1~1~1~1~1'),
('2.nid','2~2~2~2~2~2~2~2'),
('3.nid','3~3~3~3~3~3~3~3'),
('4.nid','4~4~4~4~4~4~4~4'),
('5.nid','5~5~5~5~5~5~5~5'),
('6.nid','6~6~6~6~6~6~6~6'),
('7.nid','7~7~7~7~7~7~7~7'),
('8.nid','8~8~8~8~8~8~8~8'),
('9.nid','9~9~9~9~9~9~9~9'),
('10.nid','10~10~10~10~10~10~10~10');

ALTER TABLE query_table_float_smoke ADD PARTITION(pt='20221111');
INSERT OVERWRITE TABLE query_table_float_smoke PARTITION (pt='20221111') VALUES
('q1.nid','1~1~1~1~2~2~2~2'),
('q2.nid','4~4~4~4~3~3~3~3'),
('q3.nid','9~9~9~9~5~5~5~5');

运行

您可以在DataWorks或者odpscmd中运行，请根据实际情况选择合适的运行工具。

使用DataWorks运行

您可以在DataWorks上新建MaxCompute ODPS MR节点，通过ODPS SQL脚本来运行Proxima CE。

• Volume方式。

  --@resource_reference{"<proxima_ce_jar>"} -- 引用上传的proxima-ce jar包，在“数据开发”页面，右键单击已上传的JAR包，并选择“引用资源”即可生成该行注释
  jar -resources <proxima_ce_jar>  -- 上传的proxima-ce jar包
  -classpath <proxima_ce_jar> com.alibaba.proxima2.ce.ProximaCERunner  -- classpath指定main函数入口类
  -doc_table doc_table_float_smoke  -- 输入doc表
  -doc_table_partition 20221111  -- 输入doc表的partition
  -query_table query_table_float_smoke  -- 输入query表
  -query_table_partition 20221111  -- 输入query表的partition
  -output_table output_table_float_smoke  -- 输出表
  -output_table_partition 20221111  -- 输出表partition
  -data_type float  -- 向量数据类型
  -dimension 8  -- 向量维度
  -topk 1  -- 向量检索的topk
  -job_mode train:build:seek:recall  -- 指定检索任务模式，默认为train:build:seek，加上recall能够计算本次检索的召回率
  -external_volume_name <ext_volume> -- 用户提供的创建好的volume on oss，需要底层oss目录也创建好，否则会运行失败
  -owner_id <oid>  -- 用户提供的用于标识自己的唯一id
  ; -- 注意不要丢掉分号，这是odps sql结束的标志

  您在执行上述代码时，需要根据实际情况替换以下参数：

  参数名	描述
  proxima_ce_jar	已上传的Proxima CE安装包名称，例如proxima-ce-aliyun-1.0.2.jar。详情请参见安装Proxima CE包。
  ext_volume	已创建的External Volume名称。External Volume的创建方式请参见External Volume操作。
  oid	由数字组成的用户唯一性标识，建议长度不超过32位，例如123456。推荐您使用阿里云账号ID。

• role_arn方式。

  --@resource_reference{"<proxima_ce_jar>"}  -- 引用上传的proxima-ce jar包，在“数据开发”页面，右键单击已上传的JAR包，并选择“引用资源”即可生成该行注释
  jar -resources <proxima_ce_jar>  -- 上传的proxima-ce jar包
  -classpath <proxima_ce_jar> com.alibaba.proxima2.ce.ProximaCERunner  -- classpath指定main函数入口类
  -doc_table doc_table_float_smoke  -- 输入doc表
  -doc_table_partition 20221111  -- 输入doc表的partition
  -query_table query_table_float_smoke  -- 输入query表
  -query_table_partition 20221111  -- 输入query表的partition
  -output_table output_table_float_smoke  -- 输出表
  -output_table_partition 20221111  -- 输出表partition
  -data_type float  -- 向量数据类型
  -dimension 8  -- 向量维度
  -topk 1  -- 向量检索的topk
  -job_mode train:build:seek:recall  -- 指定检索任务模式，默认为train:build:seek，加上recall能够计算本次检索的召回率
  -oss_role_arn <rolearn> -- 用户提供的云账号下可以访问oss的role_arn，形如acs:ram::1234xxx5678:role/xxx-role
  -oss_endpoint <endpoint> -- 目标地域的endpoint
  -oss_bucket <bucket> -- 已创建的oss bucket
  -owner_id <oid>  -- 用户提供的用于标识自己的唯一id
  ; -- 注意不要丢掉分号，这是odps sql结束的标志

  您在执行上述代码时，需要根据实际情况替换以下参数：

  参数名	描述
  proxima_ce_jar	已上传的Proxima CE安装包名称，例如proxima-ce-aliyun-1.0.1.jar。详情请参见安装Proxima CE包。
  rolearn	RAM角色的ARN信息，例如acs:ram::1234xxx5678:role/xxx-role。 您可以登录RAM访问控制台，在左侧导航栏身份管理下拉列表下的角色页面获取。
  endpoint	MaxCompute项目所在地域的OSS内网Endpoint。详情请参见OSS地域和访问域名。
  bucket	与MaxCompute项目位于同一地域的OSS存储空间名称，即Bucket名称。查看存储空间名称操作，请参见列举存储空间。
  oid	由数字组成的用户唯一性标识，建议长度不超过32位，例如123456。推荐您使用阿里云账号ID。

使用odpscmd运行

如果您使用odpscmd运行，可以在MaxCompute客户端（odpscmd）中执行如下脚本：

• Volume方式。

  jar -resources <proxima_ce_jar> 
  -classpath <proxima_ce_jar_path> com.alibaba.proxima2.ce.ProximaCERunner 
  -doc_table doc_table_float_smoke 
  -doc_table_partition 20221111 
  -query_table query_table_float_smoke 
  -query_table_partition 20221111 
  -output_table output_table_float_smoke 
  -output_table_partition 20221111 
  -data_type float 
  -dimension 8 
  -topk 1 
  -job_mode train:build:seek:recall 
  -external_volume_name <ext_volume> 
  -owner_id <oid> 
  ;

  您在执行上述代码时，需要根据实际情况替换以下参数：

  参数名	描述
  proxima_ce_jar	已上传的Proxima CE安装包名称，例如proxima-ce-aliyun-1.0.1.jar。详情请参见安装Proxima CE包。
  proxima_ce_jar_path	Proxima CE的JAR包所在的本地路径，此处直接使用JAR包名称，表示该JAR与执行脚本位于同一目录下。
  ext_volume	已创建的External Volume名称。External Volume的创建方式请参见External Volume操作。
  oid	由数字组成的用户唯一性标识，建议长度不超过32位，例如123456。推荐您使用阿里云账号ID。

• role_arn方式。

  jar -resources <proxima_ce_jar> 
  -classpath <proxima_ce_jar_path> com.alibaba.proxima2.ce.ProximaCERunner 
  -doc_table doc_table_float_smoke 
  -doc_table_partition 20221111 
  -query_table query_table_float_smoke 
  -query_table_partition 20221111 
  -output_table output_table_float_smoke 
  -output_table_partition 20221111 
  -data_type float 
  -dimension 8 
  -topk 1 
  -job_mode train:build:seek:recall 
  -oss_role_arn <rolearn> 
  -oss_endpoint <endpoint> 
  -oss_bucket <bucket> 
  -owner_id <oid> 
  ;

  您在执行上述代码时，需要根据实际情况替换以下参数：

  参数名	描述
  proxima_ce_jar	已上传的Proxima CE安装包名称，例如proxima-ce-aliyun-1.0.1.jar。详情请参见安装Proxima CE包。
  proxima_ce_jar_path	Proxima CE的JAR包所在的本地路径，此处直接使用JAR包名称，表示该JAR与执行脚本位于同一目录下。
  rolearn	RAM角色的ARN信息，例如acs:ram::1234xxx5678:role/xxx-role。 您可以登录RAM访问控制台，在左侧导航栏身份管理下拉列表下的角色页面获取。
  endpoint	MaxCompute项目所在地域的OSS内网Endpoint。详情请参见OSS地域和访问域名。
  bucket	与MaxCompute项目位于同一地域的OSS存储空间名称，即Bucket名称。查看存储空间名称操作，请参见列举存储空间。
  oid	由数字组成的用户唯一性标识，建议长度不超过32位，例如123456。推荐您使用阿里云账号ID。

运行结果

• 标准输出结果样例。

  向量检索  数据类型:4 , 向量维度:8 , 检索方式:HNSW , 计算方法:SquaredEuclidean , 构建模式:train:build:seek:recall
  doc表信息 表名: doc_table_float_smoke , 分区:20221111 , doc数量:10 , 向量分隔符:~
  query表信息 表名: query_table_float_smoke , 分区:20221111 , query数量:3 , 向量分隔符:~
  输出表信息 表名: output_table_float_smoke , 分区:20221111
  行列信息  行数: 1 , 列数:1 , 每列索引doc数量:1000000
  是否清除Volume索引:false
  
  各个worker的耗时(单位:秒):
     SegmentationWorker:      1
     TmpTableWorker:      0
     KmeansGraphWorker:       0
     BuildJobWorker:      120
     SeekJobWorker:       60
     TmpResultJoinWorker:     0
     RecallWorker:        60
     CleanUpWorker:       1
  总耗时(单位:分钟):
  
  实际召回率
      Recall@1:   1.0
  

• output table结果样例。

  +------------+------------+------------+------------+
  | pk         | knn_result | score      | pt         |
  +------------+------------+------------+------------+
  | q1.nid     | 1.nid      | 4.0        | 20221111   |
  | q2.nid     | 3.nid      | 4.0        | 20221111   |
  | q3.nid     | 7.nid      | 32.0       | 20221111   |

百万TopK检索

得益于Proxima2.x内核的性能提升，Proxima CE能支持百万量级的TopK检索召回（即支持在百万级向量中，快速检索与查询向量最相似的前K个结果），直接设置启动参数-topk即可。