Turbopuffer 向量检索怎么用：API 建库、写入与查询验证
Turbopuffer 是一个托管的向量检索服务，不需要自己维护索引集群，开通后拿到 API Key 就能通过 HTTP 接口完成建库、写入和查询。
下面按实际使用顺序，从准备条件到执行查询逐步说明，适合第一次接触 Turbopuffer 的开发者对照操作。
接入前需要确认的三件事
开始操作前，先确认你具备以下条件：
- 一个可用的 Turbopuffer 账号，并在控制台生成 API Key。API Key 只显示一次，建议立即保存到密码管理器。
- 本机安装
curl，用来发送 HTTP 请求。Windows 用户可在 PowerShell 中使用curl.exe，或者用 Postman 代替。 - 准备好要检索的向量数据。Turbopuffer 中的向量通常是浮点数数组，维度需要与后续查询向量保持一致。
Turbopuffer 的接口地址以官方控制台提供的区域端点为准，下文用 https://api.turbopuffer.com 作为示例基地址。
如果你的控制台显示的是其他区域域名，请替换成实际地址。
创建命名空间并写入第一批数据
Turbopuffer 用命名空间（namespace）隔离数据，类似其他数据库里的库或表。
写入文档时，每条文档包含一个唯一 id、一个 vector 字段，以及可选的属性字段。
以下命令创建一个命名空间并写入两条文档：
curl -X POST "https://api.turbopuffer.com/v1/namespaces/demo-docs" \
-H "Authorization: Bearer $TURBOPUFFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"upsert_rows": [
{
"id": "doc-1",
"vector": [0.12, 0.34, 0.56],
"title": "服务器备份策略"
},
{
"id": "doc-2",
"vector": [0.98, 0.76, 0.54],
"title": "Nginx 反向代理配置"
}
]
}'执行后如果返回成功状态码且响应体包含写入数量，说明数据已经进入命名空间。
注意 vector 的维度在同一个命名空间内应保持一致，否则后续查询可能报维度不匹配错误。
执行近邻查询并解读返回结果
写入完成后，用查询接口验证检索是否生效。
查询时传入一个查询向量，Turbopuffer 会返回距离最近的若干条文档。
curl -X POST "https://api.turbopuffer.com/v1/namespaces/demo-docs/query" \
-H "Authorization: Bearer $TURBOPUFFER_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"rank_by": ["vector", "ANN", [0.10, 0.30, 0.50]],
"limit": 2,
"include_attributes": ["title"]
}'返回结果中会包含每条文档的 id、距离值以及请求的 title 属性。
如果返回结果为空，先检查命名空间名称是否写错，再确认写入时使用的向量维度与查询向量维度一致。
容易踩坑的几个地方
- API Key 权限：API Key 通常区分读写权限。只读 Key 无法执行写入操作，如果写入返回 401 或 403，先确认 Key 类型。
- 命名空间命名：命名空间名称建议只用小写字母、数字和短横线，避免特殊字符导致请求路径解析异常。
- 向量维度一致性：同一命名空间内所有文档的向量维度必须相同，查询向量也必须同维度。维度不一致时接口会直接拒绝请求。
- 批量写入大小：单次写入文档数量不宜过大，建议先小批量验证接口可用，再逐步增加批量规模。
验证是否真正可用
完成上述步骤后，用以下方式确认服务正常：
- 重新执行一次查询，确认返回的文档顺序与距离值符合预期。
- 修改一条文档的属性后再次查询，确认返回的
title已更新，说明 upsert 生效。 - 用错误的 API Key 发起一次请求，确认接口返回 401，以此验证鉴权逻辑正常。
如果查询结果稳定返回且属性正确，说明 Turbopuffer 的基本使用流程已经跑通。
后续可以根据业务需要增加过滤条件、调整返回字段，或把写入逻辑封装到自己的后端服务中。
常见疑问
Turbopuffer 需要自己部署向量索引吗？
不需要。
Turbopuffer 是托管服务，索引由平台维护，你只需要通过 API 写入和查询数据。
查询时提示向量维度不匹配怎么办？
检查写入时使用的向量数组长度是否与查询向量长度一致。
同一命名空间内所有文档的向量维度必须统一。
写入成功但查询没有结果是什么原因？
优先检查命名空间名称是否拼写正确，以及查询向量是否与已写入向量处于同一维度。
另外确认写入后是否有短暂延迟，必要时稍等片刻再查询。
