# 工具：知识库伴侣 懒猫微服 **Repository Path**: Hashcow/markitdown-api ## Basic Information - **Project Name**: 工具：知识库伴侣 懒猫微服 - **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**: 0 - **Forks**: 5 - **Created**: 2026-06-05 - **Last Updated**: 2026-06-05 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 知识库伴侣 基于 MarkItDown 和 AI 模型的文档处理 API 服务，支持文档转换、智能切块、向量化和语义重排序。 ## 功能特性 - 📄 **文档转换**：PDF、Word、Excel、PowerPoint、图片等格式转 Markdown - 🔍 **图片识别**：OCR 文字识别 / Vision API 智能理解 / VL-Page 页面识别 / 可选忽略 - ✂️ **智能切块**：基于 BERT 的语义切分，支持自定义切块大小 - 🧠 **文本向量化**：使用 multilingual-e5-small 模型生成 384 维语义向量 - 🎯 **语义重排序**：使用 GTE-reranker 对文档进行相关性排序 - 📦 **懒猫微服应用**：预装模型，开箱即用 ## 快速开始 安装应用后，API 地址格式为： ```text https://markitdown-api.{设备名}.heiyu.space ``` 其中 `{设备名}` 是你的懒猫微服设备名。例如设备名为 `lzcos` 时，访问地址为： ```text https://markitdown-api.lzcos.heiyu.space ``` 建议先设置一个环境变量，后续示例都使用这个变量： ```bash export MARKITDOWN_API_BASE="https://markitdown-api.{设备名}.heiyu.space" ``` 常用入口： - API 服务：`$MARKITDOWN_API_BASE` - API 文档：`$MARKITDOWN_API_BASE/docs` - 健康检查：`$MARKITDOWN_API_BASE/health` 验证服务是否可访问： ```bash curl "$MARKITDOWN_API_BASE/health" ``` 也可以使用项目内测试脚本按 README 覆盖主要接口： ```bash ./script/test {设备名} ``` 如果要测试完整 URL，也可以直接传入 API 地址： ```bash ./script/test "https://markitdown-api.{设备名}.heiyu.space" ``` 服务采用**延迟加载**机制，启动后模型不会立即加载，而是在首次调用相关接口时按需加载。这样可以实现快速启动。 **启动方式选择**： - **快速启动**（推荐）：服务启动后立即可用，模型在首次使用时自动加载 ```bash # 服务启动约 30 秒至 1 分钟后即可访问 curl "$MARKITDOWN_API_BASE/health" ``` - **预热启动**：启动后主动预加载所有模型，确保首次调用时无延迟 ```bash # 等待服务启动 sleep 60 # 预热所有模型（约需 30-60 秒） curl "$MARKITDOWN_API_BASE/warmup" ``` ## API 接口 ### POST /convert-url - 从 URL 转换文档 **请求示例**： ```bash curl -X POST "$MARKITDOWN_API_BASE/convert-url" \ -H "Content-Type: application/json" \ -d '{ "url": "http://example.com/document.pdf", "name": "document.pdf", "image_process_model": "ocr", "max_chunk_size": 500 }' ``` **参数**： - `url`（必需）：文档 URL 地址 - `name`（可选）：文件名，用于类型推断 - `image_process_model`（可选）：`ocr`（默认）/ `vl` / `none` / `vl-page`（仅支持PDF） - `max_chunk_size`（可选）：切块大小，0 表示不切块 **响应**： ```json { "success": true, "url": "http://example.com/document.pdf", "name": "document.pdf", "markdown": "# 文档内容...", "chunks": ["块1...", "块2..."], "logs": "处理日志..." } ``` ### POST /convert-file - 从文件内容转换文档 **请求示例**： ```bash curl -X POST "$MARKITDOWN_API_BASE/convert-file" \ -H "Content-Type: application/json" \ -d '{ "data": "data:application/pdf;base64,JVBERi0xLjQKJeLjz9MK...", "image_process_model": "ocr", "max_chunk_size": 500 }' ``` **参数**： - `data`（必需）：Data URI 格式的文件内容（包含 MIME 类型和 Base64 编码数据） - `image_process_model`（可选）：`ocr`（默认）/ `vl` / `none` / `vl-page`（仅支持PDF） - `max_chunk_size`（可选）：切块大小，0 表示不切块 **响应**： ```json { "success": true, "url": "", "name": "", "markdown": "# 文档内容...", "chunks": ["块1...", "块2..."], "logs": "处理日志..." } ``` **Data URI 格式说明**： - 格式：`data:[][;base64],` - 示例：`data:application/pdf;base64,JVBERi0xLjQK...` - 示例：`data:text/plain;base64,SGVsbG8gV29ybGQh` - 优势：无需文件服务器，直接传输文件内容 **注意**： - 旧版本中的 `/convert2` 接口已弃用，将在后续版本中移除，请使用 `/convert-url` 替代 ### POST /chunk - 文本切块 **请求示例**： ```bash curl -X POST "$MARKITDOWN_API_BASE/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 "$MARKITDOWN_API_BASE/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 "$MARKITDOWN_API_BASE/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 /version - API版本号 返回当前API服务的版本号。 **请求示例**： ```bash curl "$MARKITDOWN_API_BASE/version" ``` **响应**： ```json { "version": "2.5.0" } ``` ### GET /health - 健康检查 ```bash curl "$MARKITDOWN_API_BASE/health" ``` **响应**： ```json { "status": "healthy" } ``` ### GET /warmup - 模型预热 预加载所有 AI 模型（chunk、embedding、rerank），返回加载日志。 **请求示例**： ```bash curl "$MARKITDOWN_API_BASE/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 模型加载成功 ============================================================ 所有模型加载完成！ ============================================================ ``` **使用场景**： - **应用启动后预热**：确保首次调用无延迟 - **性能测试前准备**：避免首次调用耗时影响测试结果 - **监控模型加载状态**：通过日志排查模型加载问题 **注意**： - 首次调用约需 30-60 秒（取决于硬件性能） - 重复调用会立即返回（模型已加载） - 不影响服务正常运行，可随时调用 ## 支持格式 | 格式 | 扩展名 | 图片识别 | |------------|-------------------------|-----------------------------| | PDF | `.pdf` | ✅ OCR / VL / VL-Page / None | | Word | `.docx` | ✅ OCR / VL / None | | PowerPoint | `.pptx` | ✅ OCR / VL / None | | Excel | `.xlsx` | ✅ OCR / VL / None | | 图片 | `.jpg`, `.png`, `.gif` | ✅ OCR / VL / None | | 文本 | `.txt`, `.json`, `.xml` | - | ## 图片识别模式 ### OCR 模式（默认） - 使用 Tesseract，开箱即用 - 支持中英文混合识别 - 输出格式：` ```ocr ... ` ` ### VL 模式，Vision API - 使用 OpenAI 兼容接口（如阿里云百炼） - 智能理解图片内容，自动提取上下文 - 输出格式：` ```vl ... ` ` - 获取 API Key：[阿里云百炼控制台](https://bailian.console.aliyun.com/) ### VL-Page 模式（仅支持 PDF） - 将 PDF 文档按页面截屏，分别调用 VL API 识别 - 输出格式：` ```vl-page ... ` `（每页一个独立代码块） - 不包含 PDF 中的原始文本，仅包含 VL 识别的结果 - 自动调整页面缩放比例，确保图片质量（可通过 `VL_PAGE_TARGET_WIDTH`、`VL_PAGE_MIN_ZOOM`、`VL_PAGE_MAX_ZOOM` 环境变量调整） - 需要配置 VL_BASE_URL 和 VL_API_KEY 环境变量 - 适用于需要完全依赖 VL 理解 PDF 内容的场景 ### None 模式 - 跳过所有图片，仅提取文本 - 大幅提升处理速度 ## AI 模型说明 | 模型 | 用途 | 参数规模 | 维度/特性 | |----------------------------|-------|------|---------------| | **BERT Chunker Chinese 2** | 文本切块 | 0.1B | 语义边界识别 | | **multilingual-e5-small** | 文本向量化 | 0.3B | 384 维，100+ 语言 | | **GTE-reranker-base** | 文档重排序 | 0.6B | 75 语言，CPU 优化 | 所有模型预装在应用包中，无需额外下载。 ## 环境变量配置 | 变量 | 默认值 | 说明 | |--------------------|-------------|---------------| | `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` | 数据存储目录 | **VL-Page 模式高级配置**（可选）： - `VL_PAGE_TARGET_WIDTH`：页面截图目标宽度（默认 2400 像素） - `VL_PAGE_MIN_ZOOM`：最小缩放比例（默认 1.2） - `VL_PAGE_MAX_ZOOM`：最大缩放比例（默认 5.0） ## License MIT