mitsuru/redact-ner-ruby
GitHub: mitsuru/redact-ner-ruby
一个Ruby绑定库，用于通过ONNX Runtime检测文本中的个人身份信息（PII）。
Stars: 0 | Forks: 0
# redact_ner
为 [`redact-ner`](https://crates.io/crates/redact-ner) Rust crate 提供的 Ruby 绑定。
依托 ONNX Runtime 实现个人身份信息 (PII) 检测的命名实体识别 (NER)。
## 状态
早期最小可行产品 (MVP)。封装了上游 `NerRecognizer` 的 API 接口：
`from_file`、`analyze`、`available?`、`supports_language?`、`supported_entities`，以及配置访问器。
## 安装
该 gem 通过 [`rb_sys`](https://github.com/oxidize-rb/rb-sys) 构建了一个原生 Rust 扩展。你需要：
- Ruby >= 3.0
- 一个可用的 Rust 工具链（`rustc` 和 `cargo`，稳定版）
- 运行时可用的 ONNX Runtime 共享库（详见下文）
```
bundle install
bin/rake compile # or: bundle exec rake compile
```
### 预编译的 musl gem（适用于 Alpine / distroless）
预编译的 `x86_64-linux-musl` 和 `aarch64-linux-musl` gem 动态链接了 C++ 运行时库 `libstdc++`，因此在加载时必须存在。纯净的 Alpine/distroless 镜像并不包含它——请先安装，例如在 Alpine 上运行 `apk add --no-cache libstdc++`。glibc 镜像（例如 Debian slim）已包含该库。
### ONNX Runtime
`redact-ner` 使用了具有 `load-dynamic` 功能的 `ort` crate，这意味着 ONNX Runtime 共享库是在运行时查找，而非在链接时。你必须将 `ORT_DYLIB_PATH` 指向一个与上游 crate 兼容的 `libonnxruntime.so` / `.dylib` / `.dll` 文件。
示例（Linux）：
```
export ORT_DYLIB_PATH=/path/to/onnxruntime-linux-x64-1.20.0/lib/libonnxruntime.so.1.20.0
```
### 优雅降级——重要说明
上游 `redact-ner` 在模型或分词器无法加载时 **不会** 抛出异常。`Recognizer.from_file` 始终会返回一个识别器对象；如果 ONNX 会话或分词器初始化失败（模型文件缺失、`ORT_DYLIB_PATH` 未设置等），识别器将处于“不可用”状态，而 `#analyze` 会静默地返回一个空数组。
如果你希望出现硬性错误而非静默降级，请立即检查 `#available?`：
```
rec = RedactNer::Recognizer.from_file("model.onnx")
raise "NER model failed to load" unless rec.available?
```
## 用法
```
require "redact_ner"
recognizer = RedactNer::Recognizer.from_file("path/to/model.onnx")
results = recognizer.analyze("John Doe works at Acme Corp in New York", "en")
results.each do |r|
puts "#{r.entity_type}\t#{r.start}..#{r.end}\t#{r.score.round(3)}\t#{r.text}"
end
```
`analyze` 返回一个 `RedactNer::Result` 数组，它是一个具有以下属性的 `Struct`：
| 属性 | 类型 | 说明 |
|--------------------|---------|-----------------------------------------------|
| `entity_type` | String | 例如 `"PERSON"`, `"ORGANIZATION"`, `"LOCATION"` |
| `start` | Integer | 字节偏移量，包含 |
| `end` | Integer | 字节偏移量，不包含 |
| `score` | Float | 模型置信度，范围 `[0.0, 1.0]` |
| `recognizer_name` | String | 始终为 `"NerRecognizer"` |
| `text` | String | 匹配到的子字符串 |
其他方法：
```
recognizer.available? # => true if a model + tokenizer were loaded
recognizer.supports_language?("ja") # => true / false
recognizer.supported_entities # => ["PERSON", "LOCATION", ...]
recognizer.name # => "NerRecognizer"
recognizer.min_confidence # => 0.7
recognizer.max_seq_length # => 512
recognizer.model_path # => the path you passed in
```
## 模型文件
此 gem 不包含模型。请使用上游 `censgate/redact` 仓库中的 [`scripts/export_ner_model.py`](https://github.com/censgate/redact/tree/main/scripts) 辅助脚本，将 HuggingFace NER 模型导出为 ONNX 格式。将生成的 `model.onnx`、`tokenizer.json` 和 `config.json` 文件放在同一目录中，并将 `.onnx` 文件的路径传递给 `Recognizer.from_file`。
## 开发
```
bundle install
bin/rake compile
bin/rake test
```
## 发布
发布已实现自动化。要发布一个新版本：
1. 运行 **Release Prep** 工作流（Actions → Release Prep → Run workflow），选择 `bump` 级别（`patch`/`minor`/`major`）。它会更新 `lib/redact_ner/version.rb`，根据 GitHub 生成的说明更新 `CHANGELOG.md`，创建一个 **Release PR**，并创建一个 **草稿 GitHub Release**。
2. 审查/编辑 Release PR（以及草稿发布说明）并 **合并** 它。合并会自动创建并推送 `vX.Y.Z` 标签。
3. 该标签将触发 **Release** 工作流：它会构建 5 个预编译 gem 和源码 gem，然后 `publish` 作业会在 `rubygems` GitHub Environment 等待批准。批准后即可发布到 RubyGems 并取消 GitHub Release 的草稿状态，同时附上 gem 资源文件。
若要在发布前中止操作，请在不合并的情况下关闭 Release PR，并删除 `release/vX.Y.Z` 分支和草稿 Release。
## 许可证
根据你的选择，采用以下任一许可证：
- Apache License, Version 2.0 ([Apache许可证](LICENSE-APACHE))
- MIT license ([MIT许可证](LICENSE-MIT))
上游 `redact-ner` crate 采用 Apache-2.0 许可证。
标签：Apex, GDPR, IPv6支持, meg, NER模型, ONNX Runtime, PII检测, Ruby编程, Rust扩展, 信息安全, 可视化界面, 合规工具, 命名实体识别, 工具开发, 数据脱敏, 数据隐私, 机器学习, 模型推理, 深度学习, 红action-ner, 网络安全, 软件开发, 隐私保护, 隐私合规, 隐私识别