LangChain 中文文档

主题

监控与告警

为 LangSmith 告警配置 Webhook 通知

概述 ​

本指南详细介绍了如何为 LangSmith 警报 设置 Webhook 通知。在继续之前，请确保您已按照 此指南 完成了创建警报直至通知步骤的所有操作。Webhook 通过在警报条件触发时发送 HTTP POST 请求，实现与自定义服务和第三方平台的集成。您可以使用 Webhook 将警报数据转发到工单系统、聊天应用程序或自定义监控解决方案。

先决条件 ​

  • 一个能够接收 HTTP POST 请求的端点
  • 接收服务所需的适当身份验证凭据（如果需要）

集成配置 ​

步骤 1：准备接收端点 ​

在 LangSmith 中配置 Webhook 之前，请确保您的接收端点：

  • 接受 HTTP POST 请求
  • 能够处理 JSON 负载
  • 可以从外部服务访问
  • 具有适当的身份验证机制（如果需要）

此外，如果是在自定义部署的 LangSmith 上，请确保没有防火墙设置阻止来自 LangSmith 服务的出口流量。

步骤 2：配置 Webhook 参数 ​

Webhook 设置

在警报的通知部分，使用以下参数完成 Webhook 配置：

必填字段

  • URL：接收端点的完整 URL
    • 示例：https://api.example.com/incident-webhook

可选字段

  • Headers：随 Webhook 请求一起发送的 JSON 键值对

    • 常见标头包括：

  • Authorization：用于身份验证令牌

  • Content-Type：通常设置为 application/json（默认值）

  • X-Source：用于标识来源为 LangSmith * 如果不需要标头，则只需使用 {}

  • 请求正文模板：自定义发送到端点的 JSON 负载

    • 默认：LangSmith 发送定义的负载，并在负载末尾附加以下额外的键值对：

  • project_name：触发警报的项目名称

  • alert_rule_id：用于标识 LangSmith 警报的 UUID。这可以在 Webhook 服务中用作去重键。

  • alert_rule_name：警报规则的名称。

  • alert_rule_type：警报的类型（截至 2025 年 4 月 1 日，所有警报均为 threshold 类型）。

  • alert_rule_attribute：与警报规则关联的属性 - error_count、feedback_score 或 latency。

  • triggered_metric_value：触发阈值时指标的值。

  • triggered_threshold：触发警报的阈值。

  • timestamp：触发警报的时间戳。

步骤 3：测试 Webhook ​

点击 发送测试警报 以发送 Webhook 通知，确保通知按预期工作。

故障排除 ​

如果 Webhook 通知未送达：

  • 验证 Webhook URL 是否正确且可访问
  • 确保任何身份验证标头格式正确
  • 检查您的接收端点是否接受 POST 请求
  • 检查端点的日志，查看是否收到但拒绝了请求
  • 验证您的自定义负载模板是否为有效的 JSON 格式

安全注意事项 ​

  • 为您的 Webhook 端点使用 HTTPS
  • 为您的 Webhook 端点实施身份验证
  • 考虑在标头中添加共享密钥以验证 Webhook 来源
  • 在处理传入的 Webhook 请求之前对其进行验证

使用 Webhook 将警报发送到 Slack ​

以下是一个配置 LangSmith 警报以使用 chat.postMessage API 向 Slack 频道发送通知的示例。

先决条件 ​

  • 拥有 Slack 工作区的访问权限
  • 拥有一个用于设置警报的 LangSmith 项目
  • 拥有创建 Slack 应用程序的权限

步骤 1：创建 Slack 应用 ​

  1. 访问 Slack API 应用程序页面
  2. 点击 创建新应用
  3. 选择 从头开始
  4. 提供 应用名称（例如，"LangSmith Alerts"）
  5. 选择您要安装该应用的工作区
  6. 点击 创建应用

步骤 2：配置机器人权限 ​

  1. 在 Slack 应用配置的左侧边栏中，点击 OAuth 和权限
  2. 向下滚动到 范围 下的 机器人令牌范围，然后点击 添加 OAuth 范围
  3. 添加以下范围：
    • chat:write（以应用身份发送消息）
    • chat:write.public（向应用不在的频道发送消息）
    • channels:read（查看基本频道信息）

步骤 3：将应用安装到您的工作区 ​

  1. 向上滚动到 OAuth 和权限 页面顶部
  2. 点击 安装到工作区
  3. 查看权限并点击 允许
  4. 复制出现的 机器人用户 OAuth 令牌（以 xoxb- 开头）

步骤 4：将机器人添加到 Slack 频道 ​

将机器人添加到您希望接收警报的特定频道。您可以通过在消息字段中提及机器人（例如，@botname）来将其添加到 Slack 频道。

您还需要频道 ID 来在 LangSmith 中配置 Webhook 警报。您可以通过打开频道详情 > 关于来找到频道 ID。

步骤 5：在 LangSmith 中配置 Webhook 警报 ​

  1. 在 LangSmith 中，导航到您的项目
  2. 选择 警报 → 创建警报
  3. 定义您的警报指标和条件
  4. 在通知部分，选择 Webhook
  5. 使用以下设置配置 Webhook：

Webhook URL

json
https://slack.com/api/chat.postMessage

Headers

将 `xoxb-your-token-here` 替换为您的机器人用户 OAuth 令牌
json
{
  "Content-Type": "application/json",
  "Authorization": "Bearer xoxb-your-token-here"
}

请求正文模板

必须填写从步骤 4 中找到的 `{channel_id}` 值。

其余字段：`alert_name`、`project_name` 和 `project_url` 可选地为警报消息添加上下文。您可以在浏览器的地址栏中找到您的 `project_url`。复制 URL 中直到但不包括任何查询参数的部分。
json
{
  "channel": "{channel_id}",
  "text": "{alert_name} triggered for {project_name}",
  "blocks": [
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "🚨{alert_name} has been triggered"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Please check the following link for more information:"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "<{project-url}|View in LangSmith>"
      }
    }
  ]
}
  1. 点击 保存 以激活 Webhook 配置

步骤 6：测试集成 ​

  1. 在 LangSmith 警报配置中，点击 测试警报
  2. 检查您指定的 Slack 频道是否收到测试通知
  3. 验证消息是否包含预期的警报信息

（可选）步骤 7：在请求正文中链接到警报预览 ​

创建警报后，您可以选择在 Webhook 的请求正文中链接到其预览。

警报预览窗格

配置方法：

  1. 保存您的警报
  2. 在警报表中找到您保存的警报并点击它
  3. 复制显示的 URL
  4. 点击"编辑警报"
  5. 将现有的项目 URL 替换为复制的警报预览 URL

其他资源 ​

LangChain 中文文档

Copyright © 王码码