GuChunk 语义分块模型

这是一个面向 RAG 知识库构建的中文语义分块模型。模型输入一段文本，输出按语义边界切分后的 chunks，并可返回候选边界、边界分数和中间 unit 信息。

模型信息

• 模型版本：hierarchical_unit_boundary_v4_semantic_window
• 默认阈值：0.8547246456
• 语义窗口半径：4
• 窗口池化方式：meanmax
• 解码方式：阈值切分，boundary_score >= threshold 时切分

文件说明

app.py                  PyTorch 推理脚本和 HTTP 服务
model.pt                PyTorch 模型权重
requirements_runtime.txt PyTorch 版基础依赖

app_numpy.py            NumPy 推理脚本和 HTTP 服务
model_numpy.npz         NumPy 版权重
model_numpy_meta.json   NumPy 版词表、配置和归一化参数
requirements_numpy.txt  NumPy 版基础依赖

如果只使用 PyTorch 版，需要 app.py、model.pt 和 requirements_runtime.txt。

如果只使用 NumPy 版，需要 app_numpy.py、model_numpy.npz、model_numpy_meta.json 和 requirements_numpy.txt。

PyTorch 版与 NumPy 版一致性

NumPy 版是 PyTorch 模型的离线转换推理实现，与 PyTorch 版共享预处理、候选边界、特征构造、阈值解码和输出协议。

由于底层数值实现不同，边界分数可能存在极小浮点差异；如果某个分数非常接近阈值，切分结果理论上可能出现差异。通常使用时，两者的行为口径是一致的，但不承诺逐 bit 完全一致。

快速开始

PyTorch 版：

pip install -r requirements_runtime.txt
python app.py --host 0.0.0.0 --port 8000

NumPy 版：

pip install -r requirements_numpy.txt
python app_numpy.py --host 0.0.0.0 --port 8000

脚本默认启动 HTTP 服务；--serve 参数仍然保留，用于兼容旧命令。

启动服务后，请求 /predict 接口：

curl -X POST http://127.0.0.1:8000/predict \
  -H "Content-Type: application/json" \
  --data-raw '{"text":"第一段。第二段。\n\n# 标题\n内容。"}'

index.html 不是模型发布包的必需文件。本发布包默认不包含网页测试页面，因此浏览器访问根路径时不会显示完整 UI；如需浏览器表单测试页，可额外加入 index.html。

请求参数

• text：必填，要切分的文本。
• threshold：可选，边界分数阈值；不传时使用模型默认阈值。
• include_boundaries：可选，是否返回候选边界，默认 true。
• include_units：可选，是否返回中间 unit，默认 false。

示例：

{
  "text": "第一段。第二段。\n\n# 标题\n内容。",
  "threshold": 0.85,
  "include_boundaries": true,
  "include_units": false
}

适用场景

• RAG 知识库入库前的文本切分
• 中文 Markdown、政策、合同、技术文档、表格和代码混合文档切分
• 需要保留语义完整性和文档结构的长文本预处理

限制

• 模型主要面向中文和中英混排文档，其他语言效果未充分验证。
• 当前使用阈值切分，不包含全局动态规划解码器。
• 模型只在候选 unit 边界上判断是否切分，不会任意生成新的字符位置。
• 对 OCR 噪声、格式损坏或极端异常结构文档，建议先做清洗。