mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-22 17:32:01 +00:00
知识库:换 embedding 模型不再 500,检索能回指了
三件事,都是"这三个模块一条测试都没有"的后果。 **换 embedder 会让检索整体 500。** 库里是 512 维的本地向量、查询是 1536 维的 远端向量时,cosine 直接 `shapes (1536,) and (512,) not aligned`。from_blob 有 dim 参数,但 kb.py 和 memory/store.py 调用时都没传;而且存量向量属于哪个模型 代码里没有任何地方记着,所以也无从降级。 Chunk / MemoryItem 各加 embed_model + embed_dim(走现成的 _COLUMN_MIGRATIONS, 存量回填空值,正好表示"不知道是谁建的")。检索遇到对不上的向量整体退回纯 关键词并说破,不是把它们当 0 分静默沉底——那样用户看到的是结果莫名其妙变差, 而不是"这里有一批索引该重建了"。配套 kb.reindex + POST /api/kb/reindex。 长期记忆那份一起修了。判重那条更危险:维度碰巧相同但模型不同时 cosine 算出来 是随机数,会把不相关的旧记忆认成"重复",然后把新内容丢掉。 **默认 embedder 没有语义能力,而开关藏在一个环境变量里。** LocalEmbedder 是 特征哈希 + TF,和 BM25 吃同一批词;alpha 默认 0.5 等于给了它一半权重,同义 改写一条都召不回。开启真模型的唯一开关是 AGENTLAB_USE_OPENAI_EMBEDDINGS—— 没界面、没人会发现。改成设置项(照 COPILOT_SETTING_KEY 的路子),知识库页顶部 能选能看能重建。 配置失败必须响:第一版写成静默退回本地,但选了 OpenAI 却拿到哈希向量的人, 在搜不出同义表达时完全无从怀疑到这里。现在抛 EmbedderUnavailable,API 400 原样交回"检查 OPENAI_API_KEY 是否配了",且不会把配置改掉。 **检索结果不进工件库。** db_query、工具节点、agent 工具调用都落 put_json 快照, run_retrieve 什么都不落——于是结论只要来自知识库,"这个数是哪来的"就断在这儿, 而数字回指正是这个项目的签名能力。现在落 kind="retrieval_snapshot",并发一条 retrieve.end 带 artifact id。解码层补了正式映射(原来会掉进"未知事件"兜底, 画成一坨原始 JSON)。 新增 test_kb.py 11 条,补上这三个模块此前的零覆盖,包括 embeddings.py 里 注释记着、但一直没有测试守的那个归一化边界(单条候选被 min_score 误杀)。 端到端在真实服务上验过:撞上存量向量返回 200 + 降级说明(以前 500)、 重建后 stale 归零、配不起来的远端模型 400 且配置不变。
This commit is contained in:
@@ -61,7 +61,9 @@ class OpenAIEmbedder:
|
||||
base_url: str | None = None) -> None:
|
||||
from langchain_openai import OpenAIEmbeddings
|
||||
|
||||
self.dim = 1536
|
||||
self.model = model
|
||||
# text-embedding-3-large 是 3072,别写死
|
||||
self.dim = 3072 if "3-large" in model else 1536
|
||||
self._impl = OpenAIEmbeddings(
|
||||
model=model,
|
||||
api_key=api_key or os.environ.get("OPENAI_API_KEY"),
|
||||
@@ -79,17 +81,92 @@ class OpenAIEmbedder:
|
||||
|
||||
_local = LocalEmbedder()
|
||||
|
||||
#: 设置表里存 embedding 配置的键。和 Copilot 模型同一套路子
|
||||
EMBEDDING_SETTING_KEY = "embedding"
|
||||
|
||||
def get_embedder() -> LocalEmbedder | OpenAIEmbedder:
|
||||
"""默认走本地;显式打开 AGENTLAB_USE_OPENAI_EMBEDDINGS 且有 key 时才用远端。"""
|
||||
#: 进程内缓存。get_embedder 在检索热路径上被反复调用,不该每次都去读库
|
||||
_cached: tuple[str, Any] | None = None
|
||||
|
||||
|
||||
class EmbedderUnavailable(RuntimeError):
|
||||
"""配了远端 embedder 但建不起来。message 直接给用户看。"""
|
||||
|
||||
|
||||
def _make(kind: str, model: str, *, strict: bool) -> "LocalEmbedder | OpenAIEmbedder":
|
||||
if kind != "openai":
|
||||
return _local
|
||||
try:
|
||||
return OpenAIEmbedder(model=model or "text-embedding-3-small")
|
||||
except Exception as e: # noqa: BLE001
|
||||
if strict:
|
||||
# 人明确选了远端就不能偷偷退回本地:他会以为自己在用语义检索,
|
||||
# 而实际拿到的是哈希词袋——搜不出同义表达时完全无从怀疑到这里
|
||||
raise EmbedderUnavailable(
|
||||
f"用不了 embedding 模型 {model or 'text-embedding-3-small'}:"
|
||||
f"{type(e).__name__}: {e}。检查 OPENAI_API_KEY 是否配了。"
|
||||
) from e
|
||||
return _local
|
||||
|
||||
|
||||
def configure(kind: str, model: str = "") -> None:
|
||||
"""切换当前 embedder。设置页保存后调用,也用于测试。建不起来会抛。"""
|
||||
global _cached
|
||||
_cached = (f"{kind}:{model}", _make(kind, model, strict=True))
|
||||
|
||||
|
||||
def get_embedder() -> "LocalEmbedder | OpenAIEmbedder":
|
||||
"""当前 embedder。
|
||||
|
||||
优先级:进程内已配置 > 环境变量兜底 > 本地。设置页写库后会调 configure,
|
||||
所以这里不再每次读库——检索热路径上一次查询要走几百次。
|
||||
|
||||
以前这里只认 AGENTLAB_USE_OPENAI_EMBEDDINGS 一个环境变量:没有界面、
|
||||
没人会发现,于是所有人都在用那个没有语义能力的哈希向量,而 alpha 默认
|
||||
0.5 还给了它一半权重。
|
||||
"""
|
||||
if _cached is not None:
|
||||
return _cached[1]
|
||||
if os.environ.get("AGENTLAB_USE_OPENAI_EMBEDDINGS") and os.environ.get("OPENAI_API_KEY"):
|
||||
try:
|
||||
return OpenAIEmbedder()
|
||||
except Exception: # noqa: BLE001
|
||||
return _local
|
||||
return _make("openai", "", strict=False)
|
||||
return _local
|
||||
|
||||
|
||||
def embedder_id() -> str:
|
||||
"""当前 embedder 的身份。存进 chunk 那一列,检索时拿它判断存量向量还能不能用。"""
|
||||
emb = get_embedder()
|
||||
name = getattr(emb, "name", "unknown")
|
||||
model = getattr(emb, "model", "")
|
||||
return f"{name}:{model}" if model else name
|
||||
|
||||
|
||||
def embedder_dim() -> int:
|
||||
return int(getattr(get_embedder(), "dim", _DIM))
|
||||
|
||||
|
||||
def usable(embed_model: str | None, embed_dim: int | None) -> bool:
|
||||
"""这条存量向量还能不能和当前查询比对。
|
||||
|
||||
维度对不上 cosine 会直接抛 ValueError(shapes (1536,) and (512,) not
|
||||
aligned),所以这不是"质量差一点",是会 500。模型名也要比:同维度不同
|
||||
模型的向量空间没有可比性,算出来的相似度是随机数。
|
||||
|
||||
存量数据这两列是空的(迁移回填的默认值),一律当成不可用——保守,
|
||||
但总比拿旧模型的向量冒充当前空间里的坐标强。
|
||||
"""
|
||||
return bool(embed_model) and embed_model == embedder_id() and embed_dim == embedder_dim()
|
||||
|
||||
|
||||
async def load_setting(session: Any) -> None:
|
||||
"""从库里读 embedding 配置并生效。应用启动时调一次。"""
|
||||
from app.db.models import Setting
|
||||
|
||||
row = await session.get(Setting, EMBEDDING_SETTING_KEY)
|
||||
saved = (row.value if row else {}) or {}
|
||||
kind = saved.get("kind")
|
||||
if kind:
|
||||
configure(kind, saved.get("model", ""))
|
||||
|
||||
|
||||
async def embed_text(text: str) -> np.ndarray:
|
||||
emb = get_embedder()
|
||||
if isinstance(emb, OpenAIEmbedder):
|
||||
|
||||
@@ -7,7 +7,9 @@ from sqlalchemy import func, select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from app.db.models import Chunk, Document
|
||||
from app.memory.embeddings import embed_text, embed_texts, from_blob, hybrid_rank, to_blob
|
||||
from app.memory.embeddings import (
|
||||
embed_text, embed_texts, embedder_dim, embedder_id, from_blob, hybrid_rank, to_blob, usable,
|
||||
)
|
||||
|
||||
_TARGET = 800
|
||||
_OVERLAP = 120
|
||||
@@ -97,6 +99,8 @@ async def ingest_document(
|
||||
ordinal=i,
|
||||
content=piece,
|
||||
embedding=to_blob(vec),
|
||||
embed_model=embedder_id(),
|
||||
embed_dim=embedder_dim(),
|
||||
meta={"title": doc.title},
|
||||
)
|
||||
)
|
||||
@@ -113,7 +117,17 @@ async def search(
|
||||
query: str,
|
||||
limit: int = 5,
|
||||
alpha: float = 0.5,
|
||||
on_degrade: Any = None,
|
||||
) -> list[dict[str, Any]]:
|
||||
"""混合检索。
|
||||
|
||||
存量向量和当前 embedder 对不上时**整个查询退回纯关键词**,并通过
|
||||
on_degrade 把原因交出去。不把对不上的那些当 0 分:那会让它们静默沉底,
|
||||
用户看到的是结果莫名其妙变差,而不是"这里有一批索引该重建了"。
|
||||
|
||||
在此之前这里连维度都不查,换个 embedder 直接 ValueError
|
||||
(shapes (1536,) and (512,) not aligned),整个检索 500。
|
||||
"""
|
||||
stmt = select(Chunk)
|
||||
if collection:
|
||||
stmt = stmt.where(Chunk.collection == collection)
|
||||
@@ -121,11 +135,26 @@ async def search(
|
||||
if not rows:
|
||||
return []
|
||||
|
||||
query_vec = await embed_text(query)
|
||||
stale = [r for r in rows if not usable(r.embed_model, r.embed_dim)]
|
||||
if stale:
|
||||
if on_degrade:
|
||||
names = sorted({r.embed_model or "未知模型" for r in stale})
|
||||
on_degrade(
|
||||
f"{collection or '全部集合'}里有 {len(stale)}/{len(rows)} 条向量由"
|
||||
f"「{'、'.join(names)}」建立,和当前的「{embedder_id()}」对不上,"
|
||||
f"本次已退回纯关键词检索。重建索引后恢复。"
|
||||
)
|
||||
alpha = 0.0 # 纯关键词
|
||||
vectors: list[Any] = [None] * len(rows)
|
||||
query_vec = await embed_text(query)
|
||||
else:
|
||||
query_vec = await embed_text(query)
|
||||
vectors = [from_blob(r.embedding, embedder_dim()) for r in rows]
|
||||
|
||||
ranked = hybrid_rank(
|
||||
query,
|
||||
[r.content for r in rows],
|
||||
[from_blob(r.embedding) for r in rows],
|
||||
vectors,
|
||||
query_vec,
|
||||
alpha=alpha,
|
||||
)
|
||||
@@ -146,6 +175,41 @@ async def search(
|
||||
return out
|
||||
|
||||
|
||||
async def reindex(session: AsyncSession, collection: str | None = None) -> dict[str, Any]:
|
||||
"""用当前 embedder 重算向量。
|
||||
|
||||
换了 embedding 模型之后唯一的恢复手段。按批做:一次几千条 chunk 全塞给
|
||||
远端 embedding 接口,要么超时要么被限流,而中途失败又没有断点。
|
||||
"""
|
||||
stmt = select(Chunk)
|
||||
if collection:
|
||||
stmt = stmt.where(Chunk.collection == collection)
|
||||
rows = list((await session.execute(stmt)).scalars())
|
||||
if not rows:
|
||||
return {"collection": collection, "reindexed": 0, "embedder": embedder_id()}
|
||||
|
||||
model_id, dim = embedder_id(), embedder_dim()
|
||||
batch = 64
|
||||
for i in range(0, len(rows), batch):
|
||||
part = rows[i:i + batch]
|
||||
vectors = await embed_texts([r.content for r in part])
|
||||
for row, vec in zip(part, vectors):
|
||||
row.embedding = to_blob(vec)
|
||||
row.embed_model = model_id
|
||||
row.embed_dim = dim
|
||||
await session.commit()
|
||||
return {"collection": collection, "reindexed": len(rows), "embedder": model_id}
|
||||
|
||||
|
||||
async def stale_count(session: AsyncSession, collection: str | None = None) -> int:
|
||||
"""有多少条向量和当前 embedder 对不上。知识库页据此提示要不要重建。"""
|
||||
stmt = select(Chunk)
|
||||
if collection:
|
||||
stmt = stmt.where(Chunk.collection == collection)
|
||||
rows = list((await session.execute(stmt)).scalars())
|
||||
return sum(1 for r in rows if not usable(r.embed_model, r.embed_dim))
|
||||
|
||||
|
||||
async def delete_document(session: AsyncSession, doc_id: str) -> bool:
|
||||
doc = await session.get(Document, doc_id)
|
||||
if not doc:
|
||||
|
||||
@@ -7,7 +7,9 @@ from sqlalchemy import delete, func, select
|
||||
from sqlalchemy.ext.asyncio import AsyncSession
|
||||
|
||||
from app.db.models import MemoryItem
|
||||
from app.memory.embeddings import cosine, embed_text, from_blob, hybrid_rank, to_blob
|
||||
from app.memory.embeddings import (
|
||||
cosine, embed_text, embedder_dim, embedder_id, from_blob, hybrid_rank, to_blob, usable,
|
||||
)
|
||||
|
||||
# 判重阈值:余弦相似度高于它才算同一件事。比排名分数严格得多,
|
||||
# 因为这里比的是真实语义距离,不是"谁排第一"。
|
||||
@@ -44,7 +46,12 @@ async def remember(
|
||||
candidates = list((await session.execute(stmt)).scalars())
|
||||
best, best_score = None, 0.0
|
||||
for row in candidates:
|
||||
other = from_blob(row.embedding)
|
||||
# 对不上当前 embedder 的直接跳过:维度不同 cosine 会抛,维度碰巧
|
||||
# 相同但模型不同则更糟——两个空间之间的相似度是个随机数,
|
||||
# 拿它判重会把不相关的旧记忆认成"重复"然后丢掉新内容
|
||||
if not usable(row.embed_model, row.embed_dim):
|
||||
continue
|
||||
other = from_blob(row.embedding, embedder_dim())
|
||||
if other is None:
|
||||
continue
|
||||
score = cosine(vec, other)
|
||||
@@ -64,6 +71,8 @@ async def remember(
|
||||
meta=meta or {},
|
||||
importance=importance,
|
||||
embedding=to_blob(vec),
|
||||
embed_model=embedder_id(),
|
||||
embed_dim=embedder_dim(),
|
||||
)
|
||||
session.add(item)
|
||||
await session.commit()
|
||||
@@ -89,11 +98,19 @@ async def recall(
|
||||
return []
|
||||
|
||||
query_vec = await embed_text(query)
|
||||
# 和 kb.search 同一个道理:有对不上的就整体退回关键词,而不是让它们静默沉底
|
||||
if any(not usable(r.embed_model, r.embed_dim) for r in rows):
|
||||
vectors: list[Any] = [None] * len(rows)
|
||||
alpha = 0.0
|
||||
else:
|
||||
vectors = [from_blob(r.embedding, embedder_dim()) for r in rows]
|
||||
alpha = 0.5
|
||||
ranked = hybrid_rank(
|
||||
query,
|
||||
[r.content for r in rows],
|
||||
[from_blob(r.embedding) for r in rows],
|
||||
vectors,
|
||||
query_vec,
|
||||
alpha=alpha,
|
||||
)
|
||||
|
||||
results: list[dict[str, Any]] = []
|
||||
|
||||
Reference in New Issue
Block a user