mirror of
https://github.com/ThearchyHelios/AgentLab.git
synced 2026-11-17 21:01:58 +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:
@@ -191,6 +191,15 @@ export const api = {
|
||||
search: (q: string, collection?: string, alpha = 0.5) =>
|
||||
get<any>(`/kb/search?q=${encodeURIComponent(q)}&alpha=${alpha}${collection ? `&collection=${collection}` : ''}`),
|
||||
remove: (id: string) => del(`/kb/documents/${id}`),
|
||||
embedding: (collection?: string) => get<{
|
||||
embedder: string; dim: number; configured: boolean
|
||||
kind: string; model: string; stale_chunks: number
|
||||
}>(`/kb/embedding${collection ? `?collection=${collection}` : ''}`),
|
||||
setEmbedding: (body: { kind: string; model?: string }) =>
|
||||
put<{ embedder: string; dim: number; stale_chunks: number }>('/kb/embedding', body),
|
||||
reindex: (collection?: string) =>
|
||||
post<{ reindexed: number; embedder: string }>(
|
||||
`/kb/reindex${collection ? `?collection=${collection}` : ''}`),
|
||||
},
|
||||
skills: {
|
||||
list: () => get<Skill[]>('/skills'),
|
||||
|
||||
@@ -29,6 +29,94 @@ export function KnowledgePage() {
|
||||
|
||||
// -------------------------------------------------------------------------
|
||||
|
||||
/**
|
||||
* 当前用哪个 embedder,以及有多少条向量已经对不上。
|
||||
*
|
||||
* 在此之前切换 embedding 模型的唯一开关是 AGENTLAB_USE_OPENAI_EMBEDDINGS——
|
||||
* 一个没有界面、没人会发现的环境变量。于是所有人都在用那个没有语义能力的
|
||||
* 哈希向量(同义改写一条都召不回),而 alpha 默认还给了它一半权重。
|
||||
*
|
||||
* 换模型之后存量向量就和查询对不上了,检索会整体退回纯关键词。这一条必须
|
||||
* 显眼:少了一半能力却不说,用户只会觉得"最近搜得不准"。
|
||||
*/
|
||||
function EmbedderBar({ collection, onChanged }: {
|
||||
collection: string
|
||||
onChanged: () => void | Promise<void>
|
||||
}) {
|
||||
const toast = useToast()
|
||||
const [info, setInfo] = useState<any>(null)
|
||||
const [busy, setBusy] = useState(false)
|
||||
|
||||
const refresh = async () => setInfo(await api.kb.embedding(collection).catch(() => null))
|
||||
useEffect(() => { void refresh() }, [collection])
|
||||
|
||||
if (!info) return null
|
||||
const stale = info.stale_chunks ?? 0
|
||||
|
||||
const pick = async (kind: string, model: string) => {
|
||||
setBusy(true)
|
||||
try {
|
||||
const out = await api.kb.setEmbedding({ kind, model })
|
||||
toast(`已切到 ${out.embedder}`, 'ok')
|
||||
await refresh()
|
||||
} catch (e: any) {
|
||||
// 400 里是"缺 OPENAI_API_KEY"这类能照着做的原因,原样交给用户
|
||||
toast(e?.message ?? '切换失败', 'error')
|
||||
} finally { setBusy(false) }
|
||||
}
|
||||
|
||||
const rebuild = async () => {
|
||||
setBusy(true)
|
||||
try {
|
||||
const out = await api.kb.reindex(collection)
|
||||
toast(`已用 ${out.embedder} 重建 ${out.reindexed} 段`, 'ok')
|
||||
await refresh()
|
||||
await onChanged()
|
||||
} catch (e: any) {
|
||||
toast(e?.message ?? '重建失败', 'error')
|
||||
} finally { setBusy(false) }
|
||||
}
|
||||
|
||||
return (
|
||||
<div className="mb-3 rounded-lg border bg-panel p-3 text-[12px]">
|
||||
<div className="flex flex-wrap items-center gap-2">
|
||||
<span className="text-faint">向量模型</span>
|
||||
<select className="field h-7 w-auto" disabled={busy}
|
||||
value={info.kind === 'openai' ? `openai:${info.model}` : 'local'}
|
||||
onChange={(e) => {
|
||||
const [kind, ...rest] = e.target.value.split(':')
|
||||
void pick(kind, rest.join(':'))
|
||||
}}>
|
||||
<option value="local">本地哈希(零配置,但没有语义能力)</option>
|
||||
<option value="openai:text-embedding-3-small">OpenAI 3-small</option>
|
||||
<option value="openai:text-embedding-3-large">OpenAI 3-large</option>
|
||||
</select>
|
||||
<span className="mono text-[11px] text-faint">{info.embedder} · {info.dim} 维</span>
|
||||
<span className="flex-1" />
|
||||
{stale > 0 && (
|
||||
<button className="btn btn-sm btn-primary" disabled={busy} onClick={rebuild}>
|
||||
重建索引({stale} 段)
|
||||
</button>
|
||||
)}
|
||||
</div>
|
||||
{stale > 0 && (
|
||||
<p className="mt-2 text-[11px]" style={{ color: 'var(--warn)' }}>
|
||||
有 {stale} 段的向量是用别的模型建的,和当前模型对不上——检索这些内容时
|
||||
会退回纯关键词(搜不出同义表达)。重建索引后恢复。
|
||||
</p>
|
||||
)}
|
||||
{info.kind !== 'openai' && stale === 0 && (
|
||||
<p className="mt-2 text-[11px] text-faint">
|
||||
本地向量不联网、零配置,但它是词频哈希、没有语义泛化——
|
||||
「管理员」搜不到「平台角色」。认真用知识库的话换成上面的真模型。
|
||||
</p>
|
||||
)}
|
||||
</div>
|
||||
)
|
||||
}
|
||||
|
||||
// -------------------------------------------------------------------------
|
||||
|
||||
function KbTab() {
|
||||
const toast = useToast()
|
||||
const refreshCatalog = useCatalog((s) => s.refresh)
|
||||
@@ -95,6 +183,8 @@ function KbTab() {
|
||||
))}
|
||||
</div>
|
||||
|
||||
<EmbedderBar collection={collection} onChanged={load} />
|
||||
|
||||
{/* 检索调试:能直观看到混合检索里语义和关键词各占多少 */}
|
||||
<div className="mb-4 rounded-lg border bg-panel p-3">
|
||||
<div className="mb-2 flex items-center gap-2">
|
||||
|
||||
@@ -712,6 +712,30 @@ export function decodeRun(events: RunEvent[]): Step[] {
|
||||
break
|
||||
}
|
||||
|
||||
case 'retrieve.end': {
|
||||
// 知识检索。以前只发一条 info 日志,于是"这句结论依据的是哪份文档的
|
||||
// 哪一段"在轨迹里查不到——而 SQL 取数那条路早就能下钻到工件
|
||||
const count = num(d.count) ?? 0
|
||||
const collection = String(d.collection ?? '')
|
||||
const top = num(d.top_score)
|
||||
push({
|
||||
id: `rt-${seq}`, seq, kind: 'schema', nodeId,
|
||||
status: count ? 'done' : 'failed',
|
||||
level: d.degraded ? 'warn' : count ? undefined : 'warn',
|
||||
title: count
|
||||
? `在「${collection}」里检索到 ${count} 段`
|
||||
: `在「${collection}」里没检索到内容`,
|
||||
detail: String(d.query ?? ''),
|
||||
meta: [
|
||||
top != null ? `最高分 ${top}` : '',
|
||||
// 退回关键词是"少了一半能力",不标出来用户只会觉得最近搜得不准
|
||||
d.degraded ? '已退回关键词' : '',
|
||||
].filter(Boolean).join(' · ') || undefined,
|
||||
artifact: d.artifact,
|
||||
}, nodeId)
|
||||
break
|
||||
}
|
||||
|
||||
default:
|
||||
// 新增事件类型时不要静默吞掉——宁可显示一条原始的,也比让人觉得
|
||||
// "什么都没发生"好。加了新事件记得回来补一条映射。
|
||||
|
||||
Reference in New Issue
Block a user