罗罗编程学习记录
本页内容 展开查看

05.6.5.2 索引过滤与集成实战

所属:全栈开发面试题库 / 05 数据库与存储 / 05.6 向量数据库与语义检索 / 05.6.5 Chroma

覆盖范围

  • HNSW 空间参数、距离度量与集合 metadata 配置落点
  • where 标量过滤语法、操作符与逻辑组合、where_document 全文过滤
  • query 多结果、include 返回字段、get 分页与点查、批量写入
  • LangChain / LlamaIndex / Spring AI / FastAPI / Node 集成方式与 filter 透传
  • 规模瓶颈、性能拐点、迁往 Milvus / pgvector / Qdrant 的时机与步骤
  • 高频踩坑:EF 不一致、类型不匹配、归一化、多进程打开、批次阻塞

检索主线

query_texts / query_embeddings
  → 集合索引(hnsw:space + ef/M 参数)
  → where 标量过滤 + where_document 全文过滤
  → TopK 候选 → include 控制返回字段(documents/embeddings/metadatas/distances)
  → 应用层 rerank / 业务库回显 / 权限补校

高频题速览

编号 题目 难度 频率
05.6.5.2-002 hnsw:space 距离度量取值 基础 ★★★★★
05.6.5.2-004 where 等值过滤写法 基础 ★★★★★
05.6.5.2-008 query 多结果与两种入参 基础 ★★★★★
05.6.5.2-015 LangChain from_documents 接入 基础 ★★★★★
05.6.5.2-027 规模瓶颈与延迟拐点 高级 ★★★★★
05.6.5.2-029 迁往生产级向量库的时机 高级 ★★★★★
05.6.5.2-031 EF 不一致导致维度报错 基础 ★★★★★
05.6.5.2-034 嵌入式被多进程打开 高级 ★★★★☆
05.6.5.2-047 Chroma 适合与不适合场景 基础 ★★★★☆
05.6.5.2-048 RAG 检索链路完整设计 高级 ★★★★★

05.6.5.2-001 Chroma 默认用什么索引结构,可配置哪些度量?

频率 ★★★★☆ | 难度 进阶

一句话结论

Chroma 近邻检索基于可配置的 HNSW 类索引,距离度量在建集合时通过 metadata 指定;具体索引实现细节与默认参数以当前版本为准(待确认),面试落点是参数配置位置而非算法原理。

概念解释

  • 索引落点:集合级配置,创建集合时写入 metadata,不在线切换。
  • 度量选择:l2、cosine、ip 三类常见取值,键名与取值拼写以官方文档为准。
  • 边界:本页不重复 IVF/HNSW 结构原理(见 05.5.2.5),只讲 Chroma 里怎么配、在哪改。

原理流程

建集合 → metadata 指定 hnsw:space 与索引参数
  → 写入建索引 → 查询按同一度量计算
  → 改度量/结构 → 新建集合迁移

代码 / 命令

# 集合创建时配置(键名以版本文档为准)
# collection = client.get_or_create_collection(name="kb", metadata={"hnsw:space": "cosine"})

常见误区

  • 误区:查询时可以临时换度量。正解:度量随集合定型,换度量必须重建集合。
  • 误区:默认参数在所有版本一致。正解:默认值随版本变化,以实测集合配置与文档为准。

追问

  • 问:文本检索默认推荐哪种度量?答:cosine 为主,具体仍以嵌入模型训练约定为准。
  • 问:索引参数在哪查看?答:读取集合 metadata 与预期基线比对,不凭记忆判断。

05.6.5.2-002 hnsw:space 可取哪些值,分别对应什么距离?

频率 ★★★★★ | 难度 基础

一句话结论

hnsw:space 常见取值为 l2(欧氏距离,越小越近)、cosine(余弦相似度,越大越相似)、ip(内积,越大越相似);取值在建集合时固定。

概念解释

  • l2:欧氏距离,受向量模长影响。
  • cosine:方向相似度,忽略模长,文本嵌入常用。
  • ip:内积,含模长信息;向量归一化后与 cosine 等价。
  • 待确认:取值字符串拼写与是否有其他度量,以官方文档为准。

原理流程

选度量 → 集合 metadata 配置 hnsw:space
  → 入库向量按约定预处理(归一化视度量而定)
  → 查询同度量排序返回

代码 / 命令

# 三种取值形态(待确认拼写)
# {"hnsw:space": "l2"}  /  {"hnsw:space": "cosine"}  /  {"hnsw:space": "ip"}

常见误区

  • 误区:l2 与 cosine 结果可以混用排序。正解:度量不同,距离含义与方向都不同。
  • 误区:ip 场景不用管模长。正解:未归一化时模长会拉大内积差异。

追问

  • 问:cosine 与 ip 何时等价?答:向量全部归一化到单位模长后。
  • 问:度量配错怎么发现?答:近邻结果与预期相关性明显偏离,核对集合 space 与向量预处理。

05.6.5.2-003 construction_ef、search_ef、M 参数分别落在哪一层?

频率 ★★★★☆ | 难度 进阶

一句话结论

M 与构建候选(construction_ef)是建图期参数,搜索候选(search_ef)是查询期参数;三者通过集合 metadata 传入,键名与默认值以版本文档为准(待确认),建图参数改动通常需要重建索引。

概念解释

  • M:节点邻居连接数,影响图密度与内存,建库期定型。
  • construction_ef:构建时候选宽度,影响图质量与构建耗时。
  • search_ef:查询时候选队列大小,影响召回与查询延迟。
  • 边界:参数含义见通用索引题,这里只讲 Chroma 的配置入口与可变性。

原理流程

建集合:metadata 传入 M / construction_ef
  → 写入过程建图 → 查询期读 search_ef
  → 调建图参数 → 重建集合;调搜索参数优先查是否支持运行期覆盖

代码 / 命令

# 参数落点示意(键名/默认值待确认,以文档为准)
# metadata={"hnsw:M": 16, "hnsw:construction_ef": 200, "hnsw:search_ef": 100}

常见误区

  • 误区:三个参数都能在线随时调大。正解:M 与构建参数属于结构参数,在线改不一定生效。
  • 误区:search_ef 越大越好。正解:候选扩大增加计算与延迟,需在召回与 P99 间权衡。

追问

  • 问:线上召回不足先调哪个?答:先评估搜索候选宽度,再看建图质量与数据分布。
  • 问:参数记不清默认值怎么办?答:标注待确认,在测试集合上读出实际值,不背诵。

05.6.5.2-004 where 等值过滤怎么写?

频率 ★★★★★ | 难度 基础

一句话结论

where 用键值字典表达标量条件,等值写法为 {"字段": "值"},查询时随 query 或 get 传入,只在满足条件的记录上检索或遍历。

概念解释

  • 结构:字段名 → 条件值;等值是最常用的简写形式。
  • 作用范围:向量查询的候选过滤、get 遍历过滤。
  • 类型一致:值的类型要与记录 metadata 存储类型匹配。

原理流程

构造 where={"tenant": "t1"}
  → query(where=...) 或 get(where=...)
  → 服务端按 metadata 匹配 → 返回子集结果

代码 / 命令

# 等值过滤形态
# collection.query(query_texts=["问题"], n_results=5, where={"tenant": "t1"})
# collection.get(where={"status": "online"})

常见误区

  • 误区:where 条件写在查询文本里。正解:标量条件走 where 参数,不拼进 query_texts。
  • 误区:字段不存在也能匹配。正解:缺该字段的记录不满足等值条件。

追问

  • 问:多字段等值怎么写?答:用逻辑组合连接多个单字段条件(见逻辑组合题)。
  • 问:过滤不生效先查什么?答:字段名拼写、值类型、记录是否真的写了该 metadata。

05.6.5.2-005 where 支持哪些比较与集合操作符?

频率 ★★★★★ | 难度 进阶

一句话结论

常见操作符包括等值/不等、集合归属与排除、大小比较:$eq、$ne、$in、$nin、$gt、$gte、$lt、$lte;支持与否与拼写以当前版本文档为准(待确认)。

概念解释

  • 等值类:$eq、$ne。
  • 集合类:$in(命中列表其一)、$nin(不在列表内)。
  • 范围类:$gt、$gte、$lt、$lte,适用于数字与约定可比较类型。
  • 写法:操作符作为值的字典键,如 {"字段": {"$gt": 10}}。

原理流程

字段 → 操作符字典 → where 传入
  → 逐条 metadata 求值 → 满足条件进入候选

代码 / 命令

# 操作符形态(待确认拼写与支持集合)
# where={"updated_at": {"$gte": 1700000000}}
# where={"status": {"$in": ["online", "pending"]}}

常见误区

  • 误区:字符串也能直接用 $gt 比较。正解:范围比较语义按类型实现,字符串比较不等同数字大小。
  • 误区:$in 可以放嵌套对象。正解:集合归属只对标量值有明确语义。

追问

  • 问:数字时间戳为什么适合范围过滤?答:可比较、排序明确,避免字符串日期格式不一致问题。
  • 问:操作符返回空结果怎么排查?答:先去掉操作符用等值验证记录存在,再逐步加条件定位。

05.6.5.2-006 $and、$or、$not 怎么组合条件?

频率 ★★★★☆ | 难度 进阶

一句话结论

逻辑组合用 $and、$or 连接条件列表,$not 对单个条件取反;嵌套层级要保持可读,复杂条件先在小样本上验证命中结果。

概念解释

  • $and:列表内条件全部满足。
  • $or:列表内任一条件满足。
  • $not:包裹一个条件取反。
  • 边界:组合语义与嵌套支持以版本文档为准(待确认),不要假设任意深度嵌套都可用。

原理流程

where={"$and": [{"tenant": "t1"}, {"status": {"$eq": "online"}}]}
  → 逐条求值 → 交集/并集/取反 → 候选集

代码 / 命令

# 组合形态(待确认拼写)
# {"$or": [{"source": "manual"}, {"source": "faq"}]}
# {"$not": {"status": "archived"}}

常见误区

  • 误区:$and 内各字段互相独立,可以随便嵌套任意层。正解:先验证当前版本的嵌套深度与写法支持。
  • 误区:条件越多结果越准。正解:过严组合会把候选压到不足 TopK,需评估选择性。

追问

  • 问:高选择性条件该怎么放?答:先按等值/集合归属缩小子集,再叠加其他条件,避免全量逐条求值。
  • 问:组合条件写错报什么?答:可能语法报错或返回空,先打印 where 结构与样例记录核对。

05.6.5.2-007 where_document 全文过滤怎么写?

频率 ★★★★☆ | 难度 进阶

一句话结论

where_document 针对入库的 documents 文本做包含类过滤,常见 $contains、$not_contains 操作符;它依赖原文入库,纯向量记录不参与,分词与匹配方式以版本实现为准(待确认)。

概念解释

  • 对象:collection 中每条记录的 document 文本。
  • 操作符:$contains 文本包含、$not_contains 不包含,可做逻辑组合。
  • 边界:这不是倒排全文检索引擎,术语精确匹配能力有限,不要替代 BM25。

原理流程

query(where_document={"$contains": "关键词"})
  → 扫描候选记录文本 → 包含匹配 → 与向量结果叠加

代码 / 命令

# 文本过滤形态(待确认操作符拼写)
# collection.query(query_texts=["问题"], where_document={"$contains": "合同"})

常见误区

  • 误区:where_document 支持复杂语法检索。正解:它是包含类过滤,不是完整全文查询。
  • 误区:原文没入库也能按文本过滤。正解:document 为空的记录无法被文本条件命中。

追问

  • 问:关键词精确匹配需求强怎么办?答:关键词场景用 BM25/ES 类方案,向量库文本过滤只做辅助。
  • 问:中文包含匹配注意什么?答:分词边界与子串匹配行为需实测,长词与近义词不要假设命中。

05.6.5.2-008 query 的入参与多结果返回是什么结构?

频率 ★★★★★ | 难度 基础

一句话结论

query 通过 query_texts(文本走 EF)或 query_embeddings(自嵌向量)传入查询,n_results 控制返回条数;支持一次多条查询,返回按查询分组的结果列表。

概念解释

  • 入参二选一:文本列表或向量列表,不能混用以致模型不一致。
  • n_results:每条查询返回的近邻条数。
  • 返回结构:每条查询对应一组命中,含 id、距离及 include 指定的字段。

原理流程

query_texts → EF 生成查询向量;或 query_embeddings 直用
  → ANN + 过滤 → Top n_results
  → 按查询分组返回 ids / distances / documents / metadatas

代码 / 命令

# 形态(字段名以版本文档为准)
# collection.query(query_texts=["问题A", "问题B"], n_results=5)
# collection.query(query_embeddings=[vec], n_results=5, where={"tenant": "t1"})

常见误区

  • 误区:query_texts 与 query_embeddings 可以同时传。正解:二选一,避免两套向量来源混用。
  • 误区:n_results 是全库返回总数。正解:是每条查询的近邻条数。

追问

  • 问:多条查询结果怎么对齐?答:返回列表下标与输入查询列表一一对应。
  • 问:n_results 设很大有什么代价?答:候选与排序成本上升,在线接口应控制条数。

05.6.5.2-009 include 控制返回哪些字段?

频率 ★★★☆☆ | 难度 基础

一句话结论

include 列表指定结果返回 documents、embeddings、metadatas、distances 等字段;不需要的字段不返回,可减少传输与序列化开销,可选字段集合以版本文档为准(待确认)。

概念解释

  • 常用字段:documents 回显片段、metadatas 过滤字段、distances 相似度、embeddings 向量本体。
  • 默认行为:query 与 get 的默认返回字段不同,需按接口文档核对。
  • 取舍:回显只需 document 与 metadata 时,不必返回 embeddings。

原理流程

检索得到候选 → 按 include 挑选字段组装结果
  → 缺字段时客户端回业务库补充

代码 / 命令

# 形态(可选字段待确认)
# collection.query(query_texts=[...], n_results=5, include=["documents", "metadatas", "distances"])

常见误区

  • 误区:include 可以返回未入库的字段。正解:只返回已存储的四要素相关字段。
  • 误区:embeddings 总会带在结果里。正解:需显式包含,默认可能不返回。

追问

  • 问:结果里没有距离怎么办?答:检查 include 是否包含 distances,以及接口返回结构。
  • 问:大向量回传有什么影响?答:增加网络与序列化开销,在线回显场景通常不返回向量本体。

05.6.5.2-010 get 的 limit/offset 分页怎么用?

频率 ★★★☆☆ | 难度 基础

一句话结论

get 用于按 id 点查或按 where 遍历记录,limit 控制单页条数、offset 控制跳过条数;分页遍历要配合稳定的排序口径,否则翻页可能漏读或重复。

概念解释

  • 用途:导出、对账、全量遍历,不是近邻检索。
  • 分页参数:limit 页大小,offset 偏移量。
  • 稳定性:遍历结果顺序若未保证,深翻页可能重复或遗漏,大批量导出优先按 id 分段。

原理流程

get(where=..., limit=page, offset=skip)
  → 取一页 → 记录游标 → 下一页 offset 累加
  → 直到返回条数不足 limit

代码 / 命令

# 分页形态(参数名以版本文档为准)
# collection.get(where={"status": "online"}, limit=100, offset=0)

常见误区

  • 误区:get 可以替代 query 做语义检索。正解:get 是点查/遍历,不按相似度排序。
  • 误区:offset 越大越没问题。正解:深翻页成本与顺序稳定性都要评估,导出改用按 id 分批。

追问

  • 问:全量导出怎么避免漏页?答:按 id 区间分批,或记录已读 id 集合对账,不只依赖 offset。
  • 问:limit 设多大合适?答:以单页内存与超时可承受为准,实测确定,不要一次拉全量。

05.6.5.2-011 get 按 ids 点查与 where 过滤怎么配合?

频率 ★★★★★ | 难度 基础

一句话结论

get 可按 ids 列表直接点查,也可叠加 where 条件过滤;点查用于回显与对账,where 遍历用于按业务字段筛选记录。

概念解释

  • ids 点查:主键定位,返回对应记录四要素。
  • where 遍历:按 metadata 条件筛选,配合分页。
  • 组合:ids 与 where 同时传入时取交集,语义以版本实现为准(待确认)。

原理流程

点查:get(ids=[...])
遍历:get(where=..., limit=..., offset=...)
组合:两者同时传入 → 交集结果

代码 / 命令

# 形态(参数名以版本文档为准)
# collection.get(ids=["doc-001", "doc-002"])
# collection.get(where={"tenant": "t1"}, limit=50)

常见误区

  • 误区:点查不存在的 id 会报错。正解:通常返回缺失项为空,按返回列表对照预期 id 集合。
  • 误区:where 遍历返回的是最相关记录。正解:无相似度排序,只是条件匹配。

追问

  • 问:检索命中后回显为什么还要 get?答:query 结果可能未含 document,按需点查补齐片段与元数据。
  • 问:批量点查 ids 上限?答:分批控制单批大小,避免单次请求过大,具体上限实测确定。

05.6.5.2-012 批量写入怎么分批?

频率 ★★★☆☆ | 难度 进阶

一句话结论

大批量写入按固定批次提交,每批控制记录数与向量规模,保留失败批次可重放;单批过大占用内存、拉长请求并提高重试成本。

概念解释

  • 分批依据:单批向量条数、总向量维度体积、原文长度。
  • 幂等:按业务主键 upsert,失败批次可安全重放。
  • 对账:每批记录写入条数与失败明细,便于补齐。

原理流程

全量记录 → 切片分批
  → 每批 upsert → 成功记录批次 → 失败批次落日志重放
  → 全部完成后 count 对账

代码 / 命令

# 分批伪代码
# for batch in chunks(records, size=100):
#     collection.upsert(ids=..., documents=..., metadatas=...)

常见误区

  • 误区:一次 add 全量最快。正解:大批次内存与超时风险高,失败后重放代价更大。
  • 误区:分批写入可以跳过对账。正解:缺批会导致检索漏片段,必须按 count 与抽样核对。

追问

  • 问:批大小怎么定?答:压测不同批次下的耗时、内存与成功率,选稳定拐点。
  • 问:写入期间 EF 调用怎么控速?答:嵌入模型调用是批量写入的主要耗时与依赖,失败重试与限频一并考虑。

05.6.5.2-013 过滤选择性强弱对检索行为有什么影响?

频率 ★★★★☆ | 难度 高级

一句话结论

高选择性条件能先缩小候选子集再做向量检索;低选择性条件或实现为后过滤时,ANN 先取候选再剔除不达标记录,可能导致 TopK 不足,需扩大候选量补位。

概念解释

  • 预过滤:先按 metadata 筛子集,子集内做向量近邻。
  • 后过滤:向量检索取足量候选,再剔除不满足条件者。
  • Chroma 具体执行方式以版本实现为准(待确认),工程上要按过滤后候选充足度设计。

原理流程

强过滤:先筛子集 → 子集内 ANN
弱过滤/后过滤:ANN 取大候选 → 过滤剔除 → 不足 K 条时补候选

代码 / 命令

# 工程兜底:过滤条件可能压低命中数时,n_results 适当放大
# 核对:过滤前后候选数量、空结果比例

常见误区

  • 误区:带过滤的查询一定在子集内走 ANN。正解:执行顺序取决于实现,后过滤会出现候选被剔除的情况。
  • 误区:TopK 不足是索引坏了。正解:常因过滤条件过严或后过滤候选不足。

追问

  • 问:强过滤字段怎么设计?答:高选择性字段(租户、状态)入库为标量,查询必带。
  • 问:过滤后空结果怎么处理?答:先放宽条件或扩大候选,区分是真无数据还是过滤过严。

05.6.5.2-014 where_document 的分词与匹配边界在哪里?

频率 ★★☆☆☆ | 难度 高级

一句话结论

文本包含匹配基于入库字符串的子串/分词实现,具体分词器、大小写与标点处理以版本为准(待确认);不要把它当支持词干、同义词、多语言分词的全文引擎。

概念解释

  • 匹配对象:原始 document 文本,不建独立倒排结构。
  • 不确定点:中文分词边界、大小写归一、标点忽略规则需实测。
  • 替代:术语、编号、同义词匹配需求交给全文检索系统。

原理流程

关键词 → 对候选 document 做包含判断
  → 命中条件进入结果 → 未命中即排除

代码 / 命令

# 验证:同一关键词在不同大小写、标点、分词写法下各跑一条样例

常见误区

  • 误区:包含匹配能命中同义词与词形变化。正解:通常只做字面匹配,不做语义扩展。
  • 误区:长文本片段不影响过滤速度。正解:逐条扫描长文本有成本,候选量大时观察延迟。

追问

  • 问:编号、型号类精确匹配怎么办?答:作为 metadata 标量字段过滤,比文本包含更可靠。
  • 问:多语言混合文本要注意什么?答:分词与编码先在测试集验证,不要假设跨语言包含一致。

05.6.5.2-015 LangChain 怎么用 from_documents 接入 Chroma?

频率 ★★★★★ | 难度 基础

一句话结论

LangChain 通过集成类把 Document 列表与 embedding 模型写入 Chroma 集合,from_documents 一次性完成文档切分后入库;核心参数是文档、嵌入模型、集合名与持久化目录/客户端。

概念解释

  • 入参:Document 列表(含文本与 metadata)、embedding 模型、collection_name。
  • 存储:persist_directory 嵌入式,或传入已有 client 连服务端。
  • 返回:VectorStore 实例,可接 retriever 供链式调用。

原理流程

Document[] + embedding 模型
  → from_documents 写入 Chroma 集合
  → VectorStore.as_retriever → 检索 → 包装回 Document

代码 / 命令

# 形态(类名/参数以当前框架版本文档为准)
# Chroma.from_documents(docs, embedding=emb_model, collection_name="kb", persist_directory="./chroma_data")

常见误区

  • 误区:框架自动选择最佳嵌入模型。正解:模型由调用方传入,版本与集合必须一致。
  • 误区:metadata 会自动映射所有文档字段。正解:Document 的 metadata 键值按写入时结构入库,需显式构造。

追问

  • 问:复用已有服务端客户端怎么传?答:集成类若支持 client 参数则传入 HttpClient 实例,具体参数核对框架文档。
  • 问:增量文档怎么写入?答:用 VectorStore 的 add 类方法按主键 upsert,不重复调 from_documents 全量覆盖。

05.6.5.2-016 LangChain retriever 的 filter 怎么透传?

频率 ★★★★☆ | 难度 进阶

一句话结论

retriever 通过 search_kwargs 传入过滤条件与条数,框架再映射到底层 where 参数;复杂过滤语法要核对集成版本的透传能力,字段名与底层 metadata 保持一致。

概念解释

  • 透传链路:retriever search_kwargs → 集成类 → Chroma where/where_document。
  • 参数:k(条数)、filter/where 条件。
  • 风险:框架封装可能只透传部分条件,未支持的写法需要回到底层客户端查询。

原理流程

as_retriever(search_kwargs={"k": 5, "filter": {"tenant": "t1"}})
  → 集成类转换为底层查询参数 → Chroma 执行过滤检索

代码 / 命令

# 形态(参数名以框架文档为准)
# retriever = vectorstore.as_retriever(search_kwargs={"k": 5, "filter": {"status": "online"}})

常见误区

  • 误区:框架层 filter 能表达所有底层操作符。正解:复杂 $and/$or/$in 需验证透传,不行就直接用底层客户端。
  • 误区:filter 字段名可以与入库 metadata 不同。正解:必须按入库键名匹配,大小写敏感。

追问

  • 问:透传丢失怎么排查?答:开启集成层日志,对比最终发到底层的 where 结构。
  • 问:检索结果带 metadata 吗?答:取决于返回封装,需要时从底层查询补取。

05.6.5.2-017 LangChain 下嵌入模型与自嵌向量怎么配合?

频率 ★★★☆☆ | 难度 进阶

一句话结论

框架链路默认由传入的嵌入模型生成向量;若要自嵌,需在写入时提供向量或绕过 EF 直接调底层客户端,保证框架检索链路与自嵌使用同一模型版本。

概念解释

  • 默认路径:Document 文本 → 传入模型 → 向量入库。
  • 自嵌路径:外部模型服务生成向量,写入底层集合;检索查询同样外部生成。
  • 一致性:模型、版本、归一化约定在写入与检索两侧统一登记。

原理流程

写入:外部模型生成向量 → 底层集合 add/upsert
检索:查询经同一模型 → query_embeddings
  → 框架只做结果包装,不混用两套向量

代码 / 命令

# 自嵌场景:直接操作底层 collection.query(query_embeddings=[...])
# 框架链路:传入与入库同一 embedding 模型实例

常见误区

  • 误区:框架写入用模型 A,检索换模型 B 没关系。正解:向量空间不同,近邻结果失真。
  • 误区:自嵌后框架还能自动重算。正解:自嵌向量不会被框架重新嵌入。

追问

  • 问:模型在独立服务里怎么接?答:应用侧调用模型服务生成向量,Chroma 只存向量与片段。
  • 问:怎么登记模型版本?答:集合 metadata 或映射表记录模型名与版本,便于重嵌排查。

05.6.5.2-018 LlamaIndex 怎么集成 Chroma?

频率 ★★★☆☆ | 难度 进阶

一句话结论

LlamaIndex 通过 ChromaVectorStore 类把节点/文档写入 Chroma 集合,检索作为查询引擎的存储后端;接入参数同样围绕集合名、客户端与嵌入模型,具体类名与方法以框架文档为准(待确认)。

概念解释

  • 抽象:VectorStore 接口承载节点存储与检索。
  • 映射:LlamaIndex 节点文本、metadata 映射到 Chroma 记录要素。
  • 一致性:嵌入模型由索引/存储配置统一,跨框架不混用。

原理流程

文档/节点 → 嵌入 → ChromaVectorStore 写入集合
  → 查询引擎 → 向量检索 → 节点回灌上下文

代码 / 命令

# 形态示意(类名/参数以 LlamaIndex 当前文档为准)
# ChromaVectorStore(collection_name="kb", ...)
# 索引建立时传入该存储与嵌入模型

常见误区

  • 误区:LlamaIndex 与 LangChain 写入同一集合可以互相补充。正解:两套封装的 metadata 映射可能不同,混用前核对字段。
  • 误区:框架会自动持久化所有配置。正解:集合与模型配置仍需应用侧登记。

追问

  • 问:节点 metadata 怎么进入 Chroma?答:按框架映射规则写入记录 metadata,写入后抽样核对键名。
  • 问:切换框架要迁移数据吗?答:集合数据可复用,但 metadata 映射与检索链路要重新验证。

05.6.5.2-019 Spring AI 怎么集成 Chroma?

频率 ★★★☆☆ | 难度 进阶

一句话结论

Spring AI 以 VectorStore 抽象统一各向量库接入,Chroma 实现类负责连接集合、写入与相似检索;配置包括客户端连接、集合名与嵌入模型,Bean 生命周期与嵌入模型依赖要纳入容器管理,具体组件名与配置项以 Spring AI 文档为准(待确认)。

概念解释

  • 抽象层:VectorStore 接口提供 add/相似检索统一方法。
  • 实现层:Chroma 客户端装配、集合初始化、FilterExpression 映射到 where。
  • 容器生命周期:嵌入模型与 VectorStore 作为 Bean 注入,配置走属性绑定。

原理流程

应用启动 → 装配嵌入模型与 Chroma VectorStore Bean
  → 文档写入 VectorStore → 检索调用 similaritySearch
  → 过滤表达式映射底层 where

代码 / 命令

# 形态示意(组件名/配置项待确认,以 Spring AI 文档为准)
# VectorStore chromaVectorStore(...) { ... }
# similaritySearch(request, filterExpression)

常见误区

  • 误区:Spring AI 过滤表达式支持所有底层操作符。正解:表达式到 where 的映射有能力边界,复杂条件先验证。
  • 误区:Bean 里自己 new 客户端即可。正解:连接配置、生命周期与异常处理应纳入容器管理。

追问

  • 问:嵌入模型 Bean 怎么复用?答:同一嵌入模型实例同时供写入与检索使用,避免两侧模型不一致。
  • 问:配置项在哪管理?答:走应用配置属性,按环境区分集合名与连接,不写死在代码。

05.6.5.2-020 FastAPI 服务化封装要考虑哪些点?

频率 ★★★★☆ | 难度 高级

一句话结论

把 Chroma 包成 FastAPI 服务时,要设计路由与请求 DTO、批量与限流、超时与错误处理、连接复用与集合初始化;应用层补齐权限校验与审计,不直接把库接口裸暴露。

概念解释

  • 接口:写入、检索、点查、删除等路由,请求/响应结构明确。
  • 工程:连接复用、批量上限、并发控制、超时与异常映射。
  • 安全:调用方身份校验、租户条件强制、敏感片段脱敏。

原理流程

请求 → 鉴权与参数校验 → 租户条件注入
  → 调用客户端(复用连接)→ 结果过滤脱敏 → 响应
  → 错误码与日志审计

代码 / 命令

# 路由示意:/retrieve  /upsert  /get  /delete
# 要点:DTO 校验 · 超时 · 批量上限 · 连接池 · 审计日志

常见误区

  • 误区:FastAPI 直接转发全部底层接口。正解:应暴露业务所需最小接口,权限与参数校验在网关层完成。
  • 误区:每个请求新建客户端。正解:客户端/连接复用,避免握手与资源泄漏。

追问

  • 问:写入接口怎么做幂等?答:按业务主键 upsert,请求携带来源标识便于对账。
  • 问:检索超时怎么兜底?答:设读取超时、有限重试与降级返回,避免工作线程堆积。

05.6.5.2-021 Node / TypeScript 客户端接入有什么要点?

频率 ★★☆☆☆ | 难度 进阶

一句话结论

官方或社区 JS/TS 客户端通过连接服务端使用,能力以客户端版本为准;要点是连接配置、集合与记录字段命名、异步调用错误处理,嵌入式存储能力在 Node 侧的支持程度需核对文档(待确认)。

概念解释

  • 连接:HttpClient 形态连接独立服务端。
  • 字段:ids/documents/embeddings/metadatas 与 Python 侧概念对齐。
  • 异步:接口为 Promise/异步调用,注意超时与异常捕获。

原理流程

初始化客户端 → 获取集合
  → 异步 add/upsert/query → 结果按结构解析
  → 错误分类重试

代码 / 命令

# 形态示意(包名/方法名以官方文档为准)
# const collection = await client.getCollection("kb")
# await collection.query({ queryTexts: [...], nResults: 5 })

常见误区

  • 误区:Node 客户端与 Python 客户端能力完全对等。正解:功能与参数支持可能滞后,以客户端文档核对。
  • 误区:字段命名两侧一致不用转换。正解:语言间命名风格可能不同(驼峰/下划线),需做映射。

追问

  • 问:多语言客户端连同一服务端注意什么?答:集合字段、模型与度量两侧约定一致,版本协议匹配。
  • 问:异步并发怎么控制?答:限制并发批次,避免一次性大量请求打爆服务端。

05.6.5.2-022 检索结果的距离怎么解释与排序?

频率 ★★★☆☆ | 难度 基础

一句话结论

返回距离的含义由度量决定:l2 越小越近,cosine/ip 越大越相似;结果按所选度量排序,跨度量不能直接比较数值大小。

概念解释

  • l2:距离值,升序,越小越相关。
  • cosine/ip:相似度值,降序,越大越相关。
  • 归一化:未归一化时内积受模长影响,解释结果要结合预处理约定。

原理流程

集合度量确定 → 查询计算距离 → 按度量方向排序
  → 结果附带 distances → 应用层按同度量解释阈值

代码 / 命令

# 阈值过滤要按度量方向:l2 用 ≤ 阈值;cosine/ip 用 ≥ 阈值
# 核对集合 hnsw:space 再决定比较方向

常见误区

  • 误区:所有距离都是越小越好。正解:相似度度量方向相反,搞反会选出不相关结果。
  • 误区:不同集合的距离值能横向比较。正解:度量、归一化与模型不同,数值不可直接对比。

追问

  • 问:相关性阈值怎么定?答:在标注集上统计命中/未命中的距离分布,选分界点,不照搬通用阈值。
  • 问:距离为负说明什么?答:内积可负,按向量方向解释,不代表错误。

05.6.5.2-023 一次多条查询的返回结构怎么对齐?

频率 ★★★☆☆ | 难度 基础

一句话结论

多条查询输入对应返回列表逐位对齐:第 i 组结果对应第 i 条查询;每组内部按命中排序,字段同样按 include 控制。

概念解释

  • 对齐依据:输入列表下标,不靠 id 或文本匹配。
  • 组内结构:ids、documents、metadatas、distances 各自成列表,位置一一对应。
  • 空命中:某组可能返回空列表,需单独处理。

原理流程

输入 [q1, q2, q3]
  → 返回 [r1, r2, r3],下标对齐
  → 每组内 ids[i] 与 distances[i] 对应同一条记录

代码 / 命令

# 遍历形态
# for i, query_result in enumerate(results):
#     for j, doc_id in enumerate(query_result["ids"]): ...

常见误区

  • 误区:返回结果按全局相似度重排混合。正解:分组返回,组内排序,组间不混排。
  • 误区:每组返回条数一定等于 n_results。正解:受候选与过滤影响,可能不足。

追问

  • 问:批量查询与单条循环哪个好?答:批量减少往返,但要控制批量大小与内存,单条便于隔离失败。
  • 问:组内字段顺序不一致怎么办?答:以 ids 为主键对齐其他字段列表,不假设列表独立有序。

05.6.5.2-024 检索结果能按文档分组或去重吗?

频率 ★★☆☆☆ | 难度 高级

一句话结论

Chroma 检索默认返回切片级命中,同一文档多个切片可能重复出现;分组去重需要应用层按文档 id 聚合,库内不保证提供分组聚合能力(以版本为准,待确认)。

概念解释

  • 粒度:记录通常是切片,一篇文档对应多条记录。
  • 去重维度:按源文档 id 归并,保留最高分切片。
  • 应用层方案:metadata 存文档标识,检索后按标识分组择优。

原理流程

切片 TopK → 按 document_id 分组
  → 每组取最高分代表切片 → 合并去重 → 交 rerank/上下文拼装

代码 / 命令

# metadata 存 doc_id;检索后应用层聚合
# 分组键:doc_id;择优:组内最大相似度

常见误区

  • 误区:TopK 条结果来自不同文档。正解:可能同一文档多个切片占据名额,应用层需归并。
  • 误区:库内有原生 group_by。正解:能力未确认前,在应用层实现分组更稳妥。

追问

  • 问:分组后上下文怎么选?答:每组取最优切片,必要时补同文档相邻切片,控制总 token。
  • 问:文档标识存哪?答:记录 metadata 存 doc_id,原文与章节结构回业务库取。

05.6.5.2-025 怎么与 rerank 模型配合?

频率 ★★★★☆ | 难度 进阶

一句话结论

Chroma 负责粗召回候选,rerank 模型在应用层对候选精排;流程是向量检索取放大候选 → rerank 打分 → 取最终 TopK,rerank 不依赖库内能力。

概念解释

  • 分工:ANN 求高召回,rerank 求高精度排序。
  • 候选量:rerank 输入大于最终条数,控制模型调用成本。
  • 位置:检索服务内或独立 rerank 阶段,结果与原始片段对应。

原理流程

query → Chroma 召回 N 条候选
  → rerank 模型对 query+片段打分 → 重排取 K 条
  → 上下文拼装

代码 / 命令

# 流程:n_results 放大 → rerank 输入 [query, document] 对 → 按重排分排序
# 成本控制:rerank 候选数与模型延迟一起评估

常见误区

  • 误区:rerank 能弥补召回缺失。正解:rerank 只排已有候选,召不回的片段无法出现。
  • 误区:候选越多越好。正解:rerank 调用成本随候选数上升,需选平衡值。

追问

  • 问:rerank 与向量距离怎么融合?答:通常以 rerank 分为准重排,向量距离作为候选粗排参考。
  • 问:延迟超标时降级顺序?答:先减 rerank 候选数,再考虑跳过 rerank 直接用向量排序。

05.6.5.2-026 关键词 + 向量混合检索在 Chroma 能力边界内怎么做?

频率 ★★★★☆ | 难度 高级

一句话结论

Chroma 自身偏向向量检索,关键词路需要外部 BM25/全文索引补齐;两路召回后在应用层用排名融合(如 RRF)合并,不要假设库内原生提供成熟混合检索(能力以版本为准,待确认)。

概念解释

  • 向量路:语义近似,覆盖同义改写。
  • 关键词路:术语、编号精确命中,外部全文系统承担。
  • 融合:应用层按位次融合,规避分数量纲差异。

原理流程

query → 向量路 Chroma TopK
      → 关键词路 BM25/全文 TopK
  → 应用层 RRF/加权融合 → 最终排序

代码 / 命令

# 两路结果各自带候选位次 → RRF 按排名融合
# 精确术语需求强时,关键词路不可省略

常见误区

  • 误区:where_document 就是 BM25。正解:包含过滤不等同倒排全文检索,无词项权重与分词索引。
  • 误区:两路分数直接相加。正解:量纲不同,先归一化或用位次融合。

追问

  • 问:什么场景必须加关键词路?答:产品编号、代码、专有名词、精确术语查询。
  • 问:融合权重怎么调?答:先按位次 RRF 兜底,再按 bad case 调整两路候选数与权重。

05.6.5.2-027 规模瓶颈与延迟拐点怎么识别?

频率 ★★★★★ | 难度 高级

一句话结论

拐点通过自有数据集压测识别:观察 QPS、P99、内存与目录增长随向量数的变化曲线;常见瓶颈在内存容纳、单进程并发与本地 IO,不存在可背诵的固定条数上限。

概念解释

  • 资源瓶颈:向量与索引占用内存,原文元数据占用磁盘。
  • 并发瓶颈:单进程请求处理能力,排队表现为 P99 抬升。
  • 存储瓶颈:大批量写入与目录 IO。
  • 方法:真实分布数据逐步加压,记录拐点指标。

原理流程

构造真实分布数据集 → 阶梯加压
  → 记录 QPS/P99/内存/目录 → 找饱和拐点
  → 对照业务 SLA 决定扩容或迁移

代码 / 命令

# 压测矩阵:向量规模 × 并发数 × 批次大小
# 输出:QPS、P50/P99、内存峰值、目录增长、错误率

常见误区

  • 误区:用随机向量压测就能代表线上。正解:分布、维度与原文长度不同,结论不可靠。
  • 误区:瓶颈只在向量数量。正解:原文长度、元数据与并发请求同样影响拐点。

追问

  • 问:P99 先于 QPS 到达瓶颈说明什么?答:并发排队或资源饱和,先看线程/连接与内存。
  • 问:拐点前要留多少余量?答:按峰值增长与 SLA 预留,不在饱和点上生产运行。

05.6.5.2-028 内存与磁盘占用怎么观察?

频率 ★★★☆☆ | 难度 高级

一句话结论

内存按向量本体 + 索引结构 + 原文元数据估算,磁盘看目录增长与单条平均占用;上线后定期统计 count、目录大小与进程内存,对比单条成本判断增长是否异常。

概念解释

  • 内存:向量浮点数组、图/索引结构、查询临时缓冲。
  • 磁盘:向量、原文片段、元数据与索引文件。
  • 异常信号:单条平均占用持续上升、删除后体积不回落、重复批次残留。

原理流程

count + 目录大小 → 单条平均占用
  → 进程内存对照估算模型 → 识别异常增长
  → 必要时导出重建回收空间

代码 / 命令

# 观察口径:count · 目录字节 · 进程内存 · 单条平均占用趋势
# 清理候选:重复批次、长原文、删除残留

常见误区

  • 误区:只按向量大小估算内存。正解:索引结构与原文元数据额外占用显著。
  • 误区:删除后磁盘立刻下降。正解:内部回收有节奏,需观察目录趋势确认。

追问

  • 问:内存上涨先查什么?答:count 是否增长、单条占用是否变大、是否残留重复与删除记录。
  • 问:磁盘不足怎么应急?答:先清理重复与无效记录,再评估迁移或扩容,不要手工删内部文件。

05.6.5.2-029 什么时候该从 Chroma 迁往 Milvus / pgvector / Qdrant?

频率 ★★★★★ | 难度 高级

一句话结论

触发条件包括:向量规模超出单机内存与压测拐点、需要水平扩展与副本、需要强多租户隔离或成熟权限、过滤/混合检索能力不足;小规模且无上述诉求时保留 Chroma 更省运维。

概念解释

  • 规模拐点:单机内存/延迟无法满足 SLA。
  • 能力缺口:分布式副本分片、权限体系、复杂过滤、混合检索。
  • 目标选型:已在 PostgreSQL 体系选 pgvector;独立高并发选 Milvus/Qdrant 类专用库。

原理流程

盘点痛点(规模/并发/隔离/能力)→ 对照目标库能力
  → 同数据集基准测试 → 确定迁移目标 → 制定双写灰度方案

代码 / 命令

# 迁移信号清单:压测拐点 · 副本需求 · 租户隔离 · 过滤/混合检索缺口 · 合规审计要求
# 不凭热度选型:以自有数据集 recall/P99/内存对比为准

常见误区

  • 误区:一上来就迁分布式大库。正解:小规模保留轻量方案,避免过度运维成本。
  • 误区:迁移只迁向量。正解:原文、元数据、过滤字段与模型约定一起迁移。

追问

  • 问:pgvector 与独立向量库怎么选?答:已在 PG 生态、规模中等选 pgvector;高并发独立检索负载选专用库。
  • 问:迁移期间旧库保留多久?答:灰度观察一个完整业务周期,确认新库召回与延迟达标后下线。

05.6.5.2-030 迁移到目标库的步骤是什么?

频率 ★★★★☆ | 难度 高级

一句话结论

步骤为:导出四要素与模型元数据 → 目标库建集合/表并配置度量 → 批量导入 → 双写增量 → 召回与延迟对照 → 灰度切流 → 旧库下线。

概念解释

  • 导出:id、embedding、document、metadata 及模型/度量/版本记录。
  • 导入:目标结构映射,维度与度量对齐。
  • 校验:记录数、抽样点查、同查询 TopK 相关性、P99 对比。

原理流程

导出旧库 → 目标建结构 → 批量导入
  → 双写增量 → 对照召回/延迟 → 灰度切流 → 下线旧库

代码 / 命令

# 对账项:count 一致 · 维度一致 · 抽样命中一致 · 过滤条件行为一致
# 回滚:旧库保留可读,切流异常时回退

常见误区

  • 误区:迁移靠复制目录到新库。正解:不同存储格式不通用,必须导出重建。
  • 误区:导入完成即切全量。正解:先双写与影子读对照,再逐步切流。

追问

  • 问:增量怎么追平?答:切换前按变更日志双写,对账差异修复后再切。
  • 问:召回下降怎么排查?答:核对模型版本、归一化、度量、过滤字段与索引参数是否对齐。

05.6.5.2-031 常见坑:EF 不一致导致维度或检索报错?

频率 ★★★★★ | 难度 基础

一句话结论

集合建成后更换嵌入模型或混用自嵌与 EF,会造成维度不符或向量空间错位;表现为写入维度报错、查询近邻不相关,根治方式是统一模型并在必要时重建集合。

概念解释

  • 维度报错:新旧模型维度不同,写入被拒绝。
  • 空间错位:维度相同但模型不同,距离结果失真。
  • 根源:写入与查询两侧模型、版本、归一化未统一。

原理流程

排查报错 → 核对集合 EF/自嵌模型 → 对比历史向量维度
  → 确认混用 → 统一模型或新建集合全量重嵌

代码 / 命令

# 检查:集合模型版本记录 · 向量长度分布 · 查询侧模型配置

常见误区

  • 误区:换模型只改查询侧。正解:库内向量必须同步重嵌,否则两侧错位。
  • 误区:维度相同就一定兼容。正解:不同模型即使同维度也处于不同向量空间。

追问

  • 问:怎么提前发现模型漂移?答:登记模型版本,抽样核对向量模长与近邻相关性,升级模型走新集合灰度。
  • 问:报错信息看不出来源怎么办?答:分别用文本与自嵌向量写入测试,定位是哪一侧模型不匹配。

05.6.5.2-032 常见坑:where 字段类型不匹配?

频率 ★★★★☆ | 难度 进阶

一句话结论

metadata 字段存为字符串、过滤传数字(或反过来)会导致条件不命中;同一字段类型必须一致,过滤前核对存储类型与条件值类型。

概念解释

  • 类型不一致:等值/范围比较不命中,结果为空。
  • 字段缺失:未写该字段的记录不满足条件。
  • 混入原因:历史批次写入格式不一、脚本转换错误。

原理流程

过滤空结果 → 取样例记录查看字段类型
  → 对比 where 值类型 → 统一转换 → 批量修正 metadata

代码 / 命令

# 校验:抽样记录 metadata 键值类型分布
# 修正:读出记录 → 转换类型 → upsert 回写

常见误区

  • 误区:数字字符串能做大小比较。正解:字符串字典序与数字大小不同,范围条件必须用数字类型。
  • 误区:字段缺省等同于空值匹配。正解:缺字段记录不满足等值条件。

追问

  • 问:怎么防止类型再次漂移?答:写入前做字段类型校验,批量脚本统一转换逻辑。
  • 问:批量修正要注意什么?答:先小批验证过滤结果,再全量 upsert,保留旧记录对账。

05.6.5.2-033 常见坑:cosine 场景未归一化误用 ip?

频率 ★★★☆☆ | 难度 进阶

一句话结论

选了 ip 但向量未归一化,模长差异会拉大距离结果;cosine 与 ip 混用会让排序偏向模长大的向量,正确做法是按度量约定统一预处理。

概念解释

  • ip 受模长影响:模长大的向量内积占优,即使方向不最相似。
  • cosine 归一化:消除模长,只比较方向。
  • 约定:入库与查询使用同一份归一化函数。

原理流程

确定度量 → 入库前统一归一化(如度量需要)
  → 查询向量走同一预处理 → 同度量排序

代码 / 命令

# 核对:抽样向量模长分布;集合 hnsw:space 与预处理约定一致

常见误区

  • 误区:ip 就是余弦相似度。正解:未归一化时两者不等价。
  • 误区:查询侧归一化就行。正解:入库向量也要同样处理,两侧一致才有效。

追问

  • 问:怎么判断模长干扰了结果?答:对比归一化前后近邻排序变化,检查是否偏向少数长模长向量。
  • 问:度量选错能在线修吗?答:不能,需新建集合按正确约定重嵌。

05.6.5.2-034 常见坑:嵌入式目录被多个进程打开?

频率 ★★★★☆ | 难度 高级

一句话结论

多副本应用或多个脚本同时以嵌入式打开同一目录,缺乏写入协调,可能损坏存储或互相覆盖;正确做法是单进程独占目录,多实例改连独立服务端。

概念解释

  • 风险:并发写入无锁协调,文件状态不一致。
  • 场景:容器多副本挂同卷、开发脚本与服务同时跑、定时任务进程并发。
  • 排查:目录被谁打开、是否存在多实例挂载同一卷。

原理流程

发现存储异常 → 检查进程/副本对同一目录的访问
  → 收敛为单进程或迁移服务端模式
  → 从备份恢复一致性

代码 / 命令

# 部署检查:副本数 × 客户端形态 × 目录挂载是否唯一

常见误区

  • 误区:文件系统锁能自动保证嵌入式一致。正解:嵌入式存储不提供多进程分布式协调。
  • 误区:只读多开没问题。正解:读写混合场景仍有状态风险,需按实现核对。

追问

  • 问:必须多实例怎么办?答:部署独立 Chroma 服务端,应用实例以 HttpClient 接入。
  • 问:目录损坏怎么恢复?答:从最近备份或业务源数据重建集合,不尝试手工修复内部文件。

05.6.5.2-035 常见坑:大批量单次写入阻塞在线接口?

频率 ★★★☆☆ | 难度 进阶

一句话结论

在在线请求里同步跑全量批量嵌入与写入,会拖长请求、占满连接与内存;批量导入应走异步队列与离线任务,在线链路只做小批增量。

概念解释

  • 阻塞源:模型调用、向量写入、原文拼装都在请求线程内。
  • 资源:大批次占用内存与连接,并发下放大为线程堆积。
  • 分工:离线批量 + 在线增量,队列削峰。

原理流程

文档事件 → 异步队列 → 批量 worker 分批写入
  → 在线接口只提交任务或单篇增量 → 不等待全量构建

代码 / 命令

# 架构:生产者发消息 → 消费者分批 upsert → 失败重试落死信

常见误区

  • 误区:用户提交文档后必须同步看到检索结果。正解:可接受短暂索引窗口,异步构建并告知状态。
  • 误区:批次越大吞吐越高。正解:在线场景大批次放大超时与内存风险。

追问

  • 问:异步构建失败怎么补?答:任务持久化、失败重试与死信告警,按主键幂等重放。
  • 问:怎么衡量批量写入瓶颈?答:分批记录耗时与成功率,定位是模型调用还是写入慢。

05.6.5.2-036 常见坑:metadata 存长文本导致膨胀?

频率 ★★☆☆☆ | 难度 进阶

一句话结论

把整段说明、备注甚至原文塞进 metadata,会放大存储与过滤扫描成本;metadata 只存短标量字段,长文本放 document 或业务库。

概念解释

  • 膨胀来源:每条记录重复存储长文本、嵌套对象。
  • 过滤成本:逐条扫描大字段降低检索与遍历效率。
  • 正确划分:过滤维度标量化,长内容外置。

原理流程

梳理字段用途 → 过滤字段入 metadata(短标量)
  → 长文本入 document/业务库 → 记录 metadata 体积抽样核对

代码 / 命令

# 检查:metadata 平均键值长度、是否有大段文本与嵌套结构

常见误区

  • 误区:metadata 存得越全越方便。正解:非过滤字段入库存只增加成本,回业务库按 id 取更灵活。
  • 误区:嵌套对象不影响过滤。正解:复杂结构支持有限且存储膨胀。

追问

  • 问:已经塞了长文本怎么清理?答:批量读出,拆出长字段到业务库,metadata 只留标识,upsert 修正。
  • 问:标签列表怎么存?答:按版本支持情况核对,不支持数组则拆分或外置,过滤方案先验证。

05.6.5.2-037 检索延迟升高怎么排查?

频率 ★★★☆☆ | 难度 高级

一句话结论

按链路分段排查:查询侧模型调用、网络与客户端、索引候选规模、过滤扫描、资源饱和;先看 P99 与错误率,再逐段对照指标定位瓶颈。

概念解释

  • 分段:EF/模型服务 → 网络 → 索引检索 → 过滤 → 结果序列化。
  • 资源:CPU、内存、磁盘 IO、连接数。
  • 数据侧:候选规模、过滤选择性、原文长度。

原理流程

取慢请求样例 → 拆分各段耗时
  → 对照资源指标 → 定位瓶颈段 → 对症优化 → 回归压测

代码 / 命令

# 排查顺序:资源是否饱和 → 过滤是否过严 → 候选是否过大 → 模型/网络耗时

常见误区

  • 误区:延迟高就调大索引参数。正解:参数调大通常更慢,先定位瓶颈段。
  • 误区:只看平均延迟。正解:P99 尾延迟才代表在线体验。

追问

  • 问:模型服务慢怎么隔离?答:嵌入结果缓存、模型超时降级,区分模型耗时与库检索耗时。
  • 问:过滤导致慢怎么办?答:评估字段选择性、减少候选扫描,必要时调整集合划分。

05.6.5.2-038 过滤后候选不足 TopK 怎么处理?

频率 ★★★☆☆ | 难度 高级

一句话结论

过滤剔除候选后不足 K 条时,可适当放大召回候选、放宽低优先级条件,或接受少于 K 条并在应用层说明;不要在无候选时硬凑不相关结果。

概念解释

  • 原因:条件过严、后过滤候选不足、子集本身数据少。
  • 手段:增大 n_results、分层条件(强条件必带、弱条件放宽)。
  • 兜底:返回实际命中数,应用层提示检索范围。

原理流程

命中不足 → 检查过滤条件选择性
  → 放大候选重查 → 仍不足 → 放宽弱条件或返回实际条数

代码 / 命令

# 策略:强过滤(租户/权限)必带;弱过滤(标签/时间)可放宽
# 返回结构标注命中条数与是否截断

常见误区

  • 误区:不足 K 条就放宽权限/租户条件。正解:安全相关条件不能为凑结果放宽。
  • 误区:候选不足说明索引坏了。正解:多数是数据子集小或过滤过严。

追问

  • 问:怎么判断是数据少还是过滤问题?答:逐步去掉条件看命中增长,定位排除哪条条件后候选充足。
  • 问:业务要求必须 K 条怎么办?答:扩大候选与召回范围,相关性不足时交 rerank 与业务确认。

05.6.5.2-039 集合建成后索引参数还能在线调整吗?

频率 ★★★☆☆ | 难度 高级

一句话结论

度量与建图结构参数属于集合创建期定型,在线改通常不生效;搜索期参数是否支持运行期覆盖以版本实现为准(待确认),结构调整一律走新建集合迁移。

概念解释

  • 建库期:度量、M、构建候选,改了需要重建索引。
  • 查询期:搜索候选宽度,部分实现可运行期设置。
  • 变更路径:新集合 → 迁移 → 校验 → 切换。

原理流程

需求变更 → 区分结构参数/搜索参数
  → 结构参数:新建集合迁移 → 搜索参数:查是否支持运行期覆盖

代码 / 命令

# 核对:读取集合当前 metadata;变更前在测试集合验证参数可变性

常见误区

  • 误区:改 metadata 键值在线生效。正解:旧集合配置不会被新传入参数覆盖。
  • 误区:所有参数都能热调。正解:图结构类参数改动必须重建。

追问

  • 问:重建索引期间服务怎么办?答:旧集合继续服务,新集合并行构建,校验后切流。
  • 问:怎么确认参数已生效?答:读取集合配置与检索行为对照,不凭写入动作判断。

05.6.5.2-040 Docker 部署下索引参数与持久化要注意什么?

频率 ★★☆☆☆ | 难度 进阶

一句话结论

容器内索引参数随集合配置生效,持久化目录必须挂卷;容器重建不丢数据靠卷,参数与度量在建集合时确定,镜像升级前备份目录并回归。

概念解释

  • 持久化:目录映射到宿主机/命名卷,容器可重建。
  • 参数:集合 metadata 在建库时写入,不依赖容器环境默认值。
  • 升级:镜像版本与客户端版本匹配,旧目录兼容性核对发行说明。

原理流程

容器启动 → 挂持久卷 → 读取既有集合配置
  → 新建集合按约定参数 → 升级前备份 → 回归检索与过滤

代码 / 命令

# 部署要点:数据卷挂载 · 镜像标签锁定 · 启动健康检查 · 配置与环境分离

常见误区

  • 误区:容器内改参数会保留在镜像层。正解:数据在卷里,配置随集合持久化,镜像本身不含业务数据。
  • 误区:不挂卷重启后数据还在。正解:容器可写层随重建清空。

追问

  • 问:容器磁盘满了怎么查?答:看卷目录大小与单条占用,区分业务增长与日志/临时文件。
  • 问:多容器实例能共享同一卷吗?答:嵌入式多进程风险同前,应改独立服务端 + 多实例连接。

05.6.5.2-041 客户端与服务端版本怎么匹配?

频率 ★★☆☆☆ | 难度 进阶

一句话结论

HttpClient 与服务端接口协议要兼容,客户端版本滞后或超前都可能出现字段缺失、参数不识别或报错;升级时先核发行说明,预发回归后再滚动升级。

概念解释

  • 协议兼容:接口路径、参数名、返回结构在版本间可能调整。
  • 存储兼容:旧目录被新版本打开的能力以发行说明为准。
  • 升级顺序:服务端与客户端的兼容矩阵先核对。

原理流程

升级前读发行说明 → 备份目录
  → 预发升级 → 回归写入/检索/过滤/删除
  → 滚动升级客户端 → 观察错误率

代码 / 命令

# 核对:客户端版本 · 服务端版本 · 目录格式 · 配置项变更

常见误区

  • 误区:客户端随便升级都向后兼容。正解:跨大版本可能有接口破坏,需按兼容矩阵验证。
  • 误区:服务端升级不用回归老接口。正解:返回字段与过滤行为都可能变化。

追问

  • 问:版本不匹配报什么现象?答:连接成功但接口报错、参数被忽略、返回字段缺失。
  • 问:回滚怎么做?答:保留旧版本客户端/镜像与目录备份,回滚后校验记录数与检索。

05.6.5.2-042 检索结果为空的排查清单是什么?

频率 ★★★☆☆ | 难度 基础

一句话结论

按「记录是否入库 → 向量/模型是否一致 → 过滤条件是否排除 → 查询向量是否正确 → 集合是否选错」逐项排查,先去掉过滤与查询变量定位环节。

概念解释

  • 入库侧:count 是否增长、记录 id 能否点查。
  • 向量侧:模型/维度/归一化是否一致。
  • 查询侧:where/where_document 条件、集合名、查询文本向量化。

原理流程

get(ids) 确认记录存在
  → 去掉 where 做纯向量 query → 有结果则过滤问题
  → 仍空:核对模型/维度/集合 → 最后检查查询向量生成

代码 / 命令

# 排查顺序:点查存在性 → 纯向量检索 → 过滤条件 → 模型与集合 → 查询向量

常见误区

  • 误区:空结果一定是索引没建好。正解:多数情况是过滤条件、模型不一致或集合选错。
  • 误区:直接加大 n_results 解决。正解:候选不足只是表象,先定位排除原因。

追问

  • 问:点查存在但向量检索为空?答:重点查模型版本、维度、归一化与度量是否一致。
  • 问:纯向量有结果但带过滤为空?答:检查字段名、类型与记录 metadata 是否真的写入。

05.6.5.2-043 批量查询与循环单条查询怎么选?

频率 ★★☆☆☆ | 难度 进阶

一句话结论

批量查询减少往返与元数据开销,适合相似请求集中处理;循环单条便于隔离失败与逐条限流,但连接往返开销高。按请求到达模式与批量大小压测选择。

概念解释

  • 批量:一次提交多条 query,共享连接与调度,吞吐更高。
  • 单条:失败隔离清晰,适合异步逐条链路。
  • 权衡:批量内存与单次请求规模,失败重试粒度。

原理流程

请求聚集 → 组批查询 → 结果按下标对齐
  → 分散实时请求 → 单条查询 + 连接复用

代码 / 命令

# 批量:控制批大小;失败按批重试或拆批重试
# 单条:复用客户端连接,避免每条新建连接

常见误区

  • 误区:批量一定更快。正解:批过大会拉长单次延迟、占用内存,尾延迟可能变差。
  • 误区:单条循环天然安全。正解:不控制并发会打爆连接与服务端。

追问

  • 问:批量结果部分失败怎么办?答:按查询下标定位失败项,单独重试,不整批重跑。
  • 问:在线接口适合批量吗?答:实时单条为主,后台分析任务适合批量。

05.6.5.2-044 多用户场景下权限过滤怎么落地?

频率 ★★★☆☆ | 难度 高级

一句话结论

权限标识存入记录 metadata,每次检索强制携带用户可见范围条件;应用层先鉴身份再注入过滤条件,不能依赖用户自行传过滤参数,集合隔离按 SLA 分级。

概念解释

  • 过滤字段:租户、角色、文档可见范围标识。
  • 强制注入:服务端从身份会话推导条件,不信任前端传入。
  • 隔离层级:共享集合过滤 → 独立集合 → 独立部署。

原理流程

用户身份 → 鉴权 → 推导可见范围条件
  → 注入 where → 检索 → 结果二次校验权限

代码 / 命令

# 条件由服务端生成,例如 where={"tenant": current_tenant, "acl": {"$in": visible_roles}}

常见误区

  • 误区:前端传 tenant 参数即可。正解:可被篡改,必须服务端从会话推导。
  • 误区:向量结果返回后无需再校验。正解:候选与结果都要过权限边界,防止过滤实现漏洞。

追问

  • 问:文档级权限怎么实现?答:权限标识入 metadata 过滤;复杂 ACL 回业务库校验后补过滤。
  • 问:大租户怎么隔离?答:独立集合或独立部署,避免共享集合被拖慢与越权风险。

05.6.5.2-045 文档更新后向量重建链路怎么设计?

频率 ★★★☆☆ | 难度 进阶

一句话结论

原文变更后必须重新嵌入并 upsert 对应切片;链路包括变更事件、重新切块、重嵌、按稳定 id 更新、旧切片清理与抽样校验,元数据单独变更不重算向量。

概念解释

  • 触发:文档内容修改产生变更事件。
  • 流程:新切块 → 重嵌 → 稳定 id upsert → 删除被替换的旧切片。
  • 例外:仅状态/来源等标量字段变更,不需要重算向量。

原理流程

文档变更事件 → 重新切块 → 模型重嵌
  → 按 doc_id 定位旧切片 → 删除旧切片 → upsert 新切片
  → 抽样检索校验

代码 / 命令

# id 规则:doc_id + 切片序号,保证新旧切片可对应
# 校验:旧切片不可检索,新切片按内容可命中

常见误区

  • 误区:只改 metadata 也要重嵌。正解:标量字段变更走 update,不触碰向量。
  • 误区:新切片直接追加不删旧切片。正解:旧内容残留会被检索到,造成上下文陈旧。

追问

  • 问:增量重嵌失败怎么补?答:任务持久化,按文档 id 对账重放,保留失败清单。
  • 问:批量重嵌用什么链路?答:离线批次 upsert,在线只处理少量更新,避免阻塞请求。

05.6.5.2-046 压测方法与基线指标怎么定?

频率 ★★★☆☆ | 难度 高级

一句话结论

用真实分布数据集与查询集压测,固定维度、度量与批次,记录 QPS、P50/P99、召回、内存与目录增长;先建暴力/已知金标准基线,再对比索引参数与并发下的表现。

概念解释

  • 数据集:向量数、维度、原文长度、metadata 分布贴近线上。
  • 指标:吞吐、延迟分布、召回、资源占用。
  • 对照:不同索引参数、批次大小、并发数的横向对比。

原理流程

准备真实样本与查询集 → 金标准基线
  → 阶梯并发加压 → 记录指标 → 找拐点与达标参数

代码 / 命令

# 压测记录:规模 · 并发 · 批次 · QPS · P99 · recall · 内存 · 目录大小
# 结论必须带数据集与条件,不移植到其他分布

常见误区

  • 误区:随机向量 + 合成查询就能定生产参数。正解:分布失真,召回与延迟结论不可靠。
  • 误区:只测纯向量检索。正解:过滤、批量写入与回显路径都要纳入压测。

追问

  • 问:召回基线怎么建?答:小批量用精确检索结果作金标准,对比 ANN TopK 重合度。
  • 问:压测环境要等比生产吗?答:硬件配置接近,数据可缩比但分布一致,结论按比例外推并留余量。

05.6.5.2-047 Chroma 适合与不适合的场景分别是什么?

频率 ★★★★☆ | 难度 基础

一句话结论

适合原型验证、中小规模知识库、单进程或单服务端的 RAG 与内部工具;不适合海量向量高并发、强多租户权限、需要副本分片与成熟混合检索的生产核心场景。

概念解释

  • 适合:快速接入、生态集成简单、数据量在单机可承载范围。
  • 不适合:分布式扩展诉求、严格隔离与审计、复杂过滤与全文混合检索。
  • 判断:以压测拐点与能力缺口为准,不凭产品热度下结论。

原理流程

列需求(规模/并发/隔离/检索能力)→ 对照适合边界
  → 满足则保留 → 出现缺口信号 → 规划迁移

代码 / 命令

# 场景核对表:规模 · 更新频率 · QPS · 过滤复杂度 · 租户隔离 · 混合检索需求

常见误区

  • 误区:Chroma 只能做 Demo 不能上生产。正解:中小规模、可接受单点与备份约束的内部场景可以使用。
  • 误区:所有 RAG 都该上分布式库。正解:小规模上分布式会增加无谓运维成本。

追问

  • 问:内部工具数据敏感怎么办?答:网络隔离、鉴权前置、脱敏与访问审计,不依赖库内置能力。
  • 问:未来可能增长怎么预留?答:数据模型保留导出路径,metadata 字段设计可迁移到目标库。

05.6.5.2-048 设计一条基于 Chroma 的 RAG 检索链路,列出关键环节与踩坑对照?

频率 ★★★★★ | 难度 高级

一句话结论

完整链路为:切块与元数据设计 → 统一嵌入模型与度量 → 离线批量 + 在线增量写入 → 强制权限过滤检索 → 候选聚合去重 → rerank 精排 → 上下文拼装;每个环节对照常见坑与校验指标。

概念解释

  • 输入:文档量与切片数、维度、查询模式、过滤维度、SLA(召回与 P99)。
  • 关键决策:集合划分、EF/自嵌、度量与归一化、过滤字段、批量与重试、备份与迁移预案。
  • 交付物:链路设计、参数基线、监控指标、bad case 排查路径与扩容/迁移触发条件。

原理流程

1) 切块与 doc_id/metadata 设计  2) 固定模型版本与度量约定
3) 批量入库 + 在线增量 upsert   4) 检索:权限过滤 + 向量召回
5) 分组去重 + rerank 精排       6) 上下文拼装与引用回链
7) 监控召回/P99/内存/目录       8) 预留导出迁移路径

代码 / 命令

# 踩坑对照:模型一致 → 维度/空间校验;类型一致 → 字段类型校验
# 过滤强制 → 服务端注入;批量异步 → 不阻塞在线;备份可重建 → 恢复演练

常见误区

  • 误区:链路设计只写检索一步。正解:切块、嵌入、写入、过滤、rerank 与回显每步都影响最终答案。
  • 误区:忽略引用回链与权限。正解:片段来源可追溯、结果权限二次校验是 RAG 落地的必要环节。

追问

  • 问:bad case 怎么定位?答:沿链路拆分:未召回到、召回不相关、排序靠后、上下文拼装或生成误用,分别对应检索与生成环节。
  • 问:怎么验证链路达标?答:标注查询集评估召回与相关性,压测 P99 与资源占用,并定期跑恢复演练。

参考来源