lingyue-zhibao/NER_README.md

NER 服务使用指南

本文档介绍 NER（命名实体识别）服务的使用方法。

概述

NER 服务提供以下功能：

1. 实体提取：从文本中识别人名、机构、地点、日期、数值、设备等实体
2. 关系抽取：从实体间抽取语义关系
3. 自动集成：文档解析完成后自动触发 NER，将结果保存到图数据库

架构

文件上传 → 文档解析 → 文本存储 → RAG 索引
                              ↓
                         发布事件
                              ↓
                         NER 监听器
                              ↓
                    调用 Python NER 服务
                              ↓
                    保存到图数据库 (graph_nodes, graph_relations)

快速开始

1. 启动 Python NER 服务

cd python-services/ner-service

# 安装依赖
pip install -r requirements.txt

# 启动服务
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload

2. 验证服务

# 健康检查
curl http://localhost:8001/health

# 运行端到端测试
./test/test_ner_e2e.sh

API 接口

Python NER 服务

方法	路径	说明
GET	/health	健康检查
POST	/ner/extract	提取实体和关系
POST	/ner/relations	从实体中抽取关系

Java NER 接口

方法	路径	说明
POST	/api/ner/extract	提取实体（同步）
POST	/api/ner/extract/async	提取实体（异步）
POST	/api/ner/relations	提取关系
POST	/api/ner/document/{documentId}	对文档执行 NER 并保存
POST	/api/ner/document/{documentId}/async	异步对文档执行 NER

图数据库接口

方法	路径	说明
GET	/api/graph/documents/{documentId}/nodes	获取文档节点
GET	/api/graph/documents/{documentId}/stats	获取图统计
POST	/api/graph/nodes	创建节点
POST	/api/graph/relations	创建关系

使用示例

实体提取

curl -X POST http://localhost:8001/ner/extract \
  -H "Content-Type: application/json" \
  -d '{
    "documentId": "doc-001",
    "text": "2024年5月15日，成都检测公司完成了环境监测项目。",
    "extractRelations": true
  }'

响应：

{
  "documentId": "doc-001",
  "entities": [
    {
      "name": "2024年5月15日",
      "type": "DATE",
      "value": "2024年5月15日",
      "position": {"charStart": 0, "charEnd": 11, "line": 1},
      "confidence": 0.8
    },
    {
      "name": "成都检测公司",
      "type": "ORG",
      "value": "成都检测公司",
      "position": {"charStart": 12, "charEnd": 18, "line": 1},
      "confidence": 0.8
    }
  ],
  "relations": [...],
  "entityCount": 2,
  "relationCount": 1,
  "processingTime": 150,
  "success": true
}

对文档执行 NER

curl -X POST "http://localhost:5232/api/ner/document/doc-001?userId=user-001"

实体类型

类型	说明	示例
PERSON	人名	张经理、李总
ORG	机构	成都检测公司
LOC	地点	成都市高新区
DATE	日期	2024年5月15日
NUMBER	数值	50分贝、100万元
DEVICE	设备	噪音检测设备
PROJECT	项目	环境监测项目
TERM	专业术语	-

关系类型

类型	说明
负责	主体负责某事
属于	隶属关系
位于	位置关系
包含	包含关系
使用	使用关系
检测	检测关系

配置说明

application.properties

# NER 自动提取配置
ner.auto-extract.enabled=true

# Python NER 服务配置
ner.python-service.url=http://localhost:8001
ner.python-service.timeout=60000
ner.python-service.max-retries=3

环境变量

变量名	说明	默认值
NER_SERVICE_URL	NER 服务地址	http://localhost:8001
NER_MODEL	NER 模型类型	rule
USE_GPU	是否使用 GPU	false

NER 模型模式

1. rule 模式（默认）

基于正则表达式规则的简单 NER，适合开发测试：

• 优点：无需额外依赖，启动快速
• 缺点：准确率有限，仅支持常见实体类型

2. spacy 模式

使用 spaCy 中文模型：

pip install spacy
python -m spacy download zh_core_web_sm

3. api 模式

调用外部 API（如 DeepSeek/Qwen）进行 NER：

NER_MODEL=api
API_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
API_KEY=your-api-key
API_MODEL=qwen-plus

故障排除

NER 服务连接失败

1. 确认 NER 服务已启动：curl http://localhost:8001/health
2. 检查防火墙设置
3. 检查配置文件中的服务地址

实体提取结果为空

1. 确认文本内容不为空
2. 检查文本是否包含可识别的实体
3. 查看 NER 服务日志

关系抽取失败

1. 确认至少有 2 个实体
2. 检查实体位置信息是否正确

开发计划

• 集成 spaCy 中文模型
• 集成 Transformers NER 模型（如 Qwen-NER）
• 实现 API 模式（DeepSeek/Qwen）
• 支持自定义实体类型
• 优化关系抽取准确率
• 添加实体去重和合并逻辑