Просмотр исходного кода

feat(langgraph): 新增知识库 verify 校验端点(cosine 换算)

Xiaogang Liao 4 дней назад
Родитель
Сommit
729ce92623
2 измененных файлов с 206 добавлено и 0 удалено
  1. 97 0
      cfc-langgraph/app/api/knowledge_base.py
  2. 109 0
      cfc-langgraph/tests/test_knowledge_verify.py

+ 97 - 0
cfc-langgraph/app/api/knowledge_base.py

@@ -4,8 +4,14 @@ from pydantic import BaseModel
 from typing import Optional, List
 import logging
 import asyncio
+import math
 import os
 
+# 模块级导入:verify 端点复用同一 Chroma/embedding 实例构造(测试可 monkeypatch)
+from langchain_chroma import Chroma
+from app.config import settings
+from app.rag.embeddings import get_embeddings
+
 logger = logging.getLogger(__name__)
 
 router = APIRouter(prefix="/api/v1/knowledge-base", tags=["knowledge-base"])
@@ -261,3 +267,94 @@ def _load_sync_state() -> str:
     except Exception:
         pass
     return "未知"
+
+
+class VerifySentence(BaseModel):
+    id: str
+    text: str
+
+
+class VerifyRequest(BaseModel):
+    sentences: List[VerifySentence]
+    source: str = "microbiome"
+    k: int = 3
+    threshold: float = 0.7
+
+
+@router.post("/verify")
+async def verify(req: VerifyRequest):
+    """知识库出处自检:对每个待检整句做 RAG 检索,返回最大 cosine 相似度。
+
+    度量说明:本库 ChromaDB collection 未配置 hnsw:space(默认 L2 距离),
+    similarity_search_with_score 的 score 是 L2 距离(越小越相似),不是相似度,
+    因而返回前必须取候选向量与 query 向量独立计算 cosine 相似度,
+    不得把 L2 距离当相似度、也不得用 1 - d^2/2 近似(仅对归一化向量成立)。
+    """
+    try:
+        store = Chroma(
+            collection_name="cfc_knowledge",
+            embedding_function=get_embeddings(),
+            persist_directory=settings.chroma_db_path,
+        )
+        embedder = get_embeddings()
+        results = []
+        for s in req.sentences:
+            text = (s.text or "").strip()
+            if not text:
+                results.append({"id": s.id, "max_similarity": 0.0, "passed": False,
+                                "matched_title": None, "matched_chunk": None})
+                continue
+            try:
+                candidates = store.similarity_search_with_score(
+                    text, k=req.k, filter={"source": req.source})
+            except Exception as e:
+                logger.warning("verify 检索失败 sentence=%s: %s", s.id, e)
+                results.append({"id": s.id, "max_similarity": 0.0, "passed": False,
+                                "matched_title": None, "matched_chunk": None})
+                continue
+            query_vec = await asyncio.to_thread(embedder.embed_query, text)
+            best = {"max_similarity": 0.0, "matched_title": None, "matched_chunk": None}
+            for doc, _dist in candidates:
+                meta = doc.metadata or {}
+                doc_id = meta.get("id")
+                if not doc_id:
+                    continue
+                try:
+                    got = store._collection.get(ids=[doc_id], include=["embeddings"])
+                    vecs = got.get("embeddings") or []
+                    if not vecs:
+                        continue
+                    cand_vec = vecs[0]
+                except Exception as e:
+                    logger.warning("verify 取 embedding 失败 doc=%s: %s", doc_id, e)
+                    continue
+                sim = _cosine(query_vec, cand_vec)
+                if sim > best["max_similarity"]:
+                    best = {
+                        "max_similarity": sim,
+                        "matched_title": meta.get("title"),
+                        "matched_chunk": (doc.page_content[:120] if doc.page_content else None),
+                    }
+            best["id"] = s.id
+            best["passed"] = best["max_similarity"] >= req.threshold
+            results.append(best)
+        all_passed = all(r["passed"] for r in results)
+        return {"code": 200, "data": {
+            "source": req.source, "threshold": req.threshold,
+            "results": results, "all_passed": all_passed,
+        }}
+    except Exception as e:
+        logger.error("verify 端点异常: %s", e)
+        raise HTTPException(status_code=500, detail=str(e))
+
+
+def _cosine(a: list, b: list) -> float:
+    """余弦相似度(对任意范数向量成立,不依赖归一化)。"""
+    if not a or not b or len(a) != len(b):
+        return 0.0
+    dot = sum(x * y for x, y in zip(a, b))
+    na = math.sqrt(sum(x * x for x in a))
+    nb = math.sqrt(sum(y * y for y in b))
+    if na == 0.0 or nb == 0.0:
+        return 0.0
+    return dot / (na * nb)

+ 109 - 0
cfc-langgraph/tests/test_knowledge_verify.py

@@ -0,0 +1,109 @@
+# -*- coding: utf-8 -*-
+"""verify 端点测试:L2→cosine 换算 + 阈值判定。"""
+import pytest
+from httpx import AsyncClient, ASGITransport
+from app.main import app
+
+
+class FakeDoc:
+    def __init__(self, content, metadata):
+        self.page_content = content
+        self.metadata = metadata
+
+
+class FakeCollection:
+    def __init__(self, emb_by_id):
+        self._emb = emb_by_id
+
+    def get(self, ids=None, include=None):
+        return {"ids": ids, "embeddings": [self._emb[i] for i in ids]}
+
+
+class FakeStore:
+    def __init__(self, emb_by_id, candidates):
+        self._collection = FakeCollection(emb_by_id)
+        self._candidates = candidates
+
+    def similarity_search_with_score(self, query, k=None, filter=None):
+        return self._candidates[:k]
+
+
+class FakeEmbeddings:
+    def __init__(self, q):
+        self.q = q
+
+    def embed_query(self, text):
+        return self.q
+
+
+def _patch_kb(monkeypatch, query_vec, emb_by_id, candidates):
+    import app.api.knowledge_base as kb
+    fake_store = FakeStore(emb_by_id, candidates)
+    monkeypatch.setattr(kb, "Chroma", lambda *a, **kw: fake_store)
+    monkeypatch.setattr(kb, "get_embeddings", lambda: FakeEmbeddings(query_vec))
+    return fake_store
+
+
+@pytest.mark.asyncio
+async def test_verify_converts_l2_to_cosine(monkeypatch):
+    """关键:L2 距离≠相似度。候选向量 [0.5,0.5,0,0] 与 query [1,0,0,0]
+    真实 cosine=0.7071;若误用 L2(1-d^2/2) 会得 0.75。断言用真实 cosine。"""
+    q = [1.0, 0.0, 0.0, 0.0]
+    # 非归一化候选:真实 cos = 0.5 / sqrt(0.5) = 0.70710678
+    emb = {"cand1": [0.5, 0.5, 0.0, 0.0]}
+    cands = [(FakeDoc("AKK菌相关内容...", {"id": "cand1", "title": "AKK菌——下一代有益菌", "source": "microbiome"}), 0.7071)]
+    _patch_kb(monkeypatch, q, emb, cands)
+
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        resp = await client.post("/api/v1/knowledge-base/verify", json={
+            "sentences": [{"id": "s1", "text": "双歧杆菌有助于维持肠道菌群平衡"}],
+            "source": "microbiome", "k": 3, "threshold": 0.7,
+        })
+    assert resp.status_code == 200
+    data = resp.json()
+    assert data["code"] == 200
+    r = data["data"]["results"][0]
+    assert r["id"] == "s1"
+    got = r.get("max_similarity")
+    assert got == pytest.approx(0.70710678, abs=1e-3), (
+        "应为真实 cosine 约 0.7071,若返回约 0.75 说明误用 L2。got=" + str(got)
+    )
+    assert r["passed"] is True
+    assert r["matched_title"] == "AKK菌——下一代有益菌"
+
+
+@pytest.mark.asyncio
+async def test_verify_passed_when_cosine_ge_threshold(monkeypatch):
+    q = [1.0, 0.0, 0.0, 0.0]
+    emb = {"cand1": [0.9, 0.43589, 0.0, 0.0]}  # norm≈1,cos=0.9 >=0.7
+    cands = [(FakeDoc("高相似内容", {"id": "cand1", "title": "T", "source": "microbiome"}), 0.3)]
+    _patch_kb(monkeypatch, q, emb, cands)
+
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        resp = await client.post("/api/v1/knowledge-base/verify", json={
+            "sentences": [{"id": "s1", "text": "双歧杆菌"}], "source": "microbiome",
+        })
+    data = resp.json()
+    r = data["data"]["results"][0]
+    assert r["passed"] is True
+    assert data["data"]["all_passed"] is True
+
+
+@pytest.mark.asyncio
+async def test_verify_failed_below_threshold(monkeypatch):
+    q = [1.0, 0.0, 0.0, 0.0]
+    emb = {"cand1": [0.3, 0.9, 0.0, 0.0]}  # cos 约 0.316 < 0.7
+    cands = [(FakeDoc("低相似内容", {"id": "cand1", "title": "T", "source": "microbiome"}), 0.9)]
+    _patch_kb(monkeypatch, q, emb, cands)
+
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as client:
+        resp = await client.post("/api/v1/knowledge-base/verify", json={
+            "sentences": [{"id": "s1", "text": "随便一句话"}], "source": "microbiome",
+        })
+    data = resp.json()
+    r = data["data"]["results"][0]
+    assert r["passed"] is False
+    assert data["data"]["all_passed"] is False