vespa-engine/vespa · 上手攻略

• 仓库：vespa-engine/vespa
• 链接：https://github.com/vespa-engine/vespa
• 分类：ai
• 作者：Tom
• 更新：2026-08-19

它是什么

Vespa 是 Yahoo（现 Verizon Media）开源的企业级 AI 搜索与推荐平台，定位并非单纯的向量数据库，而是将向量检索、全文搜索、结构化数据查询、分布式模型推理全部整合在单一分布式引擎内。用户无需组合 Elasticsearch + Milvus + 推理服务等多家基础设施，一套 Vespa 就能完成从数据索引到结果排序的全部工作。全球生产用户包括 Spotify（音乐推荐）、Perplexity（AI 搜索）、Yahoo（新闻推荐）、AlphaSense（金融搜索）等日均处理亿级请求的平台。

解决什么问题

典型 AI 检索场景面临三难：

• 数据规模大：亿级文档上百万 QPS
• 相关性要求高：需要机器学习模型参与排序，不能只靠 BM25
• 延迟要求严：P99 通常要求 <100ms

传统方案需要多系统协作：向量数据库（Milvus/Pinecone）负责 ANN 检索、Elasticsearch/Solr 负责全文搜索、外部推理服务（TensorFlow Serving/Triton）负责模型打分。这带来严重的工程复杂度——数据同步、一致性保证、跨系统延迟叠加都是坑。

Vespa 的思路是把这些全部做进一个引擎里：文档进来时同时建全文索引和向量索引，查询时多阶段过滤+向量近似搜索+ML 模型打分一条链完成，不需要任何外部服务。

快速安装

方式一：云服务（推荐尝鲜）

免费额度：https://console.vespa-cloud.com，注册后有免费套餐可直接部署应用。

方式二：Docker 单机快速体验

docker run -d --name vespa \
  --hostname vespa \
  --publish 8080:8080 \
  --publish 19071:19071 \
  vespaengine/vespa

容器启动后访问 http://localhost:8080 确认状态。

⚠️ 注意：Docker 方式仅适合本地开发，不适合生产。生产部署建议用 Vespa Cloud 或RPM/DEB 包在物理机/VM 上安装。

方式三：源码构建（贡献者/深度定制）

# 依赖：JDK 17 + Maven 3.8+
git clone https://github.com/vespa-engine/vespa.git
cd vespa
export MAVEN_OPTS="-Xms128m -Xmx1024m"
./bootstrap.sh java
mvn install --threads 1C

⚠️ 注意：全量源码编译需要 ~30GB 内存和 1 小时以上时间，普通用户不需要走这条路。

核心用法

基本概念

Vespa 应用由schema（定义文档结构）、services.xml（定义集群配置）、部署包三部分组成。核心对象：

• Document：要索引的记录，类似数据库一行
• Schema：表结构定义，包含字段和索引配置
• Searcher/Ranker：处理查询逻辑和结果排序
• Query Profile：预设查询参数模板

定义 Schema 示例

schema music {
  document music {
    field title type string {
      indexing: index
    }
    field artist type string {
      indexing: index
    }
    field embedding type tensor<float>(x[128]) {
      indexing: attribute | index
      attribute: hnsw-index
    }
    field year type int {
      indexing: attribute
    }
  }
  rank-profile default inherits default {
    first-phase {
      expression: nativeRank(title, artist)
    }
  }
}

写入文档（Python 示例）

# pip install vespa
from vespa.application import Vespa

app = Vespa(url="http://localhost:8080")

doc = {
    "fields": {
        "title": "Bohemian Rhapsody",
        "artist": "Queen",
        "year": 1975,
        "embedding": [0.1] * 128  # 示例向量，实际需真实模型生成
    }
}
app.feed_data_point("music", "doc1", doc)

全文+向量混合检索（Python）

from vespa.application import Vespa

app = Vespa(url="http://localhost:8080")

# 关键词 + 向量 ANN + 结构化过滤，一次查询完成
query = {
    "yql": 'select * from music where artist contains "Queen" and year > 1970 limit 10',
    "ranking": "nativeRank(title, artist)",
    "vector": "[0.1]*128",  # 实际应传入真实 query embedding
    "hits": 10
}

results = app.query(query)
for hit in results.hits:
    print(hit.fields["title"], hit.relevance)

Query YQL 语法示例

select * from music where
  artist contains "Queen"           -- 关键词过滤
  and year >= 1970                 -- 结构化过滤
  and [{"targetHits": 10}]         -- ANN 向量搜索
  nearAnd下地[0.1, 0.2, ...]       -- ⚠️ 语法以实际版本为准
limit 50

⚠️ 不确定处：Vespa 的 YQL 语法中，向量搜索推荐写法为 [{"targetHits": 10}]nearestNeighbor(embedding, query_embedding)，建议直接参考 docs.vespa.ai 确认当前版本语法。

API 端口说明

典型适用场景

1. AI RAG 检索层：结合 LLM 实现 RAG，向量+关键词混合搜索比纯向量召回准确度高
2. 电商/内容推荐：多维特征（用户画像+商品属性+行为）综合排序，不只是相似度
3. 新闻媒体搜索：需要同时支持关键词精准匹配 + 语义相似 + 时间衰减 + 热度加权的复杂排序
4. 金融文档检索：精确过滤（公司名、日期、公告类型）+ 语义相似双重需求
5. Perplexity 等 AI 搜索产品：生产级别 RAG 管道，日均亿级请求

坑与注意

• HNSW 参数调优：hnsw-index 的 M（连接数）和 efConstruction 影响召回率和索引大小，默认值不一定最优，需在 ANN benchmarks 上验证
• 内存消耗大：向量索引全部驻内存，生产环境建议内存/索引大小比 ≥ 1.5
• Schema 变更麻烦：已部署 schema 加字段容易，但改字段类型或删除字段需要重建索引，提前规划好
• 文档语言门槛：服务端开发者需要对 Java 或 C++ 有一定了解，定制 Ranker 需要写 Java
• 冷启动延迟：Vespa Cloud 免费套餐冷启动有 ~30s 延迟，不适合极端实时场景
• 不是银弹：如果只是简单的向量存储+检索，用专用向量库（Qdrant/Milvus）更轻量；Vespa 的优势在于复杂排序逻辑和大规模数据

与同类对比

Vespa 的核心差异化是把 ML 推理做进引擎：可以在查询时对每个候选文档跑一个 ONNX 模型打分，不需要把文档拿去外部推理服务。这对需要深度排序的搜索场景是决定性优势。

一句话推荐结论

如果你要做生产级 AI 搜索（不只是简单 RAG），需要向量+全文混合+ML排序+高并发+Vespa 是目前开源里最完整的方案；如果只是轻量向量检索，Qdrant 更简单好上手。