文档

BeRead

更新时间:

调用BeRead接口获取智能召回引擎的召回结果。

接口说明

  • 读接口需要确保对应的服务(biz)处于运行状态。

请求语法

GET /be HTTP/1.1
Authorization: Basic $(base64_encode({username}:{password}))
Host: beEndpoint

其中,usernamepassword在控制台上设置,beEndpoint在用户密码设置完成后在控制台上获取,格式为${instanceId}.be.aliyuncs.com。

请求参数

  • 参数列表

参数名称

数据类型

是否必填

示例值

描述

biz_name

String

searcher

固定参数,取值为searcher

p

String

test_biz

服务名称,为要请求的服务名

s

String

test_biz

服务名称,为要请求的服务名,和p取值一致

return_count

Integer

10

召回返回的doc个数。详情见return_count

outfmt

String

json2

固定参数,表示返回结果的格式,取值为json2

trigger_list

String

trigger_key:1,trigger_key2:1.5

trigger列表,召回引擎会返回trigger关联的doc列表。详情见trigger_list

score_rule

String

score*1.5

打分表达式,根据表达式为召回的doc打分。详情见score_rule

filter_rule

String

filed1='value1' and fileld2>10

过滤表达式,根据表达式将不符合表达式的doc过滤。详情见filter_rule

user_id

String

user01,user02

行为过滤的trigger列表。对于配置了行为过滤的biz,添加该参数会从行为表中找到user_id对应的item_id列表,从召回结果中过滤掉。详情见user_id

return_count

  • 召回返回的总doc个数。

  • 对于多路召回,可以指定每一路的召回个数,单路的召回参数名为${recall_name}_return_count。

  • 多路召回会优先返回优先级高的召回结果集。

  • 例如,return_count为10,x2i的return_count为8,vector的return为5,则在各路召回数量都充足的情况下,10个结果中,前8个为x2i返回的结果,后2个为vector返回的结果,当前面召回链路返回结果集不足时,会从后面召回链路补充。有可能出现召回结果不足的情况,如x2i只召回出2个结果,vector召回结果充足,则只会召回7个结果,其中前2个为x2i返回的结果,后5个为vector返回的结果。

trigger_list

  • x2i召回:为召回引擎中trigger的值,多个trigger用','分割。其中每个trigger需要带上打分的加权值,类型为数值型,以':'分割。例如"trigger_key:1,trigger_key2:1.5",表示需要召回trigger_key1和trigger_key2关联的doc列表,其中trigger_key1召回的doc的得分最终会乘权重值1,trigger_key2召回的doc得分最终会乘权重值1.5。

  • 向量召回:为向量对应维度的向量,向量维度间用','分割,多个向量用';'分割。

  • 多路召回:对于多路召回,触发trigger的参数名为${recall_name}_trigger_list。例如多路召回中,x2i召回的召回名为x2i_recall,trigger列表参数为x2i_recall_trigger_list;向量召回的召回名为vector_recall,trigger列表参数为vector_recall_trigger_list。

x2i example

...&trigger_list=trigger_key:1,trigger_key2:1.5&...

向量 example

...&trigger_list=-0.5430353283882141,-0.0292476424574852,-0.3608616292476654;-0.35043397545814514,-0.23355364799499512,-0.24787241220474243&...

多路召回 example

...&x2i_recall_trigger_list=trigger_key:1,trigger_key2:1.5&...&vector_recall_trigger_list=-0.5430353283882141,-0.0292476424574852,-0.3608616292476654;-0.35043397545814514,-0.23355364799499512,-0.24787241220474243&...

score_rule

  • x2i召回:

  • 对于x2i类型的召回服务,智能召回引擎默认的打分逻辑是召回doc的score(doc_score)乘以trigger的权重(trigger_weight),得到最终的doc分数。

  • score_rule参数允许用户自定义打分逻辑覆盖默认的打分逻辑,自定义打分逻辑以算数表达式表示,表达式可以使用表中已有的数值类型字段打分。

  • 向量召回:

  • 对于向量类型的召回服务,智能召回引擎的默认打分逻辑是计算trigger向量和doc向量的距离得到一个表示向量距离的得分match_score。

  • score_rule在向量召回的场景同x2i场景类似。在向量召回场景下,用户可以使用match_score字段做为自定义打分的参数。

  • 多路召回:

  • 对于多路召回,打分的参数名为${recall_name}_score_rule。例如多路召回中,x2i召回的召回名为x2i_recall,打分参数为x2i_recall_score_rule;向量召回的召回名为vector_recall,trigger列表参数为vector_recall_score_rule。

  • 多路召回中,对应召回的score_rule仅在各自召链路中生效。不同召回链路间按其优先级排序。例如多路召回指定return_count为10,其中x2i路return_count为5,vector路return_count为5,则前5个结果为x2i召回出的结果,后5个为vector召回出的结果,score_rule的打分结果在各个召回链路内部排序生效。

注意事项:

  • score_rule参数需要使用url encode。

  • 对于多个trigger召回相同doc的场景,doc的得分取最高的打分结果。

  • 用户需要保证score_rule能够正确执行运算,避免出现无法运算的场景(如使用string类型的字段运算打分逻辑),可能会导致召回出错。

  • 数值类型的字段需要转换成double进行运算,可以在score_rule参数中对数值类型进行强制类型转换。如weight字段为int类型,直接运算会报转换错误,score_rule可以写为score*double(weight)

x2i example

...&score_rule=score%2Aweight%2A2&...
// score*weight*2,使用召回表中score字段的值,乘以weight字段的值,乘以2得到最终得分。

vector exmaple

...&score_rule=match_score%2Aweight%2A2&...
//match_score*weight*2,使用向量距离得分match_score的值,乘以weight字段的值,再乘以2得到最终的得分,其中match_score为计算得到的向量距离得分。

多路召回 example

...&xi2_recall_score_rule=score%2Aweight%2A2&...&vector_recall_score_rule=match_score%2Aweight%2A2&...

filter_rule

filter_rule参数允许用户自定义过滤条件,将不满足过滤条件的doc过滤掉。

filter_rule表达式规则满足一般的条件判断表达式规则。

条件判断运算符支持“=”(等于)、“!=”(不等于)、“<”(小于)、“>”(大于)、“<=”(小于等于)、“>=”(大于等于),多个条件判断表达式支持使用“AND”、“OR”逻辑运算符链接(逻辑运算符为大写字母),同时是指使用“()”(括号为英文半角)保证子表达式的优先级。

在filter_rule中,字段名需要确保存在于表字段中,字符串需要使用“'”,否则该字符串会被认为是一个字段名。

filter_rule参数需要使用url encode。

example

...&filter_rule=score%3E1.0&...  
score>1.0,过滤score值大于1.0的doc

...&filter_rule=score%3E1.0%20and%20city%3D%27hangzhou%27&... 
score>1.0 AND city='hangzhou',过滤score值大于1.0,并且city为“hangzhou”的doc

...&filter_rule=score%3E1.0%20and%20%28city%3D%27hangzhou%27%20or%20city%3D%27beijing%27%29&... 
score>1.0 AND (city='hangzhou' OR city='beijing'),过滤score值大于1.0,并且city为“hangzhou”或“beijing”的doc

user_id

对于配置了行为过滤的biz,添加该参数会从行为表中找到user_id对应的item_id列表,从召回结果中过滤掉。

user_id支持传入多值,使用','分割

每个user_id保留最多5000个item_id,优先保留最近时间的行为数据,超过5000条的历史行为会被丢弃掉。

返回数据

返回结果为JSON格式,返回字段如下:

errorCode: 请求错误码,成功为0

errorMessage: 请求错误详情

matchItems:召回结果集

  • fieldNames:召回字段列表

  • fieldValues:召回doc内容列表

示例

  • 请求示例GET

GET /be?biz_name=searcher&p=test_x2i_biz&s=test_x2i_biz&return_count=10&outfmt=json2&trigger_list=trigger_key:1,trigger_key2:1.5
Header:
{
    "Authorization"="Basic authcontent",
    "Host": be-cn-xxxx.be.aliyuncs.com
}
  • 正常返回示例

Header:
{
    "Server" : "nginx/1.6.1", 
    "Connection" : "close", 
    "Date" : "Tue, 24 Aug 2021 14:24:08 GMT", 
    "Content-Type" : "text/html; charset=utf-8"
}
Body:
{
    "errorCode":0,
    "errorMessage":"none",
    "matchItems":{
        "fieldNames":[
            "__score__",
            "title",
            "id",
            "match_type",
            "score",
            "trigger_id",
            "trigger_score"
        ],
        "fieldValues":[
            [
                "1.0",
                "title_1",
                "3489628730026797560",
                "1",
                "0.000009883646271191537",
                "indexall_common",
                "1.0"
            ],
            [
                "1.0",
                "title_2",
                "-3094066460264965022",
                "1",
                "0.000005524287644220749",
                "indexall_common",
                "1.0"
            ]
        ]
    }
}
  • 本页导读 (0)