Chatbot_NER 项目 API 调用指南：实体识别技术详解

项目概述

Chatbot_NER 是一个专注于从文本数据中提取关键实体信息的工具库，专为对话式 AI 应用设计。它能够识别多种类型的实体，包括时间、日期、数字、电话号码、电子邮件等，支持多语言处理，是构建智能对话系统的有力工具。

核心功能特性

Chatbot_NER 提供以下实体识别能力：

1. 时间识别：支持12/24小时制，能识别相对时间表达（如"10分钟后"）
2. 日期识别：可识别多种日期格式，包括绝对日期和相对日期
3. 数字识别：支持整数、小数和货币金额等
4. 电话号码识别：能识别国际格式的电话号码
5. 电子邮件识别：识别标准电子邮件格式
6. 文本实体识别：基于上下文模型或数据存储的全文搜索识别自定义实体
7. PNR编号识别：识别旅行预订中的PNR代码
8. 正则表达式识别：支持自定义正则模式匹配

API 参数详解

基础参数

1. message (必需)

   • 描述：需要从中提取实体的原始文本
   • 示例："我想订明天下午3点的披萨"

2. entity_name (必需)

   • 描述：要识别的实体类型名称
   • 示例：对于餐厅识别，可设为"restaurant"

3. structured_value (可选)

   • 描述：从结构化数据（如表单）中获取的值
   • 使用场景：当用户通过表单选择而非文本输入时

4. fallback_value (可选)

   • 描述：当无法从文本中识别实体时的备用值
   • 示例：用户说"附近的ATM"，可使用用户位置作为备用值

5. source_language (必需)

   • 描述：输入文本的语言代码（ISO 639-1标准）
   • 示例：英语为"en"，印地语为"hi"

6. bot_message (可选)

   • 描述：机器人/代理的上一条消息
   • 作用：帮助消除用户回复的歧义

输出格式解析

API 返回一个包含识别结果的字典列表，每个字典包含以下字段：

{
    "entity_value": "识别出的实体值",
    "detection": "识别来源(message/structured_value/fallback_value)",
    "original_text": "原始文本中匹配的部分"
}

输出示例

输入文本："我想在Mainland China订2个汉堡，下午3点取餐"

输出结果：

[
  {
    "detection": "message",
    "original_text": "2",
    "entity_value": {"value": "2", "unit": null},
    "language": "en"
  },
  {
    "detection": "message",
    "original_text": "3 pm",
    "entity_value": {"mm": 0, "hh": 3, "nn": "pm"},
    "language": "en"
  }
]

典型使用场景

1. 时间识别

支持多种语言的时间表达识别，包括英语、印地语、马拉地语等。

Python调用示例：

from ner_v2.detectors.temporal.time.time_detection import TimeDetector

message = "会议安排在下午4:30，请提前15分钟到场"
entity_name = "time"
timezone = "Asia/Shanghai"
source_language = "zh"

detector = TimeDetector(entity_name=entity_name, 
                       language=source_language,
                       timezone=timezone)
result = detector.detect(message=message)
print(result)

预期输出：

[
  {
    "detection": "message",
    "original_text": "下午4:30",
    "entity_value": {"hh": 16, "mm": 30, "nn": "pm"},
    "language": "zh"
  },
  {
    "detection": "message",
    "original_text": "15分钟",
    "entity_value": {"hh": 0, "mm": 15, "nn": "df"},
    "language": "zh"
  }
]

2. 日期识别

支持绝对日期、相对日期和星期表达等多种格式。

Python调用示例：

from ner_v2.detectors.temporal.date.date_detection import DateAdvanceDetector

message = "下周三我要去北京出差"
entity_name = "date"
timezone = "Asia/Shanghai"
source_language = "zh"

detector = DateAdvanceDetector(entity_name=entity_name,
                              language=source_language,
                              timezone=timezone)
result = detector.detect(message=message)
print(result)

预期输出（假设今天是2023-06-28）：

[
  {
    "detection": "message",
    "original_text": "下周三",
    "entity_value": {
      "value": {"dd": 5, "mm": 7, "yy": 2023, "type": "date"},
      "normal": true
    },
    "language": "zh"
  }
]

最佳实践建议

1. 时区处理：始终明确指定时区参数，确保日期时间识别准确
2. 语言支持：确认目标语言是否在支持列表中，必要时可扩展语言模式
3. 错误处理：合理使用fallback_value处理识别失败场景
4. 上下文利用：通过bot_message参数提供对话上下文，提高识别准确率
5. 性能优化：对于高频调用，考虑缓存检测器实例

扩展开发

如需支持新的实体类型或语言，可以：

1. 继承基础检测器类实现自定义逻辑
2. 添加特定语言的正则模式
3. 扩展数据存储中的实体词典

Chatbot_NER 的设计允许灵活扩展，满足各种对话系统的实体识别需求。通过合理配置和定制开发，可以构建出高度精准的多语言实体识别能力。