mirror of
https://gitee.com/milvus-io/milvus.git
synced 2024-12-01 03:18:29 +08:00
[skip ci] Update README_CN
This commit is contained in:
jielinxu
GitHub
parent
4493a6248d
commit
eedb67270d
261
shards/README_CN.md
Normal file
261
shards/README_CN.md
Normal file
@ -0,0 +1,261 @@
|
||||
# Mishards - Milvus 集群分片中间件
|
||||
|
||||
Milvus 旨在帮助用户实现海量非结构化数据的近似检索和分析。单个 Milvus 实例可处理十亿级数据规模，而对于百亿或者千亿级数据，则需要一个 Milvus 集群实例。该实例对于上层应用可以像单机实例一样使用，同时满足海量数据低延迟、高并发业务需求。
|
||||
|
||||
本文主要展示如何使用 Mishards 分片中间件来搭建 Milvus 集群。
|
||||
|
||||
## Mishards 是什么
|
||||
|
||||
Mishards 是一个用 Python 开发的 Milvus 集群分片中间件，其内部处理请求转发、读写分离、水平扩展、动态扩容，为用户提供内存和算力可以无限扩容的 Milvus 实例。
|
||||
|
||||
Mishards 的设计尚未完成，属于试用功能，希望大家多多测试、提供反馈。
|
||||
|
||||
## Mishards 如何工作
|
||||
|
||||
Mishards 负责将上游请求拆分，并路由到内部各细分子服务，最后将子服务结果汇总，返回给上游。
|
||||
|
||||
|
||||
|
||||
## Mishards 相关示例
|
||||
|
||||
以下分别向您展示如何使用源代码在单机上启动 Mishards 和 Milvus 服务，以及如何使用 Kubernetes 启动 Milvus 集群和 Mishards。
|
||||
|
||||
Milvus 启动的前提条件请参考 [Milvus 安装](https://www.milvus.io/docs/zh-CN/userguide/install_milvus/)。
|
||||
|
||||
### 源代码启动示例
|
||||
|
||||
#### 前提条件
|
||||
|
||||
Python 版本为3.6及以上。
|
||||
|
||||
#### 源代码启动 Milvus 和 Mishards 实例
|
||||
|
||||
请按照以下步骤在单机上启动单个 Milvus 实例和 Mishards 服务：
|
||||
|
||||
1. 将 milvus repository 复制到本地。
|
||||
|
||||
```shell
|
||||
git clone <ssh url>
|
||||
```
|
||||
|
||||
2. 安装 Mishards 的依赖库。
|
||||
|
||||
```shell
|
||||
$ cd milvus/shards
|
||||
$ pip install -r requirements.txt
|
||||
```
|
||||
|
||||
3. 启动 Milvus 服务。
|
||||
|
||||
```shell
|
||||
$ sudo nvidia-docker run --rm -d -p 19530:19530 -v /tmp/milvus/db:/opt/milvus/db milvusdb/milvus:0.5.0-d102119-ede20b
|
||||
```
|
||||
|
||||
4. 更改目录权限。
|
||||
|
||||
```shell
|
||||
$ sudo chown -R $USER:$USER /tmp/milvus
|
||||
```
|
||||
|
||||
5. 配置 Mishards 环境变量
|
||||
|
||||
```shell
|
||||
$ cp mishards/.env.example mishards/.env
|
||||
```
|
||||
|
||||
6. 启动 Mishards 服务
|
||||
|
||||
```shell
|
||||
$ python mishards/main.py
|
||||
```
|
||||
|
||||
### Docker 示例
|
||||
|
||||
`all_in_one` 使用 Docker 容器启动2个 Milvus 实例，1个 Mishards 中间件实例，和1个 Jaeger 链路追踪实例。
|
||||
|
||||
1. 安装 [Docker Compose](https://docs.docker.com/compose/install/)。
|
||||
|
||||
2. 制作实例镜像。
|
||||
|
||||
```shell
|
||||
$ make build
|
||||
```
|
||||
|
||||
3. 启动所有服务。
|
||||
|
||||
```shell
|
||||
$ make deploy
|
||||
```
|
||||
|
||||
4. 检查确认服务状态。
|
||||
|
||||
```shell
|
||||
$ make probe_deploy
|
||||
Pass ==> Pass: Connected
|
||||
Fail ==> Error: Fail connecting to server on 127.0.0.1:19530. Timeout
|
||||
```
|
||||
|
||||
若要查看服务踪迹，使用浏览器打开 [Jaeger 页面](http://127.0.0.1:16686/)。
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
若要清理所有服务，请使用如下命令：
|
||||
|
||||
```shell
|
||||
$ make clean_deploy
|
||||
```
|
||||
|
||||
### Kubernetes 示例
|
||||
|
||||
使用 Kubernetes 部署 Milvus 分布式集群要求开发人员对 Kubernetes 的[基本概念](https://kubernetes.io/docs/concepts/)和操作有基本了解。
|
||||
|
||||
本示例主要展示如何使用 Kubernetes 搭建 Milvus 集群，包含2个 Milvus 实例（1个可读实例，1个可写实例）、1个 MySQL 实例和1个 Mishards 实例。
|
||||
|
||||
本示例不包括如何搭建 Kubernetes 集群，如何安装[共享存储](https://kubernetes.io/docs/concepts/storage/volumes/)和如何安装 [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/) 命令行工具等。
|
||||
|
||||
以下是 Kubernetes 示例架构图：
|
||||
|
||||
|
||||
|
||||
#### 前提条件
|
||||
|
||||
使用 Kubernetes 启动多个 Milvus 实例之前，请确保您已满足以下条件：
|
||||
|
||||
- 已创建 Kubernetes 集群
|
||||
- 已安装 [nvidia-docker 2.0](https://github.com/nvidia/nvidia-docker/wiki/Installation-(version-2.0))
|
||||
- 已安装共享存储
|
||||
- 已安装 kubectl，且能访问集群
|
||||
|
||||
#### Kubernetes 启动集群
|
||||
|
||||
1. 启动 Milvus 集群。
|
||||
|
||||
```shell
|
||||
$ make cluster
|
||||
```
|
||||
|
||||
2. 确认 Mishards 是否可用。
|
||||
|
||||
```shell
|
||||
$ make probe_cluster
|
||||
Pass ==> Pass: Connected
|
||||
```
|
||||
|
||||
查看集群状态：
|
||||
|
||||
```shell
|
||||
$ make cluster_status
|
||||
```
|
||||
|
||||
删除 Milvus 集群：
|
||||
|
||||
```shell
|
||||
$ make clean_cluster
|
||||
```
|
||||
|
||||
扩容 Milvus 可读实例到2个：
|
||||
|
||||
```shell
|
||||
$ cd kubernetes_demo
|
||||
$ ./start.sh scale-ro-server 2
|
||||
```
|
||||
|
||||
扩容 Mishards（代理）实例到2个：
|
||||
|
||||
```shell
|
||||
$ cd kubernetes_demo
|
||||
$ ./start.sh scale-proxy 2
|
||||
```
|
||||
|
||||
查看计算节点 `milvus-ro-servers-0` 日志：
|
||||
|
||||
```shell
|
||||
$ kubectl logs -f --tail=1000 -n milvus milvus-ro-servers-0
|
||||
```
|
||||
|
||||
## 单元测试
|
||||
|
||||
**单元测试**
|
||||
|
||||
```shell
|
||||
$ cd milvus/shards
|
||||
$ make test
|
||||
```
|
||||
|
||||
**代码覆盖率测试**
|
||||
|
||||
```shell
|
||||
$ cd milvus/shards
|
||||
$ make coverage
|
||||
```
|
||||
|
||||
**代码格式检查**
|
||||
|
||||
```shell
|
||||
$ 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`](https://www.jaegertracing.io/docs/1.14/)时，链路追踪的 service。 |
|
||||
| `TRACING_SAMPLER_TYPE` | No | string | `const` | `TRACING_CLASS_NAME`为 `Jaeger` 时，链路追踪的[采样类型](https://www.jaegertracing.io/docs/1.14/sampling/)。 |
|
||||
| `TRACING_SAMPLER_PARAM` | No | integer | `1` | `TRACING_CLASS_NAME` 为 `Jaeger`时，链路追踪的[采样频率](https://www.jaegertracing.io/docs/1.14/sampling/)。 |
|
||||
| `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`，仅限测试环境下使用。 |
|
||||
@ -1,147 +0,0 @@
|
||||
# Mishards使用文档
|
||||
---
|
||||
Milvus 旨在帮助用户实现海量非结构化数据的近似检索和分析。单个 Milvus 实例可处理十亿级数据规模，而对于百亿或者千亿规模数据的需求，则需要一个 Milvus 集群实例，该实例对于上层应用可以像单机实例一样使用，同时满足海量数据低延迟，高并发业务需求。mishards就是一个集群中间件，其内部处理请求转发，读写分离，水平扩展，动态扩容，为用户提供内存和算力可以无限扩容的 Milvus 实例。
|
||||
|
||||
## 运行环境
|
||||
---
|
||||
|
||||
### 单机快速启动实例
|
||||
**`python >= 3.4`环境**
|
||||
|
||||
```
|
||||
1. cd milvus/shards
|
||||
2. pip install -r requirements.txt
|
||||
3. nvidia-docker run --rm -d -p 19530:19530 -v /tmp/milvus/db:/opt/milvus/db milvusdb/milvus:0.5.0-d102119-ede20b
|
||||
4. sudo chown -R $USER:$USER /tmp/milvus
|
||||
5. cp mishards/.env.example mishards/.env
|
||||
6. 在python mishards/main.py #.env配置mishards监听19532端口
|
||||
7. make probe port=19532 #健康检查
|
||||
```
|
||||
|
||||
### 容器启动实例
|
||||
`all_in_one`会在服务器上开启两个milvus实例，一个mishards实例，一个jaeger链路追踪实例
|
||||
|
||||
**启动**
|
||||
```
|
||||
cd milvus/shards
|
||||
1. 安装docker-compose
|
||||
2. make build
|
||||
3. make deploy #监听19531端口
|
||||
4. make clean_deploy #清理服务
|
||||
5. make probe_deplopy #健康检查
|
||||
```
|
||||
|
||||
**打开Jaeger UI**
|
||||
```
|
||||
浏览器打开 "http://127.0.0.1:16686/"
|
||||
```
|
||||
|
||||
### kubernetes中快速启动
|
||||
**准备**
|
||||
```
|
||||
- kubernetes集群
|
||||
- 安装nvidia-docker
|
||||
- 共享存储
|
||||
- 安装kubectl并能访问集群
|
||||
```
|
||||
|
||||
**步骤**
|
||||
```
|
||||
cd milvus/shards
|
||||
1. make deploy_cluster #启动集群
|
||||
2. make probe_cluster #健康检查
|
||||
3. make clean_cluster #关闭集群
|
||||
```
|
||||
|
||||
**扩容计算实例**
|
||||
```
|
||||
cd milvus/shards/kubernetes_demo/
|
||||
./start.sh scale-ro-server 2 扩容计算实例到2
|
||||
```
|
||||
|
||||
**扩容代理器实例**
|
||||
```
|
||||
cd milvus/shards/kubernetes_demo/
|
||||
./start.sh scale-proxy 2 扩容代理服务器实例到2
|
||||
```
|
||||
|
||||
**查看日志**
|
||||
```
|
||||
kubectl logs -f --tail=1000 -n milvus milvus-ro-servers-0 查看计算节点milvus-ro-servers-0日志
|
||||
```
|
||||
|
||||
## 测试
|
||||
|
||||
**启动单元测试**
|
||||
```
|
||||
1. cd milvus/shards
|
||||
2. make test
|
||||
```
|
||||
|
||||
**单元测试覆盖率**
|
||||
```
|
||||
1. cd milvus/shards
|
||||
2. make coverage
|
||||
```
|
||||
|
||||
**代码风格检查**
|
||||
```
|
||||
1. cd milvus/shards
|
||||
2. make style
|
||||
```
|
||||
|
||||
## mishards配置详解
|
||||
|
||||
### 全局
|
||||
| Name | Required | Type | Default Value | Explanation |
|
||||
| --------------------------- | -------- | -------- | ------------- | ------------- |
|
||||
| Debug | No | bool | True | 是否Debug工作模式 |
|
||||
| TIMEZONE | No | string | "UTC" | 时区 |
|
||||
| MAX_RETRY | No | int | 3 | 最大连接重试次数 |
|
||||
| SERVER_PORT | No | int | 19530 | 配置服务端口 |
|
||||
| WOSERVER | **Yes** | str | - | 配置后台可写Milvus实例地址。目前只支持静态设置,例"tcp://127.0.0.1:19530" |
|
||||
|
||||
### 元数据
|
||||
| Name | Required | Type | Default Value | Explanation |
|
||||
| --------------------------- | -------- | -------- | ------------- | ------------- |
|
||||
| SQLALCHEMY_DATABASE_URI | **Yes** | string | - | 配置元数据存储数据库地址 |
|
||||
| SQL_ECHO | No | bool | False | 是否打印Sql详细语句 |
|
||||
| SQLALCHEMY_DATABASE_TEST_URI | No | string | - | 配置测试环境下元数据存储数据库地址 |
|
||||
| SQL_TEST_ECHO | No | bool | False | 配置测试环境下是否打印Sql详细语句 |
|
||||
|
||||
### 服务发现
|
||||
| Name | Required | Type | Default Value | Explanation |
|
||||
| --------------------------- | -------- | -------- | ------------- | ------------- |
|
||||
| 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 | int | 19530 | **DISCOVERY_CLASS_NAME** 为 **static** 时，配置 Hosts 监听端口 |
|
||||
| DISCOVERY_KUBERNETES_NAMESPACE | No | string | - | **DISCOVERY_CLASS_NAME** 为 **kubernetes** 时，配置集群 namespace |
|
||||
| DISCOVERY_KUBERNETES_IN_CLUSTER | No | bool | False | **DISCOVERY_CLASS_NAME** 为 **kubernetes** 时，标明服务发现是否在集群中运行 |
|
||||
| DISCOVERY_KUBERNETES_POLL_INTERVAL | No | int | 5 | **DISCOVERY_CLASS_NAME** 为 **kubernetes** 时，标明服务发现监听服务列表频率,单位 Second |
|
||||
| DISCOVERY_KUBERNETES_POD_PATT | No | string | - | **DISCOVERY_CLASS_NAME** 为 **kubernetes** 时，匹配可读 Milvus 实例的正则表达式 |
|
||||
| DISCOVERY_KUBERNETES_LABEL_SELECTOR | No | string | - | **SD_PROVIDER** 为**Kubernetes**时，匹配可读Milvus实例的标签选择 |
|
||||
|
||||
### 链路追踪
|
||||
| Name | Required | Type | Default Value | Explanation |
|
||||
| --------------------------- | -------- | -------- | ------------- | ------------- |
|
||||
| TRACER_PLUGIN_PATH | No | string | - | 用户自定义链路追踪插件搜索路径，默认使用系统搜索路径|
|
||||
| TRACER_CLASS_NAME | No | string | "" | 链路追踪方案选择，目前只实现 **Jaeger**, 默认不使用|
|
||||
| TRACING_SERVICE_NAME | No | string | "mishards" | **TRACING_TYPE** 为 **Jaeger** 时，链路追踪服务名 |
|
||||
| TRACING_SAMPLER_TYPE | No | string | "const" | **TRACING_TYPE** 为 **Jaeger** 时，链路追踪采样类型 |
|
||||
| TRACING_SAMPLER_PARAM | No | int | 1 | **TRACING_TYPE** 为 **Jaeger** 时，链路追踪采样频率 |
|
||||
| TRACING_LOG_PAYLOAD | No | bool | False | **TRACING_TYPE** 为 **Jaeger** 时，链路追踪是否采集 Payload |
|
||||
|
||||
### 日志
|
||||
| Name | Required | Type | Default Value | Explanation |
|
||||
| --------------------------- | -------- | -------- | ------------- | ------------- |
|
||||
| LOG_LEVEL | No | string | "DEBUG" if Debug is ON else "INFO" | 日志记录级别 |
|
||||
| LOG_PATH | No | string | "/tmp/mishards" | 日志记录路径 |
|
||||
| LOG_NAME | No | string | "logfile" | 日志记录名 |
|
||||
|
||||
### 路由
|
||||
| Name | Required | Type | Default Value | Explanation |
|
||||
| --------------------------- | -------- | -------- | ------------- | ------------- |
|
||||
| ROUTER_PLUGIN_PATH | No | string | - | 用户自定义路由插件搜索路径，默认使用系统搜索路径|
|
||||
| ROUTER_CLASS_NAME | No | string | FileBasedHashRingRouter | 处理请求路由类名, 可注册自定义类。目前系统只提供了类 **FileBasedHashRingRouter** |
|
||||
| ROUTER_CLASS_TEST_NAME | No | string | FileBasedHashRingRouter | 测试环境下处理请求路由类名, 可注册自定义类 |
|
||||
Loading…
Reference in New Issue
Block a user