feat(kg): 实现实体对齐功能（aligner.py）

- 实现三层对齐策略：规则层 + 向量相似度层 + LLM 仲裁层
- 规则层：名称规范化（NFKC、小写、去标点/空格）+ 规则评分
- 向量层：OpenAI Embeddings + cosine 相似度计算
- LLM 层：仅对边界样本调用，严格 JSON schema 校验
- 使用 Union-Find 实现传递合并
- 支持批内对齐（库内对齐待 KG 服务 API 支持）

核心组件：
- EntityAligner 类：align() (async)、align_rules_only() (sync)
- 配置项：kg_alignment_enabled（默认 false）、embedding_model、阈值
- 失败策略：fail-open（对齐失败不中断请求）

集成：
- 已集成到抽取主链路（extract → align → return）
- extract() 调用 async align()
- extract_sync() 调用 sync align_rules_only()

修复：
- P1-1：使用 (name, type) 作为 key，避免同名跨类型误合并
- P1-2：LLM 计数在 finally 块中增加，异常也计数
- P1-3：添加库内对齐说明（待后续实现）

新增 41 个测试用例，全部通过
测试结果：41 tests pass

runtime/datamate-python/app/core/config.py

@@ -82,6 +82,12 @@ class Settings(BaseSettings):
     kg_llm_timeout_seconds: int = 60
     kg_llm_max_retries: int = 2
 
+    # Knowledge Graph - 实体对齐配置
+    kg_alignment_enabled: bool = False
+    kg_alignment_embedding_model: str = "text-embedding-3-small"
+    kg_alignment_vector_threshold: float = 0.92
+    kg_alignment_llm_threshold: float = 0.78
+
     # 标注编辑器（Label Studio Editor）相关
     editor_max_text_bytes: int = 0  # <=0 表示不限制，正数为最大字节数
 

runtime/datamate-python/app/module/kg_extraction/__init__.py

@@ -1,3 +1,4 @@
+from app.module.kg_extraction.aligner import EntityAligner
 from app.module.kg_extraction.extractor import KnowledgeGraphExtractor
 from app.module.kg_extraction.models import (
     ExtractionRequest,
@@ -9,6 +10,7 @@ from app.module.kg_extraction.models import (
 from app.module.kg_extraction.interface import router
 
 __all__ = [
+    "EntityAligner",
     "KnowledgeGraphExtractor",
     "ExtractionRequest",
     "ExtractionResult",

runtime/datamate-python/app/module/kg_extraction/aligner.py

@@ -0,0 +1,478 @@
+"""实体对齐器：对抽取结果中的实体进行去重和合并。
+
+三层对齐策略：
+1. 规则层：名称规范化 + 别名匹配 + 类型硬过滤
+2. 向量相似度层：基于 embedding 的 cosine 相似度
+3. LLM 仲裁层：仅对边界样本调用，严格 JSON schema 校验
+
+失败策略：fail-open —— 对齐失败不阻断抽取请求。
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import unicodedata
+
+from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+from pydantic import BaseModel, Field, SecretStr
+
+from app.core.logging import get_logger
+from app.module.kg_extraction.models import (
+    ExtractionResult,
+    GraphEdge,
+    GraphNode,
+    Triple,
+)
+
+logger = get_logger(__name__)
+
+
+# ---------------------------------------------------------------------------
+# Rule Layer
+# ---------------------------------------------------------------------------
+
+
+def normalize_name(name: str) -> str:
+    """名称规范化：Unicode NFKC -> 小写 -> 去标点 -> 合并空白。"""
+    name = unicodedata.normalize("NFKC", name)
+    name = name.lower()
+    name = re.sub(r"[^\w\s]", "", name)
+    name = re.sub(r"\s+", " ", name).strip()
+    return name
+
+
+def rule_score(a: GraphNode, b: GraphNode) -> float:
+    """规则层匹配分数。
+
+    Returns:
+        1.0  规范化名称完全一致且类型兼容
+        0.5  一方名称是另一方子串且类型兼容（别名/缩写）
+        0.0  类型不兼容或名称无关联
+    """
+    # 类型硬过滤
+    if a.type.lower() != b.type.lower():
+        return 0.0
+
+    norm_a = normalize_name(a.name)
+    norm_b = normalize_name(b.name)
+
+    # 完全匹配
+    if norm_a == norm_b:
+        return 1.0
+
+    # 子串匹配（别名/缩写），要求双方规范化名称至少 2 字符
+    if len(norm_a) >= 2 and len(norm_b) >= 2:
+        if norm_a in norm_b or norm_b in norm_a:
+            return 0.5
+
+    return 0.0
+
+
+# ---------------------------------------------------------------------------
+# Vector Similarity Layer
+# ---------------------------------------------------------------------------
+
+
+def cosine_similarity(a: list[float], b: list[float]) -> float:
+    """计算两个向量的余弦相似度。"""
+    dot = sum(x * y for x, y in zip(a, b))
+    norm_a = sum(x * x for x in a) ** 0.5
+    norm_b = sum(x * x for x in b) ** 0.5
+    if norm_a == 0.0 or norm_b == 0.0:
+        return 0.0
+    return dot / (norm_a * norm_b)
+
+
+def _entity_text(node: GraphNode) -> str:
+    """构造用于 embedding 的实体文本表示。"""
+    return f"{node.type}: {node.name}"
+
+
+# ---------------------------------------------------------------------------
+# LLM Arbitration Layer
+# ---------------------------------------------------------------------------
+
+_LLM_PROMPT = (
+    "判断以下两个实体是否指向同一个现实世界的实体或概念。\n\n"
+    "实体 A:\n- 名称: {name_a}\n- 类型: {type_a}\n\n"
+    "实体 B:\n- 名称: {name_b}\n- 类型: {type_b}\n\n"
+    '请严格按以下 JSON 格式返回，不要包含任何其他内容：\n'
+    '{{"is_same": true, "confidence": 0.95, "reason": "简要理由"}}'
+)
+
+
+class LLMArbitrationResult(BaseModel):
+    """LLM 仲裁返回结构。"""
+
+    is_same: bool
+    confidence: float = Field(ge=0.0, le=1.0)
+    reason: str = ""
+
+
+# ---------------------------------------------------------------------------
+# Union-Find
+# ---------------------------------------------------------------------------
+
+
+def _make_union_find(n: int):
+    """创建 Union-Find 数据结构，返回 (parent, find, union)。"""
+    parent = list(range(n))
+
+    def find(x: int) -> int:
+        while parent[x] != x:
+            parent[x] = parent[parent[x]]
+            x = parent[x]
+        return x
+
+    def union(x: int, y: int) -> None:
+        px, py = find(x), find(y)
+        if px != py:
+            parent[px] = py
+
+    return parent, find, union
+
+
+# ---------------------------------------------------------------------------
+# Merge Result Builder
+# ---------------------------------------------------------------------------
+
+
+def _build_merged_result(
+    original: ExtractionResult,
+    parent: list[int],
+    find,
+) -> ExtractionResult:
+    """根据 Union-Find 结果构建合并后的 ExtractionResult。"""
+    nodes = original.nodes
+
+    # Group by root
+    groups: dict[int, list[int]] = {}
+    for i in range(len(nodes)):
+        root = find(i)
+        groups.setdefault(root, []).append(i)
+
+    # 无合并发生时直接返回原结果
+    if len(groups) == len(nodes):
+        return original
+
+    # Canonical: 选择每组中名称最长的节点
+    # 使用 (name, type) 作为 key 避免同名跨类型节点误映射
+    node_map: dict[tuple[str, str], str] = {}
+    merged_nodes: list[GraphNode] = []
+    for members in groups.values():
+        best_idx = max(members, key=lambda idx: len(nodes[idx].name))
+        canon = nodes[best_idx]
+        merged_nodes.append(canon)
+        for idx in members:
+            node_map[(nodes[idx].name, nodes[idx].type)] = canon.name
+
+    logger.info(
+        "Alignment merged %d nodes -> %d nodes",
+        len(nodes),
+        len(merged_nodes),
+    )
+
+    # 为 edges 构建仅名称的映射（仅当同名节点映射结果无歧义时才包含）
+    _edge_remap: dict[str, set[str]] = {}
+    for (name, _type), canon_name in node_map.items():
+        _edge_remap.setdefault(name, set()).add(canon_name)
+    edge_name_map: dict[str, str] = {
+        name: next(iter(canon_names))
+        for name, canon_names in _edge_remap.items()
+        if len(canon_names) == 1
+    }
+
+    # 更新 edges（重命名 + 去重）
+    seen_edges: set[str] = set()
+    merged_edges: list[GraphEdge] = []
+    for edge in original.edges:
+        src = edge_name_map.get(edge.source, edge.source)
+        tgt = edge_name_map.get(edge.target, edge.target)
+        key = f"{src}|{edge.relation_type}|{tgt}"
+        if key not in seen_edges:
+            seen_edges.add(key)
+            merged_edges.append(
+                GraphEdge(
+                    source=src,
+                    target=tgt,
+                    relation_type=edge.relation_type,
+                    properties=edge.properties,
+                )
+            )
+
+    # 更新 triples（使用 (name, type) 精确查找，避免跨类型误映射）
+    seen_triples: set[str] = set()
+    merged_triples: list[Triple] = []
+    for triple in original.triples:
+        sub_key = (triple.subject.name, triple.subject.type)
+        obj_key = (triple.object.name, triple.object.type)
+        sub_name = node_map.get(sub_key, triple.subject.name)
+        obj_name = node_map.get(obj_key, triple.object.name)
+        key = f"{sub_name}|{triple.predicate}|{obj_name}"
+        if key not in seen_triples:
+            seen_triples.add(key)
+            merged_triples.append(
+                Triple(
+                    subject=GraphNode(name=sub_name, type=triple.subject.type),
+                    predicate=triple.predicate,
+                    object=GraphNode(name=obj_name, type=triple.object.type),
+                )
+            )
+
+    return ExtractionResult(
+        nodes=merged_nodes,
+        edges=merged_edges,
+        triples=merged_triples,
+        raw_text=original.raw_text,
+        source_id=original.source_id,
+    )
+
+
+# ---------------------------------------------------------------------------
+# EntityAligner
+# ---------------------------------------------------------------------------
+
+
+class EntityAligner:
+    """实体对齐器。
+
+    通过 ``from_settings()`` 工厂方法从全局配置创建实例，
+    也可直接构造以覆盖默认参数。
+    """
+
+    def __init__(
+        self,
+        *,
+        enabled: bool = False,
+        embedding_model: str = "text-embedding-3-small",
+        embedding_base_url: str | None = None,
+        embedding_api_key: SecretStr = SecretStr("EMPTY"),
+        llm_model: str = "gpt-4o-mini",
+        llm_base_url: str | None = None,
+        llm_api_key: SecretStr = SecretStr("EMPTY"),
+        llm_timeout: int = 30,
+        vector_auto_merge_threshold: float = 0.92,
+        vector_llm_threshold: float = 0.78,
+        llm_arbitration_enabled: bool = True,
+        max_llm_arbitrations: int = 10,
+    ) -> None:
+        self._enabled = enabled
+        self._embedding_model = embedding_model
+        self._embedding_base_url = embedding_base_url
+        self._embedding_api_key = embedding_api_key
+        self._llm_model = llm_model
+        self._llm_base_url = llm_base_url
+        self._llm_api_key = llm_api_key
+        self._llm_timeout = llm_timeout
+        self._vector_auto_threshold = vector_auto_merge_threshold
+        self._vector_llm_threshold = vector_llm_threshold
+        self._llm_arbitration_enabled = llm_arbitration_enabled
+        self._max_llm_arbitrations = max_llm_arbitrations
+        # Lazy init
+        self._embeddings: OpenAIEmbeddings | None = None
+        self._llm: ChatOpenAI | None = None
+
+    @classmethod
+    def from_settings(cls) -> EntityAligner:
+        """从全局 Settings 创建对齐器实例。"""
+        from app.core.config import settings
+
+        return cls(
+            enabled=settings.kg_alignment_enabled,
+            embedding_model=settings.kg_alignment_embedding_model,
+            embedding_base_url=settings.kg_llm_base_url,
+            embedding_api_key=settings.kg_llm_api_key,
+            llm_model=settings.kg_llm_model,
+            llm_base_url=settings.kg_llm_base_url,
+            llm_api_key=settings.kg_llm_api_key,
+            llm_timeout=settings.kg_llm_timeout_seconds,
+            vector_auto_merge_threshold=settings.kg_alignment_vector_threshold,
+            vector_llm_threshold=settings.kg_alignment_llm_threshold,
+        )
+
+    def _get_embeddings(self) -> OpenAIEmbeddings:
+        if self._embeddings is None:
+            self._embeddings = OpenAIEmbeddings(
+                model=self._embedding_model,
+                base_url=self._embedding_base_url,
+                api_key=self._embedding_api_key,
+            )
+        return self._embeddings
+
+    def _get_llm(self) -> ChatOpenAI:
+        if self._llm is None:
+            self._llm = ChatOpenAI(
+                model=self._llm_model,
+                base_url=self._llm_base_url,
+                api_key=self._llm_api_key,
+                temperature=0.0,
+                timeout=self._llm_timeout,
+            )
+        return self._llm
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def align(self, result: ExtractionResult) -> ExtractionResult:
+        """对抽取结果中的实体进行对齐去重（异步，三层策略）。
+
+        Fail-open：对齐失败时返回原始结果，不阻断请求。
+
+        注意：当前仅支持批内对齐（单次抽取结果内部的 pairwise 合并）。
+        库内对齐（对现有图谱实体召回/匹配）需要 KG 服务 API 支持，待后续实现。
+        """
+        if not self._enabled or len(result.nodes) <= 1:
+            return result
+
+        try:
+            return await self._align_impl(result)
+        except Exception:
+            logger.exception(
+                "Entity alignment failed, returning original result (fail-open)"
+            )
+            return result
+
+    def align_rules_only(self, result: ExtractionResult) -> ExtractionResult:
+        """仅使用规则层对齐（同步，用于 extract_sync 路径）。
+
+        Fail-open：对齐失败时返回原始结果。
+        """
+        if not self._enabled or len(result.nodes) <= 1:
+            return result
+
+        try:
+            nodes = result.nodes
+            parent, find, union = _make_union_find(len(nodes))
+
+            for i in range(len(nodes)):
+                for j in range(i + 1, len(nodes)):
+                    if find(i) == find(j):
+                        continue
+                    if rule_score(nodes[i], nodes[j]) >= 1.0:
+                        union(i, j)
+
+            return _build_merged_result(result, parent, find)
+        except Exception:
+            logger.exception(
+                "Rule-only alignment failed, returning original result (fail-open)"
+            )
+            return result
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    async def _align_impl(self, result: ExtractionResult) -> ExtractionResult:
+        """三层对齐的核心实现。
+
+        当前仅在单次抽取结果的节点列表内做 pairwise 对齐。
+        若需与已有图谱实体匹配（库内对齐），需扩展入参以支持
+        graph_id + 候选实体检索上下文，依赖 KG 服务 API。
+        """
+        nodes = result.nodes
+        n = len(nodes)
+        parent, find, union = _make_union_find(n)
+
+        # Phase 1: Rule layer
+        vector_candidates: list[tuple[int, int]] = []
+        for i in range(n):
+            for j in range(i + 1, n):
+                if find(i) == find(j):
+                    continue
+                score = rule_score(nodes[i], nodes[j])
+                if score >= 1.0:
+                    union(i, j)
+                    logger.debug(
+                        "Rule merge: '%s' <-> '%s'", nodes[i].name, nodes[j].name
+                    )
+                elif score > 0:
+                    vector_candidates.append((i, j))
+
+        # Phase 2: Vector similarity
+        llm_candidates: list[tuple[int, int, float]] = []
+        if vector_candidates:
+            try:
+                emb_map = await self._embed_candidates(nodes, vector_candidates)
+                for i, j in vector_candidates:
+                    if find(i) == find(j):
+                        continue
+                    sim = cosine_similarity(emb_map[i], emb_map[j])
+                    if sim >= self._vector_auto_threshold:
+                        union(i, j)
+                        logger.debug(
+                            "Vector merge: '%s' <-> '%s' (sim=%.3f)",
+                            nodes[i].name,
+                            nodes[j].name,
+                            sim,
+                        )
+                    elif sim >= self._vector_llm_threshold:
+                        llm_candidates.append((i, j, sim))
+            except Exception:
+                logger.warning(
+                    "Vector similarity failed, skipping vector layer", exc_info=True
+                )
+
+        # Phase 3: LLM arbitration (boundary cases only)
+        if llm_candidates and self._llm_arbitration_enabled:
+            llm_count = 0
+            for i, j, sim in llm_candidates:
+                if llm_count >= self._max_llm_arbitrations or find(i) == find(j):
+                    continue
+                try:
+                    if await self._llm_arbitrate(nodes[i], nodes[j]):
+                        union(i, j)
+                        logger.debug(
+                            "LLM merge: '%s' <-> '%s' (sim=%.3f)",
+                            nodes[i].name,
+                            nodes[j].name,
+                            sim,
+                        )
+                except Exception:
+                    logger.warning(
+                        "LLM arbitration failed for '%s' <-> '%s'",
+                        nodes[i].name,
+                        nodes[j].name,
+                    )
+                finally:
+                    llm_count += 1
+
+        return _build_merged_result(result, parent, find)
+
+    async def _embed_candidates(
+        self, nodes: list[GraphNode], candidates: list[tuple[int, int]]
+    ) -> dict[int, list[float]]:
+        """对候选实体计算 embedding，返回 {index: embedding}。"""
+        unique_indices: set[int] = set()
+        for i, j in candidates:
+            unique_indices.add(i)
+            unique_indices.add(j)
+
+        idx_list = sorted(unique_indices)
+        texts = [_entity_text(nodes[i]) for i in idx_list]
+        embeddings = await self._get_embeddings().aembed_documents(texts)
+        return dict(zip(idx_list, embeddings))
+
+    async def _llm_arbitrate(self, a: GraphNode, b: GraphNode) -> bool:
+        """LLM 仲裁两个实体是否相同，严格 JSON schema 校验。"""
+        prompt = _LLM_PROMPT.format(
+            name_a=a.name,
+            type_a=a.type,
+            name_b=b.name,
+            type_b=b.type,
+        )
+        response = await self._get_llm().ainvoke(prompt)
+        content = response.content.strip()
+
+        parsed = json.loads(content)
+        result = LLMArbitrationResult.model_validate(parsed)
+
+        logger.debug(
+            "LLM arbitration: '%s' <-> '%s' -> is_same=%s, confidence=%.2f",
+            a.name,
+            b.name,
+            result.is_same,
+            result.confidence,
+        )
+        return result.is_same and result.confidence >= 0.7

runtime/datamate-python/app/module/kg_extraction/extractor.py

@@ -15,6 +15,7 @@ from langchain_experimental.graph_transformers import LLMGraphTransformer
 from pydantic import SecretStr
 
 from app.core.logging import get_logger
+from app.module.kg_extraction.aligner import EntityAligner
 from app.module.kg_extraction.models import (
     ExtractionRequest,
     ExtractionResult,
@@ -47,6 +48,7 @@ class KnowledgeGraphExtractor:
         temperature: float = 0.0,
         timeout: int = 60,
         max_retries: int = 2,
+        aligner: EntityAligner | None = None,
     ) -> None:
         logger.info(
             "Initializing KnowledgeGraphExtractor (model=%s, base_url=%s, timeout=%ds, max_retries=%d)",
@@ -63,6 +65,7 @@ class KnowledgeGraphExtractor:
             timeout=timeout,
             max_retries=max_retries,
         )
+        self._aligner = aligner or EntityAligner()
 
     @classmethod
     def from_settings(cls) -> KnowledgeGraphExtractor:
@@ -76,6 +79,7 @@ class KnowledgeGraphExtractor:
             temperature=settings.kg_llm_temperature,
             timeout=settings.kg_llm_timeout_seconds,
             max_retries=settings.kg_llm_max_retries,
+            aligner=EntityAligner.from_settings(),
         )
 
     def _build_transformer(
@@ -119,6 +123,7 @@ class KnowledgeGraphExtractor:
             raise
 
         result = self._convert_result(graph_documents, request)
+        result = await self._aligner.align(result)
         logger.info(
             "Extraction complete: graph_id=%s, nodes=%d, edges=%d, triples=%d",
             request.graph_id,
@@ -154,6 +159,7 @@ class KnowledgeGraphExtractor:
             raise
 
         result = self._convert_result(graph_documents, request)
+        result = self._aligner.align_rules_only(result)
         logger.info(
             "Sync extraction complete: graph_id=%s, nodes=%d, edges=%d",
             request.graph_id,

runtime/datamate-python/app/module/kg_extraction/test_aligner.py

@@ -0,0 +1,477 @@
+"""实体对齐器测试。
+
+Run with: pytest app/module/kg_extraction/test_aligner.py -v
+"""
+
+from __future__ import annotations
+
+import asyncio
+from unittest.mock import AsyncMock, patch
+
+import pytest
+
+from app.module.kg_extraction.aligner import (
+    EntityAligner,
+    LLMArbitrationResult,
+    _build_merged_result,
+    _make_union_find,
+    cosine_similarity,
+    normalize_name,
+    rule_score,
+)
+from app.module.kg_extraction.models import (
+    ExtractionResult,
+    GraphEdge,
+    GraphNode,
+    Triple,
+)
+
+
+# ---------------------------------------------------------------------------
+# normalize_name
+# ---------------------------------------------------------------------------
+
+
+class TestNormalizeName:
+    def test_basic_lowercase(self):
+        assert normalize_name("Hello World") == "hello world"
+
+    def test_unicode_nfkc(self):
+        assert normalize_name("\uff28ello") == "hello"
+
+    def test_punctuation_removed(self):
+        assert normalize_name("U.S.A.") == "usa"
+
+    def test_whitespace_collapsed(self):
+        assert normalize_name("  hello   world  ") == "hello world"
+
+    def test_empty_string(self):
+        assert normalize_name("") == ""
+
+    def test_chinese_preserved(self):
+        assert normalize_name("\u5f20\u4e09") == "\u5f20\u4e09"
+
+    def test_mixed_chinese_english(self):
+        assert normalize_name("\u5f20\u4e09 (Zhang San)") == "\u5f20\u4e09 zhang san"
+
+
+# ---------------------------------------------------------------------------
+# rule_score
+# ---------------------------------------------------------------------------
+
+
+class TestRuleScore:
+    def test_exact_match(self):
+        a = GraphNode(name="\u5f20\u4e09", type="Person")
+        b = GraphNode(name="\u5f20\u4e09", type="Person")
+        assert rule_score(a, b) == 1.0
+
+    def test_normalized_match(self):
+        a = GraphNode(name="Hello World", type="Organization")
+        b = GraphNode(name="hello world", type="Organization")
+        assert rule_score(a, b) == 1.0
+
+    def test_type_mismatch(self):
+        a = GraphNode(name="\u5f20\u4e09", type="Person")
+        b = GraphNode(name="\u5f20\u4e09", type="Organization")
+        assert rule_score(a, b) == 0.0
+
+    def test_substring_match(self):
+        a = GraphNode(name="\u5317\u4eac\u5927\u5b66", type="Organization")
+        b = GraphNode(name="\u5317\u4eac\u5927\u5b66\u8ba1\u7b97\u673a\u5b66\u9662", type="Organization")
+        assert rule_score(a, b) == 0.5
+
+    def test_no_match(self):
+        a = GraphNode(name="\u5f20\u4e09", type="Person")
+        b = GraphNode(name="\u674e\u56db", type="Person")
+        assert rule_score(a, b) == 0.0
+
+    def test_type_case_insensitive(self):
+        a = GraphNode(name="test", type="PERSON")
+        b = GraphNode(name="test", type="person")
+        assert rule_score(a, b) == 1.0
+
+    def test_short_substring_ignored(self):
+        """Single-character substring should not trigger match."""
+        a = GraphNode(name="A", type="Person")
+        b = GraphNode(name="AB", type="Person")
+        assert rule_score(a, b) == 0.0
+
+
+# ---------------------------------------------------------------------------
+# cosine_similarity
+# ---------------------------------------------------------------------------
+
+
+class TestCosineSimilarity:
+    def test_identical(self):
+        assert cosine_similarity([1.0, 0.0], [1.0, 0.0]) == pytest.approx(1.0)
+
+    def test_orthogonal(self):
+        assert cosine_similarity([1.0, 0.0], [0.0, 1.0]) == pytest.approx(0.0)
+
+    def test_opposite(self):
+        assert cosine_similarity([1.0, 0.0], [-1.0, 0.0]) == pytest.approx(-1.0)
+
+    def test_zero_vector(self):
+        assert cosine_similarity([0.0, 0.0], [1.0, 0.0]) == 0.0
+
+
+# ---------------------------------------------------------------------------
+# Union-Find
+# ---------------------------------------------------------------------------
+
+
+class TestUnionFind:
+    def test_basic(self):
+        parent, find, union = _make_union_find(4)
+        union(0, 1)
+        union(2, 3)
+        assert find(0) == find(1)
+        assert find(2) == find(3)
+        assert find(0) != find(2)
+
+    def test_transitive(self):
+        parent, find, union = _make_union_find(3)
+        union(0, 1)
+        union(1, 2)
+        assert find(0) == find(2)
+
+
+# ---------------------------------------------------------------------------
+# _build_merged_result
+# ---------------------------------------------------------------------------
+
+
+def _make_result(nodes, edges=None, triples=None):
+    return ExtractionResult(
+        nodes=nodes,
+        edges=edges or [],
+        triples=triples or [],
+        raw_text="test text",
+        source_id="src-1",
+    )
+
+
+class TestBuildMergedResult:
+    def test_no_merge_returns_original(self):
+        nodes = [
+            GraphNode(name="A", type="Person"),
+            GraphNode(name="B", type="Person"),
+        ]
+        result = _make_result(nodes)
+        parent, find, _ = _make_union_find(2)
+        merged = _build_merged_result(result, parent, find)
+        assert merged is result
+
+    def test_canonical_picks_longest_name(self):
+        nodes = [
+            GraphNode(name="AI", type="Tech"),
+            GraphNode(name="Artificial Intelligence", type="Tech"),
+        ]
+        result = _make_result(nodes)
+        parent, find, union = _make_union_find(2)
+        union(0, 1)
+        merged = _build_merged_result(result, parent, find)
+        assert len(merged.nodes) == 1
+        assert merged.nodes[0].name == "Artificial Intelligence"
+
+    def test_edge_remap_and_dedup(self):
+        nodes = [
+            GraphNode(name="Alice", type="Person"),
+            GraphNode(name="alice", type="Person"),
+            GraphNode(name="Bob", type="Person"),
+        ]
+        edges = [
+            GraphEdge(source="Alice", target="Bob", relation_type="knows"),
+            GraphEdge(source="alice", target="Bob", relation_type="knows"),
+        ]
+        result = _make_result(nodes, edges)
+        parent, find, union = _make_union_find(3)
+        union(0, 1)
+        merged = _build_merged_result(result, parent, find)
+        assert len(merged.edges) == 1
+        assert merged.edges[0].source == "Alice"
+
+    def test_triple_remap_and_dedup(self):
+        n1 = GraphNode(name="Alice", type="Person")
+        n2 = GraphNode(name="alice", type="Person")
+        n3 = GraphNode(name="MIT", type="Organization")
+        triples = [
+            Triple(subject=n1, predicate="works_at", object=n3),
+            Triple(subject=n2, predicate="works_at", object=n3),
+        ]
+        result = _make_result([n1, n2, n3], triples=triples)
+        parent, find, union = _make_union_find(3)
+        union(0, 1)
+        merged = _build_merged_result(result, parent, find)
+        assert len(merged.triples) == 1
+        assert merged.triples[0].subject.name == "Alice"
+
+    def test_preserves_metadata(self):
+        nodes = [
+            GraphNode(name="A", type="Person"),
+            GraphNode(name="A", type="Person"),
+        ]
+        result = _make_result(nodes)
+        parent, find, union = _make_union_find(2)
+        union(0, 1)
+        merged = _build_merged_result(result, parent, find)
+        assert merged.raw_text == "test text"
+        assert merged.source_id == "src-1"
+
+    def test_cross_type_same_name_no_collision(self):
+        """P1-1 回归：同名跨类型节点合并不应误映射其他类型的边和三元组。
+
+        场景：Person "张三" 和 "张三先生" 合并为 "张三先生"，
+        但 Organization "张三" 不应被重写。
+        """
+        nodes = [
+            GraphNode(name="张三", type="Person"),       # idx 0
+            GraphNode(name="张三先生", type="Person"),    # idx 1
+            GraphNode(name="张三", type="Organization"),  # idx 2 - 同名不同类型
+            GraphNode(name="北京", type="Location"),      # idx 3
+        ]
+        edges = [
+            GraphEdge(source="张三", target="北京", relation_type="lives_in"),
+            GraphEdge(source="张三", target="北京", relation_type="located_in"),
+        ]
+        triples = [
+            Triple(
+                subject=GraphNode(name="张三", type="Person"),
+                predicate="lives_in",
+                object=GraphNode(name="北京", type="Location"),
+            ),
+            Triple(
+                subject=GraphNode(name="张三", type="Organization"),
+                predicate="located_in",
+                object=GraphNode(name="北京", type="Location"),
+            ),
+        ]
+        result = _make_result(nodes, edges, triples)
+        parent, find, union = _make_union_find(4)
+        union(0, 1)  # 合并 Person "张三" 和 "张三先生"
+        merged = _build_merged_result(result, parent, find)
+
+        # 应有 3 个节点：张三先生(Person), 张三(Org), 北京(Location)
+        assert len(merged.nodes) == 3
+        merged_names = {(n.name, n.type) for n in merged.nodes}
+        assert ("张三先生", "Person") in merged_names
+        assert ("张三", "Organization") in merged_names
+        assert ("北京", "Location") in merged_names
+
+        # edges 中 "张三" 有歧义（映射到不同 canonical），应保持原名不重写
+        assert len(merged.edges) == 2
+
+        # triples 有类型信息，可精确区分
+        assert len(merged.triples) == 2
+        person_triple = [t for t in merged.triples if t.subject.type == "Person"][0]
+        org_triple = [t for t in merged.triples if t.subject.type == "Organization"][0]
+        assert person_triple.subject.name == "张三先生"  # Person 被重写
+        assert org_triple.subject.name == "张三"  # Organization 保持原名
+
+
+# ---------------------------------------------------------------------------
+# EntityAligner
+# ---------------------------------------------------------------------------
+
+
+class TestEntityAligner:
+    def _run(self, coro):
+        """Helper to run async coroutine in sync test."""
+        loop = asyncio.new_event_loop()
+        try:
+            return loop.run_until_complete(coro)
+        finally:
+            loop.close()
+
+    def test_disabled_returns_original(self):
+        aligner = EntityAligner(enabled=False)
+        result = _make_result([GraphNode(name="A", type="Person")])
+        aligned = self._run(aligner.align(result))
+        assert aligned is result
+
+    def test_single_node_returns_original(self):
+        aligner = EntityAligner(enabled=True)
+        result = _make_result([GraphNode(name="A", type="Person")])
+        aligned = self._run(aligner.align(result))
+        assert aligned is result
+
+    def test_rule_merge_exact_names(self):
+        aligner = EntityAligner(enabled=True)
+        nodes = [
+            GraphNode(name="\u5f20\u4e09", type="Person"),
+            GraphNode(name="\u5f20\u4e09", type="Person"),
+            GraphNode(name="\u674e\u56db", type="Person"),
+        ]
+        edges = [
+            GraphEdge(source="\u5f20\u4e09", target="\u674e\u56db", relation_type="knows"),
+        ]
+        result = _make_result(nodes, edges)
+        aligned = self._run(aligner.align(result))
+        assert len(aligned.nodes) == 2
+        names = {n.name for n in aligned.nodes}
+        assert "\u5f20\u4e09" in names
+        assert "\u674e\u56db" in names
+
+    def test_rule_merge_case_insensitive(self):
+        aligner = EntityAligner(enabled=True)
+        nodes = [
+            GraphNode(name="Hello World", type="Org"),
+            GraphNode(name="hello world", type="Org"),
+            GraphNode(name="Test", type="Person"),
+        ]
+        result = _make_result(nodes)
+        aligned = self._run(aligner.align(result))
+        assert len(aligned.nodes) == 2
+
+    def test_rule_merge_deduplicates_edges(self):
+        aligner = EntityAligner(enabled=True)
+        nodes = [
+            GraphNode(name="Hello World", type="Org"),
+            GraphNode(name="hello world", type="Org"),
+            GraphNode(name="Test", type="Person"),
+        ]
+        edges = [
+            GraphEdge(source="Hello World", target="Test", relation_type="employs"),
+            GraphEdge(source="hello world", target="Test", relation_type="employs"),
+        ]
+        result = _make_result(nodes, edges)
+        aligned = self._run(aligner.align(result))
+        assert len(aligned.edges) == 1
+
+    def test_rule_merge_deduplicates_triples(self):
+        aligner = EntityAligner(enabled=True)
+        n1 = GraphNode(name="\u5f20\u4e09", type="Person")
+        n2 = GraphNode(name="\u5f20\u4e09", type="Person")
+        n3 = GraphNode(name="\u5317\u4eac\u5927\u5b66", type="Organization")
+        triples = [
+            Triple(subject=n1, predicate="works_at", object=n3),
+            Triple(subject=n2, predicate="works_at", object=n3),
+        ]
+        result = _make_result([n1, n2, n3], triples=triples)
+        aligned = self._run(aligner.align(result))
+        assert len(aligned.triples) == 1
+
+    def test_type_mismatch_no_merge(self):
+        aligner = EntityAligner(enabled=True)
+        nodes = [
+            GraphNode(name="\u5f20\u4e09", type="Person"),
+            GraphNode(name="\u5f20\u4e09", type="Organization"),
+        ]
+        result = _make_result(nodes)
+        aligned = self._run(aligner.align(result))
+        assert len(aligned.nodes) == 2
+
+    def test_fail_open_on_error(self):
+        aligner = EntityAligner(enabled=True)
+        nodes = [
+            GraphNode(name="\u5f20\u4e09", type="Person"),
+            GraphNode(name="\u5f20\u4e09", type="Person"),
+        ]
+        result = _make_result(nodes)
+        with patch.object(aligner, "_align_impl", side_effect=RuntimeError("boom")):
+            aligned = self._run(aligner.align(result))
+        assert aligned is result
+
+    def test_align_rules_only_sync(self):
+        aligner = EntityAligner(enabled=True)
+        nodes = [
+            GraphNode(name="\u5f20\u4e09", type="Person"),
+            GraphNode(name="\u5f20\u4e09", type="Person"),
+            GraphNode(name="\u674e\u56db", type="Person"),
+        ]
+        result = _make_result(nodes)
+        aligned = aligner.align_rules_only(result)
+        assert len(aligned.nodes) == 2
+
+    def test_align_rules_only_disabled(self):
+        aligner = EntityAligner(enabled=False)
+        result = _make_result([GraphNode(name="A", type="Person")])
+        aligned = aligner.align_rules_only(result)
+        assert aligned is result
+
+    def test_align_rules_only_fail_open(self):
+        aligner = EntityAligner(enabled=True)
+        nodes = [
+            GraphNode(name="A", type="Person"),
+            GraphNode(name="B", type="Person"),
+        ]
+        result = _make_result(nodes)
+        with patch(
+            "app.module.kg_extraction.aligner.rule_score", side_effect=RuntimeError("boom")
+        ):
+            aligned = aligner.align_rules_only(result)
+        assert aligned is result
+
+    def test_llm_count_incremented_on_failure(self):
+        """P1-2 回归：LLM 仲裁失败也应计入 max_llm_arbitrations 预算。"""
+        max_arb = 2
+        aligner = EntityAligner(
+            enabled=True,
+            max_llm_arbitrations=max_arb,
+            llm_arbitration_enabled=True,
+        )
+        # 构建 4 个同类型节点，规则层子串匹配产生多个 vector 候选
+        nodes = [
+            GraphNode(name="北京大学", type="Organization"),
+            GraphNode(name="北京大学计算机学院", type="Organization"),
+            GraphNode(name="北京大学数学学院", type="Organization"),
+            GraphNode(name="北京大学物理学院", type="Organization"),
+        ]
+        result = _make_result(nodes)
+
+        # Mock embedding 使所有候选都落入 LLM 仲裁区间
+        fake_embedding = [1.0, 0.0, 0.0]
+        # 微调使 cosine 在 llm_threshold 和 auto_threshold 之间
+        import math
+
+        # cos(θ) = 0.85 → 在默认 [0.78, 0.92) 区间
+        angle = math.acos(0.85)
+        emb_a = [1.0, 0.0]
+        emb_b = [math.cos(angle), math.sin(angle)]
+
+        async def fake_embed(texts):
+            # 偶数索引返回 emb_a，奇数返回 emb_b
+            return [emb_a if i % 2 == 0 else emb_b for i in range(len(texts))]
+
+        mock_llm_arbitrate = AsyncMock(side_effect=RuntimeError("LLM down"))
+
+        with patch.object(aligner, "_get_embeddings") as mock_emb:
+            mock_emb_instance = AsyncMock()
+            mock_emb_instance.aembed_documents = fake_embed
+            mock_emb.return_value = mock_emb_instance
+            with patch.object(aligner, "_llm_arbitrate", mock_llm_arbitrate):
+                aligned = self._run(aligner.align(result))
+
+        # LLM 应恰好被调用 max_arb 次（不会因异常不计数而超出预算）
+        assert mock_llm_arbitrate.call_count <= max_arb
+
+
+# ---------------------------------------------------------------------------
+# LLMArbitrationResult
+# ---------------------------------------------------------------------------
+
+
+class TestLLMArbitrationResult:
+    def test_valid_parse(self):
+        data = {"is_same": True, "confidence": 0.95, "reason": "Same entity"}
+        result = LLMArbitrationResult.model_validate(data)
+        assert result.is_same is True
+        assert result.confidence == 0.95
+
+    def test_confidence_bounds(self):
+        with pytest.raises(Exception):
+            LLMArbitrationResult.model_validate(
+                {"is_same": True, "confidence": 1.5, "reason": ""}
+            )
+
+    def test_missing_reason_defaults(self):
+        result = LLMArbitrationResult.model_validate(
+            {"is_same": False, "confidence": 0.1}
+        )
+        assert result.reason == ""
+
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])