Util-阿里云帮助中心

简介

Util类封装了一系列常用的功能型函数，比如衰减函数，归一化函数等。

函数列表

函数原型	函数简介
static double gaussDecay(double origin, double value, double scale, double decay, double offset)	使用高斯函数，根据数值和给定的起始点之间的距离，计算其衰减程度
static double gaussDecay(double origin, double value, double scale, double decay)	使用高斯函数，根据数值和给定的起始点之间的距离，计算其衰减程度
static double gaussDecay(double origin, double value, double scale)	使用高斯函数，根据数值和给定的起始点之间的距离，计算其衰减程度
static double expDecay(double origin, double value, double scale, double decay, double offset)	使用指数函数，根据数值和给定的起始点之间的距离，计算其衰减程度
static double expDecay(double origin, double value, double scale, double decay)	使用指数函数，根据数值和给定的起始点之间的距离，计算其衰减程度
static double expDecay(double origin, double value, double scale)	使用指数函数，根据数值和给定的起始点之间的距离，计算其衰减程度
static double linearDecay(double origin, double value, double scale, double decay, double offset)	使用线性函数，根据数值和给定的起始点之间的距离，计算其衰减程度
static double linearDecay(double origin, double value, double scale, double decay)	使用线性函数，根据数值和给定的起始点之间的距离，计算其衰减程度
static double linearDecay(double origin, double value, double scale)	使用线性函数，根据数值和给定的起始点之间的距离，计算其衰减程度
static double normalize(double value, double max, double min)	使用线性函数进行归一化
static double normalize(double value, double max)	使用对数函数进行归一化
static double normalize(double value)	使用反正切函数进行归一化

函数详情

static double gaussDecay(double origin, double value, double scale, double decay, double offset)

使用高斯函数，根据数值和给定的起始点之间的距离，计算其衰减程度。适用于按照数值大小进行排序，并当数值在一定范围内无需在做区分，比如查找距离用户最近的酒店，按照距离由近到远排序，并且认为距离小于100m的酒店不用做区分，假设 distanceValue为距离，函数可以写为gauss_decay(0, distanceValue, 5, 0.000001, 0.1)。

参数列表：

origin — 衰减函数的起始点，value为origin时得分为1.0。
value — 需要计算衰减程度的值。
scale — 衰减率，当value从origin下落时函数算分改变的速度。
decay — 从origin衰减到scale时的得分。
offset — 当距离大于offset时才开始计算衰减程度，origin - offset < value < origin + offset时函数返回1.0。

返回值：

返回衰减程度，取值范围为[0, 1]。

代码示例：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.gaussDecay(0.0, distanceValue, 5.0, 0.000001, 0.1);
    }
}

static double gaussDecay(double origin, double value, double scale, double decay)

同static double gaussDecay(double origin, double value, double scale, double decay, double offset)，只其中offset设置为0。

参数列表：

origin — 衰减函数的起始点，value为origin时得分为1.0。
value — 需要计算衰减程度的值。
scale — 衰减率，当value从origin下落时函数算分改变的速度。
decay — 从origin衰减到scale时的得分。

返回值：

返回衰减程度，取值范围为[0, 1]。

代码示例：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.gaussDecay(0.0, distanceValue, 5.0, 0.000001);
    }
}

static double gaussDecay(double origin, double value, double scale)

同static double gaussDecay(double origin, double value, double scale, double decay, double offset)，只其中decay设置为0.000001，offset设置为0。

参数列表：

origin — 衰减函数的起始点，value为origin时得分为1.0。
value — 需要计算衰减程度的值。
scale — 衰减率，当value从origin下落时函数算分改变的速度。

返回值：

返回衰减程度，取值范围为[0, 1]。

代码示例：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.gaussDecay(0.0, distanceValue, 5.0);
    }
}

static double expDecay(double origin, double value, double scale, double decay, double offset)

使用指数函数，根据数值和给定的起始点之间的距离，计算其衰减程度。适用场景同gaussDecay函数。

参数列表：

origin — 衰减函数的起始点，value为origin时得分为1.0。
value — 需要计算衰减程度的值。
scale — 衰减率，当value从origin下落时函数算分改变的速度。
decay — 从origin衰减到scale时的得分。
offset — 当距离大于offset时才开始计算衰减程度，origin - offset < value < origin + offset时函数返回1.0。

返回值：

返回衰减程度，取值范围为[0, 1]。

代码示例：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.expDecay(0.0, distanceValue, 5.0, 0.000001, 0.1);
    }
}

static double expDecay(double origin, double value, double scale, double decay)

同static double expDecay(double origin, double value, double scale, double decay, double offset)，其中offset设置为0。

参数列表：

origin — 衰减函数的起始点，value为origin时得分为1.0。
value — 需要计算衰减程度的值。
scale — 衰减率，当value从origin下落时函数算分改变的速度。
decay — 从origin衰减到scale时的得分。

返回值：

返回衰减程度，取值范围为[0, 1]。

代码示例：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.expDecay(0.0, distanceValue, 5.0, 0.000001);
    }
}

static double expDecay(double origin, double value, double scale)

同static double expDecay(double origin, double value, double scale, double decay, double offset)，其中decay设置为0.000001，offset设置为0。

参数列表：

origin — 衰减函数的起始点，value为origin时得分为1.0。
value — 需要计算衰减程度的值。
scale — 衰减率，当value从origin下落时函数算分改变的速度。

返回值：

返回衰减程度，取值范围为[0, 1]。

代码示例：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.expDecay(0.0, distanceValue, 5.0);
    }
}

static double linearDecay(double origin, double value, double scale, double decay, double offset)

使用线性函数，根据数值和给定的起始点之间的距离，计算其衰减程度。适用场景同gaussDecay函数。

参数列表：

origin — 衰减函数的起始点，value为origin时得分为1.0。
value — 需要计算衰减程度的值。
scale — 衰减率，当value从origin下落时函数算分改变的速度。
decay — 从origin衰减到scale时的得分。
offset — 当距离大于offset时才开始计算衰减程度，origin - offset < value < origin + offset时函数返回1.0。

返回值：

返回衰减程度，取值范围为[0, 1]。

代码示例：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.linearDecay(0.0, distanceValue, 5.0, 0.000001, 0.1);
    }
}

static double linearDecay(double origin, double value, double scale, double decay)

同static double linearDecay(double origin, double value, double scale, double decay, double offset)，其中offset设置为0。

参数列表：

origin — 衰减函数的起始点，value为origin时得分为1.0。
value — 需要计算衰减程度的值。
scale — 衰减率，当value从origin下落时函数算分改变的速度。
decay — 从origin衰减到scale时的得分。

返回值：

返回衰减程度，取值范围为[0, 1]。

代码示例：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.linearDecay(0.0, distanceValue, 5.0, 0.000001);
    }
}

static double linearDecay(double origin, double value, double scale)

同static double linearDecay(double origin, double value, double scale, double decay, double offset)，其中decay设置为0.000001，offset设置为0。

参数列表：

origin — 衰减函数的起始点，value为origin时得分为1.0。
value — 需要计算衰减程度的值。
scale — 衰减率，当value从origin下落时函数算分改变的速度。

返回值：

返回衰减程度，取值范围为[0, 1]。

代码示例：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;
import com.aliyun.opensearch.cava.features.Distance;

class BasicSimilarityScorer {
    Distance _distance;
    boolean init(OpsScorerInitParams params) {
        _distance = Distance.create(params, "location", "query_location");
        return true;
    }

    double score(OpsScoreParams params) {
        double distanceValue = _distance.evaluate(params);
        return Util.linearDecay(0.0, distanceValue, 5.0);
    }
}

static double normalize(double value, double max, double min)

使用线性函数进行归一化，公式为(value - min) / (max -min)。

参数列表：

value：需要做归一化的值。
max：value的最大值。
min：value的最小值。

返回值：

返回归一化结果，取值范围为[0, 1]，当max小于min返回0。

代码示例：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;

class BasicSimilarityScorer {
    boolean init(OpsScorerInitParams params) {
        return params.getDoc().requireAttribute("price");
    }

    double score(OpsScoreParams params) {
        OpsDoc doc = params.getDoc();
        long price = doc.docFieldLong("price");
        return Util.normalize(price, 100000.0, 0.0);
    }
}

static double normalize(double value, double max)

使用对数函数进行归一化，公式为log10(value)/log(max)。

参数列表：

value：需要做归一化的值。
max：value的最大值。

返回值：

返回归一化结果，取值范围为[0, 1]，当value和max小于1时返回0。

示例代码：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;

class BasicSimilarityScorer {
    boolean init(OpsScorerInitParams params) {
        return params.getDoc().requireAttribute("price");
    }

    double score(OpsScoreParams params) {
        OpsDoc doc = params.getDoc();
        long price = doc.docFieldLong("price");
        return Util.normalize(price, 100000.0);
    }
}

static double normalize(double value)

使用反正切函数进行归一化，公式为atan(value / 1000.0) * 2 / pi，其中pi为3.141593。

参数列表：

value：需要做归一化的值。

返回值：

返回归一化结果，取值范围为[0, 1]。

示例代码：

package users.scorer;
import com.aliyun.opensearch.cava.framework.OpsScoreParams;
import com.aliyun.opensearch.cava.framework.OpsScorerInitParams;
import com.aliyun.opensearch.cava.framework.OpsRequest;
import com.aliyun.opensearch.cava.framework.OpsDoc;
import com.aliyun.opensearch.cava.features.Util;

class BasicSimilarityScorer {
    boolean init(OpsScorerInitParams params) {
        return params.getDoc().requireAttribute("price");
    }

    double score(OpsScoreParams params) {
        OpsDoc doc = params.getDoc();
        long price = doc.docFieldLong("price");
        return Util.normalize(price);
    }
}