# 工具：知识库伴侣（基于Markitdown+PyMuPDF+Tesseract+多个PyTorch模型）

**Repository Path**: low-code-dev-lab/markitdown-api

## Basic Information

- **Project Name**: 工具：知识库伴侣（基于Markitdown+PyMuPDF+Tesseract+多个PyTorch模型）
- **Description**: 提供知识库建设所需的基本功能，全CPU实现。

功能特性：
- 文件转文本：PDF、Word、Excel、PowerPoint、图片、HTML 等格式（图片识别模式： OCR、VL）
- 文本切块：BERT Chunker Chinese 2
- 文本嵌入：multilingual-e5-small
- 文本排序：gte-multilingual-reranker-base
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 11
- **Forks**: 6
- **Created**: 2025-11-21
- **Last Updated**: 2026-07-10

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 一休（ikkyu）：知识库后台服务

一休（ikkyu）是面向知识库构建场景的后台 API 服务，提供知识领域、资源文件管理、向量 + BM25 混合查询的标准化实现。开发者只需要自行完成鉴权、数据权限等非功能需求，即可完成企业级知识库的开发与交付。

项目底层基于 MarkItDown 和本地 AI 模型，提供文档转 Markdown、图片识别、智能切块、文本向量化和语义重排序等能力，可单独调用，也可组合为完整的知识资源入库与检索链路。

## 核心设计

一休把知识库拆成业务概念和存储概念两层，开发时优先面向业务概念建模：

- 知识领域（domain）：业务上的查询边界和配置边界，通常对应一个部门、制度域、产品线、项目空间或租户内的知识主题。
- 向量集合（vector collection）：每个知识领域对应一个底层向量集合，用于存放该领域内 chunk 的 embedding 和检索索引。向量集合是内部实现细节，调用方通常只需要关心知识领域。
- 资源（resource）：属于某个知识领域的源文档或知识文件。新增、编辑重建或手动重建资源时，会自动完成转换、切块、检索扩增、向量化和入库。
- 切片（chunk）：实际参与向量召回、BM25 召回和语义重排序的最小检索单元。
- 持久化文件：Docker 运行统一使用 named volume 挂载 `/var/ikkyu-data`，其中 `originals/` 保存原始资源文件或来源描述，`markdown/` 保存转换后的 Markdown；`/api/fs/*` 只读取和搜索 Markdown 文件。

默认查询路径是在一个知识领域内完成检索：调用方先确定 `domain_name`，再提交查询文本。一休会在该领域对应的向量集合内执行向量召回与 BM25 召回，并对候选 chunk 做语义重排序。

```text
domain_name + text -> 向量召回 + BM25 召回 -> 语义重排序 -> 命中资源和 chunk
```

跨知识领域查询不是默认路径，适合全局搜索、不确定知识归属、后台诊断或少数聚合型业务场景。这样的设计与常见向量数据库中的 collection、namespace 或 index 思路一致：业务层使用 `domain` 表达知识边界，存储层用独立集合承载该领域的索引数据，避免让业务代码直接耦合底层向量库命名。

## 特色功能：检索扩增

一休把入库阶段基于 chunk 生成问题或问答对的能力称为检索扩增（retrieval augmentation）。在信息检索领域，这类做法更接近文档扩展（document expansion）、查询预测（query prediction）和合成查询生成（synthetic query generation）：不是改变原文，也不是让生成内容成为新知识，而是把“用户可能会怎么问”补充到索引文本中，缓解查询表达和文档原文之间的词汇不匹配。

`augmentation` 支持三种策略：

- `none`：不做检索扩增，直接用原始 chunk 建索引。
- `t2q`：Text to Questions，基于 chunk 生成检索问题。推荐作为通用知识库的首选扩增策略。
- `t2qa`：Text to QA Pairs，基于 chunk 生成受原文约束的问答对。适合 FAQ、制度条款、操作手册等边界清楚的内容。

扩增文本只用于提升向量召回和 BM25 召回。查询结果、重排序候选和最终证据仍以原始 chunk 为准，避免把 LLM 生成内容误当成事实来源。详细设计见[检索扩增与召回策略](./doc/retrieval-augmentation.md)。

## 项目简介

- 知识领域管理：按业务域维护知识库配置，支持向量召回与 BM25 召回权重配置。
- 资源文件管理：支持资源新增、编辑、删除、重建，自动完成转换、切块、检索扩增、向量化和入库。
- 混合知识查询：默认在单个知识领域内检索，结合向量召回、BM25 召回和语义重排序返回结果；少数场景可扩展为跨领域联合查询。
- 文档转换：支持 PDF、Word、Excel、PowerPoint、图片、HTML、文本等格式转 Markdown。
- 图片识别：支持 OCR、OpenAI 兼容 Vision API、VL-Page 页面识别，也可跳过图片。
- 智能切块：基于 BERT Chunker Chinese 2 进行语义切分，支持自定义切块大小。
- 内部检索索引：使用 multilingual-e5-small 与 Faiss 为知识资源构建语义索引，数据持久化到 `/var/ikkyu-data`。
- Markdown 文件接口：提供 `ls`、`cat`、`sed`、`grep`、`find`、`stat`、`tree`、`head`、`tail`、`wc` 等只读接口，方便 agent 直接定位和引用 Markdown 资源。
- 语义重排序：使用 Alibaba GTE multilingual reranker 对候选文档排序。
- 部署方式：支持 Docker 运行、Mac / Windows 本地无 Docker 启动、离线模型和本地开发热重载。

## 文档索引

- [安装部署](./doc/install.md)：Docker 镜像、服务启动、模型预热和环境变量配置。
- [API 接口](./doc/api.md)：转换、切块、知识资源、重排序、健康检查等接口说明。
- [检索扩增与召回策略](./doc/retrieval-augmentation.md)：文档扩展、查询预测、`t2q` / `t2qa` 和混合召回设计。
- [开发调试](./doc/dev.md)：本地无 Docker 启动、目录结构、测试脚本和常见问题。