diff --git a/backend/app/api/knowledge.py b/backend/app/api/knowledge.py index 677627c7..3911abfc 100644 --- a/backend/app/api/knowledge.py +++ b/backend/app/api/knowledge.py @@ -206,6 +206,7 @@ async def embedding_status( "configured": bool(saved.get("kind")), "kind": saved.get("kind", "local"), "model": saved.get("model", ""), + "base_url": saved.get("base_url", ""), "stale_chunks": await kb.stale_count(session, collection), # 记忆和知识库共用一个 embedder,换模型时一起失效——报一个漏一个 # 的话,用户点完重建还是想不起事,而且不知道为什么 @@ -220,6 +221,9 @@ async def embedding_status( class EmbeddingIn(BaseModel): kind: str = Field(default="local", pattern="^(local|openai)$") model: str = "" + #: 任何讲 OpenAI /v1/embeddings 的地址:本机 LM Studio / Ollama / vLLM / TEI, + #: 或者你自己的网关。留空才走 api.openai.com + base_url: str = "" @kb_router.put("/embedding") @@ -235,12 +239,13 @@ async def set_embedding( from app.db.models import Setting try: - emb.configure(payload.kind, payload.model) + emb.configure(payload.kind, payload.model, payload.base_url) except emb.EmbedderUnavailable as e: raise HTTPException(400, str(e)) from e row = await session.get(Setting, emb.EMBEDDING_SETTING_KEY) - value = {"kind": payload.kind, "model": payload.model} + value = {"kind": payload.kind, "model": payload.model, + "base_url": payload.base_url} if row: row.value = value else: @@ -254,6 +259,26 @@ async def set_embedding( } +@kb_router.get("/embedding/probe") +async def probe_embedding(base_url: str) -> dict[str, Any]: + """问问这个地址上有哪些模型。 + + 自己填模型名太容易写错(LM Studio 里叫 + text-embedding-qwen3-embedding-4b,不是 Qwen3-Embedding-4B), + 而填错的表现是切换时报一句 404,人还以为是服务没起。 + """ + import httpx + + url = base_url.rstrip("/") + "/models" + try: + async with httpx.AsyncClient(timeout=8) as client: + data = (await client.get(url)).json() + except Exception as e: # noqa: BLE001 + raise HTTPException(400, f"连不上 {url}:{type(e).__name__}: {e}") from e + models = [m.get("id", "") for m in (data.get("data") or []) if m.get("id")] + return {"base_url": base_url, "models": models} + + @kb_router.post("/reindex") async def reindex( collection: str | None = None, session: AsyncSession = Depends(get_session) diff --git a/backend/tests/test_kb.py b/backend/tests/test_kb.py index 1de2a44d..abaab43c 100644 --- a/backend/tests/test_kb.py +++ b/backend/tests/test_kb.py @@ -522,3 +522,69 @@ def test_a_broken_endpoint_names_where_it_tried(monkeypatch) -> None: with pytest.raises(e.EmbedderUnavailable) as err: e.configure("openai", "qwen3-embedding-4b", "http://127.0.0.1:1234/v1") assert "127.0.0.1:1234" in str(err.value) and "qwen3-embedding-4b" in str(err.value) + + +async def test_the_probe_endpoint_lists_models(monkeypatch) -> None: + """模型名手填太容易错:LM Studio 里叫 text-embedding-qwen3-embedding-4b, + 不是 Qwen3-Embedding-4B。填错的表现是切换时 404,人还以为是服务没起。""" + import httpx + from httpx import ASGITransport, AsyncClient + + from app.main import app + + class _Resp: + def json(self): + return {"data": [{"id": "text-embedding-qwen3-embedding-4b"}, {"id": "other"}]} + + class _Client: + def __init__(self, **kw): ... + async def __aenter__(self): return self + async def __aexit__(self, *a): return False + async def get(self, _url): return _Resp() + + monkeypatch.setattr(httpx, "AsyncClient", _Client) + transport = ASGITransport(app=app) + async with AsyncClient(transport=transport, base_url="http://test") as c: + out = (await c.get("/api/kb/embedding/probe", + params={"base_url": "http://127.0.0.1:1234/v1"})).json() + assert "text-embedding-qwen3-embedding-4b" in out["models"] + + +async def test_a_dead_endpoint_says_which_address(monkeypatch) -> None: + import httpx + from httpx import ASGITransport, AsyncClient + + from app.main import app + + class _Client: + def __init__(self, **kw): ... + async def __aenter__(self): return self + async def __aexit__(self, *a): return False + async def get(self, _url): raise ConnectionError("refused") + + monkeypatch.setattr(httpx, "AsyncClient", _Client) + transport = ASGITransport(app=app) + async with AsyncClient(transport=transport, base_url="http://test") as c: + r = await c.get("/api/kb/embedding/probe", params={"base_url": "http://127.0.0.1:9999/v1"}) + assert r.status_code == 400 + assert "127.0.0.1:9999" in r.json()["detail"] + + +async def test_the_endpoint_is_remembered_across_restarts(client=None) -> None: + """base_url 不落库的话,重启后会悄悄退回本地哈希——而库里的向量是 + 上一个模型建的,检索会整体退回关键词,用户只看到"重启之后搜得不准了"。""" + from httpx import ASGITransport, AsyncClient + + from app.db.models import Setting + from app.main import app + from app.memory import embeddings as e + + transport = ASGITransport(app=app) + async with AsyncClient(transport=transport, base_url="http://test") as c: + await c.put("/api/kb/embedding", json={"kind": "local"}) + status = (await c.get("/api/kb/embedding")).json() + assert "base_url" in status, "状态里不回显 base_url,界面刷新后就不知道接的是哪" + + async with SessionLocal() as session: + row = await session.get(Setting, e.EMBEDDING_SETTING_KEY) + assert row is not None and "base_url" in row.value diff --git a/frontend/src/api/client.ts b/frontend/src/api/client.ts index e3d1aba7..ef383964 100644 --- a/frontend/src/api/client.ts +++ b/frontend/src/api/client.ts @@ -193,11 +193,17 @@ export const api = { remove: (id: string) => del(`/kb/documents/${id}`), embedding: (collection?: string) => get<{ embedder: string; dim: number; configured: boolean - kind: string; model: string; stale_chunks: number; stale_memories: number - unindexed_chunks: number + kind: string; model: string; base_url: string + stale_chunks: number; stale_memories: number; unindexed_chunks: number }>(`/kb/embedding${collection ? `?collection=${collection}` : ''}`), - setEmbedding: (body: { kind: string; model?: string }) => - put<{ embedder: string; dim: number; stale_chunks: number }>('/kb/embedding', body), + setEmbedding: (body: { kind: string; model?: string; base_url?: string }) => + put<{ + embedder: string; dim: number + stale_chunks: number; stale_memories: number + }>('/kb/embedding', body), + probeEmbedding: (baseUrl: string) => + get<{ base_url: string; models: string[] }>( + `/kb/embedding/probe?base_url=${encodeURIComponent(baseUrl)}`), reindex: (collection?: string) => post<{ reindexed: number; memories_reindexed: number; embedder: string }>( `/kb/reindex${collection ? `?collection=${collection}` : ''}`), diff --git a/frontend/src/pages/KnowledgePage.tsx b/frontend/src/pages/KnowledgePage.tsx index 71dd742a..4b63f866 100644 --- a/frontend/src/pages/KnowledgePage.tsx +++ b/frontend/src/pages/KnowledgePage.tsx @@ -46,8 +46,16 @@ function EmbedderBar({ collection, onChanged }: { const toast = useToast() const [info, setInfo] = useState(null) const [busy, setBusy] = useState(false) + const [editing, setEditing] = useState(false) + const [baseUrl, setBaseUrl] = useState('') + const [models, setModels] = useState([]) + const [model, setModel] = useState('') - const refresh = async () => setInfo(await api.kb.embedding(collection).catch(() => null)) + const refresh = async () => { + const next = await api.kb.embedding(collection).catch(() => null) + setInfo(next) + if (next) { setBaseUrl(next.base_url || ''); setModel(next.model || '') } + } useEffect(() => { void refresh() }, [collection]) if (!info) return null @@ -60,18 +68,35 @@ function EmbedderBar({ collection, onChanged }: { const unindexed = info.unindexed_chunks ?? 0 const stale = staleChunks + staleMemories + unindexed - const pick = async (kind: string, model: string) => { + const pick = async (kind: string, m = '', url = '') => { setBusy(true) try { - const out = await api.kb.setEmbedding({ kind, model }) - toast(`已切到 ${out.embedder}`, 'ok') + const out = await api.kb.setEmbedding({ kind, model: m, base_url: url }) + // 换模型之后维度多半变了,存量向量全部作废——这件事要当场说, + // 而不是等用户发现"最近搜得不准" + const stale = (out.stale_chunks ?? 0) + (out.stale_memories ?? 0) + toast(`已切到 ${out.embedder}(${out.dim} 维)` + + (stale ? `,${stale} 条存量向量需要重建` : ''), 'ok') + setEditing(false) await refresh() } catch (e: any) { - // 400 里是"缺 OPENAI_API_KEY"这类能照着做的原因,原样交给用户 + // 400 里写的是"连不上哪个地址""哪个模型名不对",都能照着做 toast(e?.message ?? '切换失败', 'error') } finally { setBusy(false) } } + const probe = async () => { + setBusy(true) + try { + const out = await api.kb.probeEmbedding(baseUrl) + setModels(out.models) + if (out.models.length === 1) setModel(out.models[0]) + if (!out.models.length) toast('这个地址上没有可用模型', 'error') + } catch (e: any) { + toast(e?.message ?? '连不上', 'error') + } finally { setBusy(false) } + } + const rebuild = async () => { setBusy(true) try { @@ -90,17 +115,14 @@ function EmbedderBar({ collection, onChanged }: {
向量模型 - - {info.embedder} · {info.dim} 维 + {info.embedder} · {info.dim} 维 + {info.kind === 'local' && ( + 没有语义能力 + )} + {stale > 0 && ( )}
+ {editing && ( +
+ + +
+
+ 自定义端点 — 任何讲 OpenAI /v1/embeddings 的服务:本机的 LM Studio、 + Ollama、vLLM、TEI,或你自己的网关 +
+
+ setBaseUrl(e.target.value)} /> + {/* 模型名手填太容易错:LM Studio 里叫 text-embedding-qwen3-embedding-4b, + 不是 Qwen3-Embedding-4B。填错的表现是切换时 404,人还以为服务没起 */} + +
+ {!!models.length && ( +
+ + +
+ )} +

+ 留空地址则走 api.openai.com(要 OPENAI_API_KEY,按量计费)。 + 换模型后维度多半会变,存量向量要重建一次。 +

+
+
+ )} + {staleChunks + staleMemories > 0 && (

有{staleChunks ? ` ${staleChunks} 段知识` : ''} diff --git a/scripts/check-ui.mjs b/scripts/check-ui.mjs index 3488bfcc..87cc9a26 100644 --- a/scripts/check-ui.mjs +++ b/scripts/check-ui.mjs @@ -200,6 +200,35 @@ console.log('\n=== 问数据 ===') await page.close() } +console.log('\n=== 向量模型设置 ===') +{ + // 以前这里只有三个写死的选项(本地 / OpenAI 3-small / 3-large),接不了 + // 本机起的服务。而本地哈希向量没有语义能力这件事,界面上也得说出来。 + const { page, errors } = await visit('/knowledge') + check('没有运行时报错', errors.length === 0, errors.slice(0, 2).join(' | ')) + + let body = await page.locator('body').innerText() + check('显示当前用的是什么、几维', /·\s*\d+\s*维/.test(body), + body.match(/[\w:.-]+ · \d+ 维/)?.[0]) + if (body.includes('local-hashing')) { + check('本地哈希要标出没有语义能力', body.includes('没有语义能力')) + } + + await page.getByRole('button', { name: '换一个' }).first().click() + await page.waitForTimeout(400) + body = await page.locator('body').innerText() + check('能配自定义端点', body.includes('自定义端点')) + check('也留着本地那一项', body.includes('本地哈希向量')) + // 模型名手填太容易错,必须能探 + check('给得出探测入口', body.includes('看看有哪些模型')) + + const overflow = await page.evaluate(() => + document.documentElement.scrollWidth - document.documentElement.clientWidth) + check('页面不横向溢出', overflow <= 0, `${overflow}px`) + await shot(page, 'embedding') + await page.close() +} + console.log('\n=== 会话 ===') { // 对话以前只活在内存里,刷新就没了。这一组守的是它真的落了库: