AmadeusGPT

🪄 我们将行为的自然语言描述转化为机器可执行的代码。

🛠️ 安装 | 🌎 主页 | 🚨 新闻 | 🪲 问题报告 | 💬 讨论！

</div>

我们使用大型语言模型（LLMs）来连接自然语言和行为分析。
本研究发表于 NeurIPS2023！ 阅读论文 AmadeusGPT：用于交互式动物行为分析的自然语言接口，作者为 Shaokai Ye、Jessy Lauer、Mu Zhou、Alexander Mathis 和 Mackenzie W. Mathis。
喜欢这个项目吗？请考虑给我们一个星标 ⭐️！

什么是 AmadeusGPT？

由部分 DeepLabCut 开发团队成员开发的 AmadeusGPT 是一个自然语言接口，可将行为的自然语言描述转化为机器可执行的代码。 量化和分析动物行为的过程涉及将其动作的自然描述性语言转换为机器可读的代码。然而，如果没有深入理解动物行为和技术机器学习知识，编写行为分析代码通常具有挑战性，因此我们希望简化这一过程。简而言之，我们为您提供了一个"无代码"界面来分析动物的视频数据。如果您是 DeepLabCut 用户，这意味着您可以上传视频和 .h5 关键点文件，然后提出诸如"老鼠在开放场地中心停留了多长时间？"之类的问题。在我们的原始工作（NeurIPS 2023）中，我们使用 GPT3.5 和 GPT4 作为代理的一部分。我们继续支持最新的 OpenAI 模型，并正在积极开发这个项目。

开始使用：安装 AmadeusGPT🎻

[1] 设置 conda 环境：

Conda 是一个易于使用的 Python 接口，支持启动 Jupyter Notebooks。如果您完全不熟悉这个，我们建议查看这里的文档以安装 conda。否则，请使用我们提供的 conda 文件之一进行操作。如您所见，我们只需要最少的依赖项即可开始，这里有一个简单的分步指南供您参考设置（或参见下面的附加内容）。以下是快速开始命令：

conda env create -f amadeusGPT.yml

请注意，AmadeusGPT 使用的一些模块受益于 GPU 支持，因此我们建议您也准备一个 NVIDIA GPU 并安装 CUDA。

[2] 您需要一个 OpenAI 密钥：

为什么需要 OpenAI API 密钥 AmadeusGPT 依赖 OpenAI 的 API 调用（我们将在未来添加更多 LLM 选项）来进行语言理解和代码编写。在这里注册 OpenAI API 密钥。

然后，您可以在启动 conda 环境后，通过在终端中传递以下内容将其添加到您的环境中：

export OPENAI_API_KEY='您的 API 密钥'

或者在 Python 脚本或 Jupyter Notebook 中，如果您没有在终端阶段传递，请添加以下内容：

import os
os.environ["OPENAI_API_KEY"] = '您的 API 密钥'

[3] 🪄 就是这样！现在您已经安装了 AmadeusGPT！

请参阅下面的内容，了解如何开始使用！

开始使用：运行 AmadeusGPT🎻

我们提供了一个 StreamLit 应用程序，或者您可以在任何 Python 界面中使用 AmadeusGPT，例如 Jupyter notebooks。为此，我们建议从我们的演示开始：

使用示例 Jupyter Notebook 尝试 AmadeusGPT

您可以 git clone（或下载）此存储库以获取副本并开始使用。我们在这里提供了示例 notebooks！

这里有一些可以激发您自己工作的演示，请务必查看它们！

绘制感兴趣区域(ROI)并询问"动物何时在ROI内？"
使用您自己的数据 - (如果您还没有对应的DeepLabCut关键点文件，请确保使用GPU运行SuperAnimal！)
编写您自己的集成模块并使用它们。额外内容：源代码。如果添加新模块，请确保删除缓存的modules_embedding.pickle文件！
多动物社交互动
重复使用LLM生成的任务程序并在不同视频上运行
您可以在多个视频中进行一次查询。将关键点文件和视频文件（成对）放在同一文件夹中，并按照此演示中所示指定data_folder。确保您的视频文件和关键点文件遵循常规DeepLabCut约定，即前缀.mp4和前缀*.h5。

最简示例

import os
from amadeusgpt import create_project
from amadeusgpt import AMADEUS
from amadeusgpt.utils import parse_result

if 'OPENAI_API_KEY' not in os.environ:  
     os.environ['OPENAI_API_KEY'] = '你的密钥'

# 数据文件夹包含视频文件和可选的关键点文件
# 请注意上述描述的命名约定
data_folder = "temp_data_folder"
# 结果保存的位置
result_folder = "temp_result_folder"
# 创建项目
config = create_project(data_folder, result_folder, video_suffix = ".mp4")

# 创建AMADEUS实例
amadeus = AMADEUS(config)

query = "使用动物中心绘制动物轨迹，并按时间着色"
qa_message = amadeus.step(query)
# 我们简化了结果解析
parse_result(amadeus, qa_message)

使用本地WebApp尝试AmadeusGPT

您需要git克隆此仓库并在本地有一个副本。然后在您的环境中运行pip install 'amadeusGPT[streamlit]'
然后您可以打开终端，在目录中运行：

make app

[附加 - 通过自定义conda环境安装]

如果您想设置自己的环境，

conda create -n amadeusGPT python=3.10

需要安装的关键依赖项是：

pip install notebook
conda install hdf5
conda install pytables==3.8
# 如果您想在自己的视频上使用SuperAnimal，请安装pip install deeplabcut==3.0.0rc4

pip install amadeusgpt

引用

如果您在工作中使用了本项目的想法或代码，请使用以下BibTeX条目引用我们。🙏

@article{ye2023amadeusGPT,
      title={AmadeusGPT: a natural language interface for interactive animal behavioral analysis}, 
      author={Shaokai Ye and Jessy Lauer and Mu Zhou and Alexander Mathis and Mackenzie Weygandt Mathis},
      journal={Thirty-seventh Conference on Neural Information Processing Systems},
      year={2023},
      url={https://openreview.net/forum?id=9AcG3Tsyoq},

arXiv预印本版本 AmadeusGPT：用于交互式动物行为分析的自然语言界面 作者：Shaokai Ye、Jessy Lauer、Mu Zhou、Alexander Mathis 和 Mackenzie W. Mathis。

许可证

AmadeusGPT采用Apache-2.0许可证。

🚨 请注意，几个关键依赖项有自己的许可证。请仔细检查DeepLabCut（LGPL-3.0许可证）、SAM（Apache-2.0许可证）等的许可证信息。

常见问题：

我是否需要提供关键点文件，还是只有视频就足够开始使用？

如果您只提供视频文件，我们使用SuperAnimal模型来预测您视频中的动物。虽然我们强烈建议使用GPU安装，但我们正在开发更快、更轻量级的SuperAnimal模型，以在您的CPU上运行。
如果您已经有与视频文件对应的关键点文件，请查看我们在Notebooks中如何设置配置文件。目前我们只支持DeepLabCut的关键点输出。