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，直到 才向用户展示“已完成同步”。如采用 Webhook，验证签名并按事件 ID/nonce 做幂等处理，因为重试会带来重复通知。