Vespa 向量数据库手册

适用版本：滚动发布（每周多版，无单一稳定版号）；GitHub Releases 顶部 Vespa CLI 8.781.11（Latest）仅为示例，生产须固定构建号（核实于 2026-11） 许可与形态：Apache 2.0；独立服务进程（自托管容器 / Vespa Cloud），schema-first + YQL 一句话定位：先写 schema 再部署应用包、用 YQL 表达检索的分布式引擎，向量检索只是其查询能力的一部分 约定：$ 普通用户、# root 或 sudo、<xxx> 为占位符；标 ⚠️ 的是高危操作。 更新时间：2026-11（版本与 API 变化快，执行前请以官方文档复核）

目录

1. 它是什么、什么时候选它
2. 版本、许可与官方入口
3. 安装与启动
4. 核心概念与数据模型
5. 快速上手：完整 CRUD 示例
6. 索引与检索进阶
7. 生产部署与运维
8. 高频故障与排障
9. 常见坑与避坑清单
10. 速查表
11. 参考与延伸

1. 它是什么、什么时候选它

1.1 定位与架构

Vespa 是服务化的分布式检索引擎：不像 Chroma / LanceDB 以「客户端连一个集合」为入口，而是先定义 Application Package（schema）、部署成应用，再用 YQL 表达查询。向量检索通过 tensor 字段 + ann=HNSW(...) 与 nearestNeighbor 算子接入，只是其查询能力的一部分。

版本差异：Vespa 滚动发布（每周多版），无单一稳定版号，官方资料明确要求固定构建号而非写死「稳定版」。部署镜像用 <固定构建号> 占位，不用 latest，也不要把 CLI 版本 8.781.11 当服务端版本号——版本号分「CLI / 服务端构建 / schema 格式」多条线。

1.2 与同类产品的本质差别

本质差别是**「schema-first + YQL + 部署即发布」**：字段类型、索引方式、距离度量、ranking 都在 schema 里声明，改结构要重新 deploy；查询是 YQL 字符串而非方法链，可在一条语句里组合 ANN、标量过滤、grouping、rank。代价是上手门槛与运维复杂度高于嵌入式库。

⚠️ 形态要点：schema 中 uri 类型已 Deprecated；改 distance-metric / max-links-per-node 需重启但无需 re-feed；nearestNeighbor 下 grouping 计数不精确。这三条最容易被旧教程误导（见第 5、9 章）。

1.3 适合 / 不适合

适合：① 需 ANN + 标量过滤 + grouping + 自定义 ranking 组合在同一条查询里的复杂检索；② 大规模、服务化、需明确端口 / 部署流程的在线服务；③ 已有 YQL / Vespa 栈、需混合检索与重排；④ 能接受「schema 变更走重新部署」发布节奏；⑤ 需固定构建号、可复现发布流程的生产环境。

不适合：① 只想 pip install 后在脚本里跑 RAG 原型（嵌入式库更轻）；② 无法接受 schema-first 与部署流程的轻量用例；③ 期待「稳定版号 + 长期维护线」的升级策略；④ 依赖官方 Helm chart 直接交付 K8s（未核实，见第 11 章，K8s 主要走 Vespa Cloud / operator）；⑤ 把 nearestNeighbor 下 grouping 计数当精确统计的报表场景。

1.4 规模参考（经验值，非官方承诺）

单集群承载量取决于节点数、tensor 维度、targetHits 与 ranking 复杂度；官方资料未给出官方容量承诺数值，须以自身数据压测为准。维度示例用 4 维（官方 Quickstart 用 384），实际常见 384 / 768 / 1024 / 1536。

1.5 在链路中的位置

文档 → Embedding 模型 → [Vespa: tensor 字段 + 标量字段, schema 声明 HNSW] → feed(/document/v1/) → YQL nearestNeighbor + 过滤 + rank → Top-K → LLM 生成。推荐 / 以图搜图同理，把 embedding 与标签写进同一 document，用 YQL 的 and 过滤、rank 重排。

2. 版本、许可与官方入口

2.1 版本状态表

版本差异：官方资料明确「写死稳定版号 → 滚动发布，固定构建号」。把构建号作为唯一变量固定，升级 = 换构建号并回归验证，不要用 latest，勿把 CLI / SDK 版本号混进服务端版本描述。

2.2 许可证与商业版边界

2.3 官方 URL 表

2.4 版本识别命令

$ vespa version                     # CLI 版本（非服务端构建号）

2.5 近两年重要变更与弃用提醒

1. 滚动发布：无单一稳定版号，固定构建号，升级需回归验证。
2. uri 类型 Deprecated：schema 中不要再使用。
3. HNSW 参数变更需重启：改 distance-metric / max-links-per-node 需重启，但无需 re-feed。
4. 过滤 + ANN：存在 post/pre-filtering 与 filter-first-threshold(0.2) 等开关；grouping 计数不精确（nearestNeighbor 下）。

3. 安装与启动

3.1 依赖与前置条件

容器运行时（自托管）或 Vespa Cloud / operator 环境；Python 侧 pip3 install pyvespa；需能访问 8080（查询 / 文档）与 19071（config / deploy）；schema 与构建号须配套管理。

3.2 方式一：Docker + Vespa CLI（本地自托管，官方）

$ pip3 install pyvespa
$ docker run --detach --name vespa --hostname vespa-container \
    --publish 8080:8080 --publish 19071:19071 vespaengine/vespa:<固定构建号>
$ vespa config set target local && vespa status deploy --wait 300

版本差异：镜像 tag 用 <固定构建号>，不要写死某个「稳定版」、也不要用 latest——Vespa 滚动发布，固定构建号才能复现环境。官方原始命令镜像未带 tag，此处按「固定构建号」要求改为占位符，具体值从 Releases 选取并锁定。

3.3 方式二：pyvespa 部署应用包（schema-first）

$ pip3 install pyvespa

以 Python 定义 ApplicationPackage 后 VespaDocker().deploy(application_package=package) 即完成部署；完整可运行代码见第 5 章，此处不重复。

3.4 方式三：Vespa Cloud / operator（生产 K8s）

官方资料提示 K8s 主要走 Vespa Cloud / operator；官方 Helm chart 未核实（见第 11 章），不臆造 chart 仓库地址，以官方文档为准。

3.5 目录与端口表

3.6 启动后健康检查与连通性验证

$ vespa status deploy --wait 300
$ curl -s -X POST http://localhost:8080/search/ -H "Content-Type: application/json" \
    -d '{"yql":"select * from sources * where true"}'

避坑：健康检查具体路径官方未明确（未核实），勿照抄第三方 /healthz 之类；用上面确认的 vespa status deploy --wait 300 判断部署就绪。

3.7 生产最小配置建议

4. 核心概念与数据模型

4.1 术语对照表

4.2 数据模型层级

ApplicationPackage(name, schema=[...]) → Schema(name, document=Document(fields=[...])) → Field(name, type, indexing, ann) → document 实例（带 id / namespace / schema）。schema-first：字段类型、索引、度量、ranking 全在 schema 声明，再 deploy 成应用，之后才能 feed 与查询。

4.3 字段与向量类型

4.4 距离度量与方向

未核实：距离度量完整枚举未逐字确认，正文只写出现过的两个取值，其余以官方文档为准；相关性得分方向 / 换算也以官方文档为准，不臆造。

4.5 索引类型与关键参数

距离度量完整枚举、HNSW 全量参数默认值官方资料官方未明确，以官方 approximate-nn-hnsw 文档为准。

4.6 写入 → 建索引 → 可检索的生命周期

1. 定义 schema（含 ann=HNSW）并 deploy；2. feed_iterable / /document/v1/ 写入文档；3. HNSW 随 feed 构建、即可被 nearestNeighbor 检索，无需显式 load / build；4. 改 HNSW 参数需重启、无需 re-feed；5. 分布式写入 / 可见性一致性承诺官方资料未给出，以官方文档为准。

5. 快速上手：完整 CRUD 示例

以下基于 pyvespa 官方 Quickstart 当前写法（schema-first + YQL），import 齐全、变量均有定义、可整体复制运行。示例用 4 维张量（官方 Quickstart 用 384；实际常见 384 / 768 / 1024 / 1536）。

from vespa.package import ApplicationPackage, Field, Schema, Document, HNSW
from vespa.deployment import VespaDocker

# 1)+2) schema-first：先声明 Schema / Document / Field，再部署成应用
package = ApplicationPackage(
    name="hybridsearch",
    schema=[
        Schema(
            name="doc",
            document=Document(fields=[
                Field(name="id", type="string", indexing=["summary"]),
                Field(name="subject", type="string", indexing=["attribute", "summary"]),
                Field(
                    name="embedding",
                    type="tensor<float>(x[4])",   # 示例 4 维；官方 Quickstart 用 384
                    indexing=["attribute"],
                    ann=HNSW(distance_metric="angular"),
                ),
            ]),
        )
    ],
)
app = VespaDocker().deploy(application_package=package)

# 3) 插入：feed 文档（官方 Quickstart 写法），变量全部定义
vespa_feed = [
    {"id": "1", "subject": "history", "embedding": [1.0, 0.0, 0.0, 0.0]},
    {"id": "2", "subject": "history", "embedding": [0.0, 1.0, 0.0, 0.0]},
    {"id": "3", "subject": "ops", "embedding": [0.0, 0.0, 1.0, 0.0]},
]

def cb(response, id):
    if not response.is_successful():
        print("feed 失败", id, response.get_json())

app.feed_iterable(vespa_feed, schema="doc", namespace="tutorial", callback=cb)
qv = [1.0, 0.0, 0.0, 0.0]

with app.syncio(connections=1) as session:
    # 4) 相似度检索：YQL + nearestNeighbor 近似 ANN
    resp = session.query(
        yql="select * from sources * where ({targetHits:1000}nearestNeighbor(embedding,q)) limit 5",
        body={"input.query(q)": qv},
    )
    print("== 纯向量检索 ==", resp.hits)
    # 5) 带标量过滤检索：YQL 追加 and 条件
    resp2 = session.query(
        yql="select * from sources * where ({targetHits:1000}nearestNeighbor(embedding,q)) "
            "and subject contains 'history' limit 5",
        body={"input.query(q)": qv},
    )
    print("== 带过滤检索 ==", resp2.hits)

# 6) 更新（同 id 重新 feed 即覆盖）；7) 删除；8) 清理 = 停止/移除容器或走 Cloud/operator 下线
app.feed_iterable([{"id": "1", "subject": "intro", "embedding": [1.0, 0.0, 0.0, 0.0]}],
                  schema="doc", namespace="tutorial", callback=cb)
app.delete_data(schema="doc", data_id="3", namespace="tutorial")

旧教程会写成什么：① 把 Vespa 当有「稳定版号」的产品，镜像写死某版本或用 latest——滚动发布，应固定构建号；② 改 distance-metric 后不重启就期望生效——改 distance-metric / max-links-per-node 需重启（但无需 re-feed）；③ 把 nearestNeighbor 下的 grouping 计数当精确值——该场景 grouping 计数不精确；④ schema 里还用 uri 类型——已 Deprecated。

补充说明：ApplicationPackage / Schema / Document / Field / HNSW / VespaDocker().deploy / feed_iterable / syncio / session.query(yql=..., body=...) 以官方 Quickstart 为准；resp.hits、回调对象方法、delete_data 及「同 id 重新 feed 即更新」删除与更新方法请以 pyvespa 官方 API 参考为准，参数细节以官方文档为准。

输出怎么读：resp.hits 为命中文档列表。

第 4 步 limit 5 取 Top-5，{targetHits:1000} 是 ANN 候选数（不是返回条数）；第 5 步叠加 and subject contains 'history' 后候选收敛，结果可能少于 5 条——属过滤收敛而非故障。

REST / cURL 等价示例：/search/ 与 YQL、input.query(q) 均为官方资料确认要素；文档写入 / 删除走 /document/v1/（官方资料仅确认前缀，完整 docid 路径格式以官方 Document API 为准，不臆造）。

$ curl -s -X POST http://localhost:8080/search/ \
    -H "Content-Type: application/json" \
    -d '{"yql":"select * from sources * where ({targetHits:1000}nearestNeighbor(embedding,q)) limit 5",
         "input.query(q)":[1.0,0.0,0.0,0.0]}'

6. 索引与检索进阶

6.1 索引参数调优表

6.2 召回、延迟与过滤行为

近似 nearestNeighbor 以少量召回损失换低延迟；提高 targetHits 通常提升 recall、增加延迟。经验做法：用精确路径做基线对比 ANN 的 Top-K 交集测 recall，先固定 limit / targetHits 再调过滤与 rank，须 A/B 压测。官方资料确认过滤 + ANN 存在 post/pre-filtering 与 filter-first-threshold(0.2) 开关；过滤越严格候选越少、结果可能少于 limit，「过滤后召回偏低」先用普通 YQL 计数核对基数，再调整过滤时机，勿假定索引损坏。

6.3 混合检索、多向量 / 稀疏向量 / 重排 / 量化

Vespa 以 YQL 组合 ANN、标量过滤、grouping 与 rank，混合检索 / 重排属其能力范畴；但 BM25 / RRF / 多向量 / 稀疏向量 / 量化压缩的逐字官方条目官方资料未给出，本篇不臆造方法名与开关，以官方文档为准。

6.4 内存与磁盘容量估算（经验公式）

公式：向量大小 ≈ N × D × 4B（float32）；总内存 ≈ 向量 + HNSW 图（受 max-links-per-node 影响） + attribute/summary + 缓冲；磁盘 ≈ 文档 + 索引 + 副本。示例：N=100 万、D=384 → 向量约 1e6 × 384 × 4B ≈ 1.43 GiB，叠加图与副本后按倍数预留。经验估算，非官方承诺，须压测。

7. 生产部署与运维

7.1 形态选择决定运维模型（重点）

版本差异：Vespa 是 schema-first + YQL + 滚动发布的服务化引擎——发布 = 「固定构建号 + 重新 deploy 应用包」，不像嵌入式库改几行代码就生效；升级先锁构建号、再回归 schema 与 YQL。官方 Helm chart 未核实，K8s 走 Vespa Cloud / operator。

7.2 高可用 / 容量规划与扩缩容

Vespa 为分布式引擎、支持多节点与数据分发，但分片 / 副本的具体配置参数官方资料未给出，以官方文档为准。容量按 6.4 估算；扩缩容 = 加节点 / 调副本 / 升配，须同步复核 HNSW 参数与 targetHits。单查询瓶颈优先「收敛过滤、调 targetHits、简化 rank」，再考虑扩容。

7.3 备份与恢复（含索引是否需重建）

⚠️ 危险：改 distance-metric / max-links-per-node 需重启，虽无需 re-feed，但重启窗口要纳入发布计划；不要在运行中直接改 schema 期望热生效。schema 变更必须走重新 deploy + 回归验证。

7.4 监控端点与关键指标、告警阈值建议

建议自建监控：部署就绪状态、/search/ P99 延迟与错误率、feed 失败率、节点内存 / 磁盘（>80% 预警）、副本健康；阈值为经验建议，按自身 SLA 调整。

7.5 升级与跨版本迁移（滚动发布）

① 从 Releases 选定并固定 <固定构建号> 写入发布单；② 用 docker inspect 核对当前实际镜像；③ 预发用同构建号重新 deploy 应用包并跑 schema / YQL 回归；④ 灰度切流，观察 /search/ 延迟与 feed 错误率；⑤ 保留旧构建号以便回滚。不要写死「稳定版」、不要用 latest。

7.6 安全基线

8. 高频故障与排障

9. 常见坑与避坑清单

1. 现象：部署脚本写死「稳定版号」或 latest。原因：Vespa 滚动发布，无单一稳定版号。怎么做：固定 <固定构建号> 并纳入发布单，CLI 8.781.11 不作镜像 tag。
2. 现象：改 distance-metric 后检索结果没变 / 报错。原因：改 distance-metric 需重启。怎么做：重新 deploy / 重启使生效，但无需 re-feed。
3. 现象：改 max-links-per-node 不生效。原因：同属需重启参数。怎么做：纳入重启窗口，重启后回归。
4. 现象：nearestNeighbor 查询的 grouping 计数对不上。原因：该场景 grouping 计数不精确。怎么做：不用于精确报表，改用精确检索核对。
5. 现象：schema 用 uri 类型告警。原因：uri 已 Deprecated。怎么做：改用当前推荐类型，以官方文档为准。
6. 现象：K8s 找不到官方 Helm chart。原因：官方 Helm chart 未核实，K8s 主要走 Vespa Cloud / operator。怎么做：以官方文档确认交付方式，不臆造仓库地址。
7. 现象：健康检查端点 404。原因：健康检查路径未核实，照抄了第三方路径。怎么做：用确认的 vespa status deploy --wait 300 判断就绪。
8. 现象：写 distance_metric="euclidean" 后行为异常。原因：距离度量完整枚举未核实。怎么做：只用确认过的 angular / prenormalized-angular，其它先查官方文档。
9. 现象：过滤后召回偏低。原因：过滤 + ANN 的 pre/post-filtering 行为。怎么做：关注 filter-first-threshold(0.2)，先核对基数再调时机。
10. 现象：把 targetHits 当返回条数。原因：它是 ANN 候选数，返回条数由 limit 决定。怎么做：分别设置 targetHits 与 limit。
11. 现象：YQL 里直接拼接用户输入被注入 / 报错。原因：字符串拼接外部输入。怎么做：查询向量走 input.query(q) 等参数化入参。
12. 现象：schema 改了却没生效。原因：schema-first，变更需重新 deploy 应用包。怎么做：应用包随代码版本化，变更走 deploy + 回归。

⚠️ 危险：distance-metric / max-links-per-node 变更与 schema 重新 deploy 都涉及重启 / 发布窗口，未经回归直接上生产可能导致检索行为变化；务必先在预发验证。

⚠️ 危险：YQL 由外部输入拼接会造成查询注入与数据越权访问；用户输入必须参数化，且 19071 部署端口不得对外暴露。

10. 速查表

10.1 命令 / API 速查

10.2 常用端口与路径

11. 参考与延伸

11.1 官方文档链接清单

11.2 与同册其他产品的关系

需嵌入式、零服务端见 LanceDB.md；本地 / Cloud 双形态、.query() 为主见 Chroma.md；已有 PostgreSQL 做向量检索见 ../02-融合型向量能力/pgvector.md（若已存在）；纯索引库见 ../03-向量索引库/。

11.3 进阶阅读方向

① 官方 approximate-nn-hnsw 文档：distance-metric 全量取值与 HNSW 参数；② YQL 参考：nearestNeighbor、过滤、grouping、rank 组合与 filter-first-threshold；③ schema / 应用包版本化与滚动发布下的回归流程；④ Vespa Cloud / operator 生产交付方式（Helm chart 未核实，勿照抄第三方）。

11.4 本篇「未核实 / 以官方为准」事项（官方资料明确标注）

以下条目官方资料标为「未核实」，正文未写作确定事实，执行前必须以官方文档复核：

1. 距离度量完整枚举——正文仅写确认过的 angular / prenormalized-angular，其余取值以官方文档为准，不得枚举或臆造。
2. 健康检查端点 / 路径——官方未明确；就绪判断只用已确认的 vespa status deploy --wait 300，不照抄第三方 /healthz 之类路径。
3. 官方 Helm chart——官方未明确；K8s 交付方式（Vespa Cloud / operator）以官方文档为准，不臆造 chart 仓库地址。

补充：滚动发布无固定稳定版号、CLI 8.781.11 为 Releases 顶部示例、8080 /search/ 与 /document/v1/、19071、angular / prenormalized-angular、改 distance-metric / max-links-per-node 需重启但无需 re-feed、nearestNeighbor 下 grouping 计数不精确、uri 已 Deprecated、filter-first-threshold(0.2) 均属已核实事实；但 HNSW 全量参数默认值、相关性得分方向、分片 / 副本配置、容器数据目录、混合检索 / 量化细节仍以官方文档为准。