Clerk2.5/pdf_converter_v2/CONFIG.md

配置文件说明

概述

PDF Converter v2 支持使用配置文件来管理所有配置项，不再依赖环境变量或 .env 文件。

配置文件格式

支持以下三种格式：

1. YAML 格式（推荐）：config.yaml 或 config.yml
2. JSON 格式：config.json

配置文件应放置在 pdf_converter_v2 目录下。

配置文件查找顺序

程序会按以下顺序自动查找配置文件：

1. pdf_converter_v2/config.yaml
2. pdf_converter_v2/config.yml
3. pdf_converter_v2/config.json

找到第一个存在的配置文件后，将使用该文件的配置。

使用方法

方法 1：使用 YAML 格式（推荐）

1. 将 config.yaml 复制并根据需要修改配置项

2. 所有配置项都是可选的，未指定的项将使用默认值

   # 查看默认配置文件
   cat pdf_converter_v2/config.yaml
   

方法 2：使用 JSON 格式

1. 复制 config.json.example 为 config.json

2. 根据需要修改配置项

   cp pdf_converter_v2/config.json.example pdf_converter_v2/config.json
   

方法 3：指定自定义配置文件（程序中）

在 Python 代码中指定配置文件路径：

from pdf_converter_v2.config_loader import reload_config

# 重新加载指定的配置文件
reload_config("/path/to/your/config.yaml")

配置项说明

设备环境配置

配置项	类型	默认值	说明
device_kind	string	自动检测	设备类型：nvi（NVIDIA GPU）/ npu（华为昇腾）/ cpu

模型配置

配置项	类型	默认值	说明
default_model_name	string	OpenDataLab/MinerU2.5-2509-1.2B	默认模型名称
default_gpu_memory_utilization	float	0.9	GPU 内存利用率（0.0-1.0）
default_dpi	int	200	DPI 设置
default_max_pages	int	10	最大页数限制

API 配置

配置项	类型	默认值	说明
api_url	string	http://127.0.0.1:5282	MinerU API 服务地址
backend	string	vlm-vllm-async-engine	处理后端：vlm-vllm-async-engine / pipeline
parse_method	string	auto	解析方法：auto / txt / ocr
start_page_id	int	0	起始页ID（从0开始）
end_page_id	int	99999	结束页ID
language	string	ch	识别语言：ch / en
server_url	string	string	服务器URL

返回格式配置

配置项	类型	默认值	说明
response_format_zip	bool	true	是否返回 ZIP 格式
return_middle_json	bool	false	是否返回中间 JSON
return_model_output	bool	true	是否返回模型输出
return_md	bool	true	是否返回 Markdown
return_images	bool	false	是否返回图片
return_content_list	bool	false	是否返回内容列表

日志配置

配置项	类型	默认值	说明
log_dir	string	./logs	日志目录
log_level	string	INFO	日志级别：DEBUG / INFO / WARNING / ERROR
log_to_file	bool	true	是否记录到文件
log_to_console	bool	true	是否输出到控制台

配置示例

YAML 格式示例

# 修改 API 地址
api_url: "http://192.168.1.100:5282"

# 修改语言为英文
language: "en"

# 启用图片返回
return_images: true

# 修改日志级别
log_level: "DEBUG"

JSON 格式示例

{
  "api_url": "http://192.168.1.100:5282",
  "language": "en",
  "return_images": true,
  "log_level": "DEBUG"
}

依赖说明

YAML 格式支持

如果使用 YAML 格式的配置文件，需要安装 PyYAML：

pip install pyyaml

JSON 格式支持

JSON 格式使用 Python 标准库，无需额外安装依赖。

配置优先级

1. 程序会按照查找顺序使用第一个找到的配置文件
2. 配置文件中未指定的项将使用默认值
3. 所有配置项都是可选的，可以只配置需要修改的项

注意事项

1. 完全移除了环境变量依赖：不再读取任何环境变量
2. 配置文件优先：所有配置都从配置文件读取
3. 向后兼容：如果没有配置文件，将使用合理的默认值
4. 类型安全：配置加载器会自动进行类型转换和验证

示例：快速开始

1. 复制默认配置文件：

   cd pdf_converter_v2
   # YAML格式（已存在）
   # 或者使用 JSON 格式
   cp config.json.example config.json
   

2. 修改配置（例如修改 API 地址）：

   # 编辑 config.yaml
   vim config.yaml
   
   # 或编辑 config.json
   vim config.json
   

3. 启动服务：

   python -m pdf_converter_v2.api_server
   # 或
   uvicorn pdf_converter_v2.api.main:app --host 0.0.0.0 --port 8000
   

配置会自动加载，无需任何额外操作！

故障排除

问题：配置文件未生效

解决方法：

1. 确认配置文件路径正确（在 pdf_converter_v2/ 目录下）
2. 检查配置文件格式是否正确（YAML 或 JSON）
3. 查看日志输出，确认配置文件是否被正确加载

问题：YAML 文件报错

解决方法：

1. 确保已安装 PyYAML：pip install pyyaml
2. 检查 YAML 语法是否正确（缩进、冒号、引号等）
3. 可以使用在线 YAML 验证工具检查语法

问题：想要使用多个配置文件

解决方法： 可以通过程序代码指定不同的配置文件：

from pdf_converter_v2.config_loader import reload_config

# 开发环境
reload_config("config.dev.yaml")

# 生产环境
reload_config("config.prod.yaml")

迁移指南

从环境变量迁移到配置文件

如果之前使用环境变量，现在迁移到配置文件很简单：

1. 创建配置文件：复制 config.yaml 或 config.json.example
2. 映射环境变量：将环境变量映射到配置文件项

例如：

旧环境变量	新配置项
API_URL	api_url
BACKEND	backend
LANGUAGE	language
LOG_LEVEL	log_level

1. 删除 .env 文件（如果有）
2. 重启服务

完成！现在配置完全由配置文件管理。