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

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

部署

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

Weaviate Agents

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

Weaviate Cloud

在云端管理和扩展 Weaviate

更多资源

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

需要帮助？

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

Go

Go 客户端 (SDK)

最新的 Go 客户端版本是 v5.6.0。

weaviate/weaviate-go-client

Weaviate Go 客户端与 Go 1.16+ 兼容。

安装​

客户端不支持旧的 Go 模块系统。 在导入 Weaviate 客户端之前，请为您的代码创建一个仓库。

创建仓库

go mod init github.com/weaviate-go-client
go mod tidy

要获取 Go 客户端库的最新稳定版本，请运行以下命令

go get github.com/weaviate/weaviate-go-client/v4

示例​

此示例建立与您的 Weaviate 实例的连接并检索模式。

package main

import (
	"context"
	"fmt"
	"github.com/weaviate/weaviate-go-client/v5/weaviate"
)

func GetSchema() {
    cfg := weaviate.Config{
        Host:   "localhost:8080",
		  Scheme: "http",
    }
    client, err := weaviate.NewClient(cfg)
    if err != nil {
        panic(err)
    }

    schema, err := client.Schema().Getter().Do(context.Background())
    if err != nil {
        panic(err)
    }
    fmt.Printf("%v", schema)
}

func main() {
   GetSchema()
}

身份验证​

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

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

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

WCD 身份验证​

WCD + Weaviate 客户端

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

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

API 密钥身份验证​

在 Weaviate Go 客户端版本 4.7.0 中添加。

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

cfg := weaviate.Config{
	Host:       "weaviate.example.com",
	Scheme:     "http",
	AuthConfig: auth.ApiKey{Value: "my-secret-key"},
	Headers:    nil,
}
client, err := weaviate.NewClient(cfg)
if err != nil{
  fmt.Println(err)
}

OIDC 身份验证​

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

然后，Weaviate 客户端将使用此配置来验证身份。 该配置包括有助于客户端获取 access token 以及（如果配置）refresh token 的密钥。

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

资源所有者密码流程​

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

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

如果没有 refresh token，则无法获取新的 access token，并且客户端在到期后将无法进行身份验证。

注意

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

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

cfg := weaviate.Config{
	Host:   "weaviate.example.com",
	Scheme: "http",
	AuthConfig: auth.ResourceOwnerPasswordFlow{
		Username: "Your user",
		Password: "Your password",
		Scopes:   []string{"offline_access"}, // optional, depends on the configuration of your identity provider (not required with WCD)
	},
	Headers: nil,
}
client, err := weaviate.NewClient(cfg)
if err != nil{
	fmt.Println(err)
}

客户端凭据流程​

此 OIDC 流程使用 client secret 来获取所需的令牌进行身份验证。

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

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

大多数提供程序不会在其响应中包含 refresh token，因此 client secret 会保存在客户端中，以便在现有令牌到期时获取新的 access token。

cfg := weaviate.Config{
	Host:   "weaviate.example.com",
	Scheme: "http",
	AuthConfig: auth.ClientCredentials{
		ClientSecret: "your_client_secret",
		Scopes:       []string{"scope1 scope2"}, // optional, depends on the configuration of your identity provider (not required with WCD)
	},
	Headers: nil,
}
client, err := weaviate.NewClient(cfg)
if err != nil{
	fmt.Println(err)
}

Refresh Token 流程​

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

如果未提供 refresh token，则无法获取新的 access token，并且客户端在到期后将无法进行身份验证。

cfg := weaviate.Config{
	Host:   "weaviate.example.com",
	Scheme: "http",
	AuthConfig: auth.BearerToken{
		AccessToken:  "some token",
		RefreshToken: "other token",
		ExpiresIn:    uint(500), // in seconds
	},
	Headers: nil,
}
client, err := weaviate.NewClient(cfg)
if err != nil{
	fmt.Println(err)
}

自定义标头​

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

cfg := weaviate.Config{
  Host:"weaviate.example.com",
  Scheme: "http",
  AuthConfig: nil,
  Headers: map[string]string{
    "header_key1": "value",
    "header_key2": "otherValue",
    },
}
client, err := weaviate.NewClient(cfg)
if err != nil{
  fmt.Println(err)
}

参考​

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

设计​

构建器模式​

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

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

迁移指南​

从 v2 到 v4​

从 GraphQL.Get() 中删除了不必要的 .Objects()​

之前

client.GraphQL().Get().Objects().WithClassName...

之后

client.GraphQL().Get().WithClassName

GraphQL Get().WithNearVector() 使用构建器模式​

在 v2 中，将 nearVector 参数传递给 client.GraphQL().Get() 需要传递一个字符串。 因此，用户必须了解 GraphQL API 的结构。 v4 通过使用构建器模式来修复此问题，如下所示

之前

client.GraphQL().Get().
  WithNearVector("{vector: [0.1, -0.2, 0.3]}")...

之后

nearVector := client.GraphQL().NearVectorArgBuilder().
  WithVector([]float32{0.1, -0.2, 0.3})

client.GraphQL().Get().
  WithNearVector(nearVector)...

所有 where 过滤器使用相同的构建器​

在 v2 中，过滤器有时以字符串形式指定，有时以结构化方式指定。 v4 统一了这一点，并确保您始终可以使用相同的构建器模式。

GraphQL Get​

之前

// using filter encoded as string
where := `where :{
  operator: Equal
  path: ["id"]
  valueText: "5b6a08ba-1d46-43aa-89cc-8b070790c6f2"
}`

client.GraphQL().Get().
  Objects().
  WithWhere(where)...
// using deprecated graphql arg builder
where := client.GraphQL().WhereArgBuilder().
  WithOperator(graphql.Equal).
  WithPath([]string{"id"}).
  WithValueString("5b6a08ba-1d46-43aa-89cc-8b070790c6f2")

client.GraphQL().Get().
  Objects().
  WithWhere(where)...

之后

where := filters.Where().
  WithPath([]string{"id"}).
  WithOperator(filters.Equal).
  WithValueString("5b6a08ba-1d46-43aa-89cc-8b070790c6f2")

client.GraphQL().Get().
  WithWhere(where)...
GraphQL Aggregate​

之前

where := client.GraphQL().WhereArgBuilder().
  WithPath([]string{"id"}).
  WithOperator(graphql.Equal).
  WithValueString("5b6a08ba-1d46-43aa-89cc-8b070790c6f2")

client.GraphQL().Aggregate().
  Objects().
  WithWhere(where)...

之后

where := filters.Where().
  WithPath([]string{"id"}).
  WithOperator(filters.Equal).
  WithValueString("5b6a08ba-1d46-43aa-89cc-8b070790c6f2")

client.GraphQL().Aggregate().
  WithWhere(where)...
分类​

之前

valueInt := 100
valueText  := "Government"

sourceWhere := &models.WhereFilter{
  ValueInt: &valueInt,
  Operator: string(graphql.GreaterThan),
  Path:     []string{"wordCount"},
}

targetWhere := &models.WhereFilter{
  ValueString: &valueText,
  Operator:    string(graphql.NotEqual),
  Path:        []string{"name"},
}

client.Classifications().Scheduler().
  WithSourceWhereFilter(sourceWhere).
  WithTargetWhereFilter(targetWhere)...

之后

sourceWhere := filters.Where().
  WithOperator(filters.GreaterThan).
  WithPath([]string{"wordCount"}).
  WithValueInt(100)

targetWhere := filters.Where().
  WithOperator(filters.NotEqual).
  WithPath([]string{"name"}).
  WithValueString("Government")

client.Classifications().Scheduler().
  WithSourceWhereFilter(sourceWhere).
  WithTargetWhereFilter(targetWhere)...

GraphQL Get().WithFields()​

在 v2 中，.WithFields() 接受一个需要了解 GraphQL 字段结构的 GraphQL 字符串。 现在，这可以使用一个可变函数来完成。 例如

之前

client.GraphQL.Get().WithClassName("MyClass").WithFields("name price age")...

之后

client.GraphQL.Get().WithClassName("MyClass").
  WithFields(graphql.Field{Name: "name"},graphql.Field{Name: "price"}, graphql.Field{Name: "age"})...

Graphql Get().WithGroup()​

在 v2 中，.WithFields() 接受一个需要了解 GraphQL 字段结构的 GraphQL 字符串。 现在，这可以使用构建器来完成。 例如

之前

client.GraphQL.Get().WithClassName("MyClass")
  .WithGroup("{type:merge force:1.0}")

之后

group := client.GraphQL().GroupArgBuilder()
  .WithType(graphql.Merge).WithForce(1.0)

client.GraphQL.Get().WithClassName("MyClass").WithGroup(group)

Graphql Data().Validator() 属性已重命名​

在 v2 中，指定 Schema 的方法的命名与其他客户端位置不一致。 这已在 v4 中修复。 按照以下方式重命名

之前

client.Data().Validator().WithSchema(properties)

之后

client.Data().Validator().WithProperties(properties)

发布版本​

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

点击此处查看 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 提供反馈。

此页面是否有帮助？