敲敲门

一个小型库，只需添加两行代码，即可在训练完成或过程中发生崩溃时收到通知。

在训练深度学习模型时，通常会使用早停策略。除了粗略的估计外，很难预测训练何时会结束。因此，为训练设置自动通知功能非常有用。此外，当训练因意外原因中途崩溃时，也能及时收到通知，这同样很有意义。

安装

使用 pip 或其他等效工具进行安装。

pip install knockknock

此代码仅在 Python >= 3.6 上进行了测试。

使用方法

该库的设计旨在无缝集成，只需对代码进行最少的修改：只需在主函数调用上方添加一个装饰器即可。返回值（如果有）也会包含在通知中。

目前共有 十二 种通知方式：

平台	外部贡献者
电子邮件	-
Slack	-
Telegram	-
Microsoft Teams	@noklam
短信	@abhishekkrthakur
Discord	@watkinsm
桌面通知	@atakanyenel @eyalmazuz
Matrix	@jcklie
Amazon Chime	@prabhakar267
DingTalk	@wuutiing
RocketChat	@radao
企业微信	@jcyk

电子邮件

该服务依赖于 Yagmail，一个 GMAIL/SMTP 客户端。您需要一个 Gmail 邮箱地址才能使用它（您可以在此处创建一个 这里，免费）。建议您创建一个新的邮箱（而不是常用的邮箱），因为您需要修改账户的安全设置，以允许 Python 库通过启用不安全的应用程序访问您的邮箱。

Python

from knockknock import email_sender

@email_sender(recipient_emails=["<your_email@address.com>", "<your_second_email@address.com>"], sender_email="<grandma's_email@gmail.com>")
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10000)
    return {'loss': 0.9} # 可选的返回值

命令行

knockknock email \
    --recipient-emails <your_email@address.com>,<your_second_email@address.com> \
    --sender-email <grandma's_email@gmail.com> \
    sleep 10

如果未指定 sender_email，则会使用 recipient_emails 中的第一个邮箱作为发件人邮箱。

请注意，运行此命令时会要求您输入发件人邮箱的密码。该密码将通过 keyring Python 库 安全地存储在系统的密钥环服务中。

Slack

同样，您也可以使用 Slack 接收通知。您需要获取 Slack 工作区的 Webhook URL，并可选择性地提供您的 用户 ID（如果您想标记自己或其他人）。

Python

from knockknock import slack_sender

webhook_url = "<webhook_url_to_your_slack_room>"
@slack_sender(webhook_url=webhook_url, channel="<your_favorite_slack_channel>")
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10000)
    return {'loss': 0.9} # 可选的返回值

您还可以指定一个可选参数来标记特定人员：user_mentions=[<your_slack_id>, <grandma's_slack_id>]。

命令行

knockknock slack \
    --webhook-url <webhook_url_to_your_slack_room> \
    --channel <your_favorite_slack_channel> \
    sleep 10

您也可以指定一个可选参数来标记特定人员：--user-mentions <your_slack_id>,<grandma's_slack_id>。

Telegram

您还可以使用 Telegram Messenger 接收通知。首先，您需要按照 Telegram 提供的三个步骤 这里 创建自己的通知机器人，并保存您的 API 访问 TOKEN。

Telegram 机器人比较害羞，无法发送第一条消息，因此您需要先发送一条消息。通过发送第一条消息，您可以访问 https://api.telegram.org/bot<YourBOTToken>/getUpdates 来获取所需的 chat_id（即您的聊天室标识符），并在 message['chat']['id'] 键下找到对应的整数值。

Python

from knockknock import telegram_sender

CHAT_ID: int = <your_messaging_room_id>
@telegram_sender(token="<your_api_token>", chat_id=CHAT_ID)
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10000)
    return {'loss': 0.9} # 可选的返回值

命令行

knockknock telegram \
    --token <your_api_token> \
    --chat-id <your_messaging_room_id> \
    sleep 10

Microsoft Teams

感谢 @noklam，你也可以使用 Microsoft Teams 接收通知。你需要获取你的团队频道的 webhook URL。

Python

from knockknock import teams_sender

@teams_sender(token="<webhook_url_to_your_teams_channel>")
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10)
    return {'loss': 0.9} # 可选返回值

命令行

knockknock teams \
    --webhook-url <webhook_url_to_your_teams_channel> \
    sleep 10

你还可以指定一个可选参数来标记特定人员：user_mentions=[<your_teams_id>, <grandma's_teams_id>]。

短信 (SMS)

感谢 @abhishekkrthakur，你可以使用 Twilio 发送短信通知。你需要在此处设置一个 Twilio 账户 这里，这是一项收费服务，价格具有竞争力：例如在美国，获取一个新的号码和通过该服务发送一条短信分别需要花费 1.00 美元和 0.0075 美元。你需要获取 (a) 一个电话号码，(b) 你的 account SID 和 (c) 你的 authentification token。详细信息请参阅 这里。

Python

from knockknock import sms_sender

ACCOUNT_SID: str = "<your_account_sid>"
AUTH_TOKEN: str = "<your_auth_token>"
@sms_sender(account_sid=ACCOUNT_SID, auth_token=AUTH_TOKEN, recipient_number="<recipient's_number>", sender_number="<sender's_number>")
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10)
    return {'loss': 0.9} # 可选返回值

命令行

knockknock sms \
    --account-sid <your_account_sid> \
    --auth-token <your_account_auth_token> \
    --recipient-number <recipient_number> \
    --sender-number <sender_number>
    sleep 10

Discord

感谢 @watkinsm，你也可以使用 Discord 接收通知。你只需要获取你的 Discord 频道的 webhook URL。

Python

from knockknock import discord_sender

webhook_url = "<webhook_url_to_your_discord_channel>"
@discord_sender(webhook_url=webhook_url)
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10000)
    return {'loss': 0.9} # 可选返回值

命令行

knockknock discord \
    --webhook-url <webhook_url_to_your_discord_channel> \
    sleep 10

桌面通知

你也可以通过桌面通知接收提醒。目前仅适用于 MacOS、Linux 和 Windows 10。

对于 Linux，它使用 notify-send 命令，该命令依赖于 libnotify。要使用 libnotify，你需要安装一个通知服务器。Cinnamon、Deepin、Enlightenment、GNOME、GNOME Flashback 和 KDE Plasma 都有自己的通知显示实现。在其他桌面环境中，你需要通过你的窗口管理器或桌面环境的“自动启动”选项来启动通知服务器。

Python

from knockknock import desktop_sender

@desktop_sender(title="Knockknock Desktop Notifier")
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10000)
    return {"loss": 0.9}

命令行

knockknock desktop \
    --title 'Knockknock Desktop Notifier' \
    sleep 2

Matrix

感谢 @jcklie，你可以通过 Matrix 发送通知。homeserver 是你将发送消息的用户所注册的服务器。不要忘记 URL 的协议（http 或 https）。

你需要获取机器人或你自己的用户的访问令牌。最简单的方法是在 Riot 中查看，进入设置中的“帮助与关于”，在底部可以看到：“访问令牌：<点击以显示>”。你还需要指定一个房间别名，用于发送消息。要在 Riot 中获取别名，创建一个你想使用的房间，然后在“房间地址”中打开房间设置并添加一个别名。

Python

from knockknock import matrix_sender

HOMESERVER = "<url_to_your_home_server>" # 例如 https://matrix.org
TOKEN = "<your_auth_token>"              # 例如 WiTyGizlr8ntvBXdFfZLctyY
ROOM = "<room_alias"                     # 例如 #knockknock:matrix.org

@matrix_sender(homeserver=HOMESERVER, token=TOKEN, room=ROOM)
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10000)
    return {'loss': 0.9} # 可选返回值

命令行

knockknock matrix \
    --homeserver <homeserver> \
    --token <token> \
    --room <room> \
    sleep 10

Amazon Chime

感谢 @prabhakar267，你也可以使用 Amazon Chime 接收通知。你需要获取你的 Chime 会议室的 webhook URL。

Python

from knockknock import chime_sender

@chime_sender(webhook_url="<webhook_url_to_your_chime_room>")
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10)
    return {'loss': 0.9} # 可选返回值

命令行

knockknock chime \
    --webhook-url <webhook_url_to_your_chime_room> \
    sleep 10

你还可以指定一个可选参数来标记特定人员：user_mentions=[<your_alias>, <grandma's_alias>]。

钉钉

现在也支持钉钉通知，感谢 @wuutiing。只需提供钉钉聊天机器人 webhook URL 和密钥/关键词（至少在创建聊天机器人时设置其中一个），你的通知就会发送到该聊天室中的任何一人。

Python

from knockknock import dingtalk_sender

webhook_url = "<webhook_url_to_your_dingtalk_chatroom_robot>"
@dingtalk_sender(webhook_url=webhook_url, secret="<your_robot_secret_if_set>", keywords=["<list_of_keywords_if_set>"])
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10000)
    return {'loss': 0.9} # 可选返回值

命令行

knockknock dingtalk \
    --webhook-url <webhook_url_to_your_dingtalk_chatroom_robot> \
    --secret <your_robot_secret_if_set> \
    sleep 10

你还可以指定一个可选参数来标记特定人员：user_mentions=["<list_of_phonenumbers_who_you_want_to_tag>"]。

RocketChat

您可以使用 RocketChat 接收通知。在发送通知之前，您需要准备以下内容：

• 一个 RocketChat 服务器，例如 rocketchat.yourcompany.com
• 一个 RocketChat 用户 ID（您可以在下一步创建个人访问令牌时查看您的用户 ID）
• 一个 RocketChat 个人访问令牌（请按照此指南创建）
• 一个 RocketChat 频道

Python

from knockknock import rocketchat_sender

@rocketchat_sender(
    rocketchat_server_url="<您的 RocketChat 服务器地址>",
    rocketchat_user_id="<您的 RocketChat 用户 ID>",
    rocketchat_auth_token="<您的 RocketChat 认证令牌>",
    channel="<频道名称>")
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10000)
    return {'loss': 0.9} # 可选返回值

您还可以指定两个可选参数：

• 标记特定用户：user_mentions=[<您的用户名>, <奶奶的用户名>]
• 使用通知别名：alias="我的别名"

命令行

knockknock rocketchat \
    --rocketchat-server-url <您的 RocketChat 服务器地址> \
    --rocketchat-user-id <您的 RocketChat 用户 ID> \
    --rocketchat-auth-token <您的 RocketChat 认证令牌> \
    --channel <频道名称> \
    sleep 10

微信企业号

感谢 @jcyk 的支持，现在也支持微信企业号了。只需提供微信企业号聊天室机器人的 Webhook 地址，您的通知就会发送到该聊天室中的所有人。

Python

from knockknock import wechat_sender

webhook_url = "<您的微信企业号聊天室机器人 Webhook 地址>"
@wechat_sender(webhook_url=webhook_url)
def train_your_nicest_model(your_nicest_parameters):
    import time
    time.sleep(10000)
    return {'loss': 0.9} # 可选返回值

命令行

knockknock wechat \
    --webhook-url <您的微信企业号聊天室机器人 Webhook 地址> \
    sleep 10

您还可以指定一个可选参数来标记特定人员：user-mentions=["<您想要标记的用户ID列表>"] 和/或 user-mentions-mobile=["<您想要标记的手机号码列表>"]。

关于分布式训练的说明

在使用分布式训练时，每个 GPU 都会通过本地 rank 变量绑定到其对应的进程。由于 knockknock 是在进程级别工作的，如果您使用 8 个 GPU，那么在训练开始和结束时都会收到 8 条通知……为了解决这个问题，除了出现错误的情况外，只有主进程可以发送通知，这样您就只会分别在训练开始和结束时各收到一条通知。

注意： 在 PyTorch 中，torch.distributed.launch 的启动会为每个进程设置一个 RANK 环境变量（详见 此处）。这个变量用于识别主进程，目前这也是我想到的唯一简单方法。遗憾的是，这种方法并不适用于所有平台，但我非常乐意在 issue 或 PR 中与大家讨论更智能、更好的分布式训练处理方式。

Knock Knock 快速上手指南

Knock Knock 是一个轻量级的 Python 库，旨在通过仅需两行代码即可在深度学习模型训练完成或意外崩溃时发送通知。它支持邮件、Slack、Telegram、钉钉、企业微信等十余种通知渠道。

环境准备

• 操作系统：Linux, macOS, Windows 10+
• Python 版本：>= 3.6
• 前置依赖：无特殊系统依赖（桌面通知在 Linux 下需确保已安装 libnotify 及相关通知服务）

安装步骤

使用 pip 进行安装。国内用户推荐使用清华或阿里镜像源以加速下载：

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

或者使用默认源：

pip install knockknock

基本使用

Knock Knock 的核心用法是通过装饰器包裹你的主训练函数。以下以最常用的 Email 和 命令行模式 为例。

方式一：Python 装饰器（推荐）

在训练脚本中导入对应的发送器，并将其作为装饰器添加到主函数上方。

示例：发送邮件通知

from knockknock import email_sender

@email_sender(
    recipient_emails=["your_email@address.com"], 
    sender_email="sender_email@gmail.com"
)
def train_your_model():
    import time
    # 模拟训练过程
    time.sleep(10) 
    return {'loss': 0.9}  # 返回值也会包含在通知中

if __name__ == "__main__":
    train_your_model()

注意：首次运行邮件通知时，程序会提示输入发件人邮箱密码，密码将安全存储在系统密钥环中。若使用 Gmail，需开启“允许不够安全的应用”访问权限。

方式二：命令行模式

无需修改代码，直接在终端命令前加上 knockknock [渠道] [参数] 即可监控任意命令的执行状态。

示例：监控一个耗时命令

knockknock email \
    --recipient-emails your_email@address.com \
    --sender-email sender_email@gmail.com \
    python train.py

支持的通知渠道

除了 Email，库还支持以下渠道（使用方法类似，只需更换导入模块或命令行关键字）：

渠道	Python 模块	命令行关键字	备注
Slack	slack_sender	slack	需 Webhook URL
Telegram	telegram_sender	telegram	需 Bot Token 和 Chat ID
钉钉	dingtalk_sender	dingtalk	需 Webhook URL (国内常用)
企业微信	wechat_work_sender	wechat-work	需 Webhook Key (国内常用)
Microsoft Teams	teams_sender	teams	需 Webhook URL
短信 (SMS)	sms_sender	sms	需 Twilio 账号 (付费)
Discord	discord_sender	discord	需 Webhook URL
桌面通知	desktop_sender	desktop	仅限本地弹窗
Matrix	matrix_sender	matrix	需 Homeserver 和 Token
Amazon Chime	chime_sender	chime	需 Webhook URL
RocketChat	rocketchat_sender	rocketchat	需 Webhook URL

具体各渠道的 Token 或 Webhook 获取方式，请参考官方文档对应章节。