Ragie 多租户知识库教程：Partition、权限过滤与引用验收

这篇教程搭一条可验收的多租户知识检索流程：把一份脱敏资料写入 Ragie 的指定 Partition，等待索引就绪，在服务端按登录用户决定检索范围，最后把检索片段和原始来源一起交给回答层。示例只用虚构租户与公开样本文本，不需要上传真实客户资料。

开始前准备

准备 Ragie 账号和服务端 API Key、两个虚构租户 tenant_alpha 与 tenant_beta，以及 10–20 份已脱敏的 Markdown/PDF。先在应用数据库中建立 user_id -> tenant_id -> allowed_projects 映射。Key 只放服务端密钥管理，不能写进浏览器代码、公开仓库或日志。确认账号套餐的页面处理、存储、连接器与月度支出上限。

Ragie 的 Partition 名称只能使用小写字母数字、下划线和连字符。示例 tenant_alpha 合法。真实项目不要由用户输入直接拼出 Partition；应使用数据库中已验证的租户映射。

第一步：把资料写入指定 Partition

上传 PDF 可调用 POST /documents 并传 file、partition、metadata；纯文本可用 POST /documents/raw。下面用原始文本避免文件上传细节：

curl -fSs https://api.ragie.ai/documents/raw \
  -H "Authorization: Bearer ${RAGIE_API_KEY}" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "alpha-support-policy",
    "partition": "tenant_alpha",
    "external_id": "alpha-policy-v1",
    "metadata": {"project_id": "support", "visibility": "team"},
    "data": "虚构公司 Alpha 的客服政策：退款申请先由人工审核。"
  }'

记录返回的文档 ID、external_id、源文件版本和所属租户。摄取是异步过程，不能收到创建响应就立刻宣布可检索。官方状态包括 pending、indexed、ready 和 failed 等；产品可轮询状态或接收 Webhook，直到 ready 才向用户展示“已完成同步”。如采用 Webhook，验证签名并按事件 ID/nonce 做幂等处理，因为重试会带来重复通知。

第二步：由服务端生成检索范围

在后端完成会话验证与项目 ACL 查询后，再构造 Ragie 请求。以下只是已验证用户属于 Alpha 且可读 support 项目时的请求体示例：

{
  "query": "退款申请谁审核？",
  "partition": "tenant_alpha",
  "filter": {"project_id": {"$eq": "support"}},
  "top_k": 8,
  "rerank": false
}

把请求体发送到 POST https://api.ragie.ai/retrievals。top_k 是最多返回的候选片段数；提高它会增加下游模型上下文和可能的延迟。rerank=true 可以改善部分查询的相关性，但也会带来额外耗时，先用基线题库对照。Ragie 文档说明：不传 partition 时检索落入默认分区，因此每个检索调用都要显式设置范围。

第三步：生成答案并保留证据链

将检索结果中允许展示的片段、来源文档 ID、页码/链接和更新时间传给回答层。提示词应要求模型只使用这些片段回答，缺证据时说“当前资料无法确认”；界面展示可点击的来源。不要把模型生成的引用文本直接当成可信链接，要按检索结果中的原始标识构造，并再次检查当前用户是否仍有权访问原文件。

测试两种常见错误：同名旧版政策被排在新版前面，以及文本中含“忽略之前指令”的提示注入。前者用版本 metadata、时间字段和测试集发现；后者应把资料视为不可信输入，不允许资料片段控制工具调用或改变系统规则。需要外部写入工具时，再加人工审批和服务端授权。

第四步：验证租户隔离、同步与成本

建立如下验收表，每条都留日志但不记录原文敏感内容：

用 30 个已标注答案的问题计算有证据的正确率、错误引用率、p95 延迟和每千个有效回答成本。若表格读取持续失败，单独比较 hi-res 处理或更强的文档解析服务；若主要问题是 ACL，换检索供应商前先修应用权限映射。

常见问题

Partition 是权限系统吗？不是。它是 Ragie 的检索范围，应用仍要验证用户、租户、资源和来源权限。连接器同步完成就表示用户能看到所有文件吗？也不是；同步状态与最终 ACL 是两件事。为什么检索不到刚上传的文件？先检查文档是否 ready、partition 是否一致、metadata 过滤是否过窄，再看摄取错误。能用客户端直接调用 Ragie 吗？多租户产品不应暴露服务端 API Key，也不应让浏览器自行决定 Partition。

资料：创建原始文本、创建文件、检索 API、Partition、Metadata 过滤、Webhook、定价。