milvus/shards/README_CN.md

Mishards - Milvus 集群分片中间件

Milvus 旨在帮助用户实现海量非结构化数据的近似检索和分析。单个 Milvus 实例可处理十亿级数据规模，而对于百亿或者千亿级数据，则需要一个 Milvus 集群实例。该实例对于上层应用可以像单机实例一样使用，同时满足海量数据低延迟、高并发业务需求。

本文主要展示如何使用 Mishards 分片中间件来搭建 Milvus 集群。

Mishards 是什么

Mishards 是一个用 Python 开发的 Milvus 集群分片中间件，其内部处理请求转发、读写分离、水平扩展、动态扩容，为用户提供内存和算力可以无限扩容的 Milvus 实例。

Mishards 的设计尚未完成，属于试用功能，希望大家多多测试、提供反馈。

Mishards 如何工作

Mishards 负责将上游请求拆分，并路由到内部各细分子服务，最后将子服务结果汇总，返回给上游。

Mishards 相关示例

以下分别向您展示如何使用源代码在单机上启动 Mishards 和 Milvus 服务，以及如何使用 Kubernetes 启动 Milvus 集群和 Mishards。

Milvus 启动的前提条件请参考 Milvus 安装。

源代码启动示例

前提条件

Python 版本为3.6及以上。

源代码启动 Milvus 和 Mishards 实例

请按照以下步骤在单机上启动单个 Milvus 实例和 Mishards 服务：

1. 将 milvus repository 复制到本地。

   git clone <ssh url>
   

2. 安装 Mishards 的依赖库。

   $ cd milvus/shards
   $ pip install -r requirements.txt
   

3. 启动 Milvus 服务。

   $ sudo nvidia-docker run --rm -d -p 19530:19530 -v /tmp/milvus/db:/opt/milvus/db milvusdb/milvus:0.8.0-gpu-d041520-464400
   

4. 更改目录权限。

   $ sudo chown -R $USER:$USER /tmp/milvus
   

5. 配置 Mishards 环境变量

   $ cp mishards/.env.example mishards/.env
   

6. 启动 Mishards 服务

   $ python mishards/main.py
   

Docker 示例

all_in_one 使用 Docker 容器启动2个 Milvus 实例，1个 Mishards 中间件实例，和1个 Jaeger 链路追踪实例。

1. 安装 Docker Compose。

2. 制作实例镜像。

   $ make build
   

3. 启动所有服务。

   $ make deploy
   

4. 检查确认服务状态。

   $ make probe_deploy
        Pass ==> Pass: Connected
        Fail ==> Error: Fail connecting to server on 127.0.0.1:19530. Timeout
   

若要查看服务踪迹，使用浏览器打开 Jaeger 页面。

若要清理所有服务，请使用如下命令：

$ make clean_deploy

Kubernetes 示例

使用 Kubernetes 部署 Milvus 分布式集群要求开发人员对 Kubernetes 的基本概念和操作有基本了解。

本示例主要展示如何使用 Kubernetes 搭建 Milvus 集群，包含2个 Milvus 实例（1个可读实例，1个可写实例）、1个 MySQL 实例和1个 Mishards 实例。

本示例不包括如何搭建 Kubernetes 集群，如何安装共享存储和如何安装 kubectl 命令行工具等。

以下是 Kubernetes 示例架构图：

前提条件

使用 Kubernetes 启动多个 Milvus 实例之前，请确保您已满足以下条件：

• 已创建 Kubernetes 集群
• 已安装 nvidia-docker 2.0
• 已安装共享存储
• 已安装 kubectl，且能访问集群

Kubernetes 启动集群

1. 启动 Milvus 集群。

   $ make cluster
   

2. 确认 Mishards 是否可用。

   $ make probe_cluster
     Pass ==> Pass: Connected
   

查看集群状态：

$ make cluster_status

删除 Milvus 集群：

$ make clean_cluster

扩容 Milvus 可读实例到2个：

$ cd kubernetes_demo
$ ./start.sh scale-ro-server 2 

扩容 Mishards（代理）实例到2个：

$ cd kubernetes_demo
$ ./start.sh scale-proxy 2 

查看计算节点 milvus-ro-servers-0 日志：

$ kubectl logs -f --tail=1000 -n milvus milvus-ro-servers-0 

单元测试

单元测试

$ cd milvus/shards
$ make test

代码覆盖率测试

$ cd milvus/shards
$ make coverage

代码格式检查

$ cd milvus/shards
$ make style

Mishards 配置

全局配置

参数	是否必填	类型	默认值	说明
Debug	No	boolean	True	选择是否启用 Debug 工作模式。
TIMEZONE	No	string	UTC	时区
MAX_RETRY	No	integer	3	Mishards 连接 Milvus 的最大重试次数。
SERVER_PORT	No	integer	19530	定义 Mishards 的服务端口。
WOSERVER	Yes	string		定义 Milvus 可写实例的地址，目前只支持静态设置。参考格式： tcp://127.0.0.1:19530。

元数据

参数	是否必填	类型	默认值	说明
SQLALCHEMY_DATABASE_URI	Yes	string		定义元数据存储的数据库地址，格式标准为 RFC-738-style。例如：mysql+pymysql://root:root@127.0.0.1:3306/milvus?charset=utf8mb4。
SQL_ECHO	No	boolean	False	选择是否打印 SQL 详细语句。
SQLALCHEMY_DATABASE_TEST_URI	No	string		定义测试环境下元数据存储的数据库地址。
SQL_TEST_ECHO	No	boolean	False	选择测试环境下是否打印 SQL 详细语句。

服务发现

参数	是否必填	类型	默认值	说明
DISCOVERY_PLUGIN_PATH	No	string		用户自定义服务发现插件的搜索路径，默认使用系统搜索路径。
DISCOVERY_CLASS_NAME	No	string	static	在插件搜索路径下，根据类名搜索类，并将其实例化。目前系统提供 static 和 kubernetes 两种类，默认使用 static。
DISCOVERY_STATIC_HOSTS	No	list	[]	DISCOVERY_CLASS_NAME为 static 时，定义服务地址列表，地址之间以逗号隔开，例如 192.168.1.188,192.168.1.190。
DISCOVERY_STATIC_PORT	No	integer	19530	DISCOVERY_CLASS_NAME 为 static 时，定义服务地址监听端口。
DISCOVERY_KUBERNETES_NAMESPACE	No	string		DISCOVERY_CLASS_NAME 为 kubernetes时，定义 Milvus 集群的namespace。
DISCOVERY_KUBERNETES_IN_CLUSTER	No	boolean	False	DISCOVERY_CLASS_NAME 为 kubernetes 时，选择服务发现是否在集群中运行。
DISCOVERY_KUBERNETES_POLL_INTERVAL	No	integer	5	DISCOVERY_CLASS_NAME 为 kubernetes 时，定义服务发现监听周期，单位：second。
DISCOVERY_KUBERNETES_POD_PATT	No	string		DISCOVERY_CLASS_NAME 为 kubernetes 时，匹配 Milvus Pod 名字的正则表达式。
DISCOVERY_KUBERNETES_LABEL_SELECTOR	No	string		SD_PROVIDER为kubernetes时，匹配 Milvus Pod 的标签。例如：tier=ro-servers。

链路追踪

参数	是否必填	类型	默认值	说明
TRACER_PLUGIN_PATH	No	string		用户自定义链路追踪插件的搜索路径，默认使用系统搜索路径。
TRACER_CLASS_NAME	No	string		在插件搜索路径下，根据类名搜索类，并将其实例化。目前只支持 Jaeger, 默认不使用。
TRACING_SERVICE_NAME	No	string	mishards	TRACING_CLASS_NAME 为 Jaeger时，链路追踪的 service。
TRACING_SAMPLER_TYPE	No	string	const	TRACING_CLASS_NAME为 Jaeger 时，链路追踪的采样类型。
TRACING_SAMPLER_PARAM	No	integer	1	TRACING_CLASS_NAME 为 Jaeger时，链路追踪的采样频率。
TRACING_LOG_PAYLOAD	No	boolean	False	TRACING_CLASS_NAME为 Jaeger时，链路追踪是否采集 Payload。

日志

参数	是否必填	类型	默认值	说明
LOG_LEVEL	No	string	DEBUG	日志记录级别，目前支持 DEBUG 、INFO 、WARNING 和ERROR。
LOG_PATH	No	string	/tmp/mishards	日志记录路径。
LOG_NAME	No	string	logfile	日志记录名。

路由

参数	是否必填	类型	默认值	说明
ROUTER_PLUGIN_PATH	No	string		用户自定义路由插件的搜索路径，默认使用系统搜索路径。
ROUTER_CLASS_NAME	No	string	FileBasedHashRingRouter	在插件搜索路径下，根据类名搜索路由的类，并将其实例化。目前系统只提供了 FileBasedHashRingRouter。
ROUTER_CLASS_TEST_NAME	No	string	FileBasedHashRingRouter	在插件搜索路径下，根据类名搜索路由的类，并将其实例化。目前系统只提供了 FileBasedHashRingRouter，仅限测试环境下使用。