# 配置文件说明

## 概述

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. 所有配置项都是可选的，未指定的项将使用默认值

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

### 方法 2：使用 JSON 格式

1. 复制 `config.json.example` 为 `config.json`
2. 根据需要修改配置项

```bash
cp pdf_converter_v2/config.json.example pdf_converter_v2/config.json
```

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

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

```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 格式示例

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

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

# 启用图片返回
return_images: true

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

### JSON 格式示例

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

## 依赖说明

### YAML 格式支持

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

```bash
pip install pyyaml
```

### JSON 格式支持

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

## 配置优先级

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

## 注意事项

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

## 示例：快速开始

1. 复制默认配置文件：
```bash
cd pdf_converter_v2
# YAML格式（已存在）
# 或者使用 JSON 格式
cp config.json.example config.json
```

2. 修改配置（例如修改 API 地址）：
```bash
# 编辑 config.yaml
vim config.yaml

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

3. 启动服务：
```bash
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 验证工具检查语法

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

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

```python
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` |

3. **删除 `.env` 文件**（如果有）
4. **重启服务**

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