WeKnora/docreader
VinhChu ae185dd1a9 fix(docreader): stop a non-ASCII base64 payload from failing the whole parse
encode_image documents errors="ignore" as "return empty bytes on decoding
errors", but it only catches binascii.Error. base64.b64decode raises that for
bad padding or a bad alphabet; for a str that is not pure ASCII it fails in
_bytes_from_decode_data first and raises a plain ValueError, which escapes.

The one caller that passes errors="ignore" is the markdown base64-image
extractor, whose payload group is `([^\)]+)` — everything up to the closing
paren, not the base64 alphabet. A CJK image title therefore lands inside the
payload:

    ![x](data:image/png;base64,iVBORw0KGgo= "图片")
                                            ^^^^ captured as base64

MarkdownImageBase64.parse_into_text does not catch, PipelineParser does not
catch, and BaseParser.parse does not catch, so the ValueError reaches the gRPC
handler and the whole document comes back as
ReadResponse(error="string argument should contain only ASCII characters").
One image title fails the entire upload, and the message names nothing the
user can act on.

The same title written in ASCII decodes fine, because b64decode with
validate=False discards the quotes and spaces. The failure only shows up for
titles in the languages this project is mostly used in.

Catching ValueError covers both cases — binascii.Error subclasses it — so the
undecodable image is skipped and logged, which is what the extractor's own
`if not image_byte` branch already expects to happen.

Not addressed here: the pattern swallowing the title is a separate bug, and
narrowing that group changes which markdown the extractor matches. Filed as
its own change rather than folded in.
2026-09-22 19:37:21 +08:00
..
client fix(ci): make DocReader client tests runnable in PR checks 2026-07-30 14:13:15 +08:00
models feat: introduce WeKnora Lite edition with lightweight configuration and deployment 2026-03-02 21:21:49 +08:00
parser fix: align client sessions and integration request handling (#3305) 2026-09-16 16:20:57 +08:00
proto feat(docreader): speed up scanned-PDF parsing, stream image results, isolate heavy async queues 2026-06-03 12:29:13 +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): stop a non-ASCII base64 payload from failing the whole parse 2026-09-22 19:37:21 +08:00
utils fix(docreader): stop a non-ASCII base64 payload from failing the whole parse 2026-09-22 19:37:21 +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
main.py feat(docreader): speed up scanned-PDF parsing, stream image results, isolate heavy async queues 2026-06-03 12:29:13 +08:00
pyproject.toml fix: pptx/ppt attachment parsing fails — missing parser engine + markitdown extras (#2621) 2026-08-09 16:23:36 +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