知识存储运维

向量数据库是将文档转换为 AI 可搜索的形式（向量）并加以存储的地方。知识索引生成的搜索数据保存在这里，AI 文档搜索和 RAG 回答都会使用这些数据。

存储在向量数据库中的数据是随时可以从原始文档重新生成的派生数据。即使更换或初始化向量数据库，工作空间中的原始文件也不会改变。

开始之前

所需权限：Workspace 管理员
在 知识服务 > 知识存储 中确认当前的驱动程序和连接状态。
切换或初始化存储可能会影响搜索结果，直到搜索数据重新准备完成，因此请安排好操作时间。

选择向量存储

在知识存储的 驱动程序 中选择。

驱动程序	存储位置	集合准备	推荐环境
Automatic (SQLite)	SpaceBuilder 服务器内部文件	不需要	默认值。选择嵌入模型后使用内置的 SQLite 存储。
Local (SQLite)	指定路径下的 `local_vectors.db` 文件	不需要	向量数量约 5 万个以下的小规模环境。想自行指定存储路径时使用。
Qdrant	外部 Qdrant 服务器	自动创建	向量数量较多，或希望将搜索数据分离到单独服务器时
Milvus	外部 Milvus 服务器	必须预先创建	已在运营 Milvus，或需要大规模集群时

向量数量不是文档数量，而是文档片段（块）的数量。文档会根据格式先按章节、页或行拆分，再按以韩文计约 700～1,000 字的大小进一步拆分后存储。一篇长文档可能会变成数十个向量。

外部向量数据库的安装和连接方法，请参阅各自的文档。

连接 Qdrant — 只需一个 Docker 容器即可安装，十分轻量。如果是首次搭建单独的服务器，推荐使用 Qdrant。
连接 Milvus — 建议使用内存 8GB 以上的单独服务器。需要自行创建集合。

Local (SQLite) 运维

Local 驱动程序无需外部服务，仅用一个 SQLite 文件（local_vectors.db）即可运行向量搜索。

项目	内容
存储文件	`数据路径` 下的 `local_vectors.db`
数据路径	默认值为 `vectordb_local`。相对路径以 SpaceBuilder 配置文件所在的文件夹为基准。
搜索方式	逐一比较所有已存储向量的方式。以 1024 维为准，1 万个向量约需 10ms，数据越多搜索时间也越长。
推荐规模	向量约 5 万个以下。超过此规模时，建议切换到 Qdrant 或 Milvus。

向量数据库概览 中会一并显示 local_vectors.db 使用量。

项目	含义
DB 文件 / WAL / SHM	SQLite 主文件和写入日志文件的大小
DB 内部可重用空间	因删除数据而空出、但尚未从文件大小中减去的空间。保存新数据时会优先重用这部分空间。

更换存储或嵌入模型时

只要更改并保存以下任一项目，SpaceBuilder 就会检测到更改并自动开始对全部原始文件重新索引。

驱动程序、端点、集合、数据路径
嵌入模型、向量维度

切换按以下顺序进行。

保存新设置。
索引调度器检测到更改，并请求对全部原始文件重新索引。
使用新设置重新嵌入所有文档，并保存到新存储。
所有文档都保存到新存储并完成搜索验证后，从原先的存储位置删除旧向量。

切换期间的搜索

在检测到更改之前，向量搜索会暂时停止，只使用关键词搜索。
重新索引期间搜索的是新存储。尚未迁移到新存储的文档可能不会出现在向量搜索结果中。
重新索引完成后，只搜索使用新设置生成的向量。

文档较多时，重新索引可能需要很长时间，请在用户较少的时段进行切换。

切换时的注意事项

在清理完成之前，请保持旧的外部存储开启。 如果从 Qdrant 或 Milvus 迁移到了其他存储，在旧向量删除完成之前，必须能够访问旧服务器。如果无法访问，清理任务会以 记录的存储目标不可用 为由持续重试。
更改向量维度时，请同时指定新的集合。 已创建的 Qdrant·Milvus 集合无法更改维度。无法将数据保存到维度不同的集合中。
即使恢复为之前的设置，也会重新索引。 按 A → B → A 的顺序恢复时，不会重用最初 A 的数据，而是重新索引。

检查运行状态

向量数据库概览

在知识存储页面顶部查看。

项目	含义
连接状态	是否能够访问向量存储
向量存储	正在使用的驱动程序和类型（内置型·服务型）
已存储的向量数	此实例（当前 SpaceBuilder）存储的向量数。不包含使用同一存储的其他实例的数据。
集合数	Local 为 1（首次索引前为 0），Qdrant·Milvus 为相应服务器上的全部集合数
集合配置	存储的维度和距离计算方式是否与设置一致

集合配置 中会显示以下之一。

显示	含义
正常（与当前设置兼容）	可以使用该集合。
尚未创建 · 首次索引时自动创建	Qdrant 集合尚不存在。这不是错误，会在首次索引时创建。
未找到集合 · 请先在 Milvus 中创建	Milvus 集合不会自动创建。请参阅连接 Milvus进行创建。
集合配置需要检查	维度或距离计算方式不一致。请查看一并显示的错误内容。

知识索引页面

在知识索引的索引摘要中查看进度。

项目	含义
待更新	新建或修改后正在等待索引的文件数
待嵌入	文字提取已完成、正在等待转换为向量的数量
嵌入数	SpaceBuilder 记录的当前嵌入数。在切换或重新索引期间，可能与向量数据库的 `已存储的向量数` 不同。
待删除向量	文件删除或存储切换后，正在等待从原存储位置删除的向量数

如果旧向量删除失败，清理重试列表中会显示存储目标和原因。重试间隔会逐渐延长，最长为 5 分钟。

原因	含义与处理
记录的存储目标不可用	旧的向量数据库服务器已关闭或无法访问。重新开启旧服务器后会自动继续清理。
远程删除失败	向量数据库拒绝了删除请求。请检查向量数据库服务器的状态和日志。
正在确认之前的存储请求结果	仍有结果尚未确认的存储请求，正在等待删除完成。大多数情况下会自动解决。
删除完成记录失败	已删除，但未能在 SpaceBuilder 中记录完成状态。将在下一周期重试。

向量同步与重建

在知识存储的 仅限管理员 区域执行。两项操作都不会删除原始文件，并且需要 Team 及以上的许可证。

操作	动作	使用时机
`同步已有嵌入`	将与当前文档片段兼容的已有嵌入复制到所选的向量数据库，仅重新生成无法恢复的向量。	更换了向量数据库，或存储中缺少向量时
`重建向量生成`	在保留旧向量的同时创建新的向量世代，验证完成后清理旧向量。	需要从头重新构建已存储的向量时

两项操作都只是受理请求，进度在采集与索引中查看。
不会影响使用同一 Qdrant·Milvus 集合的其他实例的数据。

多个实例共用一个向量数据库时

实例是指单独安装并运行的一个 SpaceBuilder。每个实例都有唯一的实例隔离键，存储的向量中会一并记录此键。因此，即使共用同一个集合，搜索、统计和向量清理也只在各实例自己的数据范围内进行。

不过，如果要按实例分别进行备份、容量管理和删除，建议每个实例使用单独的集合。使用默认集合名称（knowledge_vectors）时，设置页面会显示警告，并给出此实例的建议名称（setfn_knowledge_...）。

备份与恢复

知识数据的备份需要先停止 SpaceBuilder 服务器，再通过命令执行。服务器运行期间，备份和恢复都会被拒绝。恢复只能使用在同一实例、同一主文件夹中创建的备份。

# 备份（目标文件夹必须是尚不存在的新路径）
~/setfn-spacebuilder admin knowledge-backup <备份文件夹>

# 恢复
~/setfn-spacebuilder admin knowledge-restore <备份文件夹>

对象	是否包含在备份中
知识索引记录（团队·个人空间）	包含
Local 的 `local_vectors.db`	仅当位于 SpaceBuilder 主文件夹或配置文件夹内时包含
Qdrant·Milvus 的向量	不包含（可从原始文件重新生成的派生数据）

恢复后，请启动服务器并在知识存储中执行 同步已有嵌入，重新填充向量数据库。备份之后存储到外部向量数据库的向量会在恢复过程中转入清理对象，并在服务器启动后从原存储位置自动删除。

故障排除

症状	检查内容
连接状态为 `未连接`	请检查端点地址和端口、防火墙以及向量数据库服务器是否正在运行。
`集合配置需要检查` 和 `collection dimension is ..., expected ...`	集合维度与设置的向量维度不同。请指定新的集合名称。
`集合配置需要检查` 和 `unnamed dense vector` 相关错误	Qdrant 集合是以 Hybrid 或 named vector 方式创建的。请参阅连接 Qdrant。
已存储的向量数不增加	请检查知识索引是否已开启、当前是否处于允许时段之外，以及 `开始之前` 的检查项是否已全部完成。
`开始之前` 中的 AI 向量数据库显示警告	原因是向量数据库连接错误、集合配置不一致，或 Milvus 集合不存在。连接错误和配置不一致时，将鼠标悬停在卡片上可查看详细错误。Milvus 集合不存在时没有单独显示的错误内容，请参阅连接 Milvus创建集合。点击卡片可跳转到向量数据库设置。
向量数据库启用了认证，导致 `未连接`	请在知识存储中输入 API 密钥（Qdrant·Milvus）或用户名和密码（Milvus）并保存。
清理重试不断累积	请检查是否能够访问旧存储。请参阅检查运行状态中按原因列出的处理方法。