Supabase Headless Vector Search：用 Embedding 为文档站打造 ChatGPT 式问答

当文档变成"智能问答库"：一个技术团队的痛点

想象这样的场景：你的团队维护着一份数百页的 API 文档，某天凌晨两点，用户在 Slack 里问了一个文档里明明有答案的问题，而你从睡梦中被叫醒。如果文档自己能回答问题呢？

Supabase 团队也遇到了同样的问题。他们的开源文档 docs.supabase.com 内容庞大，用户经常找不到需要的信息。传统的关键词搜索体验差——用户搜索"认证"，搜到的可能是一堆无关的技术细节，却漏掉了最核心的 JWT 流程说明。

于是，Headless Vector Search 诞生了：一个专为文档站设计的向量语义搜索工具包，可以让任何文档站获得类似 ChatGPT 的自然语言问答能力，而无需用户学习任何向量数据库的底层原理。

技术架构：一条请求的完整旅程

当你向这个系统发送一个问题，比如"What's Supabase?"，背后的处理流程是这样的：

第一步：Query 理解与安全审查。 系统首先对用户输入进行 OpenAI 内容安全审核（Moderation API），过滤违禁内容。如果通过，则进入向量转换阶段。

第二步：Query 向量化。 调用 OpenAI text-embedding-ada-002 模型，将用户问题转换为 1536 维的数学向量。这是一种"语义坐标"——语义相近的文本在向量空间中距离更近。

第三步：向量相似度检索。 在 PostgreSQL 数据库中执行 match_page_sections RPC 函数，使用 pgvector 扩展进行余弦相似度搜索。该函数以用户 Query 向量为圆心，在向量空间中找出与之语义最接近的文档片段（默认阈值 0.78，最多返回 10 条）。

第四步：上下文拼接与生成。 将最相关的文档片段拼接为上下文 Prompt（最多消耗 1500 个 token），然后调用 gpt-3.5-turbo-instruct 模型生成自然语言回答。

第五步：流式响应。 答案以 Server-Sent Events（SSE）流式输出到客户端，支持 EventSource（浏览器原生）或标准 HTTP 流式读取。

整个流程的关键创新在于"headless"设计——它不是一个完整的应用，而是一个工具包（toolkit），通过 Supabase Edge Functions 部署，可以嵌入到任何已有的网站中。

核心数据库设计：pgvector 的工程实践

项目在 docs schema 中定义了两张核心表：

docs.page：存储文档页面的元信息，包括路径、版本、最后刷新时间等，支持父子页面层级关系（通过 parent_page_id 自引用外键）。

docs.page_section：存储文档的切片内容及对应向量。每个切片（section）有独立的 heading、slug 和 1536 维 embedding 向量。这种"文档切片"的粒度设计非常关键——切片太小（小于 50 字符）会被过滤，太大则稀释相关内容的权重。

match_page_sections 函数的实现值得玩味：使用负点积（Negative Dot Product）而非欧氏距离进行排序。代码注释解释得很清楚——OpenAI 的 embedding 是归一化的（模长为 1），所以点积与余弦相似度等价，但负点积在大规模向量搜索中的计算效率更高。

整个链路形成闭环：GitHub Action 负责数据入库 → Edge Function 负责查询检索 → 回答生成。开发者不需要管理任何服务器，只需要在 Supabase Dashboard 配置几个参数即可。

上手门槛分析

对于已有 Supabase 项目的团队，这个工具包的集成成本极低。但对于使用其他数据库或技术栈的团队，迁移成本不低——这本质上是一个"Supabase 原生"工具。

当前局限与争议

过度依赖 OpenAI。 项目硬编码使用 text-embedding-ada-002 和 gpt-3.5-turbo-instruct，不支持切换到 Claude、Google Gemini 或本地模型。这在 OpenAI 价格上调或可用性波动时成为潜在风险。

文档格式单一。 仅支持 Markdown，不支持 Notion、Confluence、Docusaurus 等常见文档格式。实际落地时，"把文档转成 Markdown"这一步可能比部署整个系统花的时间还多。

向量搜索精度依赖切片质量。 同一个页面的不同切片方式会显著影响搜索结果的好坏，目前没有任何自动切片优化或质量评估机制。

行业意义：从"搜关键词"到"问问题"的范式转变

Headless Vector Search 代表了一个重要趋势：语义搜索正在从专业向量数据库（如 Milvus、Pinecone）下沉到普通开发者触手可及的地方。 通过 pgvector，PostgreSQL 用户无需引入额外的向量数据库基础设施，就能获得生产级的语义搜索能力。

这一趋势与 RAG（Retrieval-Augmented Generation）架构的普及高度吻合。开发者不再需要理解 transformer、注意力机制等底层原理，只需要调用几个 API，就能为自己的产品添加"读懂语义"的智能问答能力。Supabase 团队把这件事做到极致——连 SQL 都不需要手写，工具包全包了。

对于文档密集型产品（API 文档、技术博客、帮助中心），这个工具包提供了极低成本的智能化升级路径。如果你已经在使用 Supabase，Headless Vector Search 几乎是最快将 ChatGPT 能力集成到文档站的方式。