快速链接

• 文档
• PyPI 包
• 贡献指南
• 许可证

在本 README 中

• 快速入门
• 安装
  • 使用 pip 安装
  • 使用 Conda 安装
  • 从源码安装
  • 检查安装
  • Docker 镜像
• 常见问题
• 团队
• 许可证

快速入门

创建一个 Tango 步骤：

# hello.py

from tango import step

@step()
def hello(name: str) -> str:
    message = f"Hello, {name}!"
    print(message)
    return message

并创建相应的实验配置文件：

// hello.jsonnet

{
  steps: {
    hello: {
      type: "hello",
      name: "World",
    }
  }
}

然后使用本地工作区运行实验以缓存结果：

tango run hello.jsonnet -w /tmp/workspace

你将在输出中看到类似以下的内容：

Starting new run expert-llama
● Starting step "hello"...
Hello, World!
✓ Finished step "hello"
✓ Finished run expert-llama

如果第二次运行，输出将变为：

Starting new run open-crab
✓ Found output for step "hello" in cache...
✓ Finished run open-crab

这次你不会看到“Hello, World!”，因为该步骤的结果已存在于缓存中，因此未再次执行。

如需更详细的介绍，请参阅第一步教程。

安装

ai2-tango 需要 Python 3.8 或更高版本。

使用 pip 安装

ai2-tango 已在 PyPI 上发布。只需运行：

pip install ai2-tango

若需安装特定集成（例如 torch），可运行：

pip install 'ai2-tango[torch]'

若需安装所有集成，可运行：

pip install 'ai2-tango[all]'

使用 conda 安装

ai2-tango 可在 conda-forge 上获取。仅安装基础包时，可运行：

conda install tango -c conda-forge

也可根据需要选择安装特定集成：

conda install tango-datasets -c conda-forge
conda install tango-torch -c conda-forge
conda install tango-wandb -c conda-forge

或直接安装所有集成：

conda install tango-all -c conda-forge

尽管 ai2-tango 本身体积较小，但安装全部集成会引入大量依赖项。请做好耐心等待的准备！

从源码安装

要从源码安装 ai2-tango，首先克隆 仓库：

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

然后运行：

pip install -e '.[all]'

若仅需安装特定集成（如 torch），可运行：

pip install -e '.[torch]'

或者仅安装基础库，可运行：

pip install -e .

检查安装

运行以下命令以验证安装是否成功：

tango info

Docker 镜像

你可以基于 官方 Dockerfile 构建适合 Tango 项目的 Docker 镜像，也可以直接使用我们提供的 预构建镜像 作为你的 Dockerfile 的基础镜像。例如：

# 从预构建的 Tango 基础镜像开始。
# 你可以从这里选择合适的标签：
# https://github.com/allenai/tango/pkgs/container/tango/versions
FROM ghcr.io/allenai/tango:cuda11.3

# 安装项目所需的额外依赖。
COPY requirements.txt .
RUN /opt/conda/bin/pip install --no-cache-dir -r requirements.txt

# 安装源代码。
# 此指令会复制当前目录（构建上下文）中的所有内容，
# 这可能并非你所期望的行为。建议使用 `.dockerignore` 文件来排除不需要包含在镜像中的文件和目录。
COPY . .

请根据你使用的 Tango 版本以及宿主机支持的 CUDA 版本，选择合适的基础镜像。 所有可用镜像标签列表可在 GitHub 上查看。

常见问题

为什么这个库叫 Tango？

我们开发这个库的初衷是希望通过将研究分解为清晰定义的步骤，使其变得更加简单。那么，当你把许多步骤编排在一起时会发生什么呢？答案就是一场舞蹈。而由于我们的 团队负责人 是一支探戈乐队的成员，“AI2 Tango”便成了一个显而易见的选择！

如何通过 Tango CLI 调试我的步骤？

你可以通过 pdb 来运行 tango 命令进行调试。例如：

python -m pdb -m tango run config.jsonnet

Tango 与 Metaflow、Airflow 或 redun 有何不同？

我们发现，像这些现有的 DAG 执行引擎非常适合生产工作流，但在处理不断变化代码的混乱协作型研究项目中并不那么适用。AI2 Tango 就是专门为这类研究项目设计的。

Tango 的缓存机制是如何工作的？

AI2 Tango 会根据步骤的 unique_id 来缓存步骤的结果。unique_id 实际上是该步骤所有输入的哈希值，再加上：

1. 步骤类的完全限定名；
2. 步骤类的 VERSION 类变量（一个任意字符串）。

与其他工作流引擎（如 redun）不同，Tango 并不会考虑类本身的源代码内容（除了其完全限定名），因为我们发现使用源代码字节的哈希值过于敏感，且对用户不够透明。

当你以有意义的方式修改了步骤的源代码时，只需手动更改 VERSION 类变量，即可告知 Tango 该步骤已更新。

团队

ai2-tango 由 AllenNLP 团队开发并维护，背后支持机构为 艾伦人工智能研究所 (AI2)。AI2 是一家非营利性研究机构，致力于通过具有重大影响力的 AI 研究与工程为人类社会作出贡献。若想了解具体为本代码库做出贡献的人员，请参阅我们的 贡献者页面。

许可证

ai2-tango 采用 Apache 2.0 许可证 许可。许可证全文可在 GitHub 上找到。

AI2 Tango 快速上手指南

AI2 Tango 是一个专为科研实验设计的工具，它将复杂的实验流程组织成可缓存、可复用的离散步骤，替代混乱的文件目录和版本表格。

环境准备

• 操作系统：Linux, macOS, Windows (推荐 Linux/macOS)
• Python 版本：3.8 或更高
• 前置依赖：
  • pip 或 conda 包管理器
  • (可选) Docker：如需使用容器化部署

注意：国内用户建议使用清华源或阿里源加速 Python 包下载。

安装步骤

方式一：使用 pip 安装（推荐）

基础安装：

pip install ai2-tango -i https://pypi.tuna.tsinghua.edu.cn/simple

安装特定集成（例如 PyTorch）：

pip install 'ai2-tango[torch]' -i https://pypi.tuna.tsinghua.edu.cn/simple

安装所有集成（体积较大）：

pip install 'ai2-tango[all]' -i https://pypi.tuna.tsinghua.edu.cn/simple

方式二：使用 Conda 安装

基础安装：

conda install tango -c conda-forge

安装特定组件：

conda install tango-torch -c conda-forge

安装全套组件：

conda install tango-all -c conda-forge

验证安装

运行以下命令检查安装是否成功：

tango info

基本使用

1. 定义实验步骤

创建一个名为 hello.py 的文件，定义一个简单的处理步骤：

# hello.py

from tango import step

@step()
def hello(name: str) -> str:
    message = f"Hello, {name}!"
    print(message)
    return message

2. 创建实验配置

创建一个名为 hello.jsonnet 的配置文件，描述实验流程：

// hello.jsonnet

{
  steps: {
    hello: {
      type: "hello",
      name: "World",
    }
  }
}

3. 运行实验

使用本地工作空间运行实验，结果将被自动缓存：

tango run hello.jsonnet -w /tmp/workspace

首次运行输出：

Starting new run expert-llama
● Starting step "hello"...
Hello, World!
✓ Finished step "hello"
✓ Finished run expert-llama

4. 体验缓存机制

再次运行相同的命令：

tango run hello.jsonnet -w /tmp/workspace

第二次运行输出：

Starting new run open-crab
✓ Found output for step "hello" in cache...
✓ Finished run open-crab

可以看到，由于步骤输入未发生变化，Tango 直接从缓存中读取了结果，跳过了实际执行过程，从而节省了大量时间。