AI智能实体侦测服务API调用教程：REST接口详细说明
1. 引言
1.1 学习目标
本文将详细介绍如何使用AI 智能实体侦测服务的 REST API 接口，帮助开发者快速集成高性能中文命名实体识别（NER）能力到自有系统中。通过本教程，您将掌握：
- 如何访问和调用 NER 服务的 RESTful 接口
- 请求与响应的数据结构解析
- 实体类型标识与返回格式说明
- 常见问题排查与最佳实践建议
无论您是希望构建信息抽取系统、自动化文档处理流程，还是增强搜索推荐能力，本文提供的 API 使用指南都能为您提供可落地的技术支持。
1.2 前置知识
在阅读本教程前，请确保您已具备以下基础：
- 熟悉 HTTP 协议基本概念（GET/POST、请求头、JSON 格式）
- 能够使用
curl或 Postman 等工具发起网络请求 - 了解 JSON 数据结构的基本语法
- 已部署并运行了 AI 智能实体侦测服务镜像（基于 ModelScope RaNER 模型）
1.3 教程价值
本教程不仅提供标准 API 文档说明，更结合实际应用场景，给出完整代码示例与调试技巧。相比官方文档，内容更具工程实用性，适合需要快速集成 NER 功能的开发团队参考使用。
2. 服务架构与功能概览
2.1 技术背景
AI 智能实体侦测服务基于达摩院开源的RaNER（Rapid Named Entity Recognition）模型构建，专为中文文本优化。该模型采用轻量级神经网络架构，在保持高精度的同时显著降低推理延迟，特别适用于 CPU 环境下的实时语义分析任务。
命名实体识别（NER）作为自然语言处理中的核心任务之一，广泛应用于新闻摘要生成、客户信息提取、知识图谱构建等场景。传统方法依赖规则匹配或复杂模型部署，而本服务通过预训练 + 微调的方式，实现了开箱即用的高质量实体抽取能力。
2.2 核心功能模块
| 模块 | 功能描述 |
|---|---|
| WebUI 交互界面 | 支持用户粘贴文本后实时显示实体高亮结果，采用 Cyberpunk 风格设计，提升可视化体验 |
| 实体识别引擎 | 基于 RaNER 模型实现人名（PER）、地名（LOC）、机构名（ORG）三类实体的自动抽取 |
| REST API 接口 | 提供标准化 HTTP 接口，便于程序化调用与系统集成 |
| 动态标签渲染 | 在前端界面中使用不同颜色对实体进行标注：红色（人名）、青色（地名）、黄色（机构名） |
2.3 双模交互设计
本服务支持两种交互模式：
可视化模式（WebUI）
用户可通过浏览器直接输入文本，点击“🚀 开始侦测”按钮查看高亮结果，适合演示、测试和非技术人员使用。程序化模式（REST API）
开发者可通过发送 HTTP 请求获取原始结构化数据，便于进一步处理或嵌入业务逻辑，适用于自动化系统集成。
3. REST API 接口详解
3.1 接口地址与协议
服务启动后，默认开放以下两个端点：
- WebUI 访问地址：
http://<your-host>:<port>/ - REST API 地址：
http://<your-host>:<port>/api/v1/ner
⚠️ 注意：
<your-host>和<port>根据实际部署环境替换。若在本地运行且未修改端口，则通常为http://localhost:7860。
所有 API 请求均使用POST方法，Content-Type 设置为application/json。
3.2 请求参数说明
请求示例（curl）
curl -X POST http://localhost:7860/api/v1/ner \ -H "Content-Type: application/json" \ -d '{ "text": "阿里巴巴集团由马云在杭州创立，现任CEO是张勇。" }'参数字段说明
| 字段名 | 类型 | 必填 | 描述 |
|---|---|---|---|
text | string | 是 | 待分析的原始中文文本，长度建议不超过 512 字符 |
highlight | boolean | 否 | 是否返回 HTML 高亮格式，默认为false |
format | string | 否 | 返回格式类型，可选值：json（默认）、bio（BIO 标注序列） |
3.3 响应数据结构
成功响应示例（JSON 格式）
{ "code": 0, "message": "success", "data": { "entities": [ { "text": "阿里巴巴集团", "type": "ORG", "start": 0, "end": 6 }, { "text": "马云", "type": "PER", "start": 7, "end": 9 }, { "text": "杭州", "type": "LOC", "start": 10, "end": 12 }, { "text": "张勇", "type": "PER", "start": 17, "end": 19 } ], "highlight_html": "<mark style='background-color:#FF6B6B'>阿里巴巴集团</mark>由<mark style='background-color:#FF6B6B'>马云</mark>在<mark style='background-color:#4ECDC4'>杭州</mark>创立，现任CEO是<mark style='background-color:#FF6B6B'>张勇</mark>。" } }字段解释
| 字段路径 | 类型 | 说明 |
|---|---|---|
code | int | 状态码，0 表示成功，非 0 表示错误 |
message | string | 状态描述信息 |
data.entities[] | array | 识别出的实体列表 |
entities.text | string | 实体原文 |
entities.type | string | 实体类型：PER（人名）、LOC（地名）、ORG（机构名） |
entities.start | int | 实体在原文中的起始位置（字符索引） |
entities.end | int | 实体在原文中的结束位置（不包含） |
data.highlight_html | string | 当highlight=true时返回，可用于前端直接渲染 |
3.4 错误码说明
| code | message | 可能原因 |
|---|---|---|
| 1001 | text is required | 请求体缺少text字段 |
| 1002 | text too long | 文本超过最大长度限制（512 字符） |
| 1003 | invalid json format | 请求体不是合法 JSON |
| 5000 | internal server error | 服务内部异常（如模型加载失败） |
4. 实际应用代码示例
4.1 Python 调用示例
import requests import json def call_ner_api(text, api_url="http://localhost:7860/api/v1/ner"): payload = { "text": text, "highlight": True } try: response = requests.post( api_url, headers={"Content-Type": "application/json"}, data=json.dumps(payload, ensure_ascii=False) ) if response.status_code == 200: result = response.json() if result["code"] == 0: return result["data"] else: print(f"Error: {result['message']} (code: {result['code']})") return None else: print(f"HTTP Error: {response.status_code}") return None except Exception as e: print(f"Request failed: {str(e)}") return None # 示例调用 text = "腾讯公司总部位于深圳南山区，马化腾是其创始人之一。" result = call_ner_api(text) if result: print("识别到的实体：") for ent in result["entities"]: print(f" [{ent['type']}] '{ent['text']}' ({ent['start']}-{ent['end']})") print("\nHTML 高亮结果：") print(result["highlight_html"])输出结果
识别到的实体： [ORG] '腾讯公司' (0-4) [LOC] '深圳南山区' (7-11) [PER] '马化腾' (12-15) HTML 高亮结果： <mark style='background-color:#FF6B6B'>腾讯公司</mark>总部位于<mark style='background-color:#4ECDC4'>深圳南山区</mark>，<mark style='background-color:#FF6B6B'>马化腾</mark>是其创始人之一。4.2 JavaScript 前端调用示例
async function detectEntities(text) { const apiUrl = 'http://localhost:7860/api/v1/ner'; try { const response = await fetch(apiUrl, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ text }) }); const data = await response.json(); if (data.code === 0) { console.log('Entities:', data.data.entities); document.getElementById('result').innerHTML = data.data.highlight_html; } else { console.error('NER Error:', data.message); } } catch (error) { console.error('Request failed:', error); } } // 使用示例 detectEntities('百度在北京设有研发中心，李彦宏担任董事长。');5. 调试与优化建议
5.1 常见问题与解决方案
| 问题现象 | 可能原因 | 解决方案 |
|---|---|---|
| 返回 404 Not Found | API 路径错误 | 检查是否访问/api/v1/ner而非根路径 |
| 中文乱码 | 编码设置不当 | 确保请求头包含"Content-Type: application/json; charset=utf-8" |
| 实体识别不全 | 文本过长或语义模糊 | 分段处理长文本，避免超过 512 字符 |
| 服务无响应 | 模型加载耗时较长 | 首次启动需等待模型初始化完成，约 10-20 秒 |
5.2 性能优化建议
批量处理优化
当前接口为单文本处理模式。如需处理大量文本，建议使用异步队列机制或自行封装批处理逻辑。缓存高频查询
对于重复出现的文本片段（如常见公司名、地名），可在客户端添加缓存层，减少重复请求。前端防抖控制
若用于实时输入分析（如边打字边识别），建议加入防抖逻辑（debounce），避免频繁触发 API。跨域问题处理
若前端与服务不在同一域名下，需确保后端启用 CORS 支持。可在启动参数中添加--enable-cors标志（视具体实现而定）。
6. 总结
6.1 核心要点回顾
- AI 智能实体侦测服务基于达摩院RaNER 模型，提供高精度中文 NER 能力。
- 支持WebUI 可视化操作与REST API 程序化调用两种模式，满足多样化需求。
- REST 接口采用标准 JSON 格式通信，易于集成至各类系统。
- 实体类型包括人名（PER）、地名（LOC）、机构名（ORG），并支持返回 HTML 高亮标记。
- 提供完整的错误码体系，便于调试与异常处理。
6.2 下一步学习建议
- 尝试将 NER 结果接入知识图谱系统，构建企业关系网络
- 结合 OCR 技术，实现 PDF/图片文档中的实体自动抽取
- 利用 BIO 序列输出，训练下游分类或问答模型
- 探索自定义实体类型的扩展方式（需重新训练模型）
💡获取更多AI镜像
想探索更多AI镜像和应用场景？访问 CSDN星图镜像广场，提供丰富的预置镜像，覆盖大模型推理、图像生成、视频生成、模型微调等多个领域，支持一键部署。
