向量计算SDK

前提条件

• 已创建AccessKey，详情请参见创建AccessKey。

• 已安装Python环境。

• 授予账号相应权限，详情请参见授予RAM用户权限。

安装SDK

您可以通过pip安装Python SDK，详细说明请参见hologres-vector。

pip install hologres-vector

使用步骤

1. 输入Hologres实例连接信息。

   from hologres_vector import HologresVector
   import os
   
   host = os.environ["<HOLO_HOST>"]
   port = os.environ["<HOLO_PORT>"]
   dbname = os.environ["<HOLO_DBNAME>"]
   user = os.environ["<HOLO_USER>"]
   password = os.environ["<HOLO_PASSWORD>"]
   
   connection_string = HologresVector.connection_string_from_db_params(host, port, dbname, user, password)

   参数说明如下：

   参数	描述
   HOLO_HOST	Hologres实例的网络地址。 进入Hologres管理控制台的实例详情页，从实例详情页获取网络地址。
   HOLO_PORT	Hologres的实例端口。 进入Hologres管理控制台的实例详情页，从实例详情页获取网络地址。
   HOLO_DBNAME	Hologres创建的数据库名称。
   HOLO_USER	当前阿里云账号的AccessKey ID。 您可以单击AccessKey 管理，获取AccessKey ID。
   HOLO_PASSWORD	当前阿里云账号的AccessKey Secret。 您可以单击AccessKey 管理，获取AccessKey Secret。

2. 创建向量表。

   需要指定向量的维度，以及表中的除向量列、主键、JSON列以外的其他强Schema列及数据类型。

   table_name = "test_table"  # 定义表名
   holo = HologresVector(
       connection_string,     # 连接信息
       5,                     # 向量维度
       table_name=table_name, # 表名
       table_schema={"t": "text", "date": "timestamptz", "i": "int"},	#定义列及数据类型
       distance_method="SquaredEuclidean", # 距离函数，推荐用默认值，也可以选择"Euclidean"或"InnerProduct"
     	pre_delete_table=True, # 若表已存在，是否删表重建
   )

   table_schema：用于定义强Schema列及对应数据类型，在Hologres表中，table_schema下的每一个字段对应一个表的列。

3. 导入向量数据。

   通过Hologres Vector SDK进行向量数据导入时，会默认按512行进行攒批，以提升导入效率。

   # 数据示例
   vectors = [[0,0,0,0,0], [1,1,1,1,1], [2,2,2,2,2]]
   ids = ['0', '1', '2'] # primary key
   schema_datas = [
       {'t': 'text 0', 'date': '2023-08-02 18:30:00', 'i': 0},
       {'t': 'text 1', 'date': '2023-08-02 19:30:00', 'i': 1},
       {'t': 'text 2', 'date': '2023-08-02 20:30:00', 'i': 2},
   ]
   metadatas = [
       {'a': "hello"},
       {'b': 123},
       {},
   ]
   
   # 导入数据
   holo.upsert_vectors(vectors, ids, schema_datas=schema_datas, metadatas=metadatas)

   • vectors：向量列，用于存储向量数据。

   • ids：主键，用于定义向量数据对应的主键ID。

   • metadatas：JSON列，用于将弱Schema字段、半结构化字段灵活定义到Hologres一个JSON列中。

4. 查询向量数据。

   • 普通查询：从数据库中任取一条数据或定义filter条件查询向量数据。

     # 任取一条数据
     holo.query(limit=1)
     # 返回结果
     [{'id': '2', 'vector': [2.0, 2.0, 2.0, 2.0, 2.0], 'metadata': {}}]
     
     # 通过filter条件查询
     holo.query(schema_data_filters={'id': '1'})
     # 返回结果
     [{'id': '1', 'vector': [1.0, 1.0, 1.0, 1.0, 1.0], 'metadata': {'b': 123}}]

   • 近邻查询：根据给定向量从表中查询最近邻向量数据。

     # 查询与给定向量最近邻的top 2向量，并通过select_columns返回指定的列
     holo.search([0.1, 0.1, 0.1, 0.1, 0.1], k=2, select_columns=['t'])
     # 结果
     [{'id': '0', 'metadata': {'a': 'hello'}, 'distance': 0.05, 't': 'text 0'},
     {'id': '1', 'metadata': {'b': 123}, 'distance': 4.05, 't': 'text 1'}]

   • 融合查询：根据给定向量从表中查询最近邻向量数据，并通过其他结构化字段定义过滤条件。

     # 查询与给定向量最近邻的top 2向量，并通过schema_data_filters定义过滤条件
     holo.search([0.1, 0.1, 0.1, 0.1, 0.1], k=2, schema_data_filters={'t': 'text 1'})
     # 结果
     [{'id': '1', 'metadata': {'b': 123}, 'distance': 4.05}]

其他操作

# 先插入一行id为3的数据
holo.upsert_vectors([[3, 3, 3, 3, 3]], [3], schema_datas=[{'t': 'old data'}])
# 再插入一行id为3的数据，下面这行会将上面的整行替换掉
holo.upsert_vectors([[-3, -3, -3, -3, -3]], [3], schema_datas=[{'t': 'new data'}])

# 查询该行数据
holo.query(schema_data_filters={'id': '3'})
# 查询结果
[{'id': '3', 'vector': [-3.0, -3.0, -3.0, -3.0, -3.0], 'metadata': {}}]