Python

Python 客户端 (SDK)

最新的 Python 客户端版本是 v4.19.2。

weaviate/weaviate-python-client 参考手册 (文档字符串)

此页面广泛介绍了 Weaviate Python 客户端 (v4 版本)。有关不特定于 Python 客户端的使用信息，例如代码示例，请参阅操作手册和指南中的相关页面。

安装

Python 客户端库使用 Python 3.8+ 开发和测试。它在 PyPI.org 上可用，可以使用以下命令安装

pip install -U weaviate-client

要安装 Beta 版本

pip install --pre -U "weaviate-client==4.*"`

要求：Weaviate 版本兼容性 & gRPC

Weaviate 版本兼容性

v4 Python 客户端需要 Weaviate 1.23.7 或更高版本。通常，我们建议您使用最新版本的 Python 客户端和 Weaviate 数据库。

在 Weaviate Cloud 中，沙盒与 2024 年 1 月 31 日起兼容 v4 客户端。在此日期之前创建的沙盒将不兼容 v4 客户端。

gRPC

v4 客户端在底层使用远程过程调用 (RPC)。因此，必须向您的 Weaviate 服务器开放 gRPC 端口。

docker-compose.yml 示例

如果您使用 Docker 运行 Weaviate，可以通过将以下内容添加到您的 docker-compose.yml 文件中来映射默认端口 (50051)

ports:
  - 8080:8080
  - 50051:50051

Weaviate Agents

您可以使用以下命令安装带有可选 agents extras 的 Weaviate 客户端库，以使用 Weaviate Agents。

pip install -U weaviate-client[agents]

入门

先决条件

如果您尚未这样做，我们建议您首先完成 快速入门教程，以便充分利用本节。

使用此 Python 示例开始使用 Weaviate。代码将引导您完成以下关键步骤

连接到 Weaviate：建立到本地（或 Cloud）Weaviate 实例的连接。
创建集合：定义 Question 集合的数据模式，使用 Ollama 模型对数据进行向量化。
导入数据：获取示例 Jeopardy 问题，并使用 Weaviate 的批量导入进行高效摄取和自动向量嵌入生成。
搜索/查询数据库：执行向量搜索，以查找与查询 biology 语义相似的问题。

.Vectors.text2vec_xxx 与 AutoSchema

使用 Python 客户端库 4.16.0-4.16.3 使用 Configure.Vectors.text2vec_xxx() 定义集合，如果在未定义任何属性且未将 vectorize_collection_name 设置为 True 的情况下，将引发错误。

这在 Weaviate Python 客户端的 4.16.4 中得到解决。有关更多详细信息，请参阅此常见问题解答条目：Python 客户端版本 4.16.0 到 4.16.3 中出现无效属性错误。

import weaviate
import requests, json
from weaviate.classes.config import Configure

client = weaviate.connect_to_local()

questions = client.collections.create(
    name="Question",
    vector_config=Configure.Vectors.text2vec_ollama(
        api_endpoint="http://ollama:11434",  # If using Docker you might need: http://host.docker.internal:11434
        model="nomic-embed-text",  # The model to use
    ),  # Configure the Ollama embedding model
)

resp = requests.get(
    "https://raw.githubusercontent.com/weaviate-tutorials/quickstart/main/data/jeopardy_tiny.json"
)
data = json.loads(resp.text)

with questions.batch.dynamic() as batch:
    for d in data:
        batch.add_object(
            {
                "answer": d["Answer"],
                "question": d["Question"],
                "category": d["Category"],
            }
        )
        if batch.number_errors > 10:
            print("Batch import stopped due to excessive errors.")
            break

failed_objects = questions.batch.failed_objects
if failed_objects:
    print(f"Number of failed imports: {len(failed_objects)}")
    print(f"First failed object: {failed_objects[0]}")

response = questions.query.near_text(query="biology", limit=2)

for obj in response.objects:
    print(json.dumps(obj.properties, indent=2))

client.close()  # Free up resources

有关更多代码示例，请查看操作手册和指南部分。

异步使用

Python 客户端库默认提供同步 API，通过 WeaviateClient 类实现，该类在本页介绍。从 weaviate-client v4.7.0 及更高版本开始，也提供了一个异步 API，通过 WeaviateAsyncClient 类实现。有关更多详细信息，请参阅异步客户端 API 页面。

发布版本

转到 GitHub 发布页面，以查看 Python 客户端库的发布历史记录和更改日志。

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

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

Weaviate 数据库 (GitHub)	首次发布日期	Python (GitHub)	TypeScript/ JavaScript (GitHub)	Go (GitHub)	Java (GitHub)
1.35.x	2025-12-17	4.19.x	N/A	N/A	N/A
1.34.x	2025-11-05	4.18.x	3.10.x	5.6.x	6.0.0
1.33.x	2025-09-25	4.17.x	3.9.x	5.5.x	5.5.x
1.32.x	2025-07-14	4.16.x	3.8.x	5.3.x	5.4.x
1.31.x	2025-05-30	4.15.x	3.6.x	5.2.x	5.3.x
1.30.x	2025-04-03	4.12.x	3.5.x	5.1.x	5.2.x
1.29.x	2025-02-17	4.11.x	3.4.x	5.0.x	5.1.x

旧版本发布

Weaviate 数据库 (GitHub)	首次发布日期	Python (GitHub)	TypeScript/ JavaScript (GitHub)	Go (GitHub)	Java (GitHub)
1.28.x	2024-12-11	4.10.x	3.3.x	4.16.x	5.0.x
1.27.x	2024-10-16	4.9.x	3.2.x	4.16.x	5.0.x 4.9.x
1.26.x	2024-07-22	4.7.x	3.1.x	4.15.x	4.8.x
1.25.x	2024-05-10	4.6.x	2.1.x	4.13.x	4.6.x
1.24.x	2024-02-27	4.5.x	2.0.x	4.10.x	4.4.x
1.23.x	2023-12-18	3.26.x	1.5.x	4.10.x	4.4.x
1.22.x	2023-10-27	3.25.x	1.5.x	4.10.x	4.3.x
1.21.x	2023-08-17	3.22.x	1.4.x	4.9.x	4.2.x
1.20.x	2023-07-06	3.22.x	1.1.x	4.7.x	4.2.x
1.19.x	2023-05-04	3.17.x	1.1.x¹	4.7.x	4.0.x
1.18.x	2023-03-07	3.13.x	2.14.x	4.6.x	3.6.x
1.17.x	2022-12-20	3.9.x	2.14.x	4.5.x	3.5.x
1.16.x	2022-10-31	3.8.x	2.13.x	4.4.x	3.4.x
1.15.x	2022-09-07	3.6.x	2.12.x	4.3.x	3.3.x
1.14.x	2022-07-07	3.6.x	2.11.x	4.2.x	3.2.x
1.13.x	2022-05-03	3.4.x	2.9.x	4.0.x	2.4.x
1.12.x	2022-04-05	3.4.x	2.8.x	3.0.x	2.3.x
1.11.x	2022-03-14	3.2.x	2.7.x	2.6.x	2.3.x
1.10.x	2022-01-27	3.1.x	2.5.x	2.4.x	2.1.x
1.9.x	2021-12-10	3.1.x	2.4.x	2.4.x	2.1.x
1.8.x	2021-11-30	3.1.x	2.4.x	2.3.x	1.1.x
1.7.x	2021-09-01	3.1.x	2.4.x	2.3.x	1.1.x
1.6.x	2021-08-11	2.4.x	2.3.x	2.2.x	1.0.x
1.5.x	2021-07-13	2.2.x	2.1.x	2.1.x	1.0.x
1.4.x	2021-06-09	2.2.x	2.1.x	2.1.x	1.0.x
1.3.x	2021-04-23	2.2.x	2.1.x	2.1.x	1.0.x
1.2.x	2021-03-15	2.2.x	2.0.x	1.1.x	-
1.1.x	2021-02-10	2.1.x	-	-	-
1.0.x	2021-01-14	2.0.x	-	-	-

TypeScript 客户端变更

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

矢量化器 API 变更 `v4.16.0`

.Vectors.text2vec_xxx 与 AutoSchema

这在 Weaviate Python 客户端的 4.16.4 中得到解决。有关更多详细信息，请参阅此常见问题解答条目：Python 客户端版本 4.16.0 到 4.16.3 中出现无效属性错误。

从 Weaviate Python 客户端 v4.16.0 开始，在创建集合时对矢量化器配置 API 进行了多项更改

.vectorizer_config 已替换为 .vector_config
Configure.NamedVectors 已替换为 Configure.Vectors 和 Configure.MultiVectors
Configure.NamedVectors.none 和 Configure.Vectorizer.none 已替换为 Configure.Vectors.self_provided 和 Configure.MultiVectors.self_provided

Python 客户端 `v3` 弃用

Weaviate Python 客户端 v3 已弃用，不应再使用。如果您需要 v3 客户端的文档，请参阅文档存档。如果您正在从 Python v3 客户端迁移到 v4 客户端，请参阅此迁移指南。

Beta 版本

迁移指南 - Beta 版本

`v4.4b9` 中的变更

`weaviate.connect_to_x` 方法

timeout 参数现在是 additional_config 参数的一部分。它接受类 weaviate.config.AdditionalConfig 作为输入。

查询

query 命名空间中方法的所有可选参数现在都强制为关键字参数。

现在有运行时逻辑来解析查询参数，强制正确的类型。

批量处理

引入了使用不同的批量处理风格在底层实现的三种不同的算法

client.batch.dynamic()
client.batch.fixed_size()
client.batch.rate_limit()

client.batch.dynamic() as batch 是对以前的 client.batch as batch 的直接替换，后者现已弃用，将在发布时删除。

with client.batch.dynamic() as batch:
  ...

等效于

with client.batch as batch:
  ...

client.batch.fixed_size() as batch 是一种配置批量处理算法以仅使用固定大小的方法。

with client.batch.dynamic() as batch:
  ...

等效于

client.batch.configure_fixed_size()
with client.batch as batch:
  ...

client.batch.rate_limit() as batch 是一种帮助避免命中第三方矢量化 API 速率限制的新方法。通过在 rate_limit() 方法中指定 request_per_minute，您可以强制批量处理算法以第三方 API 能够处理对象的速度向 Weaviate 发送对象。

这些方法现在返回完全本地化的上下文管理器。这意味着一个批次中的 failed_objects 和 failed_references 不会包含在任何后续调用中。

最后，如果负责发送批次的后台线程引发异常，则现在会在主线程中重新引发该异常，而不是静默地出错。

过滤器

Filter.by_property 中 prop 参数已重命名为 name

现在可以使用 Filter.by_ref_count(ref) 而不是 Filter([ref]) 实现引用计数。

`v4.4b8` 中的变更

引用过滤器

引用过滤器具有简化的语法。新的语法如下所示

Filter.by_ref("ref").by_property("target_property")

`v4.4b7` 中的变更

库导入

直接从 weaviate 导入已弃用。请使用 import weaviate.classes as wvc 代替。

关闭客户端连接

从 v4.4b7 开始，您必须显式关闭客户端连接。有两种方法可以关闭客户端连接。

使用 client.close() 显式关闭客户端连接。

import weaviate
client = weaviate.connect_to_local()

print(client.is_ready())

client.close()

使用上下文管理器为您关闭客户端连接。

import weaviate

with weaviate.connect_to_local() as client:
     print(client.is_ready())

# Python closes the client when you leave the 'with' block

批量处理

v4.4b7 客户端对 client.batch 进行了更改。

client.batch 需要一个上下文管理器。
删除了手动模式，您无法使用 .create_objects 发送批次。
批量大小和并发请求的数量是动态分配的。使用 batch.configure_fixed_size 指定值。
add_reference 方法已更新。
删除了 to_object_collection 方法。

更新的 client.batch 参数

旧值	v4.4b7 中的值
from_object_uuid: UUID	from_uuid: UUID
from_object_collection: str	from_collection: str
from_property_name: str	from_property: str
to_object_uuid: UUID	to: Union[WeaviateReference, List[UUID]]
to_object_collection: Optional[str] = None
tenant: Optional[str] = None	tenant: Optional[str] = None

过滤器语法

v4.4b7 中更新了过滤器语法。

注意：引用过滤器语法在 4.4b8 中进行了简化。

旧语法	v4.4b7 中的新语法
Filter(path=property)	Filter.by_property(property)
Filter(path=["ref", "target_class", "target_property"])	Filter.by_ref().link_on("ref").by_property("target_property")
FilterMetadata.ByXX	Filter.by_id() Filter.by_creation_time() Filter.by_update_time()

4.4b7 之前的过滤器语法已弃用。新的 v4.4b7 语法如下所示。

import weaviate
import datetime
import weaviate.classes as wvc

client = weaviate.connect_to_local()

jeopardy = client.collections.use("JeopardyQuestion")
response = jeopardy.query.fetch_objects(
    filters=wvc.query.Filter.by_property("round").equal("Double Jeopardy!") &
            wvc.query.Filter.by_creation_time().greater_or_equal(datetime.datetime(2005, 1, 1)) |
            wvc.query.Filter.by_creation_time().greater_or_equal(datetime.datetime(2000, 12, 31)),
            limit=3
    )


client.close()

`reference_add_many` 已更新

reference_add_many 语法已更新；DataReferenceOneToMany 现在是 DataReference。

collection.data.reference_add_many(
    [
        DataReference(
            from_property="ref",
            from_uuid=uuid_from,
            to_uuid=*one or a list of UUIDs*,
        )
    ]
)

参考

多目标引用已更新。这些是新的函数

ReferenceProperty.MultiTarget
DataReference.MultiTarget
QueryReference.MultiTarget

对于多目标引用，请使用 ReferenceToMulti。

旧版客户端变更

参考文献

现在可以通过在集合创建、对象插入和查询期间的 references 参数添加引用。
FromReference 类现在称为 QueryReference。

类/参数重组

weaviate.classes 子模块进一步拆分为
- weaviate.classes.config
- weaviate.classes.data
- weaviate.classes.query
- weaviate.classes.generic

vector_index_config 参数工厂函数，用于 wvc.config.Configure 和 wvc.config.Reconfigure，已更改为例如：

client.collections.create(
    name="MyCollection",
    vector_index_config=wvc.config.Configure.VectorIndex.hnsw(
        distance_metric=wvc.config.VectorDistances.COSINE,
        vector_cache_max_objects=1000000,
        quantizer=wvc.config.Configure.VectorIndex.Quantizer.pq()
    ),
)

vector_index_type 参数已被移除。

在 Property 构造方法中，vectorize_class_name 参数已更改为 vectorize_collection_name。
[collection].data.update() / .replace() *args 顺序已更改，旨在适应在更新时无需提供属性的情况。
[collection].data.reference_add / .reference_delete / .reference_replace 中的 ref 关键字已重命名为 to。
collections.create() / get()：提供泛型的 data_model kwarg 已重命名为 data_model_properties。
[object].metadata.uuid 现在是 [object].uuid。
[object].metadata.creation_time_unix 现在是 [object].metadata.creation_time。
[object].metadata.last_update_time_unix 现在是 [object].metadata.last_update。
quantitizer 已重命名为 quantizer
要请求返回数据中的向量，请使用 include_vector 参数。

数据类型

时间元数据（用于创建时间和最后更新时间）现在返回一个 datetime 对象，并且参数已重命名为 creation_time 和 last_update_time，位于 MetadataQuery 下。
- metadata.creation_time.timestamp() * 1000 将返回与之前相同的值。
query.fetch_object_by_id() 现在在底层使用 gRPC（而不是 REST），并以与其他查询相同的格式返回对象。
UUID 和 DATE 属性作为类型化对象返回。

代码示例和更多资源

可以在 Weaviate 文档中找到有关各种操作和功能的用法信息。

如何配置 Weaviate

配置压缩、备份、身份验证、授权、数据复制等。

如何管理集合

管理集合（CRUD），配置向量化器和索引参数，设置多租户，并执行迁移。

如何管理对象

添加新对象、获取现有对象、修改它们以及从集合中删除它们。

如何查询和搜索

从基本的向量和混合搜索到专门的图像查询以及执行数据聚合。

Weaviate API 参考页面中的搜索和 REST 也可能是很好的起点。

课程您的第一个 AI 应用（搜索和 RAG）

一个实践课程，您将使用 Weaviate 和 FastAPI 构建一个电影推荐 API。

打开学院课程

问题和反馈

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

技术问题

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

文档反馈

通过打开 GitHub issue 提供反馈。

更多资源

需要帮助？

安装​

Weaviate 版本兼容性​

gRPC​

Weaviate Agents​

入门​

异步使用​

发布版本​

TypeScript 客户端变更​

矢量化器 API 变更 v4.16.0​

Python 客户端 v3 弃用​

Beta 版本​

v4.4b9 中的变更​

weaviate.connect_to_x 方法​

查询​

批量处理​

过滤器​

v4.4b8 中的变更​

引用过滤器​

v4.4b7 中的变更​

库导入​

关闭客户端连接​

批量处理​

过滤器语法​

reference_add_many 已更新​

参考​

旧版客户端变更​

参考文献​

类/参数重组​

数据类型​

代码示例和更多资源​

课程您的第一个 AI 应用（搜索和 RAG）

问题和反馈​

安装

Weaviate 版本兼容性

gRPC

Weaviate Agents

入门

异步使用

发布版本

TypeScript 客户端变更

矢量化器 API 变更 `v4.16.0`

Python 客户端 `v3` 弃用

Beta 版本

`v4.4b9` 中的变更

`weaviate.connect_to_x` 方法

查询

批量处理

过滤器

`v4.4b8` 中的变更

引用过滤器

`v4.4b7` 中的变更

库导入

关闭客户端连接

批量处理

过滤器语法

`reference_add_many` 已更新

参考

旧版客户端变更

参考文献

类/参数重组

数据类型

代码示例和更多资源

问题和反馈