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