MinerU/docs/next/config.md

配置体系

页码规范与历史结果兼容说明见 PDF 页码范围规范。

状态: Draft 读者: 想了解 doclib / mineru 配置的用户、实现配置能力的核心开发者 范围: 本地配置、远端配置、解析参数、环境变量和优先级规则 非目标: 替代 CLI 参数手册；替代部署文档 来源: 配置专题文档仍待继续核对

1. 定位

ONNX 小模型新增 model.onnx_device: auto | cpu | gpu，环境变量为 MINERU_MODEL_ONNX_DEVICE。首次实际使用时自动选择并保存，独显优先； 集显测速、重新选择及 DirectML 厂商预设见 ONNX 设备选择。

配置体系定义 MinerU 如何在不同启动阶段得到最终行为。

MinerU 有两类配置：

• 启动前配置：doclib server 启动之前就必须知道，通常来自文件形式的配置或内置默认值。
• 运行时配置：doclib server 启动之后可从 SQLite 读取和修改，由 config、watches、exclude_rules、parsing_rules 等表承载。

启动前还存在一个 bootstrap 根目录:

• MINERU_HOME 决定 MinerU home，默认 ~/.mineru。
• 默认配置文件路径是 $MINERU_HOME/config.yaml。
• 默认 DB、日志和 UDS socket 从 MINERU_HOME 派生；默认 data_dir 是 $MINERU_HOME/doclib，其下包含 parsed/ 和 temp/。
• MINERU_CONFIG 仍可显式指定配置文件路径；MINERU_HOME 只影响默认 home 和默认配置文件位置。

远程 VLM

model.vlm 是所有本地解析入口的 VLM 默认配置，适用于 API server、Python parse() / parse_async() 和 mineru-kit parse。Standard/Advanced 将 VLM 推理交给 远程 MinerU OpenAI-compatible 服务，本地继续执行 Hybrid 处理；Flash/Basic 不调用远程 VLM。 上游须部署支持 MinerU 文档理解输出的模型，并提供 /v1/models 和 /v1/chat/completions。

model:
  vlm:
    server_url: http://127.0.0.1:30000/v1
    api_key: ${VLM_API_KEY:-}
    model: ""
    http_timeout: 600
    max_concurrency: 100

未配置 server_url 或显式设为空字符串时使用本地 VLM。地址可使用 HTTP/HTTPS 服务根地址或以 /v1 结尾的地址；反向代理前缀会保留，例如 https://host/proxy/v1 对应 https://host/proxy/v1/chat/completions。URL 不接受内嵌用户名、密码、query 或 fragment。 api_key 可为空；model 为空时要求上游模型列表恰好包含一个模型，多模型服务须显式指定模型名。 显式模型名也会通过模型列表校验。http_timeout 单位为秒，max_concurrency 是 VLM 推理请求并发，两者均为正整数；API 的 --concurrency 则控制解析任务并发。

环境变量包括 MINERU_MODEL_VLM_SERVER_URL、MINERU_MODEL_VLM_API_KEY、 MINERU_MODEL_VLM_MODEL、MINERU_MODEL_VLM_HTTP_TIMEOUT 和 MINERU_MODEL_VLM_MAX_CONCURRENCY。API 启动时的优先级为：显式启动参数 > 环境变量 > YAML > 默认值。启动参数及示例见 api-server。

Python 的 create_app()、MinerUParser、parse() / parse_async() 以及底层分析入口 可传入 vlm_config: VlmConfig | None：None 使用全局设置；显式对象完整覆盖全局设置。 应用与解析器各自保存配置副本，不修改全局配置或进程环境。

from mineru.config import VlmConfig
from mineru.parser import parse

result = parse("document.pdf", tier="standard")  # 使用全局 model.vlm
local_result = parse("document.pdf", vlm_config=VlmConfig())  # 本次使用本地 VLM

远程模式不会自动回退本地 VLM。旧底层环境变量 MINERU_VL_API_KEY、 MINERU_VL_MODEL_NAME 若与有效的新配置冲突，会明确报错；应清除旧变量并使用上述 MINERU_MODEL_VLM_* 配置。未配置远程地址时，旧 MINERU_VL_SERVER 不会启用远程 VLM。

Markdown render 同样读取启动前 config.yaml，当前支持以下配置：

render:
  latex_delimiters:
    display:
      left: "$$"
      right: "$$"
    inline:
      left: "$"
      right: "$"

四个 delimiter 必须为非空字符串。缺省值如上；环境变量可按现有字段路径规则覆盖， 例如 MINERU_RENDER_LATEX_DELIMITERS_INLINE_LEFT。

PDF 的 LLM 辅助后处理同样读取启动前 config.yaml：

llm_aided:
  api_key: ${MINERU_LLM_API_KEY:-}
  base_url: https://dashscope.aliyuncs.com/compatible-mode/v1
  model: qwen3.5-plus
  enable_thinking: false
  max_concurrency: 16
  features:
    title_leveling: false
    cross_page_table_cell_merge: false

两个功能默认关闭并共享同一套 OpenAI-compatible 连接参数。title_leveling 在严格 MiddleJson.pages 上优化标题层级，但只在 MiddleJson.is_full_document=true 的整本 PDF 输入中运行； 抽页结果会跳过标题优化。cross_page_table_cell_merge 不受整本输入限制，只消费确定性后处理 已经写入的 continues_prev，再把逐单元格的 0/1 结果写入后表根块 cell_merge。两个功能 通过同一个异步客户端并发请求，max_concurrency 是不小于 1 的共享请求上限，默认值为 16。 标题分级结果允许 1 到 6，段落标题的 1 会归一为 2，最终严格标题层级范围为 2 到 6。前置 MinerU VLM 的跨页单元格检测保持关闭。任一功能启用时，api_key、base_url 和 model 均必须为非空字符串；省略 enable_thinking 时不会发送该扩展参数。

环境变量可覆盖任意强类型字段，例如 MINERU_LLM_AIDED_API_KEY、 MINERU_LLM_AIDED_MAX_CONCURRENCY、 MINERU_LLM_AIDED_FEATURES_TITLE_LEVELING 和 MINERU_LLM_AIDED_FEATURES_CROSS_PAGE_TABLE_CELL_MERGE。

配置必须服务两个产品原则：

• 隐私优先：任何配置都不能导致静默上传文档。
• 质量优先：PDF/image 主动阅读未指定 tier 时使用默认选择策略，不能静默降级到 flash；OFD/EPUB/Office/HTML/MHTML/CSV/TSV 按实际能力归一为 flash；其它 text 直接读取。

全局日志级别由 log.level 控制，默认 info，可选 trace、debug、info、 warning、error、critical。环境变量 MINERU_LOG_LEVEL 可覆盖 YAML； 该配置作用于当前进程的 Loguru 默认 stderr sink，不会移除宿主程序显式添加的 自定义 sink。doclib.log.level 是 Doclib 进程日志级别的局部覆盖；api-server 启动参数 --log-level 是服务侧（Uvicorn/HTTP 访问/服务自身 stdlib 日志）的局部 覆盖，不影响 Loguru 默认 sink。

2. 两阶段配置模型

2.1 启动前配置

启动前配置解决“server 还没起来，不能读数据库”的问题。

这类配置包括：

分组	字段	默认值	说明
全局日志	log.level	info	Loguru 默认 stderr sink 级别；可用 MINERU_LOG_LEVEL 覆盖
UDS	doclib.uds.enabled	auto	auto / true / false；auto 时当前 Python runtime 支持 UDS 则启用，否则关闭
UDS	doclib.uds.path	~/.mineru/doclib.sock	CLI / doclib 通信 socket，默认取 $MINERU_HOME/doclib.sock
UDS	doclib.uds.permission	0o600	socket 权限
TCP	doclib.tcp.enabled	auto	auto / true / false；auto 时 UDS 不可用则启用，作为 Windows fallback
TCP	doclib.tcp.host	127.0.0.1	TCP 监听地址
TCP	doclib.tcp.port	15980	TCP 监听端口
TCP	doclib.tcp.strict_port	False	端口占用时是否报错
TCP	doclib.tcp.port_probe_count	100	strict_port 为 False 时从 port 起向后探测的端口数量上限
TCP	doclib.tcp.backlog	128	socket backlog
TCP	doclib.tcp.timeout	600	keep-alive timeout
log	doclib.log.dir	~/.mineru/logs	默认日志目录；未单独配置的日志路径会从该目录派生
log	doclib.log.app_path	unset → <dir>/doclib.log	Python application 日志路径
log	doclib.log.access_path	unset → <dir>/doclib.access.log	HTTP access 日志路径
log	doclib.log.stdout_path	unset → <dir>/doclib.stdout.log	server 子进程 stdout fallback 日志路径
log	doclib.log.stderr_path	unset → <dir>/doclib.stderr.log	server 子进程 stderr fallback 日志路径
log	doclib.log.parse_server_stdout_path	unset → <dir>/doclib.parse-server.stdout.log	managed parse-server stdout 日志路径
log	doclib.log.parse_server_stderr_path	unset → <dir>/doclib.parse-server.stderr.log	managed parse-server stderr 日志路径
log	doclib.log.level	unset → log.level	Doclib 进程日志级别局部覆盖
doclib	doclib.endpoint_path	~/.mineru/doclib.endpoint.json	当前 server 实际可用 endpoint discovery 文件
doclib	doclib.data_dir	~/.mineru/doclib	数据目录，默认取 $MINERU_HOME/doclib，但仍可通过配置文件或环境变量覆盖
doclib	doclib.managed_parse_server.host	127.0.0.1	managed parse-server 监听地址
doclib	doclib.managed_parse_server.port	16580	managed parse-server 监听端口
doclib	doclib.managed_parse_server.strict_port	False	端口占用时是否报错
doclib	doclib.managed_parse_server.port_probe_count	100	strict_port 为 False 时从 port 起向后探测的端口数量上限
doclib	doclib.ingest_workers	2	ingest worker 数
doclib	doclib.parse_workers	2	parse worker 数
doclib	doclib.scan_interval_sec	300	watch 扫描间隔
doclib	doclib.device_check_interval_sec	5	可插拔设备检测间隔
doclib	doclib.ingest_lock_timeout_sec	60	ingest 锁超时
doclib	doclib.parse_lock_timeout_sec	1800	parse 锁超时
doclib	doclib.scan_lock_timeout_sec	1800	scan 锁超时
doclib	doclib.compaction_interval_sec	3600	compaction 间隔
doclib	doclib.parse_server_health_check_interval_sec	30	parse-server 健康检查间隔
doclib	doclib.parse_server_probe_timeout_sec	10	parse-server 探测超时
doclib	doclib.parse_server_startup_grace_sec	30	managed parse-server 启动宽限时间
doclib	doclib.parse_server_startup_timeout_sec	600	managed parse-server 启动硬超时；超时后进入重启策略
doclib	doclib.parse_server_stop_timeout_sec	10	managed parse-server 停止超时
model	model.base_dir	~/.mineru/models	模型文件根目录，默认取 $MINERU_HOME/models
model	model.source	auto	模型下载来源：auto / huggingface / modelscope / local
model	model.small_backend	auto	小模型后端：auto / onnx / torch；依据依赖与设备自动选择
model	model.vlm.engine	auto	本地 VLM：auto / llama-cpp / vllm / lmdeploy / mlx；远程地址优先，MLX 仅显式使用
sqlite	doclib.sqlite.path	~/.mineru/doclib.db	SQLite DB 路径
sqlite	doclib.sqlite.busy_timeout_ms	5000	SQLite 锁等待时间（毫秒）
sqlite	doclib.sqlite.lock_retry_attempts	3	SQLITE_BUSY / SQLITE_LOCKED 的额外重试次数
sqlite	doclib.sqlite.lock_retry_base_delay_ms	50	SQLite 锁重试的指数退避初始延迟（毫秒）
sqlite	doclib.sqlite.mmap_size	268435456	mmap size
sqlite	doclib.sqlite.cache_size	-20000	SQLite cache size
sqlite	doclib.sqlite.wal_autocheckpoint	1000	WAL checkpoint 阈值
sqlite	doclib.sqlite.journal_size_limit	33554432	WAL journal size limit
sqlite	doclib.sqlite.temp_store	memory	temp store
sqlite	doclib.sqlite.synchronous	NORMAL	synchronous pragma

doclib.uds.enabled 和 doclib.tcp.enabled 是 auto | true | false 配置项。默认值为 auto。当前第一版只在启动前解析 auto: UDS 可用则启用 UDS、关闭 TCP；UDS 不可用则关闭 UDS、启用 TCP loopback。用户显式配置 true / false 时，server 尊重该配置。

这些配置影响 doclib 如何启动，因此不能依赖 mineru config 读取。

2.2 运行时配置

运行时配置在 doclib server 启动后可读写。

来源	例子	存储	说明
SQLite config 表	parse_server.local.mode、parse_server.remote.url	KV	doclib 运行时配置
watches 表	watch 目录、可插拔设备状态	表结构	文件发现配置
exclude_rules 表	exclude	表结构	路径排除规则
parsing_rules 表	parsing-rules	表结构	路径解析规则
当前命令显式参数	--tier standard、--remote	不持久化	当前请求覆盖
环境变量	MINERU_API_KEY	不持久化	临时凭证或 CI 覆盖
SDK client 参数	base_url、api_key	调用方决定	当前 client 实例

3. 优先级

运行时行为的优先级从高到低。API Key 等运行时凭证的优先级见“API Key 与环境变量”。

1. 当前命令显式参数。
2. 当前进程环境变量。
3. 启动前文件配置或 SQLite 配置。
4. 内置默认值。

启动前文件配置和 SQLite 配置不应定义同一配置项。需要在 doclib server 启动前确定的配置使用文件配置；doclib server 启动后可读写的配置使用 SQLite。设计上不允许同一项配置同时存在于文件和 DB，因此二者之间不应产生优先级冲突。

SDK client 显式参数属于当前调用方传入的请求上下文；当它最终转化为 CLI/API 请求时，按“当前命令显式参数”处理。

如果一个配置会改变隐私边界，例如启用远端上传，必须要求当前请求或规则显式允许，不能只因为全局配置存在 remote URL 或 API Key 就上传文档。

启动前配置只用于必须在 doclib 初始化前确定的字段，比如 UDS/TCP transport、endpoint discovery 路径、DB 路径、SQLite pragma。它不与 SQLite 配置定义同一 key，也不在 doclib 启动后被 SQLite 覆盖。MINERU_HOME 属于 bootstrap 层，负责默认 home 与默认配置文件位置；doclib.data_dir 是独立配置项，默认取 $MINERU_HOME/doclib。

4. 运行时 KV 配置

运行时 KV 配置的默认值由代码定义，SQLite config 表只保存用户 override。

key	默认值	说明
parse_server.local.mode	disabled	本地 parse-server 模式
parse_server.local.managed_tier	standard	managed 模式启动能力上限，只接受 basic 或 standard；Standard 同时提供 Advanced 请求能力
parse_server.remote.url	https://mineru.net/api	默认远端 API 地址

5. Parse-server 配置

parse-server 是 basic / standard / advanced 等质量 tier 的解析能力来源。它可以是本地独立进程，也可以是远端 mineru.net/api。

5.1 Local parse-server

key	默认值	说明
parse_server.local.mode	disabled	disabled / managed / self_hosted
parse_server.local.managed_tier	standard	managed 模式启动的 tier
parse_server.local.self_hosted_url	无	self-hosted parse-server URL
parse_server.local.self_hosted_api_key	无	self-hosted API Key，可选

模式语义：

mode	行为
disabled	不使用本地 parse-server；本地质量 tier 请求返回 no_engine 或相关错误
managed	doclib 启动和停止时自动管理 parse-server
self_hosted	用户自行启动 parse-server，doclib 只负责连接和探活

5.2 Remote parse-server

key	默认值	说明
parse_server.remote.url	https://mineru.net/api	默认远端 API 地址
parse_server.remote.api_key	无	远端 API Key

远端配置存在不等于允许上传。只有当前请求显式 --remote，或 parsing-rule 显式带 remote 语义时，才可以上传文档。

6. API Key 与环境变量

API Key 读取优先级：

1. Remote API 使用 SQLite config 中的 parse_server.remote.api_key。
2. 未配置 Remote API Key 时，回退到环境变量 MINERU_API_KEY。

parse_server.local.self_hosted_api_key 只读取自身的 SQLite config，不回退到 Remote API 的环境变量。

环境变量适合无 tty 场景和 CI 的默认凭证，但运行中的 doclib server 会优先使用 mineru config set 写入的运行时配置。环境变量不应改变是否允许 remote 上传的判断。

建议保留的环境变量：

变量	说明
MINERU_API_KEY	默认远端 API Key
MINERU_BASE_URL	SDK 或 CLI 的默认远端 URL，是否采用待定
MINERU_TELEMETRY	遥测开关，是否采用待定

7. CLI 参数与配置关系

mineru parse 的显式参数只影响当前请求：

CLI 参数	配置关系
--tier	覆盖当前请求 tier；未指定时使用默认选择策略
--remote	显式允许当前请求上传远端；远端 URL 来自 config，API Key 优先来自 config，未配置时使用环境变量
--pages	当前请求页码范围
--force	当前请求跳过 done 缓存；复用 active parse 或为未覆盖页创建新 parse；不删除或作废旧缓存
--wait / --no-wait	当前请求等待策略

mineru config 修改持久配置：

mineru config parse-server local.mode managed
mineru config parse-server local.managed-tier basic
mineru config parse-server remote.api-key sk-...

当前已实现的 config 命令分组：

命令	作用
mineru config show	展示 KV 配置、watch 和 rules
mineru watch add/list/remove/rescan	管理 watch 目录
mineru config exclude add/list/rm	管理排除规则
mineru config parsing-rules add/list/rm	管理解析规则
mineru config parse-server local.mode	设置本地 parse-server 模式
mineru config parse-server local.managed-tier	设置 managed tier
mineru config parse-server local.self-hosted-url	设置 self-hosted URL
mineru config parse-server local.self-hosted-api-key	设置 self-hosted API Key
mineru config parse-server remote.url	设置远端 URL
mineru config parse-server remote.api-key	设置远端 API Key

8. Watch 与 Rules

Watch 目录、parsing-rules 和 exclude 规则不直接存储在 config KV 中，但属于配置体系。

8.1 Watch

Watch 用于自动发现文件和建立搜索索引。

约束：

• watch 默认 tier 是 flash。
• watch 默认 tier 暂不配置化。
• watch 的目标是发现、预览和索引，不是最终阅读质量。
• watch 目录不允许嵌套。
• removable watch 路径不可达时，应标记 unreachable，不永久删除记录。

8.2 Parsing-rules

Parsing-rules 通过路径 glob 指定自动解析策略。

mineru config parsing-rules add "*/论文/*" --tier basic --pages all
mineru config parsing-rules add "*/合同/*" --tier standard --remote

约束：

• 对 PDF/image，规则必须显式指定 remote，才允许上传远端。
• 对 PDF/image，规则命中的 tier 必须经过能力检查。
• 对 PDF/image，规则未指定 tier 时按 standard -> basic -> flash 选择，并只记录实际使用的实体 tier。
• 对 OFD/EPUB/Office/HTML/MHTML/CSV/TSV，parsing-rule 的 tier、page_range 和 remote 不生效，实际按 flash 整本解析并记录；其它 text 只入库和索引，不创建 parse row。
• 完整归一规则见 ADR-0024。

8.3 Exclude

Exclude 使用 glob 模式排除路径。默认 exclude 规则由 DB 初始化写入 exclude_rules 表，而不是写死在 config KV 中。

默认规则覆盖：

• */Library/*
• */.git/*
• */node_modules/*
• */vendor/*
• */go/pkg/*
• */__pycache__/*
• */.venv/*
• */miniconda3/*
• */.nvm/*
• */.docker/*
• */target/*
• */dist/*
• */build/*

9. SDK Client 配置

SDK 配置应显式、可类型检查，并避免 **kwargs: Any 式透传。

建议字段：

字段	说明
base_url	API 地址
api_key	API Key
timeout	请求超时
default_tier	SDK client 自身默认 tier；未设置时使用默认选择策略
allow_remote	是否允许上传远端，应显式设置

SDK client 的配置不应在 import 时读取重依赖或启动服务。

10. 隐私与遥测

隐私配置和遥测配置必须分开。

文档隐私：

• 默认 local。
• 远端上传必须由当前请求或规则显式允许。
• API Key 存在不代表允许上传。

遥测：

• 不包含文档内容、文件名和路径。
• doclib server 是 P0 唯一 telemetry 上报主体。
• 首次启动应要求用户选择，不预选开启或关闭，用户可关闭。
• parser SDK、mineru-kit parse、mineru-kit api-server 等纯工具无 telemetry 能力。
• telemetry 配置存储在 SQLite 中，不使用启动前文件配置。
• telemetry 聚合数据也存储在 SQLite 中，flush 成功后删除已确认上报的数据。

P0 必须完成 telemetry 设计，明确字段、开关、默认值、隐私边界和上报时机。具体设计见 Telemetry 设计。

与其他文档的关系

• CLI 参数见 CLI 规格。
• CLI 配置命令见 mineru library。
• 启动前 server 配置和 SQLite config 表见 系统架构。
• API key、base_url、timeout 等 client 配置见 SDK 设计。
• 隐私默认策略见 产品路线图。
• Tier 默认语义见 解析 Tier。
• 配置相关错误见 错误码体系。

未决问题

项目级配置、用户级配置路径和正式环境变量等问题，集中维护在 开放问题清单。