支持的文件格式
| 格式 | 扩展名 | 解析器 | fallback |
|---|---|---|---|
.pdf | PyPDFLoader | UnstructuredFileLoader | |
| Word | .doc, .docx | UnstructuredWordDocumentLoader | UnstructuredFileLoader |
| Excel | .xls, .xlsx | UnstructuredExcelLoader（elements 模式） | UnstructuredFileLoader |
| PowerPoint | .ppt, .pptx | UnstructuredPowerPointLoader | UnstructuredFileLoader |
| Markdown | .md, .markdown | UnstructuredMarkdownLoader | 纯文本读取 |
| CSV | .csv | CSVLoader | 纯文本读取 |
| 纯文本 | .txt | 直接读取 | — |
处理管线
详细步骤
- 上传文件：保存到本地
data/documents/{user_id}/{kb_id}/{uuid}_{filename}，生成唯一文件名防冲突 - 创建记录：通过 Next.js API 创建文档元数据（fileName、filePath、fileType、fileSize）
- 触发处理：调用
POST /{kb_id}/documents/{doc_id}/process，加入BackgroundTasks异步执行 - 加载文档：根据文件扩展名选择对应的 LangChain Loader
- 智能分块：优先使用 SmartChunker，fallback 到 RecursiveCharacterTextSplitter
- 生成向量：使用用户配置的 Embedding 模型（
create_embeddings(user_id)） - 存储到 pgvector：每个 chunk 附带元数据 —
user_id、knowledge_base_id、document_id、chunk_index、source、page、created_at - 使 BM25 失效：通知 BM25Store 该知识库的索引需要重建（下次检索时自动构建）
- 更新状态：通过 Next.js API 更新文档状态为
completed，记录chunkCount
文档状态
| 状态 | 说明 |
|---|---|
pending | 已上传，未开始处理 |
processing | 正在处理（异步后台） |
completed | 处理完成 |
failed | 处理失败（记录 errorMessage） |
SmartChunker 智能分块
SmartChunker 借鉴 RAGFlow 的 DeepDoc 设计，根据文档类型选择最优分块策略，实现语义感知分块而非固定大小切分。分块策略
| 文档类型 | 策略 | 说明 |
|---|---|---|
| Markdown | MarkdownHeaderTextSplitter | 按标题层级（H1~H6）分块，保留层级结构元数据 |
| 代码文件 | Language-aware splitter | 按函数/类语法结构分块，支持 15+ 语言 |
| 表格 | 表格完整性保持 | 表格作为独立块，避免被切断 |
| PDF / 其他 | RecursiveCharacterTextSplitter | 递归字符分块 + 段落感知 |
支持的代码语言
Python、JavaScript/TypeScript、Java、Go、C/C++、C#、Ruby、PHP、Rust、Scala、Swift、Kotlin 等。处理配置
处理配置可以在知识库级别自定义，通过GET /api/knowledge-base/{id}/config 获取：
| 参数 | 默认值 | 说明 |
|---|---|---|
chunkSize | 1000 | 分块最大字符数 |
chunkOverlap | 200 | 分块重叠字符数 |
separators | ["\n\n", "\n", "。", ".", "!", "?", ";", "；", " ", ""] | 递归分隔符 |
indexMethod | high_quality | 索引方法 |
replaceConsecutiveSpaces | true | 替换连续空格 |
deleteUrlsAndEmails | false | 删除 URL 和邮箱 |
useSmartChunking | true | 是否启用 SmartChunker（关闭则使用传统分块） |
分块预览
提供客户端预览接口，可在配置分块参数时实时查看效果：index、content 和 length。