您可以将Proxima镜像部署为EAS模型在线服务，通过API方式请求服务，实现版本查看、集合管理、文档管理等功能。
背景信息
Proxima是阿里巴巴达摩院自研的向量检索内核。目前，其核心能力广泛应用于阿里巴巴和蚂蚁集团内众多业务，如淘宝搜索和推荐、蚂蚁人脸支付、优酷视频搜索、阿里妈妈广告检索等。同时，Proxima还深度集成在各式各类的大数据和数据库产品中，如阿里云Hologres、搜索引擎Elastic Search 和ZSearch、离线引擎MaxCompute (ODPS) 等，为其提供向量检索的能力。
使用流程
首先您需要将Proxima镜像部署为EAS模型在线服务，并通过在线调试功能，验证模型服务是否运行正常。
您可以通过API方式发送服务请求，实现Proxima版本查看、集合管理和文档管理等功能。
前提条件
已开通PAI（EAS）后付费，并创建默认工作空间，具体操作，请参见开通PAI并创建默认工作空间。
已下载EASCMD客户端并进行身份认证，具体操作，请参见下载并认证客户端。
使用限制
仅支持使用公共资源组部署Proxima镜像。
华东2（上海）仅支持使用ESSD云盘。
目前仅支持使用EASCMD客户端在公共资源组上部署带云盘的服务。
步骤一：部署及调用Proxima模型服务
部署Proxima模型服务。
准备服务的配置文件service.json。
{ "metadata": { "name": "proxima", "instance": 1, "cpu": 1, "memory": 2000 }, "containers": [ { "image": "registry-vpc.cn-shanghai.aliyuncs.com/eas/proxima-se:0.7.0.2_skylake", "script": "sh /var/lib/proxima-se/bin/run_eas.sh", "port": 16001 } ], "storage": [ { "cloud_disk": { "capacity": "200Gi", "type": "cloud_essd" }, "mount_path": "/data_cloud_disk_mount_path" } ] }其中关键参数说明如下，其他参数配置，请参见服务模型所有相关参数说明。
参数
描述
metadata.name
自定义服务名称。
metadata.cpu
CPU核数。
说明每核CPU的处理能力数量级为每秒处理100条请求，不同的数据类型会有差异，请根据实际请求数据量配置资源。
metadata.memory
内存大小，单位为GB。
说明最少需配置2 GB。建议配置为文档插入总数据尺寸的2-3倍左右。
containers.image
不同地域需要使用不同的镜像地址，请按照实际地域选择。目前支持的地域列表及对应的镜像地址如下。
华东2（上海）
registry-vpc.cn-shanghai.aliyuncs.com/eas/proxima-se:0.7.0.2_skylake
中国（香港）
registry-vpc.cn-hongkong.aliyuncs.com/eas/proxima-se:0.7.0.2_skylake
华北2（北京）
registry-vpc.cn-beijing.aliyuncs.com/eas/proxima-se:0.7.0.2_skylake
华东1（杭州）
registry-vpc.cn-hangzhou.aliyuncs.com/eas/proxima-se:0.7.0.2_skylake
华南1（深圳）
registry-vpc.cn-shenzhen.aliyuncs.com/eas/proxima-se:0.7.0.2_skylake
storage.cloud_disk.capacity
storage.cloud_disk.type
云盘类型，取值如下：
说明华东2（上海）仅支持使用ESSD云盘。
cloud_essd：ESSD云盘。
cloud_ssd：SSD云盘。
cloud_efficiency：高效云盘。
available：优先创建SSD云盘，如果可用区内SSD云盘没有可用资源，则创建高效云盘。
不同的云盘对应的存储容量规格如下。
在JSON文件所在目录，执行以下命令部署服务。
说明该命令以Windows 64版本客户端为例，如果您的操作系统为其他版本，请使用对应版本的客户端命令来部署服务。
eascmdwin64.exe create <service.json>其中：<service.json>需要替换为您的JSON文件名称。
系统返回如下类似结果。
[RequestId]: 73491125-F0CF-5749-902A-6261CF96**** +-------------------+---------------------------------------------------------------------------------------+ | Internet Endpoint | http://139699392458****.cn-shanghai.pai-eas.aliyuncs.com/api/predict/proxima | | Intranet Endpoint | http://139699392458****.vpc.cn-shanghai.pai-eas.aliyuncs.com/api/predict/proxima| | Token | NDYxYzZjM2QxNGY1OWY1YjY1ZmJlNWRkY2UxYzU1OTcyOWFiYjk****** | +-------------------+---------------------------------------------------------------------------------------+ [OK] Service is now deploying [OK] Successfully created ingress [OK] Successfully synchronized resources [OK] Waiting [Total: 1, Pending: 1, Running: 0] [OK] Waiting [Total: 1, Pending: 1, Running: 0] [OK] Service is running等待一段时间即可完成模型部署，您可以到控制台页面查看模型部署情况，详情请参见服务部署：控制台。
在线调试模型服务。
进入模型在线服务（EAS）页面，详情请参见服务部署：控制台。
在模型在线服务（EAS）页面，单击目标服务操作列下的在线调试。
以调用Proxima版本查看接口为例，在接口地址末尾添加
/service_version，并单击发送请求。说明您也可以使用RESTFul API的其他接口来调试该模型服务，仅GET类型请求需要将Request Body置为空。
在上图调试信息区域，即可查看返回结果。
在模型在线服务（EAS）页面，单击目标服务的服务方式列下的调用信息，在公网地址调用页签，查看服务访问地址和Token，并保存到本地。
后续，您可以使用该访问地址和Token通过API方式发送服务请求，详情请参见步骤二：通过API方式发送服务请求。
步骤二：通过API方式发送服务请求
目前Proxima支持两类API接口：集合管理接口和文档管理接口。
您可以在本地任意环境，参考以下内容通过API方式发送服务请求，实现Proxima版本查看、集合管理和文档管理等功能。
版本查看
发送以下服务请求，来获取Proxima的版本信息。
请求代码：
HTTP 1.1 GET /service_version返回值：
status：表示服务器Proxima执行状态，详情请参见附录：通用数据类型。
version：表示发布版本的字符串标识，STRING类型。
请求示例：
# Example: Get the version of Proxima SE ################################################## # Request: curl -X GET \ http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/service_version \ -H 'cache-control: no-cache' \ -H 'Authorization:${YourToken}' \ ################################################## # Response: { "status": { "code": 0, "reason": "Success" }, "version": "0.1.0-50-g16af91e" }其中：
http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
集合管理
您可以通过RESTful API方式进行集合的增、删、查等操作。
创建集合
请求代码：
HTTP 1.1 POST /v1/collection/<name>其中：<name>：路径参数，需要替换为实际要创建的集合名称，需全局唯一。
请求主体：
参数
描述
collection_name
可选，默认与路径参数同名，STRING类型。
max_docs_per_segment
可选，设置集合数据的分片大小阈值，UINT64类型，默认为系统最大值。
forward_column_params
正排列表，List[ForwardColumnParam,…]类型，其中ForwardColumnParam配置如下：
column_name：索引列名称，STRING类型。
data_type：正排列数据类型，只能使用字符串标识，详情请参见附录：通用数据类型。
index_column_params
索引列表，List[IndexColumnParam,...]类型，其中IndexColumnParam配置如下：
column_name：索引列名称，STRING类型。
index_type：索引类型名，STRING类型，取值如下：
IT_PROXIMA_GRAPH_INDEX：图示索引。
IT_INVERT_INDEX：倒排索引。
data_type：索引列数据类型，只能使用字符串标识，详情请参见附录：通用数据类型。
dimension： 数据维数，UINT32类型，仅针对向量列有效，详情请参见附录：通用数据类型。
extra_params：高阶参数列表，List[KeyValuePair,...]类型，其中KeyValuePair配置如下：
key：参数名称，STRING类型。
value：参数值，STRING类型。
返回值
Proxima执行状态，详情请参见附录：通用数据类型。
请求示例
# Example: Create Collection with two index colums ################################################## # Request: curl -X POST \ http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example \ -H 'cache-control: no-cache' \ -H 'content-type: application/json' \ -H 'Authorization:${YourToken}' \ -d '{ "collection_name":"example", "forward_column_params":[ {"column_name": "Name", "data_type":"DT_STRING"}, {"column_name": "SerialNo", "data_type":"DT_INT32"} ], "index_column_params":[ { "column_name":"ImageVector", "index_type":"IT_PROXIMA_GRAPH_INDEX", "data_type":"DT_VECTOR_FP32", "dimension":8, "extra_params":[ { "key":"ef_search", "value":"200" } ] }, {"column_name":"Id", "index_type":"IT_INVERT_INDEX", "data_type":"DT_STRING" } ] }' ################################################## # Response: { "code": 0, "reason": "Success" }其中：
http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
查询集合
请求代码
HTTP 1.1 GET /v1/collection/<name>其中：<name>：路径参数，需要替换为需要查询的集合名称。
返回值
参数
描述
status
表示服务执行状态，详情请参见附录：通用数据类型。
collection
表示集合详细信息，包含以下内容：
uuid：集合ID，STRING类型，全局唯一。
status：集合状态码，STRING类型，取值如下：
CS_INITIALIZED：表示集合已初始化完成。
CS_SERVING：表示集合正常提供服务。
CS_DROPPED：表示集合已被删除。
magic_number：集合魔法数，UINT64类型。与外部系统关联，您无需关注。
config：集合配置信息，详情请参见创建集合接口中的请求主体内容。
请求示例
# Example: Describe Collection ################################################## # Request: curl -X GET \ http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example \ -H 'cache-control: no-cache' \ -H 'Authorization:${YourToken}' \ ################################################## # Response: { "status": { "code": 0, "reason": "Success" }, "collection": { "uuid": "d918becac22e471db41d55050809****", "config": { "collection_name": "example", "forward_column_params": [ { "column_name": "Name", "data_type": "DT_STRING", "extra_params": [] }, { "column_name": "SerialNo", "data_type": "DT_INT32", "extra_params": [] } ], "index_column_params": [ { "column_name": "ImageVector", "data_type": "DT_VECTOR_FP32", "dimension": 8, "extra_params": [], "index_type": "IT_PROXIMA_GRAPH_INDEX" }, { "column_name": "Id", "data_type": "DT_STRING", "dimension": 0, "extra_params": [], "index_type": "IT_INVERT_INDEX" } ], "max_docs_per_segment": "1844674407370955****" }, "status": "CS_SERVING", "magic_number": "0" } }http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
集合统计
获取集合的统计信息，包含文件数、大小、文档个数等信息。
请求代码
HTTP 1.1 GET /v1/collection/<name>/stats其中：<name>：路径参数，需要替换为需要获取统计信息的集合名称。
返回值
参数
描述
status
Proxima执行状态，详情请参见附录：通用数据类型。
collection_stats
集合统计信息，包含以下内容：
collection_name：集合名称，STRING类型。
collection_path：集合的存储路径，STRING类型。
total_doc_count：集合的总文档个数，STRING类型。
total_segment_count：集合分片个数，STRING类型。
total_index_file_size：集合总的存储大小，STRING类型。
total_index_file_count：集合内总的文件个数，STRING类型。
segment_stats：分片统计信息列表，多片模式下会有多个结果，包含以下内容。
state：分片状态码，STRING类型。取值如下：
SS_WRITING：表示分片正在写入。
max_lsn：分片内最大的记录号，STRING类型。
min_lsn：分片内最小的记录号，STRING类型。
doc_count：分片内文档个数，STRING类型。
max_doc_id：分片内最大文档ID，STRING类型。
min_doc_id：分片内最小文档ID，STRING类型。
segment_id：分片编号，UINT32类型。
segment_path：分片的存储路径，STRING类型。
max_timestamp：分片内文档的最大时间戳，STRING类型。
min_timestamp：分片内文档的最小时间戳，STRING类型。
index_file_size：分片的存储大小，STRING类型。
index_file_size：分片内文档最大的主键值，STRING类型。
min_primary_key：分片内文档最小的主键值，STRING类型。
index_file_count：分片内文件个数，UINT32类型。
请求示例
# Example: Stats Collection ################################################## # Request: curl -X GET \ http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/stats \ -H 'Authorization:${YourToken}' \ -H 'cache-control: no-cache' ################################################## # Response: { "status": { "code": 0, "reason": "Success" }, "collection_stats": { "segment_stats": [ { "state": "SS_WRITING", "max_lsn": "0", "min_lsn": "4294967295", "doc_count": "0", "max_doc_id": "0", "min_doc_id": "0", "segment_id": 0, "segment_path": "", "max_timestamp": "0", "min_timestamp": "4294967295", "index_file_size": "3223552", "max_primary_key": "0", "min_primary_key": "4294967295", "index_file_count": "3" } ], "collection_name": "example", "collection_path": "/home/example.gxx/workspace/test/r/indices/example", "total_doc_count": "0", "total_segment_count": "1", "total_index_file_size": "7913472", "total_index_file_count": "7" } }其中：
http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
获取集合列表
获取满足条件的集合列表，当没有请求参数时，默认为获取所有集合。
请求代码
HTTP 1.1 GET /v1/collections返回值
参数
描述
status
Proxima的执行状态，详情请参见附录：通用数据类型。
collections
满足条件的集合列表。
请求示例
# Example: List Collections ################################################## # Request: curl -X GET \ http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collections \ -H 'Authorization:${YourToken}' \ -H 'cache-control: no-cache' ################################################## # Response: { "status": { "code": 0, "reason": "Success" }, "collections": [ { "uuid": "d918becac22e471db41d55050809****", "config": { "collection_name": "example", "index_column_params": [ { "column_name": "ImageVector", "data_type": "DT_VECTOR_FP32", "dimension": 8, "extra_params": [], "index_type": "IT_PROXIMA_GRAPH_INDEX" }, { "column_name": "Id", "data_type": "DT_STRING", "dimension": 0, "extra_params": [], "index_type": "IT_INVERT_INDEX" } ], "forward_column_params": [ { "column_name": "Name", "data_type": "DT_STRING", "extra_params": [] }, { "column_name": "SerialNo", "data_type": "DT_INT32", "extra_params": [] } ], "max_docs_per_segment": "1844674407370955****" }, "status": "CS_SERVING", "magic_number": "0" }, { "uuid": "620976bd0d6728bb5ad566912f45****", "config": { "collection_name": "example3", "index_column_params": [ { "column_name": "ImageVector", "data_type": "DT_VECTOR_FP32", "dimension": 8, "extra_params": [], "index_type": "IT_PROXIMA_GRAPH_INDEX" }, { "column_name": "Id", "data_type": "DT_STRING", "dimension": 0, "extra_params": [], "index_type": "IT_INVERT_INDEX" } ], "forward_column_params": [ { "column_name": "Name", "data_type": "DT_STRING", "extra_params": [] }, { "column_name": "SerialNo", "data_type": "DT_INT32", "extra_params": [] } ], "max_docs_per_segment": "1844674407370955****" }, "status": "CS_SERVING", "magic_number": "0" } ] }其中：
http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
删除集合
请求代码
HTTP 1.1 DELETE /v1/collection/<name>其中：<name>：路径参数，需要替换为实际的集合名称。
返回值
Proxima执行状态，详情请参见附录：通用数据类型。
请求示例
# Example: Delete Collection ################################################## # Request: curl -X DELETE \ http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example \ -H 'Authorization:${YourToken}' \ -H 'cache-control: no-cache' ################################################## # Response: { "code": 0, "reason": "Success" }其中：
http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
文档管理
您可以通过RESTful API方式进行文档的插入、删除、更新（写入文档接口仅限于测试使用，通过此接口写入的数据没有存储可靠性保证）等操作。
通过指定Rows[*].Row.operation_type可进行不同的文档操作，包括插入、删除和更新三种功能。
请求代码
HTTP 1.1 POST /v1/collection/<name>/index其中：<name>：路径参数，需要替换为实际的集合名称。
请求主体
参数
描述
request_id
可选，请求ID，用于与外部请求关联，STRING类型。
collection_name
可选，默认与路径参数同名，STRING类型。
row_meta
集合描述信息，RowMeta类型，包含正排列名称列表，以及索引列列表。
forward_column_params：索引列配置列表，List[IndexColumnMeta]类型。其中IndexColumnMeta配置如下：
column_name：索引列名称，STRING类型。
data_type：正排列数据类型，只能使用字符串标识，详情请参见附录：通用数据类型。
index_column_metas：索引列配置列表，List[IndexColumnMeta]类型。其中IndexColumnMeta配置如下：
rows：文档数据列表，详情请参见附录：通用数据类型。
magic_number：可选，魔数，UINT64（字符串标识的64位无符号整数）类型，用于与外部系统关联。
返回值
Proxima执行状态，详情请参见附录：通用数据类型。
请求示例
# Example: Insert document into collection ################################################## # Request: curl -X POST \ http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/index \ -H 'cache-control: no-cache' \ -H 'Authorization:${YourToken}' \ -H 'content-type: application/json' \ -d '{"collection_name":"example", "row_meta": { "forward_column_metas":[ {"column_name":"Name","data_type":"DT_STRING"}, {"column_name":"SerialNo","data_type":"DT_INT32"}, ], "index_column_metas": [{ "column_name":"ImageVector", "data_type":"DT_VECTOR_FP32", "dimension":8},{ "column_name":"Id", "data_type":"DT_STRING"}] }, "rows":[ { "primary_key":0, "operation_type":"OP_INSERT", "forward_column_values":{ "values":[{"string_value":"item1"}, {"int32_value":1}]}, "index_column_values":{ "values":[{"string_value":"[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8]"}, {"string_value":"111111"}]} }, { "primary_key":1, "operation_type":"OP_INSERT", "forward_column_values":{ "values":[{"string_value":"item2"}, {"int32_value":2}]}, "index_column_values":{ "values":[{"string_value":"[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8]"}, {"string_value":"222222"}]} }, { "primary_key":2, "operation_type":"OP_INSERT", "forward_column_values":{ "values":[{"string_value":"item3"}, {"int32_value":3}]}, "index_column_values":{ "values":[{"string_value":"[2.1, 2.2, 2.3, 2.4, 2.5, 2.6, 2.7, 2.8]"}, {"string_value":"333333"}]} }, { "primary_key":3, "operation_type":"OP_INSERT", "forward_column_values":{ "values":[{"string_value":"item4"}, {"int32_value":4}]}, "index_column_values":{ "values":[{"string_value":"[3.1, 3.2, 3.3, 3.4, 3.5, 3.6, 3.7, 3.8]"}, {"string_value":"444444"}]} } ] }' ################################################## # Response: { "code": 0, "reason": "Success" }其中：
http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
文档查询：执行JSON索引搜索
请求代码
HTTP 1.1 POST /v1/collection/<name>/query其中：name：路径参数，需要替换为实际的集合名称。
请求主体
参数
描述
collection_name
可选，默认与路径参数同名，STRING类型。
debug_mode
可选，打开调试模式，BOOL类型。取值如下：
true：打开调式模式。
false：默认值，关闭调试模式。
重要该操作会加大请求的延迟时间，请不要在生产环境中使用。
knn_param
可选，KNN（K-Nearest Neighbors）检索参数，详情请参见附录：通用数据类型中的近邻检索参数。
query_filter
可选，查询过滤条件，详情请参见附录：通用数据类型中的过滤条件参数。
query_fields
可选，Summary列表，字符串数组。
topk
Topn最近的邻居个数，UINT32类型。
返回值
参数
描述
status
查询请求状态，详情请参见附录：通用数据类型。
results
返回的文档列表。
debug_info
JSON格式的字符串表达，STRING类型。
latency_us
请求延时，单位为微秒。STRING类型。
请求示例1：不带过滤条件查询
# Example: Execute KNN Query ################################################## # Request: curl -X POST http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/query \ -H 'cache-control: no-cache' \ -H 'Authorization:${YourToken}' \ -H 'content-type: application/json' \ -d '{ "collection_name":"example", "debug_mode":true, "knn_param":{ "column_name":"ImageVector", "matrix":"[[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0], [1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]]", "batch_count":4, "dimension":8, "data_type":"DT_VECTOR_FP32", "is_linear":false, "extra_params":[ { "key":"customize_param", "value":"10" }, { "key":"customize_param2", "value":"1" }, { "key":"customize_param3", "value":"str" } ] }, "topk":10 }' | python -m json.tool ################################################## # Response: { "debug_info": "{\"query\":{\"latency\":286,\"prepare\":40,\"evaluate\":{\"execute\":168,\"latency\":232,\"merge_and_sort\":58},\"validate\":9},\"latency\":311,\"query_id\":27,\"after_process_query\":{\"latency\":0},\"before_process_query\":{\"latency\":10}}", "latency_us": "420", "results": [ { "documents": [ { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item4" } }, { "key": "SerialNo", "value": { "int32_value": 4 } } ], "primary_key": "3", "score": 42.84 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item3" } }, { "key": "SerialNo", "value": { "int32_value": 3 } } ], "primary_key": "2", "score": 67.64 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item2" } }, { "key": "SerialNo", "value": { "int32_value": 2 } } ], "primary_key": "1", "score": 108.44 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item1" } }, { "key": "SerialNo", "value": { "int32_value": 1 } } ], "primary_key": "0", "score": 165.24 } ] }, { "documents": [ { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item4" } }, { "key": "SerialNo", "value": { "int32_value": 4 } } ], "primary_key": "3", "score": 42.84 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item3" } }, { "key": "SerialNo", "value": { "int32_value": 3 } } ], "primary_key": "2", "score": 67.64 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item2" } }, { "key": "SerialNo", "value": { "int32_value": 2 } } ], "primary_key": "1", "score": 108.44 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item1" } }, { "key": "SerialNo", "value": { "int32_value": 1 } } ], "primary_key": "0", "score": 165.24 } ] }, { "documents": [ { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item4" } }, { "key": "SerialNo", "value": { "int32_value": 4 } } ], "primary_key": "3", "score": 42.84 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item3" } }, { "key": "SerialNo", "value": { "int32_value": 3 } } ], "primary_key": "2", "score": 67.64 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item2" } }, { "key": "SerialNo", "value": { "int32_value": 2 } } ], "primary_key": "1", "score": 108.44 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item1" } }, { "key": "SerialNo", "value": { "int32_value": 1 } } ], "primary_key": "0", "score": 165.24 } ] }, { "documents": [ { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item4" } }, { "key": "SerialNo", "value": { "int32_value": 4 } } ], "primary_key": "3", "score": 42.84 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item3" } }, { "key": "SerialNo", "value": { "int32_value": 3 } } ], "primary_key": "2", "score": 67.64 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item2" } }, { "key": "SerialNo", "value": { "int32_value": 2 } } ], "primary_key": "1", "score": 108.44 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item1" } }, { "key": "SerialNo", "value": { "int32_value": 1 } } ], "primary_key": "0", "score": 165.24 } ] } ], "status": { "code": 0, "reason": "Success" } }其中：
http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
请求示例2：带过滤条件查询
# Example: Execute Query with filter ################################################## # Request: curl -X POST http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/query \ -H 'cache-control: no-cache' \ -H 'Authorization:${YourToken}' \ -H 'content-type: application/json' \ -d '{ "collection_name":"example", "debug_mode":true, "knn_param":{ "column_name":"ImageVector", "matrix":"[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]", "batch_count":1, "dimension":8, "data_type":"DT_VECTOR_FP32", "is_linear":false }, "query_filter": { "filter_node": { "logic_type" : "OR", "expressions" : [ { "column_name" : "Id", "rel_type" : "EQ", "value": {"string_value" : "111111"} }, { "column_name" : "Id", "rel_type" : "EQ", "value": {"string_value" : "222222"} } ] } }, "topk":10 }' | python -m json.tool ################################################## # Response: { "debug_info": "{\"query\":{\"latency\":286,\"prepare\":40,\"evaluate\":{\"execute\":168,\"latency\":232,\"merge_and_sort\":58},\"validate\":9},\"latency\":311,\"query_id\":27,\"after_process_query\":{\"latency\":0},\"before_process_query\":{\"latency\":10}}", "latency_us": "420", "results": [ { "documents": [ { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item2" } }, { "key": "SerialNo", "value": { "int32_value": 2 } } ], "primary_key": "1", "score": 108.44 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item1" } }, { "key": "SerialNo", "value": { "int32_value": 1 } } ], "primary_key": "0", "score": 165.24 } ] } ], "status": { "code": 0, "reason": "Success" } }其中：
http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
文档查询：执行SQL检索
请求代码
HTTP 1.1 POST /v1/collection/<name>/sql其中：<name>：路径参数，需要替换为实际的集合名称。
请求主体
参数
描述
sql
SQL检索格式，STRING类型，详情请参见附录：通用数据类型。
debug_mode
可选，打开调试模式，BOOL类型。取值如下：
true：打开调式模式。
false：默认值，关闭调试模式。
重要该操作会加大请求的延迟时间，请不要在生产环境中使用。
返回值
参数
描述
status
查询请求状态，详情请参见附录：通用数据类型。
results
返回的文档列表。
debug_info
JSON格式的字符串表达，STRING类型。
latency_us
请求延时，单位为微秒。STRING类型。
请求示例
# Example: Execute SQL Query ################################################## # Request: curl -X POST http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/sql \ -H 'cache-control: no-cache' \ -H 'Authorization:${YourToken}' \ -H 'content-type: application/json' \ -d '{ "sql":"select * from example limit 10", "debug_mode":true, }' | python -m json.tool ################################################## # Response: { "debug_info": "{\"latency\":750,\"plan stage\":{\"latency\":19},\"parse stage\":{\"latency\":550},\"analyze stage\":{\"latency\":25},\"execution stage\":{\"latency\":86}}", "latency_us": "809", "results": [ { "documents": [ { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item1" } }, { "key": "SerialNo", "value": { "int32_value": 1 } } ], "primary_key": "0", "score": 0 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item2" } }, { "key": "SerialNo", "value": { "int32_value": 2 } } ], "primary_key": "1", "score": 0 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item3" } }, { "key": "SerialNo", "value": { "int32_value": 3 } } ], "primary_key": "2", "score": 0 }, { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item4" } }, { "key": "SerialNo", "value": { "int32_value": 4 } } ], "primary_key": "3", "score": 0 } ] } ], "status": { "code": 0, "reason": "Success" } }其中：
http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
根据主键查询文档
请求代码
HTTP 1.1 GET /v1/collection/{name}/doc?key=<key>其中：<key>：文档主键，UINT64类型。需要替换为实际文档主键。
返回值
参数
描述
status
查询请求状态，详情请参见附录：通用数据类型。
document
返回的指定文档，详情请参见附录：通用数据类型。
debug_info
JSON格式的字符串表达，STRING类型。
请求示例
# Example: Query document by key ################################################## # Request: curl -X GET \ 'http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima/v1/collection/example/doc?key=2' \ -H 'Authorization:${YourToken}' \ -H 'cache-control: no-cache' ################################################## # Response: { "status": { "code": 0, "reason": "Success" }, "document": { "forward_column_values": [ { "key": "Name", "value": { "string_value": "item3" } }, { "key": "SerialNo", "value": { "int32_value": 3 } } ], "primary_key": "2", "score": 0 }, "debug_info": "" }其中：
http://144963168668****.cn-hongkong.pai-eas.aliyuncs.com/api/predict/proxima：为服务接口地址调用文档链接，需要替换为目标服务的链接地址。
${YourToken}：需要替换为目标服务调用信息页面的Token地址。
附录：通用数据类型
执行状态
Status
code：服务器指定状态码，INT32类型。其中：
0表示正常执行。
非0表示执行错误，并配置reason字段，表示具体错误信息。
reason：可选，附加错误信息，STRING类型。
索引列数据类型
knn
DataTypes：可选，标识索引列类型，STRING类型。取值如下：
DT_VECTOR_BINARY32：多维向量类型，每一维数据为32位二进制数据。
DT_VECTOR_BINARY64：多维向量类型，每一维数据为64位二进制数据。
DT_VECTOR_FP16：多维向量类型，每一维数据为32位浮点数。
DT_VECTOR_INT8：多维向量类型，每一维数据为8位有符号整数。
invert
DataTypes：可选，标识索引列类型，STRING类型。取值如下：
DT_DT_STRING：字符串类型。
DT_INT32：32位有符号整数。
DT_UINT32：32位无符号整数。
DT_INT64：64位有符号整数。
DT_UINT64：64位无符号整数。
正排列数据类型
ForwardDataTypes：可选，标识正排列类型，STRING类型。取值如下：
DT_INT8：8位有符号整数。
DT_UINT8：8位无符号整数。
DT_INT16：16位有符号整数。
DT_UINT16：16位无符号整数。
DT_INT32：32位有符号整数。
DT_UINT32：32位无符号整数。
DT_INT64：64位有符号整数。
DT_UINT64：64位无符号整数。
DT_FLOAT：32位浮点数。
DT_DOUBLE：64位浮点数。
DT_STRING：字符串类型。
文档数据
Row
primary_key：可选，文档主键，UINT64类型。
operation_type：字符串标识的操作类型，STRING类型，取值如下：
OP_INSERT：将该文档做插入操作。
OP_UPDATE：更新主键为primary_key的文档。
OP_DELETE：删除主键为primary_key的文档。
index_column_values：向量列数据。
values：取值如下：
bytes_value：Base64位编码后的向量数据，STRING类型。
string_value：Json字符串格式的向量数据，STRING。与bytes_value二选一即可。
forward_column_values：正排列数据。
values：正排数据列表，通过不同的主键标识数据类型，取值如下：
bytes_value：Base64位编码后的二进制数据，STRING类型。
string_value：字符串数据，STRING类型。
bool_value：布尔型数据，BOOL类型。支持选择TRUE或FALSE。
int32_value：32位有符号整数，INT32类型。
int64_value：字符串标识的64位有符号整数，STRING类型。
uint32_value：32位无符号整数，UINT32类型。
uint64_value：字符串标识的64位无符号整数，UINT64类型。
float_value：32位浮点数，FLOAT类型。
double_value：32位浮点数，DOUBLE类型。
lsn_context：可选，文档上下文，用于标识唯一的来源，一般用于数据同步场景。
示例一：Base64编码的向量数据
{
"index_column_values":{
"values":[
{
"bytes_value":"P4AAAEAAAABAQAAAQIAAAECgAABAwAAAQOAAAEEAAAA="
}
]
},
"forward_column_values":{
"values":[
{
"int64_value":"1"
},
{
"float_value":1.1
}
]
}
}示例二： json字符串格式向量数据
{
"index_column_values":{
"values":[
{
"string_value":"[1.0, 2.0, 3.0, 4.0, 5.0, 6.0, 7.0, 8.0]"
}
]
},
"forward_column_values":{
"values":[
{
"int64_value":"1"
},
{
"float_value":1.1
}
]
}
}近邻检索参数
KnnQueryParam
column_name：索引列名称，STRING类型。
请求向量列表，以下参数二选一即可：
matrix：Json格式的向量请求列表，可以发多个，格式为：List[List[String]...]。
features：字符串标识的请求向量（需Base64编码），如果是批量请求，需连续编码无间隔字符，STRING类型。
batch_count：批量请求个数，UINT32类型。
dimension：向量维度，UINT32类型。
data_type：详情请参见该章节中的索引列数据类型介绍。
radius：搜索半径，不同距离函数下搜索半径取值不同，FLOAT类型。
is_linear：线性搜索标志，BOOL类型。
extra_params：附加搜索参数，Map[String, String]类型。目前支持post_filter_topk。
post_filter_topk：开启后置过滤模式，指定后置过滤后返回的结果数量，UINT32类型。
过滤条件参数
query_filter
filter_node：过滤节点。
filter_node
filter_node：表达式或节点之间关系，支持选择AND或OR。
expressions：过滤条件叶子节点表达式。
filter_nodes：过滤条件中间节点。
expressions
column_name：比较列名，STRING类型。
rel_type ：比较算符，取值为：EQ、NE、GT、LT、GE、LE或LIKE。
说明倒排条件仅支持EQ。
value ：比较值。
SQL检索格式
语法
#SELECT:
SELECT { | columnName ["," columnName ] }FROM CollectionName[ WHERE FilterExpression ][ ORDER BY columnName [DESC] ][ LIMIT number]其中语句结构定义如下：
columnName：Indentifier。
FilterExpression：LogicExpr。
LogicExpr：LogicExpr AND LogicExpr | LogicExpr OR LogicExpr | “(” logic_expr “)” | RelationExpr。
RelationExpr：columnName {“=” | “!=” | >” | “>=” | “<” | “<=” | “LIKE”} ValueExpr。
ValueExpr：Numeric | String | TRUE | FALSE | Vector | Matrix | Function。
Vector：“[” Numeric [“,” Numeric ]* “]”。
Matrix：“[” Vector [“,” Vector ]* “]”。
Numeric：int_value | float_value。
String：“’” character [character]* “’”。
Function：FuncName “(” param [, param ]* “)”。
FuncName：Indentifier。
限制
目前Order By只支持单列。
过滤条件支持除BINARY以外的类型，Like用于STRING比较。
目前函数只支持Feature函数，参数取值如下：
vector或matrix：表示向量值。
data_type：可选，向量值类型。
dimension：可选，维度。
扩展字段：可选，KVPair字符串，格式为key=value，以半角分号（;）分隔。取值如下：
radius：可选，半径。
is_linear：可选，是否线性。
使用示例
查询所有文档
select * from Plants;查询指定字段
select Price, Description from Plants;根据向量条件查询
select * from Plants where ImageVector=[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8];根据多向量条件查询
select * from Plants where ImageVector=[[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8],[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8]];根据正排条件查询
select * from Plants where Price=1.1 or Price=2.1;其中：Price为正排列。
根据倒排条件查询
select * from Plants where Name='item1';其中：Name为倒排列。
倒排和正排
select * from Plants where Name='item1' and (Price=1.1 or Price=2.1);向量条件、倒排、正排、排序和limit
select Price from Plants where ImageVector=[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8] and Name='item1' and (Price=1.1 or Price=2.1) order by Price limit 10;向量feature函数
select Price from Plants where ImageVector=feature([1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8], 'VECTOR_FP32', 8, 'radius=0.1;is_linear=false');多向量feature函数
select Price from Plants where Imor=feature([[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8],[1.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8]], 'VECTOR_FP32', 8, 'radius=0.1;is_linear=false');ageVect
向量正倒排条件规则
根据以上描述可以看到，向量、正排和倒排查询条件通过and或or混合在一起，所有用于检索的条件只支持两种情况：
单个条件（向量、倒排或正排）。
多个条件时需要满足以下规则：
向量条件至多只能有一个，且不能是or语句。
如果没有向量条件，则倒排检索条件至多只能有一个，且不能是or语句；如果存在向量条件，倒排检索条件可以有多个，需要满足以下规则。
所有倒排检索条件只能属于某一个子树（不一定是顶层子树）；该子树只能包含倒排条件，不能混合向量或正排条件；该子树整体不能是or语句，但子树内部可以存在or。
例如：Feature为向量列，A~Z为倒排列，a~z为正排列。
Feature=[]
合法。
Feature=[] and Feature2=[]
非法，存在多个向量列。
Feature=[] and A=1 and B=2 and C=3
合法，所有倒排条件都在一个子树。第一个and作为树根，将条件分为两个子树，右子树仅包含倒排条件。
Feature=[] and A=1 and B=2 or C=3
非法，由于or的优先级低，or将此条件划分成为两个子树，倒排条件存在于多个子树。
A=1 and B=2 and C=3 and Feature=[]
非法，第一个and作为树根，将条件分为两个子树，右子树即包含倒排条件又包含非倒排条件（向量条件）。
(A=1 and B=2 or C=3) and Feature=[]
合法，所有倒排条件都在一个子树，子树内部可以存在or。
Feature=[] and (A=1 and B=2 or C=3) and a=1
合法，所有倒排条件都在一个子树。
Feature=[] and (A=1 and B=2 or C=3) and a=1 and D=4
非法，倒排条件存在于多个子树，这里（A=1 and B=2 or C=3）和D=4存在于不同的子树中。如果认为所有倒排条件都存在于顶层右子树，但这个右子树中包含a=1的非向量条件。
a=1 and Feature=[] and b=2 and (A=1 and B=2 or C=3) and c=3
合法，由于括号的限定，(A=1 and B=2 or C=3) 存在于一个单独的子树中，子树内部可以包含or。
a=1 and Feature=[] and (b=2 or (A=1 and B=2 or C=3) and c=3)
非法，倒排子树不能包含or，这里（A=1 and B=2 or C=3）整体是or的子语句。
为了简化理解和实现，条件中的列同时存在正排和倒排时，如果符合倒排条件要求（仅判断相等），则只被认为是倒排条件。在倒排条件不符合以上情况时，则认为其非法并尝试重新进行分析。
文档
Documents
score：评分，FLOAT类型。
primary_key：字符串格式的64位整数，UINT64类型。
forward_column_values：List[正排字段,...]类型。
正排字段
Property
key：属性名称，STRING类型。
value：可变属性值。
相关文档
更多关于EAS的内容介绍，请参见模型在线服务（EAS）。