Xberg Kotlin/Android 抽取式摘要实战:基于 TextRank 的纯 Rust 文档摘要
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)
}
代码中有三个关键点值得拆解:
- JSON 反序列化与蛇形命名:绑定类(
ExtractInput、ExtractionConfig)通过 Jackson 反序列化,SNAKE_CASE命名策略让 JSON 中的max_tokens正确映射到 Kotlin 属性maxTokens,而strategy映射为枚举SummaryStrategy.EXTRACTIVE。这一映射关系可在生成的绑定 SummarizationConfig.kt 中确认。 - 输入类型:
ExtractInput的kind为uri,指向一个远程纯文本文档;对应的端到端测试在真实运行时会把$mock_url占位符替换为本地 mock 服务器地址,见 SummarizationTest.kt。 - 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 流程,共分五步:
- 分句:按
.、!、?与换行符切分文本,并折叠后续的连续标点与空白。 - 分词与停用词过滤:按非字母数字字符切分,转小写,剔除长度小于 2 的 token,并使用按语言加载的停用词表过滤(stopwords 内置多语言表)。
- 构建 TF-IDF 向量:对每个句子计算词频(TF),并以文档频率(DF)加权得到 TF-IDF 向量。
- 相似度建图:任意两句之间计算 TF-IDF 余弦相似度,相似度高于
MIN_EDGE_SIMILARITY = 1e-6的边才被保留,形成无向加权图。 - 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 项目中启用摘要的检查清单
- 在
ExtractionConfig中加入summarization段,strategy保持默认extractive或显式指定,按需设置max_tokens; - 用 Jackson 的
SNAKE_CASE策略反序列化,确保max_tokens正确映射; - 远程 URI 输入时保留
url.crawl.ssrf防护配置; - 从
result.results.first().summary读取text、strategy、token_count; - 若
summary为空,检查processing_warnings中是否出现summarization_extractive告警(通常意味着文档全为停用词或过短)。
这样,你就拥有了一个纯 Rust、确定性、无需外部服务的文档摘要能力,直接嵌入 Android 应用的文档处理链路。