BeRead

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

​

接口说明

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

请求语法

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

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

​

请求参数

• 参数列表

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"
            ]
        ]
    }
}