Xberg Kotlin/Android 抽取式摘要实战:基于 TextRank 的纯 Rust 文档摘要

原创2026-10-07 14:18:351,947 阅读
文章标签:后端AI 应用NLP

Xberg Kotlin/Android 抽取式摘要实战:基于 TextRank 的纯 Rust 文档摘要

导读

本文围绕 Xberg 仓库中的 Kotlin/Android 端 TextRank 抽取式摘要(extractive summarization)冒烟测试场景,讲解如何在 Android 应用中通过 Xberg.extract 一步获得多段落纯文本文档的摘要。读完本文,你将掌握 summarization 配置的完整写法与参数含义,理解抽取式摘要背后的 TextRank 图算法原理,并了解从 Rust 核心、后处理器到 Kotlin 绑定与端到端测试的完整调用链,无需任何外部服务即可获得确定性的摘要结果。

场景概述:一次调用拿到文档摘要

在 Kotlin/Android 上使用 Xberg 做抽取式摘要,本质上是在普通的文档抽取请求上叠加一个 summarization 配置段。仓库中的自动生成冒烟用例 docs-site/src/snippets-generated/kotlin-android/summarization/summarization_extractive_smoke.md 演示了这一完整流程:以一个指向多段落纯文本文档的 URI 作为输入,配置 strategy: "extractive" 与 max_tokens: 80,随后从返回结果中读取 summary 字段。

该场景对应仓库中的 fixture 定义 fixtures/summarization/extractive_smoke.json,其中声明了四个断言:请求不报错、文档 MIME 类型为 text/plain、summary.text 非空、summary.strategy 等于 extractive。它同时是对外承诺的核心语义——抽取式摘要纯 Rust 实现、完全确定性、不依赖任何外部服务。

最小可运行示例:Kotlin 侧代码

以下代码完整取自冒烟用例文档,可直接作为 Android 端调用模板:

import io.xberg.*
import com.fasterxml.jackson.module.kotlin.jacksonObjectMapper

fun main() = kotlinx.coroutines.runBlocking {
    val mapper = jacksonObjectMapper().setPropertyNamingStrategy(com.fasterxml.jackson.databind.PropertyNamingStrategies.SNAKE_CASE)
    val input = mapper.readValue("{\"kind\":\"uri\",\"uri\":\"https://example.com/text/book_war_and_peace_1p.txt\"}", ExtractInput::class.java)
    val config = mapper.readValue("{\"summarization\":{\"max_tokens\":80,\"strategy\":\"extractive\"},\"url\":{\"crawl\":{\"ssrf\":{}}}}", ExtractionConfig::class.java)
    val result = Xberg.extract(input, config)
    println(result.results.first().summary)
}

代码中有三个关键点值得拆解:

  1. JSON 反序列化与蛇形命名:绑定类(ExtractInput、ExtractionConfig)通过 Jackson 反序列化,SNAKE_CASE 命名策略让 JSON 中的 max_tokens 正确映射到 Kotlin 属性 maxTokens,而 strategy 映射为枚举 SummaryStrategy.EXTRACTIVE。这一映射关系可在生成的绑定 SummarizationConfig.kt 中确认。
  2. 输入类型:ExtractInput 的 kind 为 uri,指向一个远程纯文本文档;对应的端到端测试在真实运行时会把 $mock_url 占位符替换为本地 mock 服务器地址,见 SummarizationTest.kt。
  3. SSRF 防护显式开启:配置中的 url.crawl.ssrf 为空对象,表示启用默认的 SSRF 防护策略,保证在 Android 上抓取远程 URL 时不会访问内网地址,属于安全默认配置。

SummarizationConfig 配置详解

摘要功能的全部行为由 ExtractionConfig.summarization 控制。Rust 侧的结构体定义在 core/config/summarization.rs,Kotlin 侧绑定在 SummarizationConfig.kt,二者字段一一对应:

字段 类型 默认值 说明
strategy 枚举 extractive 摘要策略:extractive(TextRank 抽取式,纯 Rust)或 abstractive(LLM 生成式,需要 summarization-llm 特性与 LLM 配置)
max_tokens u32? null 摘要长度上限(按空白分词计)。不设置时由后端决定默认值(TextRank 实现中为 150 词)
llm LlmConfig? null 抽象式摘要专用配置。strategy = extractive 时被忽略;strategy = abstractive 时为必填,否则后处理器返回校验错误

strategy 枚举定义在 types/summary.rs:Extractive 是默认策略,对应纯 Rust 的 TextRank 实现;Abstractive 则通过共享的 LLM 文本补全通道生成。需要注意 SummarizationConfig 设置了 deny_unknown_fields,传入了不认识的字段会直接反序列化失败,写配置时务必精确匹配字段名。

抽取式摘要的底层原理:TextRank 图算法

当 strategy 为 extractive 时,实际执行的是 text/summarization/textrank.rs 中的 summarize(text, language, max_tokens)。这是一个标准的句子级 TextRank 流程,共分五步:

  1. 分句:按 .、!、? 与换行符切分文本,并折叠后续的连续标点与空白。
  2. 分词与停用词过滤:按非字母数字字符切分,转小写,剔除长度小于 2 的 token,并使用按语言加载的停用词表过滤(stopwords 内置多语言表)。
  3. 构建 TF-IDF 向量:对每个句子计算词频(TF),并以文档频率(DF)加权得到 TF-IDF 向量。
  4. 相似度建图:任意两句之间计算 TF-IDF 余弦相似度,相似度高于 MIN_EDGE_SIMILARITY = 1e-6 的边才被保留,形成无向加权图。
  5. PageRank 迭代打分:对列随机转移矩阵做阻尼幂迭代,阻尼系数 PAGERANK_DAMPING = 0.85,收敛容差 1e-4,最多迭代 64 轮;最后按预算挑选得分最高的句子,再按原文档顺序拼接输出。

实现中几个常量直接决定了摘要行为:MAX_SENTENCES = 256 限制参与计算的句子数上限(超长文档只取前 256 句,保证计算可控);DEFAULT_MAX_TOKENS = 150 是未指定 max_tokens 时的兜底预算;挑选句子时按得分降序贪婪累加 token,直至填满预算,若一条都放不下则至少保留得分最高的一句。这些常量均在 textrank.rs 中定义。

语言自适应与确定性

summarize 的 language 参数来自抽取结果中的语言检测:后处理器取 result.detected_languages 的第一个条目作为 ISO 639 语言码,用于选择停用词表;未检测到或语言码未知时回退到英语(get_stopwords_with_fallback(lang, "en"))。因为全程无随机性、无外部依赖,同一输入永远得到同一输出——textrank.rs 的单元测试 专门断言了 summarize 的确定性,并验证了单句文档原样返回、空文档返回 None、未知语言回退英文等边界行为。

后处理器机制:摘要何时被写入结果

抽取式摘要不是独立 API,而是运行在抽取流水线中的后处理器(post-processor)。其实现位于 plugins/processor/builtin/summarization.rs:

  • 触发条件:config.summarization.is_some() 时才会运行(should_process)。
  • 执行阶段:ProcessingStage::Middle——在抽取主体完成、结果正式产出之前插入。
  • 空文档短路:result.content 为空时直接跳过,不产生摘要。
  • 结果写入:把 TextRank 输出封装为 DocumentSummary { text, strategy, token_count } 挂到 ExtractedDocument.summary,token_count 由空白分词计数得出。
  • 失败告警:若抽取式摘要未能产出文本(如全为停用词),会向 processing_warnings 推入 summarization_extractive 告警,让调用方区分“未生成摘要”与“处理报错”,而不是静默丢弃。

该后处理器注册为全局默认插件(register_post_processor),因此开箱即用,无需额外初始化。

抽象式摘要:与 extractive 的对照

虽然本文场景聚焦 extractive,但 SummaryStrategy 同时定义了 abstractive 分支,理解它有助于正确选型:抽象式摘要通过 summarize_with_llm(text/summarization/llm.rs,受 summarization-llm 特性门控)调用配置的 LLM 生成全新表述。它要求 SummarizationConfig.llm 已配置,否则后处理器返回校验错误“Abstractive summarisation requires SummarizationConfig.llm to be set”;LLM 调用失败时则记录 summarization_abstractive 告警,并会把 token 用量计入 ExtractedDocument.llm_usage。

两者的取舍很清晰:extractive 零依赖、确定性、适合离线与端上场景;abstractive 表达更自然,但需要网络、模型配置与额外算力,且结果非确定性。

端到端验证与可移植性

该场景同时以三种形态存在于仓库中,互相印证:

  • 文档快照:summarization_extractive_smoke.md(本文主题文档);
  • fixture 契约:extractive_smoke.json 定义了 mock 响应(/text/book_war_and_peace_1p.txt)、输入、配置与断言;
  • 可执行测试:SummarizationTest.kt 是同一场景的 JUnit 测试,运行前通过 JNI 加载 xberg_jni 本地库,并设置 CRAWLBERG_ALLOW_PRIVATE_NETWORK=true 允许访问 mock 服务器。

此外,抽取式摘要因为不依赖任何外部服务,被编译进所有目标平台,包括 WASM 与 Android(见 text/summarization/mod.rs 的模块注释)。也就是说,同一份 summarization 配置在 REST API、CLI、MCP 服务器等其他接口上行为一致,Android 端验证通过的逻辑可以直接迁移到服务端。

小结:在 Android 项目中启用摘要的检查清单

  1. 在 ExtractionConfig 中加入 summarization 段,strategy 保持默认 extractive 或显式指定,按需设置 max_tokens;
  2. 用 Jackson 的 SNAKE_CASE 策略反序列化,确保 max_tokens 正确映射;
  3. 远程 URI 输入时保留 url.crawl.ssrf 防护配置;
  4. 从 result.results.first().summary 读取 text、strategy、token_count;
  5. 若 summary 为空,检查 processing_warnings 中是否出现 summarization_extractive 告警(通常意味着文档全为停用词或过短)。

这样,你就拥有了一个纯 Rust、确定性、无需外部服务的文档摘要能力,直接嵌入 Android 应用的文档处理链路。

登录后查看全文
xberg