🔥 请查看我们的新作 CodeNav，它克服了 VisProg 的诸多局限，并对其进行了进一步的泛化：🔥

✅ 编写工具描述 直接指向你希望 CodeNav 代理使用的代码库——没错，就是原始源代码！——CodeNav 会直接对源代码进行索引和搜索
✅ 一次性生成整个程序 CodeNav 会迭代式地生成代码（这些代码会从你的代码库中导入并调用函数和类），执行后根据执行结果决定下一步操作。下一步可能是继续在代码库中搜索，或者编写更多代码
✅ 每行只生成一个函数调用 CodeNav 可以生成自由格式的代码——你可以把它想象成在 IPython 笔记本中编写代码单元格一样。在执行当前代码块时，CodeNav 能够访问之前代码块执行过程中创建的全局变量
✅ 遇到执行错误就放弃 CodeNav 会查看包括错误、新创建的变量以及 STDOUT 在内的执行结果，并尝试在下一步修复错误
✅ 将工具实现为简单的函数调用 CodeNav 为工具开发者提供了极大的灵活性，可以根据需要构建功能完善的代码库——可以使用抽象、面向对象编程等方法——总之，遵循良好的软件开发实践即可（有意义的类/函数/变量名、文档字符串、在代码中明确指定参数类型都有帮助）

视觉编程：无需训练的组合式视觉推理（CVPR 2023 年最佳论文！）

作者：Tanmay Gupta 和 Aniruddha Kembhavi

[ 项目页面 | Arxiv 论文 | 博客 ]

本仓库包含 VisProg 的官方代码——这是一种神经符号系统，能够根据自然语言指令解决复杂且具有组合性的视觉任务。VisProg 利用 GPT-3 的上下文学习能力生成 Python 程序，然后执行这些程序以获得解决方案以及全面且可解释的推理过程。生成的每一行程序都可能调用现成的计算机视觉模型、图像处理例程或 Python 函数，从而产生中间输出，供程序后续部分使用。

该代码库的设计目标是：

:white_check_mark: 易于使用（每个任务只需一个简单的 ipynb 文件）
:white_check_mark: 易于扩展 新功能 ——只需向 VisProg 添加新模块即可
:white_check_mark: 易于扩展到 新任务 ——只需添加针对这些任务的上下文示例即可
:white_check_mark: 极简且模块化，便于深入研究和在此基础上进一步开发

安装依赖

conda env create -f environment.yaml
conda activate visprog

运行笔记本

设置并激活 Conda 环境后，你就可以开始运行 notebooks/ 文件夹中的笔记本了。如果你使用 VSCode 等编辑器，在 VSCode 中直接打开 .ipynb 文件可能是最简便的入门方式。

你会发现以下每个任务都有对应的笔记本，但它们的结构非常相似：

• 外部知识物体标注：notebooks/ok_det.ipynb
• 自然语言图像编辑：notebooks/image_editing.ipynb
• NLVR：notebooks/nlvr.ipynb
• GQA：notebooks/gqa.ipynb

只需在当前写着 <Enter your key here> 的单元格中输入你的 OpenAI API 密钥，然后运行笔记本即可。这些笔记本都是自包含的，应该能够从头到尾顺利运行，无需额外设置。

笔记本的基本结构如下：

• 设置路径
• 将 OPENAI_API_KEY 环境变量设置为使用 GPT-3
• 导入 ProgramGenerator 和 ProgramInterpreter 类
• 导入 PROMPT（包含上下文示例的文本字符串）或 create_prompt（动态生成提示语的函数）
• 创建 ProgramGenerator 和 ProgramInterpreter 对象
• 加载用于推理的图像或图像集
• 指定自然语言问题/陈述/指令
• 使用 ProgramGenerator 根据指定指令生成程序
• 使用 ProgramInterpreter 解释并执行程序
• 可视化返回的结果及可视化推理过程（执行轨迹）

示例输出

我们尽量让执行轨迹的每一步都易于可视化。

例如，当你在 assets/camel1.png 上运行 gqa 笔记本，指令为“图片中有多少人或动物？”时，你应该会看到以下输出：

程序

BOX0=LOC(image=IMAGE,object='people')
BOX1=LOC(image=IMAGE,object='animals')
ANSWER0=COUNT(box=BOX0)
ANSWER1=COUNT(box=BOX1)
ANSWER2=EVAL(expr="{ANSWER0} + {ANSWER1}")
FINAL_RESULT=RESULT(var=ANSWER2)

可视化推理过程

如果 VisProg 无法解决你的任务怎么办？

有可能你提供的指令无法被 VisProg 正确解决。这可能有以下几个原因：

1. 你的指令与 VisProg 之前见过的上下文示例差异较大。在这种情况下，即使当前的模块集合足以解决问题，VisProg 也可能因为程序生成不正确而失败。此时，你可以尝试使用 VisProg 的模块手动编写一个能解决问题的程序。如果成功，可以将这个程序加入上下文示例中，然后重新运行笔记本以处理类似的指令。
2. 当前 VisProg 中的模块集合无法解决该问题。如果是这种情况，你可以向 VisProg 添加新的模块来解决这个问题。详情请参阅下一节。

添加新功能及解决新任务的能力

• 在 engine/step_interpreters.py 中添加用于实现这些功能的新模块。别忘了在同一文件中的 register_step_interpreters 函数中注册这些模块。以下是 COUNT 模块的步骤解释器。所有模块都具有类似的结构，包含 parse、html 和 execute 三个函数。parse 函数解析程序字符串，提取参数和输出变量；html 函数生成执行轨迹的 HTML 表示；execute 函数执行模块，并返回输出结果以及（若 inspect=True）执行轨迹的 HTML。

  class CountInterpreter():
      step_name = 'COUNT'
  
      def __init__(self):
          print(f'注册 {self.step_name} 步骤')
  
      def parse(self,prog_step):
          parse_result = parse_step(prog_step.prog_str)
          step_name = parse_result['step_name']
          box_var = parse_result['args']['box']
          output_var = parse_result['output_var']
          assert(step_name==self.step_name)
          return box_var,output_var
  
      def html(self,box_img,output_var,count):
          step_name = html_step_name(self.step_name)
          output_var = html_var_name(output_var)
          box_arg = html_arg_name('bbox')
          box_img = html_embed_image(box_img)
          output = html_output(count)
          return f"""<div>{output_var}={step_name}({box_arg}={box_img})={output}</div>"""
  
      def execute(self,prog_step,inspect=False):
          box_var,output_var = self.parse(prog_step)
          boxes = prog_step.state[box_var]
          count = len(boxes)
          prog_step.state[output_var] = count
          if inspect:
              box_img = prog_step.state[box_var+'_IMAGE']
              html_str = self.html(box_img, output_var, count)
              return count, html_str
  
          return count
  

• 将你的上下文示例添加到新文件 prompts/your_task_or_dataset_name.py 中。请注意，除了使用上下文示例来生成程序之外，你还可以尝试其他提示方式，例如提供函数签名和文档字符串，而无需对代码进行任何更改！

• 现在你可以使用类似于 notebooks/ 文件夹中的笔记本，来玩转该数据集中的示例，或者编写一个 Python 脚本来对大量示例进行推理。

这就是 VisProg 目前能够做到的

当前可用模块概览

*请注意，我们已将用于 VQA 的 ViLT 替换为性能更优的 BLIP 模型，该模型最近已在 Huggingface 上发布。这表明在 VisProg 中替换或升级模块是多么容易。

自 CVPR 论文所用版本以来的变更

• GPT3 从 text-davinci-002 升级到 text-davinci-003
• VQA 模块从 ViLT 升级为性能更强的 BLIP

引用

如果你的研究中使用了这段代码，请考虑引用以下文献：

@article{Gupta2022VisProg,
  title={Visual Programming: Compositional visual reasoning without training},
  author={Tanmay Gupta and Aniruddha Kembhavi},
  journal={ArXiv},
  year={2022},
  volume={abs/2211.11559}
}

VisProg 快速上手指南

VisProg 是一个神经符号系统，能够利用 GPT-3 的上下文学习能力，根据自然语言指令生成并执行 Python 程序，从而解决复杂的组合式视觉任务（如视觉问答、图像编辑等）。无需额外训练即可使用。

环境准备

• 操作系统: Linux / macOS (Windows 需使用 WSL)
• Python 版本: 推荐 Python 3.8+
• 前置依赖:
  • Conda (推荐使用 Miniconda 或 Anaconda)
  • OpenAI API Key (用于调用 GPT-3 模型)
• 网络要求: 由于需要连接 OpenAI API 和 Hugging Face 下载模型，请确保网络通畅。国内用户建议配置代理或使用加速镜像。

安装步骤

1. 克隆仓库

   git clone https://github.com/allenai/visprog.git
   cd visprog
   

2. 创建并激活 Conda 环境 项目提供了 environment.yaml 文件以自动安装所有依赖（包括 PyTorch, Transformers, BLIP 等）。

   conda env create -f environment.yaml
   conda activate visprog
   

   提示: 如果 conda env create 速度较慢，国内用户可尝试指定清华源： conda env create -f environment.yaml --channel https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/

基本使用

VisProg 的设计初衷是“开箱即用”，每个任务都对应一个独立的 Jupyter Notebook。以下以 GQA (视觉问答) 任务为例：

1. 启动 Notebook

在激活 visprog 环境后，使用 Jupyter Lab 或 VS Code 打开对应的笔记本文件：

jupyter notebook notebooks/gqa.ipynb

(其他可用任务见 notebooks/ 目录，如 image_editing.ipynb, nlvr.ipynb 等)

2. 配置 API Key

在 Notebook 中找到标记为 <Enter your key here> 的代码单元格，填入你的 OpenAI API Key：

import os
os.environ["OPENAI_API_KEY"] = "sk-..." # 在此处填入你的密钥

3. 运行流程

按顺序执行 Notebook 中的单元格，核心流程如下：

1. 初始化: 导入 ProgramGenerator 和 ProgramInterpreter 类。
2. 加载数据: 加载目标图片（例如 assets/camel1.png）。
3. 输入指令: 定义自然语言问题，例如：

   instruction = "How many people or animals are in the image?"
   

4. 生成程序: 调用 ProgramGenerator 将指令转化为可执行的 Python 代码序列。
   • 生成的示例代码:

     BOX0=LOC(image=IMAGE,object='people')
     BOX1=LOC(image=IMAGE,object='animals')
     ANSWER0=COUNT(box=BOX0)
     ANSWER1=COUNT(box=BOX1)
     ANSWER2=EVAL(expr="{ANSWER0} + {ANSWER1}")
     FINAL_RESULT=RESULT(var=ANSWER2)
     

5. 执行与可视化: 调用 ProgramInterpreter 执行上述代码，系统将自动调用视觉模型（如 BLIP, Detectron2 等）并输出最终答案及可视化的推理过程（Visual Rationale）。

4. 查看结果

执行完毕后，Notebook 将直接显示：

• 最终答案: 问题的直接回答。
• 推理轨迹: 每一步操作的中间结果（如检测框、计数值）及其对应的可视化图像，帮助理解模型的决策过程。

---

注：若需扩展新功能或适配新任务，可参考原文档中关于添加模块 (engine/step_interpreters.py) 和提示词 (prompts/) 的说明。