Skip to content
Permalink
Browse files
enhance the doc for personal rank & add a simple case (#92)
  • Loading branch information
imbajin committed Dec 23, 2021
1 parent b341664 commit b9c38077867c4a05828de354bfee7279eb75e4ab
Showing 3 changed files with 51 additions and 38 deletions.
@@ -7,10 +7,17 @@ HugeGraphServer 除了上一节提到的遍历(traverser)方法,还提供

#### 4.2.1 Personal Rank API

Personal Rank 算法典型场景是用于推荐应用中, 根据某个点现有的出边, 推荐具有相近 / 相同关系的其他点,
比如根据某个人的阅读记录 / 习惯, 向它推荐其他可能感兴趣的书, 或潜在的书友, 举例如下:
1. 假设给定 1个 Person 点 是 tom, 它喜欢 `a,b,c,d,e` 5本书, 我们的想给 tom 推荐一些书友, 以及一些书, 最容易的想法就是看看还有哪些人喜欢过这些书 (共同兴趣)
2. 那么此时, 需要有其它的 Person 点比如 neo, 他喜欢 `b,d,f` 3本书, 以及 jay, 它喜欢 `c,d,e,g` 4本书, lee 它喜欢 `a,d,e,f` 4本书
3. 由于 tom 已经看过的书不需要重复推荐, 所以返回结果里应该期望推荐有共同喜好的其他书友看过, 但 tom 没看过的书, 比如推荐 "f" 和 "g" 书, 且优先级 f > g
4. 此时再计算 tom 的个性化 rank 值, 就会返回排序后 TopN 推荐的 书友 + 书 的结果了 (如果只需要推荐的书, 选择 OTHER_LABEL 即可)

##### 4.2.1.0 数据准备

这里以[MovieLens](https://grouplens.org/datasets/movielens/)的 1M 数据集为例,用户需
下载该数据集,然后使用 HugeGraph-Loader 导入到 HugeGraph 中,为简单起见,数据中顶点 user
上面是一个简单的例子, 这里再提供一个公开的 1MB 测试数据集 [MovieLens](https://grouplens.org/datasets/movielens/) 为例,
用户需下载该数据集,然后使用 HugeGraph-Loader 导入到 HugeGraph 中,简单起见,数据中顶点 user
和 movie 的属性都忽略,仅使用 id 字段即可,边 rating 的具体评分值也忽略。loader 使用的元数据
文件和输入源映射文件内容如下:

@@ -110,25 +117,29 @@ schema.edgeLabel("rating")
假设有一个用户和物品的二分图,基于随机游走的 PersonalRank 算法步骤如下:

1. 选定一个起点用户 u,其初始权重为 1.0,从 Vu 开始游走(有 alpha 的概率走到邻居点,1 - alpha 的概率停留);
2. 如果决定游走
2.1. 那就从当前节点的邻居节点中按照均匀分布随机选择一个,并且按照均匀分布划分权重值;
2.2. 给源顶点补偿权重 1 - alpha;
2.3. 重复步骤2;
3. 达到一定步数后收敛,得到推荐列表。
2. 如果决定向外游走, 那么会选取某一个类型的出边, 例如 `rating` 来查找共同的打分人
1. 那就从当前节点的邻居节点中按照均匀分布随机选择一个,并且按照均匀分布划分权重值;
2. 给源顶点补偿权重 1 - alpha;
3. 重复步骤2;
3. 达到一定步数或达到精度后收敛,得到推荐列表。

###### Params

- source: 源顶点 id,必填项
- label: 边的类型,必须是连接两类不同顶点的边,必填项
- alpha:每轮迭代时从某个点往外走的概率,与 PageRank 算法中的 alpha 类似,必填项,取值区间为 (0, 1]
- max_degree: 查询过程中,单个顶点遍历的最大邻接边数目,选填项,默认为 10000
- max_depth: 迭代次数,必填项,取值区间为 (0, 50]
- with_label:筛选结果中保留哪些结果,选填项,可选值为 [SAME_LABEL, OTHER_LABEL, BOTH_LABEL], 默认为 BOTH_LABEL
- SAME_LABEL:保留与源顶点相同类别的顶点
- OTHER_LABEL:保留与源顶点不同类别(二分图的另一端)的顶点
- BOTH_LABEL:保留与源顶点相同和相反类别的顶点
- limit: 返回的顶点的最大数目,选填项,默认为 10000000
- sorted:返回的结果是否根据 rank 排序,为 true 时降序排列,反之不排序,选填项,默认为 true
**必填项**:
- source: 源顶点 id
- label: 源点出发的某类边 label,须连接两类不同顶点

**选填项**:
- alpha:每轮迭代时从某个点往外走的概率,与 PageRank 算法中的 alpha 类似,取值区间为 (0, 1], 默认值 `0.85`
- max_degree: 查询过程中,单个顶点遍历的最大邻接边数目,默认为 `10000`
- max_depth: 迭代次数,取值区间为 [2, 50], 默认值 `5`
- with_label:筛选结果中保留哪些结果,可选以下三类, 默认为 `BOTH_LABEL`
- SAME_LABEL:仅保留与源顶点相同类别的顶点
- OTHER_LABEL:仅保留与源顶点不同类别(二分图的另一端)的顶点
- BOTH_LABEL:同时保留与源顶点相同和相反类别的顶点
- limit: 返回的顶点的最大数目,默认为 `100`
- max_diff: 提前收敛的精度差, 默认为 `0.0001` (*后续实现*)
- sorted:返回的结果是否根据 rank 排序,为 true 时降序排列,反之不排序,默认为 `true`

##### 4.2.1.2 使用方法

@@ -179,7 +190,9 @@ POST http://localhost:8080/graphs/hugegraph/traversers/personalrank

两类不同顶点连接形成的二分图中,给某个点推荐相关性最高的其他顶点,例如:

- 商品推荐中,查找最应该给某人推荐的商品列表
- 阅读推荐: 找出优先给某人推荐的其他**书籍**, 也可以同时推荐共同喜好最高的**书友** (例: 微信 "你的好友也在看 xx 文章" 功能)
- 社交推荐: 找出拥有相同关注话题的其他**博主**, 也可以推荐可能感兴趣的**新闻/消息** (例: Weibo 中的 "热点推荐" 功能)
- 商品推荐: 通过某人现在的购物习惯, 找出应优先推给它的**商品列表**, 也可以给它推荐**带货**播主 (例: TaoBao 的 "猜你喜欢" 功能)

#### 4.2.2 Neighbor Rank API

@@ -248,20 +248,20 @@ GET http://localhost:8080/graphs/{graph}/traversers/kout?source="1:marko"&max_de

- source:起始顶点id,必填项
- 从起始点出发的Step,必填项,结构如下:
- direction:表示边的方向(OUT,IN,BOTH),默认是BOTH
- labels:边的类型列表
- properties:通过属性的值过滤边
- max_degree:查询过程中,单个顶点遍历的最大邻接边数目,默认为 10000 (注: 0.12版之前 step 内仅支持 degree 作为参数名, 0.12开始统一使用 max_degree, 并向下兼容 degree 写法)
- skip_degree:用于设置查询过程中舍弃超级顶点的最小边数,即当某个顶点的邻接边数目大于 skip_degree 时,完全舍弃该顶点。选填项,如果开启时,需满足 `skip_degree >= max_degree` 约束,默认为0 (不启用),表示不跳过任何点 (注意: 开启此配置后,遍历时会尝试访问一个顶点的 skip_degree 条边,而不仅仅是 max_degree 条边,这样有额外的遍历开销,对查询性能影响可能有较大影响,请确认理解后再开启)
- direction:表示边的方向(OUT,IN,BOTH),默认是BOTH
- labels:边的类型列表
- properties:通过属性的值过滤边
- max_degree:查询过程中,单个顶点遍历的最大邻接边数目,默认为 10000 (注: 0.12版之前 step 内仅支持 degree 作为参数名, 0.12开始统一使用 max_degree, 并向下兼容 degree 写法)
- skip_degree:用于设置查询过程中舍弃超级顶点的最小边数,即当某个顶点的邻接边数目大于 skip_degree 时,完全舍弃该顶点。选填项,如果开启时,需满足 `skip_degree >= max_degree` 约束,默认为0 (不启用),表示不跳过任何点 (注意: 开启此配置后,遍历时会尝试访问一个顶点的 skip_degree 条边,而不仅仅是 max_degree 条边,这样有额外的遍历开销,对查询性能影响可能有较大影响,请确认理解后再开启)
- max_depth:步数,必填项
- nearest:nearest为true时,代表起始顶点到达结果顶点的最短路径长度为depth,不存在更短的路径;nearest为false时,代表起始顶点到结果顶点有一条长度为depth的路径(未必最短且可以有环),选填项,默认为true
- count_only:Boolean值,true表示只统计结果的数目,不返回具体结果;false表示返回具体的结果,默认为false
- with_path:true表示返回起始点到每个邻居的最短路径,false表示不返回起始点到每个邻居的最短路径,选填项,默认为false
- with_vertex,选填项,默认为false:
- true表示返回结果包含完整的顶点信息(路径中的全部顶点)
- with_path为true时,返回所有路径中的顶点的完整信息
- with_path为false时,返回所有邻居的完整信息
- false时表示只返回顶点id
- true表示返回结果包含完整的顶点信息(路径中的全部顶点)
- with_path为true时,返回所有路径中的顶点的完整信息
- with_path为false时,返回所有邻居的完整信息
- false时表示只返回顶点id
- capacity:遍历过程中最大的访问的顶点数目,选填项,默认为10000000
- limit:返回的顶点的最大数目,选填项,默认为10000000

@@ -450,19 +450,19 @@ GET http://localhost:8080/graphs/{graph}/traversers/kneighbor?source=“1:marko

- source:起始顶点id,必填项
- 从起始点出发的Step,必填项,结构如下:
- direction:表示边的方向(OUT,IN,BOTH),默认是BOTH
- labels:边的类型列表
- properties:通过属性的值过滤边
- max_degree:查询过程中,单个顶点遍历的最大邻接边数目,默认为 10000 (注: 0.12版之前 step 内仅支持 degree 作为参数名, 0.12开始统一使用 max_degree, 并向下兼容 degree 写法)
- skip_degree:用于设置查询过程中舍弃超级顶点的最小边数,即当某个顶点的邻接边数目大于 skip_degree 时,完全舍弃该顶点。选填项,如果开启时,需满足 `skip_degree >= max_degree` 约束,默认为0 (不启用),表示不跳过任何点 (注意: 开启此配置后,遍历时会尝试访问一个顶点的 skip_degree 条边,而不仅仅是 max_degree 条边,这样有额外的遍历开销,对查询性能影响可能有较大影响,请确认理解后再开启)
- direction:表示边的方向(OUT,IN,BOTH),默认是BOTH
- labels:边的类型列表
- properties:通过属性的值过滤边
- max_degree:查询过程中,单个顶点遍历的最大邻接边数目,默认为 10000 (注: 0.12版之前 step 内仅支持 degree 作为参数名, 0.12开始统一使用 max_degree, 并向下兼容 degree 写法)
- skip_degree:用于设置查询过程中舍弃超级顶点的最小边数,即当某个顶点的邻接边数目大于 skip_degree 时,完全舍弃该顶点。选填项,如果开启时,需满足 `skip_degree >= max_degree` 约束,默认为0 (不启用),表示不跳过任何点 (注意: 开启此配置后,遍历时会尝试访问一个顶点的 skip_degree 条边,而不仅仅是 max_degree 条边,这样有额外的遍历开销,对查询性能影响可能有较大影响,请确认理解后再开启)
- max_depth:步数,必填项
- count_only:Boolean值,true表示只统计结果的数目,不返回具体结果;false表示返回具体的结果,默认为false
- with_path:true表示返回起始点到每个邻居的最短路径,false表示不返回起始点到每个邻居的最短路径,选填项,默认为false
- with_vertex,选填项,默认为false:
- true表示返回结果包含完整的顶点信息(路径中的全部顶点)
- with_path为true时,返回所有路径中的顶点的完整信息
- with_path为false时,返回所有邻居的完整信息
- false时表示只返回顶点id
- true表示返回结果包含完整的顶点信息(路径中的全部顶点)
- with_path为true时,返回所有路径中的顶点的完整信息
- with_path为false时,返回所有邻居的完整信息
- false时表示只返回顶点id
- limit:返回的顶点的最大数目,选填项,默认为10000000

##### 3.2.4.2 使用方法
@@ -1,5 +1,5 @@
#!/bin/bash

set -x
# this script is for developers to manually deploy doc to GitHub Pages
REMOTE="github"
REMOTE_URL="https://github.com/hugegraph/hugegraph-doc"

0 comments on commit b9c3807

Please sign in to comment.