向量检索踩坑完全指南:从一次"换了个 embedding 模型、整个知识库检索全乱套"看懂向量空间不兼容

2023 年我做一个企业知识库问答系统(RAG):用户问一句,系统先把问题转成向量,去向量库里检索出几篇最相关的文档,再喂给大模型生成回答。第一版我选了一个 embedding 模型,把几十万篇文档全 embed 进了向量库,上线后效果还不错。可过了一阵,我看到一个"评测分数更高"的新 embedding 模型,就想升级。换 embedding 模型这件事,我压根没多想。我心里很省事地想:embedding 模型不就是个"把文字转成向量"的工具?换个效果更好的,把代码里的模型名一改、接上去,不就行了?我把调用处的 model 参数从旧的改成新的,就完事了。本地开发时——真不错:我拿一小批文档测了测,换模型后重新 embed 了这批,检索看着挺正常。我心里很踏实:"embedding 模型嘛,换个名字的事?"可等这个升级真正推到线上、面对那几十万篇老文档,一串问题冒了出来。第一种最先把我打懵:换上新模型后,用户问的问题,召回的全是风马牛不相及的文档,问答质量断崖式下跌。第二种最难缠:新模型输出的是 1536 维的向量,老库里存的是 768 维的——向量根本写不进去,维度直接报错。第三种最头疼:我想"那就新老一起用"——新文档用新模型、老文档保留旧向量,结果同一个库里检索时好时坏、毫无规律。第四种最莫名其妙:我在本地怎么测都正常——后来才反应过来,本地那一小批文档,是我换模型后重新 embed 过的。我盯着这一连串问题想了很久才彻底想明白,第一版错在一个根本的认知上:我以为"embedding 模型就是个把文字转成向量的通用工具,可以随便替换"。这句话把不同的 embedding 模型,当成了几个可以互换的、输出格式相同的函数。可它们不是。我脑子里,"文字转向量"就像"把摄氏度转成华氏度"——是一个有标准答案的、客观的转换,换哪个模型来做,结果都该是通用的、可比的。可 embedding 根本不是这种东西。一个 embedding 模型做的事,是把一段文本,映射成它自己专属的那个高维空间里的一个点。关键就在"它自己专属"这五个字上:每个模型,都有一套只属于它自己的、和别的模型完全不相通的坐标系。同一句话,A 模型把它放在自己空间里的某个位置,B 模型把它放在自己空间里的另一个位置——这两个位置的数值,彼此之间没有任何可比性,就像一个城市的"经纬度"和它的"邮政编码",都是在定位它,但你绝不能拿经纬度去和邮政编码做减法。而向量检索的本质,恰恰是"在同一个空间里,比较两个点离得近不近"。所以,一个向量库里存的向量,是和算出它们的那个特定模型、特定版本死死绑定的;查询的向量,也必须由同一个模型算出来,才能和库里的向量在同一个坐标系里量距离。我第一版所有的麻烦,根上都是同一件事:我用 B 模型的尺子,去量了一个全是 A 模型刻度的世界。真正用对 embedding,核心不是"换个更好的模型、改个名字接上去",而是把"向量"和"算出它的模型版本"当作一个死死绑定、不可拆分的整体来对待:换模型意味着旧库里的向量全部作废,你必须用新模型把整个语料重新 embed、重建索引,而且查询向量与库向量必须永远同源。这篇文章就把向量检索的这个坑梳理一遍:为什么"换个模型就行"是错的、怎么把向量和模型版本绑定、为什么换模型等于全量重建、怎么做平滑迁移、查询为什么必须和库同源,以及维度校验、断点续传这些把向量检索做扎实要避开的坑。

问题背景

先把那串问题的现象和我的误判讲清楚,后面所有的设计都是冲着纠正这个误判去的。

现象:一套"换个更好的 embedding 模型、改个名字就接上"的 RAG 系统,在升级推到线上后冒出一串问题:换上新模型,用户提问召回的全是不相关文档,问答质量断崖下跌;新模型 1536 维、老库 768 维,向量根本写不进去;想着新老向量混在一个库里用,检索时好时坏;而这一切在本地拿一小批"已重新 embed 过的"文档测,完全看不出来。

我当时的错误认知:"embedding 模型就是个把文字转成向量的通用工具,换个更好的,改个模型名接上就行。"

真相:这个认知错在它把"文字转向量"想象成了一种有标准答案的、客观的转换——就像摄氏度转华氏度,换哪个模型做,结果都通用、都可比。可 embedding 完全不是这种东西。一个 embedding 模型,是把文本映射到它自己专属的那个高维空间里的一个点。每个模型都有一套只属于它自己、和别的模型完全不相通的坐标系。同一句话,A 模型放在自己空间的某处,B 模型放在自己空间的另一处,两个位置的数值彼此没有任何可比性——就像一个地点的经纬度和它的邮政编码,你不能拿来做减法。而向量检索的本质,是在同一个空间里比较两个点的距离。开头那四个问题,根上全是"用 B 模型的尺子,去量一个全是 A 模型刻度的世界":召回全乱,是因为新模型算的查询向量,和旧模型算的库向量根本不在一个空间;维度报错,是因为不同模型连向量的长度都不一样;新老混用时好时坏,是因为同一个库里掺了两套坐标系的向量;本地测不出,是因为那一小批文档恰好是我用新模型重新 embed 过的、自己和自己同源。问题的根子清楚了:这不是"模型不够好"的小毛病,而是要换一个根本的认知——向量和算出它的模型版本是死死绑定的,换模型就是整个向量库作废、必须全量重建。

要把向量检索的这个坑处理对,需要几块认知:

• 为什么"换个模型就行"是错的——每个模型有自己专属、不相通的向量空间;
• 把向量和模型版本绑定——每条向量都要记清楚它是哪个模型算的;
• 换模型等于全量重建——不是增量替换,是整库重做;
• 平滑迁移——新索引在旁边单独建好,验过了再原子切换;
• 查询向量与库向量必须同源——用同一个模型算;
• 维度校验、断点续传这些工程坑怎么处理。

一、为什么"换个 embedding 模型就行"是错的

先把这件最根本的事钉死:"换个 embedding 模型就行"错在它脑子里有一幅错误的图景——它把"文字转向量"想象成了一种像单位换算那样客观、通用的转换。在这幅图景里,文本和向量之间有一种标准的对应关系,embedding 模型只是执行这个换算的工具,这个模型和那个模型,无非是换算得"准不准""好不好",但算出来的向量本身是通用的、可比的,就像不管用哪个牌子的温度计,30 摄氏度就是 30 摄氏度。这幅图景之所以危险,是因为它彻底误解了 embedding 这件事的本质。embedding 不是"换算",而是"安放"。要理解这一点,得想清楚一个 embedding 模型在做什么:它在训练过程中,凭着自己见过的海量语料,为自己构建了一个高维的语义空间,然后学会了一件事——把任意一段文本,安放到这个空间里的某个位置上,让意思相近的文本被放得彼此靠近,意思无关的文本被放得很远。注意,这个空间是模型在训练中自己长出来的,它的每一个维度代表什么、坐标原点在哪、不同语义朝哪个方向展开,完全是这个模型私有的、内部的约定。另一个模型,哪怕它也叫 embedding 模型、也输出向量,它训练出来的是另一个完全独立的空间,有另一套私有的约定。于是同一句"今天天气真好",A 模型把它安放在 A 空间的某个坐标,B 模型把它安放在 B 空间的某个坐标——这两串数字,长得都像向量,但它们是两个不同宇宙里的地址,彼此之间做任何比较、任何距离计算,都是没有意义的。这就好比经纬度和邮政编码:它们都能定位北京,但"北京的经纬度"减去"上海的邮政编码"是一个纯粹的乱码。而向量检索——也就是 RAG 的召回这一步——它的全部运作,就建立在"距离"上:把用户问题的向量,和库里每篇文档的向量,逐一算距离,挑出最近的几个。这个"算距离"的动作,有一个铁一般的前提:被比较的两个向量,必须出自同一个空间、同一套坐标系。一旦你用 B 模型算查询向量,去和 A 模型算的库向量比距离,你算出来的那个"距离",就是经纬度减邮政编码式的乱码,挑出来的"最相关文档",自然全是风马牛不相及的东西。所以正确的图景是:embedding 模型不是通用的换算器,而是各自拥有一个私有空间的"安放者";向量不是通用的、可比的数据,而是死死绑定在某一个特定空间里的坐标。把"模型只是个转换工具、向量是通用的"换成"每个模型有自己专属的空间、向量和这个空间不可分割",你才算站到了用对向量检索的起点上。

下面这段代码,就是我那个"本地测一小批没事、上线对着老库全乱"的第一版升级:

# 反面教材:换了新模型算查询向量,却去查一个用旧模型建好的向量库
def search(query):
    # 升级时,我只把这里的模型名从 v1 改成了 v2
    query_vec = embed(query, model="text-embedding-v2")   # 新模型 v2 算的查询向量
    # 可 vector_store 里的向量,全是当初用旧模型 v1 算出来写进去的
    return vector_store.search(query_vec, top_k=5)        # 破绽:v2 的尺子,量 v1 的世界

这段升级在本地开发时表现不错,因为本地我测的那批文档,其实是"自己和自己同源"的——为了测试,我临时建了一个小向量库,把那一小批文档用新模型 v2 重新 embed 后写了进去。于是本地这个小库里,装的是 v2 的向量;我查询时,embed(query, model="text-embedding-v2") 算的也是 v2 的向量。查询和库,恰好都出自 v2 这同一个空间,距离算得有意义,检索恰好正常。我亲手布置了一个"新旧不混"的舞台,把那个致命的错配完美地藏了起来。升级恰好一路平安,你看不出任何破绽。它的问题不在某一行语法上——embed()、vector_store.search(),语法都对——而在它对"查询向量和库向量是不是同源",做了一个想当然的假设:它假设只要算出一个向量,就能拿去查任何库。它从没意识到库里的向量是和某个特定模型绑定的。本地我测的小库恰好也是 v2 建的,这个假设恰好成立;一上线、面对那个装着几十万篇 v1 向量的真实大库,假设就被击穿,v2 的查询向量去量 v1 的库,召回全乱。问题的根子清楚了:用对向量检索,第一步不是去追更高分的模型,而是承认"向量和算它的模型版本是死死绑定的",然后把这个绑定关系老老实实管起来。下面五节,就是这件事怎么落地。

二、把向量和模型版本绑定起来

纠正误判的第一步,是让每一条向量,都带着"我是谁算出来的"这个身份。一条向量不能是一串裸的数字——它要记清楚自己是哪个模型、哪个版本算出来的,维度是多少:

from dataclasses import dataclass

@dataclass
class VectorRecord:
    doc_id: str           # 这条向量对应哪篇文档
    vector: list          # 文本被映射成的那个向量
    model: str            # 关键:这条向量是哪个模型、哪个版本算出来的
    dim: int              # 向量维度 —— 不同模型可能根本不一样

有了这个身份,查询之前就能先验一道:查询用的模型,和这个库是哪个模型建的,对得上才让查:

def check_compatible(query_model, index_meta):
    """查询前先验身份:查询向量和库向量必须出自同一个模型,否则距离没意义。"""
    if query_model != index_meta["model"]:
        raise ValueError(
            f"模型不一致:查询用 {query_model},"
            f"但这个库是 {index_meta['model']} 建的 —— 两套空间,不能比")
    return True

这里的认知要点是:这一节要建立的观念是——一条向量,绝不应该是一串脱离了上下文的、裸的浮点数字;它必须随身携带"产地信息"。上一节讲清了向量和模型空间的死绑定关系,但光在脑子里知道还不够,这个绑定关系必须在数据结构上被显式地记录下来,否则它就是一个随时会被忘掉的隐性约定。第一版的错,某种意义上就是"忘了"——升级的时候,我眼里只有 vector_store 里那一堆数字,它们看上去和新模型算的数字没什么两样,我完全没意识到它们身上烙着 v1 的印记。如果当初每条向量都明明白白写着"我是 text-embedding-v1 算的、768 维",我在改模型名的那一刻,就该警觉:库里全是 v1,我查询却要用 v2。所以 VectorRecord 这个结构,把 model 和 dim 和向量本身绑在了一起,它要表达的就是:向量这个数据,是不能脱离"哪个模型、多少维"这两个属性单独存在的,它们是一个不可分割的整体。这背后是一个通用的工程观念:当一份数据的正确解读,依赖于某个外部的上下文(这里是模型版本),那就绝不能把数据和这个上下文分开存储——要么把上下文作为元信息和数据存在一起,要么数据本身就毫无意义、甚至有害。再说 check_compatible。光给数据打上标签还不够,标签是用来"被检查"的。check_compatible 做的事,就是在每一次查询真正发生之前,拿查询所用的模型,和这个索引的元信息里记录的模型,做一次硬碰硬的比对——一致才放行,不一致就当场抛错。这一道检查的价值在于,它把"两套空间不能比"这条物理规律,从一个"我必须时刻记着的注意事项",变成了一道"代码会自动帮我守住的关卡"。第一版的悲剧是错配悄无声息地发生、最后以"召回质量下跌"这种模糊的方式暴露;有了 check_compatible,同样的错配会在第一时间、以一个清晰的异常炸出来,根本走不到线上。一句话:每条向量都要带上'哪个模型、多少维'的身份,并在查询前用一道检查,硬性挡住模型不一致的错配。身份和检查都有了,可还有个更上游的问题——既然换模型会让旧向量全部作废,那换模型这件事本身,到底意味着多大的工程量。

三、换模型 = 全量重建,不是增量替换

认清了"向量和模型死绑定",一个硬邦邦的结论就摆在面前:换 embedding 模型,等于把整个向量库作废、用新模型从头重建。它不是一次"增量替换"(改个配置、新数据用新模型),而是一次"整库重做"——每一篇文档,都要用新模型重新 embed 一遍:

def rebuild_index(all_docs, new_model):
    """换 embedding 模型 = 全量重建:每一篇文档,都要用新模型重新算一遍向量。"""
    new_index = vector_store.create_collection(
        name=f"docs_{new_model}",                # 新模型,新集合,和旧的分开
        dim=model_dim(new_model),                # 新模型的维度,可能和旧的不同
    )
    for doc in all_docs:
        vec = embed(doc.text, model=new_model)   # 用新模型,把这篇文档重新 embed
        new_index.add(VectorRecord(doc.id, vec, new_model, len(vec)))
    return new_index

而且不同模型连向量的长度都未必一样。写入前要挡一道维度校验——维度对不上的向量,根本不该进这个库:

def add_vector(index, record, expected_dim):
    """写入前挡一道:维度对不上,说明这条向量压根不属于这个库。"""
    if record.dim != expected_dim:
        raise ValueError(
            f"维度不匹配:这条向量是 {record.dim} 维,"
            f"但这个库要求 {expected_dim} 维")
    index.add(record)

下面这张图,把要换一个 embedding 模型,该怎么走画出来:

这里的认知要点是:这一节要把一个让人不舒服、但必须接受的结论钉死——换 embedding 模型是一个"重"操作,它的成本和你重新搭建一遍检索底座差不多,绝不是改个配置那么轻。很多人在升级 embedding 模型时,脑子里的模型是"增量替换":我改个配置,从今往后新进来的文档用新模型 embed,老文档保持不动,系统平滑过渡。这个想法,正是第一版第三个问题——"新老混用、检索时好时坏"——的来源。为什么增量替换在这里行不通?因为前两节已经讲透了:新模型和旧模型的向量处在两个不相通的空间。如果你让新文档用新模型、老文档留旧向量,那你的向量库里就同时躺着两套坐标系的向量。用户来查询,你的查询向量只能属于其中一个空间,于是它能和一半的库正确地比距离,和另一半的库比出的全是乱码——检索结果"时好时坏",好坏取决于正确答案这次恰好落在新向量还是旧向量里。这是一个根本无法稳定工作的状态。所以唯一正确的做法,就是 rebuild_index 所体现的:换模型,就老老实实把语料库里的每一篇文档,都用新模型重新 embed 一遍,建一个全新的、纯净的、只含新模型向量的索引。这里有两个点要特别说。第一,新索引要用一个新的集合,和旧的物理隔开,而不是往旧集合里覆盖写——原因下一节讲,这关系到迁移的安全。第二,不同模型的向量维度常常不同(768、1024、1536 都常见),这意味着新索引的维度参数本身就要跟着新模型变,而且一个 768 维的库,你强行往里塞 1536 维的向量,连数据结构层面都会直接报错。add_vector 里那道维度校验,就是把这个错配挡在写入的入口——维度是向量身份里最硬、最容易自动检查的一项,对不上就拒绝,绝不让一条不属于这个库的向量混进去。理解了"换模型 = 全量重建"这个成本,你在做模型选型决策时也会更清醒:升级 embedding 模型不是一个能随手做的小优化,它是一次需要规划重建窗口、重建算力、重建成本的工程项目。一句话:换 embedding 模型必然意味着用新模型全量重建整个索引,增量替换会让两套空间的向量混在一起、检索彻底不可靠。知道了要全量重建,可重建要花很长时间,这期间线上服务不能停——这就需要一套平滑迁移的办法。

四、平滑迁移:双索引并行,验过再原子切换

全量重建几十万篇文档,可能要跑好几个小时。这期间线上的问答不能停。办法是双索引并行:新索引在旧索引旁边单独建,建的过程中,线上查询照常走旧索引,用户完全无感:

def build_alongside(all_docs, old_index_name, new_model):
    """平滑迁移:新索引在旧索引旁边单独建,期间旧索引照常服务、用户无感。"""
    new_index = rebuild_index(all_docs, new_model)   # 后台慢慢建新的,几个小时也没关系
    # 整个重建期间,线上查询仍然走 old_index_name,丝毫不受影响
    return new_index                                  # 建完,等着被校验、被切换

新索引建好后,不能直接切——要先用一组人工标注的"标准问题"校验它:每个问题该召回哪篇文档是已知的,新索引召得回来,才算合格:

def validate_index(index_name, model):
    """切换前校验:用新索引自己的模型,embed 一组标准问题,看能否召回正确文档。"""
    index = vector_store.get(index_name)
    for query, expected_doc_id in GOLDEN_QUERIES:    # 一组人工标注好的"标准答案"
        query_vec = embed(query, model=model)        # 必须用新索引自己的模型来 embed
        hits = index.search(query_vec, top_k=5)
        if expected_doc_id not in [h.doc_id for h in hits]:
            return False                             # 有一个标准问题召不回,就不合格
    return True

校验通过,切换才发生。而切换的动作,要做成原子的一下——改一个"当前激活哪个索引"的指针,而不是去原地修改旧索引:

# 用一个指针,决定线上查询此刻该走哪个索引
ACTIVE_INDEX = {"name": "docs_text-embedding-v1", "model": "text-embedding-v1"}

def switch_to(new_name, new_model):
    """切换:新索引校验通过后,一次性把指针指过去 —— 切换是原子的一下。"""
    if not validate_index(new_name, new_model):
        raise RuntimeError("新索引校验未通过,取消切换,继续用旧索引")
    ACTIVE_INDEX["name"] = new_name                  # 原子地换指针
    ACTIVE_INDEX["model"] = new_model                # 模型也跟着一起换

这里的认知要点是:这一节要想清楚的是,一个"重建"类的操作,该用什么姿势上线才安全。最朴素、也最危险的姿势,是"原地替换"——直接在那个正在服务线上的向量库上动手,把旧向量一条条删掉、换成新向量。这个姿势有两个致命问题。第一,重建要花好几个小时,在这几个小时里,你的库处于一个"半新半旧"的中间态,前面刚说过,半新半旧的库检索是彻底不可靠的——也就是说,原地替换会让你的线上服务,实打实地烂掉好几个小时。第二,万一新模型换上去效果还不如旧的,你已经把旧向量删光了,根本退不回去。正确的姿势,是 build_alongside、validate_index、switch_to 这三步体现的一套思路,它的名字可以叫"造好了再切",而不是"边用边改"。第一步,新索引在一个全新的、和旧索引物理隔离的集合里,从零开始慢慢建。这个过程不管花多久,旧索引都原封不动地在线上服务,用户感知不到任何变化。第二步,新索引建完后,它还只是个"候选",要先过一道校验关。校验的办法,是事先准备一组标准问题——每个问题正确答案该是哪篇文档,是人工确认过的;让新索引来回答这组问题,它能稳定地把正确文档召回来,才证明这个新索引是健康的、可用的。这一步是在用一个客观的标尺,回答"切过去到底会变好还是变坏"。第三步,也是最关键的一步:切换本身,必须是一个原子动作。代码里用了一个 ACTIVE_INDEX 指针来表示"线上此刻走哪个索引",切换就是修改这个指针——一瞬间完成,要么指着旧的,要么指着新的,绝不存在"切了一半"的中间态。这就把切换的风险压到了最低:切换前线上是完整的旧索引,切换后线上是完整的新索引,中间没有任何一刻是坏的。而且因为旧索引在切换后并没有被销毁,万一发现新索引有问题,把指针指回去就是瞬间回滚。这套"双轨并行、造好验过、原子切换、保留旧轨可回滚"的思路,不是向量检索独有的——它和数据库的不停机迁移、服务的蓝绿部署,是同一套工程智慧。一句话:重建类操作要用'新的在旁边单独造、用标准问题集验过、再用一个指针原子切换'的姿势,旧的留着随时可回滚。迁移的姿势对了,可还有一个最容易被忽略的细节——切换之后,查询那一端也得跟着变。

五、查询向量与库向量必须永远同源

切换索引时,有个细节极易遗漏:你换了库,算查询向量用的模型,也必须跟着换。第一版反面教材的病根就在这——查询用的模型被写死了。正确的做法是:算查询向量用哪个模型,永远跟着当前激活的索引走,而不是写死:

def search_safe(query):
    """查询向量,永远用'当前激活索引'的同一个模型来算 —— 保证和库同源。"""
    model = ACTIVE_INDEX["model"]                    # 不写死模型!跟着激活索引走
    query_vec = embed(query, model=model)            # 用和库完全相同的模型算查询向量
    index = vector_store.get(ACTIVE_INDEX["name"])
    check_compatible(model, {"model": ACTIVE_INDEX["model"]})  # 再硬验一道
    return index.search(query_vec, top_k=5)

这里的认知要点是:这一节要焊死的观念是——"查询向量"和"库向量"必须出自同一个模型,这个"同源"约束,是向量检索能正常工作的物理前提,你的代码结构必须保证它在任何时候都不被打破。回头看第一版反面教材那行 embed(query, model="text-embedding-v2"),它最致命的地方,不是用了 v2,而是把模型名"写死"在了查询代码里。写死意味着什么?意味着"用什么模型算查询向量"这个决定,和"库是用什么模型建的"这个事实,变成了两件各管各的、毫无关联的事。它们一旦分了家,就一定会在某个时刻不同步——升级时你改了查询端、忘了库,或者改了库、忘了查询端,错配就发生了。要根治它,办法不是"改的时候小心一点",而是从结构上消灭"两处分别配置"这件事本身:让"库"和"查询用的模型"这两个信息,只有一个唯一的来源。search_safe 就是这么做的——它不接受任何写死的模型名,它要用的模型,是从 ACTIVE_INDEX 这个"当前激活索引"里现取的。ACTIVE_INDEX 同时记着"现在用哪个库"和"这个库是哪个模型建的",这两个信息被绑在了一起、同进同出。于是当上一节的 switch_to 把指针切到新索引时,它顺手就把模型也改了;search_safe 下一次查询,自然就用上了新模型。库变了,查询用的模型一定跟着变,因为它们本就是从同一个地方读出来的——同源,成了一件代码结构上自动成立的事,而不是一件靠人记着的事。代码里末尾还多调了一次 check_compatible 做硬验证,这是第二节那道关卡的复用:即便结构上已经保证了同源,真正查询前再硬碰硬地核对一次,是廉价而值得的。这背后是一个通用的观念:两个必须保持一致的东西,不要让它们在两个地方各自被配置,而要让它们从同一个源头派生——一致性最可靠的保证,是让"不一致"在结构上就无法被表达出来。一句话:查询向量和库向量必须同源,做法是让查询用的模型跟着'当前激活索引'走,而不是写死在查询代码里。主干都齐了,最后是几个把向量检索迁移真正做到生产里才会撞见的工程坑。

六、工程坑:断点续传、成本、维度与多语言

主干之外,还有几个工程坑,不处理就会让你的迁移在边角上出问题。坑 1:全量重建要能断点续传。重建几十万篇文档要跑几个小时,中途万一断了(进程崩了、网络抖了),不能从头再来。要记录"已经 embed 到哪了",支持中断后接着跑:

def rebuild_with_checkpoint(all_docs, new_index, new_model):
    """全量重建要能断点续传:记录进度,中断后接着跑,而不是从头来。"""
    done = load_checkpoint(new_model)                # 已经重建完的 doc_id 集合
    for i, doc in enumerate(all_docs):
        if doc.id in done:
            continue                                 # 已完成的跳过 —— 这就是断点续传
        vec = embed(doc.text, model=new_model)
        new_index.add(VectorRecord(doc.id, vec, new_model, len(vec)))
        done.add(doc.id)
        if i % 1000 == 0:
            save_checkpoint(new_model, done)         # 每 1000 篇存一次档

坑 2:全量重建是要花钱的。几十万篇文档重新调一遍 embedding 接口,是一笔实实在在的 API 费用 + 算力。换模型前要把这笔重建成本估出来,别等账单来了才意外。坑 3:别忘了"增量进来的新文档"。重建跑了几个小时,这期间系统还在收新文档。这些新文档要记下来,等切换后用新模型补 embed 进新索引,否则它们会丢。坑 4:维度变了,周边代码可能跟着崩。有些地方可能硬编码了向量维度(比如建表、初始化数组)。换模型导致维度变化时,要全局排查这些写死的维度。坑 5:同一个模型也可能"偷偷升级"。有些 embedding 服务,模型名不变、底层却悄悄迭代了版本,新算的向量和你库里旧的已经不完全在一个空间。要优先选有明确版本号、可锁定的 embedding 服务。坑 6:查询向量和文档向量,有时要用不同的"指令"。有些 embedding 模型,embed 文档和 embed 查询要加不同的前缀指令(一个是"这是一篇文档",一个是"这是一个检索问题")。这不违反同源——还是同一个模型,但调用方式有别,别用错。坑 7:迁移后要做检索质量的 A/B 对比。"评测分数更高"不等于"在你的业务数据上更好"。切换前后,要用真实查询做一轮 A/B,确认新模型在你的场景里确实更优,再正式切。坑 8:向量库要定期校验"身份一致"。跑一个巡检,确认库里所有向量的 model 标签都一致、维度都正确——一旦发现混入了异类向量,尽早报警。

关键概念速查

避坑清单

1. 把每个 embedding 模型看作有自己专属空间,向量不能跨模型比较。
2. 每条向量都记清楚 model 与 dim,作为不可剥离的身份信息。
3. 查询前用一道检查,硬性挡住查询模型与库模型不一致的错配。
4. 换 embedding 模型就是全量重建,绝不做"新老向量混用"的增量替换。
5. 新索引用新集合单独建,和旧索引物理隔离,旧索引照常服务。
6. 切换前用人工标注的标准问题集校验新索引,验过了才切。
7. 切换做成原子动作:改激活指针,旧索引留着可瞬间回滚。
8. 查询用的模型不写死,跟着当前激活索引走,结构上保证同源。
9. 全量重建要能断点续传,并把重建期间新进的文档补 embed 进去。
10. 同名模型也可能偷偷升级,优先选版本号明确可锁定的服务。

总结

回头看那串"换新模型后召回全乱、维度报错写不进、新老混用时好时坏、本地却测不出"的问题,以及我后来在向量迁移上接连踩的坑,最该记住的不是某一个重建函数的写法,而是我动手前那个想当然的判断——"embedding 模型就是个把文字转成向量的通用工具,换个更好的、改个名字就行"。这句话错在它把"文字转向量"当成了一种像单位换算那样客观、通用的转换。我以为向量是通用的、可比的,换哪个模型算出来都能拿去查任何库。可我忽略了一件最要紧的事:embedding 不是"换算",而是"安放"——每个模型在训练里为自己长出了一个私有的语义空间,它把文本安放进这个只属于它自己的空间里的某个位置。不同模型的空间,是两个互不相通的宇宙,同一句话在两个空间里的坐标,彼此没有任何可比性,就像经纬度和邮政编码不能做减法。而向量检索的全部运作都建立在"距离"上,算距离的铁律是:被比较的两个向量必须出自同一个空间。我第一版的错,就是用 v2 模型的尺子,去量了一个全是 v1 刻度的世界——算出来的"距离"全是乱码,召回自然全乱。这个错配,本地开发时根本看不出来——因为本地我测的那一小批文档,是我用新模型重新 embed 过的,查询和库恰好都出自新模型这同一个空间,错配被完美藏住;它只会在真正上线、面对那个装着几十万篇旧模型向量的真实大库时,以召回质量断崖下跌的方式爆出来。

所以用对 embedding,真正的功夫不在"调用模型、算出向量"那几行上。调一个 embedding 接口本身不难。真正的功夫,在于你要从一开始就承认"向量和算出它的模型版本是死死绑定、不可拆分的",然后把这个绑定关系处处守住:你不能把向量当成一串通用的裸数字,就给每条向量都打上"哪个模型、多少维"的身份;你不能指望"改个模型名"就完成升级,就认下"换模型 = 用新模型全量重建整个索引"这个工程量;你不能让重建打断线上服务,就用双索引并行、新的在旁边单独造;你不能凭"评测分高"就贸然切换,就用一组标准问题把新索引校验过、再原子地切;你不能让查询和库不同源,就让查询用的模型永远跟着当前激活的索引走;而到了断点续传、维度排查、同名模型偷偷升级这些边角上,你还要处处守住,别让一条异类向量混进库里。这篇文章的几节,其实就是顺着这套规矩展开的:先想清楚"换个模型就行"为什么错,再讲把向量和模型绑定、换模型等于全量重建、双索引平滑迁移、查询必须同源,最后是断点续传、成本这几个把向量检索守扎实的工程细节。

你会发现,embedding 模型迁移这件事,和现实里"给一座城市换一套地址体系"完全相通。一个鲁莽的市政官员会怎么做?他听说有一套"更先进的地址体系",就下令立刻启用——可全城几十万户人家的门牌、所有的旧地址簿、所有人脑子里记的地址,还是老一套。新体系一上线,邮递员拿着新体系的地址,却对着满城的旧门牌,一个都对不上,整座城市的邮政瞬间瘫痪。而一个稳重的市政官员怎么做?他很清楚:换地址体系,不是发个文件那么简单,而是要把全城每一户的门牌都重新编一遍(这就是全量重建);他不会在旧体系还在用的时候就去拆门牌,而是先在内部把整套新地址悄悄编好、和旧的并行准备着(这就是双索引并行);新地址编完,他会先拿一批"已知的地点"试投一遍,确认新地址都能准确送达(这就是标准问题集校验);确认无误,才挑一个时点,全城同时启用新体系——而且旧地址簿留着,万一新体系出岔子还能切回去(这就是原子切换与可回滚);启用之后,他还会确保邮递员手里的地址簿,和居民门牌上的,永远是同一套(这就是查询与库同源)。同样是换一套地址,鲁莽的官员以为"换地址就是改个名",稳重的官员心里始终装着"地址是和门牌死绑定的、要换就得整座城一起换、还得平稳地换"——差别不在"启用新体系这个动作本身难不难",只在官员心里有没有"地址和门牌是一个不可分割的整体"这根弦。

最后想说,向量检索的迁移做没做对,差距永远不会在"本地开发、自己拿一小批文档测一测"时暴露——本地那一小批文档,是你换模型后顺手用新模型重新 embed 过的,你的查询向量也是新模型算的,查询和库恰好都出自同一个空间,你那段"改个模型名、接上去"的代码恰好在一个"新旧不混"的舞台上一路平安,检索结果稳稳当当,你自然觉得"embedding 模型嘛,换个名字的事"一点问题都没有。它只在真实的、面对那个装着几十万篇旧模型向量的大库的环境里才显形。那时候它会用最难堪的方式给你结账:做不好,你会因为新模型的查询向量去量旧模型的库,让召回的全是不相关文档、问答质量断崖下跌,会因为新旧维度不一致,让向量根本写不进库,会因为新老向量混在一起,让检索结果时好时坏、毫无规律可循;而做对了,你的每一条向量都带着清清楚楚的模型身份,换模型时整个索引被用新模型干干净净地全量重建,新索引在旁边静悄悄地造好、被标准问题集验过、再被原子地切上线,查询用的模型永远和库同源,无论你升级过多少次模型,每一次检索都稳稳地在同一个空间里量距离、召回精准。所以别等"升级一上线、整个知识库检索全乱套"那一刻找上门,在你打算把那个"评测分更高的模型"接上去的时候就该想清楚:这个新模型和旧库同空间吗、维度一致吗、整库我重建了吗、迁移我平滑了吗、查询和库还同源吗,这一道道关口,我是不是都替这个"向量和模型死绑定"的事实守住了?这些问题有了答案,你交付的才不只是一套"本地测一小批看着对"的代码,而是一个无论怎么升级 embedding 模型,每一次检索都精准可靠的、让人放心的系统。

—— 别看了 · 2026