Docling Actor 版本演进解析从 Docling CLI 到 docling-serve API 的无服务器文档处理【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文以 Docling 仓库中的.actor/CHANGELOG.md为主体完整还原 Docling Actor 从 1.0.0 到 1.1.0 的版本演进脉络如何从直接调用 Docling CLI重构为调用官方 docling-serve 容器内的 REST API、Docker 镜像如何从约 6GB 瘦身到约 4GB、启动健康检查与错误处理机制如何逐步加固并结合.actor/目录下的 Dockerfile、actor.sh 与 JSON Schema 给出可对照源码的实证细节。读完本文你将能理解 Apify 平台上运行 Docling 的完整架构、输入输出契约以及本地复现开发的具体路径。一、背景Docling Actor 是什么Docling Actor 是 Docling 项目在 Apify 平台上的无服务器serverless封装允许用户不提供本地安装仅凭一份 JSON 配置和文档 URL即可在云端完成复杂文档PDF、DOCX、图片等到结构化格式Markdown、JSON、HTML、Text、DocTags的转换并可选启用 OCR 识别扫描件。仓库中.actor/目录就是该 Actor 的完整实现主文档见 Docling Actor 说明仓库文档侧的集成入口在 Apify 集成页。Actor 通过 Apify 的 Actor 规范 v1 定义其元数据文件 actor.json 声明了构建与运行入口{ actorSpecification: 1, name: docling, version: 1.0, environmentVariables: {}, dockerFile: ./Dockerfile, inputSchema: ./input_schema.json, scripts: { run: ./actor.sh } }CHANGELOG 声明其格式遵循 Keep a Changelog 惯例并遵守语义化版本Semantic Versioning。当前仓库记录的版本轨迹共有两个正式版本[1.0.0] - 2025-02-07与[1.1.0] - 2025-03-09分别对应初始发布和架构级重构两个阶段。二、版本 1.0.02025-02-07初始发布CHANGELOG 中 1.0.0 条目 记录了 Actor 的首个可用形态核心能力包括多格式输入支持 PDF、DOCX、图片等多种文档格式OCR 能力可处理扫描版文档多格式输出支持md、json、html、text、doctags五种导出格式完善的错误处理与日志处理过程中的详细日志与异常捕获带状态字段的 Dataset 记录每次处理会向 Apify Dataset 写入一条包含处理状态success/error与结果 URL 的记录内存监控与资源优化安全特性容器内以非 root 用户运行。1.0.0 的技术栈与错误码约定该版本的技术细节Technical Details明确记录了Actor 规范版本v1依赖Docling v2.17.0与Python 3.11Node.js 20.x用于运行 Apify CLI一套完整的错误码约定错误码含义10无效输入Invalid input11URL 无法访问URL inaccessible12Docling 处理失败Docling processing failed13输出文件缺失Output file missing14存储操作失败Storage operation failed15OCR 处理失败OCR processing failed这组错误码体现了 1.0.0 阶段以 Docling CLI 为处理核心的设计——每一类失败输入、URL、处理、落盘、OCR都有独立退出码便于 Apify 运行时区分失败原因。值得注意的是当前仓库中的 actor.sh 已将其简化重定义为ERR_API_UNAVAILABLE15与ERR_INVALID_INPUT16两个只读常量说明脚本在后续迭代中沿用了退出码分层表达失败场景的思想但具体取值随架构切换发生了调整。三、版本 1.1.02025-03-09从 CLI 到 docling-serve API 的架构重构1.1.0 条目 是 CHANGELOG 中篇幅最大的部分记录的是一次彻底的架构切换可归纳为五个方面。3.1 处理核心切换弃用完整 Docling CLI改用 docling-serve API1.1.0 的第一条 Changed 记录即Switched from full Docling CLI to docling-serve API。具体落地包括基础镜像更换改用官方quay.io/ds4sd/docling-serve-cpu:latest镜像Actor 不再自行安装 Docling 及其全部 Python 依赖Technical Details 中明确Eliminated Python dependencies端点标准化请求端点从自定义的/convert改为 docling-serve 的标准端点/v1alpha/convert/source。这一点可直接在 actor.sh 中得到印证DOCLING_API_ENDPOINThttp://localhost:5001/v1alpha/convert/source请求载荷结构化JSON payload 结构被修订为 docling-serve 的 API 格式即http_sourcesoptions双字段结构。actor.sh 中用jq在原始输入基础上强制注入return_as_file: true使 API 直接返回打包的 zip 文件REQUEST_JSON$(echo $INPUT | jq .options {return_as_file: true})随后以curl直接 POST 二进制请求体到上述端点actor.sh#L306curl -s -H content-type: application/json -X POST \ --data-binary $API_DIR/request.json -o $API_DIR/output.zip $DOCLING_API_ENDPOINT输出解析增加了按输出格式to_formats正确解析响应字段与 content-type 的逻辑确保 md/json/html/text/doctags 各自的返回形式被正确处理。3.2 Docker 镜像瘦身与多阶段构建CHANGELOG 记录镜像体积从约 6GB 降至约 4GB手段是为处理依赖实施多阶段 Docker 构建multi-stage build。对照当前 Dockerfile 可以看到这一设计的完整落地第一阶段builder基于node:20-slim仅安装apify-cli并将node_modules收敛到/build/lib/node_modules同时生成/build/bin/actor包装脚本最后执行npm cache clean --force清理缓存Dockerfile#L2-L20第二阶段最终镜像基于quay.io/ds4sd/docling-serve-cpu:latest从 builder 阶段只COPY精简后的/build内容到/build-filesDockerfile#L23-L70。构建器中的 Node.js 工具链与最终镜像的 Python/Docling 运行环境完全隔离这正是改进 Docker 构建流程以保证与 docling-serve-cpu 镜像兼容性这条变更记录的具体实现。另外为修复 Apify CLI 的 ES modules 兼容性问题CHANGELOG Fixed ES modules compatibility issue with Apify CLIbuilder 阶段生成的actor包装脚本将 CLI 声明为type:module的 npm 包来执行避免直接运行 CLI 入口文件导致的模块解析错误。3.3 启动流程加固健康检查与可配置 API 参数1.1.0 强调Enhanced startup process with health checks和Added configurable API host and port through environment variables。在源码中对应两处Dockerfile#L30-L33 通过环境变量固化 API 参数ENV PYTHONUNBUFFERED1 \ PYTHONDONTWRITEBYTECODE1 \ DOCLING_SERVE_HOST0.0.0.0 \ DOCLING_SERVE_PORT5001actor.sh#L195-L233 实现了一个最多重试 30 次的启动探测循环后台拉起docling-serve run --host 0.0.0.0 --port 5001后逐秒检查进程存活、grep 日志中的Application startup complete标记并额外检测Permission denied/PermissionError提前失败随后还内嵌一段 Python 探测脚本对 5001 端口做最多 5 次 TCP 连通性验证actor.sh#L254-L273。CHANGELOG 中Added explicit tmpfs volume for temporary files则对应 Dockerfile#L77 的VOLUME [/tmp]声明另有一条VOLUME [/tmp/easyocr-models]用于 OCR 模型目录的持久化Dockerfile#L80。3.4 修复输入目录冲突问题1.1.0 的 Fixed 部分记录了一个具体的解析缺陷Fixed actor input file conflict in get_actor_input(): now checks for and removes an existing /tmp/actor-input/INPUT directory if found, ensuring valid JSON input parsing.即读取 Actor 输入时若/tmp/actor-input/INPUT已存在例如容器复用场景会先清理该目录再解析保证apify actor get-input总能拿到有效的 JSON 输入。3.5 1.1.0 的技术栈快照该版本 Technical Details 小结为Actor 规范 v1基础镜像quay.io/ds4sd/docling-serve-cpu:latestNode.js 20.x 运行 Apify CLI移除了对 Python 依赖的直接安装Eliminated Python dependencies简化的 Docker 构建流程。这与 1.0.0 中Docling v2.17.0 Python 3.11 独立安装的形态形成鲜明对比——处理职责完全移交给了官方 serve 镜像内的运行时。四、输入输出契约与 CHANGELOG 变更相互印证1.1.0 中修订 JSON payload 结构以匹配 docling-serve API 格式这条变更直接体现在当前 input_schema.json 上输入只要求两个字段且都透传给 docling-serve字段类型必填预填默认说明http_sourcesarray是示例 PDF URL待处理文档的 URL 列表支持 PDF、DOCX、PPTX、XLSX、HTML、MD、XML、图片等optionsobject否{to_formats: [md]}处理选项如to_formats、do_ocr一个典型调用仓库 Apify 集成文档 与 Actor README 中均给出apify call vancura/docling --input{ options: { to_formats: [md, json, html, text, doctags] }, http_sources: [ {url: https://example.com/document.pdf} ] }输出侧的 Dataset 记录结构定义在 dataset_schema.json要求每条记录包含url源文档、output_file结果在 key-value store 中的直链与statussuccess/error可选error字段描述失败详情——这正是 CHANGELOG 中Dataset records with processing status特性的结构化落地。actor.sh 中的push_to_dataset函数即按此结构写入{output_file, format, size, status}字段。结果文件本身zip 打包的转换产物通过upload_to_kvs函数写入 key-value store 的OUTPUT键日志则导出到LOG键actor.sh#L366-L405 的cleanup陷阱函数在进程退出时执行停 API、传日志、清理临时目录的完整收尾序列。五、本地开发与复现CHANGELOG 所描述的所有组件都可以从仓库.actor/目录直接查验目录结构如下与 Actor README 的 Actor Structure 一节一致.actor/ ├── Dockerfile # 多阶段容器定义node:20-slim docling-serve-cpu ├── actor.json # Actor 元数据规范 v1 ├── actor.sh # 主执行脚本启动 docling-serve API 并编排处理流程 ├── input_schema.json # 输入参数定义 ├── dataset_schema.json # Dataset 输出格式定义 ├── CHANGELOG.md # 版本历史本文主体 └── README.md # 完整使用文档本地开发流程摘自 README 的 Local Development 章节克隆仓库、确保已安装 Docker然后在仓库根目录执行apify run即可本地拉起 Actor。六、小结两个版本揭示的演进逻辑1.0.0解决的是能用多格式输入输出、OCR、错误码、日志、Dataset 状态记录一应俱全技术栈为独立安装的 Docling v2.17.0Python 3.111.1.0解决的是轻量与可靠处理核心整体外包给官方docling-serve-cpu镜像与/v1alpha/convert/source标准端点镜像瘦身约 2GB多阶段构建隔离 Node/Python 依赖启动加入 30 次轮询 端口探活双重健康检查并修复了输入目录冲突这一边界缺陷。从 CHANGELOG 与 actor.sh、Dockerfile 的逐条对照可以确认变更记录中的每一项Changed/Fixed都在当前代码中有可定位的对应实现该 Actor 已成为 Docling 官方文档体系中云端无安装运行的推荐入口见 docs/integrations/apify.md。若需跟进版本变化直接阅读 .actor/CHANGELOG.md 并按条目回查对应源码文件即可复现本文的全部结论。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Docling Actor 版本演进解析：从 Docling CLI 到 docling-serve API 的无服务器文档处理
Docling Actor 版本演进解析从 Docling CLI 到 docling-serve API 的无服务器文档处理【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling本文以 Docling 仓库中的.actor/CHANGELOG.md为主体完整还原 Docling Actor 从 1.0.0 到 1.1.0 的版本演进脉络如何从直接调用 Docling CLI重构为调用官方 docling-serve 容器内的 REST API、Docker 镜像如何从约 6GB 瘦身到约 4GB、启动健康检查与错误处理机制如何逐步加固并结合.actor/目录下的 Dockerfile、actor.sh 与 JSON Schema 给出可对照源码的实证细节。读完本文你将能理解 Apify 平台上运行 Docling 的完整架构、输入输出契约以及本地复现开发的具体路径。一、背景Docling Actor 是什么Docling Actor 是 Docling 项目在 Apify 平台上的无服务器serverless封装允许用户不提供本地安装仅凭一份 JSON 配置和文档 URL即可在云端完成复杂文档PDF、DOCX、图片等到结构化格式Markdown、JSON、HTML、Text、DocTags的转换并可选启用 OCR 识别扫描件。仓库中.actor/目录就是该 Actor 的完整实现主文档见 Docling Actor 说明仓库文档侧的集成入口在 Apify 集成页。Actor 通过 Apify 的 Actor 规范 v1 定义其元数据文件 actor.json 声明了构建与运行入口{ actorSpecification: 1, name: docling, version: 1.0, environmentVariables: {}, dockerFile: ./Dockerfile, inputSchema: ./input_schema.json, scripts: { run: ./actor.sh } }CHANGELOG 声明其格式遵循 Keep a Changelog 惯例并遵守语义化版本Semantic Versioning。当前仓库记录的版本轨迹共有两个正式版本[1.0.0] - 2025-02-07与[1.1.0] - 2025-03-09分别对应初始发布和架构级重构两个阶段。二、版本 1.0.02025-02-07初始发布CHANGELOG 中 1.0.0 条目 记录了 Actor 的首个可用形态核心能力包括多格式输入支持 PDF、DOCX、图片等多种文档格式OCR 能力可处理扫描版文档多格式输出支持md、json、html、text、doctags五种导出格式完善的错误处理与日志处理过程中的详细日志与异常捕获带状态字段的 Dataset 记录每次处理会向 Apify Dataset 写入一条包含处理状态success/error与结果 URL 的记录内存监控与资源优化安全特性容器内以非 root 用户运行。1.0.0 的技术栈与错误码约定该版本的技术细节Technical Details明确记录了Actor 规范版本v1依赖Docling v2.17.0与Python 3.11Node.js 20.x用于运行 Apify CLI一套完整的错误码约定错误码含义10无效输入Invalid input11URL 无法访问URL inaccessible12Docling 处理失败Docling processing failed13输出文件缺失Output file missing14存储操作失败Storage operation failed15OCR 处理失败OCR processing failed这组错误码体现了 1.0.0 阶段以 Docling CLI 为处理核心的设计——每一类失败输入、URL、处理、落盘、OCR都有独立退出码便于 Apify 运行时区分失败原因。值得注意的是当前仓库中的 actor.sh 已将其简化重定义为ERR_API_UNAVAILABLE15与ERR_INVALID_INPUT16两个只读常量说明脚本在后续迭代中沿用了退出码分层表达失败场景的思想但具体取值随架构切换发生了调整。三、版本 1.1.02025-03-09从 CLI 到 docling-serve API 的架构重构1.1.0 条目 是 CHANGELOG 中篇幅最大的部分记录的是一次彻底的架构切换可归纳为五个方面。3.1 处理核心切换弃用完整 Docling CLI改用 docling-serve API1.1.0 的第一条 Changed 记录即Switched from full Docling CLI to docling-serve API。具体落地包括基础镜像更换改用官方quay.io/ds4sd/docling-serve-cpu:latest镜像Actor 不再自行安装 Docling 及其全部 Python 依赖Technical Details 中明确Eliminated Python dependencies端点标准化请求端点从自定义的/convert改为 docling-serve 的标准端点/v1alpha/convert/source。这一点可直接在 actor.sh 中得到印证DOCLING_API_ENDPOINThttp://localhost:5001/v1alpha/convert/source请求载荷结构化JSON payload 结构被修订为 docling-serve 的 API 格式即http_sourcesoptions双字段结构。actor.sh 中用jq在原始输入基础上强制注入return_as_file: true使 API 直接返回打包的 zip 文件REQUEST_JSON$(echo $INPUT | jq .options {return_as_file: true})随后以curl直接 POST 二进制请求体到上述端点actor.sh#L306curl -s -H content-type: application/json -X POST \ --data-binary $API_DIR/request.json -o $API_DIR/output.zip $DOCLING_API_ENDPOINT输出解析增加了按输出格式to_formats正确解析响应字段与 content-type 的逻辑确保 md/json/html/text/doctags 各自的返回形式被正确处理。3.2 Docker 镜像瘦身与多阶段构建CHANGELOG 记录镜像体积从约 6GB 降至约 4GB手段是为处理依赖实施多阶段 Docker 构建multi-stage build。对照当前 Dockerfile 可以看到这一设计的完整落地第一阶段builder基于node:20-slim仅安装apify-cli并将node_modules收敛到/build/lib/node_modules同时生成/build/bin/actor包装脚本最后执行npm cache clean --force清理缓存Dockerfile#L2-L20第二阶段最终镜像基于quay.io/ds4sd/docling-serve-cpu:latest从 builder 阶段只COPY精简后的/build内容到/build-filesDockerfile#L23-L70。构建器中的 Node.js 工具链与最终镜像的 Python/Docling 运行环境完全隔离这正是改进 Docker 构建流程以保证与 docling-serve-cpu 镜像兼容性这条变更记录的具体实现。另外为修复 Apify CLI 的 ES modules 兼容性问题CHANGELOG Fixed ES modules compatibility issue with Apify CLIbuilder 阶段生成的actor包装脚本将 CLI 声明为type:module的 npm 包来执行避免直接运行 CLI 入口文件导致的模块解析错误。3.3 启动流程加固健康检查与可配置 API 参数1.1.0 强调Enhanced startup process with health checks和Added configurable API host and port through environment variables。在源码中对应两处Dockerfile#L30-L33 通过环境变量固化 API 参数ENV PYTHONUNBUFFERED1 \ PYTHONDONTWRITEBYTECODE1 \ DOCLING_SERVE_HOST0.0.0.0 \ DOCLING_SERVE_PORT5001actor.sh#L195-L233 实现了一个最多重试 30 次的启动探测循环后台拉起docling-serve run --host 0.0.0.0 --port 5001后逐秒检查进程存活、grep 日志中的Application startup complete标记并额外检测Permission denied/PermissionError提前失败随后还内嵌一段 Python 探测脚本对 5001 端口做最多 5 次 TCP 连通性验证actor.sh#L254-L273。CHANGELOG 中Added explicit tmpfs volume for temporary files则对应 Dockerfile#L77 的VOLUME [/tmp]声明另有一条VOLUME [/tmp/easyocr-models]用于 OCR 模型目录的持久化Dockerfile#L80。3.4 修复输入目录冲突问题1.1.0 的 Fixed 部分记录了一个具体的解析缺陷Fixed actor input file conflict in get_actor_input(): now checks for and removes an existing /tmp/actor-input/INPUT directory if found, ensuring valid JSON input parsing.即读取 Actor 输入时若/tmp/actor-input/INPUT已存在例如容器复用场景会先清理该目录再解析保证apify actor get-input总能拿到有效的 JSON 输入。3.5 1.1.0 的技术栈快照该版本 Technical Details 小结为Actor 规范 v1基础镜像quay.io/ds4sd/docling-serve-cpu:latestNode.js 20.x 运行 Apify CLI移除了对 Python 依赖的直接安装Eliminated Python dependencies简化的 Docker 构建流程。这与 1.0.0 中Docling v2.17.0 Python 3.11 独立安装的形态形成鲜明对比——处理职责完全移交给了官方 serve 镜像内的运行时。四、输入输出契约与 CHANGELOG 变更相互印证1.1.0 中修订 JSON payload 结构以匹配 docling-serve API 格式这条变更直接体现在当前 input_schema.json 上输入只要求两个字段且都透传给 docling-serve字段类型必填预填默认说明http_sourcesarray是示例 PDF URL待处理文档的 URL 列表支持 PDF、DOCX、PPTX、XLSX、HTML、MD、XML、图片等optionsobject否{to_formats: [md]}处理选项如to_formats、do_ocr一个典型调用仓库 Apify 集成文档 与 Actor README 中均给出apify call vancura/docling --input{ options: { to_formats: [md, json, html, text, doctags] }, http_sources: [ {url: https://example.com/document.pdf} ] }输出侧的 Dataset 记录结构定义在 dataset_schema.json要求每条记录包含url源文档、output_file结果在 key-value store 中的直链与statussuccess/error可选error字段描述失败详情——这正是 CHANGELOG 中Dataset records with processing status特性的结构化落地。actor.sh 中的push_to_dataset函数即按此结构写入{output_file, format, size, status}字段。结果文件本身zip 打包的转换产物通过upload_to_kvs函数写入 key-value store 的OUTPUT键日志则导出到LOG键actor.sh#L366-L405 的cleanup陷阱函数在进程退出时执行停 API、传日志、清理临时目录的完整收尾序列。五、本地开发与复现CHANGELOG 所描述的所有组件都可以从仓库.actor/目录直接查验目录结构如下与 Actor README 的 Actor Structure 一节一致.actor/ ├── Dockerfile # 多阶段容器定义node:20-slim docling-serve-cpu ├── actor.json # Actor 元数据规范 v1 ├── actor.sh # 主执行脚本启动 docling-serve API 并编排处理流程 ├── input_schema.json # 输入参数定义 ├── dataset_schema.json # Dataset 输出格式定义 ├── CHANGELOG.md # 版本历史本文主体 └── README.md # 完整使用文档本地开发流程摘自 README 的 Local Development 章节克隆仓库、确保已安装 Docker然后在仓库根目录执行apify run即可本地拉起 Actor。六、小结两个版本揭示的演进逻辑1.0.0解决的是能用多格式输入输出、OCR、错误码、日志、Dataset 状态记录一应俱全技术栈为独立安装的 Docling v2.17.0Python 3.111.1.0解决的是轻量与可靠处理核心整体外包给官方docling-serve-cpu镜像与/v1alpha/convert/source标准端点镜像瘦身约 2GB多阶段构建隔离 Node/Python 依赖启动加入 30 次轮询 端口探活双重健康检查并修复了输入目录冲突这一边界缺陷。从 CHANGELOG 与 actor.sh、Dockerfile 的逐条对照可以确认变更记录中的每一项Changed/Fixed都在当前代码中有可定位的对应实现该 Actor 已成为 Docling 官方文档体系中云端无安装运行的推荐入口见 docs/integrations/apify.md。若需跟进版本变化直接阅读 .actor/CHANGELOG.md 并按条目回查对应源码文件即可复现本文的全部结论。【免费下载链接】doclingGet your documents ready for gen AI项目地址: https://gitcode.com/GitHub_Trending/do/docling创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考