设置页能接本机的向量模型了,不用改代码

上一版只有三个写死的选项:本地哈希 / OpenAI 3-small / 3-large。想用本机起的
LM Studio、Ollama、vLLM,只能去代码里调 configure——等于没有。

现在可以填任意 base_url。配套加了一个探测接口(GET /kb/embedding/probe),
按地址列出那台服务上有哪些模型,从列表里选。模型名手填太容易错——LM Studio
里叫 text-embedding-qwen3-embedding-4b,不是 Qwen3-Embedding-4B,而填错的
表现是切换时 404,人还以为是服务没起。

base_url 跟着落库。不存的话重启后会悄悄退回本地哈希,而库里的向量是上一个
模型建的,检索整体退回关键词——用户只看到"重启之后搜得不准了"。

几处说给用户听的:
- 当前用的是什么、几维,直接显示在最上面
- 本地哈希旁边标"没有语义能力"——它是默认值,而这个缺陷不说没人会发现
- 切换成功的提示里带上新维度和"多少条存量向量需要重建"。换模型后维度多半
  变了,存量全部作废,这件事要当场说,不能等人发现搜不准了再去猜

check-ui 加了一节,真浏览器里验过:展开、填地址、探测到本机的
text-embedding-qwen3-embedding-4b、出现「用它」。
This commit is contained in:
ThearchyHelios
2026-09-20 09:34:55 +08:00
parent 1e9f32b869
commit 11780ed0b4
5 changed files with 209 additions and 22 deletions
+27 -2
View File
@@ -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)
+66
View File
@@ -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
+10 -4
View File
@@ -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}` : ''}`),
+77 -16
View File
@@ -46,8 +46,16 @@ function EmbedderBar({ collection, onChanged }: {
const toast = useToast()
const [info, setInfo] = useState<any>(null)
const [busy, setBusy] = useState(false)
const [editing, setEditing] = useState(false)
const [baseUrl, setBaseUrl] = useState('')
const [models, setModels] = useState<string[]>([])
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 }: {
<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="mono text-[11px]">{info.embedder} · {info.dim} 维</span>
{info.kind === 'local' && (
<span className="text-[10.5px]" style={{ color: 'var(--warn)' }}>没有语义能力</span>
)}
<button className="btn btn-sm btn-ghost" disabled={busy}
onClick={() => setEditing((v) => !v)}>
{editing ? '收起' : '换一个'}
</button>
<span className="flex-1" />
{stale > 0 && (
<button className="btn btn-sm btn-primary" disabled={busy} onClick={rebuild}>
@@ -108,6 +130,45 @@ function EmbedderBar({ collection, onChanged }: {
</button>
)}
</div>
{editing && (
<div className="mt-3 space-y-2 border-t pt-3">
<button className="btn btn-sm w-full justify-start" disabled={busy}
onClick={() => void pick('local')}>
本地哈希向量 — 零配置、不联网、免费,但只认字面不认语义
</button>
<div className="rounded-lg border p-2">
<div className="mb-1.5 text-[11px] text-faint">
自定义端点 — 任何讲 OpenAI /v1/embeddings 的服务:本机的 LM Studio、
Ollama、vLLM、TEI,或你自己的网关
</div>
<div className="flex flex-wrap items-center gap-1.5">
<input className="field h-7 flex-1" placeholder="http://127.0.0.1:1234/v1"
value={baseUrl} disabled={busy}
onChange={(e) => setBaseUrl(e.target.value)} />
{/* 模型名手填太容易错:LM Studio 里叫 text-embedding-qwen3-embedding-4b,
不是 Qwen3-Embedding-4B。填错的表现是切换时 404,人还以为服务没起 */}
<button className="btn btn-sm" disabled={busy || !baseUrl.trim()}
onClick={() => void probe()}>看看有哪些模型</button>
</div>
{!!models.length && (
<div className="mt-1.5 flex flex-wrap items-center gap-1.5">
<select className="field h-7 flex-1" value={model} disabled={busy}
onChange={(e) => setModel(e.target.value)}>
{models.map((m) => <option key={m} value={m}>{m}</option>)}
</select>
<button className="btn btn-sm btn-primary" disabled={busy || !model}
onClick={() => void pick('openai', model, baseUrl)}>用它</button>
</div>
)}
<p className="mt-1.5 text-[10.5px] text-faint">
留空地址则走 api.openai.com(要 OPENAI_API_KEY,按量计费)。
换模型后维度多半会变,存量向量要重建一次。
</p>
</div>
</div>
)}
{staleChunks + staleMemories > 0 && (
<p className="mt-2 text-[11px]" style={{ color: 'var(--warn)' }}>
有{staleChunks ? ` ${staleChunks} 段知识` : ''}
+29
View File
@@ -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=== 会话 ===')
{
// 对话以前只活在内存里,刷新就没了。这一组守的是它真的落了库: