Access Tags

概述

并非所有内容都面向所有人：仅限会员的文档、特定地区的材料、付费等级的资源。借助 Access Tags，一个聊天机器人就能安全地服务不同受众。您给知识条目打上标签，从那一刻起，该条目对所有访客都不可见 — 除非访客的页面出示了由您自己的服务器签名的该标签。限制在我们的检索查询中强制执行，此时 AI 模型尚未参与。没有标签的访客无法通过巧妙提问套出内容，因为对他而言内容根本没有被检索过。

工作原理

1. 您给知识条目打标签 - 在 Access Tags 页面或直接通过 API；无标签的条目继续对所有人可用
2. 您的服务器为每位访客的标签签名 - 登录会员打开您的页面时，您的后端判定其权限，并用只有您持有的密钥签名
3. 挂件发送签名凭据 - 它随每条聊天消息一起传输；浏览器只负责传递，无法在不破坏签名的情况下更改它
4. 我们验证并过滤 - 有效签名会解锁标签匹配的条目；凭据缺失、被篡改或已过期时，访客只能获得公开内容

如何设置

在控制台的 Access Tags 页面开启功能 — 签名密钥会自动生成。请只保存在您的服务器上；任何持有它的人都能制作有效凭据。

在同一页面为内容打标签，或在通过 API 提交条目时指定：

POST /api/v1/knowledge/text/
{
  "title": "Members-only price list",
  "content": "...",
  "website_id": "123",
  "access_tags": ["premium"]
}

然后让您的服务器在挂件代码旁输出签名凭据。要签名的消息是以逗号分隔的标签列表；使用过期时间时，用竖线连接：

<?php
$tags    = "members,premium";          // this visitor's entitlements
$expires = time() + 3600;              // unix seconds, optional but recommended
$sig     = hash_hmac("sha256", $tags . "|" . $expires, $SECRET);
?>
<script>
window.Asyntai = window.Asyntai || {};
window.Asyntai.accessTags = "<?php echo $tags; ?>";
window.Asyntai.accessTagsExpires = "<?php echo $expires; ?>";
window.Asyntai.accessTagsSignature = "<?php echo $sig; ?>";
</script>

Node.js 和 Python 中的同一签名：

// Node.js
const crypto = require("crypto");
const sig = crypto.createHmac("sha256", SECRET)
                  .update(tags + "|" + expires).digest("hex");

# Python
import hmac, hashlib
sig = hmac.new(SECRET.encode(), f"{tags}|{expires}".encode(),
               hashlib.sha256).hexdigest()

不用过期时间时，只需对标签字符串本身签名。使用过期时间时，凭据在过期那一刻立即失效 — 当权限可能被收回时很有用，因为访客必须重新加载由您控制的页面才能获得新凭据。

有哪些保证

• 服务器端强制执行 - 过滤器在检索时运行于我们的数据库查询内部；对未授权访客，带标签的条目根本不会进入 AI 的上下文，因此无可泄露
• 处处默认拒绝 - 无签名、签名错误、凭据过期、功能关闭、套餐降级：在任何一种情况下，访客都只能获得公开内容，绝不会更多
• 浏览器无法伪造访问权限 - 在开发者工具中修改标签会破坏签名；密钥只在您的服务器上
• 您的权限逻辑仍归您所有 - 我们永远不知道您如何决定谁获得哪个标签；我们只验证您的服务器确实作了声明

值得了解

• Access Tags 是授权，User Context 是个性化 - 用 User Context 告诉 AI 会员是谁；用 Access Tags 控制 AI 可以引用哪些知识
• 抓取的网站内容始终公开 - 它来自您的公开网站，无需限制；标签适用于文本、文件和 API 条目
• 访客只需一个匹配的标签 - 带两个标签的条目，持有其中任意一个标签的访客即可使用
• 重新生成密钥会使所有旧凭据失效 - 若密钥可能泄露请执行此操作，然后更新页面改用新密钥签名
• 标签名称由您决定 - 每个条目最多 20 个，每个 50 字符，不含逗号和竖线；它们绝不会出现在访客看到的聊天中