Turbopuffer 混合检索教程：BM25、向量召回、RRF 与权限验收

这篇教程用一小组公开的演示文档，把 Turbopuffer 的 BM25 与向量检索接成一个可检查的 RAG 召回层。流程是：写入带文本的行 → 跑两路查询 → RRF 融合 → 人工核对候选 → 再把候选交给生成模型。示例不上传真实客户资料，也不把 API key 放进浏览器。

开始前准备

1. 在 Turbopuffer 控制台创建 API key，选择支持目标 embedding 模型的区域。以下示例沿用官方文档的 gcp-us-central1 和 nvidia/nemotron-3-embed-8b，换区域时先查模型列表。
2. 安装 Python 3 和官方 SDK：python3 -m pip install turbopuffer。
3. 在终端设置 TURBOPUFFER_API_KEY 环境变量。密钥只放服务端环境变量或密钥管理器，别写入代码、聊天记录或客户端。
4. 为这次演示准备独立 namespace，避免和生产索引混用。注意官方没有免费档，试跑前在价格页确认最低用量和账户预算。

第一步：写入同时用于 BM25 与向量的文本

保存下面代码为 hybrid_demo.py。这段代码按 2026 年 10 月官方 Python 示例整理：full_text_search 启用 BM25，embed 让同一 content 字段生成向量。示例仅用三条公开句子说明路径；真实 RAG 应保留文档 ID、页码、来源和更新时间。

import os
import uuid
import turbopuffer

key = os.environ["TURBOPUFFER_API_KEY"]
tpuf = turbopuffer.Turbopuffer(
    api_key=key,
    region="gcp-us-central1",
)
name = os.getenv("TURBOPUFFER_NAMESPACE", f"rag-demo-{uuid.uuid4().hex[:8]}")
ns = tpuf.namespace(name)

ns.write(
    upsert_rows=[
        {: , : , : },
        {: , : , : },
        {: , : , : },
    ],
    distance_metric=,
    schema={
        : {
            : ,
            : ,
            : {: , : },
        }
    },
)