P4 Gotham

实体解析：把"同一个人"认出来

跨源数据里"张远"可能是"张远 / 张远(玄武) / ZHANG YUAN"——实体解析用四层流水线打分、union-find 聚类、三阈值带分流，把同一个人自动归并到图上一个节点。看完这 4 个故事，你就能跑通"建作业 → 聚类 → 看统计 → 人工审核"的全流程。

合规顾问数据治理工程师相似度打分聚类阈值带人工审核共 4 个故事

能 / 不能速览

✅ 这个主题能做

创建解析作业并执行四层流水线：L1 确定性 / L2 规则 / L3 模糊 / L4 AI（灰区）
三阈值带分流：score ≥0.90 自动合并；0.70~0.90 待审核；<0.70 拒绝
union-find 聚类把自动合并对聚成 canonical 实体簇，代表实体写回图（resolved:{type}:{repr}）
查看作业的 clusters / pairs / stats，理解相似度分布与阈值带
人工审核 review 对：并排对比属性，确认合并或拒绝

⛔ 这个主题做不了

AI 增强层默认关闭：server 配置 LLM Provider（deepseek / dashscope 任一）才自动注入 AI 网关，未配置时灰区（0.35~0.85）没有 AI 裁决，按 L3 模糊分数分流
只有 auto_merged 对参与聚类，review 对不进簇，必须人工确认后才生效
作业名称全局唯一，重复创建同名作业返回 409
阈值（0.90 / 0.70）是默认值，需按场景在作业配置里调整，安全场景建议提高阈值

适用角色

本主题面向两类角色：

合规顾问：核心使用者，负责跨源数据的同人识别与人工审核，确保"一个主体只留一个节点"。
数据治理工程师：建解析作业、调阈值、看统计，把解析流水线跑稳。

解析作业消费 fusion 的融合实体（fused_entities），所以通常先做多源接入（fusion 主题）再跑解析。

能力速览（能做什么）

四层打分流水线

L1 确定性（external_id / fingerprint 相等 → 1.0）、L2 规则（归一化 / 别名表 / 拼音首字母）、L3 模糊（Levenshtein + Jaro-Winkler + Dice）、L4 AI（灰区可选）。

三阈值带分流

score ≥0.90 自动合并、0.70~0.90 待审核、<0.70 拒绝；每对匹配都记录 status / decision / layer / reason。

聚类写图

union-find 连通分量把 auto_merged 对聚成实体簇，代表实体写入 GraphStore（resolved:{type}:{repr}）。

人工审核回路

并排对比相似对属性、确认合并 / 拒绝，review 对处理完后再聚类生效，形成"算法建议 + 人定案"闭环。

调整指南（怎么调整）

改阈值：作业 config 里可覆盖 accept（默认 0.90）与 candidate（默认 0.70）；安全敏感场景提高 accept 降低误合并，召回优先可下调。
改分块：流水线先按 entity_type + 拼音首字母分块再桶内两两比对，避免全量 O(n²)；分块粒度影响召回，漏块可重跑作业。
改审核顺序：先按 similarity_score 降序处理 review 对，优先解决高置信待审对；确认合并后簇会更新。
改别名表：通过 Options.SynonymMap 注入额外同义词（如"有限公司"→"公司"），提升机构名命中。

做得好的场景

实体解析最擅长"跨源同人识别"：

自动合并高置信对：external_id 或归一化姓名完全一致的对直接 auto_merged，不用人管。
谐音别名被规则命中：拼音首字母相同、别名表命中的对拿到 0.85~0.95 分，进合并或待审带。
低分对自动拒绝：相似度明显不足的对直接 rejected，不打扰人工。
人审有据：每对都带 layer / reason，审核时可以看"为什么给了这个分"。

限制与不足

以下是明确的边界，使用前先知道：

AI 层默认关闭：AI 网关由 server 按 LLM Provider 配置自动注入（配 deepseek / dashscope key 即接入），未配置则告警降级——AI 灰区（0.35~0.85）不裁决，直接按 L3 模糊分分流；要启用 AI 需网关已注入，且作业级 enable_ai 或全局 EnableAI 任一开启。
阈值是经验值：0.90 / 0.70 为默认，不同实体类型、不同业务场景要按需调整。
聚类只吃 auto_merged：review 对必须人工确认后才会反映到簇与图上。
作业名唯一：同名作业重复创建返回 GOTHAM_RESOLUTION_JOB_DUPLICATE（409）。

场景故事

故事 1 建一个解析作业跑一遍，跨源同名同人开始被聚类

场景：建作业角色：合规顾问耗时：约 6 分钟

背景: 韩律师是某律所的合规顾问，负责帮客户做关联方尽调。fusion 里已有演示源 gotham_demo_personnel 的 5 条人员记录，他自己又接了一份 CSV，两个源里都出现"张远""吴刚"等名字。他要在 /gotham/resolution 建一个 person 解析作业，把两个源的候选跑一遍。

传统做法对比: 以前两个源里同一个人，要人工比对姓名、证件、电话，一份几十人的名单对完要一整天，还容易漏。现在建个作业点运行，算法先自动筛一遍，人只处理算法拿不准的少数对。

角色: 韩律师（合规顾问，创建解析作业并执行）。

操作步骤

进入实体解析页 /gotham/resolution，点"新建作业"
填写 name=person_resolution_0809、entity_type=person
source_ids 勾选演示源与 CSV 源
保存后点"运行作业"
查看作业状态与统计

系统响应

作业状态机 pending → running → completed，返回摘要：

{
  "name": "person_resolution_0809",
  "entity_type": "person",
  "status": "completed",
  "total_candidates": 10,
  "matched_pairs": 3,
  "auto_merged": 2,
  "pending_review": 1
}

候选来自两个源合并去重后的实体池。

结果洞察: 10 条候选里算法找出 3 对相似对：2 对高分自动合并、1 对落在待审带。同名同人的"张远"在两源里被识别为同一实体并聚类，韩律师不用再人肉比对。

调整建议: 作业的 source_ids 决定参与解析的源，别漏选；同一份候选可以建多个作业（不同 entity_type、不同阈值）分别跑。

动手试一试: 操作：新建作业 name=person_resolution_0809、entity_type=person、source_ids=[演示源 id]，运行。预期结果：状态流转 pending→running→completed，统计出现 total_candidates / matched_pairs / auto_merged / pending_review 四组数字。

限制提示: 作业名称全局唯一，重复创建同名作业返回 409 GOTHAM_RESOLUTION_JOB_DUPLICATE；未配置 LLM Provider 时 AI 层不启用（网关不注入），灰区对按 L3 模糊分直接分流，不会出现 ai_decided 计数。

故事 2 看聚类 clusters 与匹配对 pairs，搞清谁被并进了一个簇

场景：聚类查看角色：合规顾问耗时：约 5 分钟

背景: 作业跑完后，韩律师要看聚类结果：哪些候选被并进同一个簇、代表实体是谁、簇内相似度多少。他打开作业详情里的 clusters 与 pairs 两个标签页。

传统做法对比: 以前"谁合并了谁"全靠人记，换个同事接手就说不清。现在每个簇有 entity_ids、代表实体与相似度，每条相似对带分数与状态，证据链清清楚楚。

角色: 韩律师（合规顾问，查看聚类与匹配对）。

操作步骤

打开作业详情，进入 clusters 标签页
查看每个簇的 entity_ids / representative_id / status / similarity_score
切换到 pairs 标签页，按 status 过滤查看 auto_merged / review / rejected
点开一条 pair 看 layer / reason

系统响应

簇与相似对结构示例：

// EntityCluster
{ "entity_ids": [3, 4], "representative_id": "resolved:person:3",
  "status": "auto", "similarity_score": 0.95 }
// ResolutionPair
{ "entity_a_id": 3, "entity_b_id": 4, "similarity_score": 0.95,
  "status": "auto_merged", "decision": "合并", "layer": "rule",
  "reason": "归一化名称相等" }

代表实体写回图节点 resolved:{type}:{repr}。

结果洞察: 演示数据里张远等人物若在多个源出现，会被聚进对应簇，representative_id 形如 resolved:person:{repr}；pair 的 layer 字段告诉你这一分来自哪层（deterministic / rule / fuzzy），reason 给出依据，审计时可引用。

调整建议: 先看 clusters 拿到"一伙"的全貌，再下钻到 pairs 看每对怎么打分的；用 status 过滤只留 review 的，进入下一步人工审核。

动手试一试: 操作：/resolution/jobs/:id/clusters 与 /resolution/jobs/:id/pairs?status=auto_merged。预期结果：clusters 返回带 entity_ids 与 representative_id 的簇；pairs 返回 status=auto_merged 的对，并带 similarity_score / layer / decision。

限制提示: 只有 auto_merged 对参与 union-find 聚类；review / rejected 对不会出现在簇里。簇的 similarity_score 是簇内成员对相似度的均值，不代表单个成员的绝对置信度。

故事 3 看作业统计 stats，理解 0.90 / 0.70 阈值带怎么分流

场景：阈值带角色：数据治理工程师耗时：约 4 分钟

背景: 数据治理工程师小孟负责把解析流水线调稳。他想通过作业统计理解一批候选里"多少对自动合并、多少对要人看、多少对直接拒绝"，据此决定要不要调阈值。

传统做法对比: 以前阈值藏在脚本里，改一次要发版，效果靠跑完数结果才知道。现在作业 stats 直接把三档数量摊开，阈值影响一目了然。

角色: 小孟（数据治理工程师，看统计、调阈值）。

操作步骤

打开作业详情，进入 stats 标签页
查看 total_candidates / matched_pairs / auto_merged / pending_review / rejected
对照三阈值带理解每一档的构成
决定是否调整 accept / candidate 后重跑

系统响应

统计接口返回：

{
  "total_candidates": 10,
  "matched_pairs": 3,
  "auto_merged": 2,
  "pending_review": 1,
  "rejected": 0
}

三阈值带逻辑：score ≥0.90 → auto_merged；0.70~0.90 → review；<0.70 → rejected。

结果洞察: 这批候选 3 对里有 2 对自动合并、1 对待审，没有直接拒绝的——说明两源数据的同名记录相似度普遍较高。如果 pending_review 长期积压，说明 0.70 的 candidate 阈值偏松；如果 auto_merged 出现明显误合并，就应把 accept 提到 0.95。

调整建议: 安全敏感场景把 accept 调高（如 0.95）降低误合并；召回优先场景可下调 candidate 让更多对进待审；阈值按实体类型可覆盖，不同类型用不同档位。

动手试一试: 操作：/resolution/jobs/:id/stats。预期结果：返回 total_candidates / matched_pairs / auto_merged / pending_review 等计数；结合默认阈值 0.90 / 0.70 解读每一档为什么这么分。

限制提示: 0.90 / 0.70 是 DefaultOptions 的默认值（可在作业 config 覆盖）；AI 灰区默认 [0.35, 0.85)，但未配置 LLM Provider 时 AI 层不启用，灰区对不产生 ai_decided 计数，按 L3 分直接分流。

故事 4 人工核对相似对，确认合并 / 拒绝，人定案

场景：人工审核角色：合规顾问耗时：约 7 分钟

背景: 韩律师要处理作业里那 1 对 pending_review：两个实体名字相似但属性略有出入。实体解析工作台支持并排对比属性、差异高亮，他要在"确认合并"与"拒绝"之间做决定。

传统做法对比: 以前这种"像又不像"的对子最熬人：要开两个窗口来回比姓名、职务、公司，比完还要担心比漏。现在工作台并排展示、差异高亮，确认 / 拒绝一键完成。

角色: 韩律师（合规顾问，行使人工审核定案权）。

操作步骤

打开作业的 pairs，过滤 status=review
并排对比两个实体的属性（name / org / role / amount）
判断是否同一人：确认合并 / 拒绝
确认后回到图工作台，看合并后的代表节点（merged=true、merged_entity_ids 记录）

系统响应: 确认合并后该对 status 从 review 转为 manual_merged（decision=合并）；图层面执行 MergeNode（属性更完整者为主节点，代表实体写回图节点 resolved:person:{repr}，merged=true + merged_entity_ids 记录），两端融合实体回填 resolved；拒绝后该对 status=rejected，不产生图节点。注意：人工确认合并不新建实体簇，合并直接作用于图。

结果洞察: 韩律师确认后，跨源同人正式收敛为图上一个节点（merged=true，可回图工作台查到），尽调报告里引用该实体时不会再出现"同一个人的两条记录"。审核动作本身留痕（EntityMergeLog），可追溯谁在何时做了决定。

调整建议: 先按 similarity_score 降序处理 review 对，优先解决高置信待审对；属性差异大的对谨慎合并，宁可拒绝也不要误并。

动手试一试: 操作：pairs 过滤 status=review，并排对比后对某一对点"确认合并"。预期结果：该对变为 manual_merged（decision=合并），图工作台出现合并后的代表节点（merged=true、merged_entity_ids 记录，节点 ID 形如 resolved:person:{repr}），两端融合实体回填 resolved。

限制提示: review 对必须人工处理后才会反映到簇与图；低分对（<0.70）已被 rejected，不会出现在待审列表里，若漏检需要降低 candidate 阈值或补充源数据后重跑。

常见问题

解析作业的输入是什么？

输入是 fusion 模块的融合实体候选（fused_entities），按 entity_type 筛选、按 source_ids 限定来源。所以通常先做多源接入，再建解析作业，两个主题是先后关系。

0.90 / 0.70 这两个阈值能改吗？

能。DefaultOptions 里 accept=0.90、candidate=0.70，作业 config 可按实体类型覆盖。提高 accept 更保守、降低误合并；降低 candidate 会让更多对进入待审、提升召回。

AI 层什么时候会用上？

AI 层只在相似度落入灰区 [0.35, 0.85)、server 已配置 LLM Provider（自动注入网关）且 enable_ai（作业级或全局 EnableAI）为真时才生效，由 LLM 输出 {same, score, reason} 裁决。未配置 LLM 时默认关闭，灰区对直接按 L3 模糊分分流，不会阻塞作业。

为什么有的对直接被我跳过了？

如果它不在 pairs 列表里，多半是相似度低于 0.70 被判 rejected，或它与你的过滤条件不符。想看低分对可调整 candidate 阈值；想找回漏块的同名实体，需补源数据后重跑作业。

人工确认合并后会发生什么？

该对状态变为 manual_merged（decision=合并），直接在图层执行 MergeNode：属性更完整者为主节点，次节点被吸收删除，代表实体写入图存储（节点 ID=resolved:{type}:{repr}，merged=true、merged_entity_ids 记录），回到图工作台就能看到收敛后的单一节点。人工确认不新建实体簇，与自动合并（auto_merged 对生成簇）是两条路径。

主题小结

一句话：实体解析用"四层打分 + union-find 聚类 + 三阈值带"把跨源同人自动归并到图上一个节点，人工只处理 0.70~0.90 待审带。记住边界：AI 层默认关闭（配置 LLM Provider 自动注入网关即启用）、聚类只吃 auto_merged、阈值可调、作业名唯一。算法先筛，人定案。