PaperBanana-CN

<!-- mcp-name: io.github.llmsresearch/paperbanana --> <table align="center" width="100%" style="border: none; border-collapse: collapse;"> <tr> <td width="220" align="left" valign="middle" style="border: none;"> <img src="paperbanana/studio/assets/paperbanana-cn-logo.jpg" alt="PaperBanana-CN Logo" width="180"/> </td> <td align="left" valign="middle" style="border: none;"> <h1>PaperBanana-CN V2</h1> <p><strong>具有独立模型连接和中文工作室的PaperBanana</strong></p> <p> <a href="https://github.com/mituan-ai/PaperBanana-CN/actions/workflows/ci.yml"><img src="https://github.com/mituan-ai/PaperBanana-CN/actions/workflows/ci.yml/badge.svg" alt="CI"/></a> <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.10%2B-blue?logo=python&logoColor=white" alt="Python 3.10+"/></a> <a href="https://arxiv.org/abs/2601.23265"><img src="https://img.shields.io/badge/arXiv-2601.23265-b31b1b?logo=arxiv&logoColor=white" alt="arXiv"/></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?logo=opensourceinitiative&logoColor=white" alt="License: MIT"/></a> </p> </td> </tr> </table> --- > **版本通知**: `main` 是 PaperBanana-CN V2，已发布为 [`v2.0.0`](https://github.com/mituan-ai/PaperBanana-CN/releases/tag/v2.0.0)。冻结的 V1 实现及其完整历史记录分别保留在 [`v1`](https://github.com/mituan-ai/PaperBanana-CN/tree/v1) 分支和 [`v1.0.0`](https://github.com/mituan-ai/PaperBanana-CN/releases/tag/v1.0.0) 版本中。 > **免责声明**: 这是论文 *"PaperBanana: Automating Academic Illustration for AI Scientists"* 的**非官方、社区驱动的开源实现**，作者为 Dawei Zhu、Rui Meng、Yale Song、Xiyu Wei、Sujian Li、Tomas Pfister 和 Jinsung Yoon ([arXiv:2601.23265](https://arxiv.org/abs/2601.23265))。本项目**不隶属于或得到**原作者或 Google Research 的任何认可。本实现基于公开可用的论文，可能与原始系统有所不同。 PaperBanana-CN 保留了上游 PaperBanana 的研究插图工作流程，并添加了三个产品级功能： - 独立保存的 VLM 和图像生成器的连接。每个角色都有自己的提供商、基准 URL、API 密钥、模型和超时时间。 - 优先考虑中文的 Studio，带有英文本地化界面。界面语言不会更改提示或图表中使用的语言。 - 共享的十个宽高比和 `1K` / `2K` / `4K` 分辨率控制，在生成前针对选定的图像提供商进行验证。 上游的多智能体管道、统计图、评估、批量生成、编排、运行继续、CLI 和 MCP 工作流程仍然保持不变。 - 两阶段多智能体管道，具有迭代细化 - 多个 VLM 和图像生成提供商（OpenAI、Azure、Gemini、Atlas Cloud） - 更好的生成质量的输入优化层 - 自动细化模式和带有用户反馈的运行继续 - CLI、Python API 和用于 IDE 集成的 MCP 服务器 - **批量生成**，从清单文件（YAML/JSON）生成多个图表 - **批量绘图** - `paperbanana plot-batch` 从一个清单（CSV/JSON）运行许多统计图 - **PDF 输入**，用于方法论上下文（可选 `paperbanana[pdf]` / PyMuPDF），每页选择 - **PaperBanana Studio** - 用于图表、绘图、评估、批量和运行浏览器的本地 Gradio Web UI - 用于 `/generate-diagram`、`/generate-plot` 和 `/evaluate-diagram` 的 Claude Code 技能 <p align="center"> <img src="assets/img/hero_image.png" alt="PaperBanana takes paper as input and provide diagram as output" style="max-width: 960px; width: 100%; height: auto;"/> </p> ## Atlas Cloud <p align="center"> <img src="assets/sponsors/atlas_cloud_logo.png" alt="Atlas Cloud Logo" width="180"/> </p> Atlas Cloud 是一个全模态 AI 推理平台，为开发者提供单一的 AI API，以访问视频生成、图像生成和 LLM API。与其管理多个供应商集成，您只需连接一次，即可统一访问 300+ 个精选模型，涵盖所有模态。 请查看 Atlas Cloud 的新编码计划促销活动，以获得更经济实惠的 API 访问权限：[https://www.atlascloud.ai/console/coding-plan](https://www.atlascloud.ai/console/coding-plan?utm_source=github&utm_medium=link&utm_campaign=paperbanana) --- ## 快速入门 ### 先决条件 - Python 3.10+ - OpenAI API 密钥 ([platform.openai.com](https://platform.openai.com/api-keys)) 或 Azure OpenAI / Foundry 端点 - 或 Google Gemini API 密钥（免费，[Google AI Studio](https://makersuite.google.com/app/apikey)） ### 步骤 1：安装 PaperBanana-CN ```bash git clone https://github.com/mituan-ai/PaperBanana-CN.git cd PaperBanana-CN pip install -e ".[openai,google,studio,mcp]" ``` #### Docker 从存储库克隆并在运行时传递您的 API 密钥，构建镜像： ```bash docker build -t paperbanana . docker run --rm -e GOOGLE_API_KEY paperbanana generate --help ``` 要生成图表，请将输入和输出文件夹挂载到 `/work`： ```bash docker run --rm -e GOOGLE_API_KEY \ -v "$(pwd)/method.txt:/work/method.txt:ro" \ -v "$(pwd)/outputs:/work/outputs" \ paperbanana generate --legacy-connections \ --input method.txt --caption "Overview of our framework" ``` ### 步骤 2：保存两个模型连接 ```bash paperbanana connections add \ --role vlm \ --name "My VLM" \ --provider openai \ --base-url https://relay.example.com/v1 \ --model your-vlm-model paperbanana connections add \ --role image \ --name "My image model" \ --provider openai_imagen \ --base-url https://image-relay.example.com/v1 \ --model your-image-model \ --size-mode explicit_pixels ``` 每个命令都会提示输入该角色的 API 密钥，而不会回显。使用适配器和 `--size-mode` 以匹配端点的实际协议；`explicit_pixels` 仅在图像端点接受任意 `WIDTHxHEIGHT` 大小时才适用。检查或测试保存的配置文件： ```bash paperbanana connections list paperbanana connections test <vlm-profile-id> paperbanana connections test <image-profile-id> # local validation only paperbanana connections test <image-profile-id> --paid # sends a real test image request ``` 最近保存的每个角色的配置文件将成为活动配置文件。非机密配置文件数据和 API 密钥分别存储在操作系统的私有应用程序目录中；密钥永远不会写入存储库 YAML 或运行元数据中。参见 [连接配置](docs/CONNECTIONS.md)。 ### 步骤 3：生成图表 ```bash paperbanana generate \ --input examples/sample_inputs/transformer_method.txt \ --caption "Overview of our encoder-decoder architecture with sparse routing" ``` 启用输入优化和自动细化： ```bash 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） 从步骤 1 中启动已安装的 Studio： ```bash paperbanana studio ``` 打开终端中显示的 URL（默认为 `http://127.0.0.1:7860/`）。桌面版 Studio 有九个生产页面：方法论图表、统计图、比较评估、继续先前的运行、论文编排、方法论或图表批次、参数扫描、确定性多图像合成和 `run_*` / `batch_*` 输出的浏览器。基准测试、消融、数据集、场地管理、润色、IR 再生和 TikZ 工具仍然可通过 CLI 或 MCP 访问，而不会在 Studio 中重复。 Studio 默认以中文打开。其 VLM 和图像连接编辑器支持创建、复制、重命名、删除、测试和显式保存配置文件以供使用。API 密钥永远不会填充回浏览器；空密钥字段保留保存的值。中文和英文共享一个 Studio 页面，立即切换，无需导航、刷新或 Gradio 设置对话框。偏好设置在重新加载后被记住，不会更改生成的图表中使用的语言。 --- ## 工作原理 PaperBanana 实现了一个多智能体管道，最多可有 7 个专用智能体： **第 0 阶段 - 输入优化（可选， `--optimize`）：** 0. **输入优化器** 运行两个并行的 VLM 调用： - **上下文丰富器** 将原始方法论文本结构化为图表-ready 格式（组件、流程、分组、I/O） - **标题锐化器** 将模糊的标题转换为精确的视觉规格 **第 1 阶段 - 线性规划：** 1. **检索器** 从 13 个精选的方法论图表中选择最相关的参考示例，涵盖代理/推理、视觉/感知、生成/学习和科学/应用领域 2. **规划器** 通过上下文学习从检索的示例中生成目标图表的详细文本描述 3. **风格化器** 使用 NeurIPS 风格指南（颜色调色板、布局、字体排版）细化描述以实现视觉美学 **第 2 阶段 - 迭代细化：** 4. **可视化器** 将描述渲染为图像 5. **批评者** 评估生成的图像是否符合源上下文，并提供修订后的描述以解决任何问题 6. 步骤 4-5 重复固定次数（默认为 3），或直到批评者满意（ `--auto`） ## 提供商 PaperBanana 支持多个 VLM 和图像生成提供商： | 组件 | 提供商 | 模型 | 备注 | |-----------|----------|-------|-------| | VLM（规划、批评） | OpenAI | `gpt-5.2` | OpenAI 兼容适配器 | | 图像生成 | 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` | 旧版设置默认值 | | VLM / Image | OpenRouter | 任意支持的模型 | 灵活路由 | OpenAI 兼容和 Gemini 兼容的端点可以在保存的配置文件中按角色选择。 以下环境变量保留用于显式旧版模式。 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](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](https://www.atlascloud.ai/models?utm_source=github&utm_medium=link&utm_campaign=paperbanana) - 并且可以使用 `ATLASCLOUD_VLM_MODEL` 传递任何列出的模型 ID。 推荐的 `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` -- 方法论图表 ```bash # 基本生成 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 # PDF 作为输入（安装 PyMuPDF：pip install 'paperbanana[pdf]'） paperbanana generate \ --input paper.pdf \ --caption "Overview of our method" \ --pdf-pages "3-8" # 指南生成带有参考/草图图像（可重复） paperbanana generate \ --input method.txt \ --caption "Overview of our framework" \ --image sketch.png --image prior_figure.png` ``` | 标志 | 短 | 描述 | |------|-------|-------------| | `--input` | `-i` | 方法论文本文件或 PDF 的路径（新运行所需） | | `--caption` | `-c` | 图表标题 / 交流意图（新运行所需） | | `--image` | | 参考/草图图像（手绘草图、白板照片、先前图表）用于指导规划器。可重复使用多个图像 | | `--output` | `-o` | 输出图像路径（默认：在 `outputs/` 中自动生成） | | `--iterations` | `-n` | 可视化器-批评者细化轮数（默认：3） | | `--num-candidates` | `-k` | 并行生成 N 个候选图像，1-8（默认：1）。规划器运行一次；细化根据种子偏移量扩展到每个候选人。输出位于 `candidates/cand_<i>/`；运行根 `final_output` 是候选人 1。成本估算和 `--budget` 账户会考虑分支 | | `--auto` | | 循环直到批评者满意（带有 `--max-iterations` 安全上限） | | `--max-iterations` | | `--auto` 模式的安全上限（默认：30） | | `--optimize` | | 使用并行上下文丰富和标题锐化预处理输入 | | `--continue` | | 从 `outputs/` 中的最新运行继续 | | `--continue-run` | | 从特定的运行 ID 继续 | | `--feedback` | | 继续运行时的用户反馈 | | `--pdf-pages` | | PDF 输入仅：1-based 页（例如 `1-5`, `2,4,6-8`；默认：全部） | | `--vlm-provider` | | 旧模式 VLM 提供商名称 | | `--vlm-model` | | 旧模式 VLM 模型名称 | | `--image-provider` | | 旧模式图像提供商名称 | | `--image-model` | | 旧模式图像模型名称 | | `--vlm-connection` | | 保存的 VLM 配置文件 ID；否则使用活动 VLM 配置文件 | | `--image-connection` | | 保存的图像配置文件 ID；否则使用活动图像配置文件 | | `--legacy-connections` | | 显式使用上游 YAML/环境连接设置 | | `--aspect-ratio` | `-ar` | 之一 `1:1`, `4:3`, `3:2`, `5:4`, `16:9`, `21:9`, `4:5`, `3:4`, `2:3`, `9:16` | | `--resolution` | | 图像分辨率层级：`1K`, `2K`, 或 `4K` | | `--format` | `-f` | 输出格式：`png`, `jpeg`, 或 `webp`, | `--config` | | YAML 配置文件路径（参见 `configs/config.yaml`） | | `--verbose` | `-v` | 显示详细的代理进度和计时 | | `--progress-json` | | 将 JSON 进度事件发出到 stdout | ### `paperbanana batch` -- 批量生成 从单个清单文件（YAML 或 JSON）生成多个方法图。每个项目都运行完整的管道；输出被写入 `outputs/batch_<id>/run_<id>/` 目录下，同时生成一个 `batch_report.json` 文件来总结所有运行结果。 ```bash paperbanana batch --manifest examples/batch_manifest.yaml --optimize ``` 清单格式（YAML 或 JSON，包含 `items` 列表）： ```yaml 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" # 可选；仅限 PDF 输入 ``` 清单文件中的路径是相对于清单文件目录的。 **复合图表：** 添加一个可选的 `composite` 部分，以便在批量完成后自动将所有生成的面板拼接成一个带有标签的图表： ```yaml composite: layout: "1x3" # 行 x 列，或 "auto" labels: auto # (a), (b), (c)... 或显式列表，或 null spacing: 20 # 面板之间的像素间距 label_position: bottom # top 或 bottom output: "composite.png" items: - input: method_encoder.txt caption: "Encoder architecture" id: panel_a # ... ``` 复合图像与单个面板一起保存在批量输出目录中。参见 `examples/composite_batch_manifest.yaml` 获取完整示例。 **生成人类可读报告** 从现有的批量运行（Markdown 或 HTML）： ```bash 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 ``` 图表批量报告包含 `batch_kind: methodology`；绘图批量使用 `batch_kind: statistical_plot`。人类可读报告（`paperbanana batch-report`）在存在时显示批量类型。 **扫描清单** 允许您将整个扫描计划存储为 YAML/JSON 而不是八个逗号分隔的 CLI 标志。相互排斥的轴标志；参见 `examples/sweep_manifest.yaml`。 ```bash paperbanana sweep --manifest examples/sweep_manifest.yaml ``` **扫描报告** 由 `paperbanana sweep` 生成，可以以相同的方式渲染： ```bash paperbanana sweep-report --sweep-dir outputs/sweep_20250109_123456_abc --format html # 或按扫描 ID paperbanana sweep-report --sweep-id sweep_20250109_123456_abc --format markdown ``` 渲染的扫描报告包括摘要、排名前 5 的表格、完整的变量表格（带有每个变量的提供者/模型、迭代次数、批评者建议计数、代理分数和输出路径），以及 `quality_proxy_score` 注释。Dry-run 报告渲染一个简化的“计划变量”部分。 | 标志 | 简写 | 描述 | |------|-------|-------------| | `--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）和一个 **intent** 字符串，镜像 `paperbanana plot`。输出位于 `outputs/batch_<id>/run_<id>/` 目录下，带有相同的 `batch_report.json` 和 `paperbanana batch-report` 工作流程。 ```bash paperbanana plot-batch --manifest examples/plot_batch_manifest.yaml --optimize ``` 清单格式（`items` 列表）： ```yaml 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" # 可选，每个项目；省略时默认为 CLI --aspect-ratio ``` 路径是相对于清单文件目录的。 | 标志 | 简写 | 描述 | |------|-------|-------------| | `--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` | | 保留提示（默认：on，与 `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` 的软件包文件夹 ```bash 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)` 子面板标签的单个带标签图表： ```bash 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` 禁用（默认：auto `(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 对生成的图表与人类参考进行比较评估： ```bash 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 为基数的页面选择（默认：全部） | 四个维度上的评分（按论文分层聚合）： - **主要**：忠实度，可读性 - **次要**：简洁性，美学性 ### `paperbanana polish` -- 精炼现有图表 自带图表：VLM 审核图表是否符合会议风格指南，并提出最多 10 个具体、可行的改进建议，然后图像编辑提供者将这些建议应用于原始图表（引导编辑）。建议打印到控制台，以便您确切地看到更改了什么。 ```bash 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` | 并行应用每轮的建议 N 次（1-8） | | `--budget` | | 美元上限；当超出时，精炼会优雅地停止 | | `--seed` | | 可复制编辑的随机种子 | 需要支持引导图像编辑的图像提供者（Google Gemini 图像模型）。如果图表已经符合风格指南，则无需修改即可退出。 ### `paperbanana studio` -- 本地 Web UI 需要 `pip install 'paperbanana[studio]'`（Studio 依赖项固定为 Gradio `6.20.0`）。 ```bash 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` -- 首次配置 ```bash paperbanana setup ``` 旧版配置向导，首先询问是否使用官方 Gemini API。如果选择官方 API，则遵循默认 AI Studio 密钥流程；如果不选择，则询问自定义 Gemini 兼容 URL 和 API 密钥。命令默认使用保存的配置文件。传递 `--legacy-connections` 到生成命令，当您故意使用 `.env`、环境变量或上游 YAML 提供者字段时。 ### `paperbanana data` -- 参考数据集 ```bash # 下载 PaperBananaBench 参考集（约 254 MB，一条命令） paperbanana data download # 导入绘图参考（或两者） paperbanana data download --task plot paperbanana data download --task both # 检查/清除缓存 paperbanana data info paperbanana data clear ``` 数据集从项目托管的 GitHub 发布镜像 （[`bench-data-v1`](https://github.com/llmsresearch/paperbanana/releases/tag/bench-data-v1)） 提供，其 SHA256 校验和在提取前会进行验证。致谢 [PaperBananaBench](https://huggingface.co/datasets/dwzhu/PaperBananaBench) 作者 — 镜像跟踪他们的 2026-03-22 修订版。数据集缓存在 `~/.cache/paperbanana/` 下（使用 `PAPERBANANA_CACHE_DIR` 覆盖）；生成 命令也可以在首次使用时通过 `--auto-download-data` 获取。 --- ## Python API ```python 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}") ``` **进度回调：** `generate()` 和 `continue_run()` 接受一个可选的 `progress_callback` 参数。管道使用 `PipelineProgressEvent` 对象（阶段、消息、秒、迭代、额外）在每个步骤（优化器、检索器、规划器、造型师、视觉化工具、批评者）调用它，以便您可以在 UI 中显示进度或记录时间，而无需修补代理。 继续上一次运行： ```python 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-CN 包含一个用于 Claude Code、Cursor 和其他 MCP 兼容客户端的 MCP 服务器。 安装此存储库并配置两个活动连接配置文件，然后添加： ```json { "mcpServers": { "paperbanana": { "command": "paperbanana-mcp" } } } ``` 暴露了 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`. 工具接受显式 VLM/图像配置文件 ID；否则它们使用活动配置文件。Legacy 环境/变量设置仅在工具调用显式设置 `legacy_connections=true` 时应用。 存储库还附带 3 个 Claude Code 技能： - `/generate-diagram <file> [caption]` - 从文本文件生成方法图 - `/generate-plot <data-file> [intent]` - 从 CSV/JSON 数据生成统计图 - `/evaluate-diagram <generated> <reference>` - 评估图表与人类参考 参见 [`mcp_server/README.md`](mcp_server/README.md) 获取完整设置详情（Claude Code、Cursor、本地开发）。 --- ## Overleaf 集成（GitHub Action） 保持论文的方法图表与文本同步 — 自动。PaperBanana 配备了一个 GitHub Action，与 Overleaf 的内置 GitHub 同步配对：推送 `.tex` 更改，操作提取方法部分，生成图表，然后提交图像和准备好的 LaTeX 片段。在 Overleaf 中拉取，它就在您的文件树中。 ```yaml - 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`](integrations/github-action/README.md) 获取完整工作流程、所有输入和成本控制选项。 --- ## 配置 PaperBanana-CN 生成入口点默认使用保存的 VLM 和图像配置文件。管道 YAML 继续配置非连接设置，例如精炼、输出、检索和会议。YAML 和环境变量中的提供者/模型字段仅在显式旧版模式下读取；配置文件 ID 和旧版提供者选项不能在单个命令中混合使用。 使用自定义 YAML 配置非连接管道设置： ```bash paperbanana generate \ --input method.txt \ --caption "Overview" \ --config my_config.yaml ``` 配置文件模式的 YAML 必须省略 `vlm` 和 `image` 连接字段： ```yaml 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 ``` 附带的 `configs/config.yaml` 保留了显式旧版模式的上游提供者部分。旧版环境变量（`.env`）包括： ```bash # 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 # 覆盖模型 # 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 默认配置 GOOGLE_API_KEY=你的密钥 GOOGLE_BASE_URL= # 可选自定义 Gemini 兼容端点 GOOGLE_VLM_MODEL=gemini-2.5-flash # 覆盖 Gemini VLM 模型 GOOGLE_IMAGE_MODEL=gemini-3-pro-image-preview # 覆盖 Gemini 图片模型 --- ## 项目结构 ``` paperbanana/ ├── paperbanana/ │ ├── core/ # 管道编排、类型、配置、恢复、实用工具 │ ├── agents/ # 优化器、检索器、规划器、造型师、可视化器、评论家 │ ├── connections/ # 保存的 VLM/图片配置文件、密钥和配置文件解析 │ ├── i18n/ # 中文和英文工作室目录 │ ├── providers/ # VLM 和图片生成提供商实现 │ │ ├── vlm/ # OpenAI、Atlas Cloud、Gemini、OpenRouter VLM 提供商 │ │ └── image_gen/ # OpenAI、Atlas Cloud、Gemini、OpenRouter 图片生成提供商 │ ├── reference/ # 参考集管理（13 个精选示例） │ ├── guidelines/ # 样式指南加载器 │ └── evaluation/ # VLM-as-Judge 评估系统 ├── configs/ # YAML 配置文件 ├── prompts/ # 所有代理 + 评估的提示模板 │ ├── diagram/ # 上下文增强器、标题锐化器、检索器、规划器、造型师、可视化器、评论家 │ ├── plot/ # plot 特定提示变体 │ └── evaluation/ # 真实性、简洁性、可读性、美观性 ├── data/ │ ├── reference_sets/ # 13 个验证方法图 │ └── guidelines/ # NeurIPS 风格美学指南 ├── examples/ # 工作示例脚本 + 示例输入 ├── scripts/ # 数据管理和构建脚本 ├── tests/ # 测试套件 ├── mcp_server/ # 用于 IDE 集成的 MCP 服务器 └── .claude/skills/ # Claude Code 技能（生成图表、生成绘图、评估图表） ``` ## 开发 ```bash # 安装开发依赖 pip install -e ".[dev,openai,google]" # 运行测试 pytest tests/ -v # 检查代码风格 ruff check paperbanana/ mcp_server/ tests/ scripts/ # 格式化代码 ruff format paperbanana/ mcp_server/ tests/ scripts/ ``` ## 引用 这是一个**非官方**实现。如果您使用此作品，请引用**原始论文**： ```bibtex @article{zhu2026paperbanana, title={PaperBanana: 为 AI 科学家自动生成学术插图}, author={朱大为 and 孟睿 and 宋雅乐 and 魏西宇 and 李素剑 and Pfister, Tomas and Yoon, Jinsung}, journal={arXiv 预印本 arXiv:2601.23265}, year={2026} } ``` **原始论文**：[https://arxiv.org/abs/2601.23265](https://arxiv.org/abs/2601.23265) ## 免责声明 本项目是基于公开可用的论文的独立开源重新实现。它与原作者、谷歌研究院或 北京大学没有任何关联、认可或联系。实现可能与论文中描述的原始系统有所不同。 请自行判断使用风险。 ## 许可证 MIT