# paddlevl-api

**Repository Path**: lidonghuigitee/paddlevl-api

## Basic Information

- **Project Name**: paddlevl-api
- **Description**: 本项目是 PaddleVL 的 API 转发代理服务，将请求转发到后端 Docker 容器中的 PaddleVL OCR 服务。
- **Primary Language**: Python
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 1
- **Created**: 2026-04-14
- **Last Updated**: 2026-04-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# PaddleVL API 代理服务

## 项目概述

本项目是 PaddleVL 的 API 转发代理服务，将请求转发到后端 Docker 容器中的 PaddleVL OCR 服务。

**架构说明**：
```
客户端 -> minimal_api.py (Flask代理, 端口5000) -> Docker容器 (PaddleVL服务, 端口8080)
```

## 目录结构

```
paddlevl_api/
├── install/            # 安装相关文件
│   ├── docker/         # Docker 配置文件
│   │   ├── .env        # 环境变量配置
│   │   └── compose.yaml # Docker Compose 配置
│   ├── deploy_fixed_port.sh     # 固定端口部署脚本
│   ├── deploy_paddlevl_docker.sh # Docker 部署脚本
│   ├── quick_test_paddlevl.sh   # 快速测试脚本
│   └── start_api.sh             # API 启动脚本
├── example/            # 示例代码
│   ├── simple_client.py # 简单客户端示例（推荐）
│   ├── paddlevl.py     # PaddleVL引擎实现（依赖外部模块）
│   └── best_practice.py # 最佳调用示例（依赖外部模块）
├── minimal_api.py      # 主API代理服务（转发到Docker）
├── mock_api.py         # 模拟API（用于测试）
├── simple_api.py       # 简单API实现
├── test_paddlevl_api.py # API测试脚本
├── requirements.txt    # Python依赖
└── README.md           # 项目说明文档
```

## 安装与部署

### 1. 依赖安装

```bash
pip install -r requirements.txt
```

### 2. Docker 部署（后端服务）

1. 进入 install 目录：
   ```bash
   cd install
   ```

2. 运行部署脚本：
   ```bash
   bash deploy_paddlevl_docker.sh
   ```

3. 或使用固定端口部署：
   ```bash
   bash deploy_fixed_port.sh
   ```

### 3. 启动 API 代理服务

```bash
# 方式一：使用启动脚本
cd install
bash start_api.sh

# 方式二：直接运行
python minimal_api.py
```

## API 接口

### 接口列表

| 接口 | 方法 | 说明 |
|------|------|------|
| `/api/v1/file_parse` | POST | 文件解析接口 |
| `/api/v1/health` | GET | 健康检查 |

### 文件解析接口

**请求**：
```bash
curl -X POST http://localhost:5000/api/v1/file_parse \
  -F "file=@document.pdf"
```

**响应**：
```json
{
  "success": true,
  "code": 200,
  "message": "File processed",
  "data": {
    "filename": "document.pdf",
    "pages": 1,
    "md_content": "# OCR识别结果...",
    "processing_time_ms": 1036,
    "mode": "paddleocr_vl_0.9b"
  }
}
```

### 支持的文件格式

- PDF: `.pdf`
- 图片: `.png`, `.jpg`, `.jpeg`, `.bmp`, `.tiff`, `.tif`, `.gif`

## 快速测试

```bash
# 健康检查
curl http://192.168.80.143:5000/api/v1/health

# 文件上传测试
curl -X POST http://192.168.80.143:5000/api/v1/file_parse -F "file=@test_pillow.png"
```

## 调用示例

### 方式一：使用简单客户端（推荐）

`example/simple_client.py` 是一个独立的客户端示例，无需外部依赖，可直接运行：

```python
from example.simple_client import PaddleVLClient

# 创建客户端
client = PaddleVLClient(base_url="http://192.168.80.143:5000")

# 健康检查
if client.health_check():
    print("服务正常")

# 处理文件
result = client.process_file("input.pdf", "output.md")
if result.success:
    print(result.content)
```

运行验证：
```bash
python example/simple_client.py
```

### 方式二：使用完整引擎（需要外部依赖）

`example/paddlevl.py` 和 `example/best_practice.py` 依赖 `scripts.engines.base` 模块，适用于集成到已有项目中。

## 验证 API 正常工作

### 1. 健康检查
```bash
curl http://192.168.80.143:5000/api/v1/health
```
预期响应：
```json
{"code":200,"data":{"docker_service_available":true},"message":"Service running","success":true}
```

### 2. 文件上传测试
```bash
curl -X POST http://192.168.80.143:5000/api/v1/file_parse -F "file=@test_pillow.png"
```
预期响应包含 `md_content` 字段。

### 3. Python 客户端测试
```bash
python example/simple_client.py
```

## 注意事项

- 确保 Docker 容器已启动并运行在端口 8080
- API 代理服务默认运行在端口 5000
- 最大文件上传限制：100MB
- 请求超时时间：300秒

## 维护与更新

- 定期更新 Docker 镜像以获取最新功能
- 根据实际需求调整代理服务配置
- 保持文档与代码同步更新