尧图网站建设 
GPT4All LocalDocs 实战指南用本地嵌入索引把设备上的文档带进 LLM 对话【免费下载链接】gpt4allGPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4allLocalDocs 是 GPT4All 桌面端的核心 RAG检索增强生成能力它把设备上的文件文件夹按设置切片用 Nomic 的嵌入模型为每个文本片段生成嵌入向量再在对话中做语义检索把与提问最相关的片段注入 LLM 提示词——全程在本地完成数据不出设备。读完本文你将掌握 LocalDocs 集合的创建与重建流程、全部可配置项分片大小、检索条数、文件扩展名、嵌入设备等的默认值与取舍以及从 LocalDocs 单例、Database 向量库到 EmbeddingLLM 的完整源码调用链从而能准确判断它为什么快、何时会慢、如何调整。一、LocalDocs 解决什么问题LocalDocs 把你设备上文件中的信息私有地带入 LLM 对话原文定义brings the information you have from files on-device into your LLM chats — privately。它的工作方式是把一个文件夹登记为一个collection集合集合内的文件按扩展名白名单筛选后被切成固定大小的文本片段snippets/chunks每个片段由嵌入模型计算得到一个嵌入向量你在聊天框输入的问题也会被嵌入系统通过向量相似度找到语义最接近的片段这些片段被追加进发给 LLM 的提示词模型据此基于你的私有文档作答并在回答下方给出Sources来源列表。二、创建 LocalDocs 集合操作步骤以下流程与桌面端 LocalDocs 视图 和 AddCollectionView 的交互一一对应点击 Add Collection进入新建集合页面为集合命名并关联一个文件夹即截图所示的 New Collection 表单填写名称后选择本地目录点击Create Collection。索引进度会显示在 LocalDocs 页面每个集合条目展示正在索引的文件数 / 总文件数、已嵌入条数 / 总条数等统计。集合全部就绪后会看到绿色的Ready指示器。注意在整集合就绪之前你已经可以针对已就绪的文件进行对话源码中集合项的状态角色IndexingRole、CurrentDocsToIndexRole、TotalDocsToIndexRole、TotalEmbeddingsToIndexRole等在 LocalDocsModel 中定义供 UI 逐条刷新在聊天界面中点击右上角按钮打开LocalDocs勾选/选择要参与本次对话的集合即可让 LLM 获得这些文件的上下文点击 LLM 回答下方的Sources查看本次回答实际引用了哪些文件与片段是否默认展示由设置项Show Sources控制。后续重建修改 LocalDocs 设置如换嵌入模型、调整分片大小之后可以用新设置**重建rebuild**集合而不是删掉重来。重建入口对应 LocalDocs::forceIndexing()它会携带当前EmbeddingLLM::model()发出requestForceIndexing信号Database::forceIndexing() 会先更新集合的embedding_model字段再触发对文件夹的重新扫描与重新嵌入。此外LocalDocs::addFolder() / removeFolder() 分别支持向集合增删文件夹——addFolder在取得嵌入模型为空时会直接告警返回这是没有嵌入模型就无法建索引的硬前提。三、工作原理从文件到嵌入向量3.1 分片chunkSize 决定检索粒度文件夹被登记后Database 会对白名单扩展名的文件做文本抽取与分片每个片段存入 SQLite 的chunks表。分片大小由localdocs/chunkSize字符数控制默认512 字符。分片是检索单元查询只会命中整段片段片段再被拼接进提示词。因此分片越大单片包含的上下文越完整回答越可能贴合事实但单次生成的 token 越多、速度越慢且相似度匹配的精准度下降分片越小检索越聚焦但容易把一句话拆断造成上下文缺失。LocalDocs 设置页 对这两个高级参数有明确警告Values too large may cause localdocs failure, extremely slow responses or failure to respond at all数值过大会导致 LocalDocs 失败、响应极慢甚至无响应并提示约等于N 个字符 × N 个片段会被加进模型上下文窗口——这就是为什么它被归入 Advanced usage only 区块。3.2 嵌入模型本地模型 与 Nomic Embed API 二选一How It Works 原文指出LocalDocs 集合使用Nomic AI 免费、快速的设备端嵌入模型把文件夹索引为带嵌入向量的文本片段这些向量用于在你的问题和提示词与文件片段之间做语义相似度匹配。从源码结构看GPT4All 对嵌入计算提供两条路径由 EmbeddingLLMWorker 统一封装本地模型路径m_modelLLModel *指向一个嵌入专用的本地模型EmbeddingLLM::generateDocEmbeddingsAsync() 把片段批次QVectorEmbeddingChunk交给独立工作线程QThread m_workerThread计算避免阻塞 UINomic 云端 API 路径m_nomicAPIKey非空时isNomic()判断通过QNetworkAccessManager走 HTTP 请求 Nomic Embed API本地不做嵌入计算查询侧嵌入EmbeddingLLM::generateQueryEmbedding() 对用户提问做同步嵌入查询文本很短无需异步。每条结果EmbeddingResult携带model / folder_id / chunk_id / std::vectorfloat embedding写回数据库时按(model, folder_id, chunk_id)定位到对应片段见 database.cpp 中的 sqlAddEmbeddings 逻辑因此不同嵌入模型产生的向量互不混用——这也是更换嵌入模型后必须重建集合的原因。3.3 向量检索usearch 索引 语义取回向量存储基于 usearchnamespace us unum::usearch;见 database.cpp。对话发起检索时调用链是ChatLLM 读取localDocsRetrievalSize()对已启用集合发出requestRetrieveFromDB(enabledCollections, queryStr, retrievalSize, databaseResults)阻塞等待EmbeddingLLM生成查询向量数据库在 usearch 索引中做最近邻检索取回 top-N 片段的chunk_text拼接进系统提示词上下文。检索条数由localdocs/retrievalSizeMax document snippets per prompt控制默认3。设置页的帮助文本同样提示数值越大越可能提高事实性但生成更慢——它直接决定了片段字符数 × 片段条数注入的上下文体量。四、LocalDocs 全部设置项与默认值以下默认值来自 MySettings 的 basicDefaults界面配置逻辑在 LocalDocsSettings.qml设置项存储键界面名称默认值说明localdocs/chunkSizeDocument snippet size (characters)512每个文本片段的字符数越大越保真但越慢localdocs/retrievalSizeMax document snippets per prompt3每次提示词注入的最多片段条数localdocs/showReferencesShow Sourcestrue回答下方是否展示引用来源localdocs/fileExtensionsAllowed File Extensionsdocx, pdf, txt, md, rst逗号分隔白名单只索引这些扩展名的文件localdocs/useRemoteEmbedUse Nomic Embed APIfalse改用 Nomic 云端 API 而非本地嵌入模型需重启localdocs/nomicAPIKeyNomic API Key空形如nk- 43 位字母数字QML 内以正则/^(nk-[a-zA-Z0-9_-]{43})?$/校验需重启localdocs/embedDeviceEmbeddings DeviceAuto本地嵌入使用的计算设备Auto 表示应用默认需重启几个实现层面的细节值得注意扩展名白名单带硬编码黑名单LocalDocsSettings.qml 在用户输入后会剔除常见不支持的扩展名Office 二进制格式、图片、音视频、可执行文件、压缩包等并做了小写化与去重。注释说明其立场We only support plain text and PDFs——本地路径只真正处理纯文本类与 PDFdocx通过 QXlsx/OOXML 相关依赖解析为文本。修改 chunkSize / 扩展名会即时广播MySettings 的变更信号 触发 LocalDocs::handleChunkSizeChanged() / handleFileExtensionsChanged()进而调用Database::changeChunkSize / changeFileExtensions使已有集合按新参数重建索引数据库以设置创建LocalDocs构造时即用当前chunkSize与fileExtensions初始化 Database并通过Qt::QueuedConnection把requestStart、requestAddFolder、requestRemoveFolder、requestForceIndexing等信号全部桥接到 Database 线程侧槽函数保证索引操作不占用 GUI 线程。五、源码结构速览组件文件职责LocalDocs单例localdocs.h / localdocs.cpp对外暴露addFolder、removeFolder、forceIndexing等 Q_INVOKABLE持有Database与LocalDocsModel负责信号路由LocalDocsModellocaldocsmodel.h集合列表的 Qt 模型QAbstractListModel提供进度/状态角色供 QML 绑定Databasedatabase.cppSQLite 元数据chunks、embeddings、collections表 usearch 向量索引 文件扫描与分片流ChunkStreamerEmbeddingLLMembllm.h嵌入门面本地LLModel或 Nomic API查询嵌入同步与文档嵌入异步设置持久化mysettings.cpplocaldocs/*键的读写与默认值、变更信号UILocalDocsSettings.qml、AddCollectionView.qml设置表单、新建集合对话框、进度展示六、使用前提与限制必须先有可用嵌入模型addFolder与forceIndexing都会先检查EmbeddingLLM::model()为空则记录 ERROR: We have no embedding model 并中止。即对话模型与嵌入模型是两回事后者缺失时 LocalDocs 完全不可用换模型 / 改参数需要重建向量按embedding_model字段隔离存储旧向量对新模型无效需走 rebuild 流程上下文窗口预算注入片段约为chunkSize × retrievalSize字符量级对短上下文模型要谨慎调大这两个值隐私边界默认useRemoteEmbedfalse嵌入全部在本地完成勾选 Nomic Embed API 后文档片段会经网络发送到 Nomic 服务做嵌入计算不再完全离线——按设置页说明该项需重启应用生效。【免费下载链接】gpt4allGPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4all创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 GPT4All LocalDocs 实战指南：用本地嵌入索引把设备上的文档带进 LLM 对话
GPT4All LocalDocs 实战指南用本地嵌入索引把设备上的文档带进 LLM 对话【免费下载链接】gpt4allGPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4allLocalDocs 是 GPT4All 桌面端的核心 RAG检索增强生成能力它把设备上的文件文件夹按设置切片用 Nomic 的嵌入模型为每个文本片段生成嵌入向量再在对话中做语义检索把与提问最相关的片段注入 LLM 提示词——全程在本地完成数据不出设备。读完本文你将掌握 LocalDocs 集合的创建与重建流程、全部可配置项分片大小、检索条数、文件扩展名、嵌入设备等的默认值与取舍以及从 LocalDocs 单例、Database 向量库到 EmbeddingLLM 的完整源码调用链从而能准确判断它为什么快、何时会慢、如何调整。一、LocalDocs 解决什么问题LocalDocs 把你设备上文件中的信息私有地带入 LLM 对话原文定义brings the information you have from files on-device into your LLM chats — privately。它的工作方式是把一个文件夹登记为一个collection集合集合内的文件按扩展名白名单筛选后被切成固定大小的文本片段snippets/chunks每个片段由嵌入模型计算得到一个嵌入向量你在聊天框输入的问题也会被嵌入系统通过向量相似度找到语义最接近的片段这些片段被追加进发给 LLM 的提示词模型据此基于你的私有文档作答并在回答下方给出Sources来源列表。二、创建 LocalDocs 集合操作步骤以下流程与桌面端 LocalDocs 视图 和 AddCollectionView 的交互一一对应点击 Add Collection进入新建集合页面为集合命名并关联一个文件夹即截图所示的 New Collection 表单填写名称后选择本地目录点击Create Collection。索引进度会显示在 LocalDocs 页面每个集合条目展示正在索引的文件数 / 总文件数、已嵌入条数 / 总条数等统计。集合全部就绪后会看到绿色的Ready指示器。注意在整集合就绪之前你已经可以针对已就绪的文件进行对话源码中集合项的状态角色IndexingRole、CurrentDocsToIndexRole、TotalDocsToIndexRole、TotalEmbeddingsToIndexRole等在 LocalDocsModel 中定义供 UI 逐条刷新在聊天界面中点击右上角按钮打开LocalDocs勾选/选择要参与本次对话的集合即可让 LLM 获得这些文件的上下文点击 LLM 回答下方的Sources查看本次回答实际引用了哪些文件与片段是否默认展示由设置项Show Sources控制。后续重建修改 LocalDocs 设置如换嵌入模型、调整分片大小之后可以用新设置**重建rebuild**集合而不是删掉重来。重建入口对应 LocalDocs::forceIndexing()它会携带当前EmbeddingLLM::model()发出requestForceIndexing信号Database::forceIndexing() 会先更新集合的embedding_model字段再触发对文件夹的重新扫描与重新嵌入。此外LocalDocs::addFolder() / removeFolder() 分别支持向集合增删文件夹——addFolder在取得嵌入模型为空时会直接告警返回这是没有嵌入模型就无法建索引的硬前提。三、工作原理从文件到嵌入向量3.1 分片chunkSize 决定检索粒度文件夹被登记后Database 会对白名单扩展名的文件做文本抽取与分片每个片段存入 SQLite 的chunks表。分片大小由localdocs/chunkSize字符数控制默认512 字符。分片是检索单元查询只会命中整段片段片段再被拼接进提示词。因此分片越大单片包含的上下文越完整回答越可能贴合事实但单次生成的 token 越多、速度越慢且相似度匹配的精准度下降分片越小检索越聚焦但容易把一句话拆断造成上下文缺失。LocalDocs 设置页 对这两个高级参数有明确警告Values too large may cause localdocs failure, extremely slow responses or failure to respond at all数值过大会导致 LocalDocs 失败、响应极慢甚至无响应并提示约等于N 个字符 × N 个片段会被加进模型上下文窗口——这就是为什么它被归入 Advanced usage only 区块。3.2 嵌入模型本地模型 与 Nomic Embed API 二选一How It Works 原文指出LocalDocs 集合使用Nomic AI 免费、快速的设备端嵌入模型把文件夹索引为带嵌入向量的文本片段这些向量用于在你的问题和提示词与文件片段之间做语义相似度匹配。从源码结构看GPT4All 对嵌入计算提供两条路径由 EmbeddingLLMWorker 统一封装本地模型路径m_modelLLModel *指向一个嵌入专用的本地模型EmbeddingLLM::generateDocEmbeddingsAsync() 把片段批次QVectorEmbeddingChunk交给独立工作线程QThread m_workerThread计算避免阻塞 UINomic 云端 API 路径m_nomicAPIKey非空时isNomic()判断通过QNetworkAccessManager走 HTTP 请求 Nomic Embed API本地不做嵌入计算查询侧嵌入EmbeddingLLM::generateQueryEmbedding() 对用户提问做同步嵌入查询文本很短无需异步。每条结果EmbeddingResult携带model / folder_id / chunk_id / std::vectorfloat embedding写回数据库时按(model, folder_id, chunk_id)定位到对应片段见 database.cpp 中的 sqlAddEmbeddings 逻辑因此不同嵌入模型产生的向量互不混用——这也是更换嵌入模型后必须重建集合的原因。3.3 向量检索usearch 索引 语义取回向量存储基于 usearchnamespace us unum::usearch;见 database.cpp。对话发起检索时调用链是ChatLLM 读取localDocsRetrievalSize()对已启用集合发出requestRetrieveFromDB(enabledCollections, queryStr, retrievalSize, databaseResults)阻塞等待EmbeddingLLM生成查询向量数据库在 usearch 索引中做最近邻检索取回 top-N 片段的chunk_text拼接进系统提示词上下文。检索条数由localdocs/retrievalSizeMax document snippets per prompt控制默认3。设置页的帮助文本同样提示数值越大越可能提高事实性但生成更慢——它直接决定了片段字符数 × 片段条数注入的上下文体量。四、LocalDocs 全部设置项与默认值以下默认值来自 MySettings 的 basicDefaults界面配置逻辑在 LocalDocsSettings.qml设置项存储键界面名称默认值说明localdocs/chunkSizeDocument snippet size (characters)512每个文本片段的字符数越大越保真但越慢localdocs/retrievalSizeMax document snippets per prompt3每次提示词注入的最多片段条数localdocs/showReferencesShow Sourcestrue回答下方是否展示引用来源localdocs/fileExtensionsAllowed File Extensionsdocx, pdf, txt, md, rst逗号分隔白名单只索引这些扩展名的文件localdocs/useRemoteEmbedUse Nomic Embed APIfalse改用 Nomic 云端 API 而非本地嵌入模型需重启localdocs/nomicAPIKeyNomic API Key空形如nk- 43 位字母数字QML 内以正则/^(nk-[a-zA-Z0-9_-]{43})?$/校验需重启localdocs/embedDeviceEmbeddings DeviceAuto本地嵌入使用的计算设备Auto 表示应用默认需重启几个实现层面的细节值得注意扩展名白名单带硬编码黑名单LocalDocsSettings.qml 在用户输入后会剔除常见不支持的扩展名Office 二进制格式、图片、音视频、可执行文件、压缩包等并做了小写化与去重。注释说明其立场We only support plain text and PDFs——本地路径只真正处理纯文本类与 PDFdocx通过 QXlsx/OOXML 相关依赖解析为文本。修改 chunkSize / 扩展名会即时广播MySettings 的变更信号 触发 LocalDocs::handleChunkSizeChanged() / handleFileExtensionsChanged()进而调用Database::changeChunkSize / changeFileExtensions使已有集合按新参数重建索引数据库以设置创建LocalDocs构造时即用当前chunkSize与fileExtensions初始化 Database并通过Qt::QueuedConnection把requestStart、requestAddFolder、requestRemoveFolder、requestForceIndexing等信号全部桥接到 Database 线程侧槽函数保证索引操作不占用 GUI 线程。五、源码结构速览组件文件职责LocalDocs单例localdocs.h / localdocs.cpp对外暴露addFolder、removeFolder、forceIndexing等 Q_INVOKABLE持有Database与LocalDocsModel负责信号路由LocalDocsModellocaldocsmodel.h集合列表的 Qt 模型QAbstractListModel提供进度/状态角色供 QML 绑定Databasedatabase.cppSQLite 元数据chunks、embeddings、collections表 usearch 向量索引 文件扫描与分片流ChunkStreamerEmbeddingLLMembllm.h嵌入门面本地LLModel或 Nomic API查询嵌入同步与文档嵌入异步设置持久化mysettings.cpplocaldocs/*键的读写与默认值、变更信号UILocalDocsSettings.qml、AddCollectionView.qml设置表单、新建集合对话框、进度展示六、使用前提与限制必须先有可用嵌入模型addFolder与forceIndexing都会先检查EmbeddingLLM::model()为空则记录 ERROR: We have no embedding model 并中止。即对话模型与嵌入模型是两回事后者缺失时 LocalDocs 完全不可用换模型 / 改参数需要重建向量按embedding_model字段隔离存储旧向量对新模型无效需走 rebuild 流程上下文窗口预算注入片段约为chunkSize × retrievalSize字符量级对短上下文模型要谨慎调大这两个值隐私边界默认useRemoteEmbedfalse嵌入全部在本地完成勾选 Nomic Embed API 后文档片段会经网络发送到 Nomic 服务做嵌入计算不再完全离线——按设置页说明该项需重启应用生效。【免费下载链接】gpt4allGPT4All: Run Local LLMs on Any Device. Open-source and available for commercial use.项目地址: https://gitcode.com/GitHub_Trending/gp/gpt4all创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考