实体关系抽取

1. 页面概览

1.1 是什么

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

• 文档列表：复用知识库文档接口，对选中文档点「抽取」触发任务化 LLM 抽取。
• 抽取运行：POST /knowledge/documents/:id/extract 任务化部署，前端每 2 秒轮询 /extract_runs 至终态。
• 实体表格：名称/类型/别名/属性/置信度/状态/溯源（doc:// URI 可复制）/操作（确认/拒绝）。
• 关系表格：主语/谓词/宾语/宾语类型/置信度，只读展示。
• 关系简图：ECharts 力导向图，实体节点 + text 虚拟节点 + 谓词边。

1.2 核心价值

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/标题/格式/版本/更新时间/操作（抽取/查看实体）
└─ 实体卡片：状态过滤下拉 + 「刷新」；表格 名称/类型/别名/属性/置信度/状态/溯源/操作（确认/拒绝）
└─ 关系卡片：表格 主语/谓词/宾语/宾语类型/置信度
└─ 实体关系图卡片：ECharts 力导向图（420px 高）

各板块职责：

• 最近抽取运行：展示当前/最近一次抽取任务状态与结果计数，queued/running 时每 2 秒自动刷新。
• 知识文档：选择要抽取的文档，行内「抽取」触发、「查看实体」设为活动文档。
• 实体表格：按状态过滤实体，行内确认/拒绝闭环。
• 关系表格：活动文档的关系列表（subject/object 名称已回填）。
• 实体关系图：活动文档的图谱，ECharts 力导向渲染，可拖拽缩放。

4. 交互元素详解

4.1 知识文档

4.2 实体表格

实体状态文案：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 端点表

5.3 关键机制

• 任务化抽取与轮询：extractDocument 在注入 task.Manager 时返回 {run, task}；前端 startPolling 每 2 秒 GET /extract_runs?doc_id=&limit=1 取最新 run，queued/running 期间运行卡片标注「（每 2 秒自动刷新）」，到 success/failed 停轮询并刷新数据；轮询上限 120 次（约 4 分钟）自动停止。
• 抽取流水线：分块遍历 → 每块 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 路由缺失，或轮询达到 120 次上限后停止。处理：确认 18080 AIP 后端存活与 LLM 网关路由已种 entity_extract；等队列消化后重新点「抽取」；若报错查看运行卡片的 error 文本。

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

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

7.3 实体/关系表格为空

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

7.4 关系图不显示或为空白

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

8. 已知缺陷与边界

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