# 工具：知识库伴侣（基于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**: 1
- **Forks**: 1
- **Created**: 2025-11-21
- **Last Updated**: 2025-12-16

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 知识库伴侣

基于 MarkItDown 和 AI 模型的文档处理 API 服务，支持文档转换、智能切块、向量化和语义重排序。

## 功能特性

- 📄 **文档转换**：PDF、Word、Excel、PowerPoint、图片、HTML 等格式转 Markdown
- 🔍 **图片识别**：OCR 文字识别 / Vision API 智能理解 / 可选忽略
- ✂️ **智能切块**：基于 BERT 的语义切分，支持自定义切块大小
- 🧠 **文本向量化**：使用 multilingual-e5-small 模型生成 384 维语义向量
- 🎯 **语义重排序**：使用 GTE-reranker 对文档进行相关性排序
- 🐳 **Docker 部署**：预装模型，开箱即用

## 快速开始

### 预编译镜像部署（推荐）

**1. 拉取镜像：**
```bash
docker pull crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab/markitdown-api-lite:[版本号]
```

> **提示**：
> - 上述 Docker 镜像为 x64 架构。若在 arm64 架构上运行，需要获取代码，使用 arm64 架构另行编译。
> - [版本号]请参见本项目的[“发行版”](https://gitee.com/low-code-dev-lab/markitdown-api/releases)。

**2. 启动服务：**

```bash
docker run -d --name markitdown-api-lite --restart unless-stopped --network=host -p 8300:8300 -v ./data:/app/data -e VL_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1" -e VL_API_KEY="sk-xxx" -e VL_MODEL="qwen-vl-plus" -e DATA_DIR=/app/data crpi-4auaoyyj6r36p6lb.cn-hangzhou.personal.cr.aliyuncs.com/huozige_lab/markitdown-api-lite:[版本号]
```

**注意**：
- 如需在局域网内使用，需要增加--network=host，以便于使用宿主机的DNS地址，用来访问到宿主机或其他服务器上的文件。如果您的宿主机是Windows Docker Desktop，您需要前往Docker Desktop的【设置】界面，在【Resource】下找到【Network】选项卡，勾选【Enable host networking】来启用对该功能的支持。启动成功后，Docker会提示“……忽略端口设置……”的文字消息，这是正常的，不影响使用。
- 如需在广域网使用，需确保指定的端口已经允许公开访问。

### Docker Compose 部署

**1. 配置 .env 文件**（可选，用于VL模式的图片识别）：
```bash
VL_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
VL_API_KEY=sk-xxx
VL_MODEL=qwen-vl-plus
```

**2. 启动服务**：
```bash
docker-compose up -d --build
```

**3. 确保服务成功启动**：

服务采用**延迟加载**机制，启动后模型不会立即加载，而是在首次调用相关接口时按需加载。这样可以实现快速启动。

**启动方式选择**：

- **快速启动**（推荐）：服务启动后立即可用，模型在首次使用时自动加载
  ```bash
  # 服务启动约 5-10 秒即可访问
  curl http://localhost:8300/health
  ```

- **预热启动**：启动后主动预加载所有模型，确保首次调用时无延迟
  ```bash
  # 等待服务启动
  sleep 5

  # 预热所有模型（约需 30-60 秒）
  curl http://localhost:8300/warmup
  ```

### 访问地址

- API 服务：http://localhost:8300
- API 文档：http://localhost:8300/docs

## API 接口

### POST /convert2 - 文档转 Markdown

**请求示例**：
```bash
curl -X POST "http://localhost:8300/convert2" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://example.com/document.pdf",
    "image_process_model": "ocr",
    "max_chunk_size": 500
  }'
```

**参数**：
- `url`（必需）：文档 URL
- `name`（可选）：文件名，用于类型推断
- `image_process_model`（可选）：`ocr`（默认）/ `vl` / `none`
- `max_chunk_size`（可选）：切块大小，0 表示不切块

**响应**：
```json
{
  "success": true,
  "markdown": "# 文档内容...",
  "chunks": ["块1...", "块2..."],
  "logs": "处理日志..."
}
```

### POST /chunk - 文本切块

**请求示例**：
```bash
curl -X POST "http://localhost:8300/chunk" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "长文本内容...",
    "max_chunk_size": 500
  }'
```

**参数**：
- `content`（必需）：待切块的文本
- `max_chunk_size`（可选）：切块大小

**响应**：
```json
{
  "success": true,
  "chunks": ["块1...", "块2..."],
  "logs": "切块日志..."
}
```

### POST /embedding - 文本嵌入向量

**请求示例**：
```bash
curl -X POST "http://localhost:8300/embedding" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "这是一段文本",
    "type": "passage"
  }'
```

**参数**：
- `text`（必需）：待向量化的文本
- `type`（可选）：`passage`（默认，用于文档）/ `query`（用于查询）

**响应**：
```json
{
  "embedding": [0.123, -0.456, ...],
  "dimension": 384,
  "duration": 0.032
}
```

**返回字段说明**：
- `embedding`: L2 归一化后的嵌入向量（384 维浮点数组）
- `dimension`: 向量维度（固定 384）
- `duration`: 处理耗时（秒）

**特点**：
- 使用 multilingual-e5-small 模型
- 固定 384 维向量输出
- 支持中英文及 100+ 种语言
- 自动 L2 归一化

### POST /rerank - 文档重排序

**请求示例**：
```bash
curl -X POST "http://localhost:8300/rerank" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "员工请假需要提前多久申请？",
    "inputs": [
      "年假申请需提前3天...",
      "病假申请流程...",
      "请假扣款规定..."
    ],
    "topN": 2
  }'
```

**参数**：
- `query`（必需）：查询文本
- `inputs`（必需）：候选文档列表
- `topN`（必需）：返回的文档数量

**响应**：
```json
{
  "results": [
    {
      "index": 0,
      "relevance_score": 0.8542,
      "document": {
        "text": "年假申请需提前3天..."
      }
    },
    {
      "index": 1,
      "relevance_score": 0.7231,
      "document": {
        "text": "病假申请流程..."
      }
    }
  ],
  "duration": 0.125
}
```

**返回字段说明**：
- `index`: 文档在原始输入列表中的索引
- `relevance_score`: 相关性分数（越高越相关）
- `document.text`: 文档文本内容
- `duration`: 处理耗时（秒）

**特点**：
- 使用 Alibaba GTE-multilingual-reranker-base 模型
- CPU 优化，推理速度快（~50ms/10 文档）
- 支持 75 种语言
- 显著提升检索准确率（+20-30%）

**典型应用场景**：
```
用户查询 → 向量检索（召回 Top 50-100）→ Rerank（精选 Top 5-10）→ 返回用户
```

### GET /health - 健康检查

```bash
curl http://localhost:8300/health
```

**响应**：
```json
{
  "status": "healthy"
}
```

### GET /warmup - 模型预热

预加载所有 AI 模型（chunk、embedding、rerank），返回加载日志。

**请求示例**：
```bash
curl http://localhost:8300/warmup
```

**响应**（纯文本）：
```
============================================================
[1/3] 开始加载 Chunk 模型...
============================================================
Initializing BERT Chunker Chinese 2 model, device: cpu
Loading tokenizer...
[OK] Tokenizer loaded
Loading model...
[OK] Model loaded
[OK] Chunk 模型加载成功

============================================================
[2/3] 开始加载 Embedding 模型...
============================================================
正在加载 intfloat/multilingual-e5-small 模型...
模型加载完成
[OK] Embedding 模型加载成功

============================================================
[3/3] 开始加载 Rerank 模型...
============================================================
正在加载 Alibaba-NLP/gte-multilingual-reranker-base 模型...
模型加载完成
[OK] Rerank 模型加载成功

============================================================
所有模型加载完成！
============================================================
```

**使用场景**：
- **容器启动后预热**：确保首次调用无延迟
- **Kubernetes 就绪探针**：作为 readinessProbe 确保 Pod 完全就绪
- **性能测试前准备**：避免首次调用耗时影响测试结果
- **监控模型加载状态**：通过日志排查模型加载问题

**注意**：
- 首次调用约需 30-60 秒（取决于硬件性能）
- 重复调用会立即返回（模型已加载）
- 不影响服务正常运行，可随时调用

## 支持格式

| 格式 | 扩展名 | 图片识别 |
|------|--------|----------|
| PDF | `.pdf` | ✅ OCR / VL / None |
| Word | `.docx`, `.doc` | ✅ OCR / VL / None |
| PowerPoint | `.pptx`, `.ppt` | ✅ OCR / VL / None |
| Excel | `.xlsx`, `.xls` | ✅ OCR / VL / None |
| 图片 | `.jpg`, `.png`, `.gif` | ✅ OCR / VL / None |
| HTML | `.html` | ✅ OCR / VL / None |
| 文本 | `.txt`, `.json`, `.xml` | - |

## 图片识别模式

### OCR 模式（默认）
- 使用 Tesseract，开箱即用
- 支持中英文混合识别
- 输出格式：` ```ocr ... ` `

### VL 模式，Vision API
- 使用 OpenAI 兼容接口（如阿里云百炼）
- 智能理解图片内容，自动提取上下文
- 输出格式：` ```vl ... ` `
- 获取 API Key：[阿里云百炼控制台](https://bailian.console.aliyun.com/)

### None 模式
- 跳过所有图片，仅提取文本
- 大幅提升处理速度

## AI 模型说明

| 模型 | 用途 | 大小 | 维度/特性 |
|------|------|------|-----------|
| **BERT Chunker Chinese 2** | 文本切块 | ~95 MB | 语义边界识别 |
| **multilingual-e5-small** | 文本向量化 | ~493 MB | 384 维，100+ 语言 |
| **GTE-reranker-base** | 文档重排序 | ~612 MB | 75 语言，CPU 优化 |

所有模型预装在 Docker 镜像中，无需额外下载。

## 环境变量配置

| 变量 | 默认值 | 说明 |
|------|--------|------|
| `VL_BASE_URL` | - | Vision API 地址 |
| `VL_API_KEY` | - | Vision API 密钥 |
| `VL_MODEL` | - | Vision 模型名称 |
| `DOWNLOAD_TIMEOUT` | 300 秒 | 文件下载超时 |
| `VL_API_TIMEOUT` | 120 秒 | Vision API 超时 |
| `DATA_DIR` | `/app/data` | 数据存储目录 |

## 开发指南

查看 **[DEV_GUIDE.md](./DEV_GUIDE.md)** 了解开发模式、热重载、调试等详细说明。

**快速启动开发模式**：
```bash
# Windows
dev.bat init && dev.bat dev

# Linux/Mac
make init-cache && make dev
```

## 项目结构

```
app/
├── main.py           # FastAPI 应用
├── routes.py         # API 路由
├── core.py           # 文档转换
├── chunk.py          # 文本切块
├── embedding.py      # 向量化
├── rerank.py         # 重排序
├── schemas.py        # 数据模型
└── processor/        # 文档处理器
```

## 技术栈

- **Web 框架**：FastAPI + Uvicorn
- **文档转换**：MarkItDown + PyMuPDF
- **图片识别**：Tesseract OCR / OpenAI Vision API
- **AI 模型**：
  - BERT Chunker Chinese 2（语义切块）
  - multilingual-e5-small（文本向量化）
  - Alibaba GTE-reranker-base（文档重排序）
- **运行环境**：Python 3.12 + uv

## License

MIT