推荐语

Milvus SDK v2全新升级，带来更高效、易用的AI开发体验！

核心内容：
1. Milvus SDK v2解决v1版本异步接口缺失、性能瓶颈等问题
2. 统一接口设计，提升易用性和跨语言协作效率
3. Python SDK v2详细解读，支持MCP等新特性

杨芳贤

53A创始人/腾讯云(TVP)最具价值专家

前言

“Milvus很好，但接口和功能有点复杂！

使用Milvus过程中，为什么总要在SDK 文档和 Stack Overflow 之间来回跳转？

好不容易调通了接口，结果又遇到性能瓶颈和异步调用麻烦！

难道没有一个更简单、更统一、更高效的 SDK 吗？”

大家在社区中给到的这些鞭策与建议，我们已经全部收到

今天，我们官宣，Milvus SDK v2正式上线！

聚焦开发者体验，Milvus SDK v2 以统一的接口设计、灵活的异步模式和显著提升的易用性，彻底解决了以往接口复杂、文档不全以及部分功能缺失的问题。

一句话总结：Milvus SDK v2用更简单易用的用户接口，为AI落地提供了更高保障！

以下为具体功能解读：

01

痛点剖析：为何需要变革？

Milvus 作为一款深受开发者喜爱的向量数据库，被广泛应用在 AI 应用开发中，然而 Milvus 的 v1 SDK 也存在诸多不便之处，以下列举一些痛点：

痛点一：异步接口缺失，难以应对高并发挑战

在 v1 时代，部分 SDK（如 pymilvus）缺乏原生异步支持，开发者不得不依靠线程或回调来实现并发操作。在面对批量数据加载、并行查询等高并发场景时，这种方式不仅使代码臃肿，调试难度也大大增加，严重影响了系统的吞吐能力和响应速度。

痛点二：性能瓶颈：缺乏 Schema Cache 导致插入与查询低效

除了异步问题，v1 SDK 在性能上也存在一些短板。由于没有引入 Schema Cache 等优化机制，数据插入和查询时频繁的 schema 校验和解析操作，使得整体性能得不到有效提升。在海量数据场景下，这些问题尤为突出，直接制约了应用的实时性和扩展性。

痛点三：易用性不足：操作繁琐、接口逻辑不一致

以 pymilvus 为例，v1 版本采用了混合的 ORM 和过程式编程模式，既有面向常用对象的类（如 Collection），又有面向过程的函数用于复杂逻辑的处理，这种混合模式让新手困惑，也与其他语言用法不一致。此外，不同语言间的 SDK 命名和调用方式各异，给开发者带来了额外的学习负担，也使得跨语言团队协作和代码维护变得更加复杂。

痛点四：接口功能不统一，完成度不同

另外，由于 http 接口起步较晚，早期的 RESTful API 功能十分有限，许多操作（例如分区管理、索引构建等）只能通过其它 SDK 实现，导致接口功能受限、体验不佳。除 python 外，其他语言的 SDK 也存在类似的功能缺失问题，无法满足一些特定语言用户的功能需求。

02

解决之道：Milvus SDK v2

针对以上痛点，我们对 Milvus SDK 进行了全面改进，涉及多个编程语言，最终呈现的版本包括 ：

• Python SDK v2（pymilvus.MilvusClient）（https://milvus.io/api-reference/pymilvus/v2.5.x/About.md）

• Java v2（https://github.com/milvus-io/milvus-sdk-java）

• Go v2（https://github.com/milvus-io/milvus/tree/client/v2.5.1/client）

• NodeJS（https://github.com/milvus-io/milvus-sdk-node）

• Restful v2（https://milvus.io/api-reference/restful/v2.5.x/About.md）

新版 SDK 带来了以下各项好处：

（1）原生异步接口：全面拥抱高并发时代

为满足高并发场景的需求，Milvus SDK v2 引入了原生的异步调用支持（https://milvus.io/docs/use-async-milvus-client-with-asyncio.md）。

以 Python SDK 为例，v2.5.3 开始提供了 AsyncMilvusClient，基于 asyncio 实现真正的 async/await 异步调用。它的接口与同步的 MilvusClient 拥有相同的参数和行为，区别仅在于调用方式不同。

通过 AsyncMilvusClient，开发者可以方便地并行执行多个 Milvus 操作（插入、查询、搜索等），充分利用异步IO实现高吞吐。

相比 v1 时代依赖 Future 或回调的方案，新版的原生异步模式更简洁高效。一些之前复杂的并发逻辑，如批量向量插入、并行多查询等，现在只需使用 asyncio.gather 等即可轻松实现。

原生 async/await 的加入，使 Python 能充分发挥并发能力，这对批量数据加载、并行查询等场景的性能提升非常显著，此外也便于集成到 Python 后端的异步框架（如 aiohttp、FastAPI 等）。

（2）性能提升：Schema Cache 助力高效数据处理

新版 Milvus SDK 通过引入 Schema Cache 机制，在性能优化方面实现了显著突破。

该机制在首次获取 collection schema 后，会将其缓存在本地内存中，从而在后续的数据插入和查询操作中直接利用缓存信息，避免了重复请求和解析带来的额外网络延迟和 CPU 资源浪费。

尤其是在批量数据写入和高频查询等实时性要求较高的场景中，这一优化显著提升了系统的响应速度和吞吐量，同时也大幅减轻了服务器的负载压力。

通过减少重复解析 schema 的开销，新版 SDK 不仅提高了数据处理效率，更为开发者构建高性能应用提供了坚实的技术保障。

（3）接口功能更统一更完整

Milvus SDK v2 最显著的改进之一是实现了接口的统一化：各语言 SDK 提供了更为统一、完备的 API 方法，尤其是 RESTful API 的功能得到了大幅增强。

此前，由于 HTTP 接口的起步晚于 gRPC，功能存在一定缺失，但如今 RESTful API 已经补齐了这些差距。例如，现在开发者可通过 RESTful 接口轻松完成集合创建、分区管理、索引构建以及数据查询等几乎所有操作，而无需再切换到其他接口形式。

这种统一的接口设计使 Milvus 在不同场景下的操作体验更加一致，不仅降低了开发者的学习成本，还显著提升了产品的易用性。

如果您希望快速上手使用 Milvus，推荐采用更易用的 RESTful API；但如果对性能或高级功能（如 iterator）有更高要求，建议使用基于 gRPC 的客户端，以获得更好的性能与更丰富的功能支持。

（4）各语言 SDK 逻辑对齐，一致性更高

Milvus SDK v2 对各语言的客户端进行了重构和对齐，使它们的接口命名和调用方式保持高度一致。

现在无论是 Python、Java、Go、还是 NodeJS，各 SDK 都引入了一个 MilvusClient 主类，并提供相似的接口方法 (code example changed from PyMilvus ORM to the MilvusClient SDK · milvus-io milvus · Discussion #33979 · GitHub)。

这一改变的目的正是为了让所有 SDK 行为一致，避免以前版本中各语言用法差异带来的困扰。例如，之前可能某些操作在不同语言里函数名不同、参数格式不一，如今这些都统一规范化了。这样的对齐使跨语言开发更顺畅——熟悉一种语言的 Milvus SDK 后，再使用其他语言 SDK 时几乎不用重新学习，不再因为命名差异而困惑。

（5）PyMilvus 从 ORM 到 MilvusClient：易用性提升

Python SDK 的演进充分体现了 Milvus SDK v2 的改进。

旧版 PyMilvus 使用 ORM 模块，提供了 Collection、Index、Partition 等面向对象类以及独立的连接函数。这种 ORM 模式存在面向对象和面向过程混用的问题：开发者需要先定义 schema 对象，再实例化集合，操作起来较为繁琐，而且概念理解门槛高。

相较于过去在 ORM 模式下创建集合需要手动定义 FieldSchema 列表、构造 CollectionSchema，然后调用 Collection 类创建集合。现在可以直接使用 MilvusClient.create_collection() 一步完成集合创建。

该方法支持直接传入维度 dimension、度量类型 metric_type 等参数快速定义好 schema，或者传入自定义的 schema 对象。

更重要的是，它可以接受索引参数并自动为向量字段构建索引，创建集合的同时完成索引构建并加载数据到内存。也就是说，只需一次调用就相当于完成了 “创建集合 -> 创建索引 -> 加载集合” 三步操作（如果提供了索引参数，集合创建后会自动 load，无需显式调用）。这大大减少了启动的流程依赖，方便开箱即用。

通过以上改进，升级后的 PyMilvus milvusclient 模块相比旧 ORM 在易用性、一致性和性能方面都有显著优势。老的 ORM 接口目前虽然仍可用，但未来我们会考虑逐步废弃 (ORM | Python | ORM | Zilliz Cloud Developer Hub)，全面转向 MilvusClient。因此，强烈建议您尽快升级，享受新 SDK 带来的便利。

（6）更加清晰和完善的文档

我们全面优化并重构了产品文档，推出了更完整、更清晰的 API Reference，同时在 User Guide 中增加了多语言支持的示例代码，帮助您快速上手、深入理解 Milvus 的各项功能。此外，非常推荐大家使用文档站提供的 Ask AI 助手，它可以帮您介绍新功能、理解 Milvus 内部机理、生成并修改示例代码，使得查阅文档和探索功能变得更加轻松愉快。

（7）基于 Milvus SDK 构建的 MCP server

基于 Milvus SDK 构建的 MCP Server（GitHub 链接）采用了模型上下文协议（MCP），旨在实现 LLM 应用程序与外部数据源及工具之间的无缝集成。

随着 AI Agent 不断普及，未来不仅能通过自然语言自动生成代码，还需要能设计出面向 AI 的 API，使后端服务的调用与调度更加智能和自动化。基于 Milvus SDK 构建的 MCP Server 正是在这种背景下诞生的：它不仅实现了对 Milvus 集群的操作和管理，还为自动化运维、智能调度以及跨系统交互提供了统一而开放的接口。

这样一来，不仅开发者可以轻松管理 Milvus 集群，未来的 AI Agent 也能直接利用这些 API 自动生成代码、执行复杂任务，实现人与机器、机器与机器之间的无缝协作。

03

示例代码

下面通过简单的代码片段，演示如何使用 Python SDK v2 版本的新接口来完成集合创建和异步操作，相比 v1 的 ORM 模式，代码更加简洁统一。

（1）使用 MilvusClient 创建集合、Schema、索引并加载：

from pymilvus import MilvusClient, DataType# 1. 连接 Milvus（初始化客户端，即建立连接）client = MilvusClient(uri="http://localhost:19530")# 2. 定义集合的 schema（模式）schema = MilvusClient.create_schema(auto_id=False, description="示例集合的schema")schema.add_field("id", DataType.INT64, is_primary=True)           # 主键字段schema.add_field("embedding", DataType.FLOAT_VECTOR, dim=128)     # 向量字段# 3. 准备索引参数（可选步骤，如果需要在创建时建索引）index_params = client.prepare_index_params()index_params.add_index(    field_name="embedding",    index_type="AUTOINDEX",    metric_type="L2")# 4. 创建集合并附带索引，自动加载进内存client.create_collection(    collection_name="example_collection",    schema=schema,    index_params=index_params)print("Collection created and loaded with index!")

以上代码在一个调用中完成了集合的定义、创建和索引构建。

create_collection 提供的 index_params参数使我们不用再调用独立的 create_index 和 load_collection，集合创建后会自动建立索引并加载至内存。这也是 Milvus Client 推崇的处理逻辑：用一个接口来完成建表所需的各种操作。

除此之外，MilvusClient 也支持快速建表模式，进一步提升了易用性：仅填入必填参数即可一行代码完成建表。

client.create_collection(    collection_name="test_collection",     dimension=128)

（对比说明：旧版本 ORM 中，我们需要先调用 Collection(schema) 创建集合对象，再调用 collection.create_index() 创建索引，最后 collection.load() 加载数据集；而现在使用 MilvusClient 一步到位。）

（2）使用 AsyncMilvusClient 进行高并发异步操作：

import asynciofrom pymilvus import AsyncMilvusClientasync def insert_vectors_concurrently():    client = AsyncMilvusClient(uri="http://localhost:19530")        vectors_to_insert = [[...], [...], ...]  # 假设有10万条向量    batch_size = 1000  # 推荐批量大小    tasks = []        for i in range(0, len(vectors_to_insert), batch_size):        batch_vectors = vectors_to_insert[i:i+batch_size]        # 批量构造数据        data = [            list(range(i, i + len(batch_vectors))),  # 批量id            batch_vectors                            # 批量向量        ]        # 添加异步任务，每次插入一批数据        tasks.append(client.insert("example_collection", data=data))        # 并发批量插入    insert_results = await asyncio.gather(*tasks)        await client.close()# 执行异步任务asyncio.run(insert_vectors_concurrently())

上面的代码使用 AsyncMilvusClient 实例通过 async/await 语法并发执行插入操作。我们创建了多个插入任务并使用 asyncio.gather 同时调度它们，从而充分利用 Milvus 后端的并发处理能力。相比同步逐条插入，异步并发插入可以大幅提高吞吐量。在 Python SDK v1 中没有这样原生的 async 支持，而 Milvus SDK v2 使得 Python 的异步特性得到充分发挥。

类似地，您也可以使用异步客户端并发执行查询或搜索操作。例如，将以上代码的插入改为 client.search("example_collection", data=[query_vec], limit=5)，就可以同时发起多路搜索请求。Milvus SDK v2 的异步接口确保每个请求都以非阻塞方式执行，最大化利用客户端和服务器资源。

04

总结

Milvus SDK v2 相较 v1 带来了显著的改进：性能更高效、接口更统一、跨语言更一致、使用更简单。

通过统一各语言的 MilvusClient 接口，开发者可以在任意语言中享受一致的开发体验；借助原生异步支持，Milvus 在高并发场景下的性能得以提升；以 Python SDK 为例的新设计更是解决了旧 ORM 模式的诸多不足。同时，新版文档与直观简洁的 UI 设计，让开发者能够快速上手并高效构建应用。我们坚信，随着 Milvus 在各语言平台上不断完善与发展，将进一步推动非结构化数据处理和 AI 集成的变革。

我们强烈建议仍在使用 SDK v1 的用户尽快升级到 Milvus SDK v2，v1 版本的支持计划在 Milvus 3.0 终止。升级并不困难——Milvus 团队在 2.x 版本中提供了向后兼容支持，一段时间内旧的 v1/ORM 接口依然可用。您可以一边参考新版文档改进代码，一边逐步弃用旧接口。官方文档和社区资源提供了详尽的指南和示例，帮助您平滑迁移。在享受 Milvus SDK v2 带来便利的同时，您也将获得社区更积极的支持和后续版本的新特性。

更多详细的信息请访问我们官方最新版本的 API Reference，同时我们的用户文档（User Guides）的更新也在持续完善中。