PaperBanana 面向AI科学家的自动化学术插图工具

---

免责声明: 本项目是Dawei Zhu、Rui Meng、Yale Song、Xiyu Wei、Sujian Li、Tomas Pfister和Jinsung Yoon所著论文《PaperBanana: 面向AI科学家的自动化学术插图》（arXiv:2601.23265）的非官方、社区驱动的开源实现。本项目与原作者或Google Research均无关联，亦未获得其认可。该实现基于公开论文，可能与原始系统存在差异。

一个基于智能体框架的工具，可根据文本描述生成出版级质量的学术图表和统计图形。支持OpenAI（GPT-5.2 + GPT-Image-1.5）、Azure OpenAI / Foundry以及Google Gemini等服务提供商。

• 两阶段多智能体流水线，具备迭代优化功能
• 支持多种视觉语言模型及图像生成服务提供商（OpenAI、Azure、Gemini）
• 输入优化层，提升生成质量
• 自动精修模式及用户反馈下的运行续接
• 提供命令行界面、Python API以及MCP服务器，便于集成到IDE中
• 可通过清单文件（YAML/JSON）进行批量生成，一次运行即可完成多个图表的制作
• 支持PDF输入以提供方法论背景信息（可选paperbanana[pdf] / PyMuPDF），并可逐页选择
• PaperBanana Studio — 本地Gradio Web界面（paperbanana studio），用于图表、绘图、评估、批量处理及运行结果浏览
• 支持Claude Code技能，可用于/generate-diagram、/generate-plot和/evaluate-diagram等指令

---

快速入门

前置条件

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

第一步：安装

pip install paperbanana

若需开发，则可从源码安装：

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

第二步：获取API密钥

cp .env.example .env
# 编辑.env文件并添加您的API密钥：
#   OPENAI_API_KEY=your-key-here
#   GOOGLE_API_KEY=your-key-here
#
# 对于Azure OpenAI / Foundry：
#   OPENAI_BASE_URL=https://<resource>.openai.azure.com/openai/v1
#
# 可选的Gemini自定义配置：
#   GOOGLE_BASE_URL=https://your-gemini-proxy.example.com
#   GOOGLE_VLM_MODEL=gemini-2.0-flash
#   GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview

您也可以使用Gemini的设置向导：

paperbanana setup

第三步：生成图表

paperbanana generate \
  --input examples/sample_inputs/transformer_method.txt \
  --caption "我们的稀疏路由编码器-解码器架构概览"

结合输入优化与自动精修功能：

paperbanana generate \
  --input my_method.txt \
  --caption "我们的编码器-解码器框架概览" \
  --optimize --auto

生成结果将保存至outputs/run_<timestamp>/final_output.png，同时包含所有中间迭代步骤及元数据。

PaperBanana Studio（本地Web界面）

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

pip install 'paperbanana[studio]'
paperbanana studio

打开终端中显示的URL（默认为http://127.0.0.1:7860/）。Studio提供了与命令行界面相同的流程：方法论图表、统计图表、对比评估、继续之前的运行、批量清单处理，以及用于浏览run_*和batch_*输出文件夹的简单浏览器。可根据需要使用--host、--port、--config和--output-dir等参数。

---

工作原理

PaperBanana 实现了一个包含最多 7 个专业代理的多代理流水线：

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

0. 输入优化器 并行调用两个视觉语言模型（VLM）：
   • 上下文增强器 将原始方法文本结构化为适合绘制图表的格式（组件、流程、分组、输入输出）
   • 标题精炼器 将模糊的标题转化为精确的可视化规范

阶段 1 -- 线性规划：

1. 检索器 从一个精选的 13 张方法论图表集合中选择最相关的参考示例，这些图表涵盖代理/推理、视觉/感知、生成式/学习以及科学/应用等领域。
2. 规划器 基于检索到的示例进行上下文学习，生成目标图表的详细文本描述。
3. 风格设计师 使用 NeurIPS 风格指南（配色方案、布局、排版）对描述进行润色，以提升视觉美感。

阶段 2 -- 迭代优化：

4. 可视化器 将描述渲染成图像。
5. 评论员 根据源上下文评估生成的图像，并提供修改后的描述以解决任何问题。
6. 上述第 4 至第 5 步会重复执行固定次数（默认 3 次），或直到评论员满意为止（--auto）。

服务提供商

PaperBanana 支持多种视觉语言模型和图像生成服务提供商：

组件	服务提供商	模型	备注
VLM（规划、评论）	OpenAI	gpt-5.2	默认
图像生成	OpenAI	gpt-image-1.5	默认
VLM	Google Gemini	gemini-2.0-flash	免费层级
图像生成	Google Gemini	gemini-3-pro-image-preview	免费层级
VLM / 图像	OpenRouter	任何支持的模型	灵活路由

Azure OpenAI 和 Foundry 的端点会自动检测——只需设置 OPENAI_BASE_URL 为您的端点即可。同时，也支持与 Gemini 兼容的网关——在需要时设置 GOOGLE_BASE_URL。

---

CLI 参考

paperbanana generate -- 方法论图表

# 基本生成
paperbanana generate \
  --input method.txt \
  --caption "我们的框架概述"

# 带有输入优化和自动优化
paperbanana generate \
  --input method.txt \
  --caption "我们的框架概述" \
  --optimize --auto

# 根据用户反馈继续最近一次运行
paperbanana generate --continue \
  --feedback "让箭头更粗，颜色更鲜明"

# 继续特定运行
paperbanana generate --continue-run run_20260218_125448_e7b876 \
  --iterations 3

# PDF 作为输入（需安装 PyMuPDF：pip install 'paperbanana[pdf]’）
paperbanana generate \
  --input paper.pdf \
  --caption "我们方法的概述" \
  --pdf-pages "3-8"

标志	缩写	描述
--input	-i	方法文本文件或 PDF 的路径（新运行必需）
--caption	-c	图表标题/沟通意图（新运行必需）
--output	-o	输出图像路径（默认：自动生成在 outputs/ 目录下）
--iterations	-n	可视化器-评论员优化轮次（默认：3）
--auto		循环直至评论员满意（并设有 --max-iterations 安全上限）
--max-iterations		--auto 模式的安全上限（默认：30）
--optimize		使用并行上下文增强和标题精炼预处理输入
--continue		从 outputs/ 中的最新运行继续
--continue-run		从特定运行 ID 继续
--feedback		继续运行时提供给评论员的用户反馈
--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	显示详细的代理进度和计时信息
--progress-json		在生成过程中将进度事件以 JSON 格式输出到标准输出

paperbanana plot -- 统计图表

paperbanana plot \
  --data results.csv \
  --intent "比较各基准上模型准确率的柱状图"

标志	缩写	描述
--data	-d	数据文件路径，CSV 或 JSON（必需）
--intent		图表的沟通意图（必需）
--output	-o	输出图像路径
--iterations	-n	优化迭代次数（默认：3）

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: "我们的编码解码器概述"
    id: fig1
  - input: method2.txt
    caption: "训练流程"
    id: fig2
  - input: paper.pdf
    caption: "系统概述"
    id: fig3
    pdf_pages: "4-9" # 可选；仅适用于 PDF 输入

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

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

paperbanana batch-report --batch-dir outputs/batch_20250109_123456_abc --format markdown
# 或者通过批量 ID（在默认输出目录下）
paperbanana batch-report --batch-id batch_20250109_123456_abc --format html --output report.html

标志	缩写	描述
--manifest	-m	清单文件路径（必需）
--output-dir	-o	批量运行的父目录（默认：outputs）
--config		配置 YAML 文件路径
--iterations	-n	每个条目的优化迭代次数
--optimize		对每个条目的输入进行预处理
--auto		循环直至每个条目都得到评论员的满意
--format	-f	输出图像格式（png、jpeg、webp）
--auto-download-data		如有需要，下载扩展的参考数据集

paperbanana evaluate -- 质量评估

使用 VLM 作为评判者，对生成的图表与人工参考图进行对比评估：

paperbanana evaluate \
  --generated diagram.png \
  --reference human_diagram.png \
  --context method.txt \
  --caption "我们框架的概述"

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

在四个维度上打分（按照论文中的层次化聚合方式）：

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

paperbanana studio -- 本地 Web UI

需要运行 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 密钥。

---

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,   # 启用输入优化
    auto_refine=True,       # 循环直到批评家满意
)

pipeline = PaperBananaPipeline(settings=settings)

result = asyncio.run(pipeline.generate(
    GenerationInput(
        source_context="我们的框架包括...",
        communicative_intent="对所提方法的概述。",
        diagram_type=DiagramType.METHODOLOGY,
    )
))

print(f"输出: {result.image_path}")

进度回调： generate() 和 continue_run() 接受一个可选的 progress_callback 参数。流水线会在每个步骤（优化器、检索器、规划器、风格师、可视化器、批评家）中调用它，并传递 PipelineProgressEvent 对象（阶段、消息、秒数、迭代次数、额外信息），以便您可以在 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="让编码器模块更突出",
))

完整的工作示例请参见 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" }
    }
  }
}

暴露了三个 MCP 工具：generate_diagram、generate_plot 和 evaluate_diagram。

该仓库还附带 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。

---

配置

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

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

关键设置如下：

vlm:
  provider: openai           # openai、gemini 或 openrouter
  model: gpt-5.2

image:
  provider: openai_imagen    # openai_imagen、google_imagen 或 openrouter_imagen
  model: gpt-image-1.5

pipeline:
  num_retrieval_examples: 10
  refinement_iterations: 3
  # auto_refine: true        # 循环直到批评家满意
  # max_iterations: 30       # 自动精炼模式的安全上限
  # optimize_inputs: true    # 预处理输入以提高生成质量
  output_resolution: "2k"

reference:
  path: data/reference_sets

output:
  dir: outputs
  save_iterations: true
  save_metadata: true

环境变量（.env）：

# OpenAI（默认）
OPENAI_API_KEY=your-key
OPENAI_BASE_URL=https://api.openai.com/v1    # 或 Azure 端点
OPENAI_VLM_MODEL=gpt-5.2                      # 覆盖模型
OPENAI_IMAGE_MODEL=gpt-image-1.5              # 覆盖模型

# Google Gemini（替代方案，免费）
GOOGLE_API_KEY=your-key
GOOGLE_BASE_URL=                            # 可选的自定义兼容 Gemini 的端点
GOOGLE_VLM_MODEL=gemini-2.0-flash          # 覆盖 Gemini VLM 模型
GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview  # 覆盖 Gemini 图像模型

---

项目结构

paperbanana/
├── paperbanana/
│   ├── core/          # 管道编排、类型定义、配置、恢复机制、工具函数
│   ├── agents/        # 优化器、检索器、规划器、风格化器、可视化器、评价器
│   ├── providers/     # 多模态大模型及图像生成提供商实现
│   │   ├── vlm/       # OpenAI、Gemini、OpenRouter 的多模态大模型提供商
│   │   └── image_gen/ # OpenAI、Gemini、OpenRouter 的图像生成提供商
│   ├── reference/     # 参考集管理（13个精选示例）
│   ├── guidelines/    # 风格指南加载器
│   └── evaluation/    # 基于多模态大模型的评价系统
├── configs/           # YAML 配置文件
├── prompts/           # 所有智能体及评价模块的提示模板
│   ├── diagram/       # 上下文增强器、标题优化器、检索器、规划器、风格化器、可视化器、评价器
│   ├── plot/          # 针对不同情节的提示变体
│   └── evaluation/    # 忠实性、简洁性、可读性、美学
├── data/
│   ├── reference_sets/  # 13张经过验证的方法学示意图
│   └── guidelines/      # NeurIPS 风格的美学指南
├── examples/          # 可运行的示例脚本及输入样本
├── scripts/           # 数据整理与构建脚本
├── tests/             # 测试套件
├── mcp_server/        # 用于 IDE 集成的 MCP 服务器
└── .claude/skills/    # Claude Code 技能（生成示意图、生成情节图、评估示意图）

开发

# 安装并包含开发依赖
pip install -e ".[dev,openai,google]"

# 运行测试
pytest tests/ -v

# 代码检查
ruff check paperbanana/ mcp_server/ tests/ scripts/

# 代码格式化
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 或北京大学均无任何关联、背书或联系。该实现可能与论文中描述的原始系统存在差异。请用户自行判断并谨慎使用。

许可证

MIT

PaperBanana 快速上手指南

PaperBanana 是一个专为 AI 科研人员设计的自动化学术插图生成工具。它能够通过多智能体协作流程，将文本描述或论文片段转化为出版级的方法论图表和统计图。

环境准备

在开始之前，请确保满足以下系统要求和前置条件：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：3.10 或更高版本
• API 密钥（任选其一）：
  • OpenAI: 需要 OPENAI_API_KEY (支持 GPT-5.2 + GPT-Image-1.5)
  • Google Gemini: 需要 GOOGLE_API_KEY (免费层级可用)
  • Azure OpenAI / Foundry: 需要对应的 Endpoint 和 Key
• 可选依赖：若需处理 PDF 输入，需安装 PyMuPDF。

安装步骤

1. 基础安装

通过 pip 直接安装最新版本：

pip install paperbanana

2. 开发版安装（可选）

如需从源码安装并包含所有开发依赖及提供商支持：

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

3. 配置 API 密钥

复制环境变量模板文件并编辑：

cp .env.example .env

使用文本编辑器打开 .env 文件，填入你的 API 密钥：

# OpenAI 配置
OPENAI_API_KEY=your-key-here

# Google Gemini 配置
GOOGLE_API_KEY=your-key-here

# Azure OpenAI 配置 (如有需要)
OPENAI_BASE_URL=https://<resource>.openai.azure.com/openai/v1

提示：如果你主要使用 Gemini，也可以运行交互式设置向导：

paperbanana setup

基本使用

生成方法论图表 (Methodology Diagrams)

这是最常用的功能，将文本描述转换为架构图。

最简单的用法： 准备一个包含方法描述的文本文件（例如 method.txt），然后运行：

paperbanana generate \
  --input method.txt \
  --caption "Overview of our encoder-decoder architecture"

进阶用法（带输入优化与自动修正）： 启用 --optimize 对输入进行预处理，并使用 --auto 让系统自动迭代直到批评家（Critic）满意：

paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --optimize --auto

生成的图片将保存在 outputs/run_<timestamp>/final_output.png。

生成统计图表 (Statistical Plots)

基于数据文件自动生成可视化图表：

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

启动本地 Web 界面 (PaperBanana Studio)

如果你更喜欢图形化界面操作，可以安装并启动 Studio：

pip install 'paperbanana[studio]'
paperbanana studio

启动后，在浏览器中访问终端显示的地址（默认为 http://127.0.0.1:7860/），即可通过网页进行图表生成、批量任务和结果浏览。