一分钟启动服务器#
pip install "docling-serve[ui]"
docling-serve run --enable-ui # API：http://127.0.0.1:5001 · 文档：/docs · 界面：/uidocker run -p 5001:5001 -e DOCLING_SERVE_ENABLE_UI=1 \
quay.io/docling-project/docling-serve-cpudocling-serve run 监听所有网卡（主机 0.0.0.0）；docling-serve dev 绑定 127.0.0.1 并在开发时自动重载。镜像选择和 GPU 版本见 Docker 页面。
请求如何流转#
接口#
| 方法与路径 | 用途 |
|---|---|
POST /v1/convert/source | 从 URL 或云存储来源转换，等待结果 |
POST /v1/convert/file | 转换上传的文件（multipart），等待结果 |
POST /v1/convert/source/async、/v1/convert/file/async | 启动任务，立即返回 task_id |
POST /v1/convert/source/batch | 把多个来源作为一个批次提交 |
POST /v1/chunk/{hybrid|hierarchical}/{source|file}[/async] | 一次调用完成转换和分块 |
GET /v1/status/poll/{task_id} | 任务状态（pending、started、success、failure……） |
WS /v1/status/ws/{task_id} | 通过 WebSocket 推送状态更新 |
GET /v1/result/{task_id} | 获取完成的结果 |
GET /health、/ready、/version、/v1/capabilities | 健康、就绪、版本、已启用功能 |
GET /docs、/scalar、/ui | Swagger 文档、Scalar 文档、体验界面 |
路径读取自 1.38.2 的 docling_serve/app.py。管理接口（/v1/clear/*、/v1/memory/*）存在，但除非设置 DOCLING_SERVE_ENABLE_MANAGEMENT_ENDPOINTS，否则处于关闭状态。
转换一个 URL#
curl -X POST http://localhost:5001/v1/convert/source \
-H 'Content-Type: application/json' \
-d '{
"sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2408.09869"}],
"options": {"to_formats": ["md", "json"], "do_ocr": false}
}'响应是 ConvertDocumentResponse：document（按你请求的格式包含 md_content、json_content、html_content、text_content、doctags_content）、status、errors、processing_time、timings 和 confidence。
2.143.1 请求模型接受的来源类型：http、file（base64）、s3、azure_blob、google_cloud_storage 和 google_drive。
上传文件#
curl -X POST http://localhost:5001/v1/convert/file \
-F 'files=@report.pdf' \
-F 'to_formats=md' \
-F 'do_ocr=false' \
-F 'table_mode=fast'选项变成与 JSON 请求体同名的表单字段；列表通过重复字段传入（-F to_formats=md -F to_formats=json）。配置生成器可以替你写好这些请求。
长文档：异步任务#
import time, requests
BASE = "http://localhost:5001"
job = requests.post(f"{BASE}/v1/convert/source/async", json={
"sources": [{"kind": "http", "url": "https://arxiv.org/pdf/2408.09869"}],
"options": {"to_formats": ["md"]},
}).json()
task_id = job["task_id"]
while True:
status = requests.get(f"{BASE}/v1/status/poll/{task_id}").json()
if status["task_status"] in ("success", "partial_success", "failure"):
break
time.sleep(2)
result = requests.get(f"{BASE}/v1/result/{task_id}").json()
print(result["document"]["md_content"][:300])常用选项#
JSON 中的 options 对象即 ConvertDocumentsOptions。2.143.1 中最常用的字段及默认值：
| 字段 | 默认值 | 说明 |
|---|---|---|
to_formats | ["md"] | md、json、html、text、doctags…… |
image_export_mode | placeholder | 与 CLI 不同，CLI 默认为 embedded |
do_ocr / force_ocr | true / false | |
ocr_preset / ocr_lang | auto / 无 | 预设 ID 即 CLI 的引擎名；ocr_engine 仍可用但已弃用。pip 安装的服务器没有 onnxruntime，因此 rapidocr 预设会失败——auto 可用。使用 tesseract 时务必设置 ocr_lang（eng 或 iso:en 可用；单写 en 不行）。 |
pipeline | standard | vlm 搭配 vlm_pipeline_preset |
table_mode | accurate | fast 更快 |
page_range | 全部页面 | [1, 10] |
document_timeout | 无 | 每个文档的秒数 |
images_scale | 2.0 | 服务器上限为 DOCLING_SERVE_MAX_IMAGES_SCALE（2.0） |
do_formula_enrichment、do_code_enrichment、do_picture_description、do_chart_extraction | false | 增强模型 |
服务器设置#
所有设置都是带 DOCLING_SERVE_ 前缀的环境变量（或由 DOCLING_SERVE_CONFIG_FILE 指定的 YAML/JSON 文件）。Uvicorn 设置使用 UVICORN_ 前缀。
| 变量 | 默认值 | 作用 |
|---|---|---|
DOCLING_SERVE_ENABLE_UI | false | 在 /ui 提供体验界面 |
DOCLING_SERVE_API_KEY | 空（不认证） | 要求 X-Api-Key |
DOCLING_SERVE_MAX_SYNC_WAIT | 120 | 同步请求等待的秒数 |
DOCLING_SERVE_ENG_KIND | local | local、rq（Redis 队列）或 ray |
DOCLING_SERVE_ENG_LOC_NUM_WORKERS | 2 | 本地引擎的并行任务数 |
DOCLING_SERVE_MAX_NUM_PAGES、…_MAX_FILE_SIZE | 不限 | 拒绝过大的文档 |
DOCLING_SERVE_MAX_SOURCES_PER_REQUEST | 3 | 每次调用的来源数 |
DOCLING_SERVE_LOAD_MODELS_AT_BOOT | true | 启动时预热模型 |
DOCLING_SERVE_ARTIFACTS_PATH | 无 | 预下载的模型（离线） |
DOCLING_SERVE_ENABLE_REMOTE_SERVICES | false | 允许基于 API 的模型 |
DOCLING_SERVE_SINGLE_USE_RESULTS、…_RESULT_REMOVAL_DELAY | true、300 | 获取后删除结果 |
DOCLING_SERVE_CORS_ORIGINS | ["*"] | 面向浏览器客户端时应收紧 |
默认值读取自 docling_serve/settings.py（1.38.2）。
Python 客户端#
Docling 自带客户端，接口与 DocumentConverter 对应，在本地和远程转换之间切换只需改一行。
from docling.datamodel.service.options import ConvertDocumentsOptions
from docling.service_client import DoclingServiceClient
with DoclingServiceClient(url="http://localhost:5001") as client: # 如已设置则加 api_key="..."
result = client.convert(
"https://arxiv.org/pdf/2408.09869",
options=ConvertDocumentsOptions(do_ocr=False, to_formats=["md"]),
)
print(result.document.export_to_markdown()[:300])不装 PyTorch 也能安装：pip install "docling-slim[service-client]"；这个组件还会加入 docling convert-remote 命令（见 CLI 参考）。
MCP：给 AI 智能体用的 Docling#
docling-mcp 把转换和文档工具提供给 Claude Desktop、LM Studio 等 MCP 客户端。3.x 版本的默认转换模式是 remote，因此请把它指向一个 docling-serve 实例，或安装 local 组件。
{
"mcpServers": {
"docling": {
"command": "uvx",
"args": ["--from=docling-mcp", "docling-mcp-server"],
"env": {
"DOCLING_MCP_CONVERSION_MODE": "remote",
"DOCLING_MCP_SERVICE_URL": "http://localhost:5001"
}
}
}
}uvx --from "docling-mcp[local]" docling-mcp-server --transport stdio
# 环境中设置 DOCLING_MCP_CONVERSION_MODE=local传输方式：stdio（桌面客户端）、sse 和 streamable-http（容器）。docling-mcp 3.x 需要 MCP SDK 2.x；尚未迁移的客户端请固定 docling-mcp<3.0.0。
生产环境清单#
- 设置
DOCLING_SERVE_API_KEY，并限制DOCLING_SERVE_CORS_ORIGINS。 - 超过几页的文档都用异步接口；同步调用上限为 120 秒。
- 用
DOCLING_SERVE_MAX_NUM_PAGES和DOCLING_SERVE_MAX_FILE_SIZE限制输入。 - 把模型预下载到镜像中（
DOCLING_SERVE_ARTIFACTS_PATH），让 Pod 无需联网即可启动。 - 单机不够时，用
DOCLING_SERVE_ENG_KIND=rq和 Redis 工作进程横向扩展。
常见问题
docling-serve 使用哪个端口？
默认 5001。API 地址为 http://127.0.0.1:5001，交互式 API 文档在 /docs；用 --enable-ui 或 DOCLING_SERVE_ENABLE_UI=1 开启后，/ui 提供体验界面。
如何为 docling-serve 添加认证？
把 DOCLING_SERVE_API_KEY 设为一个密钥，客户端随后必须在 X-Api-Key 请求头中发送它。
为什么 docling-serve 的同步请求会超时？
同步接口最多等待 DOCLING_SERVE_MAX_SYNC_WAIT 秒（默认 120）。长文档请使用 /async 接口并轮询结果，或调高这个上限。
docling-serve 的结果能获取两次吗？
默认不能。DOCLING_SERVE_SINGLE_USE_RESULTS 为 true，结果在被获取后（延迟 300 秒）删除。如果客户端可能重试，请设为 false。
如何把 Docling 连接到 Claude Desktop 或其他 MCP 客户端？
使用 docling-mcp：添加一个运行 uvx --from docling-mcp docling-mcp-server 的服务器条目。从 docling-mcp 3.x 起默认模式为 remote，因此请把 DOCLING_MCP_SERVICE_URL 设为你的 docling-serve，或安装 docling-mcp[local] 并设置 DOCLING_MCP_CONVERSION_MODE=local。
资料来源
- docling-serve 1.38.2 源码：app.py、settings.py、auth.py
- docling-serve 文档
- docling 2.143.1：ConvertDocumentsOptions（docling/datamodel/service/options.py）
- docling-mcp 3.3.0 README