Langchain-Chatchat 知识库迁移机制全解从建表、三种向量库重建模式到数据清理与版本升级导入【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat导读Langchain-Chatchat基于 Langchain 的本地知识库 RAG 与 Agent 应用把知识库文档入库拆成两套存储体系——SQLite 元数据库info.db 等记录文件与切分信息与向量数据库默认 faiss也可用 milvus/pg/chromadb 等。当本地content文件夹中已有现成文档、而数据库或向量库尚未同步例如更换了 Embedding 模型、调整了默认向量库类型、或数据库结构随版本升级变化时就需要一套可复用的迁移能力。本文将围绕 migrate.md 与其底层实现 migrate.py完整讲解建表/重置表、从旧 SQLite 备份导数据、以本地文件夹为基准填充库的三种模式recreate_vs / update_in_db / increment、双向清理prune_db_docs / prune_folder_files并结合 init_database.py 的 CLI 参数与 test_migrate.py 给出可直接落地的操作方案。读完本文你将掌握知识库元数据表是如何被创建与重置的、版本升级时如何不动向量库地导入旧库数据、如何按需全量重建 / 只更新库内文件 / 增量补建向量索引以及如何通过两条 prune 命令让本地文件与数据库保持最终一致避免磁盘被无用文档占满或数据库残留已删除文件的脏记录。一、迁移模块的整体定位在 chatchat-server 的包结构中该模块位于 server/knowledge_base/migrate.py是知识库管理knowledge_base 文档组中最核心的数据库 ↔ 本地文件夹 ↔ 向量库三向同步工具。它对外暴露七个主要函数函数职责影响面create_tables依据 ORM 元数据创建全部数据库表数据库结构reset_tables先 drop 全部表再重建回到干净初始态数据库结构破坏性import_from_db(sqlite_path)从旧版 SQLite 备份把行数据导入当前库仅数据不动向量库file_to_kbfile(kb_name, files)文件名列表 →KnowledgeFile对象列表公共辅助folder2db(kb_names, mode, ...)以本地文件夹为基准执行三种模式的入库数据库 向量库prune_db_docs(kb_names)删除库里有、本地文件夹已无的文档数据库 向量库prune_folder_files(kb_names)删除本地有、库里未登记的文档文件本地磁盘破坏性从源码调用关系看init_database.py 一次性导入了create_tables、reset_tables、folder2db、import_from_db、prune_db_docs、prune_folder_files这些函数是知识库初始化与迁移 CLI 的全部底层动作。二、表结构的创建与重置create_tables 与 reset_tables2.1 create_tables只建不动的安全函数create_tables的实现只有一行核心逻辑见 migrate.pydef create_tables(): Base.metadata.create_all(bindengine)Base是 SQLAlchemy 的声明式 ORM 基类集中持有本项目全部表模型的元数据相关模型集中在 server/db/models对话、消息、知识库、知识文件、知识元数据、MCP 连接、HumanMessageEvent 等表。engine是 SQLAlchemy 连接引擎实际连接目标数据库。SQLAlchemy 的create_all采用只创建不存在的表语义已存在的表不会被修改或更新因此该函数是幂等且相对安全的适合在初始化与启动流程中反复调用。它的实际调用场景包括均可从源码确认项目初始化chatchat init在 cli.py 中先执行create_tables()保证数据表齐全后再继续服务器启动若表不存在则先建表见 startup.py 中对create_tables的导入重置流程reset_tables删除后调用它重建见 2.2向量库相关测试如 tests/kb_vector_db/test_faiss_kb.py、test_milvus_db.py、test_pg_db.py 在用例前都先 importcreate_tables以保证测试环境表结构正确。注意因为它不会更新已有表结构所以当升级后的模型新增了字段、表结构发生变更时需要配合数据库备份迁移见第三节 import_from_db或人工执行 DDL单纯调用本函数无法完成结构升级。2.2 reset_tables彻底清空后重建def reset_tables(): Base.metadata.drop_all(bindengine) create_tables()先drop_all删除当前数据库中的全部表再调用create_tables重建得到一份干净的初始表结构见 migrate.py。典型用途测试环境重置、或希望彻底清空元数据后从头重建知识库登记信息。高危警告会删除所有表及其中数据且不可回滚生产环境使用前必须备份数据库文件文档与源码函数 docstring 与注释均强调了这一点。2.3 对应 CLI--create-tables 与 --clear-tables在 init_database.py 的worker中参数被映射为CLI 参数触发动作--create-tables调用create_tables()确认表存在--clear-tables先reset_tables()再打印database tables reset# 只补建缺失的表 python chatchat/init_database.py --create-tables # 清空并重建全部表危险操作请先备份 python chatchat/init_database.py --clear-tables三、版本升级数据导入import_from_db3.1 适用场景与前提Langchain-Chatchat 的知识库元数据存放在 SQLiteinfo.db中。当版本升级导致 info.db 的表结构变化但文档内容与已向量化的数据没有变化时没有必要重新做一遍全文切分与向量化——只需把旧库里的结构化数据搬进新库即可。这正是import_from_db的存在意义docstring 见 migrate.py。使用前提有三条必须同时满足传入的sqlite_path是合法的 SQLite 数据库文件路径备份库的表名、需要导入的字段名与当前 ORM 模型一致函数只做名称交集过滤不负责重命名当前仅支持 SQLite直接使用sqlite3标准库连接其它数据库备份不在支持范围内。3.2 实现原理与字段处理核心流程migrate.pymodels list(Base.registry.mappers)拿到当前注册的全部 ORM 模型映射连接旧库通过sqlite_master查得全部表名遍历每个模型取model.local_table.fullname与旧库表名比对表不存在则跳过该模型对存在的表逐行select *再用{k: row[k] for k in row.keys() if k in model.columns}做字段名交集过滤只保留当前模型确实存在的列特殊处理时间字段若行含create_time调用dateutil.parser.parse见文件顶部from dateutil.parser import parse把字符串解析为正确的时间对象避免 SQLite 时间格式与 ORM DateTime 列类型冲突在session_scope()上下文内session.add(model.class_(**data))逐行添加依赖上下文管理器自动提交/回滚会话管理实现在 server/db/session.py全部成功则关闭连接并返回True任何异常打印无法读取备份数据库{sqlite_path}。错误信息{e}并返回False。3.3 CLI 用法python chatchat/init_database.py --import-db /path/to/old/info.db执行前务必停止一切对目标库的读写操作源码注释明确要求避免数据冲突并确认新库的表已创建必要时先跑--create-tables。四、以本地文件夹为基准填充数据库与向量库folder2db4.1 参数清单folder2db是本模块的重头戏。完整签名与默认值见 migrate.py其中多个默认值直接来自Settings.kb_settings定义于 settings.py默认向量类型、切分参数等集中在此参数类型/取值默认值说明kb_namesList[str]—为None时取list_kbs_from_folder()即KB_ROOT_PATH下全部知识库目录要处理的知识库名称列表moderecreate_vs/update_in_db/increment无必填迁移模式语义见 4.2vs_typefaiss/milvus/pg/chromadbSettings.kb_settings.DEFAULT_VS_TYPE默认faiss向量库类型注意全局设置项还支持 zilliz/es/relyt此处函数级字面量限定了这四种embed_modelstrget_default_embedding()默认模型取配置如bge-m3Embedding 模型名chunk_sizeintSettings.kb_settings.CHUNK_SIZE默认750文本切分块大小字符数chunk_overlapintSettings.kb_settings.OVERLAP_SIZE默认150相邻分块重叠大小zh_title_enhanceboolSettings.kb_settings.ZH_TITLE_ENHANCE默认False是否启用中文标题增强切分4.2 三种迁移模式的语义务必先理解再操作源码 docstring 与分支实现migrate.py给出了清晰差异模式触发分支行为适用场景recreate_vskb.clear_vs()→create_kb()→ 全量 files2vs →save_vector_store()清空向量库并从本地文件夹全量重建同时把全部本地文件登记入库拷贝了新文档到content目录但向量库尚未填充或更换了DEFAULT_VS_TYPE/DEFAULT_EMBEDDING_MODEL需要整体重向量化update_in_db取kb.list_files()以数据库记录为基准→ files2vs → save只更新数据库里已存在文件的向量跳过仅存在于本地目录的文件只想为已入库文件重算向量例如换了切分参数后刷新incrementfiles set(folder_files) - set(db_files)→ files2vs → save只为本地存在但数据库没有的文件增量建向量与登记日常增量入库新文档执行流程先为每个kb_name通过KBServiceFactory.get_service(kb_name, vs_type, embed_model)获取服务实例工厂实现见 server/knowledge_base/kb_service/base.py若知识库尚不存在则create_kb()。每个知识库处理完毕后会打印汇总统计包括知识库名称、类型kb.vs_type()、向量模型、文件总数量、入库文件数、知识条目数各文件切分文档数求和、用时并仅对 FAISS 类型额外打印知识库路径kb.kb_path见 migrate.py。4.3 内部批量入库files2vsfiles2vs(kb_name, kb_files)是folder2db内部定义的辅助函数migrate.py承担文件 → 文档 → 向量的流水线调用files2docs_in_thread实现于 server/knowledge_base/utils.py基于多线程把KnowledgeFile列表转成文档期间应用chunk_size、chunk_overlap、zh_title_enhance三个切分参数对每个返回元组(success, res)判定失败则直接打印错误成功则解包出文件名与文档列表重建一个KnowledgeFile把切分好的splited_docs挂到kb_file.splited_docs上调用知识库服务实例kb.add_doc(kb_file, not_refresh_vs_cacheTrue)入库——注意not_refresh_vs_cacheTrue即单文件入向量库后不立即刷新缓存批量完成后再由外层统一kb.save_vector_store()既提升批量性能也保证最终一致性把{kb_name, file, docs}追加进 result供外层统计成功数。4.4 CLI 触发方式三种模式都通过worker分派init_database.py与命令行参数的对应关系如下# 全量重建所有知识库-e 可换 Embedding 模型-n 可限定知识库名可重复传 python chatchat/init_database.py -r python chatchat/init_database.py -r -e text2vec-base-chinese -n samples # 只更新数据库中已存在文件的向量 python chatchat/init_database.py -u # 增量补建只为本地有而库里没有的文件建向量 python chatchat/init_database.py -i # 参数释义--help 输出原文核心语义 # -r/--recreate-vs : 已把文档放进 content 目录但向量库未建或 DEFAULT_VS_TYPE/DEFAULT_EMBEDDING_MODEL 已变更时使用 # -u/--update-in-db : 为已入库文件重建向量跳过只在本地目录的文件 # -i/--increment : 为本地存在、库中不存在的文件增量创建向量 # -n/--kb-name : 指定要操作的知识库名默认处理 KB_ROOT_PATH 下全部目录可多次指定 # -e/--embed-model : 指定 Embedding 模型默认 get_default_embedding()此外若使用统一 CLI 入口chatchat kb命令会转发到本模块的main见 cli.py 的main.add_command(kb_main, kb)chatchat init -r --recreate-kb则会在初始化阶段直接调用一次folder2db(kb_names..., moderecreate_vs, ...)cli.py并建议随后执行chatchat start -a启动服务。4.5 测试验证三种模式都有用例背书tests/test_migrate.py 从正反两侧验证了迁移流程test_recreate_vs先建测试知识库test_kb_for_migrate素材readme.md拷贝自仓库根目录调用folder2db([kb_name], recreate_vs)后断言知识库存在、文件在kb.list_files()中、且每个切分文档的metadata[source]均等于文件名同时覆盖按文件名与按 metadata 两种list_docs检索test_increment先清空向量库使list_files()[]再以increment模式重建并做同样断言。这意味着全量重建 / 增量补建都能得到可被元数据检索命中的向量索引是有自动化用例保证的。五、本地文件与数据库的双向清理用户常直接在文件浏览器里增删content目录下的文档这会造成本地与数据库/向量库状态漂移。模块提供方向相反的两个清理函数原理都是求差集 复用服务能力。5.1 prune_db_docs删除库中残留的幽灵文档场景本地文件已被删除但数据库记录与向量还留着。prune_db_docs(kb_names)migrate.py的处理步骤KBServiceFactory.get_service_by_name(kb_name)按名称取服务实例取不到如drop_kb后返回None则跳过该库kb.list_files()拿到库内文件list_files_from_folder(kb_name)utils 中实现拿到本地目录文件求set(files_in_db) - set(files_in_folder)得到库里有、本地无的集合经file_to_kbfile转成KnowledgeFile后逐个kb.delete_doc(kb_file, not_refresh_vs_cacheTrue)并打印success to delete docs for file: kb_name/file全部删完后调用一次kb.save_vector_store()统一落盘向量缓存。5.2 prune_folder_files删除本地未被登记的孤儿文件场景某些文件从未入库或库内记录已删留在磁盘上白白占用空间。prune_folder_files(kb_names)migrate.py方向相反同样先取服务实例并跳过不存在的库求set(files_in_folder) - set(files_in_db)即本地有、库中无对每个文件调用os.remove(get_file_path(kb_name, file))直接物理删除并打印success to delete file: kb_name/file。高危提醒os.remove是物理删除且不可逆执行前务必确认这些文件确实无需保留例如已人工核对不需要入库并做好备份。对应 CLIinit_database.py为# 用户删除了文件浏览器中的文档后同步清掉数据库里的对应记录与向量 python chatchat/init_database.py --prune-db # 释放磁盘删除本地存在但数据库未登记的无用文件 python chatchat/init_database.py --prune-folder两者也建议配合-n限定知识库范围避免误伤其它库。测试方面test_prune_db删除本地文件→prune_db_docs→断言库内文件与 docs 均消失与test_prune_folder先删库内 doc→prune_folder_files→断言本地文件被物理删除共同验证了这两条清理链路的正确性见 test_migrate.py。六、file_to_kbfile两条主流程共用的文件封装file_to_kbfile(kb_name, files)migrate.py把知识库名 文件名列表统一转成KnowledgeFile列表遍历文件列表逐个构造KnowledgeFile(filenamefile, knowledge_base_namekb_name)单个文件构造失败如格式不支持时打印{异常类}: {e}已跳过并继续返回成功构造的对象列表。KnowledgeFile类定义于 server/knowledge_base/utils.py是贯穿全文档加载、切分、入库流程的核心载体。该辅助函数在folder2db三种模式migrate.py与prune_db_docs中都被复用是理解上述流程的最小公共单元。调用示例from chatchat.server.knowledge_base.utils import KnowledgeFile kb_files file_to_kbfile(demo_kb, [document1.md, document2.txt]) # 结果形如 [KnowledgeFile(filenamedocument1.md, knowledge_base_namedemo_kb), # KnowledgeFile(filenamedocument2.txt, knowledge_base_namedemo_kb)]注意调用前需确保文件真实存在于磁盘若依赖日志排查跳过原因日志详细度受全局log_verbose配置控制。七、操作速查与实践建议7.1 常见运维场景的推荐组合你的需求推荐命令/调用刚部署完、首次把本地知识库文档向量化chatchat init必要时加-r/--recreate-kb或python chatchat/init_database.py -r换了 Embedding 模型 / 改了默认向量库类型需要整体重建python chatchat/init_database.py -r -e 新embed模型只希望已入库文件按新切分参数重向量化python chatchat/init_database.py -u每天往content目录丢新文档想只补增量python chatchat/init_database.py -i在文件管理器里删了文档想清库中残留python chatchat/init_database.py --prune-db本地积压大量未登记文件想释放磁盘python chatchat/init_database.py --prune-folder先确认无用大版本升级后 info.db 结构变化但向量无需重建python chatchat/init_database.py --import-db 旧库路径测试环境表结构脏了想重置python chatchat/init_database.py --clear-tables7.2 三条必须牢记的边界create_tables只建新表不改旧表结构升级依赖import_from_db或人工迁移不要把建表函数当作升级工具reset_tables与prune_folder_files具备破坏性一个清空全部表、一个物理删文件生产环境操作前必须备份import_from_db当前仅支持 SQLite并要求备份库的表名与字段名交集和当前 ORM 模型兼容执行时保证目标库无并发写入。7.3 再探一步想要在业务代码中直接调用而不走 CLI可参照 test_migrate.py 的写法引入from chatchat.server.knowledge_base.migrate import ( create_tables, reset_tables, import_from_db, file_to_kbfile, folder2db, prune_db_docs, prune_folder_files, )例如在初始化脚本里先create_tables()保证表存在再按模式调用folder2db([samples], increment)增量入库完成后通过KBServiceFactory.get_service_by_name校验list_files()。函数入参默认值统一来自Settings.kb_settings见 settings.py 与对应配置文档 settings.md即切分与向量化行为与全站配置保持一致无需在每次调用时手工重复传入。【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Langchain-Chatchat 知识库迁移机制全解：从建表、三种向量库重建模式到数据清理与版本升级导入
Langchain-Chatchat 知识库迁移机制全解从建表、三种向量库重建模式到数据清理与版本升级导入【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat导读Langchain-Chatchat基于 Langchain 的本地知识库 RAG 与 Agent 应用把知识库文档入库拆成两套存储体系——SQLite 元数据库info.db 等记录文件与切分信息与向量数据库默认 faiss也可用 milvus/pg/chromadb 等。当本地content文件夹中已有现成文档、而数据库或向量库尚未同步例如更换了 Embedding 模型、调整了默认向量库类型、或数据库结构随版本升级变化时就需要一套可复用的迁移能力。本文将围绕 migrate.md 与其底层实现 migrate.py完整讲解建表/重置表、从旧 SQLite 备份导数据、以本地文件夹为基准填充库的三种模式recreate_vs / update_in_db / increment、双向清理prune_db_docs / prune_folder_files并结合 init_database.py 的 CLI 参数与 test_migrate.py 给出可直接落地的操作方案。读完本文你将掌握知识库元数据表是如何被创建与重置的、版本升级时如何不动向量库地导入旧库数据、如何按需全量重建 / 只更新库内文件 / 增量补建向量索引以及如何通过两条 prune 命令让本地文件与数据库保持最终一致避免磁盘被无用文档占满或数据库残留已删除文件的脏记录。一、迁移模块的整体定位在 chatchat-server 的包结构中该模块位于 server/knowledge_base/migrate.py是知识库管理knowledge_base 文档组中最核心的数据库 ↔ 本地文件夹 ↔ 向量库三向同步工具。它对外暴露七个主要函数函数职责影响面create_tables依据 ORM 元数据创建全部数据库表数据库结构reset_tables先 drop 全部表再重建回到干净初始态数据库结构破坏性import_from_db(sqlite_path)从旧版 SQLite 备份把行数据导入当前库仅数据不动向量库file_to_kbfile(kb_name, files)文件名列表 →KnowledgeFile对象列表公共辅助folder2db(kb_names, mode, ...)以本地文件夹为基准执行三种模式的入库数据库 向量库prune_db_docs(kb_names)删除库里有、本地文件夹已无的文档数据库 向量库prune_folder_files(kb_names)删除本地有、库里未登记的文档文件本地磁盘破坏性从源码调用关系看init_database.py 一次性导入了create_tables、reset_tables、folder2db、import_from_db、prune_db_docs、prune_folder_files这些函数是知识库初始化与迁移 CLI 的全部底层动作。二、表结构的创建与重置create_tables 与 reset_tables2.1 create_tables只建不动的安全函数create_tables的实现只有一行核心逻辑见 migrate.pydef create_tables(): Base.metadata.create_all(bindengine)Base是 SQLAlchemy 的声明式 ORM 基类集中持有本项目全部表模型的元数据相关模型集中在 server/db/models对话、消息、知识库、知识文件、知识元数据、MCP 连接、HumanMessageEvent 等表。engine是 SQLAlchemy 连接引擎实际连接目标数据库。SQLAlchemy 的create_all采用只创建不存在的表语义已存在的表不会被修改或更新因此该函数是幂等且相对安全的适合在初始化与启动流程中反复调用。它的实际调用场景包括均可从源码确认项目初始化chatchat init在 cli.py 中先执行create_tables()保证数据表齐全后再继续服务器启动若表不存在则先建表见 startup.py 中对create_tables的导入重置流程reset_tables删除后调用它重建见 2.2向量库相关测试如 tests/kb_vector_db/test_faiss_kb.py、test_milvus_db.py、test_pg_db.py 在用例前都先 importcreate_tables以保证测试环境表结构正确。注意因为它不会更新已有表结构所以当升级后的模型新增了字段、表结构发生变更时需要配合数据库备份迁移见第三节 import_from_db或人工执行 DDL单纯调用本函数无法完成结构升级。2.2 reset_tables彻底清空后重建def reset_tables(): Base.metadata.drop_all(bindengine) create_tables()先drop_all删除当前数据库中的全部表再调用create_tables重建得到一份干净的初始表结构见 migrate.py。典型用途测试环境重置、或希望彻底清空元数据后从头重建知识库登记信息。高危警告会删除所有表及其中数据且不可回滚生产环境使用前必须备份数据库文件文档与源码函数 docstring 与注释均强调了这一点。2.3 对应 CLI--create-tables 与 --clear-tables在 init_database.py 的worker中参数被映射为CLI 参数触发动作--create-tables调用create_tables()确认表存在--clear-tables先reset_tables()再打印database tables reset# 只补建缺失的表 python chatchat/init_database.py --create-tables # 清空并重建全部表危险操作请先备份 python chatchat/init_database.py --clear-tables三、版本升级数据导入import_from_db3.1 适用场景与前提Langchain-Chatchat 的知识库元数据存放在 SQLiteinfo.db中。当版本升级导致 info.db 的表结构变化但文档内容与已向量化的数据没有变化时没有必要重新做一遍全文切分与向量化——只需把旧库里的结构化数据搬进新库即可。这正是import_from_db的存在意义docstring 见 migrate.py。使用前提有三条必须同时满足传入的sqlite_path是合法的 SQLite 数据库文件路径备份库的表名、需要导入的字段名与当前 ORM 模型一致函数只做名称交集过滤不负责重命名当前仅支持 SQLite直接使用sqlite3标准库连接其它数据库备份不在支持范围内。3.2 实现原理与字段处理核心流程migrate.pymodels list(Base.registry.mappers)拿到当前注册的全部 ORM 模型映射连接旧库通过sqlite_master查得全部表名遍历每个模型取model.local_table.fullname与旧库表名比对表不存在则跳过该模型对存在的表逐行select *再用{k: row[k] for k in row.keys() if k in model.columns}做字段名交集过滤只保留当前模型确实存在的列特殊处理时间字段若行含create_time调用dateutil.parser.parse见文件顶部from dateutil.parser import parse把字符串解析为正确的时间对象避免 SQLite 时间格式与 ORM DateTime 列类型冲突在session_scope()上下文内session.add(model.class_(**data))逐行添加依赖上下文管理器自动提交/回滚会话管理实现在 server/db/session.py全部成功则关闭连接并返回True任何异常打印无法读取备份数据库{sqlite_path}。错误信息{e}并返回False。3.3 CLI 用法python chatchat/init_database.py --import-db /path/to/old/info.db执行前务必停止一切对目标库的读写操作源码注释明确要求避免数据冲突并确认新库的表已创建必要时先跑--create-tables。四、以本地文件夹为基准填充数据库与向量库folder2db4.1 参数清单folder2db是本模块的重头戏。完整签名与默认值见 migrate.py其中多个默认值直接来自Settings.kb_settings定义于 settings.py默认向量类型、切分参数等集中在此参数类型/取值默认值说明kb_namesList[str]—为None时取list_kbs_from_folder()即KB_ROOT_PATH下全部知识库目录要处理的知识库名称列表moderecreate_vs/update_in_db/increment无必填迁移模式语义见 4.2vs_typefaiss/milvus/pg/chromadbSettings.kb_settings.DEFAULT_VS_TYPE默认faiss向量库类型注意全局设置项还支持 zilliz/es/relyt此处函数级字面量限定了这四种embed_modelstrget_default_embedding()默认模型取配置如bge-m3Embedding 模型名chunk_sizeintSettings.kb_settings.CHUNK_SIZE默认750文本切分块大小字符数chunk_overlapintSettings.kb_settings.OVERLAP_SIZE默认150相邻分块重叠大小zh_title_enhanceboolSettings.kb_settings.ZH_TITLE_ENHANCE默认False是否启用中文标题增强切分4.2 三种迁移模式的语义务必先理解再操作源码 docstring 与分支实现migrate.py给出了清晰差异模式触发分支行为适用场景recreate_vskb.clear_vs()→create_kb()→ 全量 files2vs →save_vector_store()清空向量库并从本地文件夹全量重建同时把全部本地文件登记入库拷贝了新文档到content目录但向量库尚未填充或更换了DEFAULT_VS_TYPE/DEFAULT_EMBEDDING_MODEL需要整体重向量化update_in_db取kb.list_files()以数据库记录为基准→ files2vs → save只更新数据库里已存在文件的向量跳过仅存在于本地目录的文件只想为已入库文件重算向量例如换了切分参数后刷新incrementfiles set(folder_files) - set(db_files)→ files2vs → save只为本地存在但数据库没有的文件增量建向量与登记日常增量入库新文档执行流程先为每个kb_name通过KBServiceFactory.get_service(kb_name, vs_type, embed_model)获取服务实例工厂实现见 server/knowledge_base/kb_service/base.py若知识库尚不存在则create_kb()。每个知识库处理完毕后会打印汇总统计包括知识库名称、类型kb.vs_type()、向量模型、文件总数量、入库文件数、知识条目数各文件切分文档数求和、用时并仅对 FAISS 类型额外打印知识库路径kb.kb_path见 migrate.py。4.3 内部批量入库files2vsfiles2vs(kb_name, kb_files)是folder2db内部定义的辅助函数migrate.py承担文件 → 文档 → 向量的流水线调用files2docs_in_thread实现于 server/knowledge_base/utils.py基于多线程把KnowledgeFile列表转成文档期间应用chunk_size、chunk_overlap、zh_title_enhance三个切分参数对每个返回元组(success, res)判定失败则直接打印错误成功则解包出文件名与文档列表重建一个KnowledgeFile把切分好的splited_docs挂到kb_file.splited_docs上调用知识库服务实例kb.add_doc(kb_file, not_refresh_vs_cacheTrue)入库——注意not_refresh_vs_cacheTrue即单文件入向量库后不立即刷新缓存批量完成后再由外层统一kb.save_vector_store()既提升批量性能也保证最终一致性把{kb_name, file, docs}追加进 result供外层统计成功数。4.4 CLI 触发方式三种模式都通过worker分派init_database.py与命令行参数的对应关系如下# 全量重建所有知识库-e 可换 Embedding 模型-n 可限定知识库名可重复传 python chatchat/init_database.py -r python chatchat/init_database.py -r -e text2vec-base-chinese -n samples # 只更新数据库中已存在文件的向量 python chatchat/init_database.py -u # 增量补建只为本地有而库里没有的文件建向量 python chatchat/init_database.py -i # 参数释义--help 输出原文核心语义 # -r/--recreate-vs : 已把文档放进 content 目录但向量库未建或 DEFAULT_VS_TYPE/DEFAULT_EMBEDDING_MODEL 已变更时使用 # -u/--update-in-db : 为已入库文件重建向量跳过只在本地目录的文件 # -i/--increment : 为本地存在、库中不存在的文件增量创建向量 # -n/--kb-name : 指定要操作的知识库名默认处理 KB_ROOT_PATH 下全部目录可多次指定 # -e/--embed-model : 指定 Embedding 模型默认 get_default_embedding()此外若使用统一 CLI 入口chatchat kb命令会转发到本模块的main见 cli.py 的main.add_command(kb_main, kb)chatchat init -r --recreate-kb则会在初始化阶段直接调用一次folder2db(kb_names..., moderecreate_vs, ...)cli.py并建议随后执行chatchat start -a启动服务。4.5 测试验证三种模式都有用例背书tests/test_migrate.py 从正反两侧验证了迁移流程test_recreate_vs先建测试知识库test_kb_for_migrate素材readme.md拷贝自仓库根目录调用folder2db([kb_name], recreate_vs)后断言知识库存在、文件在kb.list_files()中、且每个切分文档的metadata[source]均等于文件名同时覆盖按文件名与按 metadata 两种list_docs检索test_increment先清空向量库使list_files()[]再以increment模式重建并做同样断言。这意味着全量重建 / 增量补建都能得到可被元数据检索命中的向量索引是有自动化用例保证的。五、本地文件与数据库的双向清理用户常直接在文件浏览器里增删content目录下的文档这会造成本地与数据库/向量库状态漂移。模块提供方向相反的两个清理函数原理都是求差集 复用服务能力。5.1 prune_db_docs删除库中残留的幽灵文档场景本地文件已被删除但数据库记录与向量还留着。prune_db_docs(kb_names)migrate.py的处理步骤KBServiceFactory.get_service_by_name(kb_name)按名称取服务实例取不到如drop_kb后返回None则跳过该库kb.list_files()拿到库内文件list_files_from_folder(kb_name)utils 中实现拿到本地目录文件求set(files_in_db) - set(files_in_folder)得到库里有、本地无的集合经file_to_kbfile转成KnowledgeFile后逐个kb.delete_doc(kb_file, not_refresh_vs_cacheTrue)并打印success to delete docs for file: kb_name/file全部删完后调用一次kb.save_vector_store()统一落盘向量缓存。5.2 prune_folder_files删除本地未被登记的孤儿文件场景某些文件从未入库或库内记录已删留在磁盘上白白占用空间。prune_folder_files(kb_names)migrate.py方向相反同样先取服务实例并跳过不存在的库求set(files_in_folder) - set(files_in_db)即本地有、库中无对每个文件调用os.remove(get_file_path(kb_name, file))直接物理删除并打印success to delete file: kb_name/file。高危提醒os.remove是物理删除且不可逆执行前务必确认这些文件确实无需保留例如已人工核对不需要入库并做好备份。对应 CLIinit_database.py为# 用户删除了文件浏览器中的文档后同步清掉数据库里的对应记录与向量 python chatchat/init_database.py --prune-db # 释放磁盘删除本地存在但数据库未登记的无用文件 python chatchat/init_database.py --prune-folder两者也建议配合-n限定知识库范围避免误伤其它库。测试方面test_prune_db删除本地文件→prune_db_docs→断言库内文件与 docs 均消失与test_prune_folder先删库内 doc→prune_folder_files→断言本地文件被物理删除共同验证了这两条清理链路的正确性见 test_migrate.py。六、file_to_kbfile两条主流程共用的文件封装file_to_kbfile(kb_name, files)migrate.py把知识库名 文件名列表统一转成KnowledgeFile列表遍历文件列表逐个构造KnowledgeFile(filenamefile, knowledge_base_namekb_name)单个文件构造失败如格式不支持时打印{异常类}: {e}已跳过并继续返回成功构造的对象列表。KnowledgeFile类定义于 server/knowledge_base/utils.py是贯穿全文档加载、切分、入库流程的核心载体。该辅助函数在folder2db三种模式migrate.py与prune_db_docs中都被复用是理解上述流程的最小公共单元。调用示例from chatchat.server.knowledge_base.utils import KnowledgeFile kb_files file_to_kbfile(demo_kb, [document1.md, document2.txt]) # 结果形如 [KnowledgeFile(filenamedocument1.md, knowledge_base_namedemo_kb), # KnowledgeFile(filenamedocument2.txt, knowledge_base_namedemo_kb)]注意调用前需确保文件真实存在于磁盘若依赖日志排查跳过原因日志详细度受全局log_verbose配置控制。七、操作速查与实践建议7.1 常见运维场景的推荐组合你的需求推荐命令/调用刚部署完、首次把本地知识库文档向量化chatchat init必要时加-r/--recreate-kb或python chatchat/init_database.py -r换了 Embedding 模型 / 改了默认向量库类型需要整体重建python chatchat/init_database.py -r -e 新embed模型只希望已入库文件按新切分参数重向量化python chatchat/init_database.py -u每天往content目录丢新文档想只补增量python chatchat/init_database.py -i在文件管理器里删了文档想清库中残留python chatchat/init_database.py --prune-db本地积压大量未登记文件想释放磁盘python chatchat/init_database.py --prune-folder先确认无用大版本升级后 info.db 结构变化但向量无需重建python chatchat/init_database.py --import-db 旧库路径测试环境表结构脏了想重置python chatchat/init_database.py --clear-tables7.2 三条必须牢记的边界create_tables只建新表不改旧表结构升级依赖import_from_db或人工迁移不要把建表函数当作升级工具reset_tables与prune_folder_files具备破坏性一个清空全部表、一个物理删文件生产环境操作前必须备份import_from_db当前仅支持 SQLite并要求备份库的表名与字段名交集和当前 ORM 模型兼容执行时保证目标库无并发写入。7.3 再探一步想要在业务代码中直接调用而不走 CLI可参照 test_migrate.py 的写法引入from chatchat.server.knowledge_base.migrate import ( create_tables, reset_tables, import_from_db, file_to_kbfile, folder2db, prune_db_docs, prune_folder_files, )例如在初始化脚本里先create_tables()保证表存在再按模式调用folder2db([samples], increment)增量入库完成后通过KBServiceFactory.get_service_by_name校验list_files()。函数入参默认值统一来自Settings.kb_settings见 settings.py 与对应配置文档 settings.md即切分与向量化行为与全站配置保持一致无需在每次调用时手工重复传入。【免费下载链接】Langchain-ChatchatLangchain-Chatchat原Langchain-ChatGLM基于 Langchain 与 ChatGLM, Qwen 与 Llama 等语言模型的 RAG 与 Agent 应用 | Langchain-Chatchat (formerly langchain-ChatGLM), local knowledge based LLM (like ChatGLM, Qwen and Llama) RAG and Agent app with langchain项目地址: https://gitcode.com/GitHub_Trending/la/Langchain-Chatchat创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考