元数据语义标注 · LightAIP

1. 页面概览

1.1 是什么

元数据语义标注页面（SchemaAnnotationPage.vue，V5 Stage 2 B2-4）对已导入元数据的数据源做「表间关系 + 列语义」推断并人工确认闭环。页面描述：数据源元数据 → 采样 + 外键/命名启发 + LLM 推断表间关系与列语义 → 人工确认闭环。

数据源选择：下拉选择已导入元数据的数据源（GET /datasources 复用数据源管理接口）。
运行推断：POST /datasources/:id/infer-relationships 任务化部署，前端每 2 秒轮询 GET /tasks/:id 至终态；同步模式直接返回 run。
关系推断表格：来源表/来源列/目标表/目标列/类型（外键/语义/连接路径）/置信度/来源/状态/操作（确认/驳回）。
列语义标注表格：表/列/语义类型（枚举/金额/标识符/文本/指标/维度/时间）/描述/置信度/来源/状态/操作（确认）。

1.2 核心价值

能力	说明
双路推断	FK/命名启发 + LLM 批量判定，来源诚实标注（llm / 规则）
任务化执行	推断提交后台执行，前端轮询不阻塞
人工确认闭环	确认关系写入语义层依据，驳回不再被采纳
列语义标注	7 类 semantic_type 徽标展示，逐列确认

1.3 一句话总结

元数据语义标注页给数据源「补语义」：自动推断表间关系与列含义，人工确认后成为 NLQ/SQL 生成的语义层依据。

2. 访问入口

2.1 路由与菜单

路由路径：/schema-annotation，路由名 SchemaAnnotation，meta.title 为「元数据语义标注」，requiresAuth: true。
菜单入口：Action 栏目左侧边栏「元数据语义标注」（ActionLayout.vue 第 6 项）。
源码文件：action/web/src/views/SchemaAnnotationPage.vue。

2.2 认证与权限

路由级 requiresAuth: true，未登录访问跳 /login。
API 级：经 action/web/src/api/schemaAiApi.js → aipClient.js 附带 aip_token Bearer；401 跳登录。任务轮询 GET /tasks/:id 手动附带 Bearer 头。
权限要求：普通登录用户可访问；接口挂 AIP protected 组。

2.3 端口与 API 前缀

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

3. 界面布局

元数据语义标注（页头 + 描述）
└─ 操作结果提示条
└─ 数据源卡片：下拉（请选择数据源（需已导入元数据））+「运行推断」+「刷新」
   └─ 最近一次推断提示（表 N · 采样 N · 候选关系 N · 写入关系 N · 标注 N + source 徽标）
└─ 关系推断卡片：表格 来源表/来源列/目标表/目标列/类型/置信度/来源/状态/操作（确认/驳回）
└─ 列语义标注卡片：表格 表/列/语义类型/描述/置信度/来源/状态/操作（确认）

各板块职责：

数据源：选择推断目标并触发「运行推断」；下方提示最近一次推断摘要（含 source 徽标：LLM 绿 / 规则橙）。
关系推断：数据源表间候选关系，确认/驳回闭环。
列语义标注：列语义类型候选，确认后成为语义标注。

4. 交互元素详解

4.1 数据源选择与推断

控件	含义	操作效果	后端调用
下拉「请选择数据源（需已导入元数据）」	推断目标	切换即清空并加载该源的关系/标注	GET /datasources/:id/relationships、/annotations
按钮「运行推断」/「推断中...」	触发推断	任务化提交返回 task_id 则启动轮询；同步返回 run 直接刷新	POST /datasources/:id/infer-relationships
按钮「刷新」	重载数据源列表	重查 GET /datasources	—

「最近一次推断」提示示例：最近一次推断（数据源 1）：表 3 · 采样 2 · 候选关系 2 · 写入关系 1 · 标注 5，并带来源徽标（llm=run-ok 绿、rule_only=run-degraded 橙）；任务执行中追加「（任务执行中，每 2 秒刷新...）」。

4.2 关系推断表格

控件	含义	操作效果	后端调用
行内「确认」	suggested → confirmed	提示「关系表.列 → 表.列已确认」并重载	POST /schemaai/relationships/:id/confirm
行内「驳回」	suggested/confirmed → rejected	提示「关系已驳回」并重载	POST /schemaai/relationships/:id/reject

列展示：来源表、来源列、目标表、目标列、类型徽标（外键/语义/连接路径）、置信度百分比、来源（LLM/规则）、状态（待确认/已确认/已拒绝）。表格下方提示「确认的关系写入语义层依据（suggested/rejected 不参与）；驳回的关系不再被采纳。」。

4.3 列语义标注表格

行内「确认」把 suggested → confirmed（提示「标注表.列已确认」）。列展示：表、列、语义类型徽标（枚举/金额/标识符/文本/指标/维度/时间，各配色）、描述（悬浮看全文）、置信度、来源、状态（已确认/待确认）。已确认行不再显示确认按钮。

5. 后端关联

5.1 API 客户端

本页使用 action/web/src/api/schemaAiApi.js，复用 aipClient（baseURL /aip-api/v1）。listDataSources 走原始响应 {data_sources:[...]}；inferRelationships timeout 120s；RELATION_STATUS_LABELS/RELATION_TYPE_LABELS/SEMANTIC_TYPE_LABELS/sourceLabel 提供中文文案与来源标注。

5.2 端点表

方法	路径（前缀 /aip-api/v1）	用途
GET	/datasources	数据源列表（返回原始 `{data_sources:[...]}`）
POST	/datasources/:id/infer-relationships	触发关系/标注推断（任务化返回 `{task_id, task}`；同步返回 `{run}`）
GET	/datasources/:id/relationships	关系推断列表（status/relation_type/limit 过滤）
POST	/schemaai/relationships/:id/confirm	确认关系推断
POST	/schemaai/relationships/:id/reject	驳回关系推断
GET	/datasources/:id/annotations	列语义标注列表（status/semantic_type/limit 过滤）
POST	/schemaai/annotations/:id/confirm	确认列标注
GET	/tasks/:id	任务详情（前端轮询推断终态）

5.3 关键机制

推断流水线（service.go）：① 读 table_schemas / column_schemas；② FK/命名启发产生候选关系（*_id 后缀匹配表名单数 confidence 0.8；列名 == 其他表主键名 confidence 0.6）；③ 每表经连接器 LIMIT 20 采样（连接器缺失不阻塞，标注 sampled=false）；④ 候选关系对喂 LLM 批量判定（JSON 输出 + 置信度，坏 JSON 重试 1 次，单次候选上限 40）；⑤ 列语义标注 LLM 批量判定（每批 3 表、每列带 3 个采样值）；⑥ 落表：人工 confirmed/rejected 保留，suggested 原位更新。
降级约定：llm 服务为 nil 或调用/解析失败时仅规则推断与类型映射启发，source="rule_only"（页面徽标橙）；LLM 成功 source="llm"（绿）。采样成功但零重叠时置信度折减 0.5。
任务化与轮询：InferDataSource 注入 task.Manager 时返回 {task_id, task}，前端 pollTask 每 2 秒 GET /tasks/:id，status=success 时取 t.result 为 run 摘要并重载数据；failed 报错停止。
状态机：关系推断 suggested（待确认）/confirmed（已确认）/rejected（已拒绝）；列标注 suggested/confirmed 两态。确认的关系才进入语义层依据。

6. 权限与安全

认证：aip_token JWT；401 清理并跳登录；轮询任务手动附带 Bearer 头。
权限范围：接口挂 AIP protected 组；推断/确认/驳回记录当前用户（缺省回退 anonymous）；AI 决策类审计按 refType="ai_decision" 打点。
写操作防护：确认/驳回为显式动作；推断提交中按钮禁用；关系/标注列表默认 limit 200/500。

7. 常见问题与排错

7.1 下拉没有可选数据源

现象：数据源下拉为空，只有「请选择数据源（需已导入元数据）」。原因：GET /datasources 返回空列表——尚未创建数据源或未导入元数据。处理：先在「数据源管理」创建数据源并导入元数据（table_schemas/column_schemas），再回本页点「刷新」。

7.2 点「运行推断」提示「推断失败: ...」或「提交推断失败」

现象：红条提示失败（任务轮询到 failed 或提交被拒）。原因：数据源无元数据、连接器采样异常、LLM 网关 schema_annotation 路由未种或未配置。处理：确认数据源已导入元数据；检查 LLM 网关配置；重新点「运行推断」。

7.3 推断完成但徽标显示「规则」（rule_only）

现象：最近一次推断 source 徽标为橙「规则」。原因：LLM 未注入或调用/解析失败，走了规则降级路径（诚实标注）。处理：非错误；若需要 LLM 推断，检查 LLM 网关与 schema_annotation 默认路由后重跑。

7.4 确认/驳回后列表没有变化

现象：点「确认」/「驳回」提示成功但表格状态未变。原因：loadData 重载被并发覆盖，或列表 limit 截断看不到目标行。处理：点「刷新」手动重载；用状态筛选（如「待确认」）定位目标行。

8. 已知缺陷与边界

项目	说明
采样不阻塞	连接器缺失/失败时跳过采样（sampled=false），推断仍继续
规则降级	LLM 不可用时仅 FK/命名启发，无列语义深判
置信度折减	采样成功但零重叠时候选置信度减半（confNoOverlapRatio=0.5）
候选上限	单次 LLM 关系判定候选上限 40，超大库分批处理

注：任务无取消入口（POST /tasks/:id/cancel 未暴露）已于 2026-09-06 修复（取消按钮 + 终态 cancelled）。

注：轮询用原生 fetch 手写 Bearer（与其他 axios 调用风格不一致）已于 2026-09-06 修复（改走统一 api client 拦截器）。

相邻页面：实体关系抽取 · 知识库分层树 · 数据源管理