超长文档截图往往超过视觉模型的输入限制，高像素表格又容易触发内存溢出、切断单元格或打乱阅读顺序。AFAC 在调用文档解析服务前先理解图像类型与布局，再选择对应处理链：
- 长图通道：带重叠的纵向切片、并发解析、字符与表格级去重。
- 高像素通道：轻量分类、YOLO 表格定位、网格线感知切片、跨块表格重建。
- 工程可靠性：Unicode 路径支持、失败重试、账号轮询、批处理断点续跑、稳定 CSV 输出。
- 轻量本地模型：内置二分类权重和表格检测权重；大模型能力由 FinixDoc 兼容 API 提供。
flowchart LR
A[文档图片] --> B[轻量图像分类]
B -->|超长图| C[重叠纵向切片]
B -->|高像素图| D[YOLO 表格定位]
D --> E[网格线 / 安全切线规划]
C --> F[FinixDoc API 并发解析]
E --> F
F --> G[重叠去重与表格重组]
G --> H[Markdown / CSV]
所有 API 凭据仅从环境变量读取。仓库不包含有效密钥、用户 ID、比赛数据集或提交结果。
建议使用 Python 3.10–3.12 和独立虚拟环境。
git clone https://github.com/neflibata-feng/AFAC-OpenSource.git
cd AFAC-OpenSource
python -m venv .venv
# Linux / macOS
source .venv/bin/activate
# Windows PowerShell
# .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .PyTorch 在不同硬件平台上的安装方式可能不同。如需专用 CUDA 版本，请先按照 PyTorch 官方安装说明 安装 PyTorch，再执行上述命令。
向 FinixDoc 兼容服务的运营方申请凭据，并在当前终端设置：
# Linux / macOS
export FINIX_API_KEY="your-api-key"
export FINIX_USER_IDS="user-id-1,user-id-2"# Windows PowerShell
$env:FINIX_API_KEY = "your-api-key"
$env:FINIX_USER_IDS = "user-id-1,user-id-2"可选配置：
| 环境变量 | 默认值 | 说明 |
|---|---|---|
FINIX_API_URL |
FinixDoc 官方接口 | 兼容服务地址 |
AFAC_MAX_WORKERS |
10 |
最大并发 API 请求数 |
请勿把真实凭据写入代码、.env.example、Issue 或日志。项目会忽略本地 .env 文件，但不会自动加载它。
解析单张图片并写入 Markdown：
afac document.png --output result.md批量解析目录并生成 file_name,ground_truth 格式的 CSV：
afac ./images --output results.csv递归扫描并从已有结果继续：
afac ./images --recursive --resume --output results.csv --workers 8也可以不安装命令行入口：
python -m afac document.png -o result.mdfrom afac import process
markdown = process("document.png")
print(markdown)process() 会在系统临时目录创建切片，并在正常结束后清理。解析服务失败时返回空结果；输入、模型或配置错误会抛出明确异常。
AFAC-OpenSource/
├── src/afac/
│ ├── models/ # 轻量分类器与表格检测权重
│ ├── cv/ # 裁边、网格线检测、安全切线
│ ├── perception/ # 图像分类、密度与表格感知
│ ├── planner/ # 长图与网格切片规划
│ ├── dedup/ # 相邻块去重
│ ├── merger/ # Markdown 与表格重组
│ ├── client.py # FinixDoc 兼容 API 客户端
│ ├── pipeline.py # 自适应解析主流程
│ └── cli.py # 单图与批量命令行入口
├── tests/
├── pyproject.toml
└── LICENSE
发布包包含项目最终版训练得到的两个轻量模型：
| 文件 | 用途 | 大小 | SHA-256 |
|---|---|---|---|
classifier.pth |
长图 / 高像素图二分类 | 2.2 MB | 67f7afec5a3c6f77b146f85cf09db669c05a27c3aa2c2036d5116a850aecc90c |
yolo.pt |
表格区域检测 | 20.5 MB | 77c6fe78d0923e40a526228ea607f344a3209cd360f1c2bd18a9bd9554bfd4fa |
模型默认在 CPU 上运行。首次加载 Ultralytics 时，其上游库可能在用户配置目录创建自身设置文件。
python -m pip install -e ".[dev]"
pytest
ruff check src tests
python -m build测试不调用真实 API，也不需要有效凭据。提交代码前请同时运行测试、静态检查和构建。
- AFAC 不是独立 OCR/VLM；完整解析需要有权限访问的 FinixDoc 兼容服务。
- 输入质量、版面复杂度和上游服务响应会影响最终 Markdown。
- 批处理 CSV 使用图片 basename 作为
file_name；递归目录中不允许出现同名图片。 - 仓库未包含训练/比赛数据集，请确保自行使用的数据和服务符合其授权条款。
欢迎提交 Issue 和 Pull Request。开始前请阅读 贡献指南 和 安全策略。行为变更应包含测试，任何日志和测试夹具都不得携带真实文档、凭据或用户信息。
本项目整体按 GNU Affero General Public License v3.0 发布，包括源代码与随附模型权重。修改、分发或通过网络提供本项目服务时，请遵守 AGPL-3.0 的源代码开放义务。需要闭源集成或无法满足 AGPL-3.0 的场景，应另行取得相关权利方授权，详见 第三方声明。
感谢 FinixDoc 文档解析能力与 Ultralytics、PyTorch、OpenCV 等开源生态为本项目提供基础支持。