一个使用 Go 编写的轻量级文本关键词匹配服务。项目基于 Aho-Corasick 自动机,提供关键词扫描、分类标签、备注信息、在线词库管理、运行统计与热更新能力,并内置了可直接使用的 Web 控制台。
适合用于内容分类、文本标注、规则路由、合规提示、客服质检等需要按词库快速识别文本片段的场景。
- 高效匹配:使用 Aho-Corasick 自动机一次扫描多个关键词。
- Unicode 支持:按
rune处理文本,支持中文、英文、Emoji 等内容,并返回准确的字符区间。 - 灵活元数据:每个词条可配置多个分类标签与多条备注。
- 批量词条:一个配置项可通过中英文逗号声明多个关键词,共享同一组标签和备注。
- 在线管理:通过 Web 控制台或 HTTP API 查询、新增、修改和删除词条。
- 动态更新:支持监听词库文件自动重载,也可通过 API 手动触发重载。
- 并发友好:新自动机在后台构建完成后通过
atomic.Value发布,查询路径无需等待重建过程。 - 运行统计:记录请求量、匹配量和高频命中项,可选定期持久化。
- 访问控制:可为词库写操作配置访问令牌。
- 便于部署:支持本地运行、Docker 和 Docker Compose,无需单独部署前端。
完整接口定义及响应字段说明请参阅 API.md。
models/**/model.safetensors 由 Git LFS 管理。直接 git clone 拿到的是 132 字节的指针文件,不是真实权重,此时模型服务无法启动、发布包也构建不出来(release.py 会主动拒绝 LFS 指针)。
# 先装 git-lfs:Debian/Ubuntu 用 apt install git-lfs,macOS 用 brew install git-lfs
git lfs install
git clone <仓库地址>
cd noblack
git lfs pull # 拉取约 800MB 的模型权重已经克隆过但忘了装 LFS,补拉即可:
git lfs install && git lfs pull检查是否拉取成功——真实权重是几百 MB,指针只有 132 字节:
ls -la models/lite-production-v1/model.safetensors只做词库检测、不启用 AI 模型时可以跳过这一步,用
-model-service-url ""启动即可。
环境要求:Go 1.21 或更高版本。
go mod download
go run ./cmd/server服务默认监听 :8080,词库默认读取当前目录下的 data/words.json。
启动后可访问:
- Web 控制台:
http://localhost:8080 - 健康检查:
http://localhost:8080/health
常用启动方式:
# 指定监听地址和词库文件
go run ./cmd/server -addr :8080 -words ./data/words.json
# 启用英文大小写忽略匹配
go run ./cmd/server -ci
# 持久化运行统计
go run ./cmd/server -stats-file ./stats.json
# 为词库写操作启用访问令牌
go run ./cmd/server -token "your-secret-token"
# 关闭文件监听,仅通过 API 手动重载
go run ./cmd/server -watch=falsedocker compose up -d --build默认配置会将宿主机的 ./data 挂载到容器 /data:
./data/words.json:词库文件./data/stats.json:统计数据
容器和服务进程均以 root 身份运行,避免宿主机绑定挂载目录的 UID/GID 与容器用户不一致,导致无法创建临时文件、更新词库或持久化统计。
首次启动且 ./data/words.json 不存在时,容器会自动复制一份默认词库。更新配置后需要重新构建并创建容器:
docker compose down
docker compose up -d --build --force-recreatedocker build -t noblack:latest .
mkdir -p ./data
docker run -d \
--name noblack \
-p 8080:8080 \
-v "$(pwd)/data:/data" \
noblack:latest默认词库采用 JSON 格式:
{
"words": [
{
"word": "售后服务",
"levels": ["customer-service"],
"remarks": ["转交售后流程"]
},
{
"word": "退款,退货",
"levels": ["after-sales", "priority"],
"remarks": ["需要人工复核"]
},
{
"word": "Example",
"level": "demo",
"remarks": "英文示例"
}
]
}字段说明:
| 字段 | 类型 | 说明 |
|---|---|---|
word |
string | 待匹配的关键词;可用中文或英文逗号分隔多个词 |
levels |
string[] | 推荐写法,一个词条可配置多个分类标签 |
level |
string | 兼容单标签写法;与 levels 同时存在时优先使用 levels |
remarks |
string[] / string | 备注列表,也可写成逗号分隔的字符串 |
补充规则:
- 未提供
level或levels时,使用-default-level指定的默认值。 - 顶层既可以使用
{ "words": [...] },也可以直接使用数组[...]。 - 逗号分隔的多个关键词会分别参与匹配和统计,但共享标签与备注。
- 保存词库时会清理空白项,并以规范 JSON 格式写回文件。
主要接口如下:
| 分类 | 方法与路径 | 说明 |
|---|---|---|
| 文本匹配 | POST /check |
扫描文本并返回命中位置及元数据 |
| 词库管理 | GET /words |
分页查询词条(支持关键词筛选) |
| 词库管理 | POST /words |
新增词条 |
| 词库管理 | PUT /words/{word} |
修改词条 |
| 词库管理 | DELETE /words/{word} |
删除词条 |
| 配置查询 | GET /levels |
获取当前词库中的全部标签 |
| 动态更新 | POST /reload |
从文件重新加载词库 |
| 运行统计 | GET /stats |
获取统计信息(高频词支持分页) |
| 运行统计 | POST /stats/reset |
重置统计信息 |
| 鉴权 | GET /auth/status |
查询是否启用写操作鉴权 |
| 鉴权 | POST /auth/verify |
校验访问令牌 |
| 运维 | GET /health |
健康检查 |
示例:
# 扫描文本
curl -X POST http://localhost:8080/check \
-H 'Content-Type: application/json' \
-d '{"text":"我需要申请退款并联系售后服务"}'
# 新增词条
curl -X POST http://localhost:8080/words \
-H 'Content-Type: application/json' \
-H 'X-Auth-Token: your-secret-token' \
-d '{"word":"物流查询","levels":["customer-service"],"remarks":["转交物流流程"]}'
# 查看统计
curl "http://localhost:8080/stats?top=10"写操作令牌同时支持以下两种请求头:
X-Auth-Token: your-secret-token
Authorization: Bearer your-secret-token
更多请求、响应和错误码示例见 API.md。
| 参数 | 默认值 | 说明 |
|---|---|---|
-addr |
:8080 |
HTTP 监听地址 |
-words |
./data/words.json |
词库文件路径 |
-watch |
true |
是否监听词库文件并自动重载 |
-ci |
false |
是否忽略英文大小写 |
-default-level |
Low |
词条未配置标签时使用的默认值 |
-stats-file |
空 | 统计持久化文件;为空时不持久化 |
-stats-flush-interval |
30s |
统计数据定期写入文件的间隔 |
-token |
空 | 词库写操作令牌;为空时不启用鉴权 |
-normalize |
true |
归一化输入以对抗变体绕过(炸.药 → 炸药);亦可用环境变量 NB_NORMALIZE |
-samples-file |
空 | 语义样本库文件路径;留空则禁用;亦可用环境变量 NB_SAMPLES |
-sample-threshold |
0.75 |
语义样本相似度阈值(0-1),越高越严格;亦可用环境变量 NB_SAMPLE_THRESHOLD |
-detect-mode |
both |
检测模式:model_only / model_first / word_only / word_first / both;亦可用环境变量 NB_DETECT_MODE;请求体 mode 可覆盖 |
-recall-on-miss |
false |
优先链路未命中时补跑另一条链路以提高召回;亦可用环境变量 NB_RECALL_ON_MISS;请求体 recall_on_miss 可覆盖 |
程序启动时会自动查找并加载 config.env(依次尝试可执行文件所在目录和当前工作目录),因此直接运行 noblack / noblack.exe 也能读到配置,无需经过启动脚本。可用 -config <路径> 显式指定。
启动日志会明确打印配置来源,便于确认是否生效:
已加载配置文件: D:\...\config.env (生效 14 项)
未找到 config.env, 使用默认配置与命令行参数 (可用 -config 指定路径)
配置优先级由低到高:config.env → 环境变量 → 命令行参数 → 请求体字段(后者覆盖前者)。文件中只有 NB_ 前缀的大写键会生效,与启动脚本的解析规则一致。
黑产常在敏感词中间插入字符来绕过检测——炸.药、炸 药、炸_药、炸药(零宽空格),或改用繁体 槍支。这些写法在字面上匹配不到词库,也会打断模型的语义信号。
启用 -normalize(默认开启)后,词库匹配与模型推理都会先把输入还原为标准形式:
| 处理 | 效果 |
|---|---|
| 去除标点、空白、Emoji、零宽字符、下划线 | 炸.药 炸 药 炸🔥药 → 炸药 |
| 繁体转简体 | 槍支彈藥 → 枪支弹药(2956 字对照表,源自 OpenCC) |
| 全角转半角 | C4 → c4 |
| 大小写折叠 | C4炸药 → c4炸药 |
命中位置仍指向原文,且覆盖被剔除的干扰字符——这里有炸.药教程 返回 [3,6),前端高亮能盖住完整的变体写法。
实测:随机抽取词库中 150 个真实词条,中间插入一个点后,关闭归一化时仅 63 条被拦截,开启后 150 条全部拦截。正常文本(价格是99.5元、test.user@example.com)不受影响。
词库与输入用同一套规则归一化,两侧在同一空间比较。
-normalize=false可退回纯字面匹配。
繁简对照表由 scripts/gen_traditional.py 从 OpenCC 生成,Go 与 Python 两份表同源,测试会校验一致性。需要更新时:
pip install opencc-python-reimplemented
python3 scripts/gen_traditional.py模型权重无法在线更新,遇到漏报只能等下一轮微调。词库能补单词,但补不了"换几个字的同类句式"。样本库填补这个空档——把漏报的整句提交上来,立即生效。
用 -samples-file 启用:
noblack -samples-file data/samples.json -sample-threshold 0.75| 接口 | 说明 |
|---|---|
GET /samples |
列出全部样本与当前阈值 |
POST /samples |
新增样本(需令牌) |
DELETE /samples/{id} |
删除样本(需令牌) |
# 提交一条模型漏报的句子
curl -X POST http://localhost:8080/samples \
-H 'Content-Type: application/json' -H 'X-Auth-Token: <令牌>' \
-d '{"text":"漏报的整句原文","levels":["违法"],"remark":"模型漏报"}'命中后 /check 返回 decided_by: "sample",并在 sample_matches 里给出命中的样本与相似度。
工作原理:把样本与待检文本都归一化后取字符 bigram 集合,算 Dice 相似度,超过阈值即判定命中。因此它能召回"改动几个字的改写版",而不只是逐字相同的文本。
阈值取舍(-sample-threshold,默认 0.75):
| 阈值 | 效果 |
|---|---|
| 0.6 以下 | 召回激进,同话题但无关的句子也可能被拦,误报风险高 |
| 0.75 | 能容忍替换几个字或调整语序,实测不误拦正常文本 |
| 0.9 以上 | 几乎只匹配逐字相同的文本,失去泛化能力 |
样本库只在词库和模型都没有拦下来时才参与判定,不会覆盖更精确的归因。样本按归一化文本去重,
炸药教程与炸.药教程视为同一条。
-detect-mode 决定词库与模型两条链路的编排方式:
| 模式 | 行为 |
|---|---|
word_only |
仅词库,完全不调用模型 |
model_only |
仅模型,技术失败时不回退词库 |
model_first |
模型优先,仅在模型技术失败时回退词库 |
word_first |
词库优先;词库不会技术失败,故模型仅用于未命中召回 |
both |
两条链路并行全跑,任一命中即拦截(默认,兼容历史行为) |
⚠️ "失败" 与 "未命中" 语义不同: 技术失败(服务不可用/超时)触发model_first的降级回退;未命中(正常返回但判无风险)默认不触发任何回退,需显式开启-recall-on-miss才补跑另一条链路。除
both外的模式均为串行短路——优先链路命中即返回,省掉另一条链路的开销。
响应中 blocked 为跨链路最终判定,decided_by 说明结论来源;has_sensitive_word 仅代表词库链路,保留用于兼容旧调用方。
| 环境变量 | 默认值 | 对应参数 | 说明 |
|---|---|---|---|
NB_ADDR |
:8080 |
-addr |
HTTP 监听地址 |
NB_WORDS |
/data/words.json |
-words |
词库文件路径 |
NB_STATS |
/data/stats.json |
-stats-file |
统计持久化文件;置空可关闭 |
NB_TOKEN |
空 | -token |
词库写操作令牌 |
NB_CI |
false |
-ci |
是否忽略英文大小写 |
NB_WATCH |
true |
-watch |
是否启用文件监听 |
NB_MODEL_SERVICE_URL |
空 | -model-service-url |
可选模型服务地址;为空时仅使用词库匹配 |
NB_DETECT_MODE |
both |
-detect-mode |
检测模式;留空使用默认值 |
NB_RECALL_ON_MISS |
false |
-recall-on-miss |
未命中时是否补跑另一条链路 |
词库更新不会直接修改正在提供查询的自动机:
- 从 JSON 文件或在线管理接口读取最新词条。
- 在后台完整构建新的 Aho-Corasick 自动机。
- 构建成功后,通过
atomic.Value一次性替换当前实例。 - 已开始的请求继续使用原实例,后续请求使用新实例。
文件监听使用 fsnotify,也可以调用 POST /reload 主动触发更新。重建操作会串行执行,但不会占用查询路径上的锁。
noblack/
├── cmd/server/ # 服务入口
├── internal/api/ # HTTP 接口与内嵌控制台
├── internal/matcher/ # 自动机、词库解析与匹配逻辑
├── internal/stats/ # 运行统计与持久化
├── internal/store/ # 词库管理、热替换与文件监听
├── data/words.json # 默认及运行词库
├── API.md # 完整接口文档
├── Dockerfile
└── docker-compose.yml
# 运行全部测试
go test ./...
# 运行匹配模块基准测试
go test -bench=. ./internal/matcher/实际吞吐会受文本长度、命中数量、词库内容、硬件环境和并发模型影响。建议使用与生产场景接近的数据运行基准测试,再据此设置实例数量和资源限制。
- 生产环境建议配置
-token,并在反向代理层限制管理接口的访问范围。 - 词库与统计文件可能包含业务数据,请合理设置文件权限、备份和保留策略。
- 自动匹配结果适合作为规则判断或人工复核的辅助信息,不应在缺少上下文时作为唯一决策依据。
本项目采用 GNU Affero General Public License v3.0 许可。
- 请求体不超过 3 MiB 时正常处理。
- 请求体超过 3 MiB 且不超过 10 MiB 时,服务端必须已配置令牌,并且请求需要携带该有效令牌。
- 请求体超过 10 MiB 时返回 HTTP 413,携带令牌也不会放行。
- 启用令牌鉴权后,
POST /reload和POST /stats/reset与词库增删改接口使用相同的令牌鉴权。
项目可选内置 Lite 与 MacBERT 两个模型。默认部署仅使用合并后的词库匹配,不启动模型服务;显式配置 NB_MODEL_SERVICE_URL 或使用 --enable-models 后,两个模型才会同时常驻内存并并行执行。
生产微调模型默认采用 max 策略以保留任一模型发现的色情/谐音风险;如需进一步压低误报,可设置 NB_MODEL_COMBINE_POLICY=consensus,要求两个模型共同升级。
# Windows(默认仅词库匹配)
.\scripts\start-all.ps1
# Windows(启用可选 CPU 模型)
.\scripts\start-all.ps1 -EnableModels
# Docker(默认仅词库匹配)
docker compose up -d --build打开 http://127.0.0.1:8080。详细说明见 DEPLOY_MODELS.md。
发布脚本会校验生产模型权重,分别构建 Go 主服务和 PyInstaller 模型服务,并生成带 SHA-256 的原生离线包。模型程序必须在目标操作系统上构建。
新克隆的仓库缺两样构建必需、但不在版本库里的东西:LFS 模型权重(仓库里只有 132 字节的指针)和 Python 虚拟环境(.build/ 在 .gitignore 中)。一条命令补齐:
./scripts/bootstrap.sh它会依次:检查 Go/Python → 拉取 LFS 权重 → 建 venv 并装依赖(torch CPU 版 + requirements + PyInstaller)→ 跑 Go 测试 → 校验发布输入。脚本是幂等的,已就绪的环节会跳过,可反复执行。
常用选项:--recreate(依赖版本变更后重建 venv)、--skip-lfs、--skip-venv。
环境已经就绪时不必运行它——下面这段说明的就是复用现有环境的方式。
⚠️ 构建前先看这里,不要重新安装依赖。构建用的 Python 虚拟环境已存在于
.build/下(该目录在.gitignore中,不会提交,但请勿删除):
环境 路径 解释器 Linux .build/linux-venv/.build/linux-venv/bin/pythonWindows .build/windows-venv/.build/windows-venv/Scripts/python.exe直接用上表的解释器调用
scripts/release.py,无需 pip install(torch 等依赖有数 GB,重装非常耗时):.build/linux-venv/bin/python scripts/release.py build --target linux-amd64检查环境是否可用(而不是去看系统 Python 或项目根目录的
.venv):.build/linux-venv/bin/python -c "import PyInstaller, torch, transformers; print('ok')"依赖版本以
model_service/requirements.txt为准(transformers 5.13.1、safetensors 0.8.0、pypinyin 0.55.0),配合torch==2.6.0+cpu。
⚠️ Windows 构建必须先清空PYTHONPATH。 系统环境变量PYTHONPATH=K:\site-packages指向一个外部 conda 环境(装有 FunASR、ModelScope 等其他项目的依赖),它在sys.path中排在 venv 自身的Lib\site-packages之前,会让构建误用 transformers 4.27.4 等旧版本。在 PowerShell 中按下面这样构建($env:只影响当前会话,不改系统设置):cd D:\work\project\go\noblack $env:PYTHONPATH = "" .build\windows-venv\Scripts\python.exe scripts\release.py build --target windows-amd64验证构建实际用的版本(应为 5.13.1,而非 4.27.4):
$env:PYTHONPATH = "" .build\windows-venv\Scripts\python.exe -c "import transformers; print(transformers.__version__, transformers.__file__)"注意 WSL 侧无法覆盖这个变量——它是 Windows 系统级设置,Windows 进程启动时从注册表读取,
env -u PYTHONPATH之类的做法无效。
# Linux x86_64
python scripts/release.py validate
python scripts/release.py build --target linux-amd64# Windows 10/11 x64
python scripts\release.py validate
python scripts\release.py build --target windows-amd64PyInstaller 不支持交叉编译。若临时需要在 Linux 上打 Windows 包,可用 --model-executable 复用一份已构建好的模型程序:
.build/linux-venv/bin/python scripts/release.py build --target windows-amd64 \
--model-executable .build/keep/noblack-model.exe
⚠️ --model-executable的路径不能放在.build/<target>/下。release.py在构建开始时会清空该目录,源文件会在被读取前就被删掉, 报错model executable missing。把要复用的 exe 先拷到.build/keep/之类不参与清理的目录再传入。上次在 Windows 上原生构建的产物会同时留在
dist/noblack-windows-amd64/, 那份可以作为复用来源(注意先确认它比.build/pyi-dist/里的更新—— 后者可能是很久以前的旧版)。
但这样只有 Go 主服务是新的,模型服务仍是复用的旧版——model_service/ 下的 Python 改动不会进入该包。只要改动了 model_service/,就必须按上面的 PowerShell 方式在 Windows 上原生构建。
输出位于 dist/:
noblack-linux-amd64.tar.gznoblack-windows-amd64.zip- 对应的
.sha256文件和已组装运行目录
运行包提供完整双模型模式和仅词库模式,目标机器无需安装 Go、Python、PyTorch 或 Transformers。