使用预签名 URL 收集反馈 - Docs by LangChain中文

预签名反馈令牌允许您从客户端应用程序（浏览器、移动应用等）收集反馈，而无需暴露您的 LangSmith API 密钥。每个令牌都会生成一个 URL，该 URL 的范围限定于特定的运行和反馈键。客户端通过直接调用该 URL 来提交反馈，无需进行身份验证。这在以下情况下非常有用：

您的前端从最终用户那里收集点赞/踩或星级评分。
您希望将反馈链接嵌入到电子邮件、Slack 消息或其他外部渠道中。
您需要将反馈收集与您的后端解耦。

如果您正在使用 Agent Server，当您在运行请求中包含 feedback_keys 时，预签名反馈 URL 会自动生成。有关该工作流程，请参阅为 Agent Server 运行收集用户反馈。

创建预签名反馈令牌

使用 create_presigned_feedback_token() / createPresignedFeedbackToken 来为特定的运行和反馈键生成一个令牌。返回的对象包含一个 url，客户端可以调用它来提交反馈：

from langsmith import Client

client = Client()

run_id = "<run_id>"

token = client.create_presigned_feedback_token(
    run_id,
    feedback_key="user_score",
)

print(token.url)
# https://api.smith.langchain.com/api/v1/feedback/tokens/<token_id>

import { Client } from "langsmith";

const client = new Client();

const runId = "<run_id>";

const token = await client.createPresignedFeedbackToken(runId, "user_score");

console.log(token.url);
// https://api.smith.langchain.com/api/v1/feedback/tokens/<token_id>

设置令牌过期时间

令牌默认在 3 小时后过期。传递 expiration 参数来自定义此时间，可以使用 timedelta（相对时间）或 datetime（绝对时间）：

import datetime
from langsmith import Client

client = Client()

run_id = "<run_id>"

token = client.create_presigned_feedback_token(
    run_id,
    feedback_key="user_score",
    expiration=datetime.timedelta(hours=24),
)

import { Client } from "langsmith";

const client = new Client();

const runId = "<run_id>";

const token = await client.createPresignedFeedbackToken(runId, "user_score", {
  expiration: { hours: 24 },
});

限制反馈值

传递 feedback_config 来限制客户端可以提交的值。这对于强制执行特定的反馈模式非常有用（例如，点赞/踩、1-5 星或分类标签）：

from langsmith import Client

client = Client()

run_id = "<run_id>"

token = client.create_presigned_feedback_token(
    run_id,
    feedback_key="user_score",
    feedback_config={
        "type": "continuous",
        "min": 0,
        "max": 1,
    },
)

import { Client } from "langsmith";

const client = new Client();

const runId = "<run_id>";

const token = await client.createPresignedFeedbackToken(runId, "user_score", {
  feedbackConfig: {
    type: "continuous",
    min: 0,
    max: 1,
  },
});

批量创建令牌（仅限 Python）

使用 create_presigned_feedback_tokens（复数形式）在一次调用中为多个反馈键生成令牌：

Python

from langsmith import Client

client = Client()

run_id = "<run_id>"

tokens = client.create_presigned_feedback_tokens(
    run_id,
    feedback_keys=["thumbs_up", "thumbs_down"],
)

for token in tokens:
    print(f"{token.id}: {token.url}")

使用预签名 URL 提交反馈

获得预签名 URL 后，您的前端代码或电子邮件客户端可以通过向该 URL 发送 POST 或 GET 请求来提交反馈。该 URL 不需要 API 密钥或身份验证，因为令牌已提供授权。默认情况下，预签名 URL 反馈会将基础保留期的跟踪延长至扩展保留期。预签名 URL 没有用于退出此行为的参数。有关完整的保留模型，请参阅数据保留自动升级。

POST 请求

当用户与反馈控件交互（例如，点击点赞按钮）时，从您的前端使用 POST 请求。POST 支持 score、value、comment、correction 和 metadata 字段。

curl --request POST \
  --url "https://api.smith.langchain.com/api/v1/feedback/tokens/<token_id>" \
  --header "Content-Type: application/json" \
  --data '{
    "score": 1,
    "comment": "This response was helpful!"
  }'

GET 请求

当将反馈链接嵌入到电子邮件或 Slack 消息中时使用 GET。用户的点击会触发请求。GET 将 score、value、comment 和 correction 作为查询参数支持。GET 不支持 metadata。

curl --request GET \
  --url "https://api.smith.langchain.com/api/v1/feedback/tokens/<token_id>?score=1&comment=This%20response%20was%20helpful!"

使用 SDK 提交反馈

您也可以使用 SDK 从预签名令牌提交反馈，这对于从另一个服务接收到令牌 URL 的服务器端工作流非常有用。

from langsmith import Client

client = Client()

client.create_feedback_from_token(
    "<token_or_url>",
    score=1,
    comment="This response was helpful!",
)

// Use a direct HTTP request to the presigned URL
await fetch(tokenUrl, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    score: 1,
    comment: "This response was helpful!",
  }),
});

列出现有令牌

使用 list_presigned_feedback_tokens / listPresignedFeedbackTokens 来检索某个运行的所有预签名反馈令牌。

from langsmith import Client

client = Client()

run_id = "<run_id>"

for token in client.list_presigned_feedback_tokens(run_id):
    print(f"ID: {token.id}, URL: {token.url}, Expires: {token.expires_at}")

import { Client } from "langsmith";

const client = new Client();

const runId = "<run_id>";

for await (const token of client.listPresignedFeedbackTokens(runId)) {
  console.log(`URL: ${token.url}, Expires: ${token.expires_at}`);
}

​创建预签名反馈令牌

​设置令牌过期时间

​限制反馈值

​批量创建令牌（仅限 Python）

​使用预签名 URL 提交反馈

​POST 请求

​GET 请求

​使用 SDK 提交反馈

​列出现有令牌

​相关内容

创建预签名反馈令牌

设置令牌过期时间

限制反馈值

批量创建令牌（仅限 Python）

使用预签名 URL 提交反馈

POST 请求

GET 请求

使用 SDK 提交反馈

列出现有令牌

相关内容