feat: smarter fallback — heuristic sufficiency + result merging (v3.1)

Previously: fallback fired only on entities==0, and replaced primary results.
Now: heuristic sufficiency check, with results MERGED (not replaced).

Sufficiency criterion (NERService._expected_min)
expected_min = max(length_floor, label_floor)
length_floor: text<30→1, <100→2, <300→3, ≥300→4
label_floor : ⌈len(labels)/3⌉, default 1
fallback fires when len(primary_entities) < expected_min

Override
ExtractRequest.min_entities (int, ≥0): client overrides the heuristic
min_entities=0 disables fallback entirely

Merge semantics
primary results are kept verbatim
fallback results appended; deduplication keeps highest-score per (start,end)
applies to both single-language fallback and mixed-language dual-run

Tests: 38 → 48 (heuristic, override, additive merge, EN/ZH symmetric paths)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

app/main.py

@@ -48,11 +48,12 @@ def health():
 @app.post("/api/v1/extract", response_model=ExtractResponse, tags=["NER"])
 def extract(req: ExtractRequest):
     logger.info(
-        "extract request | text_len=%d labels=%s threshold=%s language=%s",
+        "extract request | text_len=%d labels=%s threshold=%s language=%s min_entities=%s",
         len(req.text),
         req.labels or "(default)",
         req.threshold,
         req.language,
+        req.min_entities,
     )
     t0 = time.perf_counter()
     entities, labels_used = ner_service.extract(
@@ -60,6 +61,7 @@ def extract(req: ExtractRequest):
         req.labels,
         req.threshold,
         language=req.language,
+        min_entities=req.min_entities,
     )
     elapsed_ms = (time.perf_counter() - t0) * 1000
 

app/models.py

@@ -35,6 +35,17 @@ class ExtractRequest(BaseModel):
         ),
     )
 
+    min_entities: int | None = Field(
+        default=None,
+        ge=0,
+        description=(
+            "Minimum entity count for the primary model to be considered 'sufficient'. "
+            "If the primary returns fewer than this, the fallback model is invoked and "
+            "its results are MERGED with the primary's (not replaced). "
+            "Leave null/omit to auto-calculate from text length and label count."
+        ),
+    )
+
 
 class Entity(BaseModel):
     text: str

app/ner.py

@@ -1,19 +1,31 @@
 """
-NER 服务层 — 双模型路由 + 兜底策略
+NER 服务层 — 双模型路由 + 兜底合并
 ──────────────────────────────────────────────────────────────────────────────
 语言检测（两层）：
   1. Unicode 脚本比例：快速，适合中文 / 阿拉伯文等脚本明显的语言
   2. langdetect 库兜底：覆盖纯英文及边界文本
 
-路由 & 兜底规则：
-  ┌──────────┬──────────────────┬──────────────────────────────┐
-  │ language │ 主模型           │ 兜底条件                     │
-  ├──────────┼──────────────────┼──────────────────────────────┤
-  │ zh       │ ChineseBERT      │ 实体数=0 → 补充 GLiNER 结果  │
-  │ en / ar  │ GLiNER           │ 实体数=0 → 补充 BERT 结果    │
-  │ mixed    │ GLiNER + BERT    │ 同时运行两个模型，结果合并   │
-  │ auto     │ 先检测语言再路由 │                              │
-  └──────────┴──────────────────┴──────────────────────────────┘
+充分性判定（替代粗暴的 ==0）：
+  expected_min = max( length_floor, label_floor )
+    length_floor: text<30→1, <100→2, <300→3, ≥300→4
+    label_floor : ⌈len(labels)/3⌉，无 labels 时为 1
+  主模型实体数 < expected_min  → 触发兜底
+  调用方可在请求里直接传 min_entities 覆盖启发式
+
+兜底合并（关键：相加而非替换）：
+  1. 主模型先跑一遍，结果保留
+  2. 若不充分，兜底模型再跑一遍
+  3. 两份结果合并 → 按 (start, end) 去重，同一 span 保留得分最高的
+
+路由：
+  ┌──────────┬──────────────────────────┐
+  │ language │ 主模型 → 兜底模型        │
+  ├──────────┼──────────────────────────┤
+  │ zh       │ BERT-Chinese → GLiNER    │
+  │ en / ar  │ GLiNER → BERT-Chinese    │
+  │ mixed    │ 两个模型同时运行后合并   │
+  │ auto     │ 先检测语言再路由         │
+  └──────────┴──────────────────────────┘
 """
 
 import threading
@@ -254,18 +266,38 @@ class NERService:
                     self._zh_backend = ChineseBERTBackend(self._zh_name, self._cache_dir)
         return self._zh_backend
 
+    # ── 充分性判定 ────────────────────────────────────────────────────────────
+
+    @staticmethod
+    def _expected_min(text: str, labels: list[str]) -> int:
+        """
+        启发式：根据文本长度和标签数计算最小期望实体数。
+        取 length_floor 与 label_floor 中的较大值。
+        """
+        n = len(text)
+        if   n < 30:   length_floor = 1
+        elif n < 100:  length_floor = 2
+        elif n < 300:  length_floor = 3
+        else:          length_floor = 4
+
+        label_floor = max(1, (len(labels) + 2) // 3) if labels else 1
+        return max(length_floor, label_floor)
+
     # ── 兜底合并 ──────────────────────────────────────────────────────────────
 
+    @staticmethod
     def _merge(
-        self,
         primary: tuple[list[Entity], list[str]],
         fallback: tuple[list[Entity], list[str]],
     ) -> tuple[list[Entity], list[str]]:
-        """合并两个模型的结果，去重后按位置排序。"""
+        """
+        相加合并：保留主模型所有结果，再加上兜底模型的结果，
+        按 (start, end) 去重（同一 span 保留得分最高），按位置排序。
+        """
         p_ents, p_labels = primary
         f_ents, f_labels = fallback
         merged = _deduplicate(p_ents + f_ents)
-        used = list(dict.fromkeys(p_labels + f_labels))  # 保序去重
+        used = list(dict.fromkeys(p_labels + f_labels))   # 保序去重
         return merged, used
 
     # ── 主入口 ────────────────────────────────────────────────────────────────
@@ -276,42 +308,52 @@ class NERService:
         labels: list[str],
         threshold: float,
         language: str = "auto",
+        min_entities: int | None = None,
     ) -> tuple[list[Entity], list[str]]:
         """
         返回 (entities, labels_used)。
 
-        路由逻辑：
+        路由：
           auto  → 检测语言 → 路由
-          zh    → BERT 主，GLiNER 兜底（主模型无结果时补充）
-          en/ar → GLiNER 主，BERT 兜底（主模型无结果时补充）
-          mixed → 两模型同时运行，结果合并去重
+          zh    → BERT 主，GLiNER 兜底
+          en/ar → GLiNER 主，BERT 兜底
+          mixed → 两模型同时运行 → 合并
+
+        兜底触发条件（zh / en / ar）：
+          主模型实体数 < expected_min（默认启发式，可由 min_entities 覆盖）
+        触发后：主结果 + 兜底结果一并返回，按 span 去重。
         """
         if not text:
             return [], labels
 
         lang = language if language != "auto" else detect_language(text)
 
+        # mixed 永远跑双模型并合并
         if lang == "mixed":
-            # 同时运行两个模型，合并结果
-            en_result = self._en().predict(text, labels, threshold)
-            zh_result = self._zh().predict(text, labels, threshold)
-            return self._merge(en_result, zh_result)
+            return self._merge(
+                self._en().predict(text, labels, threshold),
+                self._zh().predict(text, labels, threshold),
+            )
 
+        # 单语言：选主模型 + 兜底模型
         if lang == "zh":
-            primary_result = self._zh().predict(text, labels, threshold)
-            if not primary_result[0]:       # 主模型无结果 → GLiNER 兜底
-                fallback_result = self._en().predict(text, labels, threshold)
-                if fallback_result[0]:
-                    return fallback_result
+            primary, fallback = self._zh(), self._en()
+        else:  # en / ar
+            primary, fallback = self._en(), self._zh()
+
+        primary_result = primary.predict(text, labels, threshold)
+
+        # 充分性判定
+        threshold_n = (
+            min_entities if min_entities is not None
+            else self._expected_min(text, labels)
+        )
+        if len(primary_result[0]) >= threshold_n:
             return primary_result
 
-        # en / ar / 其他
-        primary_result = self._en().predict(text, labels, threshold)
-        if not primary_result[0]:           # 主模型无结果 → BERT 兜底
-            fallback_result = self._zh().predict(text, labels, threshold)
-            if fallback_result[0]:
-                return fallback_result
-        return primary_result
+        # 不充分 → 兜底相加
+        fallback_result = fallback.predict(text, labels, threshold)
+        return self._merge(primary_result, fallback_result)
 
     def warmup(self) -> None:
         """启动时预热两个模型，首个请求无需等待。"""

tests/test_extract.py

@@ -77,7 +77,9 @@ def test_extract_threshold_forwarded(client):
     c, mock_ner = client
     c.post("/api/v1/extract",
            json={"text": "Hello", "labels": ["person"], "threshold": 0.8})
-    mock_ner.extract.assert_called_once_with("Hello", ["person"], 0.8, language="auto")
+    mock_ner.extract.assert_called_once_with(
+        "Hello", ["person"], 0.8, language="auto", min_entities=None
+    )
 
 
 def test_extract_invalid_threshold(client):
@@ -90,7 +92,25 @@ def test_extract_language_field_forwarded(client):
     c, mock_ner = client
     c.post("/api/v1/extract",
            json={"text": "北京协和医院", "labels": ["医院名称"], "language": "zh"})
-    mock_ner.extract.assert_called_once_with("北京协和医院", ["医院名称"], 0.4, language="zh")
+    mock_ner.extract.assert_called_once_with(
+        "北京协和医院", ["医院名称"], 0.4, language="zh", min_entities=None
+    )
+
+
+def test_extract_min_entities_forwarded(client):
+    c, mock_ner = client
+    c.post("/api/v1/extract",
+           json={"text": "马云在杭州。", "language": "zh", "min_entities": 5})
+    mock_ner.extract.assert_called_once_with(
+        "马云在杭州。", [], 0.4, language="zh", min_entities=5
+    )
+
+
+def test_extract_negative_min_entities_rejected(client):
+    c, _ = client
+    resp = c.post("/api/v1/extract",
+                  json={"text": "x", "min_entities": -1})
+    assert resp.status_code == 422
 
 
 def test_extract_invalid_language(client):
@@ -232,7 +252,8 @@ def test_english_threshold_forwarded(client):
                  "labels": ["company or organization name"],
                  "threshold": 0.8, "language": "en"})
     mock_ner.extract.assert_called_once_with(
-        "NASA explored the Moon.", ["company or organization name"], 0.8, language="en"
+        "NASA explored the Moon.", ["company or organization name"], 0.8,
+        language="en", min_entities=None,
     )
 
 
@@ -351,101 +372,170 @@ def test_mixed_no_cross_language_contamination(client):
 
 # ── Fallback & merge (NERService unit tests, no HTTP) ────────────────────────
 
-def test_fallback_zh_empty_uses_en():
-    """ZH 主模型返回空时，应使用 GLiNER 兜底。"""
+def _build_svc():
+    """Construct a bare NERService with mocked backends and locks."""
+    import threading
     from app.ner import NERService
-
     svc = NERService.__new__(NERService)
-    svc._en_lock = __import__("threading").Lock()
-    svc._zh_lock = __import__("threading").Lock()
-
-    # ZH backend: returns nothing
-    zh_mock = MagicMock()
-    zh_mock.predict.return_value = ([], [])
-    # EN fallback: returns one entity
-    en_mock = MagicMock()
-    en_mock.predict.return_value = _ents(
+    svc._en_lock = threading.Lock()
+    svc._zh_lock = threading.Lock()
+    svc._en_backend = MagicMock()
+    svc._zh_backend = MagicMock()
+    return svc
+
+
+# ── Sufficiency heuristic ────────────────────────────────────────────────────
+
+def test_expected_min_short_text():
+    from app.ner import NERService
+    assert NERService._expected_min("马云", []) == 1
+
+
+def test_expected_min_medium_text():
+    from app.ner import NERService
+    text = "x" * 50
+    assert NERService._expected_min(text, []) == 2
+
+
+def test_expected_min_long_text():
+    from app.ner import NERService
+    text = "x" * 350
+    assert NERService._expected_min(text, []) == 4
+
+
+def test_expected_min_label_floor_takes_over():
+    """9 个标签 → ⌈9/3⌉=3，超过短文本的 length_floor=1，最终取 3。"""
+    from app.ner import NERService
+    short_text = "马云"
+    labels = [f"l{i}" for i in range(9)]
+    assert NERService._expected_min(short_text, labels) == 3
+
+
+# ── ZH branch fallback ───────────────────────────────────────────────────────
+
+def test_zh_empty_triggers_fallback_and_adds():
+    """ZH 主模型 0 个 → 触发兜底 → 返回兜底结果。"""
+    svc = _build_svc()
+    svc._zh_backend.predict.return_value = ([], [])
+    svc._en_backend.predict.return_value = _ents(
         Entity(text="马云", label="person", score=0.75, start=0, end=2)
     )
-    svc._zh_backend = zh_mock
-    svc._en_backend = en_mock
-
     entities, _ = svc.extract("马云", [], 0.4, language="zh")
     assert any(e.text == "马云" for e in entities)
-    zh_mock.predict.assert_called_once()
-    en_mock.predict.assert_called_once()   # 兜底被调用
+    svc._zh_backend.predict.assert_called_once()
+    svc._en_backend.predict.assert_called_once()
 
 
-def test_fallback_zh_has_results_no_en_called():
-    """ZH 主模型有结果时，不应调用 GLiNER 兜底。"""
-    from app.ner import NERService
+def test_zh_sufficient_no_fallback():
+    """ZH 主模型实体数 ≥ expected_min(=1 短文本) → 不调用兜底。"""
+    svc = _build_svc()
+    svc._zh_backend.predict.return_value = _ents(
+        Entity(text="马云", label="person", score=0.92, start=0, end=2)
+    )
+    svc.extract("马云", [], 0.4, language="zh")
+    svc._en_backend.predict.assert_not_called()
 
-    svc = NERService.__new__(NERService)
-    svc._en_lock = __import__("threading").Lock()
-    svc._zh_lock = __import__("threading").Lock()
 
-    zh_mock = MagicMock()
-    zh_mock.predict.return_value = _ents(
-        Entity(text="马云", label="person", score=0.92, start=0, end=2)
+def test_zh_insufficient_triggers_fallback_and_results_added():
+    """
+    关键测试：ZH 返回 1 个，但文本长 → expected_min=4，不充分 →
+    触发兜底，主结果 + 兜底结果一并返回（相加，不替换）。
+    """
+    svc = _build_svc()
+    long_text = "马云" + "x" * 350     # length_floor = 4
+    svc._zh_backend.predict.return_value = _ents(
+        Entity(text="马云", label="人名或姓名", score=0.95, start=0, end=2),
     )
-    en_mock = MagicMock()
-    svc._zh_backend = zh_mock
-    svc._en_backend = en_mock
+    svc._en_backend.predict.return_value = _ents(
+        Entity(text="Tesla", label="organization", score=0.90, start=10, end=15),
+        Entity(text="2024",  label="date",         score=0.88, start=20, end=24),
+    )
+    entities, _ = svc.extract(long_text, [], 0.4, language="zh")
 
-    svc.extract("马云", [], 0.4, language="zh")
-    en_mock.predict.assert_not_called()   # 不应调用兜底
+    texts = {e.text for e in entities}
+    # 主模型的"马云"必须保留，同时兜底的 Tesla / 2024 也加进来
+    assert "马云"  in texts
+    assert "Tesla" in texts
+    assert "2024"  in texts
+    assert len(entities) == 3      # 1 + 2 = 3，确实是相加
+
+
+def test_user_min_entities_overrides_heuristic():
+    """请求里传 min_entities=5 时应覆盖启发式，主模型 3 个仍触发兜底。"""
+    svc = _build_svc()
+    svc._zh_backend.predict.return_value = _ents(
+        Entity(text="马云", label="person", score=0.95, start=0, end=2),
+        Entity(text="张勇", label="person", score=0.93, start=4, end=6),
+        Entity(text="杭州", label="location", score=0.91, start=8, end=10),
+    )
+    svc._en_backend.predict.return_value = _ents(
+        Entity(text="Tesla", label="organization", score=0.85, start=15, end=20),
+    )
+    entities, _ = svc.extract("马云、张勇、杭州 Tesla", [], 0.4,
+                              language="zh", min_entities=5)
 
+    # 3 < 5 → 触发兜底；最终 3 + 1 = 4
+    assert len(entities) == 4
+    svc._en_backend.predict.assert_called_once()
 
-def test_mixed_runs_both_models_and_merges():
-    """Mixed 语言应同时运行两个模型并合并结果。"""
-    from app.ner import NERService
 
-    svc = NERService.__new__(NERService)
-    svc._en_lock = __import__("threading").Lock()
-    svc._zh_lock = __import__("threading").Lock()
+def test_user_min_entities_zero_disables_fallback():
+    """min_entities=0 时主模型即使返回空也不触发兜底。"""
+    svc = _build_svc()
+    svc._zh_backend.predict.return_value = ([], [])
+    svc.extract("马云", [], 0.4, language="zh", min_entities=0)
+    svc._en_backend.predict.assert_not_called()
 
-    en_mock = MagicMock()
-    en_mock.predict.return_value = _ents(
-        Entity(text="Google", label="organization", score=0.95, start=5, end=11)
+
+# ── EN branch fallback (symmetric) ───────────────────────────────────────────
+
+def test_en_insufficient_triggers_zh_fallback_and_adds():
+    """EN 主模型不充分 → 调 ZH 兜底 → 结果相加。"""
+    svc = _build_svc()
+    long_text = "Tesla" + "x" * 350
+    svc._en_backend.predict.return_value = _ents(
+        Entity(text="Tesla", label="organization", score=0.95, start=0, end=5),
     )
-    zh_mock = MagicMock()
-    zh_mock.predict.return_value = _ents(
-        Entity(text="张伟", label="person", score=0.91, start=0, end=2)
+    svc._zh_backend.predict.return_value = _ents(
+        Entity(text="马云", label="人名或姓名", score=0.91, start=10, end=12),
     )
-    svc._en_backend = en_mock
-    svc._zh_backend = zh_mock
+    entities, _ = svc.extract(long_text, [], 0.4, language="en")
 
-    entities, _ = svc.extract("张伟加入 Google。", [], 0.4, language="mixed")
     texts = {e.text for e in entities}
-    assert "Google" in texts
-    assert "张伟"   in texts
-    en_mock.predict.assert_called_once()
-    zh_mock.predict.assert_called_once()
+    assert "Tesla" in texts and "马云" in texts
+    assert len(entities) == 2
 
 
-def test_mixed_deduplicates_overlapping_spans():
-    """两个模型对同一 span 都命中时，只保留得分最高的。"""
-    from app.ner import NERService
+# ── Mixed: always merge both ─────────────────────────────────────────────────
+
+def test_mixed_always_runs_both_models():
+    """mixed ���言无视充分性，永远跑两个模型并合并。"""
+    svc = _build_svc()
+    svc._en_backend.predict.return_value = _ents(
+        Entity(text="Google", label="organization", score=0.95, start=5, end=11)
+    )
+    svc._zh_backend.predict.return_value = _ents(
+        Entity(text="张伟", label="人名或姓名", score=0.91, start=0, end=2)
+    )
+    entities, _ = svc.extract("张伟加入 Google。", [], 0.4, language="mixed")
+    texts = {e.text for e in entities}
+    assert {"Google", "张伟"} <= texts
+    svc._en_backend.predict.assert_called_once()
+    svc._zh_backend.predict.assert_called_once()
 
-    svc = NERService.__new__(NERService)
-    svc._en_lock = __import__("threading").Lock()
-    svc._zh_lock = __import__("threading").Lock()
 
-    en_mock = MagicMock()
-    en_mock.predict.return_value = (
+def test_merge_deduplicates_overlapping_spans():
+    """两个模型对同一 span 都命中 → 保留得分最高的那条。"""
+    svc = _build_svc()
+    svc._en_backend.predict.return_value = (
         [Entity(text="张伟", label="person", score=0.70, start=0, end=2)],
         ["person"],
     )
-    zh_mock = MagicMock()
-    zh_mock.predict.return_value = (
+    svc._zh_backend.predict.return_value = (
         [Entity(text="张伟", label="人名或姓名", score=0.92, start=0, end=2)],
         ["人名或姓名"],
     )
-    svc._en_backend = en_mock
-    svc._zh_backend = zh_mock
-
     entities, _ = svc.extract("张伟", [], 0.4, language="mixed")
-    # 去重后只有 1 个 "张伟"，且是得分更高的那条
-    zhang_wei = [e for e in entities if e.text == "张伟"]
-    assert len(zhang_wei) == 1
-    assert zhang_wei[0].score == 0.92
+    matches = [e for e in entities if e.text == "张伟"]
+    assert len(matches) == 1
+    assert matches[0].score == 0.92          # 高分胜出