Skip to content

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Poster Agent Flow

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.md

posters/、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

1. 文件发现

命令可以接收单个文件或目录。目录会被递归扫描,目前支持:

  • PDF
  • PNG
  • JPG / JPEG
  • TIFF
  • HEIC

文件按路径稳定排序,确保多次运行生成报告的顺序一致。

2. PNG 格式归一化

Python 调度器首次运行时会编译 native/PosterToPNG.m。所有输入在 OCR 前统一转换为标准 8-bit PNG:单张图片对应一个 PNG,多页 PDF 对应按顺序编号的多个 PNG。为控制磁盘占用, 图片等比例缩放且长边最大为 4,200 像素。归一化文件存放在 输入目录的 .posterflow/normalized/<文件指纹>/ 下。

这层隔离了 HEIC 等 Apple 特有格式,之后的 OCR 与调试工具只需处理通用 PNG。即便把中间 结果复制到非 Apple 环境,也可以直接查看,不再依赖 HEIC 解码能力。PNG 转换结果独立缓存, 输入文件未变化时不会重复转换。

3. macOS Vision OCR

Python 调度器首次运行时会用系统 clang 编译 native/VisionOCR.m,生成轻量原生 worker。 worker 使用 Vision 的 VNRecognizeTextRequest 识别归一化后的 PNG。

每张 poster 由独立子进程处理,Python 使用 OCR_CONCURRENCY 信号量限制同时运行的 worker 数量。OCR 完成后,文本和分页结果会写入 JSON 缓存。

这一阶段完全在本机执行,poster 图片不会因 OCR 被上传到外部服务。

4. 元数据 Agent

OCR 文本发送给通过 LiteLLM 配置的模型。第一个轻量 Agent 以结构化 JSON 输出:

  • 原始论文题目
  • 作者列表
  • 适合学术搜索的查询词
  • poster 上可见的 URL 或 DOI

Pydantic 会校验返回结构。成功结果立即缓存,后续重跑不会重复消耗模型调用。

5. 并发检索原文

工作流同时查询三个公开学术索引:

  • arXiv:对刚发布的预印本通常覆盖最快。
  • Semantic Scholar:可提供摘要、作者、引用数、DOI 和开放 PDF。
  • Crossref:用于查找 DOI 和正式出版元数据。

候选结果会按标准化标题相似度排序,并按 DOI 或标题去重。相似度低的候选可以作为分析 参考,但不会被直接当作论文原文链接。

6. 分析 Agent

第二个 Agent 接收 OCR 文本、抽取的元数据和检索候选,生成:

  • 论文题目
  • 原文链接或 null
  • 中文浓缩介绍
  • 核心 insight 列表
  • 匹配置信度
  • 链接选择依据

Prompt 明确限制 paper_url 只能逐字选自检索候选;如果证据不足,必须返回 null。 这能避免模型为了填满报告而编造论文链接。

7. 人工核验链接

部分 poster 只展示方法名,而正式论文使用不同标题;刚录用的论文也可能尚未被学术 API 索引。此时可以在项目根目录维护:

{
  "报告中的论文题目": "https://arxiv.org/abs/xxxx.xxxxx"
}

先复制示例文件:

cp verified_links.example.json verified_links.json

文件名为 verified_links.json。其中的链接优先于自动检索结果,并会在报告中标记为人工 核验。不要加入只凭关键词猜测的链接。真实文件默认被 Git 忽略,仓库中只提交不含真实数据 的 verified_links.example.json。

8. 报告汇总

所有任务完成后,结果按 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 | sh

安装项目

git clone <repository-url>
cd poster-agent-flow
uv sync
cp .env.example .env

uv 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

OpenAI-compatible 自定义服务

如果配置了 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 已知 Provider 时,保留明确前缀:

LITELLM_MODEL=anthropic/claude-sonnet-4-5

程序不会修改已经包含 / 的模型名。

使用方法

完整处理

将 poster 放入 posters/,执行:

uv run posterflow run ./posters \
  --output ./outputs/poster_report.md

仅运行 OCR

用于在调用模型前检查识别质量:

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.md

临时调整并发

OCR_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。

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages