面向 AI/ML 的开发环境

什么是 envd？

envd（发音为 ɪnˈvdɪ）是一款命令行工具，可帮助您创建基于容器的 AI/ML 开发环境。

构建开发环境并不容易，尤其是在当今复杂系统和依赖关系的情况下。从 Python 到 CUDA、BASH 脚本和 Dockerfile，这些工具和配置文件经常出现兼容性问题或失效，这让人感到非常棘手——直到现在！

只需在 build.envd 中简单声明所需的软件包，并执行一条命令：envd up，即可快速搭建出完全符合需求的开发环境！

为什么使用 envd？

使用 envd 构建的环境开箱即用，具备以下特性：

简洁的 CLI 和编程语言

envd 让您可以将强大的命令行工具无缝集成到现有的 Python 工作流中，从而轻松 provision 您的开发环境，而无需学习新的语言或 DSL。

def build():
    base(dev=True)
    install.conda()
    install.python()
    install.python_packages(name = [
        "numpy",
    ])
    shell("fish")
    config.jupyter()

隔离性，兼容 OCI 镜像

借助 envd，用户可以创建一个隔离的空间来进行训练、微调或服务部署。通过利用先进的虚拟化技术以及 buildkit 等功能，envd 是环境搭建的理想解决方案。

envd 环境镜像是兼容 OCI 镜像规范 的。借助 OCI 镜像的强大功能，您可以将您的环境共享给任何人！只需将其推送到 Harbor 或 Docker Hub 等容器注册表即可实现这一点。

本地与云端支持

envd 现在可以在混合平台上使用，从本地机器到 Kubernetes 托管的集群均可运行。无论选择哪种方式，都能为开发者提供高效且灵活的方式来构建项目！

$ envd context use local
# 在本地运行 envd 环境
$ envd up
...
$ envd context use cluster
# 在集群中以相同体验运行 envd 环境
$ envd up

更多详细信息请参阅 文档。

随时随地构建，速度更快

借助 buildkit，envd 提供了远程构建和软件缓存等功能，例如 pip 索引缓存或 apt 缓存，所有这些都旨在让您无需直接接触代码就能更轻松地完成工作！

复用之前从 PyPI/APT 缓存中下载的软件包，可以节省时间和精力，使构建过程更加高效。无需再次下载已获取的内容——只需一次下载即可多次使用！

而在传统的 Dockerfile v1 中，用户无法利用 PyPI 缓存来提升安装速度，但 envd 不仅支持这一功能，还提供了更多便利！

此外，envd 还支持远程构建，这意味着您可以在远程机器上（如云服务器）构建环境，然后将其推送到注册表。当您使用的机器资源有限，或者希望使用性能更高的构建机器时，这一功能尤为有用。

团队知识共享

告别复制粘贴 Dockerfile 指令吧！使用 envd 可以轻松构建函数，并通过 include 函数导入任何 Git 仓库来重复使用它们！快速打造强大的自定义解决方案。

envdlib = include("https://github.com/tensorchord/envdlib")

def build():
    base(dev=True)
    install.conda()
    install.python()
    envdlib.tensorboard(host_port=8888)

def tensorboard(
    envd_port=6006,
    envd_dir="/home/envd/logs",
    host_port=0,
    host_dir="/tmp",
):
    """配置 TensorBoard。

    请确保您对 `host_dir` 具有访问权限

    Args:
        envd_port (Optional[int]): envd 容器使用的端口
        envd_dir (Optional[str]): envd 容器中的日志存储挂载路径
        host_port (Optional[int]): 主机使用的端口，若未指定或等于 0，
            envd 将随机选择一个空闲端口
        host_dir (Optional[str]): 主机上的日志存储挂载路径
    """
    install.python_packages(["tensorboard"])
    runtime.mount(host_path=host_dir, envd_path=envd_dir)
    runtime.daemon(
        commands=[
            [
                "tensorboard",
                "--logdir",
                envd_dir,
                "--port",
                str(envd_port),
                "--host",
                "0.0.0.0",
            ],
        ]
    )
    runtime.expose(envd_port=envd_port，host_port=host_port，service="tensorboard")

快速开始 🚀

系统要求

• Docker (20.10.0 或更高版本)

安装并初始化 envd

envd 可以通过 pip 安装，或者直接从 release 下载二进制文件。安装完成后，请运行 envd bootstrap 进行初始化。

pip install --upgrade envd

安装完成后，请运行 envd bootstrap 进行初始化：

envd bootstrap

更多替代安装方法请参阅 文档。

在运行 envd bootstrap 时，可以添加 --dockerhub-mirror 或 -m 标志来配置 docker.io 注册表的镜像源：

envd bootstrap --dockerhub-mirror https://docker.mirrors.sjtug.sjtu.edu.cn

创建 envd 环境

请克隆 envd-quick-start：

git clone https://github.com/tensorchord/envd-quick-start.git

构建清单文件 build.envd 如下所示：

def build():
    base(dev=True)
    install.conda()
    install.python()
    # 如果需要，可以配置 pip 源。
    # config.pip_index(url = "https://pypi.tuna.tsinghua.edu.cn/simple")
    install.python_packages(name = [
        "numpy",
    ])
    shell("fish")

请注意，这里我们以 Python 为例，但您也可以查看其他语言（如 R 和 Julia）的示例 这里。

然后，请运行以下命令来设置一个新的环境：

cd envd-quick-start && envd up

$ cd envd-quick-start && envd up
[+] ⌚ 解析 build.envd 并下载/缓存依赖项 6.2s ✅ (已完成) 
[+] 构建 envd 环境 19.0s (47/47) 已完成                                                 
 => 缓存 [内部] 设置 pip 缓存挂载权限                                     0.0s
 => docker-image://docker.io/tensorchord/envd-sshd-from-scratch:v0.4.3                        2.3s
 => => 解析 docker.io/tensorchord/envd-sshd-from-scratch:v0.4.3                            2.3s
 => docker-image://docker.io/library/ubuntu:22.04                                             0.0s
......
 => [内部] pip 安装 numpy                                                              2.5s
 => 缓存 [内部] 下载 fish shell                                                     0.0s
 => [内部] 配置 /opt/conda 的用户权限                                      1.0s
 => [内部] 创建 ssh 密钥目录                                                         0.5s
 => [内部] 安装 ssh 密钥                                                               0.2s
 => [内部] 从构建镜像复制 fish shell                                         0.2s
 => [内部] 安装 fish shell                                                             0.5s
......
 => [内部] 创建工作目录：/home/envd/envd-quick-start                                   0.2s
 => 导出到镜像                                                                        7.7s
 => => 导出层                                                                       7.7s
 => => 写入镜像 sha256:464a0c12759d3d1732404f217d5c6e06d0ee4890cccd66391a608daf2bd314e4  0.0s
 => => 命名为 docker.io/library/envd-quick-start:dev                                       0.0s
------
 > 从 docker.io/tensorchord/python-cache:envd-v0.4.3 导入缓存清单：
------
⣽ [5/5] 挂载环境  [2s]            
欢迎使用 fish，友好的交互式 shell
键入 help 获取使用 fish 的说明

envd-quick-start 在 git master 上 [!] 使用 Py v3.11.11 通过 🅒 envd 以 sudo 身份运行 
⬢ [envd]❯ # 您现在处于基于容器的环境中！

设置 Jupyter Notebook

请编辑 build.envd 以启用 Jupyter Notebook：

def build():
    base(dev=True)
    install.conda()
    install.python()
    # 如果需要，可以配置 pip 源。
    # config.pip_index(url = "https://pypi.tuna.tsinghua.edu.cn/simple")
    install.python_packages(name = [
        "numpy",
    ])
    shell("fish")
    config.jupyter()

您可以使用 envd envs ls 获取正在运行的 Jupyter Notebook 的访问地址。

$ envd up --detach
$ envd envs ls
NAME                    JUPYTER                 SSH TARGET              CONTEXT                                 IMAGE                   GPU     CUDA    CUDNN   STATUS          CONTAINER ID
envd-quick-start        http://localhost:42779   envd-quick-start.envd   /home/gaocegege/code/envd-quick-start   envd-quick-start:dev    false   <none>  <none>  运行了 54 秒   bd3f6a729e94

v0 和 v1 语法的区别

[!注意] 自 envd v1.0 起，v1 语法成为 build.envd 文件的默认语法，且默认构建器为 moby-worker。

[!重要提示] 更多详情请参阅 升级到 v1 文档。

更多文档信息 📝

请参阅 envd 文档。

路线图 🗂️

请查看 路线图。

贡献 😊

我们欢迎来自开源社区、个人和合作伙伴的各种贡献。

• 加入我们的 Discord 社区!
• 若要从源代码构建，请阅读我们的 贡献文档 和 开发教程。

贡献者 ✨

感谢以下优秀人士（emoji key）：

Friends A. 📖 🎨	Aaron Sun 📓 💻	Aka.Fido 📦 📖 💻	Alex Xi 💻	Bingtan Lu 💻	Bingyi Sun 💻	Ce Gao 💻 📖 🎨 📆
Frost Ming 💻 📖	Guangyang Li 💻	Gui-Yue 💻	Haiker Sun 💻	Ikko Ashimine 💻	Isaac 💻	JasonZhu 💻
Jian Zeng 🎨 🤔 🔬	Jinjing Zhou 🐛 💻 🎨 📖	Jun 📦 💻	Kaiyang Chen 💻	Keming 💻 📖 🤔 🚇	Kevin Su 💻	Ling Jin 🐛 🚇
Manjusaka 💻	Nino 🎨 💻	Pengyu Wang 📖	Sepush 📖	Shao Wang 💻	Siyuan Wang 💻 🚇 🚧	Suyan 📖
To My 📖	Tumushimire Yves 💻	Wei Zhang 💻	Weixiao Huang 💻	Weizhen Wang 💻	XRW 💻	Xu Jin 💻
Xuanwo 💬 🎨 🤔 👀	Yijiang Liu 💻	Yilong Li 📖 🐛 💻	Yuan Tang 💻 🎨 📖 🤔	Yuchen Cheng 🐛 🚇 🚧 🔧	Yuedong Wu 💻	Yunchuan Zheng 💻
Zheming Li 💻	Zhenguo.Li 💻 📖	Zhenzhen Zhao 🚇 📓 💻	Zhizhen He 💻 📖	cutecutecat 💻	dqhl76 📖 💻	heyjude 💻
jimoosciuc 📓	kenwoodjw 💻	li mengyang 💻	nullday 🤔 💻	rrain7 💻	tison 💻	wangxiaolei 💻
wyq 🐛 🎨 💻	x0oo0x 💻	xiangtianyu 📖	xieydd 💻	xing0821 🤔 📓 💻	xxchan 📖	zhang-wei 💻
zhyon404 💻	杨成锴 💻

本项目遵循 all-contributors 规范。欢迎任何形式的贡献！

许可证 📋

Apache 2.0

envd 快速上手指南

envd 是一款专为 AI/ML 开发者设计的命令行工具，旨在通过简单的声明式配置，快速构建基于容器的开发环境。它解决了传统 Dockerfile 编写复杂、依赖管理困难的问题，支持本地与云端混合部署，并提供高效的构建缓存机制。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2)
• 核心依赖：Docker (版本需 >= 20.10.0)
  • 请确保 Docker 守护进程已启动且当前用户有权限运行 Docker 命令。

安装步骤

1. 安装 envd

推荐使用 pip 进行安装（需预先安装 Python）：

pip install --upgrade envd

或者，您也可以直接从 GitHub Releases 下载二进制文件。

2. 初始化引导

安装完成后，必须运行引导命令以配置后端环境。国内用户建议配置 Docker 镜像加速源以提升拉取速度：

# 使用国内镜像源（例如上海交通大学镜像站）进行引导
envd bootstrap --dockerhub-mirror https://docker.mirrors.sjtug.sjtu.edu.cn

如果不配置镜像源，可直接运行：

envd bootstrap

基本使用

1. 获取示例项目

克隆官方提供的快速入门项目：

git clone https://github.com/tensorchord/envd-quick-start.git
cd envd-quick-start

2. 理解配置文件

项目根目录下的 build.envd 文件定义了环境依赖。这是一个标准的 Python 脚本，语法直观：

def build():
    base(dev=True)
    install.conda()
    install.python()
    # 如需加速 pip 下载，可取消下方注释并配置国内源
    # config.pip_index(url = "https://pypi.tuna.tsinghua.edu.cn/simple")
    install.python_packages(name = [
        "numpy",
    ])
    shell("fish")
    # 如需启用 Jupyter，请添加下方配置
    # config.jupyter()

3. 启动开发环境

在项目目录下运行以下命令，envd 将自动解析依赖、构建镜像并启动容器：

envd up

执行过程说明：

• 首次运行时会下载基础镜像并安装依赖（后续构建利用缓存将非常快）。
• 构建完成后，终端会自动附加到容器内的 Shell（默认为 fish），您已处于配置好的 AI 开发环境中。

Welcome to fish, the friendly interactive shell
...
⬢ [envd]❯ # 您现在可以在容器中直接运行 python, numpy 等命令

4. 进阶：启动 Jupyter Notebook

如果需要 Web 界面进行开发：

1. 编辑 build.envd，取消 config.jupyter() 的注释。
2. 后台启动环境：

   envd up --detach
   

3. 查看访问地址：

   envd envs ls
   

   输出中的 JUPYTER 列即为访问链接（例如 http://localhost:42779）。