跳至主要内容
前往文档
⌘U
Weaviate 数据库

使用 Weaviate 的 APIs 和工具开发 AI 应用

部署

部署、配置和维护 Weaviate 数据库

Weaviate Agents

使用 Weaviate 构建和部署智能代理

Weaviate Cloud

在云端管理和扩展 Weaviate

更多资源

集成
贡献者指南
活动 & 工作坊
Weaviate Academy

需要帮助？

Weaviate Logo询问 AI 助手⌘K
社区论坛

Java v5

Java v5 即将弃用

The Java 客户端 v6 已发布。新的 Weaviate 功能将不再受 v5 客户端支持，我们建议切换到 v6 客户端。

Java 客户端 (SDK)

最新的 Java v5 客户端版本是 v5.5.0。

weaviate/java-client

安装和设置​

要获取 Java 客户端库的最新稳定版本，请将此依赖项添加到您的项目中

<dependency>
  <groupId>io.weaviate</groupId>
  <artifactId>client</artifactId>
  <version>4.7.0</version>  <!-- Check latest version -->
</dependency>

此 API 客户端与 Java 8 及更高版本兼容。

您可以在项目中如下使用客户端

package io.weaviate;

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;
import io.weaviate.client.base.Result;
import io.weaviate.client.v1.misc.model.Meta;

public class App {
  public static void main(String[] args) {
    Config config = new Config("http", "localhost:8080");
    WeaviateClient client = new WeaviateClient(config);
    Result<Meta> meta = client.misc().metaGetter().run();
    if (meta.getError() == null) {
      System.out.printf("meta.hostname: %s\n", meta.getResult().getHostname());
      System.out.printf("meta.version: %s\n", meta.getResult().getVersion());
      System.out.printf("meta.modules: %s\n", meta.getResult().getModules());
    } else {
      System.out.printf("Error: %s\n", meta.getError().getMessages());
    }
  }
}

身份验证​

有关配置 Weaviate 身份验证的更全面信息，请参阅 身份验证 页面。

TheJava客户端提供多种针对 Weaviate 进行身份验证的选项，包括多种 OIDC 身份验证流程。

客户端的合适身份验证选项和方法在很大程度上取决于 Weaviate 实例的特定配置。

WCD 身份验证​

WCD + Weaviate 客户端

在 Weaviate Cloud (WCD) 中，每个 Weaviate 实例都预配置为充当 OIDC 身份验证的令牌颁发者。

请参阅我们的 WCD 身份验证文档，了解如何使用您首选的 Weaviate 客户端对 WCD 进行身份验证。

API 密钥身份验证​

添加到 Weaviate Java 客户端版本 4.0.2。

如果您使用 API 密钥进行身份验证，请像这样实例化客户端

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;

Config config = new Config("https", "WEAVIATE_INSTANCE_URL");
WeaviateClient client = WeaviateAuthClient.apiKey(config, "YOUR-WEAVIATE-API-KEY");  // Replace with your Weaviate instance API key

OIDC 身份验证​

要使用 OIDC 对 Weaviate 进行身份验证，您必须选择由身份提供程序提供的流程并创建特定于该流程的身份验证配置。

然后，客户端将使用该配置来验证身份。该配置包括有助于客户端获取 访问令牌 和（如果配置）刷新令牌 的密钥。

将 访问令牌 添加到每个请求的 HTTP 标头中，并用于使用 Weaviate 进行身份验证。通常，此令牌的生命周期有限，并且可以使用 刷新令牌 在必要时获取一组新的令牌。

资源所有者密码流程​

此 OIDC 流程使用用户名和密码来获取所需的令牌进行身份验证。

请注意，并非每个提供程序都会自动包含 刷新令牌，并且可能需要一个特定的 范围，具体取决于您的身份提供程序。客户端默认使用 offline_access 作为范围。这适用于某些提供程序，但由于它取决于身份提供程序的配置，我们建议您参考身份提供程序的文档。

如果没有刷新令牌，则无法获取新的 访问令牌，并且客户端在到期后将无法进行身份验证。

注意

Weaviate 客户端不会保存用于的用户名或密码。

它们仅用于获取第一个令牌，之后将使用现有的令牌来获取后续的令牌（如果可能）。

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;

Config config = new Config("http", "weaviate.example.com:8080");
WeaviateAuthClient.clientPassword(
    config,
    "Your user",
    "Your password",
    Arrays.asList("scope1", "scope2") // optional, depends on the configuration of your identity provider (not required with WCD)
);

客户端凭据流程​

此 OIDC 流程使用 客户端密钥 来获取所需的令牌进行身份验证。

此流程建议用于服务器到服务器的通信，而无需最终用户，并向 Weaviate 验证应用程序。此身份验证流程通常被认为比资源所有者密码流程更安全：可以简单地撤销受损的客户端密钥，而受损的密码可能会产生超出身份验证范围的更大影响。

为了验证客户端密钥，大多数身份提供程序要求指定一个 范围。此 范围 取决于身份提供程序的配置，因此我们建议您参考身份提供程序的文档。

大多数提供程序不会在其响应中包含刷新令牌，因此 客户端密钥 会保存在客户端中，以便在现有令牌到期时获取新的 访问令牌。

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;

Config config = new Config("http", "weaviate.example.com:8080");
WeaviateAuthClient.clientCredentials(
    config,
    "your_client_secret",
    Arrays.asList("scope1" ,"scope2") // optional, depends on the configuration of your identity provider
);

刷新令牌流程​

可以使用任何其他 OIDC 身份验证方法直接从您的身份提供程序获取令牌，例如，使用 混合流程 的分步指南。

如果未提供 刷新令牌，则无法获取新的 访问令牌，并且客户端在到期后将无法进行身份验证。

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateAuthClient;

Config config = new Config("http", "weaviate.example.com:8080");
WeaviateAuthClient.bearerToken(
    config,
    "Your_access_token",
    500,  // lifetime in seconds
    "Your_refresh_token",
);

自定义标头​

您可以在初始化时将自定义标头传递给客户端

import io.weaviate.client.Config;
import io.weaviate.client.WeaviateClient;

public class App {
  public static void main(String[] args) {
    Map<String, String> headers = new HashMap<String, String>() { {
      put("header_key", "value");
    } };
    Config config = new Config("http", "localhost:8080", headers);
    WeaviateClient client = new WeaviateClient(config);
  }
}

参考​

所有 RESTful 端点 和 GraphQL 函数 引用都包含在 Java 客户端中，并在这些参考页面中的代码块中进行了说明。

类型化的 GraphQL 响应​

Weaviate Java 客户端支持将 GraphQL 查询响应自动反序列化为 Java 对象。这消除了手动 JSON 解析的需要，并在使用集合数据时提供了编译时类型安全。

例如，您可以定义一个 Pizzas 类来捕获以下查询的响应

@Getter
public static class Pizzas {
  @SerializedName(value = "Pizza")
  List<Pizza> pizzas;

  @Getter
  public static class Pizza extends GraphQLGetBaseObject {
    String name;
    String description;
    String bestBefore;
    Float price;
  }
}

try (WeaviateAsyncClient asyncClient = client.async()) {
  return asyncClient.graphQL().get()
    .withClassName("Pizza")
    .withFields(Field.builder().name("name").build(), Field.builder().name("description").build())
    .run(Pizzas.class)
    .get();
}

作为回报，响应将是一个 GraphQLTypedResponse<Pizzas> 对象

Result<GraphQLTypedResponse<Pizzas>> result = getResults();

List<Pizzas.Pizza> pizzas = result.getResult().getData().getObjects().getPizzas();

Pizzas.Pizza pizza = pizzas.get(0);

// access Pizza specific properties
Float price = pizza.getPrice();

// access _additional values like vector (and others)
Float[] vector = pizza.getAdditional().getVector();
Float certainty = pizza.getAdditional().getCertainty();

设计​

构建器模式​

Java 客户端函数的设计采用“构建器模式”。使用模式来构建复杂的查询对象。这意味着一个函数（例如，从 Weaviate 检索数据，类似于 RESTful GET 请求或更复杂的 GraphQL 查询）是通过单个对象构建的，以减少复杂性。一些构建器对象是可选的，其他对象是执行特定函数所必需的。所有内容均记录在 RESTful API 参考页面 和 GraphQL 参考页面 上。

上面的代码片段显示了一个类似于 RESTful GET /v1/meta 的简单查询。通过需要包并连接到正在运行的实例来启动客户端。然后，通过在 .misc() 上使用 .metaGetter() 来构建查询。该查询将使用 .run() 函数发送，因此此对象是您想要构建和执行的每个函数所必需的。

迁移指南​

从 3.x.x 到 4.0.0​

从 technology.semi.weaviate 移动到 io.weaviate 包​

之前

package technology.semi.weaviate;
import technology.semi.weaviate.client.*;

之后

package io.weaviate;
import io.weaviate.client.*;

从 2.4.0 到 3.0.0​

删除了 @Deprecated 方法 Aggregate::withFields(Fields fields)​

之前

// import io.weaviate.client.v1.graphql.query.fields.Field;
// import io.weaviate.client.v1.graphql.query.fields.Fields;

Fields fields = Fields.builder().fields(new Field[]{name, description}).build();
client.graphQL().aggregate().withFields(fields)...

之后

client.graphQL().aggregate().withFields(name, description)...

删除了 @Deprecated 方法 Get::withFields(Fields fields)​

之前

// import io.weaviate.client.v1.graphql.query.fields.Field;
// import io.weaviate.client.v1.graphql.query.fields.Fields;

Fields fields = Fields.builder().fields(new Field[]{name, description}).build();
client.graphQL().get().withFields(fields)...

之后

client.graphQL().get().withFields(name, description)...

删除了 @Deprecated 方法 Get::withNearVector(Float[] vector)​

之前

client.graphQL().get().withNearVector(new Float[]{ 0f, 1f, 0.8f })...

之后

// import io.weaviate.client.v1.graphql.query.argument.NearVectorArgument;

NearVectorArgument nearVector = NearVectorArgument.builder().vector(new Float[]{ 0f, 1f, 0.8f }).certainty(0.8f).build();
client.graphQL().get().withNearVector(nearVector)...

所有 where 过滤器使用相同的实现​

使用 批量删除 功能，引入了统一的 filters.WhereFilter 实现，它取代了 classifications.WhereFilter、graphql.query.argument.WhereArgument 和 graphql.query.argument.WhereFilter。

GraphQL​

之前

// import io.weaviate.client.v1.graphql.query.argument.GeoCoordinatesParameter;
// import io.weaviate.client.v1.graphql.query.argument.WhereArgument;
// import io.weaviate.client.v1.graphql.query.argument.WhereOperator;

GeoCoordinatesParameter geo = GeoCoordinatesParameter.builder()
    .latitude(50.51f)
    .longitude(0.11f)
    .maxDistance(3000f)
    .build();
WhereArgument where = WhereArgument.builder()
    .valueGeoRange(geo)
    .operator(WhereOperator.WithinGeoRange)
    .path(new String[]{ "add "})
    .build();

client.graphQL().aggregate().withWhere(where)...

之后

// import io.weaviate.client.v1.filters.Operator;
// import io.weaviate.client.v1.filters.WhereFilter;

WhereFilter where = WhereFilter.builder()
    .valueGeoRange(WhereFilter.GeoRange.builder()
        .geoCoordinates(WhereFilter.GeoCoordinates.builder()
            .latitude(50.51f)
            .longitude(0.11f)
            .build()
        )
        .distance(WhereFilter.GeoDistance.builder()
            .max(3000f)
            .build()
        )
        .build()
    )
    .operator(Operator.WithinGeoRange)
    .path(new String[]{ "add" })
    .build();

client.graphQL().aggregate().withWhere(where)...

之前

// import io.weaviate.client.v1.graphql.query.argument.WhereArgument;
// import io.weaviate.client.v1.graphql.query.argument.WhereOperator;

WhereArgument where = WhereArgument.builder()
    .valueText("txt")
    .operator(WhereOperator.Equal)
    .path(new String[]{ "add" })
    .build();

client.graphQL().aggregate().withWhere(where)...

之后

// import io.weaviate.client.v1.filters.Operator;
// import io.weaviate.client.v1.filters.WhereFilter;

WhereFilter where = WhereFilter.builder()
    .valueText("txt")
    .operator(Operator.Equal)
    .path(new String[]{ "add" })
    .build();

client.graphQL().aggregate().withWhere(where)...

之前

// import io.weaviate.client.v1.graphql.query.argument.WhereArgument;
// import io.weaviate.client.v1.graphql.query.argument.WhereFilter;
// import io.weaviate.client.v1.graphql.query.argument.WhereOperator;

WhereArgument where = WhereArgument.builder()
    .operands(new WhereFilter[]{
        WhereFilter.builder()
            .valueInt(10)
            .path(new String[]{ "wordCount" })
            .operator(WhereOperator.LessThanEqual)
            .build(),
        WhereFilter.builder()
            .valueText("word")
            .path(new String[]{ "word" })
            .operator(WhereOperator.LessThan)
            .build()
    })
    .operator(WhereOperator.And)
    .build();

client.graphQL().aggregate().withWhere(where)...

之后

// import io.weaviate.client.v1.filters.Operator;
// import io.weaviate.client.v1.filters.WhereFilter;

WhereFilter where = WhereFilter.builder()
    .operands(new WhereFilter[]{
        WhereFilter.builder()
            .valueInt(10)
            .path(new String[]{ "wordCount" })
            .operator(Operator.LessThanEqual)
            .build(),
        WhereFilter.builder()
            .valueText("word")
            .path(new String[]{ "word" })
            .operator(Operator.LessThan)
            .build(),
    })
    .operator(Operator.And)
    .build();

client.graphQL().aggregate().withWhere(where)...
分类​

之前

// import io.weaviate.client.v1.classifications.model.GeoCoordinates;
// import io.weaviate.client.v1.classifications.model.Operator;
// import io.weaviate.client.v1.classifications.model.WhereFilter;
// import io.weaviate.client.v1.classifications.model.WhereFilterGeoRange;
// import io.weaviate.client.v1.classifications.model.WhereFilterGeoRangeDistance;

WhereFilter where = WhereFilter.builder()
    .valueGeoRange(WhereFilterGeoRange.builder()
        .geoCoordinates(GeoCoordinates.builder()
            .latitude(50.51f)
            .longitude(0.11f)
            .build())
        .distance(WhereFilterGeoRangeDistance.builder()
            .max(3000d)
            .build())
        .build())
    .operator(Operator.WithinGeoRange)
    .path(new String[]{ "geo" })
    .build();

client.classifications().scheduler().withTrainingSetWhereFilter(where)...

之后

// import io.weaviate.client.v1.filters.Operator;
// import io.weaviate.client.v1.filters.WhereFilter;

WhereFilter where = WhereFilter.builder()
    .valueGeoRange(WhereFilter.GeoRange.builder()
        .geoCoordinates(WhereFilter.GeoCoordinates.builder()
            .latitude(50.51f)
            .longitude(0.11f)
            .build())
        .distance(WhereFilter.GeoDistance.builder()
            .max(3000f)
            .build())
        .build())
    .operator(Operator.WithinGeoRange)
    .path(new String[]{ "geo" })
    .build();

client.classifications().scheduler().withTrainingSetWhereFilter(where)...

发布版本​

转到 GitHub 发布页面，以查看 Java 客户端库发布的历史记录。

点击此处查看 Weaviate 和相应客户端版本的表格

此表列出了最新的五个 Weaviate 数据库版本和相应的客户端库版本。

Weaviate 数据库
(GitHub)		首次
发布日期		Python
(GitHub)		TypeScript/
JavaScript
(GitHub)		Go
(GitHub)		Java
(GitHub)
1.35.x2025-12-174.19.xN/AN/AN/A
1.34.x2025-11-054.18.x3.10.x5.6.x6.0.0
1.33.x2025-09-254.17.x3.9.x5.5.x5.5.x
1.32.x2025-07-144.16.x3.8.x5.3.x5.4.x
1.31.x2025-05-304.15.x3.6.x5.2.x5.3.x
1.30.x2025-04-034.12.x3.5.x5.1.x5.2.x
1.29.x2025-02-174.11.x3.4.x5.0.x5.1.x
旧版本发布
Weaviate 数据库
(GitHub)		首次
发布日期		Python
(GitHub)		TypeScript/
JavaScript
(GitHub)		Go
(GitHub)		Java
(GitHub)
1.28.x2024-12-114.10.x3.3.x4.16.x5.0.x
1.27.x2024-10-164.9.x3.2.x4.16.x5.0.x
4.9.x
1.26.x2024-07-224.7.x3.1.x4.15.x4.8.x
1.25.x2024-05-104.6.x2.1.x4.13.x4.6.x
1.24.x2024-02-274.5.x2.0.x4.10.x4.4.x
1.23.x2023-12-183.26.x1.5.x4.10.x4.4.x
1.22.x2023-10-273.25.x1.5.x4.10.x4.3.x
1.21.x2023-08-173.22.x1.4.x4.9.x4.2.x
1.20.x2023-07-063.22.x1.1.x4.7.x4.2.x
1.19.x2023-05-043.17.x1.1.x14.7.x4.0.x
1.18.x2023-03-073.13.x2.14.x4.6.x3.6.x
1.17.x2022-12-203.9.x2.14.x4.5.x3.5.x
1.16.x2022-10-313.8.x2.13.x4.4.x3.4.x
1.15.x2022-09-073.6.x2.12.x4.3.x3.3.x
1.14.x2022-07-073.6.x2.11.x4.2.x3.2.x
1.13.x2022-05-033.4.x2.9.x4.0.x2.4.x
1.12.x2022-04-053.4.x2.8.x3.0.x2.3.x
1.11.x2022-03-143.2.x2.7.x2.6.x2.3.x
1.10.x2022-01-273.1.x2.5.x2.4.x2.1.x
1.9.x2021-12-103.1.x2.4.x2.4.x2.1.x
1.8.x2021-11-303.1.x2.4.x2.3.x1.1.x
1.7.x2021-09-013.1.x2.4.x2.3.x1.1.x
1.6.x2021-08-112.4.x2.3.x2.2.x1.0.x
1.5.x2021-07-132.2.x2.1.x2.1.x1.0.x
1.4.x2021-06-092.2.x2.1.x2.1.x1.0.x
1.3.x2021-04-232.2.x2.1.x2.1.x1.0.x
1.2.x2021-03-152.2.x2.0.x1.1.x-
1.1.x2021-02-102.1.x---
1.0.x2021-01-142.0.x---

TypeScript 客户端变更​

TypeScript 客户端 于 2023-03-17 替换了 JavaScript 客户端。

问题和反馈​

如果您有任何问题或反馈，请在 用户论坛 中告诉我们。

技术问题

如果您有任何问题，请在我们的 社区论坛 上发帖。

文档反馈

通过打开 GitHub issue 提供反馈。

此页面是否有帮助？