实体关系抽取 · LightAIP · frontend-intro-v5

1. 页面概览

1.1 是什么

实体关系抽取页面（EntityExtractPage.vue，V5 Stage 2 B2-1）把知识文档转化为结构化实体/关系，并注入 RAG 检索的第五通道（entity）。页面描述：知识文档 → LLM 抽取实体/关系 → 落表确认 → 注入 RAG 实体检索通道（doc:// URI 溯源）。

文档列表：复用知识库文档接口，对选中文档点「抽取」触发任务化 LLM 抽取。
抽取运行：POST /knowledge/documents/:id/extract 任务化部署，前端退避轮询 /extract_runs 至终态（1.5 秒起、每次 ×1.5、封顶 10 秒，截止 5 分钟；超时后保留状态并提供「继续轮询」）。
实体表格：名称/类型/别名/属性/置信度/状态/溯源（doc:// URI 可复制）/操作（确认/拒绝）。
关系表格：主语/谓词/宾语/宾语类型/置信度，只读展示。
关系简图：ECharts 力导向图，实体节点 + text 虚拟节点 + 谓词边。

1.2 核心价值

能力	说明
任务化抽取	提交后后台执行，前端退避轮询（1.5s→10s，截止 5 分钟，可续），不阻塞页面
人工确认闭环	实体确认保持沉淀，拒绝后不再进入 RAG 召回
doc:// 溯源	每个实体带来源 URI，可一键复制
关系可视化	力导向图展示实体与谓词边

1.3 一句话总结

实体关系抽取页把「文档知识」变成「可查询的知识图谱」：LLM 抽取 → 人工确认 → RAG 实体通道召回，全程 doc:// 可溯源。

2. 访问入口

2.1 路由与菜单

路由路径：/entity-extract，路由名 EntityExtract，meta.title 为「实体关系抽取」，requiresAuth: true。
菜单入口：Action 栏目左侧边栏「实体关系抽取」（ActionLayout.vue 第 5 项）。
源码文件：action/web/src/views/EntityExtractPage.vue。

2.2 认证与权限

路由级 requiresAuth: true，未登录访问跳 /login。
API 级：经 action/web/src/api/entityApi.js → aipClient.js 附带 aip_token Bearer；401 跳登录。
权限要求：普通登录用户可访问；接口挂在 AIP protected 组。

2.3 端口与 API 前缀

端口：18080（AIP 后端）。API 前缀：/aip-api/v1（Vite 代理到 18080 并重写为 /api/v1）。

3. 界面布局

实体关系抽取（页头 + 描述）
└─ 操作结果提示条
└─ 最近抽取运行卡片（doc_id + 状态徽标 + 实体/关系计数 + 错误 + 超时「继续轮询」）
└─ 知识文档卡片：按标题过滤 + 「刷新」；表格 ID/标题/格式/版本/更新时间/操作（抽取/查看实体）
└─ 实体卡片：状态过滤下拉 + 取回上限(200/500/1000) + 「刷新」；
     表格 名称/类型/别名/属性/置信度/状态/溯源/操作（确认/拒绝）+ 渲染层分页（20 条/页）
└─ 关系卡片：表格 主语/谓词/宾语/宾语类型/置信度 + 渲染层分页（20 条/页）
└─ 实体关系图卡片：ECharts 力导向图（420px 高）

各板块职责：

最近抽取运行：展示当前/最近一次抽取任务状态与结果计数，queued/running 时退避轮询刷新；到 5 分钟截止不丢状态，显示常驻提示 + 「继续轮询」按钮。
知识文档：选择要抽取的文档，行内「抽取」触发、「查看实体」设为活动文档。
实体表格：按状态过滤实体，行内确认/拒绝闭环；列表为渲染层分页（20 条/页），取回上限可切 200/500/1000。
关系表格：活动文档的关系列表（subject/object 名称已回填），同样渲染层分页。
实体关系图：活动文档的图谱，ECharts 力导向渲染，可拖拽缩放。

4. 交互元素详解

4.1 知识文档

控件	含义	操作效果	后端调用
输入「按标题过滤」+ 按钮「刷新」	过滤/刷新文档列表	`@input` 即时过滤（page 1、page_size 50）	GET /knowledge/documents
行内「抽取」	触发实体/关系抽取	任务化提交；同步完成直接刷新，否则启动轮询（按钮变「抽取中...」）	POST /knowledge/documents/:id/extract
行内「查看实体」	设为活动文档	加载该文档实体/关系/关系图	GET /entities、/relations、/graph

4.2 实体表格

控件	含义	操作效果	后端调用
下拉「全部状态/待确认/已确认/已拒绝」	实体状态过滤	切换即重新加载（页码复位第 1 页）	GET /entities?status=
下拉「取回上限」200/500/1000	实体/关系一次取回条数（后端 `limit`，默认 200、上限 1000）	切换即 `refreshActive` 重载实体/关系/图，页码复位	GET /entities?limit=、GET /relations?limit=
按钮「刷新」	刷新实体/关系/关系图	`refreshActive` 并行刷新三块	同上
分页「上一页/下一页」	实体、关系各一组渲染层分页（20 条/页）	仅切分已取回数据，不发请求	—
行内「确认」	确认实体（auto→confirmed）	成功提示「实体「xx」已确认」	POST /entities/:id/confirm
行内「拒绝」	拒绝实体（→rejected）	提示「已拒绝（RAG 不再召回）」	POST /entities/:id/reject
溯源 URI	`doc://...` 链接	点击复制 URI 到剪贴板	—

实体状态文案：auto=待确认、confirmed=已确认、rejected=已拒绝；类型徽标：person/org/product/metric/term/other 各自配色。表格下方提示「确认后的实体保持沉淀；拒绝的实体不再进入 RAG 实体检索通道。」。

4.3 关系表格与关系图

关系表格：只读；宾语类型按 object_id 是否为空显示「实体」或「文本」；主语/宾语名称已回填（subject_name/object_name），无名称回退 id/原文。
实体关系图：ECharts graph force 布局；text 虚拟节点 symbolSize 26、实体节点 44；边带谓词 label；可 roam/draggable；tooltip 悬停显示类型。未选文档时显示「选择左侧文档后展示实体关系图」。

5. 后端关联

5.1 API 客户端

本页使用 action/web/src/api/entityApi.js，复用 aipClient（baseURL /aip-api/v1）。unwrap 解析 {code, data}，错误取 body.error；extractDocument timeout 放宽到 120 秒。状态文案常量：ENTITY_STATUS_LABELS（auto/confirmed/rejected）、RUN_STATUS_LABELS（queued/running/success/failed）。

5.2 端点表

方法	路径（前缀 /aip-api/v1）	用途
GET	/knowledge/documents	文档列表（复用知识库路由，供抽取选择）
POST	/knowledge/documents/:id/extract	触发抽取（任务化返回 `{run, task}`）
GET	/entities?doc_id=&status=&limit=	实体列表
GET	/relations?doc_id=&limit=	关系列表（subject/object 名称回填）
POST	/entities/:id/confirm	确认实体
POST	/entities/:id/reject	拒绝实体
GET	/knowledge/documents/:id/graph	实体关系图数据（nodes/edges）
GET	/extract_runs?doc_id=&limit=	抽取运行记录（前端轮询任务状态）

5.3 关键机制

任务化抽取与轮询（退避 + 可续）：extractDocument 在注入 task.Manager 时返回 {run, task}；前端 startPolling 以退避节奏 GET /extract_runs?doc_id=&limit=1 取最新 run——延迟 1.5 秒起、每次 ×1.5、封顶 10 秒，截止时间 5 分钟（对齐 FusionPage.vue 既有范式）。queued/running 期间运行卡片标注「退避轮询中」；到 success/failed 停轮询并刷新数据。到 5 分钟仍未终态时不丢状态：保留 currentRun、置 pollTimedOut 并露出「继续轮询」按钮（点击继续轮询至终态）；轮询令牌 pollToken 在 onBeforeUnmount 中被递增，使在途循环失效，避免离开页面后继续请求。
取回上限与渲染层分页：/entities 与 /relations 仅支持 limit（<=0 默认 200、上限 1000），无 offset，故实体表与关系表各做渲染层分页（20 条/页 + 上/下一页），页面常驻标注「无服务端分页」。
抽取流水线：分块遍历 → 每块 LLM 抽取（限定 JSON schema：entities[名称/类型/别名/属性/原文片段]、relations[主语/谓词/宾语]）→ 坏 JSON 重试 1 次 → 去重落表；单 chunk 最大 6000 字符；置信度默认 0.6；实体类型白名单 person/org/product/metric/term/other（可配置）。
RAG 第五通道：实体经确认后进入 entity 检索通道（权重 0.10，四通道权重调整为 metadata 0.35/knowledge 0.25/history 0.15/fewshot 0.15/entity 0.10）；recallEntity 按 name/aliases LIKE 匹配实体 → 取命中实体所在 chunk 的 doc://aip/<docID>?chunk=n URI 与文本参与召回；拒绝的实体不再召回。
图数据：GET /knowledge/documents/:id/graph 由实体关系构造 nodes/edges，ECharts graph 直接消费；text 虚拟节点表示非实体宾语。

6. 权限与安全

认证：aip_token JWT；401 清理并跳登录。
权限范围：接口挂 AIP protected 组；抽取/确认/拒绝均记录当前用户（currentUserID，缺省回退 system）。
写操作防护：抽取触发按钮提交中禁用（防重复提交）；确认/拒绝为显式动作；实体 URI 为只读溯源信息，点击仅复制。

7. 常见问题与排错

7.1 点「抽取」一直停留在「抽取中...」或运行卡片卡在排队

现象：按钮长时间「抽取中...」，运行卡片状态为「排队中」或「抽取中」且不再刷新。原因：任务队列繁忙、LLM 网关 entity_extract 路由缺失，或轮询已达 5 分钟截止时间而自动停止（任务仍在后台执行）。处理：确认 18080 AIP 后端存活与 LLM 网关路由已种 entity_extract；到截止时间后点运行卡片里的「继续轮询」即可续轮询至终态（状态不会丢失）；亦可等队列消化后重新点「抽取」；若报错查看运行卡片的 error 文本。

7.2 抽取失败提示「抽取失败: ...」

现象：轮询到 failed，alert 红条提示失败原因。原因：LLM 调用失败、文档无内容可分块，或任务执行异常。处理：看运行卡片 error 字段；确认文档内容非空；检查 LLM 网关配置后重新触发。

7.3 实体/关系表格为空

现象：「查看实体」后实体表显示「暂无实体（选择文档并抽取）」，关系表「暂无关系」。原因：文档尚未抽取，或抽取未成功；状态过滤与活动文档不匹配。处理：确认已点「抽取」且运行状态为「完成」；确认状态过滤未限制；点「刷新」重载。

7.4 关系图不显示或为空白

现象：选择文档后关系图区空白，或提示「选择左侧文档后展示实体关系图」。原因：GET /graph 未返回 nodes（无抽取结果）；或 ECharts 渲染时容器隐藏。处理：确认抽取成功且有实体；点「刷新」重载；浏览器窗口缩放会自动 chart.resize()。

8. 已知缺陷与边界

项目	说明
抽取依赖 LLM	无规则降级路径，LLM 网关未注入时 `ExtractDocument` 直接报错
轮询为退避 + 可续	延迟 1.5s 起、每次 ×1.5、封顶 10s，截止 5 分钟；到截止时间停止轮询但保留状态并露出「继续轮询」按钮（任务仍在后台执行）。轮询令牌在组件卸载时失效，不会在离开页面后继续请求
实体扫描上限 1000	RAG 实体通道单次扫描实体数上限 `entityScanLimit=1000`
列表为渲染层分页	`/entities`、`/relations` 仅支持 `limit`（默认 200、上限 1000），无 `offset`/`total` 分页契约（`entityextract/rest.go:58-89`、`service.go:427-473`），故分页在已取回数组上做（20 条/页）；超出取回上限（默认 200，可切 500/1000）的更早数据当前不可见，需后端补 `offset` 才能真分页
图仅活动文档	关系图只展示当前活动文档的实体关系，无全局图谱
关系只读	本页不支持编辑/删除关系，仅实体可确认/拒绝

相邻页面：知识库管理 · 知识库分层树 · 元数据语义标注