# DocSifter 开源：一个面向中文技术文档的本地 AI 审校小工具

Source: https://flowingdocs.com/blog/docsifter-open-source/

在技术文档的写作与发布流程里，内容审校向来是一件性价比极低但又不得不做的事：人工逐字挑错费时费力，而直接拿通用 AI 或云端大模型去纠错，又极容易踩雷——模型分不清技术边界，随手就把代码注释改崩、把行内参数名翻译掉，或者把 `API 网关` 自作聪明改成 `API 网管`。更不用说在很多正式发版前，包含未公开架构的文档根本过不了公网 API 的数据安全合规。

过去这一年，为了在我们内部一个近 38 万字的技术文档库里安全落地自动化审校，我折腾了一套“本地优先、轻量小模型推理、带代码结构保护”的审校系统。

在[上一篇文章](https://flowingdocs.com/blog/building-a-local-ai-content-review-system)分享完架构思路后，收到一些朋友关于源码的询问。其实它最初只是个内部“能跑就行”的粗糙脚本，算不上什么高大上的系统。为了能拿出来供有类似需求的朋友参考，这几个月花时间把代码重新脱敏整理，补齐了 Web 界面、Docker 和测试用例。

今天，把这套工具开源出来，希望能给大家提供一点参考。

[DocSifter](https://github.com/heywalter/docsifter) 正式开源，采用 MIT 协议。

想先看它怎么工作，可以直接打开[交互式产品演示](https://flowingdocs.com/demos/docsifter/index.html)。

<!--truncate-->

## 它是什么

简单说，DocSifter 是一个专为技术文档设计的“体检”工具：给它一个 Markdown、AsciiDoc 或纯文本文档目录，它结合规则引擎和本地中文小模型，挑出里面的错别字、术语误写和不通顺的表达，生成一份带修改建议对比和质量指标的 HTML 报告。支持 CLI、Web 界面和 GitHub PR webhook 三种接入方式。

读过前两篇文章的话，对它的思路应该已经有印象了。这篇主要补充背后的设计取舍，以及怎么在本地快速跑起来。

## 为什么不直接用现成工具

中文纠错工具不少，为什么还要自己做？

现有工具的问题不是能力不够，是场景对不上。通用纠错工具遇到技术文档容易过度纠错——`API 网关` 被改成 `API 网管`，代码注释被改坏。云端大模型帮得上忙，但技术文档里经常有未发布功能、内部架构和客户信息，送到外部服务这件事本身就需要额外审批。纯规则又覆盖不了上下文相关的表达问题。

核心矛盾在于：技术文档不是普通中文文章，一篇里可能同时混着 YAML 配置、Shell 命令、API 参数名和中英文混排的产品术语。纠错工具得知道哪些内容该看、哪些绝对不能动。这套系统的设计核心就是这个边界。

## 三层流水线

从轻到重，按需启用：

```
第一层：规则预览
  └─ 确定性问题（重复词、标点空格、固定术语拼写）
  └─ 无需下载模型，秒级响应

第二层：本地小模型纠错
  └─ shibing624/chinese-text-correction-1.5b（默认）或 7B
  └─ 完全离线，本地 GPU/CPU 运行

第三层：LLM 二次确认（可选）
  └─ 对小模型的发现再验证，过滤误报
  └─ 支持任何 OpenAI 兼容接口，也可以用自托管模型
```

![架构图](https://flowingdocs.com/llms/assets/6563578701bc1c5d-local_content_review_architecture.png)

第一层没有任何模型依赖，装完就能跑。第二层是核心，处理规则覆盖不了的语义问题。第三层专门解决"小模型认为是问题，但其实不是"的情况——用一个更强的模型做二次判断，减少误报。三层都有独立的开关，可以单独用，也可以全部串起来。

## 几个设计取舍

### 数据不出本地

很多工具说"支持本地部署"，实际上只是把 API 调用挪到了私有服务器。这里的本地优先是：默认不联网，第一次运行会自动下载模型权重（约 3.1 GB），之后完全在本地跑。

对文档团队来说，数据不出本地不是性能优化，是把这个工具接入内部流程的前提。如果需要用云端模型做第三层确认，可以显式配置，但这是主动选择，不是默认行为。

### 先保护，再纠错

任何内容送到模型之前，系统先做一轮结构解析：围栏代码块、行内代码、YAML/JSON 配置片段直接跳过；链接 URL、图片路径、API 参数名局部保护；不破坏 AsciiDoc 和 Markdown 的语法结构。模型只处理过滤后的纯文本段落，就算给出了有问题的建议，写回报告前还有一轮安全检查。

这是整套系统里最关键的工程设计，也是直接调用通用大模型审文档最容易出事的地方。

### 误报数据归团队所有

中文 AI 纠错用着用着，最先让人放弃的不是漏报，是误报。公司产品名、内部技术术语，工具一直报错，团队很快就不用了。

白名单、强制修复规则和误报过滤在这里都是本地持久化数据。用户通过 Web 界面点"拒绝"的建议，会自动沉淀为过滤规则，下次不再提示。这些数据不会随工具升级丢失——某种程度上，它们比工具本身更值钱，记录了团队在这个领域积累的判断。

### 后端可以换

本地 transformers 是默认，但后端可以替换成 Ollama 或任何 OpenAI 兼容接口：

```bash
export DOCSIFTER_MODEL_BACKEND=ollama
export DOCSIFTER_OLLAMA_BASE_URL=http://127.0.0.1:11434

# 或者 vLLM、DashScope、OpenRouter 等
export DOCSIFTER_MODEL_BACKEND=openai
export DOCSIFTER_OPENAI_BASE_URL="https://your-endpoint.example.com/v1"
```

切换后端不需要改代码，所有后端共用同一套保护管道。

## 跑起来

安装后先用规则预览模式验证一下（不下载模型）：

```bash
pip install -e .
docsifter ./examples/sample-docs
```

启用本地小模型（首次会下载约 3.1 GB 权重）：

```bash
pip install -r requirements-model.txt
docsifter ./examples/sample-docs --model shibing624/chinese-text-correction-1.5b
```

Web 界面：

```bash
docsifter-web
# http://localhost:8080
```

扫完生成自包含 HTML 报告，包含逐行修改建议对比、千字缺陷率等质量指标。前两篇文章里的截图就是这个输出——约 38 万字的技术文档仓库，RTX 3060 环境下扫描约 60 分钟，大概每秒 100 字。

![本地小模型审校界面](https://flowingdocs.com/llms/assets/09b0ff44ce782fad-local_llm_content_review.png)

![审校报告分析](https://flowingdocs.com/llms/assets/59f046c72143605a-review_analysis.png)

## 能做什么，不能做什么

这套工具在基础文本质量上效率高，但有明确边界：它能发现错别字、术语误写、明显病句，发现不了"这段产品能力描述是否还准确"。后者需要配合 Codex 这类更强的 AI review 层（[第一篇文章](https://flowingdocs.com/blog/ai-content-review-with-codex)里有详细介绍）。它的定位也很聚焦，专门针对技术文档场景，不适合拿来审普通散文或小说。另外还有一点：目前只处理中文内容。

接入 Docs-as-Code 流程的话，有三个自然的位置：本地写作时用 CLI 做快速预检、提交 PR 前用 Web UI 批量扫描、PR 阶段通过 GitHub webhook 自动触发只检查变更文件。我们内部的用法是三者叠加，规则预览最轻、最快；小模型审校在提交前跑；Codex Cloud review 在 PR 阶段兜底。

## 为什么现在开源

做这个决定比整理代码花的时间长。

内部工具变成公开项目，不只是脱敏和写 README，还有一堆需要想清楚的问题：配置怎么设计才对陌生用户友好，安全边界在哪，单实例部署拓扑怎么说明，测试覆盖够不够。从原来 `main.py` 里的一堆函数，到现在有 CI、Docker 支持、结构化日志、Prometheus 指标端点的版本，中间是一段相当实在的重构。

原因倒也不复杂：这个系统在内部跑了将近一年，基本思路验证下来是可行的。搜索"技术文档 + 中文 + 本地 AI 审校"，几乎找不到现成的工程化参考。如果有团队在处理类似问题，能少走一段弯路，就值得发出来。

***

GitHub：[heywalter/docsifter](https://github.com/heywalter/docsifter)

有问题或者用法上的需求，欢迎[提 Issue](https://github.com/heywalter/docsifter/issues)。如果你们团队也在做文档质量工程，也欢迎在评论区聊——这类场景下每个团队的文档结构和术语体系差异很大，不同的踩坑经验通常都有参考价值。