Paperbanana

PaperBanana 面向 AI 科学家的学术插图自动生成

---

免责声明：这是对该论文的非官方、由社区驱动的开源实现： 《PaperBanana：面向 AI 科学家的学术插图自动生成》，作者为 Dawei Zhu、Rui Meng、Yale Song、 Xiyu Wei、Sujian Li、Tomas Pfister 和 Jinsung Yoon（arXiv:2601.23265）。 本项目与原作者或 Google Research 无关联，也未获其认可。 此实现基于公开发表的论文，可能与原始系统有所不同。

一个智能体框架，可根据文本描述生成适合发表的学术图表和统计图。支持 OpenAI（GPT-5.2 + GPT-Image-1.5）、Azure OpenAI / Foundry、Google Gemini 和 Atlas Cloud 提供商。

• 采用两阶段多 Agent 流水线进行迭代优化
• 支持多种 VLM 和图像生成服务商（OpenAI、Azure、Gemini、Atlas Cloud）
• 输入优化层可提升生成质量
• 自动优化模式，以及根据用户反馈继续运行
• 提供 CLI、Python API 和 MCP 服务，方便与 IDE 集成
• 批量生成：通过清单文件（YAML/JSON）一次运行生成多个图表
• 批量绘图 — paperbanana plot-batch 根据一个清单（每项对应 CSV/JSON）批量生成多个统计图
• PDF 输入：提供方法背景信息（可选安装 paperbanana[pdf] / PyMuPDF），并可选择页面
• PaperBanana Studio — 本地 Gradio Web UI（paperbanana studio），支持图表、绘图、评估、批量处理和运行浏览
• Claude Code 技能，支持 /generate-diagram、/generate-plot 和 /evaluate-diagram

正在学习大模型概念？ 我们还发布了 211 张免费视觉卡片， 涵盖注意力、RAG、Agent 和推理。 在线阅读。

Atlas Cloud

Atlas Cloud 是一个全模态 AI 推理平台，为开发者提供统一的 AI API，以访问视频生成、图像生成和大模型 API。无需管理多个服务商的集成，只需连接一次，即可统一访问涵盖所有模态的 300 多种精选模型。

了解 Atlas Cloud 推出的全新编码套餐促销活动，以更实惠的价格使用 API： https://www.atlascloud.ai/console/coding-plan

---

快速开始

在浏览器中试用：Colab 快速入门笔记本 将带你完整走过安装 → API 密钥 → 生成图表的流程，无需本地配置。

前提条件

• Python 3.10+
• OpenAI API 密钥（platform.openai.com）或 Azure OpenAI / Foundry 端点
• 或 Google Gemini API 密钥（免费，Google AI Studio）

步骤 1：安装

pip install paperbanana

或者从源代码安装以进行开发：

git clone https://github.com/llmsresearch/paperbanana.git
cd paperbanana
pip install -e ".[dev,openai,google]"

Docker

从仓库克隆版本构建镜像，并在运行时传入 API 密钥：

docker build -t paperbanana .
docker run --rm -e GOOGLE_API_KEY paperbanana generate --help

要生成图表，请将输入文件和输出文件夹挂载到 /work：

docker run --rm -e GOOGLE_API_KEY \
  -v "$(pwd)/method.txt:/work/method.txt:ro" \
  -v "$(pwd)/outputs:/work/outputs" \
  paperbanana generate --input method.txt --caption "Overview of our framework"

步骤 2：获取 API 密钥

cp .env.example .env
# Edit .env and add your API key:
#   OPENAI_API_KEY=your-key-here
#   GOOGLE_API_KEY=your-key-here
#
# For Azure OpenAI / Foundry:
#   OPENAI_BASE_URL=https://<resource>.openai.azure.com/openai/v1
#
# Optional Gemini overrides:
#   GOOGLE_BASE_URL=https://your-gemini-proxy.example.com
#   GOOGLE_VLM_MODEL=gemini-2.5-flash
#   GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview

或者使用 Gemini 设置向导：

paperbanana setup

步骤 3：生成图表

paperbanana generate \
  --input examples/sample_inputs/transformer_method.txt \
  --caption "Overview of our encoder-decoder architecture with sparse routing"

启用输入优化和自动优化：

paperbanana generate \
  --input my_method.txt \
  --caption "Overview of our encoder-decoder framework" \
  --optimize --auto

输出将保存到 outputs/run_<timestamp>/final_output.png，同时包含所有中间迭代结果和元数据。

PaperBanana Studio（本地 Web UI）

安装可选的 Gradio 依赖项，然后启动应用：

pip install 'paperbanana[studio]'
paperbanana studio

打开终端中显示的 URL（默认值为 http://127.0.0.1:7860/）。Studio 提供与 CLI 相同的工作流：方法图表、统计图、比较评估、继续之前的运行、批量清单（方法类或绘图批处理，可通过 Batch 选项卡使用），以及用于浏览 run_* / batch_* 输出文件夹的简易浏览器。可按需使用 --host、--port、--config 和 --output-dir。

---

工作原理

PaperBanana 采用多 Agent 流水线，最多包含 7 个专用 Agent：

阶段 0 -- 输入优化（可选，--optimize）：

0. 输入优化器运行两个并行 VLM 调用：
   • 上下文增强器将原始方法论文本整理为适合绘图的格式（组件、流程、分组、输入/输出）
   • 标题优化器将含糊的标题改写为精确的视觉规范

阶段 1 -- 线性规划：

1. 检索器从精选的 13 个方法论图示中选出最相关的参考示例，涵盖 Agent/推理、视觉/感知、生成式/学习和科学/应用领域
2. 规划器通过从检索到的示例中进行上下文学习，生成目标图示的详细文字描述
3. 风格设计器根据 NeurIPS 风格指南（配色方案、布局、排版）优化描述，提升视觉美感

阶段 2 -- 迭代优化：

4. 可视化器将描述渲染为图像
5. 评审器根据源上下文评估生成的图像，并提供修订后的描述以解决任何问题
6. 重复步骤 4-5 达到固定迭代次数（默认 3 次），或直到评审器满意（--auto）

服务提供商

PaperBanana 支持多种 VLM 和图像生成服务提供商：

组件	服务提供商	模型	备注
VLM（规划、评审）	OpenAI	gpt-5.2	默认
图像生成	OpenAI	gpt-image-1.5	默认
VLM	Atlas Cloud	deepseek-ai/DeepSeek-V3-0324	兼容 OpenAI 的聊天端点
图像生成	Atlas Cloud	openai/gpt-image-2/text-to-image	异步预测 API
VLM	Google Gemini	gemini-2.5-flash	成本低
图像生成	Google Gemini	gemini-3-pro-image-preview	$0.134/张图像（1K）
VLM / 图像	OpenRouter	任意受支持的模型	路由灵活

Azure OpenAI / Foundry 端点会自动检测——将 OPENAI_BASE_URL 设置为你的端点。 也支持兼容 Gemini 的网关——需要时设置 GOOGLE_BASE_URL。 Atlas Cloud 的聊天服务使用 ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1，图像生成使用 ATLASCLOUD_IMAGE_BASE_URL=https://api.atlascloud.ai/api/v1。

Atlas Cloud 官方网站： https://www.atlascloud.ai/?utm_source=github&utm_medium=link&utm_campaign=paperbanana

推荐用于 ATLASCLOUD_VLM_MODEL 的 Atlas LLM 模型：

• deepseek-ai/DeepSeek-V3-0324（默认）
• openai/gpt-4o
• openai/gpt-4.1
• google/gemini-2.5-flash
• anthropic/claude-sonnet-4.5-20250929

这些模型稳定且普遍可用，并已通过 Atlas Cloud API 验证。完整且持续更新的模型池（300 多个模型）记录在 Atlas Cloud 自有文档中——参见 https://www.atlascloud.ai/models——其中列出的任何模型 ID 都可以通过 ATLASCLOUD_VLM_MODEL 传入。

推荐用于 ATLASCLOUD_IMAGE_MODEL 的 Atlas 图像模型：

• openai/gpt-image-2/text-to-image
• openai/gpt-image-2/edit
• baidu/ERNIE-Image-Turbo/text-to-image
• black-forest-labs/flux-dev
• black-forest-labs/flux-schnell
• qwen/qwen-image

---

CLI 参考

paperbanana generate — 方法图

# Basic generation
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework"

# With input optimization and auto-refine
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --optimize --auto

# Continue the latest run with user feedback
paperbanana generate --continue \
  --feedback "Make arrows thicker and colors more distinct"

# Continue a specific run
paperbanana generate --continue-run run_20260218_125448_e7b876 \
  --iterations 3

# PDF as input (install PyMuPDF: pip install 'paperbanana[pdf]')
paperbanana generate \
  --input paper.pdf \
  --caption "Overview of our method" \
  --pdf-pages "3-8"

# Guide generation with a reference/sketch image (repeatable)
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --image sketch.png --image prior_figure.png

标志	简写	说明
--input	-i	方法论文本文件或 PDF 的路径（新运行时必需）
--caption	-c	图注／传达意图（新运行时必需）
--image		参考图／草图（手绘草图、白板照片、已有图表），用于引导 Planner。可重复指定多张图片
--output	-o	输出图像路径（默认：在 outputs/ 中自动生成）
--iterations	-n	Visualizer-Critic 优化轮数（默认：3）
--num-candidates	-k	并行生成 N 张候选图像，范围为 1-8（默认：1）。规划只运行一次；优化会针对每个候选项分别进行，并使用不同的种子偏移量。输出位于 candidates/cand_<i>/；运行根目录下的 final_output 为候选图像 1。成本估算和 --budget 均会计入并行生成的开销
--auto		循环运行，直到 Critic 满意（受 --max-iterations 安全上限限制）
--max-iterations		--auto 模式的安全上限（默认：30）
--optimize		通过并行上下文增强和图注优化来预处理输入
--continue		从 outputs/ 中最新的运行继续
--continue-run		从指定运行 ID 继续
--feedback		继续运行时提供给 Critic 的用户反馈
--pdf-pages		仅适用于 PDF 输入：从 1 开始编号的页码（例如 1-5、2,4,6-8；默认：全部）
--vlm-provider		VLM 提供商名称（默认：openai）
--vlm-model		VLM 模型名称（默认：gpt-5.2）
--image-provider		图像生成提供商（默认：openai_imagen）
--image-model		图像生成模型（默认：gpt-image-1.5）
--format	-f	输出格式：png、jpeg 或 webp（默认：png）
--config		YAML 配置文件路径（参见 configs/config.yaml）
--verbose	-v	显示详细的 Agent 进度和耗时
--progress-json		在生成过程中向标准输出发送 JSON 进度事件

paperbanana plot — 统计图表

paperbanana plot \
  --data results.csv \
  --intent "Bar chart comparing model accuracy across benchmarks"

标志	简写	说明
--data	-d	数据文件路径，格式为 CSV 或 JSON（必需）
--intent		图表的传达意图（必需）
--output	-o	输出图像路径
--iterations	-n	优化轮数（默认：3）
--vlm-provider		VLM 提供商名称
--vlm-model		VLM 模型名称

图表通过 VLM 生成的 matplotlib 代码进行绘制，无需图像生成提供商或凭据。

paperbanana venues — 自定义会议风格包

--venue 用于选择一个会议风格包：包含 methodology_style_guide.md、plot_style_guide.md 和可选 venue.yaml 的目录。PaperBanana 内置风格包（neurips、icml、acl、ieee）；你也可以在 ~/.config/paperbanana/venues/ 下添加自己的风格包（使用 --venue-dir 或 PAPERBANANA_VENUE_DIR 覆盖），无需修改仓库：

# 1. Scaffold a pack (seeds both guides from the NeurIPS templates)
paperbanana venues init mylab

# 2. Edit the style guides — or generate them from a corpus of example figures:
#    paperbanana guidelines synthesize --reference-set ./examples \
#      --output ~/.config/paperbanana/venues/mylab/methodology_style_guide.md

# 3. Use it anywhere --venue is accepted
paperbanana generate --input method.txt --caption "Overview" --venue mylab

# See everything that's available (built-in + user, with source)
paperbanana venues list

venue.yaml（所有字段均可选）：

display_name: "My Lab Style"  # shown by `paperbanana venues list`
aspect_ratio: "16:9"          # default --aspect-ratio for this venue's runs
fonts:                        # preferred fonts, appended to the style guides
  - "Helvetica"

如果名称冲突，优先使用内置风格包——用户风格包不能覆盖内置会议。遇到未知会议名称时，会立即报错并列出来自两个来源的可用风格包。

paperbanana batch —— 批量生成

从单个清单文件（YAML 或 JSON）生成多个方法图。每个项目都会运行完整流程；输出写入 outputs/batch_<id>/run_<id>/，并由 batch_report.json 汇总所有运行结果。

paperbanana batch --manifest examples/batch_manifest.yaml --optimize

清单格式（YAML 或 JSON，包含 items 列表）：

items:
  - input: path/to/method1.txt
    caption: "Overview of our encoder-decoder"
    id: fig1
  - input: method2.txt
    caption: "Training pipeline"
    id: fig2
  - input: paper.pdf
    caption: "System overview"
    id: fig3
    pdf_pages: "4-9" # optional; PDF inputs only

清单中的路径相对于清单文件所在目录解析。

组合图： 添加可选的 composite 部分，在批量处理完成后自动将所有生成的面板拼接成一张带标签的图：

composite:
  layout: "1x3"          # rows x cols, or "auto"
  labels: auto            # (a), (b), (c)... or explicit list, or null
  spacing: 20             # pixels between panels
  label_position: bottom  # top or bottom
  output: "composite.png"

items:
  - input: method_encoder.txt
    caption: "Encoder architecture"
    id: panel_a
  # ...

组合图像与各个面板一同保存在批量输出目录中。完整示例请参见 examples/composite_batch_manifest.yaml。

从现有批量运行生成人类可读的报告（Markdown 或 HTML）：

paperbanana batch-report --batch-dir outputs/batch_20250109_123456_abc --format markdown
# or by batch ID (under default output dir)
paperbanana batch-report --batch-id batch_20250109_123456_abc --format html --output report.html

图表批量报告包含 batch_kind: methodology；绘图批次则使用 batch_kind: statistical_plot。人类可读的报告（paperbanana batch-report）会在存在批次类型时显示该类型。

Sweep 清单可让你将完整的 sweep 计划保存为 YAML/JSON，而不是使用八个以逗号分隔的 CLI 标志。它与轴标志互斥；请参见 examples/sweep_manifest.yaml。

paperbanana sweep --manifest examples/sweep_manifest.yaml

paperbanana sweep 生成的Sweep 报告也可以通过相同方式呈现：

paperbanana sweep-report --sweep-dir outputs/sweep_20250109_123456_abc --format html
# or by sweep ID
paperbanana sweep-report --sweep-id sweep_20250109_123456_abc --format markdown

呈现后的 sweep 报告包含摘要、排名前 5 的表格、完整的变体表格（含每个变体的提供方/模型、迭代次数、评论者建议数量、代理评分和输出路径），以及 quality_proxy_score 说明。试运行报告会呈现精简的“计划变体”部分。

标志	简写	描述
--manifest	-m	清单文件路径（必填）
--output-dir	-o	批量运行的父目录（默认：outputs）
--config		配置 YAML 文件路径
--iterations	-n	每个项目的优化迭代次数
--optimize		为每个项目预处理输入
--auto		持续循环，直到每个项目都通过评论者审核
--format	-f	输出图像格式（png、jpeg、webp）
--auto-download-data		如果未缓存，则自动下载 PaperBananaBench 参考集（约 254 MB）

paperbanana plot-batch —— 批量统计绘图

根据清单（YAML 或 JSON）生成多个绘图。每个项目指定一个 数据 文件（CSV 或 JSON）和一个 意图字符串，与 paperbanana plot 的用法一致。输出位于 outputs/batch_<id>/run_<id>/ 下，并使用与图表批次相同的 batch_report.json 和 paperbanana batch-report 工作流。

paperbanana plot-batch --manifest examples/plot_batch_manifest.yaml --optimize

清单格式（items 列表）：

items:
  - data: path/to/results.csv
    intent: "Bar chart comparing accuracy across models"
    id: fig_acc
  - data: other.json
    intent: "Scatter plot with trend line"
    aspect_ratio: "16:9"   # optional per item; CLI --aspect-ratio is the default when omitted

路径相对于清单文件所在目录解析。

标志	简写	描述
--manifest	-m	清单路径（必填）
--output-dir	-o	batch_* 的父目录（默认：outputs）
--config		配置 YAML 文件路径
--vlm-provider		VLM 提供方（默认：gemini）
--vlm-model		覆盖 VLM 模型
--image-provider		图像生成提供方
--image-model		图像生成模型
--iterations	-n	每个项目的优化迭代次数
--auto		持续循环，直到每个项目都通过评论者审核
--max-iterations		--auto 的安全上限
--optimize		优化每个项目的输入
--format	-f	png、jpeg 或 webp
--save-prompts / --no-save-prompts		保存提示词（默认：开启，与 plot 相同）
--venue		会议风格包：内置（neurips、icml、acl、ieee）、用户风格包或 custom
--aspect-ratio	-ar	清单中未设置时使用的默认宽高比
--verbose	-v	详细日志记录

paperbanana orchestrate —— 完整论文图件包

从完整论文源文件生成以发表为导向的图件包，并可选择生成数据驱动型图表。此命令会：

• 解析论文（.txt、.md 或 .pdf）
• 根据章节结构规划多张方法图
• 可选发现 CSV/JSON 文件，以规划统计图表
• 为所有规划项运行生成任务
• 写入一个包含 figure_package.json、figures/、figures.tex 和 captions.md 的图件包文件夹

paperbanana orchestrate \
  --paper paper.pdf \
  --data-dir ./results \
  --max-method-figures 4 \
  --max-plot-figures 3 \
  --optimize

使用 --dry-run 仅规划并检查 orchestration_plan.json，不调用 API。 使用 --resume-orchestrate <id-or-path> 从检查点状态继续中断的编排任务。

标志	描述
--paper / -p	论文源文件路径（.txt、.md 或 .pdf）
--resume-orchestrate	通过 ID 或目录恢复现有编排任务
--retry-failed	恢复时包含先前失败的任务
--max-retries	每项任务首次失败后的额外重试次数
--data-dir	可选目录，包含用于图表规划的 CSV/JSON 文件
--output-dir / -o	父输出目录（创建 orchestrate_*）
--max-method-figures	规划/生成的方法图数量上限
--max-plot-figures	规划/生成的图表数量上限
--pdf-pages	仅用于 PDF 的页面选择（例如 1-5、2,4,6-8）
--optimize	为生成项启用输入优化
--iterations / -n	每个生成项的优化迭代次数
--auto + --max-iterations	由评审驱动的自动优化模式，并设定安全上限
--concurrency	并行生成图件的工作线程数
--format / -f	输出格式（png、jpeg、webp）
--dry-run	仅规划图件包；不调用生成服务

paperbanana composite —— 合成多面板图

将多张图像拼接成一张带有 (a)、(b)、(c) 子面板标签的图：

paperbanana composite \
  panel_a.png panel_b.png panel_c.png \
  --layout 1x3 \
  --output figure2.png

标志	简写	描述
IMAGES		位置参数：要合成的图像路径
--layout	-l	网格布局：RxC（例如 1x3、2x2）或 auto（默认：auto）
--labels		逗号分隔的标签，或使用 none 禁用标签（默认：自动标记为 (a),(b),...）
--spacing	-s	面板之间的像素间距（默认：20）
--label-position		top 或 bottom（默认：bottom）
--label-font-size		标签字体大小（默认：32）
--output	-o	输出路径（默认：composite_output.png）

此命令适用于任何现有图像，无需调用 API。如果批处理清单包含 composite 部分，此命令也会自动触发（参见上文的 paperbanana batch）。

paperbanana evaluate —— 质量评估

使用 VLM-as-a-Judge 对生成的图表与人工参考图进行对比评估：

paperbanana evaluate \
  --generated diagram.png \
  --reference human_diagram.png \
  --context method.txt \
  --caption "Overview of our framework"

标志	简写	描述
--generated	-g	生成图像的路径（必需）
--reference	-r	人工参考图像的路径（必需）
--context		源上下文文本文件或 PDF 的路径（必需）
--caption	-c	图注（必需）
--pdf-pages		仅用于 PDF 上下文：按从 1 开始的页码选择页面（默认：全部）

根据 4 个维度评分（按照论文中的方法进行分层汇总）：

• 主要：忠实度、可读性
• 次要：简洁性、美观度

paperbanana polish —— 优化现有图示

使用你自己的图示：VLM 会依据会议风格指南检查图示，并提出最多 10 项具体、可执行的改进建议；随后，支持图像编辑的提供方会将这些改进应用到原始图示上（引导式编辑）。建议会打印到控制台，让你确切了解哪些内容发生了变化。

paperbanana polish --input figure.png
paperbanana polish --input figure.png --venue icml --iterations 2 --output polished.png

标志	简写	描述
--input	-i	现有图像文件的路径（必需）
--output	-o	输出路径（默认值：outputs/polish_<timestamp>/final_output.png）
--venue		会议风格指南：neurips（默认值）、icml、acl、ieee、custom
--iterations	-n	优化轮数；每轮都会针对上一轮的结果提出并应用改进建议（默认值：1）
--aspect-ratio	-ar	目标宽高比（默认保留输入图示的宽高比）
--num-candidates	-k	每轮并行应用建议的次数（1-8）
--budget		美元预算上限；超出时会平稳停止优化
--seed		用于生成可复现编辑结果的随机种子

需要支持引导式图像编辑的图像提供方（Google Gemini 图像模型）。如果图示已符合风格指南，polish 会直接退出，不做任何更改。

paperbanana studio —— 本地 Web 界面

需要安装 pip install 'paperbanana[studio]'（Gradio）。

paperbanana studio
paperbanana studio --port 8080 --output-dir ./my_outputs

标志	描述
--host	绑定地址（默认值：127.0.0.1）
--port	端口（默认值：7860）
--share	创建临时公开的 Gradio 链接（请勿用于敏感数据）
--config	YAML 配置文件的路径
--output-dir / -o	运行结果的默认输出目录
--root-path	位于反向代理后时使用的 URL 子路径

paperbanana setup —— 首次配置

paperbanana setup

交互式向导会先询问是否使用官方 Gemini API。 如果选择官方 API，向导会采用默认的 AI Studio 密钥流程；如果不选择，则会询问自定义 Gemini 兼容 URL 和 API 密钥。

paperbanana data —— 参考数据集

# Download the PaperBananaBench reference set (~254 MB, one command)
paperbanana data download

# Import plot references too (or both)
paperbanana data download --task plot
paperbanana data download --task both

# Inspect / clear the cache
paperbanana data info
paperbanana data clear

数据集由项目托管的 GitHub 发布镜像提供 （bench-data-v1）， 并会在解压前验证其 SHA256 校验和。感谢 PaperBananaBench 作者—— 该镜像同步自其 2026-03-22 版本。数据集会缓存到 ~/.cache/paperbanana/（可通过 PAPERBANANA_CACHE_DIR 覆盖）；生成命令也可通过 --auto-download-data 在首次使用时下载数据集。

---

Python API

import asyncio
from paperbanana import PaperBananaPipeline, GenerationInput, DiagramType
from paperbanana.core.config import Settings

settings = Settings(
    vlm_provider="openai",
    vlm_model="gpt-5.2",
    image_provider="openai_imagen",
    image_model="gpt-image-1.5",
    optimize_inputs=True,   # Enable input optimization
    auto_refine=True,       # Loop until critic is satisfied
)

pipeline = PaperBananaPipeline(settings=settings)

result = asyncio.run(pipeline.generate(
    GenerationInput(
        source_context="Our framework consists of...",
        communicative_intent="Overview of the proposed method.",
        diagram_type=DiagramType.METHODOLOGY,
    )
))

print(f"Output: {result.image_path}")

进度回调： generate() 和 continue_run() 接受可选的 progress_callback 参数。流水线会在每个步骤（optimizer、retriever、planner、stylist、visualizer、critic）调用此参数，并传入 PipelineProgressEvent 对象（stage、message、seconds、iteration、extra），这样你无需修改 Agent，就能在 UI 中显示进度或记录各步骤耗时。

继续之前的运行：

from paperbanana.core.resume import load_resume_state

state = load_resume_state("outputs", "run_20260218_125448_e7b876")
result = asyncio.run(pipeline.continue_run(
    resume_state=state,
    additional_iterations=3,
    user_feedback="Make the encoder block more prominent",
))

完整可运行示例请参阅 examples/generate_diagram.py 和 examples/generate_plot.py。

---

MCP 服务

PaperBanana 包含一个 MCP 服务，可与 Claude Code、Cursor 或任何兼容 MCP 的客户端配合使用。添加以下配置，即可通过 uvx 使用，无需本地克隆：

{
  "mcpServers": {
    "paperbanana": {
      "command": "uvx",
      "args": ["--from", "paperbanana[mcp]", "paperbanana-mcp"],
      "env": { "GOOGLE_API_KEY": "your-google-api-key" }
    }
  }
}

该服务提供 11 个 MCP 工具：generate_diagram、generate_plot、continue_run（可选提供反馈，以继续之前的 run_*）、continue_diagram、continue_plot、evaluate_diagram、evaluate_plot、orchestrate_figures（完整论文图件套装）、batch_diagrams、batch_plots 和 download_references。

仓库还附带 3 个 Claude Code 技能：

• /generate-diagram <file> [caption] - 根据文本文件生成方法示意图
• /generate-plot <data-file> [intent] - 根据 CSV/JSON 数据生成统计图
• /evaluate-diagram <generated> <reference> - 对照人工参考图评估示意图

完整设置说明（Claude Code、Cursor、本地开发）请参阅 mcp_server/README.md。

---

Overleaf 集成（GitHub Action）

让论文中的方法示意图自动与正文保持同步。PaperBanana 附带一个 GitHub Action，可与 Overleaf 内置的 GitHub 同步功能配合使用：推送 .tex 更改后，该 Action 会提取方法部分、生成示意图，并将图片和可直接用于 \input 的 LaTeX 代码片段提交回来。拉取到 Overleaf 后，文件便会出现在文件树中。

- uses: actions/checkout@v4
- uses: llmsresearch/paperbanana/integrations/github-action@main
  with:
    tex-file: sections/method.tex
    caption: "Overview of our proposed framework"
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

完整工作流、所有输入项和成本控制选项，请参阅 integrations/github-action/README.md。

---

配置

默认设置位于 configs/config.yaml。可通过 CLI 标志或自定义 YAML 文件进行覆盖：

paperbanana generate \
  --input method.txt \
  --caption "Overview" \
  --config my_config.yaml

关键设置：

vlm:
  provider: openai           # openai, atlas, gemini, or openrouter
  model: gpt-5.2

image:
  provider: openai_imagen    # openai_imagen, atlas_imagen, google_imagen, or openrouter_imagen
  model: gpt-image-1.5

pipeline:
  num_retrieval_examples: 10
  refinement_iterations: 3
  # auto_refine: true        # Loop until critic is satisfied
  # max_iterations: 30       # Safety cap for auto_refine mode
  # optimize_inputs: true    # Preprocess inputs for better generation
  output_resolution: "2k"

reference:
  path: data/reference_sets

output:
  dir: outputs
  save_iterations: true
  save_metadata: true

环境变量（.env）：

# OpenAI (default)
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com/v1    # or Azure endpoint
OPENAI_VLM_MODEL=gpt-5.2                      # override model
OPENAI_IMAGE_MODEL=gpt-image-1.5              # override model

# Atlas Cloud
ATLASCLOUD_API_KEY=your-key
ATLASCLOUD_BASE_URL=https://api.atlascloud.ai/v1
ATLASCLOUD_VLM_MODEL=deepseek-ai/DeepSeek-V3-0324
ATLASCLOUD_IMAGE_BASE_URL=https://api.atlascloud.ai/api/v1
ATLASCLOUD_IMAGE_MODEL=openai/gpt-image-2/text-to-image

# Google Gemini (alternative, free)
GOOGLE_API_KEY=your-key
GOOGLE_BASE_URL=                            # optional custom Gemini-compatible endpoint
GOOGLE_VLM_MODEL=gemini-2.5-flash          # override Gemini VLM model
GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview  # override Gemini image model

---

项目结构

paperbanana/
├── paperbanana/
│   ├── core/          # Pipeline orchestration, types, config, resume, utilities
│   ├── agents/        # Optimizer, Retriever, Planner, Stylist, Visualizer, Critic
│   ├── providers/     # VLM and image gen provider implementations
│   │   ├── vlm/       # OpenAI, Atlas Cloud, Gemini, OpenRouter VLM providers
│   │   └── image_gen/ # OpenAI, Atlas Cloud, Gemini, OpenRouter image gen providers
│   ├── reference/     # Reference set management (13 curated examples)
│   ├── guidelines/    # Style guidelines loader
│   └── evaluation/    # VLM-as-Judge evaluation system
├── configs/           # YAML configuration files
├── prompts/           # Prompt templates for all agents + evaluation
│   ├── diagram/       # context_enricher, caption_sharpener, retriever, planner, stylist, visualizer, critic
│   ├── plot/          # plot-specific prompt variants
│   └── evaluation/    # faithfulness, conciseness, readability, aesthetics
├── data/
│   ├── reference_sets/  # 13 verified methodology diagrams
│   └── guidelines/      # NeurIPS-style aesthetic guidelines
├── examples/          # Working example scripts + sample inputs
├── scripts/           # Data curation and build scripts
├── tests/             # Test suite
├── mcp_server/        # MCP server for IDE integration
└── .claude/skills/    # Claude Code skills (generate-diagram, generate-plot, evaluate-diagram)

开发

# Install with dev dependencies
pip install -e ".[dev,openai,google]"

# Run tests
pytest tests/ -v

# Lint
ruff check paperbanana/ mcp_server/ tests/ scripts/

# Format
ruff format paperbanana/ mcp_server/ tests/ scripts/

引用

这是一个非官方实现。如果您使用了本项目，请引用原始论文：

@article{zhu2026paperbanana,
  title={PaperBanana: Automating Academic Illustration for AI Scientists},
  author={Zhu, Dawei and Meng, Rui and Song, Yale and Wei, Xiyu
          and Li, Sujian and Pfister, Tomas and Yoon, Jinsung},
  journal={arXiv preprint arXiv:2601.23265},
  year={2026}
}

原始论文：https://arxiv.org/abs/2601.23265

免责声明

本项目是基于公开论文独立进行的开源再实现。 它与原作者、Google Research 或 Peking University 均无任何关联，也未获得其认可。此实现可能与论文中描述的原始系统有所不同。 请自行斟酌使用。

许可证

MIT