AimeRead

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

接口说明

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

请求语法

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

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

请求参数

• 参数列表

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。

• 向量服务：为向量对应维度的向量，向量维度间用','分割，多个向量用';'分割。

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&...

scorer_rule

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

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

score_rule参数需要使用URL encode。

example

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

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

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

score_rule参数需要使用url encode。

exmaple

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

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

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

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

filter_rule

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

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

条件判断运算符支持“=”（等于）、“!=”（不等于）、“<”（小于）、“>”（大于）、“<=”（小于等于）、“>=”（大于等于），多个条件判断表达式支持使用“and”、“or”逻辑运算符链接，同时是指使用“()”保证子表达式的优先级。

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

score_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

返回数据

返回结果为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": aime-cn-xxxx.aime.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"
            ]
        ]
    }
}