命名实体别名判断

本项目对两个命名实体是否互为别名进行判断。项目只包含推理流程，不包含模型训练。

环境准备

建议使用 Python 3.10 或更高版本，在项目目录执行：

pip install torch transformers safetensors fastapi "uvicorn[standard]"

模型完全从本地 model/ 目录加载，推理时不需要下载模型。程序会自动使用可用的 CUDA，否则使用 CPU。

输入格式

输入文件统一使用 .json。单条输入时，JSON 顶层为一个对象；批量输入时，JSON 顶层为对象数组。每条数据必须包含以下 8 个字段，名称和类型必须保持一致：

{
  "alias_name": "示例公司",
  "alias_description": "[2026-07-08T06:35:10.120000+00:00] 目标企业的历史称呼",
  "alias_description_summary": "",
  "alias_aliases": [],
  "target_name": "目标企业",
  "target_description": "[2026-07-08T06:35:10.120000+00:00] 用于演示别名判断的虚构企业",
  "target_description_summary": "",
  "target_aliases": ["目标企业旧称", "示例公司"]
}

其中，名称和描述字段必须是字符串，alias_aliases 与 target_aliases 必须是字符串数组。描述摘要可以使用空字符串，但字段不能省略。描述中的 OSS 时间戳可以原样保留，程序会自动清洗；aliases 数组也会参与硬规则判断。本项目不接收 OSS 快照、candidates 或 llm_raw 等上游结构。

使用方法

直接运行内置示例：

python main.py

读取自己的文件：

python main.py --input input_example.json

结果默认保存到 result/input_example_result.json。也可以指定文件名和批大小：

python main.py --input input_example.json --output result/my_result.json --batch-size 16

在其他 Python 代码中直接调用：

from main import AliasJudgeService

sample = {
    "alias_name": "示例公司",
    "alias_description": "[2026-07-08T06:35:10.120000+00:00] 目标企业的历史称呼",
    "alias_description_summary": "",
    "alias_aliases": [],
    "target_name": "目标企业",
    "target_description": "[2026-07-08T06:35:10.120000+00:00] 用于演示别名判断的虚构企业",
    "target_description_summary": "",
    "target_aliases": ["目标企业旧称", "示例公司"],
}

service = AliasJudgeService()
result = service.predict(sample)
print(result["label"])

建议在服务启动时只创建一次 AliasJudgeService，后续重复调用 predict 或 predict_many，避免反复加载约 400 MB 的模型。

输出格式

输出统一采用 JSON，并保持与输入相同的顶层结构：单条对象输入对应单个结果对象，批量数组输入对应结果数组。每条结果保留原始 8 个字段，并追加：

label：最终布尔标签，true 表示 merge，false 表示 drop。
decision：与 label 对应的可读结果 merge 或 drop。
merge_probability：模型给出的 merge 概率；硬规则命中时为 1.0。
threshold：本条数据采用的阈值；硬规则命中时为 null。
reason：模型预测 或 alias 列表硬规则命中。

FastAPI 服务

启动服务：

python service_alias_recognition.py

默认地址为 http://localhost:18083，提供 /health、/predict 和 /predict_batch 接口。详细请求示例参见 FastAPI调用指南.md。

数据到 label 的过程

flowchart TD
    A[输入固定的 8 个字段] --> B[校验字段与类型]
    B --> C[移除时间戳、低信息模板和重复子句]
    C --> D{aliases 硬规则命中?}
    D -- 是 --> E[label = true]
    D -- 否 --> F[按实体名称筛选描述子句并截断]
    F --> G[构造 4 个高价值规则特征]
    F --> H[BERT 编码名称与描述 4 个片段]
    F --> I[计算名称 Hamming 相似度]
    G --> J[融合为 9 维特征]
    H --> J
    I --> J
    J --> K[MLP 输出 merge 概率]
    K --> L{target_name 是否为 用户?}
    L -- 是 --> M[使用 0.30 阈值]
    L -- 否 --> N[使用 0.45 阈值]
    M --> O[生成 label 并写入 result]
    N --> O
    E --> O

清洗和特征构造与训练时保持一致。alias_name 已存在于 target_aliases，或非泛化名称的 target_name 已存在于 alias_aliases 时，直接判断为 merge；其他数据进入模型。模型融合 4 个规则特征、4 个 BERT 片段特征和 1 个名称相似度特征，再按用户/非用户场景采用不同阈值生成 label。

目录说明

alias_test_github/
├── main.py
├── input_example.json
├── README.md
├── model/
│   ├── bert_encoder/
│   ├── custom_components/
│   ├── tokenizer/
│   └── deploy_config.json
└── result/                 # 首次运行后自动创建