Poster Agent Flow 是一个运行在 macOS 上的轻量化学术海报批处理工具。它先把 HEIC、PDF 和其他输入统一归一化为标准 PNG,再使用 Apple Vision 在本机并发完成 OCR,随后通过 LiteLLM 调用轻量模型提取论文元数据、检索论文原文、分析海报内容,最终汇总为一份中文 Markdown 报告。
项目适合处理会议现场拍摄的大批量 poster 照片,也支持 PDF 和常见图片格式。整个流程按 poster 粒度异步执行,OCR、检索和 LLM 分别控制并发;每个阶段都会写入缓存,因此中断后可 继续运行,单张 poster 失败也不会影响其他任务。
平台说明: OCR 和格式归一化依赖 Apple Vision、AppKit 与 PDFKit,因此当前版本仅 支持 macOS。原始图片只在本地处理,但 OCR 文本会发送到用户配置的模型服务。
uv sync
cp .env.example .env
mkdir -p posters outputs填写 .env 中的模型配置,把 poster 放入本地 posters/,然后执行:
uv run posterflow run ./posters -o ./outputs/poster_report.mdposters/、outputs/、.env 和所有运行缓存均已被 Git 忽略,不会随仓库发布。
最终报告为每张 poster 提供:
- 论文题目
- 经过证据约束的论文原文链接
- 2~4 句中文浓缩介绍
- 3~6 条核心 insight
- 链接匹配置信度和判断依据
- 对应的原始 poster 文件名
示例结构:
## 1. Paper Title
- Poster:`posters/example.heic`
- 原文链接:[https://arxiv.org/abs/xxxx.xxxxx](...)
- 匹配置信度:high
### 浓缩介绍
论文研究的问题、方法与主要结果。
### 核心 insight
- 核心结论一
- 核心结论二
- 核心结论三- 本地原生 OCR:使用 Apple Vision,不把原始 poster 图片上传给第三方 OCR 服务。
- 统一 PNG 输入:Apple 特有的 HEIC、PDF 页面和其他图片会先转成标准 8-bit PNG。
- 轻量 Agent:通过 LiteLLM 接入 OpenAI-compatible 或其他受支持的模型服务。
- 三级独立并发:OCR、学术检索和 LLM 调用分别设置并发上限。
- 多源论文检索:并发查询 arXiv、Semantic Scholar 和 Crossref。
- 证据约束链接:模型只能从检索候选中选择 URL,无法可靠匹配时明确留空。
- 阶段化缓存:OCR、元数据、检索候选、分析结果和最终结果分别缓存。
- 失败隔离:某张 poster 失败不会终止整个批次,重跑时只处理未完成部分。
- 人工核验入口:支持用
verified_links.json补充方法名、别名或尚未被索引的论文。
Poster 文件
│
▼
文件发现与格式过滤
│
▼
原生 PNG 格式归一化 ────────────► 标准 PNG 页面缓存
│ HEIC / PDF / JPEG / TIFF / PNG
▼
Apple Vision OCR ───────────────► OCR JSON 缓存
│ 本机运行,不上传图片
▼
LiteLLM 元数据 Agent ───────────► 题目 / 作者 / DOI / 检索词缓存
│
├────────► arXiv
├────────► Semantic Scholar 并发检索与标题相似度排序
└────────► Crossref
│
▼
候选论文证据
│
▼
LiteLLM 分析 Agent ─────────────► 浓缩介绍 / 核心 insight / 链接判断
│
▼
verified_links.json 人工核验覆盖(可选)
│
▼
稳定排序 + 原子写入
│
▼
outputs/poster_report.md
命令可以接收单个文件或目录。目录会被递归扫描,目前支持:
- PNG
- JPG / JPEG
- TIFF
- HEIC
文件按路径稳定排序,确保多次运行生成报告的顺序一致。
Python 调度器首次运行时会编译 native/PosterToPNG.m。所有输入在 OCR 前统一转换为标准
8-bit PNG:单张图片对应一个 PNG,多页 PDF 对应按顺序编号的多个 PNG。为控制磁盘占用,
图片等比例缩放且长边最大为 4,200 像素。归一化文件存放在
输入目录的 .posterflow/normalized/<文件指纹>/ 下。
这层隔离了 HEIC 等 Apple 特有格式,之后的 OCR 与调试工具只需处理通用 PNG。即便把中间 结果复制到非 Apple 环境,也可以直接查看,不再依赖 HEIC 解码能力。PNG 转换结果独立缓存, 输入文件未变化时不会重复转换。
Python 调度器首次运行时会用系统 clang 编译 native/VisionOCR.m,生成轻量原生 worker。
worker 使用 Vision 的 VNRecognizeTextRequest 识别归一化后的 PNG。
每张 poster 由独立子进程处理,Python 使用 OCR_CONCURRENCY 信号量限制同时运行的
worker 数量。OCR 完成后,文本和分页结果会写入 JSON 缓存。
这一阶段完全在本机执行,poster 图片不会因 OCR 被上传到外部服务。
OCR 文本发送给通过 LiteLLM 配置的模型。第一个轻量 Agent 以结构化 JSON 输出:
- 原始论文题目
- 作者列表
- 适合学术搜索的查询词
- poster 上可见的 URL 或 DOI
Pydantic 会校验返回结构。成功结果立即缓存,后续重跑不会重复消耗模型调用。
工作流同时查询三个公开学术索引:
- arXiv:对刚发布的预印本通常覆盖最快。
- Semantic Scholar:可提供摘要、作者、引用数、DOI 和开放 PDF。
- Crossref:用于查找 DOI 和正式出版元数据。
候选结果会按标准化标题相似度排序,并按 DOI 或标题去重。相似度低的候选可以作为分析 参考,但不会被直接当作论文原文链接。
第二个 Agent 接收 OCR 文本、抽取的元数据和检索候选,生成:
- 论文题目
- 原文链接或
null - 中文浓缩介绍
- 核心 insight 列表
- 匹配置信度
- 链接选择依据
Prompt 明确限制 paper_url 只能逐字选自检索候选;如果证据不足,必须返回 null。
这能避免模型为了填满报告而编造论文链接。
部分 poster 只展示方法名,而正式论文使用不同标题;刚录用的论文也可能尚未被学术 API 索引。此时可以在项目根目录维护:
{
"报告中的论文题目": "https://arxiv.org/abs/xxxx.xxxxx"
}先复制示例文件:
cp verified_links.example.json verified_links.json文件名为 verified_links.json。其中的链接优先于自动检索结果,并会在报告中标记为人工
核验。不要加入只凭关键词猜测的链接。真实文件默认被 Git 忽略,仓库中只提交不含真实数据
的 verified_links.example.json。
所有任务完成后,结果按 poster 文件名排序,通过临时文件和原子替换写入 Markdown。失败 项目会单独列在报告末尾,不会丢失已经成功的分析。
三级并发由独立的 asyncio.Semaphore 控制:
| 阶段 | 配置项 | 默认值 | 主要限制因素 |
|---|---|---|---|
| Vision OCR | OCR_CONCURRENCY |
4 | CPU、内存、Vision/ANE 压力 |
| LiteLLM | LLM_CONCURRENCY |
8 | 模型服务限流、费用、上下文吞吐 |
| 学术检索 | SEARCH_CONCURRENCY |
8 | 公共 API 限流和网络连接数 |
每个 poster 都是一个异步任务,但只有进入对应阶段时才占用该阶段的信号量。因此慢速 OCR 不会阻塞已经完成 OCR 的 poster 进入 LLM 和检索阶段,形成异步流水线并行。
推荐从以下配置开始:
OCR_CONCURRENCY=4
LLM_CONCURRENCY=8
SEARCH_CONCURRENCY=8如果 Mac 内存压力较大,将 OCR 并发降至 2;如果模型端出现 429 或超时,降低 LLM 并发。
默认缓存目录位于输入目录下:
posters/.posterflow/
├── bin/ # 编译后的 Vision OCR worker
├── clang-module-cache/ # Objective-C 编译缓存
├── normalized/ # 按文件指纹缓存的标准 PNG 页面
└── cache/
├── *.normalized_png_v2.json
├── *.ocr_png_v2.json
├── *.metadata.json
├── *.search_v2.json
├── *.analysis.json
└── *.final_v3.json
缓存键由绝对路径、文件大小和修改时间生成。修改 poster 后会自动得到新的缓存键;未修改的 文件会直接复用已完成阶段。
普通重跑:
uv run posterflow run ./posters -o ./outputs/poster_report.md会跳过已完成的任务,只重试失败或缺少缓存的阶段。需要完全忽略缓存时使用:
uv run posterflow run ./posters -o ./outputs/poster_report.md --force--force 会重新进行 OCR 和模型调用,可能产生额外费用。
- macOS 13 或更高版本
- Xcode Command Line Tools(提供
clang和 macOS SDK) - Python 3.11+
- uv
- 一个 LiteLLM 支持的模型服务
安装 Command Line Tools:
xcode-select --install安装 uv:
curl -LsSf https://astral.sh/uv/install.sh | shgit clone <repository-url>
cd poster-agent-flow
uv sync
cp .env.example .envuv sync 会根据 uv.lock 创建隔离虚拟环境并安装锁定版本。
也可以构建本地 wheel 和源码包:
uv build构建配置会把 native/ 下的 Objective-C worker 源码一并放入 wheel;用户安装后首次运行时
仍由本机 clang 针对当前 macOS 编译。
编辑 .env:
# LiteLLM 模型名称
LITELLM_MODEL=
# 模型服务凭证
LITELLM_API_KEY=
LITELLM_API_BASE=
# 可选:提高 Semantic Scholar 限额
SEMANTIC_SCHOLAR_API_KEY=
# 并发设置
OCR_CONCURRENCY=4
LLM_CONCURRENCY=8
SEARCH_CONCURRENCY=8
# OCR 语言,逗号分隔
OCR_LANGUAGES=en-US,zh-Hans
LLM_TEMPERATURE=0.1
HTTP_TIMEOUT_SECONDS=30如果配置了 LITELLM_API_BASE,可以填写裸模型名:
LITELLM_MODEL=deepseek-v4-pro
LITELLM_API_KEY=
LITELLM_API_BASE=https://example.com/v1程序会自动按 openai/deepseek-v4-pro 路由给 LiteLLM。
使用 LiteLLM 已知 Provider 时,保留明确前缀:
LITELLM_MODEL=anthropic/claude-sonnet-4-5程序不会修改已经包含 / 的模型名。
将 poster 放入 posters/,执行:
uv run posterflow run ./posters \
--output ./outputs/poster_report.md用于在调用模型前检查识别质量:
uv run posterflow ocr ./posters \
--output-dir ./outputs/ocr每张 poster 会生成一份独立的 .ocr.json。
uv run posterflow run ./posters \
--cache-dir ./work/cache \
--output ./outputs/poster_report.mdOCR_CONCURRENCY=2 LLM_CONCURRENCY=4 SEARCH_CONCURRENCY=6 \
uv run posterflow run ./posters -o ./outputs/poster_report.md- 原始 poster 文件只由本机 Apple Vision OCR 读取。
- OCR 文本会发送到
.env中配置的 LiteLLM 模型服务。 - 论文题目和检索词会发送到 arXiv、Semantic Scholar 和 Crossref。
.env已被.gitignore排除,不应提交 API Key。- OCR 缓存和阶段缓存默认位于 poster 目录下的
.posterflow,也已被忽略。 posters/、outputs/、work/和人工核验结果均不会进入 Git。.env.example和verified_links.example.json只包含空值或虚构示例,可以安全提交。
处理未公开、受保密协议约束或包含个人敏感信息的 poster 前,请先确认所配置模型服务的 数据政策,或只运行本地 OCR 命令。
poster-agent-flow/
├── native/
│ ├── VisionOCR.m # Apple Vision 原生 OCR worker
│ └── PosterToPNG.m # HEIC/PDF/图片统一转标准 PNG
├── src/posterflow/
│ ├── agent.py # LiteLLM 结构化元数据与分析 Agent
│ ├── cache.py # 文件指纹和 JSON 阶段缓存
│ ├── cli.py # Typer 命令行入口
│ ├── config.py # 环境配置和 poster 文件发现
│ ├── models.py # Pydantic 数据模型
│ ├── ocr.py # 原生 worker 编译与异步子进程调度
│ ├── pipeline.py # 全流程异步编排、失败隔离和续跑
│ ├── report.py # Markdown 报告渲染和原子写入
│ └── search.py # arXiv / Semantic Scholar / Crossref 检索
├── tests/ # 单元测试
├── posters/ # poster 输入目录(示例约定)
├── outputs/ # OCR 与最终报告输出
├── verified_links.example.json # 可提交的人工核验模板
├── LICENSE # MIT License
├── .env.example # 配置模板
├── pyproject.toml # uv/Python 项目配置
└── uv.lock # 锁定依赖
uv sync
uv run ruff check .
uv run pytest -q查看 CLI 帮助:
uv run posterflow --help
uv run posterflow run --help
uv run posterflow ocr --help仓库通过 .gitignore 默认排除以下内容:
.env、各种环境变体、私钥和凭证文件posters/、inputs/中的原始数据outputs/、reports/、work/中的报告和中间产物.posterflow/中的 PNG、OCR、检索和 Agent 缓存.venv/、Python 缓存、测试缓存和本地编译产物- 用户数据对应的
verified_links.json
首次发布或每次加入新文件后,建议执行:
# 查看 Git 准备提交的文件
git status --short
# 检查所有未忽略文件;列表中不应出现 poster、报告或 .env
git ls-files --cached --others --exclude-standard
# 验证关键路径确实被忽略
git check-ignore -v .env posters/example.heic outputs/poster_report.md \
work/debug.png posters/.posterflow/cache/example.ocr.json verified_links.json
# 代码质量
uv run ruff check .
uv run pytest -q注意:.gitignore 不能自动移除已经被 Git 跟踪的敏感文件。如果某个文件曾被 git add,
需要先执行 git rm --cached <path>,再检查提交历史中是否包含密钥或私有数据。已经公开的
密钥必须立即吊销和轮换,仅从最新提交删除是不够的。
本项目采用 MIT License。可以自由使用、修改和分发,但需保留许可证和版权声明。
项目直接调用 Apple Vision,因此需要把 Objective-C worker 编译成当前 Mac 可执行文件。编译 只在 worker 不存在或源码更新时发生,产物会被缓存。
这表示检索结果与 poster 标题不够一致,或者论文尚未被公共学术索引收录。工作流有意保守
处理链接,避免把相似论文误认为原文。可以在人工确认后加入 verified_links.json。
每张 poster 都有独立异常边界。批量任务最重要的是保留已完成结果,因此单个网络请求、 模型格式或图片问题不会取消其他任务。报告末尾会列出失败原因。
Python 虚拟环境中的脚本可能记录绝对路径。移动项目后重新创建即可:
mv .venv /tmp/poster-agent-flow-old-venv
uv sync- 先运行
posterflow ocr检查 OCR 质量。 - 使用小型、支持 JSON 输出的模型。
- 不要无必要地使用
--force。 - 保留
.posterflow/cache,失败后直接重跑。 - 根据服务限额适当降低
LLM_CONCURRENCY。