Paperbanana

🚀 PaperBanana

PaperBanana 是一个为人工智能科学家打造的自动化学术插图生成框架，能根据文本描述生成高质量的学术图表和统计绘图。它支持多种图像生成模型，如 OpenAI（GPT - 5.2 + GPT - Image - 1.5）、Azure OpenAI / Foundry 以及 Google Gemini 等。

🚀 快速开始

前提条件

• Python 3.10 及以上版本
• 拥有 OpenAI API 密钥（[platform.openai.com](https://platform.openai.com/api - keys)）或 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]"

步骤 2：获取 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

步骤 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，同时保存所有中间迭代和元数据。

✨ 主要特性

• 采用两阶段多智能体管道，支持迭代优化
• 支持多种视觉语言模型（VLM）和图像生成提供商，如 OpenAI、Azure、Gemini
• 具备输入优化层，可提升生成质量
• 支持自动优化模式，并可根据用户反馈继续运行
• 提供命令行界面（CLI）、Python API 以及 MCP 服务器，方便与 IDE 集成
• 支持从清单文件（YAML/JSON）进行批量生成，一次运行可生成多个图表
• 具备 Claude Code 技能，可用于 /generate - diagram、/generate - plot 和 /evaluate - diagram

📦 安装指南

从 PyPI 安装

pip install paperbanana

从源码安装（用于开发）

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

💻 使用示例

基础用法

# 基本生成
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework"

高级用法

# 使用输入优化和自动优化
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --optimize --auto

# 根据用户反馈继续上一次运行
paperbanana generate --continue \
  --feedback "Make arrows thicker and colors more distinct"

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

📚 详细文档

CLI 参考

paperbanana generate -- 方法图表生成

# 基本生成
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework"

# 带输入优化和自动优化
paperbanana generate \
  --input method.txt \
  --caption "Overview of our framework" \
  --optimize --auto

# 继续最新运行并提供用户反馈
paperbanana generate --continue \
  --feedback "Make arrows thicker and colors more distinct"

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

paperbanana plot -- 统计绘图

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

paperbanana batch -- 批量生成

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

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

# 从现有批量运行生成人类可读报告（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

paperbanana evaluate -- 质量评估

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

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

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="Our framework consists of...",
        communicative_intent="Overview of the proposed method.",
        diagram_type=DiagramType.METHODOLOGY,
    )
))

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

继续之前的运行：

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" }
    }
  }
}

暴露了三个 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> - 将生成的图表与人类参考图表进行评估

完整的设置细节请参考 。

配置

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

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

关键设置：

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

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

pipeline:
  num_retrieval_examples: 10
  refinement_iterations: 3
  # auto_refine: true        # 循环直到评估器满意
  # max_iterations: 30       # auto_refine 模式的安全上限
  # 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 实现了一个多智能体管道，最多包含 7 个专门的智能体：

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

0. 输入优化器 并行运行两个 VLM 调用：
   • 上下文丰富器 将原始方法文本转换为适合图表生成的格式（组件、流程、分组、输入输出）
   • 标题锐化器 将模糊的标题转换为精确的视觉规格

阶段 1 -- 线性规划

1. 检索器 从精心挑选的 13 个方法图表参考集中选择最相关的示例，这些图表涵盖了智能体/推理、视觉/感知、生成/学习以及科学/应用等领域
2. 规划器 通过从检索到的示例中进行上下文学习，生成目标图表的详细文本描述
3. 风格器 使用 NeurIPS 风格指南（调色板、布局、排版）优化描述以提升视觉美感

阶段 2 -- 迭代优化

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

支持的提供商

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

📄 许可证

本项目采用 MIT 许可证。

免责声明

本项目是基于公开可用论文的独立开源重新实现，与原作者、Google Research 或北京大学没有任何关联、认可或联系。实现可能与论文中描述的原始系统有所不同，请自行决定是否使用。

引用

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

@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