导入文档到知识库

本指南说明如何把已有资料（论文、条款、研究笔记、报告等）导入到 Notez 的本地知识库，并让它们被 AI 检索、引用、续写与对话调用。

1. 支持的文件格式

类型	扩展名	说明
文本	.md / .mdx / .txt	Markdown 建议优先（结构清晰）
办公	.docx / .doc	仅正文（复杂样式会被简化）
PDF	.pdf	会提取可选文本层；扫描件需自行 OCR 后导入
结构化	.csv / .json (规划中)	即将支持；用于表格/结构数据

注意：加密 PDF、图片扫描无文字层、受 DRM 保护的文件无法索引（需先转换）。

2. 三种导入方式

2.1 拖拽导入（最快）

1. 在应用中打开「知识库」模块
2. 直接将文件或文件夹拖入窗口
3. 弹出任务队列 → 显示解析 / 分片 / 向量化进度

适合：临时批量导入、桌面已有整理好的目录。

2.2 按钮选择导入

1. 点击「上传文件」或「上传文件夹」
2. 在系统选择器中多选（Cmd/Shift 支持范围与离散选择）
3. 确认后加入解析队列

适合：精确挑选少量文件。

2.3 目录同步（持续更新）

1. 点击「添加同步目录」
2. 选择一个本地文件夹
3. 开启后：新增 / 修改 / 删除 会被监听并同步索引（延迟数秒）

适合：长期维护的项目仓库 / 研究文献目录。
提示：移动或重命名大量文件可能触发重建；建议在空闲时段操作。

3. 索引过程说明

导入后会进入内部流水线（按文件逐步执行）：

1. 解析（Parsing）：解码文本、清理多余格式
2. 结构抽取（Structure）：尝试识别标题、列表、分节（Markdown/Docx 最佳）
3. 分块（Chunking）：按语义或长度切片（避免超长输入）
4. 向量化（Embedding）：生成向量表示（取决于是否已配置嵌入模型）
5. 建立倒排索引（Keyword Index）
6. 附加分析（可选）：摘要 / 主题标签（开启深度搜索时）

状态指示：

• 等待中 / 解析中 / 索引中 / 已完成 / 失败
  失败常见原因：文件损坏、无文本层、编码错误。

6. 更新与删除策略

一旦上传，Notez不会执行任何的更新或者删除，除非用户手动操作。

7. 隐私与本地性

• 所有原始文件、解析缓存、向量均存储于本地应用数据目录
• 仅在调用外部大模型时，将相关上下文片段（截断后）随请求发送
• 未开启模型配置时，只建立关键字索引（功能受限但完全离线）

8. 与 AI 功能的联动

功能	使用导入成果方式
智能续写	自动检索相似片段并融合
Chat 问答	基于向量召回 + 关键词过滤
引用溯源	返回片段 + 原文件名 + 标题锚点
选中文本增强	反向检索上下文提供补充证据

若某文件未被引用：检查是否完成嵌入构建。

9. 常见问题 (FAQ)

Q: PDF 乱码？
A: 可能是图片扫描或自定义字体。先用 OCR（如 ocrmypdf）转换为可选文本。

Q: 新增文件很晚才出现？
A: 查看队列是否堆积；大文件 / 并发多时会排队。可暂停再重排优先级（规划中）。

Q: 重复内容太多影响检索？
A: 可在设置中开启「重复分片折叠」。或手动合并零散笔记。

Q: 未配置嵌入模型还能用吗？
A: 只能关键词检索，不支持语义相关、引用智能排序。

Q: 删除源文件后引用还在？
A: 旧引用会显示为失效（标记），点击可触发清理。

10. 故障排查速览

症状	排查步骤
全部导入失败	检查磁盘权限（macOS 系统设置 > 隐私 > 文件与文件夹）
单文件失败	在日志面板查看解析错误；尝试转存为 UTF-8
向量化卡住	是否已正确配置嵌入模型 URL / Key / 模型名
Chat 不引用本地	检查片段数量是否为 0；是否没有选中「右侧的参考文献」
速度慢	减少并发；拆分超大 PDF；关闭暂不需要的深度搜索

11. 最佳实践清单

• 初次导入：先整理目录再批量同步，避免后期频繁重构
• 优先 Markdown：结构信号最好，模型引用更精准
• 统一标签风格：英文小写 + 连字符，如：deep-learning, contract-law
• 定期清理陈旧版本，避免语义冲突

12. 下一步

完成导入后，可以继续：

• 试用智能检索：输入自然语言问题观察结果
• 在文档中调用续写，验证引用是否准确
• 配置多个模型对比响应质量

—— 以上即为导入与索引流程