企业官网建设流程全解析

Butterbase 原生 RAG 教程：只需 2 次 API 调用实现文档语义搜索与智能问答

【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss

Butterbase 原生 RAG是这款开源 BaaS 平台内置的检索增强生成（Retrieval-Augmented Generation）能力：你只需两次 API 调用——ingest导入文档、query语义搜索，即可让应用拥有"读懂自己的文档"的智能问答能力。分块、向量化（text-embedding-3-small）、pgvector 存储全部由平台托管，新手无需搭建任何 ML 基础设施。

本文带你用最短路径跑通 Butterbase RAG：从创建集合、导入文档到带 AI 生成的语义问答，并附常用参数调优技巧 🚀

什么是 Butterbase 原生 RAG？

RAG 的核心理念：先用语义检索从文档库中捞出最相关的片段，再交给大模型生成答案。相比把文档全部塞进提示词，RAG 更省 token、答案可溯源、知识库可随时更新。

Butterbase 把整条 RAG 流水线做成了平台原语，官方文档一句话总结见 RAG (Native) 概念文档：

Ingest documents and query them with natural language. The platform handles chunking, embedding, and vector storage — no ML infrastructure required.

它的三步工作原理：

1. Ingest 导入—— 上传文件或直接传文本，平台自动解析、切分成带重叠的 chunk 并生成向量；
2. Store 存储—— chunk 与向量写入你应用自己的 Postgres（pgvector + HNSW 索引），不经过第三方向量数据库；
3. Query 查询—— 自然语言提问，平台将其向量化后做余弦相似度检索，可选地再调用 LLM 合成带引用的答案。

对应的底层表结构定义在 010_rag_tables.sql，其中_rag_chunks表上的 HNSW 索引保证了检索速度。

2 次 API 调用：Ingest 与 Query

Butterbase RAG 的所有端点都在/v1/{app_id}/rag/下，完整参数见 RAG API 参考。核心只有两个动作：

第 1 步：Ingest 导入文档

导入前需要有一个**集合（Collection）**作为文档的命名空间。支持两种导入来源：

• 纯文本：body 里传text+ 可选的filename；
• 已上传的文件：先通过 Storage 上传拿到objectId，再把它作为storage_object_id传给 ingest 端点。

POST /v1/{app_id}/rag/collections/support-docs/ingest { "text": "Refunds are accepted within 30 days of purchase...", "filename": "refund-policy.txt" }

导入是异步的：接口立即返回status: "pending"和documentId，之后文档会经历pending → processing → ready（失败则进入failed），轮询文档状态端点即可。

第 2 步：Query 语义搜索 + 智能问答

POST /v1/{app_id}/rag/collections/support-docs/query { "query": "What is the refund policy?", "topK": 5, "threshold": 0.7, "synthesize": true }

响应会返回按相似度排序的chunks（含score、来源filename、metadata）；开启synthesize后还会多一个answer字段，由 LLM 基于检索到的片段生成，并引用[Source N]。

TypeScript SDK：10 行代码接入 RAG

不想手写 fetch？官方 SDK 的 RagClient 已封装好全部能力（类型定义见 types.ts）：

import { createClient } from '@butterbase/sdk'; const bb = createClient({ appId: 'app_abc123', apiUrl: 'https://api.butterbase.ai' }); // 创建共享集合 await bb.rag.createCollection({ name: 'support-docs', accessMode: 'shared' }); // 导入文档（file 或 text 二选一） await bb.rag.ingest('support-docs', { text: 'Refunds are accepted within 30 days...', filename: 'refund-policy.txt' }); // 语义查询 + AI 合成答案 const { data } = await bb.rag.query('support-docs', { query: 'What is the return policy?', synthesize: true, }); console.log(data.answer);

SDK 的ingest方法还很贴心：传file时会自动先走 Storage 上传、再携带storage_object_id调用 ingest，两步合并为一步。

CLI 一键操作：collections、ingest、query

命令行党可以用 CLI 的 rag 命令 在终端里完成同样的事：

• butterbase rag collections create support-docs --access-mode shared—— 创建集合
• butterbase rag ingest ./manual.pdf --collection support-docs—— 自动上传并导入本地文件
• butterbase rag query support-docs -q "如何退货" --synthesize—— 终端直接打印 AI 答案与来源分数

加--json可输出原始 JSON，方便接入自己的脚本。

访问控制：3 种 accessMode 与 RLS

RAG 集合与普通表共用同一套 RLS（行级安全）模型，创建集合时选定：

这意味着多租户隔离是白送的：private模式下，用户 A 的私有文档绝不会出现在用户 B 的检索结果里——无需写一行安全代码。策略的创建逻辑可在 RAG 路由源码 中查看。

参数调优：topK、threshold 与 filter

想让检索更准？调好这三个参数：

• topK（默认 5）：返回最相关的 chunk 数量。文档较长、答案分散时可调大到 8~10；
• threshold（0–1）：最低余弦相似度。设成0.7左右可以过滤掉"似是而非"的片段，宁缺毋滥；
• filter：按 metadata 键值对过滤。导入时用metadata: { category: "billing" }打标，查询时传filter: { category: "billing" }就能只搜账单类文档——用一套集合管理多类知识库。

费用提示：embedding 调用与synthesize的 LLM 调用都计入你的 AI 积分额度，上传文件计入存储配额，没有额外的 RAG 专项收费。

常见问题（FAQ）

问：支持哪些文件格式？答：.txt、.md、.pdf、.docx、.xlsx、.pptx、.html、.csv，以及直接传纯文本。

问：导入要等多久？答：ingest 接口立即返回pending，处理是异步的。轮询GET .../documents/{id}直到状态变为ready（SDK 中为bb.rag.getDocument）。

问：向量存在哪里？答：存在你应用自己的 Postgres 里（pgvector，HNSW 索引），数据不出你的库，删除文档或集合即级联删除全部向量，不可恢复、请谨慎。

相关源码与文档

• 概念文档：RAG (Native)
• API 参考：RAG API
• 服务端实现：services/control-api/src/routes/rag.ts
• SDK 客户端：packages/sdk/src/rag/rag-client.ts
• 数据表结构：db/data-plane/010_rag_tables.sql

从ingest到query，两次调用就把语义搜索和智能问答装进你的应用——这就是 Butterbase 原生 RAG 的全部 🎉

【免费下载链接】butterbase-ossOpen-source backend-as-a-service. Postgres, auth, storage, functions, AI gateway, MCP.项目地址: https://gitcode.com/gh_mirrors/bu/butterbase-oss