academic-figure-generation

学术论文配图生成

PaperBanana（又称 PaperVizAgent）的轻量命令行包装器。PaperBanana 是一个用于学术论文配图生成的多 Agent 流水线。

该技能只提供一个脚本：scripts/generate.py。它会将方法文本和图注传入 PaperBanana，并生成 N 张候选 PNG。模型选择和 API 密钥均由 PaperBanana 自己的 configs/model_config.yaml 配置——此包装器不会覆盖这些设置。

一次性设置

1. 将 PaperBanana 克隆到方便的位置：

   git clone https://github.com/dwzhu-pku/PaperBanana.git ~/PaperBanana
   cd ~/PaperBanana
   uv venv && uv pip install -r requirements.txt
   

2. 配置 configs/model_config.yaml——设置图像模型和相应的 API 密钥。以下是两种常见配置：

   defaults:
     image_model_name: "gemini-3-pro-image-preview"   # or "openai/gpt-5.4-image-2"
     model_name: "gemini-3.1-pro-preview"             # text model for Planner/Stylist/Critic
   
   api_keys:
     google_api_key: "..."        # required for Gemini models
     openrouter_api_key: ""       # required for openai/gpt-5.4-image-2
   

   如果你有 Google AI 密钥，请使用 Gemini；如果你有 OpenRouter 密钥，请通过 OpenRouter 使用 GPT-Image-2。任选其一即可——无需配置其他内容。

工作流

步骤 1：收集输入

你需要：

1. 方法文本：论文中描述该方法的相关章节（./method.md 或 ./method.tex）。
2. 图注：目标图注，例如 "Figure 1: Overview of our framework"。

如果用户只提出了模糊的需求，请询问：

• 配图应重点呈现方法的哪个方面？
• 想要什么风格？（框图、流程图、流水线、架构图、对比图）
• 投稿会议 / 栏宽是多少？（ACL ≤ 7.5"，NeurIPS 单栏 5.5"）

步骤 2：生成

~/PaperBanana/.venv/bin/python scripts/generate.py \
  --paperbanana-root ~/PaperBanana \
  --method-file ./method.md \
  --caption "Figure 1: Overview of our framework" \
  --out-dir ./figures/v1 \
  --candidates 3 \
  --aspect-ratio 16:9

标志	默认值	说明
--paperbanana-root	（必需）	PaperBanana 克隆仓库的路径
--method-file	（必需）	方法章节所在的文本 / Markdown 文件
--caption	（必需）	目标图注
--out-dir	（必需）	PNG 文件的输出目录
--candidates	3	独立的配图候选数量
--max-concurrent	2	并发运行上限（请合理使用配额）
--exp-mode	demo_full	完整流水线（Planner+Stylist+Visualizer+Critic）。使用 demo_planner_critic 可跳过 Stylist，使用 vanilla 可进行单轮生成。
--aspect-ratio	16:9	可选值：21:9、16:9、3:2、1:1
--max-critic-rounds	2	评审 → 修改循环次数（如果评审者表示“无需修改”，则提前退出）

步骤 3：展示并迭代

• 向用户展示所有候选图。
• 常见的修改方向：配色方案、布局、标签文本、字号。
• 调整图注或增加候选数量后重新运行。

步骤 4：导出

• PNG 文件会以 candidate_0.png、candidate_1.png、……的名称写入 --out-dir。
• 如需用于投稿的 PDF：magick candidate_0.png candidate_0.pdf。

风格指南

• 颜色：使用一致且适合色盲读者的调色板
• 字体：与论文正文的字体保持一致（ACL/EMNLP 使用 Times，许多机器学习会议使用 Helvetica/Arial）
• 标签：简洁；图中不要使用完整句子
• 箭头：实线表示数据流，虚线表示可选流程 / 反馈循环
• 留白：避免过于拥挤——审稿人通常只用几秒钟浏览配图

常见图类型

类型	适用场景	关键元素
流水线 / 流程图	顺序处理	方框 + 箭头，从左到右或从上到下
架构图	系统概览	嵌套方框、清晰的模块边界
对比图	前后对比、基线与所提方法对比	并排面板
消融图	展示各组件的贡献	柱状图、高亮行
框架图	高层次概念概览	抽象图形、尽量少的细节

故障排除

• Gemini 上出现 429 RESOURCE_EXHAUSTED：已达到 Google AI Studio 月度支出上限。请前往 https://ai.studio/spend 提高上限，或将 image_model_name 切换为 openai/gpt-5.4-image-2 并设置 OPENROUTER_API_KEY。
• OpenRouter Client not initialized：环境变量中未设置 OPENROUTER_API_KEY，且 YAML 中也未设置 openrouter_api_key。
• 输出目录中没有 PNG 文件：检查 out_dir/results.json，查看原始的逐候选响应和任何错误消息。
• 延迟过长（>5 分钟）：大部分耗时来自图像模型。请减少 --candidates，或使用 --exp-mode vanilla 加快迭代。

链接

• PaperBanana 仓库：https://github.com/dwzhu-pku/PaperBanana
• PaperVizAgent（同一项目的 Google Research 版本）：https://github.com/google-research/papervizagent