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

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-ossButterbase 原生 RAG是这款开源 BaaS 平台内置的检索增强生成Retrieval-Augmented Generation能力你只需两次 API 调用——ingest导入文档、query语义搜索即可让应用拥有读懂自己的文档的智能问答能力。分块、向量化text-embedding-3-small、pgvector 存储全部由平台托管新手无需搭建任何 ML 基础设施。本文带你用最短路径跑通 Butterbase RAG从创建集合、导入文档到带 AI 生成的语义问答并附常用参数调优技巧 什么是 Butterbase 原生 RAGRAG 的核心理念先用语义检索从文档库中捞出最相关的片段再交给大模型生成答案。相比把文档全部塞进提示词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.它的三步工作原理Ingest 导入—— 上传文件或直接传文本平台自动解析、切分成带重叠的 chunk 并生成向量Store 存储—— chunk 与向量写入你应用自己的 Postgrespgvector HNSW 索引不经过第三方向量数据库Query 查询—— 自然语言提问平台将其向量化后做余弦相似度检索可选地再调用 LLM 合成带引用的答案。对应的底层表结构定义在 010_rag_tables.sql其中_rag_chunks表上的 HNSW 索引保证了检索速度。2 次 API 调用Ingest 与 QueryButterbase RAG 的所有端点都在/v1/{app_id}/rag/下完整参数见 RAG API 参考。核心只有两个动作调用端点作用① 导入POST /v1/{app_id}/rag/collections/{name}/ingest把文件PDF/TXT/MD/DOCX/XLSX/PPTX/HTML/CSV或纯文本变成向量 chunk② 查询POST /v1/{app_id}/rag/collections/{name}/query语义搜索可选synthesize: true直接返回 AI 答案第 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 SDK10 行代码接入 RAG不想手写 fetch官方 SDK 的 RagClient 已封装好全部能力类型定义见 types.tsimport { 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 与 RLSRAG 集合与普通表共用同一套 RLS行级安全模型创建集合时选定模式行为private默认每个用户只能检索自己导入的文档RLS 策略自动创建shared所有已登录用户可检索集合内全部文档适合帮助文档等公共知识库custom不自动生成策略你可以自己写CREATE POLICY定制规则这意味着多租户隔离是白送的private模式下用户 A 的私有文档绝不会出现在用户 B 的检索结果里——无需写一行安全代码。策略的创建逻辑可在 RAG 路由源码 中查看。参数调优topK、threshold 与 filter想让检索更准调好这三个参数topK默认 5返回最相关的 chunk 数量。文档较长、答案分散时可调大到 8~10threshold0–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}直到状态变为readySDK 中为bb.rag.getDocument。问向量存在哪里答存在你应用自己的 Postgres 里pgvectorHNSW 索引数据不出你的库删除文档或集合即级联删除全部向量不可恢复、请谨慎。相关源码与文档概念文档RAG (Native)API 参考RAG API服务端实现services/control-api/src/routes/rag.tsSDK 客户端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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考