Deep dive #2：API 与 Python SDKs 详解

作者：杨璇

编者按：

API 是什么？Python SDKs 又是什么？熟悉 Milvus 数据库的朋友们应该会立刻联想到 Milvus protocol API 和 PyMilvus。本期内容能帮助你以一个全新的视角看待 Milvus 和 Milvus 开源社区。

讲师简介：

杨璇，pymilvus-admin 和 Milvus contributor，负责维护 PyMilvus 项目以及研发 Milvus 的 DataNode 模块。开源社区的狂热粉丝，积极参与各种开源活动，是 GDG 上海核心志愿者成员。武汉大学软件工程硕士，在 Zilliz 除了担任软件开发工程师，还是一个让部门所有人弃 vscode 转 vim 的 vim 小学生。

分享大纲：

1. PyMilvus 和 Milvus protocol API 背景介绍

2. protocol API 使用方法

3. PyMilvus 代码深入

4. PyMilvus 发展目标和计划

背景介绍

让我们把 Milvus 当作一个黑盒子。下面这张图代表了 SDKs 通过 gRPC 与 Milvus 交互的过程， gRPC 使用的是 Protocol buffers 作为接口定义语言来描述服务端的接口，以及它们传递消息的信息结构。Protocol buffers 的语言文件通常以 proto 作为结尾。所以，Milvus 这个黑盒子的所有行为实际上都是在 protocol API 里面进行定义。

PyMilvus protocol API 的具体内容分别为：

1. milvus.proto

2. common.proto

3. schema.proto

如果 SDKs 想要正常工作，都需要使用这三个 proto 文件与 Milvus 进行交互。本次分享的 Milvus API 便是对这三个文件进行初步解读。

感兴趣的小伙伴可以查阅 Milvus 2.0 SDK roadmap：https://milvus.io/docs/v2.0.0/roadmap.md#SDK

同时，PyMilvus 2.0 版本引入了一套全新的接口——object relational mapping（ORM），它与之前版本的接口非常不同，今天，我们也会聊一聊 ORM 接口的特点以及 PyMilvus 接下来的发展路径。

Milvus protocol API

milvus.proto

Milvus protocol API 中最主要的是 milvus.proto，它定义了 MilvusService，而 MilvusService 继续定义了 Milvus 所有的 RPC 接口。因此，在与 Milvus 进行交互的过程中，这里需要重点注意。

下图中的 RPC 接口参数为 CreatePartitionRequest，两个主要参数为 string 类型的 collection_name 与 partition_name，基于这几点就可以创建 collection partition。

这个 protocol 到底长什么样子？进入到 PyMilvus 的仓库（https://github.com/milvus-io/pymilvus/blob/master/pymilvus/grpc_gen/proto/milvus.proto）中，可以在第 19 行找到上方提到的例子：

我们可以在该文件中找到 CreatePartitionRequest 的定义：

如果大家需要开发新功能，或者开发新 SDK，PyMilvus 仓库可以帮助你查找 Milvus 通过 RPC 对外提供的接口。

common.proto

顾名思义，common.proto 部分是一些 common 的类型。这部分的结构包括了常用的ErrorCode 和 Status 等：

Schema.proto

在传参数的时候，需要的 schema 都在这个部分进行定义。CollectionSchema 的示例如下：

上述三个 proto 组合在一起，共同构成了 Milvus 对外的 API，可以在其中找到所有 Milvus 对外的行为。

你可以阅读源码，观察 create_index() 发现，像create_index 这样的对外接口，实际上调用了 describe_collection 、describe_index 等多个 RPC 接口。总结起来，Milvus 中很多对外接口实际上是由多个 RPC 接口组合而成的功能。

所以，当你理解了这些 RPC 的行为后，就可以在 SDK 层面通过组合创造新的功能。欢迎大家在这个部分发挥自己的创造力和想象力，为 Milvus 社区添砖加瓦！

PyMilvus 2.0

Object-relational mapping（ORM）

ORM 用一句话简单表述便是：对本地对象操作会影响服务端点一个对象。PyMilvus 的 ORM 接口有以下三个特点：

1. Operate directly on objects. 直接作用于对象。

2. Isolate business logic and data access details. 隔离业务逻辑和数据访问详细信息。

3. Hide the implementation complexity, same codes everywhere. 隐藏实现的复杂，一套代码可以到处跑。

第三点对于 Milvus 而言，无论是作为 DBS，还是本地的 library，亦或者是 cloud service，无论中间实现的过程是 RPC 还是 python，只要使用 ORM 风格的代码，那么这些代码无需改变就可以适用多种 Milvus server 的状态。这就是 ORM 抽象出来的好处。

ORM style API

ORM 风格的 API 最大的特点，便是可以控制对 Milvus 的连接。例如，可以添加多个 Milvus server 别名，选择使用别名去连接或关闭其中的一台服务。也可以通过删除本地的 server address，精确控制哪一些对象使用的是哪一台机器、哪一个连接。

第二个特点是，所有的操作都是直接面向对象进行的操作，对象包括 collection、partition 和 index。当三个对象被抽象出来后，所有对他们的操作都可以直接在对象上进行。

例如，我们想要提取一个 collection 对象，无论这个 collection 是新创建的，还是 Milvus server 里面已经存在的，都可以通过 collection 这个接口去创建一个对象出来。还可以给对象绑定 connection ，将 films 这个对象用 DEV 别名指代 Milvus server，films 在本地会有一些状态，我们可以对这个对象直接进行各种操作。

如果想要构建一个 partition 对象的话，有两种方法。这里只提供了一种：我们可以通过 films 这个 collection 对象去创建一个 partition，拿到了这个 adventure 之后，partition 也会有自己的一些 states。我们可以像对 collection 一样对 partition 进行同样的操作。这里还有一个对象 Index。和 partition 类似，我们也可以通过这个 collection 对象 films 去创建一个 index，进行后续的操作。

除了创建新的 addition 和新的 index 这些方法，如果 films 这个 collection 里面已经存在了 partition 或者是 index 的话，也可以通过 films 这个 collection 对象去提取。

更多帮助

推荐大家通过 PyMilvus 文档，真正并深入了解使用方法。PyMilvus 文档由两部分组成，第一部分是在 API doc-strings 里面自动生成的，第二部分就是由 PyMilvus contributors 撰写的、基于用户使用的角度文档，非常实用。

大家可以在这里查看我们所有的文档：https://milvus.io/docs

PyMilvus 的文档源代码查看地址：pymilvus/docs at master · milvus-io/pymilvus