WeKnora/docreader
Lukas e7aaf8ae02
fix(docreader): keep the space held by a whitespace-only inline element (#3978)
markdownify renders an emphasis, code or link element whose text is only
whitespace as "", and the whitespace goes with it. HTML and MHTML
uploads therefore lost word boundaries: `further<strong> </strong>
reference` became `furtherreference`, and `<b>First</b><b> </b><b>Last</b>`
became `**First****Last**`. Editors produce that markup whenever a single
space between two words carries different formatting.

Before conversion, unwrap such elements so their whitespace stays as plain
text. Only elements with no child elements are touched, innermost first,
so a linked image keeps its link and nested wrappers come off completely.
2026-10-08 01:31:48 +08:00
..
client fix(milvus): validate connections and preserve gRPC resolver defaults (#3654) 2026-10-08 00:48:45 +08:00
models feat(chat): open cited documents at the cited passage (#3700) 2026-09-25 13:26:16 +08:00
parser fix(docreader): keep the space held by a whitespace-only inline element (#3978) 2026-10-08 01:31:48 +08:00
proto feat(chat): open cited documents at the cited passage (#3700) 2026-09-25 13:26:16 +08:00
scripts feat(docreader): speed up scanned-PDF parsing, stream image results, isolate heavy async queues 2026-06-03 12:29:13 +08:00
splitter feat(parser): add OpenDataLoader, PaddleOCR-VL engines, and parser improvements 2026-06-03 12:29:13 +08:00
testdata chore(docreader): 重新组织模块文件 2025-11-05 12:07:39 +08:00
tests fix(docreader): keep the space held by a whitespace-only inline element (#3978) 2026-10-08 01:31:48 +08:00
utils feat(security): add a whitelist-only outbound mode that refuses before DNS (#3393) 2026-09-23 12:02:06 +08:00
.pylintrc feat: 新增文档模型类,调整配置与解析逻辑,优化日志及导入 2025-11-18 22:37:01 +08:00
Makefile chore(docreader): 重新组织模块文件 2025-11-05 12:07:39 +08:00
README.md fix(compose): let PDF render parallelism follow CPU-aware code default 2026-07-21 16:02:31 +08:00
auth.py fix(docreader/auth): harden gRPC TLS/Token rollout from #1359 2026-05-16 21:45:56 +08:00
config.py feat(parser): add OpenDataLoader, PaddleOCR-VL engines, and parser improvements 2026-06-03 12:29:13 +08:00
container_entrypoint.py fix(citations): 修复原文定位、高亮范围与 DocReader 启动失败 (#3794) 2026-09-27 20:32:26 +08:00
main.py feat(chat): open cited documents at the cited passage (#3700) 2026-09-25 13:26:16 +08:00
pyproject.toml fix: pptx/ppt attachment parsing fails — missing parser engine + markitdown extras (#2621) 2026-08-09 16:23:36 +08:00
source_wire.py feat(chat): open cited documents at the cited passage (#3700) 2026-09-25 13:26:16 +08:00
uv.lock fix: pptx/ppt attachment parsing fails — missing parser engine + markitdown extras (#2621) 2026-08-09 16:23:36 +08:00

README.md

DocReader Service

DocReader 是 WeKnora 项目中负责文档解析和处理的 gRPC 服务。它支持多种文档格式的读取、OCR 识别、多模态处理等功能。

Docker Compose 环境变量配置

在 docker-compose.yml 文件中,docreader 服务配置了以下环境变量:

docreader:
  image: wechatopenai/weknora-docreader:${WEKNORA_VERSION:-latest}
  environment:
    - MINIO_ENDPOINT=minio:9000
    - MINIO_PUBLIC_ENDPOINT=http://localhost:${MINIO_PORT:-9000}
    - MINERU_ENDPOINT=${MINERU_ENDPOINT:-}
    - MAX_FILE_SIZE_MB=${MAX_FILE_SIZE_MB:-}

环境变量说明

1. MINIO_ENDPOINT

  • 说明: MinIO 服务的内部访问地址(容器间通信)
  • 默认值: minio:9000
  • 用途: DocReader 服务使用此地址连接到 MinIO 对象存储服务,用于读取和存储文档处理过程中的文件
  • 配置示例:
    - MINIO_ENDPOINT=minio:9000  # Docker 网络内部地址
    

2. MINIO_PUBLIC_ENDPOINT

  • 说明: MinIO 服务的公开访问地址(外部访问)
  • 默认值: http://localhost:9000
  • 用途: 用于生成可从外部访问的文件 URL,例如在文档解析后返回图片链接时使用
  • 重要提示:
    • 如果需要从其他设备或容器访问,需要将 localhost 替换为实际的 IP 地址
    • 可以在 .env 文件中配置 MINIO_PORT 来自定义端口
  • 配置示例:
    # .env 文件
    MINIO_PORT=9000
    
    或直接在 docker-compose.yml 中修改:
    - MINIO_PUBLIC_ENDPOINT=http://192.168.1.100:9000  # 使用实际 IP
    

3. MINERU_ENDPOINT

  • 说明: MinerU 服务的访问地址(可选)
  • 默认值: 空(不使用 MinerU)
  • 用途: MinerU 是一个高级文档解析服务,支持更复杂的文档结构识别和处理。配置此变量后,DocReader 可以调用 MinerU 进行文档解析
  • 配置示例:
    # .env 文件
    MINERU_ENDPOINT=http://mineru-service:8080
    

4. MAX_FILE_SIZE_MB

  • 说明: 允许上传的最大文件大小(单位:MB)
  • 默认值: 50 MB
  • 用途: 限制 gRPC 服务接收的文件大小,防止过大的文件导致服务崩溃或性能问题
  • 配置示例:
    # .env 文件
    MAX_FILE_SIZE_MB=100  # 允许最大 100MB 的文件
    

其他可配置的环境变量

除了 docker-compose.yml 中已配置的变量外,DocReader 还支持以下环境变量(可根据需要添加):

gRPC 配置

  • DOCREADER_GRPC_MAX_WORKERS: gRPC 服务的最大工作线程数(默认:4)
  • DOCREADER_GRPC_PORT: gRPC 服务监听端口(默认:50051)

解析器资源控制

  • DOCREADER_MARKITDOWN_MAX_WORKERS: MarkItDown 解析的最大并发数(默认:1,设为 0 可关闭限流)
  • DOCREADER_PDF_RENDER_MAX_WORKERS: 扫描 PDF 渲染为图片的最大并发数(默认:1,设为 0 可关闭限流)
  • DOCREADER_PDF_RENDER_DPI: 扫描 PDF 渲染 DPI(默认:200)
  • DOCREADER_PDF_JPEG_QUALITY: 扫描 PDF 输出 JPEG 质量(默认:85,范围会自动限制在 1-95)

OCR / VLM

DocReader 自身不再内置 OCR 与 VLM 后端。扫描 PDF 会被渲染为 JPEG 图片后交由 Go App 侧调用 OCR/VLM 服务处理,相关配置请参考主项目文档。

存储配置

DocReader 支持多种存储后端:

MinIO/S3 存储(推荐)

  • STORAGE_TYPE: 设置为 minio
  • MINIO_ACCESS_KEY_ID: MinIO 访问密钥 ID(默认:minioadmin)
  • MINIO_SECRET_ACCESS_KEY: MinIO 访问密钥(默认:minioadmin)
  • MINIO_BUCKET_NAME: MinIO 存储桶名称(默认:WeKnora)
  • MINIO_PATH_PREFIX: 文件路径前缀
  • MINIO_USE_SSL: 是否使用 SSL(默认:false)

腾讯云 COS 存储

  • STORAGE_TYPE: 设置为 cos
  • COS_SECRET_ID: COS 访问密钥 ID
  • COS_SECRET_KEY: COS 访问密钥
  • COS_REGION: COS 区域
  • COS_BUCKET_NAME: COS 存储桶名称
  • COS_APP_ID: COS 应用 ID
  • COS_PATH_PREFIX: 文件路径前缀
  • COS_ENABLE_OLD_DOMAIN: 是否使用旧域名(默认:true)

阿里云 OSS 存储

  • STORAGE_TYPE: 设置为 oss
  • OSS_ACCESS_KEY_ID: OSS 访问密钥 ID
  • OSS_ACCESS_KEY_SECRET: OSS 访问密钥
  • OSS_ENDPOINT: OSS 端点(如 oss-cn-hangzhou.aliyuncs.com)
  • OSS_BUCKET_NAME: OSS 存储桶名称
  • OSS_REGION: OSS 区域(如 cn-hangzhou)
  • OSS_PATH_PREFIX: 文件路径前缀

代理配置

如果需要通过代理访问外部服务:

  • EXTERNAL_HTTP_PROXY: HTTP 代理地址
  • EXTERNAL_HTTPS_PROXY: HTTPS 代理地址

图像处理配置

扫描 PDF 会被渲染为 JPEG 图片后交给 Go App 侧 OCR 处理。如果在导入多个大 PDF 时出现资源占用过高, 可以优先调低 DOCREADER_PDF_RENDER_MAX_WORKERS 或 DOCREADER_MARKITDOWN_MAX_WORKERS。

配置示例

基础配置(使用 MinIO)

docreader:
  environment:
    - MINIO_ENDPOINT=minio:9000
    - MINIO_PUBLIC_ENDPOINT=http://localhost:9000
    - MAX_FILE_SIZE_MB=50

高级配置(启用 MinerU)

docreader:
  environment:
    - MINIO_ENDPOINT=minio:9000
    - MINIO_PUBLIC_ENDPOINT=http://192.168.1.100:9000
    - MINERU_ENDPOINT=http://mineru:8080
    - MAX_FILE_SIZE_MB=100

使用腾讯云 COS

docreader:
  environment:
    - STORAGE_TYPE=cos
    - COS_SECRET_ID=your_secret_id
    - COS_SECRET_KEY=your_secret_key
    - COS_REGION=ap-guangzhou
    - COS_BUCKET_NAME=your-bucket
    - COS_APP_ID=your_app_id
    - MAX_FILE_SIZE_MB=50

使用阿里云 OSS

docreader:
  environment:
    - STORAGE_TYPE=oss
    - OSS_ACCESS_KEY_ID=your_access_key_id
    - OSS_ACCESS_KEY_SECRET=your_access_key_secret
    - OSS_ENDPOINT=oss-cn-hangzhou.aliyuncs.com
    - OSS_BUCKET_NAME=your-bucket
    - OSS_REGION=cn-hangzhou
    - MAX_FILE_SIZE_MB=50

常见问题

1. DocReader 服务无法启动?

检查容器日志中是否存在依赖缺失或权限相关错误,必要时确认 MINIO_ENDPOINT / 存储相关环境变量是否正确配置。

2. 图片无法显示?

检查 MINIO_PUBLIC_ENDPOINT 配置:

  • 确保使用的是可从浏览器访问的地址
  • 如果从其他设备访问,不要使用 localhost,应使用实际 IP 地址

3. 文件上传失败?

检查 MAX_FILE_SIZE_MB 配置,确保限制足够大。同时需要确保前端和后端服务的文件大小限制保持一致。

服务健康检查

DocReader 服务配置了健康检查:

healthcheck:
  test: ["CMD", "grpc_health_probe", "-addr=localhost:50051"]
  interval: 30s
  timeout: 10s
  retries: 3
  start_period: 60s

可以通过以下命令检查服务状态:

docker ps | grep docreader
docker logs WeKnora-docreader

更多信息

  • 服务端口:50051(gRPC)
  • 容器名称:WeKnora-docreader
  • 网络:WeKnora-network
  • 重启策略:unless-stopped