add docs
This commit is contained in:
@@ -2,82 +2,177 @@
|
||||
|
||||
一个精简版图片/PDF 转 Markdown 服务，核心依赖 `openocr-python==0.1.5`，保留文档解析能力，去掉训练、评测和实验脚本。
|
||||
|
||||
**工作流**：Windows 本地编写代码 → Git 推送 → Ubuntu 服务器 Docker 运行。
|
||||
|
||||
## 功能
|
||||
|
||||
- `POST /api/recognize`：上传图片或 PDF，生成 Markdown 和 JSON。
|
||||
- `GET /api/history`：查看已解析文件列表。
|
||||
- `GET /output/...`：访问生成的 Markdown、JSON 和原始文件。
|
||||
- `openocr-md`：命令行直接解析单个图片/PDF。
|
||||
- `POST /api/recognize`：上传图片或 PDF，生成 Markdown 和 JSON
|
||||
- `GET /api/history`：查看已解析文件列表
|
||||
- `GET /output/...`：访问生成的 Markdown、JSON 和原始文件
|
||||
- `GET /health`：健康检查
|
||||
- `GET /docs`：Swagger API 文档
|
||||
|
||||
## 本地运行
|
||||
---
|
||||
|
||||
## 服务器首次初始化（Ubuntu）
|
||||
|
||||
### 1. 克隆代码与创建目录
|
||||
|
||||
```bash
|
||||
python -m venv .venv
|
||||
source .venv/bin/activate
|
||||
pip install -e .
|
||||
cp .env.example .env
|
||||
uvicorn openocr_markdown.api:app --host 0.0.0.0 --port 8000
|
||||
cd ~
|
||||
git clone <你的仓库地址> OpenOCR
|
||||
cd OpenOCR
|
||||
mkdir -p data/output data/uploads
|
||||
```
|
||||
|
||||
Windows PowerShell:
|
||||
|
||||
```powershell
|
||||
python -m venv .venv
|
||||
.\.venv\Scripts\Activate.ps1
|
||||
pip install -e .
|
||||
Copy-Item .env.example .env
|
||||
uvicorn openocr_markdown.api:app --host 0.0.0.0 --port 8000
|
||||
```
|
||||
|
||||
首次运行会自动下载 OpenOCR 所需模型，耗时取决于网络和机器性能。
|
||||
|
||||
## API 示例
|
||||
|
||||
```bash
|
||||
curl -F "file=@examples/page.png" http://127.0.0.1:8000/api/recognize
|
||||
curl http://127.0.0.1:8000/api/history
|
||||
```
|
||||
|
||||
重复上传同名文件默认复用已有结果；需要重新识别时增加 `force=true`：
|
||||
|
||||
```bash
|
||||
curl -F "file=@examples/page.png" -F "force=true" http://127.0.0.1:8000/api/recognize
|
||||
```
|
||||
|
||||
## 命令行
|
||||
|
||||
```bash
|
||||
openocr-md path/to/document.pdf --output-dir data/output
|
||||
```
|
||||
|
||||
## Docker 部署
|
||||
### 2. 生成并配置环境变量
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
服务启动后访问：
|
||||
|
||||
- API 文档：`http://服务器IP:8000/docs`
|
||||
- 健康检查：`http://服务器IP:8000/health`
|
||||
- 输出文件：`http://服务器IP:8000/output/...`
|
||||
|
||||
## 关键配置
|
||||
|
||||
通过 `.env` 或服务器环境变量配置：
|
||||
纯 Docker 部署时，重点确认以下配置：
|
||||
|
||||
```env
|
||||
OPENOCR_OUTPUT_DIR=data/output
|
||||
OPENOCR_UPLOAD_DIR=data/uploads
|
||||
OPENOCR_USE_GPU=false
|
||||
OPENOCR_AUTO_DOWNLOAD=true
|
||||
OPENOCR_LAYOUT_THRESHOLD=0.4
|
||||
OPENOCR_MAX_LENGTH=2048
|
||||
OPENOCR_AUTO_DOWNLOAD=true # 首次运行让容器自动下载模型
|
||||
OPENOCR_USE_GPU=false # 未配置 NVIDIA Docker 插件前保持 false
|
||||
OPENOCR_CORS_ORIGINS=*
|
||||
```
|
||||
|
||||
如果远程服务器有 GPU，可以先安装带 GPU 的运行环境，再把 `OPENOCR_USE_GPU=true`。当前 Dockerfile 默认是 CPU 版，适合先验证完整链路。
|
||||
完整配置项见 `.env.example`。
|
||||
|
||||
### 3. 一键编译并启动容器
|
||||
|
||||
```bash
|
||||
docker compose up -d --build
|
||||
```
|
||||
|
||||
### 4. 跟踪模型下载进度
|
||||
|
||||
模型体积较大，容器启动后会在后台自动下载。**此时不要急着调用接口**，先查看日志：
|
||||
|
||||
```bash
|
||||
docker compose logs -f
|
||||
```
|
||||
|
||||
首次下载可能需要 **5～30 分钟**（取决于网络）。当日志出现 `Application startup complete.` 且无报错时，说明模型加载完成，按 `Ctrl + C` 退出日志跟踪。
|
||||
|
||||
---
|
||||
|
||||
## 健康检查与验证
|
||||
|
||||
### 服务器本地
|
||||
|
||||
```bash
|
||||
curl http://127.0.0.1:8000/health
|
||||
# 期望返回: {"status":"ok"}
|
||||
```
|
||||
|
||||
### Windows 本地浏览器
|
||||
|
||||
将 `服务器IP` 替换为实际地址：
|
||||
|
||||
- API 文档：`http://服务器IP:8000/docs`
|
||||
- 健康检查：`http://服务器IP:8000/health`
|
||||
|
||||
若无法访问，请在云服务器安全组中放行 **8000** 端口。
|
||||
|
||||
### API 调用示例
|
||||
|
||||
```bash
|
||||
# 上传图片/PDF 进行解析
|
||||
curl -F "file=@/path/to/page.png" http://127.0.0.1:8000/api/recognize
|
||||
|
||||
# 查看历史记录
|
||||
curl http://127.0.0.1:8000/api/history
|
||||
|
||||
# 强制重新识别（同名文件默认复用已有结果）
|
||||
curl -F "file=@/path/to/page.png" -F "force=true" http://127.0.0.1:8000/api/recognize
|
||||
```
|
||||
|
||||
成功响应示例：
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "page",
|
||||
"status": "success",
|
||||
"message": "Parsed successfully in 12.34s.",
|
||||
"markdown_url": "/output/page/page.md",
|
||||
"json_url": "/output/page/page.json"
|
||||
}
|
||||
```
|
||||
|
||||
Markdown 访问地址：`http://服务器IP:8000/output/<文档名>/<文档名>.md`
|
||||
|
||||
---
|
||||
|
||||
## 日常开发与更新
|
||||
|
||||
### Windows 本地
|
||||
|
||||
改完代码后推送到远程仓库：
|
||||
|
||||
```powershell
|
||||
# 若已配置 git 快捷别名
|
||||
gpush "feat: 优化 OCR 的 Markdown 布局解析器"
|
||||
|
||||
# 或标准命令
|
||||
git add .
|
||||
git commit -m "feat: 优化 OCR 的 Markdown 布局解析器"
|
||||
git push
|
||||
```
|
||||
|
||||
### Ubuntu 服务器
|
||||
|
||||
```bash
|
||||
cd ~/OpenOCR
|
||||
git pull && docker compose up -d --build
|
||||
```
|
||||
|
||||
`docker compose up -d --build` 会检测代码变更并重新构建 API 容器、平滑重启服务。缓存在数据卷中的模型文件和 `data/` 目录下的解析结果不会丢失。
|
||||
|
||||
---
|
||||
|
||||
## 日常排错与手动测试
|
||||
|
||||
### 查看日志
|
||||
|
||||
```bash
|
||||
docker compose logs -f openocr-markdown
|
||||
```
|
||||
|
||||
### 命令行手动解析（不经过 API）
|
||||
|
||||
```bash
|
||||
docker compose exec openocr-markdown openocr-md /app/data/uploads/test.pdf --output-dir /app/data/output
|
||||
```
|
||||
|
||||
### 常用运维命令
|
||||
|
||||
```bash
|
||||
docker compose ps # 查看容器状态
|
||||
docker compose down # 停止服务
|
||||
docker compose up -d --build # 重新构建并启动
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 关键配置
|
||||
|
||||
通过 `.env` 或环境变量配置：
|
||||
|
||||
| 变量 | 默认值 | 说明 |
|
||||
|------|--------|------|
|
||||
| `OPENOCR_OUTPUT_DIR` | `data/output` | 解析结果输出目录 |
|
||||
| `OPENOCR_UPLOAD_DIR` | `data/uploads` | 上传文件临时目录 |
|
||||
| `OPENOCR_USE_GPU` | `false` | 是否使用 GPU |
|
||||
| `OPENOCR_AUTO_DOWNLOAD` | `true` | 首次运行自动下载模型 |
|
||||
| `OPENOCR_LAYOUT_THRESHOLD` | `0.4` | 版面分析阈值 |
|
||||
| `OPENOCR_MAX_LENGTH` | `2048` | 识别最大长度 |
|
||||
| `OPENOCR_CORS_ORIGINS` | `*` | 跨域来源，多个用逗号分隔 |
|
||||
| `OPENOCR_LOG_LEVEL` | `info` | 日志级别 |
|
||||
|
||||
---
|
||||
|
||||
## 项目结构
|
||||
|
||||
@@ -95,3 +190,9 @@ OPENOCR_CORS_ORIGINS=*
|
||||
├── pyproject.toml
|
||||
└── .env.example
|
||||
```
|
||||
|
||||
## 注意事项
|
||||
|
||||
- `.env`、`data/`、模型缓存目录已在 `.gitignore` 中排除，不会进入 Git
|
||||
- 首次启动耗时较长属于正常现象，等待模型下载完成后再调用接口
|
||||
- 生产环境建议在 Docker 前加 Nginx 反向代理并配置 HTTPS
|
||||
|
||||
Reference in New Issue
Block a user