05.6.5.1 架构部署与集合管理
所属:全栈开发面试题库 / 05 数据库与存储 / 05.6 向量数据库与语义检索 / 05.6.5 Chroma
覆盖范围
- Chroma 的定位、适用规模与不适用场景
- 嵌入式 PersistentClient、临时内存 Client、HttpClient 三种形态差异
- 服务端启动、Docker 部署、持久化目录与卷挂载
- collection 概念、命名与生命周期管理
- ids / embeddings / documents / metadatas 四要素与 add / update / upsert / delete 语义
- embedding_function 注入与自提供向量的边界
- 集合元数据、维度一致性、模型切换代价、多租户与鉴权现状
- 备份迁移、版本兼容、单机上限、进程模型与生态耦合
部署与数据模型主线
Client 层:PersistentClient(嵌入式)/ 内存 Client / HttpClient(连服务端)
↓
Collection(name + embedding_function + metadata)
↓
记录四要素:id · embedding · document · metadata
↓
写入语义:add(新增)/ update(局部更新)/ upsert(存在则改、不存在则增)/ delete
高频题速览
| 编号 | 题目 | 难度 | 频率 |
|---|---|---|---|
| 05.6.5.1-001 | Chroma 定位与适用规模 | 基础 | ★★★★★ |
| 05.6.5.1-002 | PersistentClient 嵌入式模式 | 基础 | ★★★★★ |
| 05.6.5.1-007 | 三种部署形态对比与选择 | 进阶 | ★★★★★ |
| 05.6.5.1-010 | 四要素 ids/embeddings/documents/metadatas | 基础 | ★★★★★ |
| 05.6.5.1-011 | add 写入语义 | 基础 | ★★★★★ |
| 05.6.5.1-013 | upsert 语义 | 进阶 | ★★★★★ |
| 05.6.5.1-018 | 维度一致性约束 | 进阶 | ★★★★★ |
| 05.6.5.1-024 | 多租户实现方式 | 高级 | ★★★★☆ |
| 05.6.5.1-030 | 嵌入式能否被多进程访问 | 高级 | ★★★★☆ |
| 05.6.5.1-048 | 中小规模 RAG 部署与集合设计 | 高级 | ★★★★★ |
05.6.5.1-001 Chroma 的定位是什么,什么场景该选它?
频率 ★★★★★ | 难度 基础
一句话结论
Chroma 是面向原型验证与中小规模 RAG 的开源向量库,开箱即用、API 简单、与 LangChain/LlamaIndex 生态紧耦合;大规模、高并发、强多租户与生产级副本分片不应以它为最终形态。
概念解释
- 定位:嵌入式即可运行的向量存储,负责向量、原文片段与元数据的存取和近邻检索。
- 优势:接入门槛低、集合模型直观、默认内置 embedding function,适合 Demo、课程、内部工具与中小知识库。
- 边界:不是分布式数据库,不提供完整的副本分片、强隔离多租户与企业级鉴权(能力随版本演进,以官方文档为准)。
原理流程
选型判断:向量规模 → 更新频率 → 并发与隔离要求 → 运维能力
中小规模 + 快速原型 → Chroma
海量向量 / 高并发 / 强租户隔离 → 生产级向量库或自建检索服务
代码 / 命令
# 面试表达模板
# 1) 说明目标规模与 QPS 2) 说明过滤与租户需求 3) 说明可接受的运维复杂度
# 4) 判断 Chroma 是否够用 5) 给出规模增长后的迁移预案
常见误区
- 误区:Chroma 可以当作生产分布式向量库直接承载十亿级向量。正解:它的设计取向是轻量嵌入,超大规模需要换专门的向量库。
- 误区:用了 Chroma 就不需要业务库。正解:业务主数据仍在关系型库,Chroma 只保留检索所需的向量、片段与元数据。
追问
- 问:Chroma 与 Faiss 的区别?答:Faiss 是纯检索算法库,不存原文与元数据;Chroma 是带存储与集合模型的向量库,但底层检索能力可参考同类索引实现。
- 问:什么信号说明该离开 Chroma?答:单机内存与磁盘逼近上限、并发延迟不可控、需要独立副本分片或强权限隔离时。
05.6.5.1-002 PersistentClient 嵌入式模式是怎么工作的?
频率 ★★★★★ | 难度 基础
一句话结论
PersistentClient 在应用进程内直接打开一个本地持久化目录,数据随目录落盘,进程退出后再次打开仍可读,适合单进程应用与本地原型。
概念解释
- 嵌入式:客户端库直接持有存储,不经过独立服务进程,调用是进程内函数调用。
- 持久化:指定本地目录作为数据根,集合、向量、原文与元数据写入该目录。
- 适用:单进程 Web 服务、脚本、本地知识库;不适合多个进程同时读写同一目录。
原理流程
应用启动 → PersistentClient(path=持久化目录)
→ 打开/创建目录存储 → 取或建 collection → 读写记录
进程退出 → 数据保留在目录中 → 下次启动按同一路径打开
代码 / 命令
# Python SDK 形态(方法名以当前版本文档为准)
# import chromadb
# client = chromadb.PersistentClient(path="./chroma_data")
# collection = client.get_or_create_collection(name="kb")
常见误区
- 误区:PersistentClient 是独立服务。正解:它是进程内嵌入式客户端,数据目录由当前进程管理。
- 误区:持久化目录可以被多个应用实例同时打开。正解:嵌入式存储同一目录被多进程并发打开存在损坏风险,服务化场景应改用 HttpClient 连独立服务。
追问
- 问:path 用相对路径还是绝对路径?答:代码内可配置;部署时由环境变量或启动参数决定数据目录位置,避免依赖调用者当前工作目录。
- 问:嵌入式模式能横向扩展吗?答:不能。扩缩容要把数据目录迁移到服务端形态,或改用分布式向量库。
05.6.5.1-003 临时(内存)Client 有什么特点,什么时候用?
频率 ★★★☆☆ | 难度 基础
一句话结论
内存 Client 把数据放在进程内存中,不做磁盘持久化,进程结束数据即失,只适合单元测试、快速演示与临时计算。
概念解释
- 生命周期:数据仅存在于当前进程内存,重启后为空。
- 用途:测试隔离、算法验证、一次性批量检索实验。
- 风险:误把内存 Client 用于生产会在重启后丢失全部向量与片段。
原理流程
Client()(无持久化路径)→ 内存集合 → 读写
进程退出 → 内存释放 → 数据不可恢复
代码 / 命令
# 测试或演示形态(方法名以当前版本文档为准)
# client = chromadb.Client()
# 每个测试方法独立 Client,避免用例间数据串扰
常见误区
- 误区:内存 Client 也会自动落盘。正解:不落盘,重启即空。
- 误区:内存 Client 比持久化快就该上线。正解:快是因为没有持久化与恢复保障,生产场景必须评估可恢复性。
追问
- 问:内存 Client 支持并发多进程吗?答:数据在单进程内存中,不提供跨进程共享。
- 问:测试中如何构造可重复数据?答:每个用例重新写入固定样本,不依赖上一次运行残留。
05.6.5.1-004 HttpClient 客户端-服务端模式怎么连?
频率 ★★★★☆ | 难度 基础
一句话结论
HttpClient 连接一个已启动的独立 Chroma 服务端,应用进程只发网络请求;多个应用实例可以共用同一个服务端,是服务化部署的基础形态。
概念解释
- 客户端-服务端:存储与索引在服务端进程,客户端通过网络接口访问。
- 解耦:应用可多实例接入,重启应用不直接影响数据文件。
- 前提:服务端进程存活、网络可达、端口与版本匹配。
原理流程
独立服务端启动并监听端口
→ HttpClient(host, port) 建立连接
→ 集合与记录操作经网络发往服务端
→ 服务端读写自身持久化目录后返回结果
代码 / 命令
# 客户端连接形态(参数名以当前版本文档为准)
# client = chromadb.HttpClient(host="chroma-host", port=8000)
# 注意:host/port 通过配置注入,不在代码里写死环境地址
常见误区
- 误区:HttpClient 与 PersistentClient 只是写法不同、可以随便互换。正解:前者数据在远端服务,后者在本地目录,备份、扩容与故障域都不同。
- 误区:客户端断连后本地有缓存兜底。正解:嵌入式才有本地存储,HttpClient 的数据全部在服务端。
追问
- 问:服务端宕机时客户端表现?答:连接与请求失败,需要超时、重试与熔断,不能假设永不掉线。
- 问:多实例应用共用一个服务端要注意什么?答:连接数、并发与集合命名隔离,避免不同应用互相覆盖同名集合。
05.6.5.1-005 服务端怎么启动,Docker 部署要点是什么?
频率 ★★★★☆ | 难度 基础
一句话结论
服务端既可通过 CLI 命令启动并指定持久化目录,也可用官方镜像以容器方式运行;容器化的关键是把数据目录挂持久卷,否则容器重建即丢数据。
概念解释
- CLI 启动:服务端进程绑定本地目录与端口,供 HttpClient 接入。
- 容器部署:镜像内服务进程监听默认端口,数据目录必须映射到宿主机卷或命名卷。
- 健康检查:启动后要验证端口可达、能建集合、能写入并检索一条样本。
原理流程
准备持久化目录 → 启动服务端(绑定目录与端口)
→ 容器场景:目录挂卷 → 客户端连通性验证
→ 写入一条样本 → 检索命中 → 部署完成
代码 / 命令
# 容器启动形态(镜像名与端口以官方当前发布为准)
# docker run -d --name chroma -p 8000:8000 -v <host_data_dir>:/chroma/chroma <chroma-image>
# 验证:访问健康接口 → 建集合 → add 一条 → query 命中
常见误区
- 误区:容器内数据目录不挂卷也能长期跑。正解:容器重建后数据目录清空,必须挂持久卷。
- 误区:端口映射冲突无所谓。正解:宿主端口被占用会导致服务端无法监听,客户端连不上。
追问
- 问:镜像版本怎么锁定?答:生产使用明确标签,不使用浮动 latest,便于回滚与版本核对。
- 问:容器内时区与日志要注意什么?答:日志时间与归档按宿主机/容器配置对齐,排障时能按时间还原写入顺序。
05.6.5.1-006 持久化目录与数据卷怎么规划?
频率 ★★★★☆ | 难度 进阶
一句话结论
持久化目录要单独规划容量、备份权限与 IO 位置,目录内文件由服务端管理,应用不要手工改名或挪动;目录损坏会影响全部集合。
概念解释
- 目录内容:集合定义、向量、原文片段、元数据及索引相关文件,具体文件构成随版本演进(待确认,以官方存储文档为准)。
- 容量:向量数 × 维度 × 单维字节,加上索引结构、原文与元数据的额外占用。
- 权限:目录读写权限只授予运行服务的用户,避免误删与越权访问。
原理流程
估算向量规模与原文大小 → 规划目录容量与余量
→ 挂载独立卷 → 配置目录归属与权限
→ 定期备份目录 → 恢复演练验证可读
代码 / 命令
# 规划清单:向量数 · 维度 · 单条原文长度 · 元数据字段
# 容量 = 向量占用 + 索引结构 + 原文与元数据 + 版本余量
# 备份 = 目录快照 + 恢复后抽样检索校验
常见误区
- 误区:把持久化目录放在临时目录或容器可写层。正解:临时层会被清理,必须落持久卷。
- 误区:目录里的文件可以按文本方式直接编辑修复。正解:内部文件结构由服务端管理,手工改动可能导致集合无法打开。
追问
- 问:目录空间增长怎么观察?答:定期统计目录大小与集合记录数,对比单条平均占用,提前扩容。
- 问:多个环境能否共用一个目录?答:不能。开发、预发、生产各自独立目录,避免串数据与误删。
05.6.5.1-007 嵌入式、内存、服务端三种形态怎么选?
频率 ★★★★★ | 难度 进阶
一句话结论
按「进程数、持久化需求、并发接入与运维能力」选择:单进程本地用 PersistentClient,测试用内存 Client,多实例或独立部署用 HttpClient 连服务端。
概念解释
- PersistentClient:单进程、需要落盘、部署简单。
- 内存 Client:无持久化、临时隔离、测试与演示。
- HttpClient:多实例共享、数据独立于应用进程、需要运维一个服务端。
- 切换代价:形态变更涉及数据目录导出导入,不是改一行配置那么简单。
原理流程
是否需要持久化? 否 → 内存 Client
需要持久化且单进程 → PersistentClient
需要多实例接入或独立故障域 → HttpClient + 服务端
规模增长超出服务端能力 → 评估迁移专用向量库
代码 / 命令
# 选型核对项:进程数量 · 重启后数据是否保留 · 并发连接数 · 备份方式 · 扩容路径
# 面试表达:先列约束,再给形态,最后说切换与迁移预案
常见误区
- 误区:开发用嵌入式、生产也沿用嵌入式。正解:生产多实例部署应评估服务端形态,避免单进程数据目录被多实例争抢。
- 误区:服务端形态天然支持高可用。正解:单服务端仍是单点,副本与容灾能力要看产品版本与部署方案。
追问
- 问:从嵌入式迁到服务端怎么做?答:把旧目录数据按导出流程搬到新服务端持久化目录,校验记录数与抽样检索后再切客户端。
- 问:服务端形态的备份对象是什么?答:服务端持久化目录,而不是应用进程内存。
05.6.5.1-008 collection 是什么,命名有什么规则?
频率 ★★★★☆ | 难度 基础
一句话结论
collection 是向量、原文与元数据的逻辑容器,每个集合绑定自己的 embedding function 与索引配置;命名需唯一且符合 SDK 与后端允许的字符约束,不能靠大小写或空格区分近似集合名。
概念解释
- 容器职责:集合内记录共享同一套向量维度、距离度量与元数据结构约定。
- 命名:在同一客户端作用域内唯一,作为 get/delete/rename 的定位标识。
- 约束:非法字符、过长名称或与保留名冲突会在建集合时失败,具体允许字符集以当前版本文档为准(待确认)。
原理流程
确定知识库/业务域 → 命名集合(可带业务前缀与环境标识)
→ create 或 get_or_create → 后续按名称定位
→ 不同业务域或不同模型版本使用不同集合
代码 / 命令
# 命名建议:业务前缀 + 用途 + 模型/版本后缀
# 例如 kb-product-2026q3;避免仅用 test、临时名长期留在生产
# 同名重复创建的行为取决于接口:create 冲突报错,get_or_create 复用已有集合
常见误区
- 误区:一个集合里可以混用不同维度的向量。正解:同一集合维度必须一致,换维度要另建集合并迁移。
- 误区:集合名可以随便改不影响数据。正解:重命名影响所有按名称引用的客户端与脚本。
追问
- 问:一个应用建多少集合合适?答:按业务域、隔离需求或模型版本划分,集合过多会增加管理与元数据负担。
- 问:集合名要带环境标识吗?答:建议带,避免开发脚本误连生产同名集合。
05.6.5.1-009 create_collection、get_or_create_collection、get_collection 有什么区别?
频率 ★★★★★ | 难度 基础
一句话结论
create 只负责新建,同名已存在会冲突;get 只负责取已有集合,不存在会报错;get_or_create 取已有或新建,是启动时最常用的幂等入口。
概念解释
- create_collection:显式建集合,用于需要确认集合不存在的初始化场景。
- get_collection:按名称取已有集合,适合启动后校验与复用。
- get_or_create_collection:幂等获取,集合不存在则创建,存在则返回现有集合。
- 注意:get_or_create 复用时不会把新传入的配置覆盖到已有集合。
原理流程
启动 → get_or_create(name, embedding_function, metadata)
→ 存在:返回原集合(配置以原集合为准)
→ 不存在:按传入配置创建
显式场景:create(要求不存在)/ get(要求存在)
代码 / 命令
# 幂等启动形态(方法名以当前版本文档为准)
# collection = client.get_or_create_collection(
# name="kb", embedding_function=ef, metadata={"hnsw:space": "cosine"})
# 排查:配置不生效时先确认返回的集合是不是旧集合
常见误区
- 误区:get_or_create 传入新 metadata 会更新旧集合配置。正解:复用旧集合时配置不被覆盖,改配置需要重建集合。
- 误区:create 冲突时会自动返回旧集合。正解:冲突按报错处理,需先确认集合是否存在。
追问
- 问:如何避免旧集合参数与预期不一致?答:启动时读取集合 metadata 与维度,与配置基线比对,不一致则告警或走重建流程。
- 问:初始化脚本该用哪个?答:需要幂等重复执行用 get_or_create;需要严格校验环境用 get + 显式 create 两步。
05.6.5.1-010 记录的 ids、embeddings、documents、metadatas 四要素分别是什么?
频率 ★★★★★ | 难度 基础
一句话结论
每条记录由唯一 id、向量 embedding、原文片段 document、元数据 metadata 组成;id 定位记录,embedding 参与相似度计算,document 提供回显片段,metadata 承载过滤字段。
概念解释
- ids:记录主键,字符串或可接受的标识类型,用于增删改与点查。
- embeddings:与集合维度一致的浮点向量;也可只给 document 由 embedding function 生成。
- documents:原始文本片段,检索回显与 where_document 过滤的对象。
- metadatas:键值对元数据,供 where 过滤与业务关联,不参与向量距离计算。
原理流程
写入:id + document(+ EF 生成 embedding)+ metadata
检索:query 向量 → 近邻 → 返回 id / document / metadata / 距离
点查:按 id 定位 → 取回对应四要素
代码 / 命令
# 写入记录四要素(字段名以当前版本文档为准)
# collection.add(
# ids=["doc-001"],
# documents=["片段文本"],
# metadatas=[{"source": "manual", "tenant": "t1"}],
# embeddings=[[...float32 向量...]])
常见误区
- 误区:metadata 里存长原文有利于检索。正解:长文本应放 document,metadata 存短标量字段,否则过滤与存储都膨胀。
- 误区:id 可以重复出现。正解:id 在集合内唯一,重复行为取决于写入接口语义(见 add/upsert 题)。
追问
- 问:哪些要素是必填?答:至少需要 id 与可产生向量的来源(自嵌向量或 document + EF);document 与 metadata 视业务需要提供。
- 问:metadata 能存数组吗?答:支持的取值类型随版本而定(待确认),复杂结构建议拆成标量字段或外置业务库。
05.6.5.1-011 add 写入的语义是什么?
频率 ★★★★★ | 难度 基础
一句话结论
add 用于新增记录;若传入已存在的 id,行为按接口约定处理(重复 id 是否覆盖或报错需以当前版本文档为准,待确认),因此幂等写入应优先评估 upsert。
概念解释
- 新增语义:每条记录携带 id、向量来源与元数据写入集合。
- 批量:add 支持一次传入多条记录,单批大小需结合内存与超时控制。
- 一致性:写入成功后记录进入集合,可见性取决于存储实现与刷新节奏(见写入可见性题)。
原理流程
准备批量记录(ids/documents/metadatas/embeddings)
→ 校验维度与字段类型 → add 写入
→ 返回写入状态 → 抽样按 id 点查确认
代码 / 命令
# 批量 add 形态(字段名以当前版本文档为准)
# collection.add(ids=batch_ids, documents=batch_docs, metadatas=batch_meta)
# 幂等与重试:按业务主键控制,避免重复批次产生重复记录
常见误区
- 误区:add 可以安全地重复执行。正解:重复 id 的处理未确认前,重复执行可能产生冲突或重复记录,幂等场景用 upsert。
- 误区:单批越大效率越高。正解:过大批次占用内存、拉长请求并提高失败重试成本,应分批写入。
追问
- 问:add 时不带 embeddings 怎么办?答:由集合绑定的 embedding function 对 documents 生成向量;自嵌场景则必须提供与维度一致的向量。
- 问:写入失败如何重试?答:按 id 幂等重试,记录失败批次并核对已写入部分,避免半截批次难以对账。
05.6.5.1-012 update 的语义是什么,与 add 有何不同?
频率 ★★★★☆ | 难度 进阶
一句话结论
update 针对已存在的 id 做局部字段更新;不存在的 id 不会自动补插,未传入的字段保持不变,因此它不是全量覆盖接口。
概念解释
- 局部更新:可单独更新 document、embedding 或 metadata,不需要重传整条记录。
- 前提:目标 id 必须存在,否则按接口约定处理(待确认是否报错或忽略)。
- 边界:换 embedding 时要保证新向量维度与集合一致;metadata 更新是键值合并还是整体替换,以版本文档为准(待确认)。
原理流程
定位已存在 id → 传入需要变更的字段(document/embedding/metadata)
→ 服务端局部更新 → 点查回读比对字段
代码 / 命令
# 局部更新形态(字段名以当前版本文档为准)
# collection.update(ids=["doc-001"], documents=["新片段"], metadatas=[{"status": "updated"}])
# 先 get 确认 id 存在,再 update;不存在的记录改走 upsert
常见误区
- 误区:update 能把不存在的记录补进去。正解:不存在时应使用 upsert,不能依赖 update 自动插入。
- 误区:update 不传 metadata 会清空旧 metadata。正解:是否保留旧字段取决于实现,先回读确认再批量执行。
追问
- 问:原文改了之后向量要不要重算?答:document 内容变更后语义已变,需要重新生成 embedding 再更新,否则向量与原文不匹配。
- 问:metadata 字段值变更需要重建索引吗?答:标量字段变更不改变向量索引结构,过滤侧可见性按存储实现为准。
05.6.5.1-013 upsert 的语义是什么,什么场景用它?
频率 ★★★★★ | 难度 进阶
一句话结论
upsert 是「存在则更新、不存在则插入」的幂等写入语义,适合增量同步、文档重切片与定时回填,避免先查后写的竞态。
概念解释
- 幂等:同一批记录重复执行,结果收敛到最终状态,不会凭空产生重复 id 记录。
- 覆盖范围:传入的字段在命中旧记录时被更新;未传字段的保留行为以版本文档为准(待确认)。
- 适用:业务主键已知的增量入库、模型重嵌入后的全量刷新。
原理流程
按 id 判断存在 → 存在:更新传入字段;不存在:插入新记录
→ 重复执行收敛到同一状态 → 抽样点查核对
代码 / 命令
# 幂等写入形态(方法名以当前版本文档为准)
# collection.upsert(ids=batch_ids, documents=batch_docs, metadatas=batch_meta)
# 定时同步:按业务主键 upsert,失败批次可安全重放
常见误区
- 误区:upsert 会把没传的 metadata 清空。正解:字段合并语义需先在测试环境验证,再批量执行。
- 误区:upsert 替代 delete。正解:被删除的业务文档不能靠 upsert 下线,必须显式 delete。
追问
- 问:全量重建时用 upsert 还是清空后 add?答:数据量大且需要在线保留时可按批次 upsert;彻底重建更稳妥的方式是建新集合双写、校验后切换。
- 问:upsert 后旧向量空间残留怎么办?答:索引与存储的压缩回收行为随实现而定(待确认),大规模删除更新后要观察集合体积与召回。
05.6.5.1-014 delete 的语义是什么,删除后多久不可检索?
频率 ★★★☆☆ | 难度 进阶
一句话结论
delete 按 id 删除记录;删除后该 id 不再参与检索与点查,空间是否立即回收取决于存储与索引实现,删除比例高时集合体积与召回可能受影响。
概念解释
- 删除定位:按 ids 列表删除,也可结合 where 条件按元数据删除(能力以版本文档为准,待确认)。
- 可见性:删除成功后新检索不应命中该记录;索引内部是否做物理清理不向调用方承诺即时回收。
- 合规:删除要覆盖向量、原文、元数据以及备份与缓存中的副本。
原理流程
确认待删 id 清单 → delete(ids=...)
→ 点查确认不存在 → 检索抽样确认未命中
→ 高比例删除后评估重建集合回收空间
代码 / 命令
# 删除形态(参数名以当前版本文档为准)
# collection.delete(ids=["doc-001"])
# 核对:get(ids=["doc-001"]) 返回空;query 结果不再出现该 id
常见误区
- 误区:delete 返回成功就等于磁盘空间释放。正解:内部回收是另一回事,空间占用要观察目录大小趋势。
- 误区:where 删除可以随意执行。正解:条件误写会批量删错记录,先 dry-run 列出命中 id 清单再执行。
追问
- 问:删除后能否误恢复?答:删除前保留导出快照;已删除记录在新集合重建时从业务源数据重新生成。
- 问:频繁删除更新的集合怎么维护?答:监控删除比例与召回,必要时导出全量、新建集合重写并切换。
05.6.5.1-015 embedding_function 是什么,在集合的哪一层注入?
频率 ★★★★★ | 难度 基础
一句话结论
embedding function 负责把文本转成向量,在创建集合时绑定;集合内所有由文本生成的向量都走这套函数,函数与模型版本必须全程一致。
概念解释
- 职责:接收 document 文本,输出固定维度的浮点向量。
- 绑定层级:集合级配置,创建时传入;默认内置一个本地 embedding function(具体模型名与版本随发布变化,待确认)。
- 一致性:集合建成后更换函数或模型,新旧向量不可混用。
原理流程
创建集合时传入 embedding_function
→ add/upsert 带 document 时调用 EF 生成向量
→ query 带文本时同一 EF 生成查询向量
→ 换模型必须新集合 + 全量重嵌
代码 / 命令
# 自定义 EF 注入形态(接口名以当前版本文档为准)
# collection = client.get_or_create_collection(name="kb", embedding_function=my_ef)
# 自嵌向量场景:写入与查询都直接提供 embeddings,EF 仅作为兜底
常见误区
- 误区:查询时可以换一个 EF 而不影响结果。正解:查询向量必须与库内向量同模型同空间,否则相似度无意义。
- 误区:默认 EF 在所有部署环境模型一致。正解:本地模型下载、版本与缓存路径不同会导致向量不一致,需固定模型版本。
追问
- 问:EF 在哪里执行?答:嵌入式在应用进程内执行;服务端形态下按客户端或服务端配置执行(待确认版本行为),要明确模型与网络依赖。
- 问:EF 调用失败怎么处理?答:写入与查询前检查 EF 可用性,超时降级并记录,不要让半截批次落库。
05.6.5.1-016 自提供 embeddings 与 EF 是什么关系?
频率 ★★★★☆ | 难度 进阶
一句话结论
可以在写入时直接提供 embeddings 跳过 EF 生成;但查询侧若提供 query_embeddings 就自嵌、提供 query_texts 才走 EF,两条路径不能混用不同模型。
概念解释
- 自嵌:应用自行调用模型生成向量,Chroma 只负责存储与检索,适合模型在外部服务统一管理的场景。
- EF 兜底:只给文本时由集合绑定的 EF 生成向量。
- 一致性约束:自嵌向量的维度、归一化方式与度量必须和集合约定一致。
原理流程
写入:有 embeddings 用自嵌;无则 document → EF 生成
查询:query_embeddings 直用;query_texts → EF 生成
→ 全链路核对:同一模型、同一版本、同一归一化约定
代码 / 命令
# 自嵌写入与查询形态(参数名以当前版本文档为准)
# collection.add(ids=[...], embeddings=[...], documents=[...])
# collection.query(query_embeddings=[...], n_results=5)
常见误区
- 误区:一部分记录自嵌、另一部分走默认 EF 没问题。正解:两套模型向量处于不同空间,近邻结果不可信。
- 误区:自嵌就可以不登记模型版本。正解:映射表或元数据里要记录模型与版本,便于排查与重嵌。
追问
- 问:模型服务故障时自嵌链路怎么办?答:向量在外部生成,Chroma 不重试模型调用;应用侧要做模型服务超时、重试与缓存。
- 问:自嵌向量需要归一化吗?答:取决于距离度量,cosine 场景的归一化约定要在入库前统一(见度量题)。
05.6.5.1-017 集合 metadata 存什么,哪些配置建成后不可改?
频率 ★★★★☆ | 难度 进阶
一句话结论
集合 metadata 承载索引参数与集合级标注;距离度量、索引空间参数等在建集合时确定,建成后调整通常需要重建集合,不能指望在线改参数生效。
概念解释
- 配置项:如 HNSW 空间与构建/搜索参数,键名以当前版本文档为准(待确认默认值)。
- 标注项:可记录模型版本、业务域、创建时间等便于运维的信息。
- 不可变边界:索引结构与度量在集合创建时定型,复用旧集合时新传入配置不会覆盖。
原理流程
建集合前确定度量与索引参数 → 写入 metadata
→ 运行期读取 metadata 核对基线
→ 需要改结构参数 → 新建集合 → 迁移数据 → 切换
代码 / 命令
# 集合级 metadata 形态(键名以当前版本文档为准)
# metadata={"hnsw:space": "cosine", "model": "emb-model-name", "version": "v1"}
# 变更参数:先建新集合,不在线改写旧集合索引
常见误区
- 误区:metadata 是自由键值,运行期随便加键不影响。正解:保留的索引配置键被误改会影响行为,自定义标注键与配置键要分开管理。
- 误区:建完集合还能在线换度量。正解:换度量等价于重建空间,必须迁移到新集合。
追问
- 问:怎么核对线上集合配置?答:读取集合 metadata 与预期基线比对,维度、度量、模型版本逐项校验。
- 问:参数默认值记不清怎么办?答:标注「待确认」,以官方文档与实测集合配置为准,不背诵未核实的默认值。
05.6.5.1-018 维度一致性约束是什么,违反会怎样?
频率 ★★★★★ | 难度 进阶
一句话结论
同一集合内所有向量必须是同一维度;混入不同维度的向量会在写入或检索时报错,维度由绑定模型或自嵌约定决定,不能在集合内逐条调整。
概念解释
- 维度来源:EF 输出维度固定,或自嵌向量的模型维度固定。
- 后果:维度不一致导致距离计算无法对齐,写入被拒绝或结果错乱。
- 变更方式:换模型/换维度要新建集合并全量重嵌,不能在原集合追加另一维度向量。
原理流程
创建集合 → 确定维度(EF 模型维度或约定维度)
→ 每条写入向量校验维度 → 不一致即拒绝
→ 换维度需求 → 新集合 → 全量重嵌 → 切换
代码 / 命令
# 校验:写入前检查 len(vector) == 集合预期维度
# 排查维度报错:核对模型版本、是否混用两套自嵌向量、历史残留集合
常见误区
- 误区:向量长度差一位也能跑,只是精度下降。正解:维度不同属于结构不兼容,不是精度问题。
- 误区:可以在旧集合上追加新模型的短向量。正解:新旧模型向量必须分集合存放。
追问
- 问:怎么发现线上维度已经被混用?答:抽样统计向量长度分布,结合写入报错与异常近邻结果定位。
- 问:降维后的向量能回填旧集合吗?答:不能,应另建集合;旧集合与新集合不做向量混用。
05.6.5.1-019 切换 Embedding 模型的代价是什么,怎么迁?
频率 ★★★★☆ | 难度 高级
一句话结论
换模型等于在新向量空间重建索引:旧集合向量与新模型向量不可混用,必须全量重新生成向量、建新集合、双写校验后灰度切换,不能只换查询侧模型。
概念解释
- 代价:需要遍历全部原文重新嵌入,消耗模型调用与存储;旧集合在迁移完成前保留。
- 不可混用:不同模型的向量分布与维度通常不同,混合入库会让检索失效。
- 收益:新模型领域匹配度更高,可改善召回质量。
原理流程
选新模型 → 新建空集合(新维度/新度量)
→ 从业务源原文批量重嵌写入新集合
→ 双写期新旧对照 → 抽样召回对比 → 灰度切查询到新集合 → 下线旧集合
代码 / 命令
# 迁移要点:源文档以业务库为准,不依赖旧集合反推原文
# 校验:两集合记录数一致;同查询对照 TopK 相关性;模型版本登记到 metadata
常见误区
- 误区:只把查询换成新模型,库内旧向量继续用。正解:查询与库内必须同模型,否则相似度失真。
- 误区:重嵌失败可以局部补几条。正解:全量重嵌要保留批次与对账,避免新旧记录混在同一集合。
追问
- 问:迁移期间要双写吗?答:增量文档在双写期同时写新旧集合,保证切换前新集合数据不落后。
- 问:怎么评估新模型值不值得迁?答:在同一查询标注集上对比新旧召回相关性与延迟,达标再执行全量迁移。
05.6.5.1-020 metadata 字段怎么设计?
频率 ★★★☆☆ | 难度 进阶
一句话结论
metadata 只放短标量过滤字段(来源、租户、时间、状态、权限标识),长文本与复杂结构外置业务库;字段命名稳定、类型一致,便于 where 过滤与对账。
概念解释
- 适合入库:枚举值、数字时间戳、短字符串标识、布尔状态。
- 不适合入库:大段正文、嵌套对象、高频变化的非过滤字段。
- 一致性:同一字段在不同记录中类型保持一致,避免过滤时类型不匹配。
原理流程
梳理过滤维度 → 拆成标量字段 → 规定取值类型与命名
→ 写入时校验类型 → 检索时按字段过滤
→ 复杂关联回业务库按 id 取
代码 / 命令
# 建议 metadata:{"tenant": "t1", "source": "manual", "status": "online", "updated_at": 1700000000}
# 避免:整段原文、多级嵌套、长度不可控的说明字段
常见误区
- 误区:metadata 越全越好,把业务字段都塞进来。正解:非过滤字段放业务库,减少存储膨胀与过滤扫描成本。
- 误区:同一字段今天存字符串明天存数字没关系。正解:类型混开会让过滤结果不稳定。
追问
- 问:需要权限过滤的字段放哪里?答:角色/租户/文档权限标识放 metadata 查询强制带条件,敏感本体仍由业务库与权限服务把关。
- 问:时间字段用什么格式?答:用可比较的时间戳或约定格式,保证范围过滤语义明确。
05.6.5.1-021 metadata 取值类型有哪些约束?
频率 ★★★☆☆ | 难度 进阶
一句话结论
metadata 键值以标量类型为主(字符串、数字、布尔等),复杂集合类型的支持程度随版本而定;过滤操作符只对标量值有明确语义,拿不准的类型先在测试环境验证。
概念解释
- 标量:等值、范围与集合归属过滤直接可用。
- 集合类型:是否支持数组字段及其操作语义需以当前版本文档为准(待确认)。
- 类型一致性:字段内类型不统一会导致过滤行为异常。
原理流程
定义字段类型 → 写入前校验 → 测试环境验证过滤操作符
→ 线上批量写入 → 抽样核对过滤命中结果
代码 / 命令
# 验证清单:字符串等值 / 数字范围 / 布尔 / 集合归属 各跑一条样例
# 不支持的复杂结构:落到业务库,metadata 只存外键标识
常见误区
- 误区:metadata 能存任意 JSON 对象并按嵌套路径过滤。正解:嵌套路径过滤能力未确认,不要在生产依赖未验证的写法。
- 误区:数字存成字符串也能范围比较。正解:字符串比较与数字范围语义不同,类型必须对齐。
追问
- 问:字段支持哪些操作符?答:等值、不等、集合归属、大小比较与逻辑组合,具体操作符名在过滤页展开,以版本文档为准。
- 问:类型存错了怎么修?答:批量读出转换类型后 upsert 修正,先小批量验证过滤结果。
05.6.5.1-022 count 与 peek 用来做什么?
频率 ★★☆☆☆ | 难度 基础
一句话结论
count 返回集合记录总数,用于容量观察与对账;peek 取少量样例记录,用于结构抽查与演示,不能替代正式分页查询。
概念解释
- count:集合规模的快速口径,写入/删除后用于核对批次数量。
- peek:返回有限样例,方便开发时查看 document/metadata 形态。
- 边界:peek 不是按相似度检索,也不保证返回最新或代表性数据。
原理流程
对账:写入批次后 count 对比预期条数
抽查:peek 查看样例字段完整性
正式遍历:用 get 配合 limit/offset 分页
代码 / 命令
# 形态(方法名以当前版本文档为准)
# total = collection.count()
# sample = collection.peek(limit=5)
常见误区
- 误区:peek 返回的是最相关的记录。正解:它只是样例抽样,不代表检索排序结果。
- 误区:count 可以当作精确的实时并发口径。正解:计数口径受写入删除节奏影响,对账要结合批次日志。
追问
- 问:count 与实际向量数不一致怎么办?答:排查重复 id、删除残留与半截批次,必要时重建集合对账。
- 问:遍历时能用 peek 取全部吗?答:不能,大集合分页走 get 的 limit/offset 机制。
05.6.5.1-023 Chroma 的鉴权机制现状如何?
频率 ★★★☆☆ | 难度 高级
一句话结论
开源版 Chroma 的内置鉴权能力有限,认证授权方式随版本演进;生产暴露给不可信网络时,应在网络层、反向代理与应用层补齐身份校验,不能假设库自带完整 RBAC。
概念解释
- 现状边界:是否内置账号、token 或权限体系,以当前版本官方文档为准(待确认),不要背诵未核实的鉴权 API。
- 补齐手段:内网访问、网关鉴权、TLS、应用侧按租户校验查询条件。
- 风险面:服务端端口直接暴露、默认凭据、越权读取其他集合。
原理流程
梳理访问主体 → 网络隔离 + 网关认证
→ 应用层校验租户与权限 → 查询强制带隔离条件
→ 审计集合级访问与批量操作
代码 / 命令
# 自检清单:端口是否内网可达 · 是否有网关鉴权 · 集合命名是否带租户隔离
# 未确认的内置鉴权能力:标注待确认,以官方文档为准
常见误区
- 误区:连上服务端就天然有权限隔离。正解:缺少内置鉴权时,任何能连通端口的调用都可能访问集合,必须前置防护。
- 误区:鉴权只在登录入口做。正解:每次检索请求都要携带并校验租户与权限条件。
追问
- 问:多租户下怎么防止越权读?答:查询强制带租户 metadata 条件,集合按租户或业务域隔离,网关校验调用方身份。
- 问:敏感片段能直接入库吗?答:按合规要求脱敏或控制访问范围,向量并非绝对不可反演。
05.6.5.1-024 多租户有哪几种实现方式?
频率 ★★★★☆ | 难度 高级
一句话结论
按隔离强度从弱到强:共享集合加租户字段过滤、按租户分集合、独立数据库/命名空间(能力随版本而定);越强隔离成本越高,大租户应单独处理。
概念解释
- 共享集合 + 过滤:成本最低,所有查询强制带租户条件,隔离性依赖应用层正确性。
- 独立集合:租户间 schema 与索引参数可分开,删除与迁移按集合进行。
- 独立 database/tenant:若版本提供该能力可做强隔离,否则用独立服务端或独立部署代替。
原理流程
评估租户数量、数据量与隔离要求
→ 小租户共享集合 + 过滤;大租户独立集合
→ 强隔离需求 → 独立部署/独立服务端
→ 所有查询路径强制携带租户条件
代码 / 命令
# 共享集合过滤:query(where={"tenant": current_tenant}, ...)
# 集合命名带租户前缀;租户级配额与指标在应用侧统计
常见误区
- 误区:只靠 where tenant 就够,集合共用无所谓。正解:大租户会拖慢同集合其他租户,且漏写条件即越权。
- 误区:每个租户一个服务端最稳。正解:运维成本与实例数量线性上升,应按 SLA 分级。
追问
- 问:租户迁移怎么做?答:按租户维度导出集合记录,在新集合/新环境重建,校验记录数与抽样检索后切换。
- 问:租户删除要清理什么?答:对应集合或 metadata 记录、备份副本与缓存,保留审计记录。
05.6.5.1-025 备份怎么做?
频率 ★★★☆☆ | 难度 进阶
一句话结论
备份对象是服务端持久化目录(嵌入式同理):停写或低峰期做目录快照,配合集合导出做可移植副本;恢复后必须校验记录数与抽样检索,不能只看文件存在。
概念解释
- 目录快照:整目录拷贝是基础备份方式,注意文件一致性,避免拷贝途中写入造成快照损坏。
- 集合导出:通过 get 遍历记录导出 id、向量、原文、元数据,便于跨环境迁移与重建。
- 校验:恢复后 count、抽样点查与近邻检索都要跑一遍。
原理流程
低峰停写或快照模式 → 拷贝持久化目录
→ 可选:遍历集合导出结构化副本
→ 异机保存 → 恢复演练:读目录/导入副本 → 校验行数与检索
代码 / 命令
# 备份清单:目录快照 + 导出副本 + 模型/度量/参数记录
# 恢复演练周期:每季度或重大变更后执行一次
常见误区
- 误区:只备份向量不备份原文和元数据。正解:缺原文与元数据无法重建可用检索,导出副本要包含四要素。
- 误区:目录拷贝随时可做且一致。正解:写入进行中拷贝可能得到不一致状态,应在低峰或停写窗口执行。
追问
- 问:增量备份可做吗?答:可在应用侧按变更日志导出增量记录,复杂度高于全量,按 RPO 要求设计。
- 问:备份保留多久?答:按合规要求与恢复演练需要设定,过期备份按策略清理。
05.6.5.1-026 数据迁移到另一台机器或另一个客户端怎么做?
频率 ★★★☆☆ | 难度 进阶
一句话结论
迁移要么搬运持久化目录到同版本服务端,要么导出四要素后在目标环境重新写入;两种方式都要核对模型版本、度量与记录数,目录方式受版本兼容约束。
概念解释
- 目录迁移:停写后拷贝目录,目标环境版本与配置一致,适合同版本快速搬迁。
- 导出导入:遍历集合导出记录,目标环境建新集合后写入,跨版本更稳但要重跑写入链路。
- 一致性:迁移后比对 count、抽样点查、同查询近邻结果。
原理流程
确认目标环境版本与模型 → 选择目录搬迁或导出导入
→ 执行迁移 → 校验记录数与向量维度
→ 抽样检索对照 → 切流 → 保留旧环境副本观察期
代码 / 命令
# 导出字段:id · embedding · document · metadata · 模型版本 · 度量
# 导入后校验:count 一致、维度一致、抽样 TopK 相关
常见误区
- 误区:目录随便拷到新版本就能用。正解:跨版本文件兼容未保证时,应走导出导入重建。
- 误区:迁移只搬向量。正解:原文、元数据与索引参数记录一起搬,否则检索回显与过滤缺失。
追问
- 问:迁移期间增量数据怎么办?答:双写或记录变更日志,切换前把增量补到目标环境。
- 问:迁移后召回下降怎么排查?答:核对模型版本、归一化、度量与集合参数是否与源环境一致。
05.6.5.1-027 版本兼容与升级要注意什么?
频率 ★★☆☆☆ | 难度 高级
一句话结论
升级前核对客户端与服务端版本匹配、持久化目录格式兼容与配置项变更;先在预发环境跑通写入、检索、过滤与恢复,不能只验证服务能启动。
概念解释
- 客户端/服务端匹配:HttpClient 与服务端版本协议要兼容。
- 存储格式:旧目录能否被新版本直接打开,以发行说明为准(待确认)。
- 配置变更:参数名、默认值与行为可能调整,升级后要回归基线用例。
原理流程
读发行说明 → 备份目录 → 预发升级 → 回归读写/过滤/删除/恢复
→ 灰度升级客户端 → 观察指标 → 全量
代码 / 命令
# 升级检查:版本匹配 · 目录备份 · 配置项核对 · 回归用例清单
# 回滚保留:旧版本镜像与备份目录可快速还原
常见误区
- 误区:小版本升级一定无损数据。正解:目录格式与默认行为都可能变化,必须备份与回归。
- 误区:客户端可以滞后很多个版本连新服务端。正解:协议不匹配会出现接口报错或字段缺失。
追问
- 问:升级后召回异常怎么回退?答:保留旧目录备份与旧版本镜像,回滚后先校验记录数再切流量。
- 问:哪些变更最需要回归?答:写入批次、where 过滤、where_document、删除与备份恢复链路。
05.6.5.1-028 单机容量上限与瓶颈在哪里?
频率 ★★★★☆ | 难度 高级
一句话结论
Chroma 单机瓶颈主要在内存容纳量、单进程并发与本地 IO;不存在可背诵的固定条数上限,应以自有数据集压测得到的延迟、内存与磁盘拐点为准。
概念解释
- 内存:向量、索引结构、原文与元数据驻留或缓存,内存不足会拖慢甚至失败。
- 并发:单服务端进程的请求处理能力有限,高并发排队表现为 P99 上升。
- 磁盘:持久化目录 IO 与容量约束,大批量写入时更明显。
- 规模经验:适合中小规模知识库;具体拐点必须实测,不引用未核实的数字上限。
原理流程
估算向量数 × 维度 × 字节 + 原文元数据 + 索引结构
→ 构造真实分布数据集压测 → 记录 QPS、P99、内存、磁盘
→ 找到拐点 → 决定扩容或迁移方案
代码 / 命令
# 压测指标:QPS · P50/P99 · 内存峰值 · 目录增长 · 写入批次耗时
# 不写固定上限数字;用实测曲线与业务 SLA 对照
常见误区
- 误区:官方文档给过明确条数上限可以直接背。正解:上限随维度、原文长度、索引参数与硬件变化,必须实测。
- 误区:瓶颈只在向量数量。正解:原文片段长度、元数据膨胀与并发请求同样会拖垮单机。
追问
- 问:接近瓶颈时先优化什么?答:先减小单条占用(原文长度、元数据、维度),再考虑分片或迁移专用库。
- 问:怎么提前预警?答:监控内存、目录大小、P99 与队列等待,到达阈值前安排扩容或迁移。
05.6.5.1-029 它与 LangChain 的默认耦合点在哪里?
频率 ★★★★☆ | 难度 基础
一句话结论
LangChain 把 Chroma 实现为 VectorStore:文档与嵌入通过集成类写入集合,检索结果按文档格式返回;耦合点是集合名、持久化目录、embedding 模型与 filter 透传。
概念解释
- VectorStore 抽象:统一 add/检索/留存接口,Chroma 集成类负责调用底层客户端。
- 入参:文档列表、embedding 模型、集合名、持久化目录或客户端对象。
- 透传:检索时的过滤条件、返回数量等参数映射到底层查询接口。
原理流程
LangChain 文档 → embedding 模型 → Chroma 集合
→ retriever → Chroma 查询 → 过滤/TopK → 包装回 Document
→ 进入生成链路
代码 / 命令
# 集成接入形态(类名与参数以当前框架版本文档为准)
# Chroma.from_documents(documents, embedding=embedding_model, collection_name="kb", persist_directory=...)
# retriever = vectorstore.as_retriever(search_kwargs={"k": 5, "filter": where_dict})
常见误区
- 误区:框架集成自动管理模型版本与集合迁移。正解:集合、模型与参数仍需应用侧登记与治理。
- 误区:filter 参数在框架层随便写都能透传。正解:透传能力受集成版本限制,复杂条件要核对底层 where 语法。
追问
- 问:自定义客户端能传给集成类吗?答:多数集成支持传入已有 client 对象,便于复用服务端连接,具体参数以框架文档为准。
- 问:集成层检索结果不带距离吗?答:返回格式以框架封装为准,需要距离时回到底层客户端查询接口获取。
05.6.5.1-030 嵌入式模式能被多个进程或线程访问吗?
频率 ★★★★☆ | 难度 高级
一句话结论
嵌入式客户端直接打开本地目录,多进程并发读写同一目录存在一致性与损坏风险;多实例部署应走服务端模式,进程内多线程并发也要核对客户端实现的线程安全性。
概念解释
- 多进程:各自打开同一存储目录时缺乏分布式锁协调,可能互相覆盖或损坏文件。
- 多线程:同一客户端实例的并发调用是否线程安全,需以库实现为准(待确认),保守做法是串行化或用连接池。
- 正确姿势:Web 多实例连独立服务端;单进程内按官方约定控制并发。
原理流程
单进程 → 嵌入式客户端(按线程安全约定访问)
多实例 → HttpClient → 独立服务端统一读写
禁止:多个进程同时打开同一持久化目录
代码 / 命令
# 部署核对:实例数量 → 客户端形态 → 目录是否被多进程共享
# 服务化:应用实例无状态,数据访问收敛到服务端
常见误区
- 误区:嵌入式目录像普通文件夹一样谁都能开。正解:存储内部状态依赖写入协调,多进程直开风险高。
- 误区:多线程调用同一客户端天然安全。正解:未确认线程安全前,用队列串行化写入或查官方并发说明。
追问
- 问:容器多副本挂载同一目录会怎样?答:多副本同时写同一目录风险同多进程,应改为连独立服务端。
- 问:服务端模式下并发由谁承担?答:服务端进程负责存储访问,应用侧只控制请求并发与重试。
05.6.5.1-031 持久化目录里的数据是怎么构成的?
频率 ★★★☆☆ | 难度 高级
一句话结论
目录内保存集合定义、向量、原文、元数据与索引相关文件,具体文件名与布局随版本演进;排障时观察目录增长与文件类型,不手工编辑内部文件。
概念解释
- 数据面:向量数组、文档文本、元数据键值。
- 索引面:近邻检索所用的索引结构文件。
- 元数据面:集合配置、命名与关联关系。
- 待确认:底层存储引擎与文件格式细节以官方文档为准,不凭印象背诵引擎名。
原理流程
写入 → 数据落目录(向量/原文/元数据)→ 索引结构更新
→ 目录大小随记录数增长 → 备份以目录为单位
代码 / 命令
# 运维观察:目录总大小 · 集合记录数 · 单条平均占用 · 增长趋势
# 禁止:手工改名、删除内部文件、用文本编辑器改写
常见误区
- 误区:目录里都是可直接读的 JSON。正解:内部存储格式由实现决定,直接解析不可靠。
- 误区:删掉某个大文件能立刻回收空间且不影响集合。正解:内部文件被引用关系管理,误删会导致集合打不开。
追问
- 问:目录异常增大怎么排查?答:结合 count 算单条平均占用,检查是否残留大量删除记录、长原文或重复批次。
- 问:能否从目录直接提取原文备份?答:优先用客户端导出接口;直接读内部文件格式不稳定。
05.6.5.1-032 写入后立即可见吗?
频率 ★★★☆☆ | 难度 进阶
一句话结论
写入返回成功后记录通常可被点查与检索,但可见性与索引更新节奏受存储实现影响;对「写后必须能搜到」的链路,应做点查确认或设置合理的等待与重试。
概念解释
- 可见性分层:写入落存储、索引更新、检索可命中三者不完全等同。
- 场景差异:嵌入式与服务端、不同版本的刷新节奏可能不同(待确认)。
- 工程兜底:关键流程按 id 点查确认,检索侧容忍短暂不可见窗口。
原理流程
写入返回 → 点查 id 确认存在 → 等待索引可见 → 检索命中
→ 不可见则按策略重试 → 记录可见性延迟指标
代码 / 命令
# 关键链路:写入后 get(ids=[id]) 校验;检索失败不立即判定为脏数据
# 指标:写入时间 → 首次可检索时间的差值分布
常见误区
- 误区:add 返回成功就一定能被 query 命中。正解:索引可见存在节奏差,强需求要确认机制。
- 误区:所有版本可见性行为一致。正解:以当前版本实测为准,不把旧经验套到新版本。
追问
- 问:写后搜不到先查什么?答:id 是否写入、向量维度是否一致、索引可见节奏、过滤条件是否排除该记录。
- 问:批量导入后何时允许检索?答:批次全部完成并抽样命中后再放开查询流量。
05.6.5.1-033 重复 id 会发生什么?
频率 ★★★☆☆ | 难度 基础
一句话结论
id 是集合内主键;add 遇到已存在 id 的行为按版本约定处理,update/upsert 面向已存在 id,避免依赖未确认的冲突行为做幂等设计。
概念解释
- 主键唯一性:同一集合内 id 不允许代表两条不同记录。
- 接口差异:add、upsert、update 对重复 id 的语义不同,生产前应在测试环境核实。
- 幂等设计:业务主键稳定可预测,同步链路用 upsert 收敛重复执行。
原理流程
生成业务主键 → 写入前不假设接口冲突行为
→ 测试环境核实重复 id 表现 → 批量同步采用 upsert
→ 对账按 id 去重
代码 / 命令
# 主键建议:业务文档稳定标识 + 切片序号,避免用随机值导致重复同步
# 核对:测试同一 id 两次 add 的返回与最终记录状态
常见误区
- 误区:重复 add 一定报错所以天然防重。正解:不同接口行为不同,未核实前不能依赖报错做去重。
- 误区:切片重生成时换 id 无所谓。正解:同一切片换 id 会留下旧记录残留,应沿用稳定 id 或先清理旧切片。
追问
- 问:文档重切片后旧切片怎么清?答:按文档标识找出旧切片 id 删除,再 upsert 新切片。
- 问:id 用数字还是字符串?答:按 SDK 允许类型选择,业务侧保持类型一致,避免隐式转换导致对不上。
05.6.5.1-034 documents 可以为空吗,向量怎么来?
频率 ★★☆☆☆ | 难度 进阶
一句话结论
可以不存 document,但必须有可检索的向量来源:要么自嵌 embeddings,要么给 document 由 EF 生成;既无文本又无向量的记录无法参与语义检索。
概念解释
- 纯向量记录:只存 embedding 与元数据,用于对外部已有向量的检索托管。
- 无向量来源:记录无法被 query 命中,只能被点查或按元数据遍历。
- 回显需求:没有 document 时,检索结果需回业务库按 id 取原文。
原理流程
记录入库路径:document + EF → 向量;或直接 embeddings
→ 查询路径:query_texts 走 EF;query_embeddings 直用
→ 无原文记录:结果 id 回业务库拼装片段
代码 / 命令
# 纯向量写入:collection.add(ids=[...], embeddings=[...], metadatas=[...])
# 回显:检索返回 id → 业务库取 document,避免向量库存重复长文本
常见误区
- 误区:不存 document 就没法检索。正解:有自嵌向量即可检索,只是回显要回业务库。
- 误区:document 可空时随便写占位文本。正解:占位文本会污染 where_document 过滤与未来重嵌。
追问
- 问:原文放业务库、向量库只存 id 与向量有什么好处?答:减少向量库存储,原文更新与权限管理收敛到业务库。
- 问:where_document 过滤依赖什么?答:依赖入库的 documents 字段,纯向量记录不参与文本过滤。
05.6.5.1-035 删除集合与重建集合怎么操作?
频率 ★★☆☆☆ | 难度 基础
一句话结论
删除集合会移除该集合全部记录与索引配置;重建通常是新建同名或新名集合并重新写入,操作前必须确认备份与数据来源,避免误删不可恢复。
概念解释
- 删除入口:客户端按名称删除集合;删除后集合元数据与记录一并移除。
- 重建场景:换度量、换模型、索引参数调整、清理大量删除残留。
- 前置条件:保留业务源数据与备份,重建后可重新嵌入写入。
原理流程
确认重建原因 → 备份/导出旧集合 → 建新集合与参数
→ 批量重写 → 校验 count 与检索 → 删除旧集合
代码 / 命令
# 删除形态(方法名以当前版本文档为准)
# client.delete_collection(name="kb")
# 重建不直接覆盖:先建新集合双写校验,再下线旧集合
常见误区
- 误区:删集合后目录空间自动立刻清零。正解:内部回收节奏不承诺即时,观察目录大小趋势。
- 误区:重建可以在原集合上直接改维度与度量。正解:结构参数不在线变更,必须新建集合。
追问
- 问:集合能改名吗?答:是否支持 rename 以版本文档为准(待确认);不支持时用新建集合迁移替代。
- 问:重建期间线上检索怎么办?答:旧集合保留服务,新集合并行构建,校验通过后切流。
05.6.5.1-036 Chroma 有分布式与高可用能力吗?
频率 ★★★☆☆ | 难度 高级
一句话结论
开源形态以单机服务端或嵌入式为主,副本分片、自动故障转移与水平扩展不是它的核心设计;高可用需要外部备份、多实例与应用层降级配合,不能套用分布式数据库的副本语义。
概念解释
- 现状边界:是否提供集群/副本拓扑以官方版本能力为准(待确认),不假设内置分布式协调。
- 外部兜底:独立备份、服务端多实例前置负载均衡、数据可从业务源重建。
- 故障域:单服务端宕机影响全部连接该实例的请求。
原理流程
评估 HA 要求 → 明确产品能力边界
→ 数据可重建 + 定期备份 + 应用重试降级
→ 高可用要求超出能力 → 迁移分布式向量库
代码 / 命令
# HA 检查:单点组件清单 · 备份恢复时长 · 重建链路 · 应用超时与降级开关
# 不承诺自动副本同步与选主
常见误区
- 误区:部署两个服务端实例就自动同步数据。正解:无内置副本协调时,两实例数据独立,不能互为热备。
- 误区:向量库都天然支持分片扩容。正解:Chroma 的扩缩容边界需按版本能力核对,超大规模应换专用库。
追问
- 问:单服务端故障怎么降级?答:应用侧缓存最近结果、延迟重试、提示稍后再试,避免雪崩。
- 问:数据可重建对 HA 的意义?答:只要业务源与嵌入链路保留,服务端可从备份或源数据重建,降低单点损失。
05.6.5.1-037 客户端配置走哪些环境变量?
频率 ★★☆☆☆ | 难度 进阶
一句话结论
服务端地址、端口、是否持久化目录等配置应通过环境变量或配置文件注入,不写死在代码;具体支持的变量名以当前版本文档为准,未核实的变量不要背诵。
概念解释
- 配置项:host、port、数据目录、证书/超时类参数(若版本提供)。
- 环境差异:开发、预发、生产使用不同配置与凭据。
- 可观测:配置项启动时打印摘要(不含敏感信息)便于核对。
原理流程
配置模板 → 各环境变量渲染 → 客户端初始化读取
→ 启动校验连通性 → 配置变更走发布流程
代码 / 命令
# 形态示意:host/port/persist_dir 由环境变量注入
# 禁止:代码内硬编码生产地址、账号或凭据
常见误区
- 误区:环境变量名凭旧版本记忆使用。正解:变量名与默认值以当前文档为准,升级后核对。
- 误区:配置差异靠改代码分支。正解:同一镜像/包体通过配置切换环境。
追问
- 问:连接超时在哪配?答:客户端/服务端超时参数以 SDK 文档为准,应用侧还要设请求超时与重试。
- 问:敏感配置怎么管理?答:走配置中心或环境注入,不提交到代码仓库。
05.6.5.1-038 嵌入式客户端放在 Web 服务里要注意什么?
频率 ★★★★☆ | 难度 进阶
一句话结论
Web 服务用嵌入式时通常是单实例约束:数据目录不能被多实例共享,重启加载与内存占用要纳入部署规划,实例数与目录归属必须一致。
概念解释
- 实例约束:多副本 Web 服务不能各自打开同一目录,否则数据不一致。
- 启动加载:服务启动时打开目录,首次加载与预热影响启动时间。
- 资源:向量与索引占用应用进程内存,与业务请求争抢。
原理流程
Web 单实例 → 嵌入式客户端绑定目录
→ 启动打开存储 → 请求进程内读写
→ 多实例需求 → 改服务端形态,不共享目录
代码 / 命令
# 部署核对:副本数 = 1 或改用独立服务端
# 资源:内存预算包含向量库占用;目录挂持久卷
常见误区
- 误区:K8s 多副本都挂同一目录做嵌入式。正解:多副本并发打开同一目录风险高,应连独立服务端。
- 误区:向量库内存不计入应用容量。正解:进程内嵌入式共享应用内存预算,OOM 会影响业务请求。
追问
- 问:嵌入式 Web 服务重启数据会丢吗?答:目录已持久化则不丢,但启动加载期间不可立即服务。
- 问:从嵌入式 Web 拆出独立服务端怎么过渡?答:保留旧实例,新服务端导入数据,应用配置切换到 HttpClient 后再下线旧实例。
05.6.5.1-039 写入与查询的错误怎么处理和重试?
频率 ★★☆☆☆ | 难度 进阶
一句话结论
区分可重试错误(网络超时、临时不可用)与不可重试错误(维度不符、字段类型错、id 冲突),重试按幂等主键退避执行,错误批次落日志可对账。
概念解释
- 可重试:连接超时、服务端暂时不可用、限流。
- 不可重试:参数非法、维度不一致、不支持的字段类型,重试不会成功。
- 幂等基础:按业务主键 upsert,失败批次可安全重放。
原理流程
捕获错误 → 分类(临时/永久)
→ 临时:退避重试有限次数 → 仍失败入死信/日志
→ 永久:记录原因,修正参数后重跑
代码 / 命令
# 重试要点:指数退避 · 最大次数 · 幂等主键 · 批次级对账
# 永久错误不重试,避免放大压力
常见误区
- 误区:所有错误都无限重试。正解:参数错误重试只放大请求,应先修正数据。
- 误区:重试不区分批次。正解:半截批次要记录已写部分,重放时按 id 幂等收敛。
追问
- 问:查询超时要不要重试?答:只读查询可在幂等前提下有限重试,注意 P99 与雪崩风险,配合熔断。
- 问:错误记录保留什么?答:批次标识、id 范围、错误类型与堆栈,便于离线补写。
05.6.5.1-040 合规删除(被遗忘权)怎么落地?
频率 ★★☆☆☆ | 难度 高级
一句话结论
合规删除要完成向量库记录删除、业务库原文清理、备份与缓存副本处理,并保留可审计的删除记录;只调 delete 接口不算闭环。
概念解释
- 主链路:按用户/文档标识删除向量、原文与元数据记录。
- 旁路:历史快照、导出副本、缓存、日志中的片段需要按保留策略处理。
- 审计:删除时间、范围、执行人或任务记录可追溯。
原理流程
接收删除请求 → 定位标识 → 删除向量库记录
→ 清理业务原文与关联 → 处理备份/缓存副本 → 记录审计 → 抽样核验不可检索
代码 / 命令
# 核验:按 id 点查为空;抽样 query 不命中;备份清理记录可查
# 保留:合规审计所需的最小操作记录,不保留原文副本
常见误区
- 误区:向量不含原文就无需删除。正解:向量可关联回用户数据,仍需删除并处理关联副本。
- 误区:delete 成功即合规完成。正解:备份与日志中的残留未处理,闭环不成立。
追问
- 问:备份里的历史副本怎么处理?答:按合规保留期到期清理,或在导出备份时脱敏,保留处理记录。
- 问:怎么向审计证明已删除?答:抽样核验报告 + 删除操作日志 + 备份清理记录。
05.6.5.1-041 开发、测试、生产环境分别用什么形态?
频率 ★★★☆☆ | 难度 基础
一句话结论
开发可用内存或嵌入式快速迭代;测试用可重复初始化的持久化小数据集;生产按多实例与备份要求选服务端形态,三环境配置与数据严格隔离。
概念解释
- 开发:内存 Client 或本地嵌入式,追求启动快、可重置。
- 测试:固定样本数据集,每个用例可重建,避免相互污染。
- 生产:服务端 + 持久卷 + 备份 + 监控,配置独立于代码。
原理流程
开发 → 本地嵌入式/内存 → 随时重置
测试 → 脚本初始化样本 → 用例后清理
生产 → 独立服务端 → 持久卷/备份/监控
代码 / 命令
# 隔离检查:环境标识在集合名/配置中;凭据不跨环境;样本数据脱敏
常见误区
- 误区:测试连生产只读副本。正解:测试写入与检索会污染生产指标,必须独立环境。
- 误区:生产沿用开发的嵌入式目录。正解:生产要评估多实例、备份与故障域。
追问
- 问:预发环境要多大?答:能跑通生产量级缩比压测与迁移演练即可,不必等比放大全部资源。
- 问:如何防止误连生产?答:网络隔离、配置分环境、启动时打印目标环境并做连接校验。
05.6.5.1-042 服务端模式下连接与并发怎么管理?
频率 ★★☆☆☆ | 难度 高级
一句话结论
应用侧复用连接、控制并发上限,设置合理超时与熔断;服务端能力按压测 QPS 规划,避免每个请求新建连接把开销堆在握手与连接管理上。
概念解释
- 连接复用:HttpClient 连接池或长连接,降低反复建连开销。
- 并发控制:信号量/线程池限制在途请求数,防止瞬时流量打满服务端。
- 超时熔断:连接与读取超时、失败率超阈值熔断,快速失败而非长时间挂起。
原理流程
客户端初始化复用连接 → 并发上限控制
→ 请求带超时 → 失败重试退避 → 熔断保护服务端
→ 压测得到单服务端承载 QPS 后规划副本
代码 / 命令
# 参数核对:连接池大小 · 并发上限 · 连接/读取超时 · 熔断阈值
# 指标:连接数 · 在途请求 · P99 · 错误率
常见误区
- 误区:每次请求 new 一个 Client。正解:重复建连增加延迟与服务端连接压力,应复用实例。
- 误区:无限排队等服务端恢复。正解:快速失败 + 退避,避免线程堆积。
追问
- 问:单服务端连接数上限受什么影响?答:服务端实现、端口与文件句柄限制,压测时观察拒绝与排队情况。
- 问:QPS 上来先扩什么?答:先定位瓶颈在 CPU、内存还是连接数,再决定扩实例或优化批量。
05.6.5.1-043 集合 metadata 与记录 metadata 有什么区别?
频率 ★★★☆☆ | 难度 进阶
一句话结论
集合 metadata 是容器级配置与标注(度量、索引参数、模型版本),记录 metadata 是每条向量的过滤键值;前者建集合时定型,后者随记录写入与更新。
概念解释
- 集合级:影响整个集合的检索空间与索引行为,变更需重建集合。
- 记录级:参与 where 过滤,逐条存储,可 update/upsert 变更。
- 用途区分:模型版本、空间参数放集合级;来源、租户、状态放记录级。
原理流程
建集合 → 集合 metadata(参数 + 基线标注)
→ 写记录 → 记录 metadata(过滤字段)
→ 核对:参数在集合级,过滤维度在记录级
代码 / 命令
# 集合 metadata:度量、索引参数、模型与版本
# 记录 metadata:tenant、source、status、updated_at
常见误区
- 误区:把过滤字段写进集合 metadata。正解:集合级键不按记录区分,无法做逐条过滤。
- 误区:集合 metadata 可以像记录 metadata 一样随时改。正解:结构参数改动需重建。
追问
- 问:模型版本记在哪里更合适?答:集合 metadata 记录当前集合所用模型;记录级也可留分片来源便于追溯。
- 问:过滤字段变更类型怎么处理?答:属于记录 metadata,批量 update/upsert 修正。
05.6.5.1-044 向量归一化与距离度量在入库前由谁负责?
频率 ★★★☆☆ | 难度 进阶
一句话结论
归一化与度量约定要在入库前统一:cosine 场景通常配合归一化向量,L2 与 IP 各有适用前提;库内向量与查询向量必须遵循同一约定,不能一边归一化一边不归一化。
概念解释
- 度量选择:cosine 看方向,L2 看绝对距离,IP 受模长影响。
- 归一化:cosine/IP 场景把向量模长统一为 1,避免模长干扰比较。
- 一致性:写入与查询同模型、同归一化步骤、同度量。
原理流程
确定度量 → 入库前统一归一化(如需要)→ 写入集合
→ 查询向量走相同预处理 → 同度量比较排序
代码 / 命令
# 约定登记:度量类型、是否归一化、模型版本
# 核对:抽样向量模长分布;查询预处理与入库一致
常见误区
- 误区:选了 cosine 就不用管模长。正解:实现是否内部归一化以版本为准,未确认时入库前统一处理。
- 误区:IP 与 cosine 可以随意互换。正解:未归一化时两者结果不同,混用会排错序。
追问
- 问:归一化在哪一步做?答:模型输出后、写入与查询前同一函数处理,避免两处各写一套。
- 问:度量选错怎么修?答:属集合级配置,需新建集合按正确约定重嵌迁移。
05.6.5.1-045 离线批量入库与在线写入怎么分工?
频率 ★★★☆☆ | 难度 进阶
一句话结论
历史文档批量导入走离线分批链路(限速、对账、可重放),增量文档走在线轻量写入;两条链路共用同一套主键与字段约定,避免批次重复与结构不一致。
概念解释
- 离线批量:全量或大批量重嵌,关注批次大小、吞吐与失败补写。
- 在线写入:单篇或少篇增量,关注低延迟与幂等。
- 共用约定:id 规则、metadata 字段、模型与度量一致。
原理流程
离线:源文档 → 分批嵌入 → upsert → 批次对账
在线:新文档事件 → 单篇/小批 upsert → 点查确认
→ 增量并入同一集合,字段约定统一
代码 / 命令
# 批量:控制单批大小、记录失败批次、按 id 幂等重放
# 在线:异步队列削峰,避免阻塞主业务请求
常见误区
- 误区:离线大批量一次写完最快。正解:单批过大会造成内存与超时压力,失败重放成本高。
- 误区:在线写入可以用临时字段格式。正解:字段类型与命名必须和批量入库一致。
追问
- 问:批量导入期间能检索吗?答:可以,但要接受部分可见;关键场景先导入完成再放开查询。
- 问:批量与在线同时写同一集合要注意什么?答:主键规则统一,按 id 幂等,避免同一切片两套 id。
05.6.5.1-046 集合重命名与 schema 变更怎么做?
频率 ★★☆☆☆ | 难度 高级
一句话结论
重命名是否原生支持以版本文档为准(待确认);schema 层面的维度、度量、索引参数变更不在线原地完成,标准做法是新建集合、迁移数据、校验后切换引用。
概念解释
- 重命名:影响所有按名称引用的客户端与脚本,需同步更新配置。
- 结构变更:维度/度量/参数定型于集合创建,原地改不了。
- 迁移路径:新集合并行写入 → 双写校验 → 切流 → 旧集合下线。
原理流程
变更需求 → 评估是否可通过 metadata 标注解决
→ 结构变更:新建集合 → 迁移 → 校验 → 切换引用 → 下线旧集合
代码 / 命令
# 变更清单:影响的客户端/脚本/配置 → 新集合参数 → 迁移对账 → 回滚保留旧集合
常见误区
- 误区:改集合名不需要改应用配置。正解:名称是定位标识,引用方不同步会连到旧集合或找不到集合。
- 误区:schema 可以在线加字段。正解:记录 metadata 键值可补充,但向量结构参数不能原地改。
追问
- 问:没有 rename 能力怎么改名?答:新建目标集合导入数据,更新引用后删除旧集合。
- 问:变更期间双写怎么保证一致?答:按主键幂等,定时对账差异并修复。
05.6.5.1-047 上线后要观察哪些资源指标?
频率 ★★☆☆☆ | 难度 高级
一句话结论
观察集合记录数、内存与目录增长、查询 P50/P99 与错误率、写入批次耗时;指标要能按集合与租户拆分,否则瓶颈无法定位到具体业务域。
概念解释
- 规模:count 趋势、单条平均占用、目录大小。
- 性能:查询延迟分布、QPS、超时与错误率。
- 写入:批次大小、耗时、失败重试次数。
- 资源:进程内存、磁盘 IO、句柄与连接数。
原理流程
埋点采集 → 按集合/租户聚合 → 阈值告警
→ 异常曲线对照写入批次与资源指标 → 定位瓶颈
代码 / 命令
# 看板清单:count · 目录大小 · 内存 · QPS · P99 · 错误率 · 写批耗时
# 告警:内存/磁盘水位、P99 超 SLA、错误率上升
常见误区
- 误区:只看平均延迟。正解:P99 才反映在线体验,平均值会掩盖尾延迟。
- 误区:不按集合拆分指标。正解:一个慢集合会拖垮整体均值,无法定位。
追问
- 问:内存持续上涨先查什么?答:删除残留、单条占用增长、重复批次,结合 count 算平均占用。
- 问:P99 上升怎么排查?答:先看是否慢在过滤、候选规模或资源饱和,再决定调参或扩容。
05.6.5.1-048 给一个中小规模 RAG,Chroma 怎么部署与设计集合?
频率 ★★★★★ | 难度 高级
一句话结论
按「规模与 SLA 估算 → 定形态与部署 → 定集合与字段 → 定写入与备份链路 → 配监控与迁移预案」给出完整方案,明确假设、可验证指标与离开 Chroma 的触发条件。
概念解释
- 输入:文档数与切片数、向量维度、日增量、QPS 与 P99 目标、过滤维度(租户/来源/时间)。
- 关键决策:嵌入式或服务端、集合划分、EF/自嵌与度量、元数据字段、备份与重建链路。
- 交付物:部署拓扑、集合 schema、写入与检索流程、监控告警、压测结论与迁移预案。
原理流程
1) 估算切片数与内存/原文占用 2) 按单实例与多实例需求定形态
3) 按业务域/模型版本划分集合 4) 定字段、度量与归一化约定
5) 离线批量 + 在线增量写入 6) 备份/恢复演练 + 监控告警
7) 压测 recall 与 P99 8) 预留迁往专用向量库的导出路径
代码 / 命令
# 面试表达:先讲假设与规模 → 再讲部署与集合设计 → 取舍理由 → 验证方式
# 方案要点:模型版本登记 · 主键稳定 · 过滤字段标量化 · 备份可重建 · 指标基线
常见误区
- 误区:直接说“用 Chroma 跑起来就行”。正解:没有规模估算、字段设计与备份预案的方案不可信。
- 误区:忽略过滤维度与多实例约束。正解:租户/来源过滤与部署形态会反过来影响集合划分。
追问
- 问:峰值时段 QPS 高怎么办?答:评估服务端并发与连接复用,必要时只读缓存热点结果,超过单机能力再迁移。
- 问:怎么验证方案成立?答:用真实分布数据集压测 recall@k、P99 与内存占用,并做一次恢复演练。
参考来源
- Chroma 官方文档:https://docs.trychroma.com
- Chroma 仓库:https://github.com/chroma-core/chroma
- LangChain Chroma 向量库集成:https://python.langchain.com/docs/integrations/vectorstores/chroma
- LlamaIndex Chroma 集成:https://docs.llamaindex.ai
- Spring AI 向量存储抽象:https://docs.spring.io/spring-ai/reference/api/vectorstore.html