在服务时以任意规模对向量、张量、文本和结构化数据进行搜索、推理和组织。

本仓库包含构建和运行 Vespa 所需的所有代码，并且您可以实时查看所有开发进展。 本仓库中的所有内容均采用 Apache 2.0 许可证授权。

每周一至周四上午中欧时间，都会从该仓库的 master 分支发布 Vespa 的新版本。

• 首页：https://vespa.ai
• 文档：https://docs.vespa.ai
• 持续集成：https://factory.vespa.ai
• 在云端免费运行应用：vespa.ai/free-trial

目录

• 背景
• 安装
• 使用
• 贡献
• 构建
• 许可证

背景

诸如搜索、推荐和个性化等用例需要从庞大的语料库中筛选出一部分数据， 对这些数据运行机器学习模型进行评估，再对其进行组织和聚合后返回结果，整个过程通常需要在不到 100 毫秒内完成， 而且数据语料库还在不断变化。

要做到这一点非常困难，尤其是在处理需要分布到多个节点并并行计算的大规模数据集时。Vespa 是一个能够为您高效、高可用地执行这些操作的平台。 它经过多年的发展，已被多家大型互联网服务和应用所采用，每秒可处理数十万次来自 Vespa 的查询请求。

安装

将您的 Vespa 应用部署到云服务：console.vespa-cloud.com， 或自行运行一个 Vespa 实例：https://docs.vespa.ai/en/getting-started.html

使用

• 上文链接的入门指南中创建的应用程序已经完全可用且可用于生产环境，但您可能希望添加更多节点以提高冗余性。
• 有关如何为您的 Vespa 应用程序添加自定义 Java 组件，请参阅开发应用程序。
• Vespa API 有助于理解如何与 Vespa 进行交互。
• 浏览示例应用程序。
• 关注Vespa 博客以获取功能更新和用例信息。
• 加入Vespa Slack 社区提问并分享反馈。

完整文档请访问https://docs.vespa.ai。

贡献

我们欢迎各方贡献！请参阅CONTRIBUTING.md，了解如何参与贡献。 如果您想为文档做出贡献，请访问 https://github.com/vespa-engine/documentation。

构建

您无需构建 Vespa 即可使用它，但如果您想参与贡献，则需要能够编译代码。 本节将说明如何构建和测试 Vespa。要了解应在何处进行修改，请参阅Code-map.md。 一些带有代码指针的改进建议可在TODO.md中找到。

开发环境

C++ 和 Java 的编译支持 AlmaLinux 8 系统。 Java 源代码也可以在任何已安装 Java 17 和 Maven 3.8+ 的平台上编译。 请参考以下指南，使用 Docker 设置完整的开发环境，用于构建 Vespa、运行单元测试和系统测试： Vespa 在 AlmaLinux 8 上的开发。

Mac 上的 Java 环境

1. 通过 Homebrew 安装 JDK17、 Maven 版本管理器 和 jEnv：

brew install jenv mvnvm openjdk@17

2. 对于 ARM 架构的 Mac（如 M1、M2 等），由于 grpc 尚未得到良好维护，请安装 Intel 兼容层：

softwareupdate --install-rosetta

3. 为了让系统 Java 包装器找到此 JDK，需创建符号链接：

sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

4. 按照 https://www.jenv.be 中的“配置您的 shell”步骤操作。配置因 shell 而异。对于 zsh，请使用以下命令：

echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(jenv init -)"' >> ~/.zshrc
eval "$(jenv init -)"
jenv enable-plugin export
exec $SHELL -l

5. 将 JDK17 添加到 jEnv：

jenv add $(/usr/libexec/java_home -v 17)

6. 通过在源代码根目录下执行以下命令来验证配置是否正确。输出应显示 .java-version 和 mvnvm.properties 中指定的 JDK 和 Maven 版本。

mvn -v

编译 Java 模块

export MAVEN_OPTS="-Xms128m -Xmx1024m"
./bootstrap.sh java
mvn install --threads 1C

如果您只需要编译 Java 模块，可以使用此方法；否则，请按照上述完整的开发指南操作。

在 Mac 上运行 Shell 脚本测试

Shell 脚本使用 BATS 进行测试。 要在本地运行测试，请先安装测试框架及其插件：

brew install node
sudo npm install -g bats bats-assert bats-support bats-mock

导出 BATS_PLUGIN_PATH 环境变量，使其指向全局 npm 模块目录，该目录包含 BATS 插件：

export BATS_PLUGIN_PATH="$(npm root -g)"

然后在仓库根目录下运行以下命令以执行所有测试：

bats -r .

要运行特定的测试，可以使用：

bats test_dir/test_name.bats

此外，也可以在 IntelliJ IDEA 中使用 BashSupport Pro 插件来运行测试。请确保在启动 IDE 之前已导出 BATS_PLUGIN_PATH 环境变量，以免需要在每个运行配置中单独设置。

许可证

代码采用 Apache 2.0 许可证授权。详细条款请参阅 LICENSE 文件。

Vespa 快速上手指南

Vespa 是一个高性能的大数据处理与实时计算引擎，适用于搜索、推荐、个性化及向量检索等场景。它能够在毫秒级延迟下，对海量数据进行过滤、机器学习模型推理、聚合与排序。

环境准备

系统要求

• 推荐系统: AlmaLinux 8 (官方构建环境)。
• 通用支持: 任何安装了 Java 17 和 Maven 3.8+ 的操作系统（Linux, macOS, Windows via WSL）。
• macOS 特别说明:
  • 需安装 Rosetta 2 (针对 M1/M2 等 ARM 芯片)，因为部分 gRPC 组件依赖 Intel 架构兼容层。
  • 推荐使用 Docker 进行开发以获得一致的环境体验。

前置依赖

请确保已安装以下工具：

• JDK: OpenJDK 17
• 构建工具: Maven 3.8+
• 容器化 (可选但推荐): Docker

macOS 用户快速配置命令:

# 1. 安装必要工具 (通过 Homebrew)
brew install jenv mvnvm openjdk@17

# 2. ARM 芯片 (M1/M2) 安装 Intel 兼容层
softwareupdate --install-rosetta

# 3. 创建 JDK 软链接以便系统识别
sudo ln -sfn /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk /Library/Java/JavaVirtualMachines/openjdk-17.jdk

# 4. 配置 jEnv (以 zsh 为例)
echo 'export PATH="$HOME/.jenv/bin:$PATH"' >> ~/.zshrc
echo 'eval "$(jenv init -)"' >> ~/.zshrc
eval "$(jenv init -)"
jenv enable-plugin export
exec $SHELL -l

# 5. 将 JDK 17 添加到 jEnv 管理
jenv add $(/usr/libexec/java_home -v 17)

# 6. 验证版本
mvn -v

安装步骤

Vespa 提供两种主要使用方式：云端托管（最快上手）和 本地自建。

方案 A：使用 Vespa Cloud (推荐新手)

无需配置本地环境，直接在云端免费试用。

1. 访问 Vespa Cloud Console。
2. 注册账号并创建新应用。
3. 按照网页指引部署即可。

方案 B：本地自建 (Docker 方式)

适合需要在本地调试或私有化部署的开发者。

1. 拉取并运行 Vespa Docker 镜像:

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

   注：启动可能需要几分钟，可通过 docker logs --follow vespa 查看进度，直到出现 "Vespa started" 字样。

2. 验证安装: 访问 http://localhost:8080/ApplicationStatus 确认服务状态为 up。

3. 部署示例应用: 确保本地已安装 vespa-cli (或通过 Docker 执行)，部署一个简单的搜索应用：

   # 如果使用本地 vespa-cli
   vespa deploy --wait-for-deployment
   
   # 或者直接使用官方提供的 sample-apps (需先 git clone)
   # cd sample-apps/basic-search
   # vespa deploy --wait-for-deployment
   

基本使用

以下演示如何向 Vespa 写入数据并执行查询。假设你已部署了基础的 basic-search 示例应用。

1. 写入文档 (Feed)

创建一个名为 feed.json 的文件，包含测试数据：

[
  {
    "put": "id:music:music::1",
    "fields": {
      "title": "Best of Blues",
      "artist": "B.B. King",
      "year": 2000,
      "category_scores": {
        "cells": [
          {"address": {"cat": "pop"}, "value": 0.1},
          {"address": {"cat": "rock"}, "value": 0.2},
          {"address": {"cat": "blues"}, "value": 0.9}
        ]
      }
    }
  },
  {
    "put": "id:music:music::2",
    "fields": {
      "title": "Greatest Hits",
      "artist": "Queen",
      "year": 1981,
      "category_scores": {
        "cells": [
          {"address": {"cat": "pop"}, "value": 0.8},
          {"address": {"cat": "rock"}, "value": 0.9},
          {"address": {"cat": "blues"}, "value": 0.1}
        ]
      }
    }
  }
]

执行写入命令：

vespa feed feed.json

2. 执行查询 (Query)

使用 vespa query 或 curl 进行搜索。例如，查找艺术家为 "Queen" 的歌曲：

vespa query "select * from music where artist contains 'Queen'"

或者使用原生 HTTP API：

curl -H "Content-Type: application/json" \
  "http://localhost:8080/search/?query=queen&hits=2"

3. 下一步

• 自定义开发: 参考 开发者指南 添加自定义 Java 组件。
• 更多示例: 浏览 sample-apps 仓库获取搜索、推荐、向量检索等完整案例。
• 社区交流: 加入 Vespa Slack 获取技术支持。