为规则配置 Webhook 通知 - 以编程方式使用文档

当您在自动化操作中添加 Webhook URL 时，您定义的规则匹配任何新运行时，LangSmith 会向您的 Webhook 端点发送 POST 请求。

Webhook 载荷

LangSmith 发送到您 Webhook 端点的载荷包含：

- "rule_id"：这是发送此载荷的自动化 ID。
- "start_time" 和 "end_time"：这些是 LangSmith 找到匹配运行的时间边界。
- "runs"：这是一个运行数组，其中每个运行都是一个字典。如果您需要更多关于每个运行的信息，请在端点中使用 SDK 从 API 获取。
- "feedback_stats"：这是包含运行反馈统计信息的字典。该字段的示例载荷在以下代码块中显示。

"feedback_stats": {
    "about_langchain": {
        "n": 1,
        "avg": 0.0,
        "show_feedback_arrow": true,
        "values": {}
    },
    "category": {
        "n": 0,
        "avg": null,
        "show_feedback_arrow": true,
        "values": {
            "CONCEPTUAL": 1
        }
    },
    "user_score": {
        "n": 2,
        "avg": 0.0,
        "show_feedback_arrow": false,
        "values": {}
    },
    "vagueness": {
        "n": 1,
        "avg": 0.0,
        "show_feedback_arrow": true,
        "values": {}
    }
}

以下是一个完整的 LangSmith 发送至您 Webhook 端点的载荷示例：

{
  "rule_id": "d75d7417-0c57-4655-88fe-1db3cda3a47a",
  "start_time": "2024-04-05T01:28:54.734491+00:00",
  "end_time": "2024-04-05T01:28:56.492563+00:00",
  "runs": [
    {
      "status": "success",
      "is_root": true,
      "trace_id": "6ab80f10-d79c-4fa2-b441-922ed6feb630",
      "dotted_order": "20230505T051324571809Z6ab80f10-d79c-4fa2-b441-922ed6feb630",
      "run_type": "tool",
      "modified_at": "2024-04-05T01:28:54.145062",
      "tenant_id": "2ebda79f-2946-4491-a9ad-d642f49e0815",
      "end_time": "2024-04-05T01:28:54.085649",
      "name": "Search",
      "start_time": "2024-04-05T01:28:54.085646",
      "id": "6ab80f10-d79c-4fa2-b441-922ed6feb630",
      "session_id": "6a3be6a2-9a8c-4fc8-b4c6-a8983b286cc5",
      "parent_run_ids": [],
      "child_run_ids": null,
      "direct_child_run_ids": null,
      "total_tokens": 0,
      "completion_tokens": 0,
      "prompt_tokens": 0,
      "total_cost": null,
      "completion_cost": null,
      "prompt_cost": null,
      "first_token_time": null,
      "app_path": "/o/2ebda79f-2946-4491-a9ad-d642f49e0815/projects/p/6a3be6a2-9a8c-4fc8-b4c6-a8983b286cc5/r/6ab80f10-d79c-4fa2-b441-922ed6feb630?trace_id=6ab80f10-d79c-4fa2-b441-922ed6feb630&start_time=2023-05-05T05:13:24.571809",
      "in_dataset": false,
      "last_queued_at": null,
      "inputs": null,
      "inputs_s3_urls": null,
      "outputs": null,
      "outputs_s3_urls": null,
      "extra": null,
      "events": null,
      "feedback_stats": null,
      "serialized": null,
      "share_token": null
    }
  ]
}

安全性

在 Webhook URL 中添加一个密钥查询字符串参数，并在每个传入请求时进行验证。这样可以确保即使有人发现了您的 Webhook URL，您也能区分这些调用与真实的 Webhook 通知。

例如

https://api.example.com/langsmith_webhook?secret=38ee77617c3a489ab6e871fbeb2ec87d

Webhook 自定义 HTTP 头

如果您想随 Webhook 发送任何特定的 headers，可以为每个 URL 进行配置。设置方法：点击 Headers URL 字段旁边的选项并添加您的 headers。

!Webhook Headers

Webhook 传递

在向您的 Webhook 端点传递事件时，LangSmith 遵循以下准则：

- 如果 LangSmith 无法连接到您的端点，LangSmith 会重试传输连接最多 2 次，然后才宣布传递失败。
- 如果您的端点响应时间超过 5 秒，LangSmith 宣布传递失败且不会重试。
- 如果您的端点在 5 秒内返回 5xx 状态码，LangSmith 会以指数退避方式重试最多 2 次。
- 如果您的端点返回 4xx 状态码，LangSmith 宣布传递失败且不会重试。
- 您的端点在响应体中返回的任何内容都将被忽略。

确保 Webhook 触发前完成评估

默认情况下，自动化规则按独立计划运行。扫描同一项目的 Webhook 规则和在线评估器规则可能在不同时间获取同一运行，因此 Webhook 可能在评估器有机会对运行进行评分之前就触发了。

推荐的解决方案是添加一个 _反馈过滤器_ 添加到您的 webhook 规则中。这告诉 LangSmith 仅在运行已携带预期分数时才将其发送到 webhook，无论何时评估该分数。

例如，您有一个在线评估器，它会产生一个 answer_usefulness 分数，且 webhook 规则仅应在该分数存在后才触发。

在跟踪项目的 **自动化** 标签页中打开 webhook 自动化规则。
编辑规则的过滤器以要求反馈键。在过滤器构建器中，添加条件：

   has(feedback_key, "answer_usefulness")

保存规则。

现在 webhook 规则将跳过任何尚不具有 answer_usefulness 分数的运行。当评估器规则运行并附加分数后，webhook 规则的下一次轮询周期将获取这些运行并将其发送到您的端点。

建议

您还可以根据分数值本身进行过滤，而不仅仅是其存在。例如，仅向您的端点发送低有用性分数的运行：

has(feedback_key, "answer_usefulness") and feedback_score < 0.5

有关完整的过滤语法，请参阅过滤追踪.

使用 Modal 的示例

设置

有关如何设置此功能的示例，本指南使用 Modal。Modal 为推理和微调提供自动扩展 GPU，为代码代理提供安全容器化，并为 Python Web 提供无服务器端点。本指南重点介绍 Web 端点。

首先，创建一个 Modal 账户。然后，在本地安装 Modal SDK：

pip install modal

uv add modal

要完成账户设置，请运行命令：

modal setup

按照说明完成账户设置。

密钥

接下来，您需要在 Modal 中设置一些密钥。

首先，LangSmith 需要通过传入密钥来向 Modal 进行身份验证。最简单的方法是在查询参数中传入密钥。要验证此密钥，请在 _Modal_ 中添加密钥进行验证。通过创建 Modal 密钥. 来执行此操作。将密钥命名为 ls-webhook 并设置名称为 LS_WEBHOOK.

的环境变量。您还可以设置 LangSmith 密钥——幸运的是，已经有一个集成模板了！

!LangSmith Modal 模板

服务

之后，您可以创建一个 Python 文件作为您的端点。以下代码块中显示了示例，并附有解释正在发生什么的注释：

from fastapi import HTTPException, status, Request, Query
from modal import Secret, Stub, web_endpoint, Image

stub = Stub("auth-example", image=Image.debian_slim().pip_install("langsmith"))


@stub.function(
    secrets=[Secret.from_name("ls-webhook"), Secret.from_name("my-langsmith-secret")]
)
# We want this to be a `POST` endpoint since we will post data here
@web_endpoint(method="POST")
# We set up a `secret` query parameter
def f(data: dict, secret: str = Query(...)):
    # You can import dependencies you don't have locally inside Modal functions
    from langsmith import Client

    # First, we validate the secret key we pass


    if secret != os.environ["LS_WEBHOOK"]:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Incorrect bearer token",
            headers={"WWW-Authenticate": "Bearer"},
        )

    # This is where we put the logic for what should happen inside this webhook
    ls_client = Client()
    runs = data["runs"]
    ids = [r["id"] for r in runs]
    feedback = list(ls_client.list_feedback(run_ids=ids))
    for r, f in zip(runs, feedback):
        try:
            ls_client.create_example(
                inputs=r["inputs"],
                outputs={"output": f.correction},
                dataset_name="classifier-github-issues",
            )
        except Exception:
            raise ValueError(f"{r} and {f}")
    # Function body
    return "success!"

使用以下命令部署此服务 modal deploy ... （请参阅管理 Modal 部署).

您现在应该会看到类似的内容：

✓ Created objects.
├── 🔨 Created mount /Users/harrisonchase/workplace/langsmith-docs/example-webhook.py
├── 🔨 Created mount PythonPackage:langsmith
└── 🔨 Created f => https://hwchase17--auth-example-f.modal.run
✓ App deployed! 🎉

View Deployment: https://modal.com/apps/hwchase17/auth-example

注意函数 URL： https://hwchase17--auth-example-f.modal.run. 注意：这不是最终的部署 URL，请确保不要误用。

连接配置

使用您之前创建的函数 URL 并将其添加为 webhook。请记得也将密钥作为查询参数传递。将所有内容整合在一起，应该看起来像这样：

https://hwchase17--auth-example-f-dev.modal.run?secret={SECRET}

替换 {SECRET} 为您创建用于访问 Modal 服务的密钥。