软件遗产 - 图服务

概述

swh_graph 是一个库和服务器，允许通过使用基于 软件遗产 DAG 的内存压缩表示来快速遍历查询 软件遗产存档，该表示基于 webgraph。

这个库和服务器最初是用 Java 编写的；本文档描述了 Rust 重写版本，它实现了相同的概念和算法，但更简洁、更快。

每个节点都由一个整数标识，从 0 到 n-1，其中 n 是图中节点的总数

提供的 API 是

• 给定一个 SWHID v1.1 返回一个节点 ID，反之亦然
• 同样，对于原始数据，编码为 swh:1:ori:$hash，其中 $hash 是原始 URL 的 SHA1 哈希值
• 给定一个节点 ID，列出其所有后继节点，例如目录中的所有条目，或修订/提交的所有父节点（注意，在作为图中的有向弧时，“父修订”被视为后继节点）。一些弧可能具有标签，例如目录条目或分支的名称。
• 给定一个节点 ID，列出其所有前驱节点，例如包含给定目录条目的所有目录，或修订/提交的所有子节点。一些弧也可能有标签。
• 给定一个节点 ID，返回此节点的属性，例如
  • 其类型
  • 如果节点是修订或发布，则消息或日期
  • 如果节点是内容，则长度

swh_graph 还提供了一些递归遍历查询的实现，作为 gRPC API 的一部分

如果您已经熟悉 Java API，请参阅 教程 或 快速入门。

构建分发版

依赖项

代码需要稳定的Rust版本 >= 1.79，因为我们依赖于webgraph使用了关联类型界限。

如果您想使用--features=grpc-server来构建，还需要安装protoc（在Debian上使用apt-get install protobuf-compiler）。

分发

要分发可执行文件，您可以静态编译代码

RUSTFLAGS="-C target-cpu=x86-64-v3" cargo build --release --target x86_64-unknown-linux-musl

要添加目标使用

rustup target add x86_64-unknown-linux-musl

目标-cpu将限制兼容的CPU，但将启用更多优化。一些有趣的架构包括

• native表示编译的CPU架构，当您在同一台机器上编译和运行时，这是性能的最佳选项。
• x86-64-v3用于Intel Haswell和更新的（2013年），支持AVX2和BMI2指令的最老架构。
• x86-64-v2用于Intel Core 2和更新的（2006年），最合理的编译架构。

性能考虑

在每次随机访问时，我们需要查询Elias-Fano数据结构来找到给定节点代码开始的位偏移。此操作必须在给定内存单词中找到第i个。

在sux-rs中的实现可以利用pdep指令来加速操作。因此，使用pdep功能编译代码非常重要，并通常通过使用RUSTFLAGS环境变量来针对预期的CPU架构进行编译

RUSTFLAGS="-C target-cpu=native" cargo run --release --bin bfs

此编译针对编译的CPU架构。

因此，默认情况下在.cargo/config.toml文件中启用。请注意，使用pdep启用编译的文件将无法在不支持它的CPU上运行。通常，在另一台机器上运行使用给定CPU特征集编译的二进制文件将导致SIGILL（非法指令）错误。

测试的最小设置

以下是您需要执行此包中的Python测试的最小设置。这不是生产部署的推荐构建过程！

1. 安装二进制依赖项

swh-graph$ sudo apt install protobuf-compiler
swh-graph$ curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

由于Debian稳定版（bookworm）仅提供rust 1.63，因此从上游安装Rust编译器。

2. 编译二进制资源

swh-graph$ cargo build --all-features

这将在本地目录target/debug中构建二进制资源。检查swh-graph-grpc-serve是否存在于那里并且可以正确执行。

swh-graph$ ./target/debug/swh-graph-grpc-serve --help
gRPC server for the compressed Software Heritage graph

Usage: swh-graph-grpc-serve [OPTIONS] <GRAPH_PATH>

Arguments:
  <GRAPH_PATH>

Options:
      --bind <BIND>                  [default: [::]:5009]
      --masked-nodes <MASKED_NODES>  A line-separated list of node SWHIDs to exclude from the graph
  -v, --verbose...
  -h, --help                         Print help

部署

下载压缩图

请参阅软件遗产数据集文档，其中列出了软件遗产存档的所有导出；其中大部分提供压缩图表示，可以使用swh_graph（尽管某些可能需要进行一些转换，见下文）加载。

在进程间共享映射数据

大多数数据文件都是mmaped。您应该预先将它们加载到内存中，以确保它们不会被从内存缓存中淘汰。

加载旧图

WebGraph的原始Java（和C++）实现与Rust实现使用的数据结构和格式略有不同。因此，您需要生成新文件才能使用Rust实现加载旧图；对于代表完整SWH导出的图，这可能需要几个小时。

swh graph reindex命令（通过pip3 install swh.graph提供）负责运行转换。

此外，.ef格式可能会不时更改。如果您遇到此类错误

Error: Cannot map Elias-Fano pointer list ../swh/graph/example_dataset/compressed/example.ef

Caused by:
    Wrong type hash. Expected: 0x47e8ca1ab8fa94f1 Actual: 0x890ce77a9258940c.
    You are trying to deserialize a file with the wrong type.
    The serialized type is 'sux::dict::elias_fano::EliasFano<sux::rank_sel::select_fixed2::SelectFixed2<sux::bits::bit_vec::CountBitVec, alloc::vec::Vec<u64>, 8>>' and the deserialized type is 'sux::dict::elias_fano::EliasFano<sux::rank_sel::select_adapt_const::SelectAdaptConst<sux::bits::bit_vec::BitVec<alloc::boxed::Box<[usize]>>, alloc::boxed::Box<[usize]>, 12, 4>>'.

您需要运行 swh graph reindex --ef 来在您系统的当前版本上重新创建它们。