embedding 能接本地端点了:维度改成探测,不再按模型名猜

在本机 LM Studio 上接 Qwen3-Embedding-4B 时撞出来的两个兼容问题。

**维度不能猜。** 原来是"名字里有 3-large 就 3072,否则一律 1536"。本地部署的
模型五花八门——bge-m3 是 1024、Qwen3-Embedding-4B 是 2560——猜错的后果不是
差一点,是所有存量向量都被判成"和当前 embedder 对不上",检索整体退回关键词。
改成建 embedder 时实际探一次。

**langchain 默认发的是 token 数组。** 它先把文本分词,再把 token id 数组发过去,
OpenAI 官方认,LM Studio 这类本地服务只收字符串,直接 400:

    'input' field must be a string or an array of strings

自定义 base_url 时关掉这个行为发原文。我们的片段都在 800 字上下,本来也用不着
那套长度保护。顺带设了 chunk_size=512——远端接口单次批量有上限,不分块的话
大文档必挂。

报错也改了:原来只说"检查 OPENAI_API_KEY",现在带上试的是哪个地址、哪个模型
——本地服务没起的话,照着旧文案去翻 key 是白费功夫。

实测 Qwen3-Embedding-4B(2560 维)对比本地哈希向量:

            hit@1  hit@5   MRR    字面    语义    入库    每查
    哈希      88%   100%  0.911   100%    75%    0.2s   0.00s
    Qwen3    94%   100%  0.958   100%    88%    3.4s   0.09s

涨的全在语义类,字面类没被搞坏。has_semantics() 转真后 alpha 默认从 0 自动
回到 0.5,不用手调。

一个没料到的结果:纯向量(alpha=1)只有 81%,比纯关键词(alpha=0)的 88% 还低,
混合(0.5)才是 94%。专有名词靠 BM25、换了说法靠向量,两边各管一半——混合
检索在这份语料上是真有必要,不是摆设。

样本只有 16 题,差一题就是 6 个百分点,别把 94% 当结论;方向是明确的。
This commit is contained in:
ThearchyHelios
2026-09-20 09:31:00 +08:00
parent 901d840b86
commit 1e9f32b869
2 changed files with 113 additions and 16 deletions
+34 -16
View File
@@ -4,7 +4,7 @@ import hashlib
import math
import os
import re
from typing import Sequence
from typing import Any, Sequence
import numpy as np
@@ -53,7 +53,8 @@ class LocalEmbedder:
class OpenAIEmbedder:
"""配了 key 就用真 embedding 模型,检索质量明显更好。"""
"""任何讲 OpenAI /v1/embeddings 的服务:官方 API、也可以是本地起的
LM Studio / Ollama / vLLM / TEI。区别只在 base_url。"""
name = "openai"
@@ -62,13 +63,26 @@ class OpenAIEmbedder:
from langchain_openai import OpenAIEmbeddings
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"),
base_url=base_url,
)
self.base_url = base_url
kwargs: dict[str, Any] = {
"model": model,
# 本地服务通常不校验 key,但 SDK 要求非空
"api_key": api_key or os.environ.get("OPENAI_API_KEY") or "not-needed",
"base_url": base_url,
# 远端接口单次批量有上限(OpenAI 是 2048),langchain 按这个分块发
"chunk_size": 512,
}
if base_url:
# langchain 默认先把文本分词、发 token 数组过去——OpenAI 官方认,
# 但 LM Studio 这类本地服务只收字符串,会报
# "'input' field must be a string or an array of strings"。
# 关掉之后发原文。我们的片段都在 800 字上下,也用不着那套长度保护
kwargs["check_embedding_ctx_length"] = False
self._impl = OpenAIEmbeddings(**kwargs)
# 维度必须问出来,不能按模型名猜。本地部署的模型五花八门——
# bge-m3 是 1024、Qwen3-Embedding-4B 是 2560,猜错的后果是所有存量
# 向量都被判成"和当前 embedder 对不上",检索整体退回关键词
self.dim = len(self._impl.embed_query("dim probe"))
async def aembed(self, text: str) -> np.ndarray:
vec = await self._impl.aembed_query(text)
@@ -92,26 +106,30 @@ class EmbedderUnavailable(RuntimeError):
"""配了远端 embedder 但建不起来。message 直接给用户看。"""
def _make(kind: str, model: str, *, strict: bool) -> "LocalEmbedder | OpenAIEmbedder":
def _make(kind: str, model: str, base_url: str = "", *,
strict: bool) -> "LocalEmbedder | OpenAIEmbedder":
if kind != "openai":
return _local
try:
return OpenAIEmbedder(model=model or "text-embedding-3-small")
return OpenAIEmbedder(model=model or "text-embedding-3-small",
base_url=base_url or None)
except Exception as e: # noqa: BLE001
if strict:
# 人明确选了远端就不能偷偷退回本地:他会以为自己在用语义检索,
# 而实际拿到的是哈希词袋——搜不出同义表达时完全无从怀疑到这里
where = base_url or "api.openai.com"
raise EmbedderUnavailable(
f"用不了 embedding 模型 {model or 'text-embedding-3-small'}:"
f"{type(e).__name__}: {e}。检查 OPENAI_API_KEY 是否配了。"
f"用不了 {where} 上的 embedding 模型 "
f"{model or 'text-embedding-3-small'}:{type(e).__name__}: {e}。"
f"检查服务在不在、模型名对不对;走官方接口还要看 OPENAI_API_KEY。"
) from e
return _local
def configure(kind: str, model: str = "") -> None:
def configure(kind: str, model: str = "", base_url: str = "") -> None:
"""切换当前 embedder。设置页保存后调用,也用于测试。建不起来会抛。"""
global _cached
_cached = (f"{kind}:{model}", _make(kind, model, strict=True))
_cached = (f"{kind}:{model}:{base_url}", _make(kind, model, base_url, strict=True))
def get_embedder() -> "LocalEmbedder | OpenAIEmbedder":
@@ -183,7 +201,7 @@ async def load_setting(session: Any) -> None:
saved = (row.value if row else {}) or {}
kind = saved.get("kind")
if kind:
configure(kind, saved.get("model", ""))
configure(kind, saved.get("model", ""), saved.get("base_url", ""))
async def embed_text(text: str) -> np.ndarray:
+79
View File
@@ -443,3 +443,82 @@ async def test_a_word_document_with_a_table_survives_the_whole_pipeline() -> Non
# 命中的片段里必须能看出这些数是什么
assert any("门店 | 城市 | 销售额" in h["content"] for h in hits), (
"召回的片段全都没有表头,拿回去也读不懂")
# --------------------------------------------------------------------------
# 自定义 embedding 端点
# --------------------------------------------------------------------------
def test_dimension_is_probed_not_guessed(monkeypatch) -> None:
"""维度必须问出来。
原来是按模型名猜:名字里有 3-large 就 3072,否则一律 1536。本地部署的
模型五花八门——bge-m3 是 1024、Qwen3-Embedding-4B 是 2560——猜错的后果是
所有存量向量都被判成"和当前 embedder 对不上",检索整体退回关键词。
"""
from app.memory import embeddings as e
probed: list[str] = []
class _Fake:
def __init__(self, **kw):
self.kw = kw
def embed_query(self, text):
probed.append(text)
return [0.0] * 2560 # 假装是个 2560 维的本地模型
import langchain_openai
monkeypatch.setattr(langchain_openai, "OpenAIEmbeddings", _Fake)
emb_obj = e.OpenAIEmbedder(model="my-local-model", base_url="http://127.0.0.1:1234/v1")
assert emb_obj.dim == 2560, "维度没去问,还在按名字猜"
assert probed, "根本没探测"
def test_a_custom_endpoint_gets_plain_strings(monkeypatch) -> None:
"""langchain 默认先分词、把 token 数组发过去。
OpenAI 官方认,但 LM Studio 这类本地服务只收字符串,会直接 400:
'input' field must be a string or an array of strings
"""
from app.memory import embeddings as e
captured: dict = {}
class _Fake:
def __init__(self, **kw):
captured.update(kw)
def embed_query(self, _t):
return [0.0] * 8
import langchain_openai
monkeypatch.setattr(langchain_openai, "OpenAIEmbeddings", _Fake)
e.OpenAIEmbedder(model="m", base_url="http://127.0.0.1:1234/v1")
assert captured.get("check_embedding_ctx_length") is False
assert captured.get("base_url") == "http://127.0.0.1:1234/v1"
# 批量上限:远端接口单次有上限,不分块的话大文档必挂
assert captured.get("chunk_size")
captured.clear()
e.OpenAIEmbedder(model="text-embedding-3-small") # 官方接口走默认行为
assert "check_embedding_ctx_length" not in captured
def test_a_broken_endpoint_names_where_it_tried(monkeypatch) -> None:
"""报错要说清楚是哪个地址上的哪个模型,否则本地服务没起都不知道去哪查。"""
from app.memory import embeddings as e
class _Boom:
def __init__(self, **kw):
raise RuntimeError("connection refused")
import langchain_openai
monkeypatch.setattr(langchain_openai, "OpenAIEmbeddings", _Boom)
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)