向量数据库怎么用

很多人卡在第一步：库选好了、Key 也有了，打开文档却不知道该先写哪行代码。这篇不讲原理，只按接入、写入、检索的顺序把动作拆开，每步告诉你该确认什么、容易在哪翻车，以及什么时候这套做法不适用。

很多人卡在第一步：库选好了、Key 也有了，打开文档却不知道该先写哪行代码。这篇不讲原理，只按接入、写入、检索的顺序把动作拆开，每步告诉你该确认什么、容易在哪翻车。

整体流程就三步：连上库建好集合、把数据写进去、把召回接进自己的代码。三步拆开跑，哪一步出错都好定位，别一上来就写完整链路。

第一步：连上库、建好集合，别急着写数据

连上库之前先确认三件事：连接串与鉴权方式、向量维度是否和嵌入模型一致、距离度量用的是哪种。维度填错是最常见的第一次失败原因，而且报错信息往往不直白，容易查半天。

• 连接方式：拿到连接串和密钥后，先用官方客户端跑一次最简单的连通性检查，别直接写业务代码
• 向量维度：必须先确认清楚嵌入模型输出的维度，再到 /embeddings 页面核对该模型的口径，各家不一样
• 距离度量：建集合时就要选，余弦、内积、欧氏各有适用场景，选错会让排序结果整体不可信
• 先小规模试：先用几十条数据跑通建库、写入、查询，确认链路没问题再批量导

小团队的一个常规做法是：先在本地起一个容器实例跑通整条流程，确认代码逻辑没问题，再换成托管服务。这样能把代码问题和网络、权限问题分开排查，不用边改代码边查连接。

第二步：写入，id、向量、原文、元数据四件套

一条记录至少要有四样东西：唯一 id、向量本身、原始文本或它的引用、以及后面要用来过滤的元数据字段。四件套里缺哪样，后面检索或调试时都会难受。

• id 自己生成并且可复现，比如按来源加序号拼出来，重跑导入脚本时方便去重
• 元数据只留后面真要用来过滤的字段，来源、分类、时间这类，用不上的别加
• 写入按批提交，批次大小先小后大试，观察耗时和报错再调整
• 导入中途失败要有重投或去重的办法，不然跑一半挂了只能整批重来

写入阶段最容易被忽略的是幂等：同一个文档重复导入会怎样，要提前想清楚。把 id 设计成可复现的，遇到重复就能覆盖而不是新增。

第三步：检索，先拿到结果再谈调优

查询时要用同一套嵌入模型把问题转成向量。这一点没有商量余地：模型换一个，之前写进去的向量基本就废了，两边必须一致，否则召回结果会整体跑偏。

先设一个召回条数跑通，拿到结果看排序合不合理，再考虑加过滤条件或加一层重排。一开始就调各种参数，容易分不清是参数问题还是数据问题。

1. 跑通最小查询固定一个召回条数，直接打印召回结果，人工看排序是否合理
2. 加过滤条件用元数据字段限制来源或分类，确认过滤后结果仍符合预期
3. 接进业务代码把召回结果拼进提示词交给模型，注意控制拼接长度，避免噪声挤掉关键内容
4. 分开排查答得不好时先看召回本身对不对，再看拼装方式，两者混在一起查会很慢

过滤逻辑尽量走元数据字段，别把筛选条件写在提示词里让模型自己挑，那样既不可控也没法验证。各产品接口字段是否必填，到 /stacks/vector-dbs 对照接口说明。

这些情况下先别上向量库

向量库不是所有检索场景的默认答案。判断标准很简单：如果关键词匹配就能稳定命中，或者查询本身需要精确匹配，那引入向量链路只会让系统更难解释、更难排查。

• 数据量很小、关键词就能命中的场景，全文检索更简单，结果也更好解释
• 需要精确匹配编号、订单号、代码符号这类内容的查询，向量检索天生不擅长，应该做混合检索
• 文档本身还没清洗干净就先别入库，脏数据进去只会让召回结果更难判断对错
• 对延迟极其敏感又不接受额外跳转的场景，要考虑检索能不能提前算好或缓存

还有一种情况要留意：团队里没人维护嵌入模型和向量数据的同步。模型一升级、数据一改版，向量就得重算，没有固定的人跟这件事，链路会慢慢烂掉。这种时候先别上，比上了再撤更省事。