Vespa 使用教程：Docker 启动与检索验证

Vespa 是一个支持关键词检索、向量检索和结构化过滤的搜索引擎。
如果你想先把它跑起来看看效果，最省事的方式是用 Docker 启动单节点模式，再部署一个最小 application package，最后用 curl 写入数据并执行查询。
本文按这个顺序展开，适合第一次接触 Vespa、想在本地或测试机验证检索能力的读者。

先确认运行环境和端口

Vespa 对内存比较敏感，单节点验证建议至少 4GB 可用内存。
需要准备：

• 一台能运行 Docker 的 Linux 主机或本地开发机，已安装 docker 并启动服务
• 能访问 Docker Hub 的网络环境
• 主机上可用的 curl 和文本编辑器
• 记录好要映射的端口，Vespa 默认使用 8080（文档与查询接口）和 19071（配置服务）

先拉取镜像并启动容器：

docker pull vespaengine/vespa
docker run --detach --name vespa --hostname vespa-container \
  --publish 8080:8080 --publish 19071:19071 \
  vespaengine/vespa

启动后配置服务需要一点时间，用下面的命令确认它已经就绪，返回内容里能看到状态信息即表示可以继续：

curl -s http://localhost:19071/state/v1/health

如果长时间没有响应，先执行 docker logs vespa 查看容器日志，常见原因是内存不足或端口被占用。

编写最小 application package

Vespa 的索引结构、字段类型和检索行为都写在 application package 里。
新建一个目录，放入两个文件。

schemas/doc.sd 定义字段和检索方式：

schema doc {
  document doc {
    field id type string {
      indexing: summary | attribute
    }
    field title type string {
      indexing: summary | index
    }
    field embedding type tensor(d[4]) {
      indexing: summary | attribute
      attribute: tensor(d[4])
    }
  }
  rank-profile default {
    first-phase {
      expression: closeness(field, embedding)
    }
  }
}

services.xml 声明单节点容器集群：

  
    
    
    
      
    
  
  
    1
    
      
    
    
      
    
  

把这两个文件按 app/schemas/doc.sd 和 app/services.xml 的目录结构放好，然后打包并部署：

cd app && zip -r ../app.zip . && cd ..
curl --header Content-Type:application/zip \
  --data-binary @app.zip \
  http://localhost:19071/application/v2/tenant/default/prepareandactivate

部署接口返回的 JSON 中 status 为 active 时，说明配置已生效。

写入测试数据并执行查询

先写入一条带向量的文档，注意 id 的命名空间和文档类型要与 schema 对应：

curl -s -X POST http://localhost:8080/document/v1/default/doc/docid/1 \
  -H 'Content-Type: application/json' \
  -d '{"fields":{"id":"1","title":"vespa tutorial","embedding":[0.1,0.2,0.3,0.4]}}'

返回中包含 id 字段就表示写入成功。
接着做一次近似向量检索：

curl -s http://localhost:8080/search/ \
  -H 'Content-Type: application/json' \
  -d '{"yql":"select * from doc where {targetHits:10}nearestNeighbor(embedding, q)","input.query(q):[0.1,0.2,0.3,0.4],"ranking.profile":"default"}'

响应里的 root.children 数组应包含刚写入的文档。
如果数组为空，先确认 input.query(q) 的维度与 schema 中 tensor(d[4]) 一致，维度不匹配时查询不会报错但也不会命中。

容易踩的几个坑

• 部署超时：prepareandactivate 返回错误时，用 docker exec vespa vespa-logfmt -l error 查看配置服务日志，多数是 application package 语法错误。
• 查询无结果：除了维度问题，还要检查 ranking.profile 是否与 schema 中定义的 rank-profile 名称一致。
• 容器重启后数据丢失：上面命令没有挂载数据卷，验证阶段可以接受；需要保留数据时给 docker run 增加 -v vespa-data:/opt/vespa/var 之类的挂载参数。
• 内存不足：Vespa 启动后占用内存较高，在小规格机器上容易出现容器反复退出，建议先确认可用内存再启动。

验证服务是否真正可用

完成上面步骤后，可以用两个检查点确认环境正常：访问 http://localhost:8080/ 能看到 Vespa 的默认页面；
重新执行一次查询命令，返回结果中 totalCount 大于 0。
做到这两点，说明单节点 Vespa 已经可以用于后续的检索实验。

常见疑问：Vespa 必须用 Docker 吗？
不是，也可以按官方文档在主机上安装，但 Docker 方式更适合快速验证。
application package 改完要重新部署吗？
需要，每次修改 schema 或 services 后都要重新打包并调用部署接口。
单节点能用于生产吗？
单节点主要适合开发和测试，生产环境通常需要多节点和冗余配置。