CrewAI 本地知识库为何随进程重建
1.15.42 的默认 Qdrant 目录按进程隔离并在正常退出时清理,跨次复用知识索引需要显式指定非默认路径,同时遵守本地存储的单进程边界。
正文
核心变化是存储生命周期,不是模型能力
CrewAI 1.15.42 将 Knowledge 的默认存储改为本地 Qdrant,但这不等于默认获得可跨进程复用的持久知识库:该版本会给默认目录加上进程 ID,并在进程正常退出时清理;需要保留索引,就要显式指定不同于默认位置的路径,同时接受本地目录只能由一个进程占用的边界。
这次发布于 2026 年 11 月 18 日,官方发布说明还明确把 ChromaDB 改为可选依赖。对使用 Knowledge 的开发者而言,真正要检查的是默认后端、索引目录、embedding 配置和进程启动方式,而不是只确认安装命令成功,或者让代理回答一道问题。
这些变化的讨论范围是 1.15.42 的内置 Knowledge 与 RAG 存储路径。显式传入自定义 storage 的应用走的是另一条分支,不能把默认后端的行为套到所有自定义存储上;Knowledge 的构造源码明确优先使用传入的存储实例。
默认目录为什么不等于持久索引
先区分 Qdrant 客户端的能力和 CrewAI 的默认策略。Qdrant 官方 Python 客户端支持内存模式,也支持通过 path 把数据写到磁盘;后者本身具备持久化能力。CrewAI 则在这层能力之上,增加了默认目录的进程隔离和退出清理。
在 1.15.42 中,QdrantConfig 的默认路径是 db_storage_path() 下的 qdrant。客户端工厂会展开路径、处理符号链接并规范化位置,然后检查它是否等于这个默认目录。若相等,实际打开的是加有 -pid<进程 ID> 后缀的目录,并注册退出处理函数删除该目录。
这解释了两个容易误判的现象。第一,看见磁盘文件不能证明下次启动会继续使用同一份索引,因为实际目录带有进程身份。第二,仅设置 CREWAI_STORAGE_DIR 改变存储根目录,并不会取消默认目录的隔离和清理逻辑。
还有一个细节值得保留:源码判断的是规范化后的实际路径,而不是“有没有写 path 参数”。如果手动填写的路径仍然指向默认的 qdrant 位置,它依旧会被当成默认目录。要保留索引,应使用另一个明确命名的位置,例如 knowledge-store。
正常退出清理也不等于异常退出一定清理。不能依赖这段逻辑完成崩溃后的目录回收,更不能把异常残留文件当成恢复承诺。对开发环境来说,按进程隔离可以避开多个脚本争用默认目录;对重复运行的知识处理任务来说,代价就是每个进程需要重新写入和生成自己的索引。
存储在本地,不代表 embedding 也在本地
另一个需要从源码确认的边界是 embedding。默认 RAG 配置和直接调用 QdrantConfig() 并不是同一个选择。
1.15.42 的 _default_rag_config() 会构造默认 embedding 函数,经 QdrantEmbeddingAdapter 交给 Qdrant;这个默认函数使用 OpenAI 的 text-embedding-3-small。因此,向量库位于本地,不意味着文档向量生成也离线完成。
直接构造 QdrantConfig() 而不传 embedding_function,则会进入另一条默认分支:使用 FastEmbed 和 all-MiniLM-L6-v2。该分支缺少 FastEmbed 时会给出安装 crewai[qdrant] 的提示。项目依赖文件也把这个 extra 与基础安装区分开来。
所以,迁移时不要把“换向量数据库”和“换 embedding 模型”合成一个不受控的操作。存储位置决定谁保存索引,embedding 模型决定文本如何进入向量空间;两者需要分别配置和验收。若更换了模型,应使用新的集合并重新建立索引,避免把不同模型生成的向量混进同一个集合。
如果排障起点是读取文件时占用过多内存,可以先对照文件分块读取与索引缓冲的区别。文件读取、embedding 和索引保存是三个环节,修好前一个环节,并不会自动改变后两个环节的生命周期。
跨次复用索引,要显式选择非默认路径
下面给出一个保留默认 OpenAI embedding、只改变索引目录的配置片段。它适用于 1.15.42,需要已有可用的 OPENAI_API_KEY,实际写入或查询时会发生 embedding 请求;这不是离线示例,也不是把 Qdrant 服务端部署到本机。
python -m pip install "crewai==1.15.42"
from pathlib import Path
from crewai.rag.config.utils import (
default_embedding_function,
set_rag_config,
)
from crewai.rag.qdrant.config import QdrantConfig
from crewai.rag.qdrant.embedding_adapter import QdrantEmbeddingAdapter
index_path = Path("./knowledge-store").resolve()
index_path.mkdir(parents=True, exist_ok=True)
embedder = QdrantEmbeddingAdapter(default_embedding_function())
set_rag_config(
QdrantConfig(
options={"path": str(index_path)},
embedding_function=embedder,
)
)
# 在完成存储配置后,再创建使用内置存储的 Knowledge 或 Crew。
配置应在应用启动时完成,并放在 Knowledge 初始化和文档入库之前。对显式使用自定义存储的实例,这个配置不能替代它自己的连接与生命周期管理。
示例选择 knowledge-store,是为了避开内置默认目录的判定,不是要求所有项目使用这个名字。容器部署还需要把这个位置映射到可保留的数据卷;只把目录固定在可被替换的容器文件系统中,并不能完成跨容器恢复。
保留目录以后,也要保留原始文档和入库配置。向量文件不是完整的知识来源档案,重建时仍需要知道文档版本、切分方式、集合名称和 embedding 模型。尤其不要把旧 ChromaDB 的文件目录直接交给 Qdrant:切换默认后端不是一份已核实的格式转换流程,发布说明没有承诺自动转换旧索引。
多进程共享应换服务端,而不是绕过目录锁
固定目录解决的是跨次复用,不是多进程共享。1.15.42 的客户端工厂明确说明,本地 Qdrant 一个目录只允许一个进程使用;同一进程内的客户端会按规范化路径复用底层对象,并通过锁串行执行公开方法。
如果 API 服务启动多个 worker,或者脚本与 Notebook 同时打开同一个固定目录,第二个进程会遇到占用错误。CrewAI 对底层错误补充了提示,要求选择不同目录、使用 Qdrant 服务端,或显式继续使用 ChromaDB。关闭线程检查不是解除跨进程目录占用的方案,框架中的线程锁也不能把本地文件变成多进程数据库服务。
因此可以按部署方式做选择,而不是按数据库名字做选择。
- 单进程脚本或开发实验。 默认目录提供隔离,接受每次启动重新建立索引即可。
- 单进程、需要复用索引的任务。 使用非默认固定路径,同时安排备份、原始文档保存和重建流程。
- 多个进程需要访问同一知识集合。 使用 Qdrant 服务端,把连接配置改为服务地址;数据卷、访问控制和服务运维随之成为应用需要处理的问题。
- 需要保留既有 ChromaDB 路径。 安装可选依赖并显式设置 ChromaDB 配置,先验证原有集合和 embedding 设置,不能只靠升级基础包维持原先默认行为。
服务端配置的关键区别是传入 url,而不是让每个 worker 共享同一 path。以下片段沿用上一节的 embedding 配置,要求目标 Qdrant 服务已经启动。
set_rag_config(
QdrantConfig(
options={"url": "http://localhost:6333"},
embedding_function=embedder,
)
)
另外,不能在父进程打开本地客户端,再让 fork 出来的 worker 直接继承使用。该版本的包装客户端记录了所属进程,子进程调用继承对象会被拒绝;源码提示在 fork 之后、各 worker 内创建客户端或依赖它的 Knowledge/Crew。这个约束与索引有没有落盘是两回事。
升级验收要覆盖重启和检索,不只看一次回答
可以把验收拆成一组可独立观察的动作。
先记录实际包版本和配置,确认走的是默认后端还是显式存储。接着写入一份内容与标记都固定的测试文档,查看集合记录,再正常结束进程。第二次启动时先检查目录和集合是否存在,不重新入库就执行检索;这能把“读取保留索引”与“重新建立索引后回答成功”分开。
如果采用固定目录,再用另一个进程尝试打开它,确认应用能识别占用错误,而不是让 worker 不断重启。这里应使用专门的测试目录,不要拿生产知识库做冲突试验,也不要用删除目录的办法掩盖占用问题。
一次模型回答不足以证明索引续用成功。回答可能来自模型已有知识,也可能来自本次重新导入的文档;测试文档应包含应用自定义标记,并分别核对集合记录和检索返回的内容。遇到空结果还要看日志:该版本 KnowledgeStorage.search() 会捕获异常、记录错误并返回空列表,不能把所有空列表都解释成没有相关知识。
为核对存储边界,2026 年 11 月 21 日在独立临时目录中进行了离线检查:提取 1.15.42 官方源码中的本地客户端工厂与锁包装,配合 qdrant-client==1.14.3 写入人工二维向量。检查确认默认目录在正常退出后被清理,非默认目录被保留,另一个进程重新打开后能读到记录,同时占用该目录会被拒绝。这个检查不包含完整 CrewAI 执行、真实 embedding 请求或模型效果评估。
最后,知识索引与 Flow 执行状态应分别验收。CrewAI Flow 的工具计数重置问题发生在每次执行的配额状态层;即使这类执行状态已正确重置,也不能推出知识集合已经持久化。把进程生命周期、知识索引生命周期和一次任务的执行状态拆开,才能判断升级改变了哪一层,并为自己的部署方式选择明确配置。
参考来源
以下来源于 2026 年 11 月 21 日打开核对,版本相关结论以固定版本的发布说明与源码为准。
- CrewAI 1.15.42 官方发布说明——确认默认 Knowledge 后端与可选依赖变化。
- CrewAI 1.15.42 的 Qdrant 客户端工厂源码——确认默认目录隔离、退出清理、目录锁和 fork 边界。
- CrewAI 1.15.42 的 Qdrant 配置源码——确认默认路径和 FastEmbed 分支。
- CrewAI 1.15.42 的 RAG 配置工具源码——确认内置默认 embedding 与显式配置入口。
- CrewAI 1.15.42 的 KnowledgeStorage 源码——确认后端选择、embedding 配置保留和检索异常处理。
- CrewAI 1.15.42 的 Knowledge 构造源码——确认显式存储优先于默认存储。
- CrewAI 1.15.42 的依赖配置——确认 ChromaDB 与 FastEmbed 的可选安装方式。
- Qdrant Python 客户端 1.14.3 官方说明——区分内存模式、本地落盘和服务端连接。