diff --git a/clients/restful-api/rank.md b/clients/restful-api/rank.md index 53cf8605f..c7e682ef4 100644 --- a/clients/restful-api/rank.md +++ b/clients/restful-api/rank.md @@ -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 diff --git a/clients/restful-api/traverser.md b/clients/restful-api/traverser.md index d055ffafd..c4c9b23b7 100644 --- a/clients/restful-api/traverser.md +++ b/clients/restful-api/traverser.md @@ -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 使用方法 diff --git a/scripts/github-deploy.sh b/scripts/github-deploy.sh index c70289513..05b61def3 100644 --- a/scripts/github-deploy.sh +++ b/scripts/github-deploy.sh @@ -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"