From 5b0dc8df70639483b50626f9c740d8f98edcd012 Mon Sep 17 00:00:00 2001 From: ougongchang Date: Sat, 1 Nov 2025 18:12:21 +0800 Subject: [PATCH] docs fix --- README.md | 3 +- README_CN.md | 3 +- docs/source_zh_cn/api/api_cpp/kv_cache.md | 35 +- docs/source_zh_cn/api/api_cpp/object_cache.md | 418 +++++++++--------- .../datasystem.DsTensorClient.dev_mset.rst | 2 +- ...etero_client.HeteroClient.generate_key.rst | 4 +- ...system.kv_client.KVClient.generate_key.rst | 2 +- .../datasystem.kv_client.KVClient.set.rst | 2 +- ...atasystem.kv_client.KVClient.set_value.rst | 2 +- .../datasystem.kv_client.SetParam.rst | 2 + ...tasystem.object_client.Buffer.get_size.rst | 2 +- .../datasystem.object_client.ObjectClient.rst | 3 +- docs/source_zh_cn/development-guide/hetero.md | 2 +- docs/source_zh_cn/development-guide/kv.md | 2 +- docs/source_zh_cn/development-guide/object.md | 2 +- docs/source_zh_cn/getting-started/overview.md | 12 +- python/ds_client.py | 3 +- python/object_client.py | 7 +- .../pybind_api/pybind_register_object.cpp | 4 +- tests/ut/CMakeLists.txt | 2 +- 20 files changed, 254 insertions(+), 258 deletions(-) diff --git a/README.md b/README.md index 7edd97c..76482bb 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ openYuanrong 由多语言函数运行时、函数系统和数据系统组成， openYuanrong 分为三个代码仓库：[yuanrong-runtime](https://gitee.com/openeuler/yuanrong-runtime) 对应多语言函数运行时；[yuanrong-functionsystem](https://gitee.com/openeuler/yuanrong-functionsystem) 对应函数系统；[yuanrong-datasystem](https://gitee.com/openeuler/yuanrong-datasystem) 对应数据系统，即当前代码仓。 -**数据系统（openYuanrong datasystem）** 是 openYuanrong 的核心概念抽象，是一款专为 AI 训推场景设计的分布式异构缓存系统。支持 HBM/DDR/SSD 异构介质池化缓存及 NPU 间异步并发高效数据传输，用于分布式 KVCache 缓存、模型参数缓存、高性能 replaybuffer 等场景。 +**数据系统（openYuanrong datasystem）** 是 openYuanrong 的核心概念抽象，是一个分布式缓存系统，利用计算集群的 HBM/DRAM/SSD 资源构建近计算多级缓存，提升模型训练及推理、大数据、微服务等场景数据访问性能。 openYuanrong datasystem 的主要特性包括： @@ -33,6 +33,7 @@ openYuanrong datasystem 的主要特性包括： - **模型推理实例 M->N 快速弹性**：利用异构对象的卡间直通及 P2P 数据分发能力实现模型参数快速复制。 - **强化学习模型参数重排**：利用异构对象的卡间直通传输能力，快速将模型参数从训练侧同步到推理侧。 - **训练场景 CheckPoint 快速保存及加载**：基于 KV 接口快速写 Checkpoint，并支持将数据持久化到二级缓存保证数据可靠性。Checkpoint恢复时各节点将 Checkpoint 分片快速加载到异构对象中，利用异构对象的卡间直通传输及 P2P 数据分发能力，快速将 Checkpoint 传递到各节点 HBM。 +- **微服务状态数据快速读写**：基于 KV 接口实现内存级读写微服务状态数据，并支持将数据持久化到二级缓存保证数据可靠性。 ### openYuanrong datasystem 架构 diff --git a/README_CN.md b/README_CN.md index 7edd97c..76482bb 100644 --- a/README_CN.md +++ b/README_CN.md @@ -14,7 +14,7 @@ openYuanrong 由多语言函数运行时、函数系统和数据系统组成， openYuanrong 分为三个代码仓库：[yuanrong-runtime](https://gitee.com/openeuler/yuanrong-runtime) 对应多语言函数运行时；[yuanrong-functionsystem](https://gitee.com/openeuler/yuanrong-functionsystem) 对应函数系统；[yuanrong-datasystem](https://gitee.com/openeuler/yuanrong-datasystem) 对应数据系统，即当前代码仓。 -**数据系统（openYuanrong datasystem）** 是 openYuanrong 的核心概念抽象，是一款专为 AI 训推场景设计的分布式异构缓存系统。支持 HBM/DDR/SSD 异构介质池化缓存及 NPU 间异步并发高效数据传输，用于分布式 KVCache 缓存、模型参数缓存、高性能 replaybuffer 等场景。 +**数据系统（openYuanrong datasystem）** 是 openYuanrong 的核心概念抽象，是一个分布式缓存系统，利用计算集群的 HBM/DRAM/SSD 资源构建近计算多级缓存，提升模型训练及推理、大数据、微服务等场景数据访问性能。 openYuanrong datasystem 的主要特性包括： @@ -33,6 +33,7 @@ openYuanrong datasystem 的主要特性包括： - **模型推理实例 M->N 快速弹性**：利用异构对象的卡间直通及 P2P 数据分发能力实现模型参数快速复制。 - **强化学习模型参数重排**：利用异构对象的卡间直通传输能力，快速将模型参数从训练侧同步到推理侧。 - **训练场景 CheckPoint 快速保存及加载**：基于 KV 接口快速写 Checkpoint，并支持将数据持久化到二级缓存保证数据可靠性。Checkpoint恢复时各节点将 Checkpoint 分片快速加载到异构对象中，利用异构对象的卡间直通传输及 P2P 数据分发能力，快速将 Checkpoint 传递到各节点 HBM。 +- **微服务状态数据快速读写**：基于 KV 接口实现内存级读写微服务状态数据，并支持将数据持久化到二级缓存保证数据可靠性。 ### openYuanrong datasystem 架构 diff --git a/docs/source_zh_cn/api/api_cpp/kv_cache.md b/docs/source_zh_cn/api/api_cpp/kv_cache.md index 988c4e1..ae1413b 100644 --- a/docs/source_zh_cn/api/api_cpp/kv_cache.md +++ b/docs/source_zh_cn/api/api_cpp/kv_cache.md @@ -6,25 +6,13 @@ | 类名 | 说明 | |--------------------------------|---------------------------------------------| -|[`enum ExistenceOpt`](#enum-existenceopt) |该选项用于配置对象存在时是否允许继续操作 | |[`class KVClient`](#class-kvclient) | KV缓存客户端类| +|[`enum ExistenceOpt`](#enum-existenceopt) |该选项用于配置对象存在时是否允许继续操作 | |[`class ReadOnlyBuffer`](#class-readonlybuffer) | 只读缓冲区结构类 | |[`struct MSetParam`](#struct-msetparam) | 同时创建多个Key时设置的属性 | |[`struct ReadParam`](#struct-readparam) | 偏移读取Key时设置的属性 | |[`struct SetParam`](#struct-setparam) | 创建Key时设置的属性 | - -## enum ExistenceOpt - -\#include <[datasystem/kv_cache/kv_client.h](../../../../include/datasystem/kv_cache/kv_client.h)> - -用于配置对象存在时是否允许继续操作的枚举类。 - - 定义 | 说明 ---------------------------------|--------------------------------------------- -NONE | 允许Key存在时执行Set -NX | 不允许Key存在时执行Set - ## class KVClient \#include <[datasystem/kv_cache/kv_client.h](../../../../include/datasystem/kv_cache/kv_client.h)> @@ -103,7 +91,7 @@ KV缓存对象类 - `param` 设置参数，详见[SetParam](#struct-setparam)章节 - 返回值 - - 成功时返回非空字符串 + - 成功时返回key - 失败时返回空字符串 @@ -266,7 +254,7 @@ KV缓存对象类 返回值状态码为 `K_OK` 时表示 Worker 健康，否则返回其他错误码。 -#### Status KVClient::Exist(const std::vector &keys, std::vector &exists) +#### Status KVClient::Exist(const std::vector<std::string> &keys, std::vector &exists) 批量查询一组键（keys）是否存在，并返回每个键的存在性状态。支持最多10000个键的查询。 @@ -283,7 +271,7 @@ KV缓存对象类 -#### Status Expire (const std::vector &keys, uint32_t ttlSeconds, std::vector &failedKeys) +#### Status Expire (const std::vector<std::string> &keys, uint32_t ttlSeconds, std::vector<std::string> &failedKeys) 批量为一组键（keys）更新过期生命周期（ttlSeconds），并返回更新失败的键（failedKeys）。最多支持 10000 个键的查询。 @@ -300,17 +288,28 @@ KV缓存对象类 - 返回`K_NOT_READY` 表示服务当前无法处理请求 - 返回`K_RUNTIME_ERROR`表示 worker 侧存在错误 +## enum ExistenceOpt + +\#include <[datasystem/kv_cache/kv_client.h](../../../../include/datasystem/kv_cache/kv_client.h)> + +用于配置对象存在时是否允许继续操作的枚举类。 + + 定义 | 说明 +--------------------------------|--------------------------------------------- +NONE | 允许Key存在时执行Set +NX | 不允许Key存在时执行Set + ## class ReadOnlyBuffer \#include <[datasystem/kv_cache/read_only_buffer.h](../../../../include/datasystem/kv_cache/read_only_buffer.h)> ### 构造函数和析构函数 -#### ReadOnlyBuffer () = default +#### ReadOnlyBuffer () 构造只读缓冲区结构类 -#### ~ReadOnlyBuffer () = default +#### ~ReadOnlyBuffer () 析构只读缓冲区结构类 diff --git a/docs/source_zh_cn/api/api_cpp/object_cache.md b/docs/source_zh_cn/api/api_cpp/object_cache.md index d0fd8d3..04c6a51 100644 --- a/docs/source_zh_cn/api/api_cpp/object_cache.md +++ b/docs/source_zh_cn/api/api_cpp/object_cache.md @@ -6,30 +6,214 @@ | 类名 | 说明 | | --- | --- | +| [ObjectClient](#objectclient) | 对象缓存客户端类。| | [Buffer](#buffer) | 对象缓存数据类。| | [CreateParam](#createparam) | 创建对象时的配置参数类。| | [WriteMode](#writemode) | 配置对象可靠性的枚举类。| | [ConsistencyType](#consistencytype) | 配置对象一致性的枚举类。| -| [ObjectClient](#objectclient) | 对象缓存客户端类。| +| [CacheType](#cachetype) | 配置对象缓存类型。| -## enum CacheType -\#include <[datasystem/object_cache/object_enum.h](../../../../include/datasystem/object_cache/object_enum.h)> +## ObjectClient -CacheType 类用于配置对象保存位置，当前定义如下： +\#include <[datasystem/object_cache/object_client.h](../../../../include/datasystem/object_cache/object_client.h)> + +Buffer 类用于表示对象缓存数据类。 + +### 构造函数和析构函数 ```cpp -enum class CacheType : int { - MEMORY = 0, - DISK = 1, -}; +explicit ObjectClient(const ConnectOptions &connectOptions = {}) +~ObjectClient() +``` +### 公有成员函数 + +| 函数 | 说明 | +|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------| +| [`Status Init()`](#init) | 初始化客户端。 | +| [`Status ShutDown()`](#shutdown) | 关闭客户端。 | +| [`Status GIncreaseRef(const std::vector &objectKeys, std::vector &failedObjectKeys)`](#gincreaseref) | 增加对象的全局引用计数。 | +| [`Status GDecreaseRef(const std::vector &objectKeys, std::vector &failedObjectKeys)`](#gdecreaseref) | 减少对象的全局引用计数。 | +| [`int QueryGlobalRefNum(const std::string &objectKey)`](#queryglobalrefnum) | 查询对象的全局引用计数。 | +| [`Status Create(const std::string &objectKey, uint64_t size, const CreateParam ¶m, std::shared_ptr &buffer)`](#create) | 创建对象 Buffer。 | +| [`Status Put(const std::string &objectKey, const uint8_t *data, uint64_t size, const CreateParam ¶m, const std::unordered_set &nestedObjectKeys = {})`](#put) | 创建或更新对象并发布。 | +| [`Status Get(const std::vector &objectKeys, int32_t subTimeoutMs, std::vector> &buffers)`](#get) | 获取对象。 | +| [`Status GenerateObjectKey(const std::string &prefix, std::string &objectKey)`](#generateobjectkey) | 生成带数据系统 Worker UUID 的对象 key。 | +| [`Status HealthCheck()`](#healthcheck) | 检查当前正在连接的数据系统 Worker 健康检查状况。 | + +#### ShutDown + +```cpp +Status ShutDown() ``` -目前，支持以下 `CacheType`： -|定义| 说明 | -|----|--------------------------------------| -|`CacheType.MEMORY` | 保存到内存| -|`CacheType.DISK` | 保存到磁盘| +断开对象缓存客户端与当前数据系统 Worker 之间的连接。 + +- 返回值 + + 返回值状态码为 `K_OK` 时表示断链成功，否则返回其他错误码。 + +#### Init + +```cpp +Status Init() +``` + +建立对象缓存客户端与当前数据系统 Worker 之间的连接并完成初始化。 + +- 返回值 + + 返回值状态码为 `K_OK` 时表示初始化成功，否则返回其他错误码。 + +#### GIncreaseRef + +```cpp +Status GIncreaseRef(const std::vector &objectKeys, std::vector &failedObjectKeys) +``` + +增加对象的全局引用计数。 + +- 参数 + + - `objectKeys`: 需要增加全局引用计数的对象 key 数组。约束：传入的object key的数量不能超过1万。 + - `failedObjectKeys`: 传出参数，增加全局引用计数失败的对象 key 会被保存在该字符串数组中。 + +- 返回值 + + - 返回值状态码为 `K_OK` 时表示至少有一个对象增加全局引用计数成功。 + - 返回值状态码为 `K_RPC_UNAVAILABLE` 时表示请求遇到了网络错误。 + - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 + +#### GDecreaseRef + +```cpp +Status GDecreaseRef(const std::vector &objectKeys, std::vector &failedObjectKeys) +``` + +减少对象的全局引用计数。 + +- 参数 + + - `objectKeys`: 需要减少全局引用计数的对象 key 数组。约束：传入的object key的数量不能超过1万。 + - `failedObjectKeys`: 传出参数，减少全局引用计数失败的对象 key 会被保存在该字符串数组中。 + +- 返回值 + + - 返回值状态码为 `K_OK` 时表示至少有一个对象减少全局引用计数成功。 + - 返回值状态码为 `K_RPC_UNAVAILABLE` 时表示请求遇到了网络错误。 + - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 + +#### QueryGlobalRefNum + +```cpp +int QueryGlobalRefNum(const std::string &objectKey) +``` + +查询对象的全局引用计数。 + +- 参数 + + - `objectKey`: 对象 key。 + +- 返回值 + + 返回值为大于等于 0 的数字时表示查询成功，返回值即为对象 key 的全局引用计数；返回 -1 时表示查询失败。 + +#### Create + +```cpp +Status Create(const std::string &objectKey, uint64_t size, const CreateParam ¶m, + std::shared_ptr &buffer) +``` + +创建对象 Buffer。 + +- 参数 + + - `objectKey`: 对象 key。 + - `size`: 对象大小（以字节为单位）。 + - `param`: 详见 [CreateParam](#createparam) 章节。 + - `buffer`: 传出参数，[Buffer](#buffer)。 + +- 返回值 + + - 返回值状态码为 `K_OK` 时表示创建对象成功。 + - 返回值状态码为 `K_RPC_UNAVAILABLE` 时表示请求遇到了网络错误。 + - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 + +#### Put + +```cpp +Status Put(const std::string &objectKey, const uint8_t *data, uint64_t size, const CreateParam ¶m, + const std::unordered_set &nestedObjectKeys = {}) +``` + +创建或更新对象并发布。 + +- 参数 + + - `objectKey`: 对象 key。 + - `data`: 数据内存地址指针。 + - `size`: 数据大小（以字节为单位）。 + - `param`: 详见 [CreateParam](#createparam) 章节。 + - `nestedObjectKeys`: 对该对象 key 有依赖关系的对象 key 数组。 + +- 返回值 + + - 返回值状态码为 `K_OK` 时表示对象创建或更新并发布成功。 + - 返回值状态码为 `K_RPC_UNAVAILABLE` 时表示请求遇到了网络错误。 + - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 + +#### Get + +```cpp +Status Get(const std::vector &objectKeys, int32_t subTimeoutMs, std::vector> &buffers) +``` + +获取对象。 + +- 参数 + + - `objectKeys`: 需要获取的对象 key 数组。约束：传入的object key的数量不能超过1万。 + - `subTimeoutMs`: 对象订阅时间（以毫秒为单位）；对象未就绪时，产生订阅等待对象就绪返回，0 表示不订阅，可配置范围为[0, INT32_MAX]。 + - `buffers`: 对象 [Buffer](#buffer)。 + +- 返回值 + + - 返回值状态码为 `K_OK` 时表示至少有一个对象获取成功。 + - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 + - 返回值状态码为 `K_NOT_FOUND` 时表示所有对象都无法获取到。 + - 返回值状态码为 `K_RUNTIME_ERROR` 时表示获取对象遇到了错误。 + +#### GenerateObjectKey + +```cpp +Status GenerateObjectKey(const std::string &prefix, std::string &objectKey) +``` + +生成带数据系统 Worker UUID 的对象 key。 + +- 参数 + + - `prefix`: 对象 key 前缀。 + - `objectKey`: 传出参数，生成成功时会将对象 key 写入到该参数中。 + +- 返回值 + + - 返回值状态码为 `K_OK` 时表示对象 key 生成成功。 + - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 + +#### HealthCheck + +```cpp +Status HealthCheck() +``` + +检查当前正在连接的数据系统 Worker 健康检查状况。 + +- 返回值 + + - 返回值状态码为 `K_OK` 时表示 Worker 状态健康，否则返回其他错误码。 ## Buffer @@ -275,205 +459,21 @@ enum class ConsistencyType : int { |`ConsistencyType.PRAM` | PRAM 一致性。| |`ConsistencyType.CAUSAL` | 因果一致性。| +## enum CacheType +\#include <[datasystem/object_cache/object_enum.h](../../../../include/datasystem/object_cache/object_enum.h)> -## ObjectClient - -\#include <[datasystem/object_cache/object_client.h](../../../../include/datasystem/object_cache/object_client.h)> - -Buffer 类用于表示对象缓存数据类。 - -### 构造函数和析构函数 - -```cpp -explicit ObjectClient(const ConnectOptions &connectOptions = {}) -~ObjectClient() -``` - -### 公有成员函数 - -| 函数 | 说明 | -|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------| -| [`Status Init()`](#init) | 初始化客户端。 | -| [`Status ShutDown()`](#shutdown) | 关闭客户端。 | -| [`Status GIncreaseRef(const std::vector &objectKeys, std::vector &failedObjectKeys)`](#gincreaseref) | 增加对象的全局引用计数。 | -| [`Status GDecreaseRef(const std::vector &objectKeys, std::vector &failedObjectKeys)`](#gdecreaseref) | 减少对象的全局引用计数。 | -| [`int QueryGlobalRefNum(const std::string &objectKey)`](#queryglobalrefnum) | 查询对象的全局引用计数。 | -| [`Status Create(const std::string &objectKey, uint64_t size, const CreateParam ¶m, std::shared_ptr &buffer)`](#create) | 创建对象 Buffer。 | -| [`Status Put(const std::string &objectKey, const uint8_t *data, uint64_t size, const CreateParam ¶m, const std::unordered_set &nestedObjectKeys = {})`](#put) | 创建或更新对象并发布。 | -| [`Status Get(const std::vector &objectKeys, int32_t subTimeoutMs, std::vector> &buffers)`](#get) | 获取对象。 | -| [`Status GenerateObjectKey(const std::string &prefix, std::string &objectKey)`](#generateobjectkey) | 生成带数据系统 Worker UUID 的对象 key。 | -| [`Status HealthCheck()`](#healthcheck) | 检查当前正在连接的数据系统 Worker 健康检查状况。 | - -#### ShutDown - -```cpp -Status ShutDown() -``` - -断开对象缓存客户端与当前数据系统 Worker 之间的连接。 - -- 返回值 - - 返回值状态码为 `K_OK` 时表示断链成功，否则返回其他错误码。 - -#### Init - -```cpp -Status Init() -``` - -建立对象缓存客户端与当前数据系统 Worker 之间的连接并完成初始化。 - -- 返回值 - - 返回值状态码为 `K_OK` 时表示初始化成功，否则返回其他错误码。 - -#### GIncreaseRef - -```cpp -Status GIncreaseRef(const std::vector &objectKeys, std::vector &failedObjectKeys) -``` - -增加对象的全局引用计数。 - -- 参数 - - - `objectKeys`: 需要增加全局引用计数的对象 key 数组。约束：传入的object key的数量不能超过1万。 - - `failedObjectKeys`: 传出参数，增加全局引用计数失败的对象 key 会被保存在该字符串数组中。 - -- 返回值 - - - 返回值状态码为 `K_OK` 时表示至少有一个对象增加全局引用计数成功。 - - 返回值状态码为 `K_RPC_UNAVAILABLE` 时表示请求遇到了网络错误。 - - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 - -#### GDecreaseRef - -```cpp -Status GDecreaseRef(const std::vector &objectKeys, std::vector &failedObjectKeys) -``` - -减少对象的全局引用计数。 - -- 参数 - - - `objectKeys`: 需要减少全局引用计数的对象 key 数组。约束：传入的object key的数量不能超过1万。 - - `failedObjectKeys`: 传出参数，减少全局引用计数失败的对象 key 会被保存在该字符串数组中。 - -- 返回值 - - - 返回值状态码为 `K_OK` 时表示至少有一个对象减少全局引用计数成功。 - - 返回值状态码为 `K_RPC_UNAVAILABLE` 时表示请求遇到了网络错误。 - - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 - -#### QueryGlobalRefNum - -```cpp -int QueryGlobalRefNum(const std::string &objectKey) -``` - -查询对象的全局引用计数。 - -- 参数 - - - `objectKey`: 对象 key。 - -- 返回值 - - 返回值为大于等于 0 的数字时表示查询成功，返回值即为对象 key 的全局引用计数；返回 -1 时表示查询失败。 - -#### Create - -```cpp -Status Create(const std::string &objectKey, uint64_t size, const CreateParam ¶m, - std::shared_ptr &buffer) -``` - -创建对象 Buffer。 - -- 参数 - - - `objectKey`: 对象 key。 - - `size`: 对象大小（以字节为单位）。 - - `param`: 详见 [CreateParam](#createparam) 章节。 - - `buffer`: 传出参数，[Buffer](#buffer)。 - -- 返回值 - - - 返回值状态码为 `K_OK` 时表示创建对象成功。 - - 返回值状态码为 `K_RPC_UNAVAILABLE` 时表示请求遇到了网络错误。 - - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 - -#### Put - -```cpp -Status Put(const std::string &objectKey, const uint8_t *data, uint64_t size, const CreateParam ¶m, - const std::unordered_set &nestedObjectKeys = {}) -``` - -创建或更新对象并发布。 - -- 参数 - - - `objectKey`: 对象 key。 - - `data`: 数据内存地址指针。 - - `size`: 数据大小（以字节为单位）。 - - `param`: 详见 [CreateParam](#createparam) 章节。 - - `nestedObjectKeys`: 对该对象 key 有依赖关系的对象 key 数组。 - -- 返回值 - - - 返回值状态码为 `K_OK` 时表示对象创建或更新并发布成功。 - - 返回值状态码为 `K_RPC_UNAVAILABLE` 时表示请求遇到了网络错误。 - - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 - -#### Get - -```cpp -Status Get(const std::vector &objectKeys, int32_t subTimeoutMs, std::vector> &buffers) -``` - -获取对象。 - -- 参数 - - - `objectKeys`: 需要获取的对象 key 数组。约束：传入的object key的数量不能超过1万。 - - `subTimeoutMs`: 对象订阅时间（以毫秒为单位）；对象未就绪时，产生订阅等待对象就绪返回，0 表示不订阅，可配置范围为[0, INT32_MAX]。 - - `buffers`: 对象 [Buffer](#buffer)。 - -- 返回值 - - - 返回值状态码为 `K_OK` 时表示至少有一个对象获取成功。 - - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 - - 返回值状态码为 `K_NOT_FOUND` 时表示所有对象都无法获取到。 - - 返回值状态码为 `K_RUNTIME_ERROR` 时表示获取对象遇到了错误。 - -#### GenerateObjectKey +CacheType 类用于配置对象保存位置，当前定义如下： ```cpp -Status GenerateObjectKey(const std::string &prefix, std::string &objectKey) -``` - -生成带数据系统 Worker UUID 的对象 key。 - -- 参数 - - - `prefix`: 对象 key 前缀。 - - `objectKey`: 传出参数，生成成功时会将对象 key 写入到该参数中。 - -- 返回值 - - - 返回值状态码为 `K_OK` 时表示对象 key 生成成功。 - - 返回值状态码为 `K_INVALID` 时表示传入参数未通过参数合法校验。 - -#### HealthCheck +enum class CacheType : int { + MEMORY = 0, + DISK = 1, +}; -```cpp -Status HealthCheck() ``` -检查当前正在连接的数据系统 Worker 健康检查状况。 - -- 返回值 - - - 返回值状态码为 `K_OK` 时表示 Worker 状态健康，否则返回其他错误码。 +目前，支持以下 `CacheType`： +|定义| 说明 | +|----|--------------------------------------| +|`CacheType.MEMORY` | 保存到内存| +|`CacheType.DISK` | 保存到磁盘| diff --git a/docs/source_zh_cn/api/api_python/ds_tensor_client/DsTensorClient/datasystem.DsTensorClient.dev_mset.rst b/docs/source_zh_cn/api/api_python/ds_tensor_client/DsTensorClient/datasystem.DsTensorClient.dev_mset.rst index 1c71a1e..ca81bf2 100644 --- a/docs/source_zh_cn/api/api_python/ds_tensor_client/DsTensorClient/datasystem.DsTensorClient.dev_mset.rst +++ b/docs/source_zh_cn/api/api_python/ds_tensor_client/DsTensorClient/datasystem.DsTensorClient.dev_mset.rst @@ -5,7 +5,7 @@ datasystem.DsTensorClient.dev_mset 通过数据系统缓存 Device 上的数据，将 tensors 对应的 key 的元数据写入数据系统，可供其他 client 访问。 - dev_mset 和 dev_mget 需配套使用。dev_mset 和 dev_mget 传入的 Device 内存地址不能归属于同一张 NPU 卡。 + dev_mset 和 dev_mget 需配套使用。 dev_mget 后不会自动删除异构对象，如对象不再使用，可调用 dev_local_delete 或 dev_delete 删除。 diff --git a/docs/source_zh_cn/api/api_python/hetero_client/HeteroClient/datasystem.hetero_client.HeteroClient.generate_key.rst b/docs/source_zh_cn/api/api_python/hetero_client/HeteroClient/datasystem.hetero_client.HeteroClient.generate_key.rst index 7d958be..7fadde4 100644 --- a/docs/source_zh_cn/api/api_python/hetero_client/HeteroClient/datasystem.hetero_client.HeteroClient.generate_key.rst +++ b/docs/source_zh_cn/api/api_python/hetero_client/HeteroClient/datasystem.hetero_client.HeteroClient.generate_key.rst @@ -1,12 +1,12 @@ datasystem.hetero_client.HeteroClient.generate_key ================================================== -.. py:method:: datasystem.hetero_client.HeteroClient.generate_key(prefix) +.. py:method:: datasystem.hetero_client.HeteroClient.generate_key(prefix='') 生成一个带数据系统 Worker UUID 的 key。 参数： - - **prefix** (str) - key 的前缀。 + - **prefix** (str) - key 的前缀，当为空时自动生成前缀。 返回： - **key** (string) - 生成的 key。 diff --git a/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.generate_key.rst b/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.generate_key.rst index 163d10d..d978908 100644 --- a/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.generate_key.rst +++ b/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.generate_key.rst @@ -6,7 +6,7 @@ datasystem.kv_client.KVClient.generate_key 生成唯一的键。 参数： - - **prefix** (str) - 前缀。 + - **prefix** (str) - 前缀，当为空时自动生成前缀。 返回： 唯一键。如果键生成失败，将返回空字符串。 diff --git a/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.set.rst b/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.set.rst index 3ff86fd..1368d66 100644 --- a/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.set.rst +++ b/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.set.rst @@ -9,7 +9,7 @@ datasystem.kv_client.KVClient.set - **key** (str) - 字符串类型的键。 - **val** (Union[memoryview, bytes, bytearray, str]) - 要设置的数据。 - **write_mode** (WriteMode) - 控制数据是否写入L2缓存以增强数据可靠性。 - - **ttl_second** (int) - 控制数据的过期时间。 + - **ttl_second** (int) - 控制数据的过期时间，超时会自动删除，单位为秒。0表示不会自动过期，需要通过调用 :func:`datasystem.kv_client.KVClient.delete` 接口删除 `keys` 才能退出生命周期。默认值：``0``。 异常： - **RuntimeError** - 如果设置键值失败，将抛出运行时错误。 diff --git a/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.set_value.rst b/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.set_value.rst index 34257db..774f03c 100644 --- a/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.set_value.rst +++ b/docs/source_zh_cn/api/api_python/kv_client/KVClient/datasystem.kv_client.KVClient.set_value.rst @@ -8,7 +8,7 @@ datasystem.kv_client.KVClient.set_value 参数： - **val** (Union[memoryview, bytes, bytearray, str]) - 要设置的数据。 - **write_mode** (WriteMode) - 控制数据是否写入二级缓存以增强数据可靠性。 - - **ttl_second** (int) - 控制数据的过期时间。 + - **ttl_second** (int) - 控制数据的过期时间，超时会自动删除，单位为秒。0表示不会自动过期，需要通过调用 :func:`datasystem.kv_client.KVClient.delete` 接口删除 `keys` 才能退出生命周期。默认值：``0``。 返回： 数据的键。如果设置失败，将返回空字符串。 diff --git a/docs/source_zh_cn/api/api_python/kv_client/datasystem.kv_client.SetParam.rst b/docs/source_zh_cn/api/api_python/kv_client/datasystem.kv_client.SetParam.rst index 3a35570..9123ede 100644 --- a/docs/source_zh_cn/api/api_python/kv_client/datasystem.kv_client.SetParam.rst +++ b/docs/source_zh_cn/api/api_python/kv_client/datasystem.kv_client.SetParam.rst @@ -3,6 +3,8 @@ datasystem.kv_client.SetParam .. py:class:: datasystem.kv_client.SetParam + :func:`datasystem.hetero_client.HeteroClient.mset_d2h` 以及 `datasystem.hetero_client.HeteroClient.async_mset_d2h` 方法的入参，用于指定随机读的键名称、偏移量以及大小。 + :ivar WriteMode write_mode: key的可靠性配置。 :ivar int ttl_seconds: key的存活时间, (以秒为单位)。 :ivar ExistenceOpt existence: key存在时能否设置。 diff --git a/docs/source_zh_cn/api/api_python/object_client/Buffer/datasystem.object_client.Buffer.get_size.rst b/docs/source_zh_cn/api/api_python/object_client/Buffer/datasystem.object_client.Buffer.get_size.rst index 9ed6c0b..53bf012 100644 --- a/docs/source_zh_cn/api/api_python/object_client/Buffer/datasystem.object_client.Buffer.get_size.rst +++ b/docs/source_zh_cn/api/api_python/object_client/Buffer/datasystem.object_client.Buffer.get_size.rst @@ -3,7 +3,7 @@ datasystem.object_client.Buffer.get_size .. py:method:: datasystem.object_client.Buffer.get_size - 创建对象buffer。 + 获取对象buffer的大小。 返回： size，对象buffer大小（以字节为单位）。 diff --git a/docs/source_zh_cn/api/api_python/object_client/datasystem.object_client.ObjectClient.rst b/docs/source_zh_cn/api/api_python/object_client/datasystem.object_client.ObjectClient.rst index 8f6be4f..e1446ff 100644 --- a/docs/source_zh_cn/api/api_python/object_client/datasystem.object_client.ObjectClient.rst +++ b/docs/source_zh_cn/api/api_python/object_client/datasystem.object_client.ObjectClient.rst @@ -1,7 +1,7 @@ datasystem.object_client.ObjectClient ===================================== -.. py:class:: datasystem.object_client.ObjectClient(host, port, connect_timeout_ms=60000, client_public_key="", client_private_key="", server_public_key="", access_key="", secret_key="", tenant_id="", enable_cross_node_connection=False) +.. py:class:: datasystem.object_client.ObjectClient(host, port, connect_timeout_ms=60000, client_public_key="", client_private_key="", server_public_key="", access_key="", secret_key="", tenant_id="") 对象缓存客户端。 @@ -15,7 +15,6 @@ datasystem.object_client.ObjectClient - **access_key** (str) - AK/SK授权使用的访问密钥。默认值： ``""`` 。 - **secret_key** (str) - AK/SK授权的密钥。默认值： ``""`` 。 - **tenant_id** (str) - 租户ID。默认值： ``""`` 。 - - **enable_cross_node_connection** (bool) - 如果为 ``True`` ，允许客户端在与当前数据系统Worker连接异常时自动切换到备用节点。默认值： ``False`` 。 输出： ObjectClient diff --git a/docs/source_zh_cn/development-guide/hetero.md b/docs/source_zh_cn/development-guide/hetero.md index c09de1b..01398cb 100644 --- a/docs/source_zh_cn/development-guide/hetero.md +++ b/docs/source_zh_cn/development-guide/hetero.md @@ -481,7 +481,7 @@ ASSERT_TRUE(status.IsOk()); ## 使用限制 -- key 仅支持大写字母、小写字母、数字以及如下特定字符：`~.-/_!@#%^&*()+=:;`。 +- key 仅支持大写字母、小写字母、数字以及如下特定字符：`-_!@#%^*()+=:;`。 - key 的最大长度为 255 字节。 - DevPublish 和 DevSubscribe 需配套使用，不能和 DevMSet 及 DevMGet 混合使用。 - DevMSet 及 DevMGet 配套使用，写入的 key 使用 DevDelete 及 DevLocalDelete 删除。 diff --git a/docs/source_zh_cn/development-guide/kv.md b/docs/source_zh_cn/development-guide/kv.md index 7637de1..9670820 100644 --- a/docs/source_zh_cn/development-guide/kv.md +++ b/docs/source_zh_cn/development-guide/kv.md @@ -68,7 +68,7 @@ ASSERT_TRUE(status.IsError()); ## 使用限制 -- key 仅支持大写字母、小写字母、数字以及如下特定字符：`~.-/_!@#%^&*()+=:;`。 +- key 仅支持大写字母、小写字母、数字以及如下特定字符：`-_!@#%^*()+=:;`。 - key 的最大长度为 255 字节。 - value 的最大长度没有限制，但是不能超出配置的共享内存大小。 - 未写入二级缓存的数据，不保证数据可靠性，当发生故障时数据可能会丢失。 diff --git a/docs/source_zh_cn/development-guide/object.md b/docs/source_zh_cn/development-guide/object.md index 1687239..11181d8 100644 --- a/docs/source_zh_cn/development-guide/object.md +++ b/docs/source_zh_cn/development-guide/object.md @@ -98,7 +98,7 @@ Object 数据支持将数据溢出到磁盘，相关配置与 KV 相同，详情 ## 使用限制 -- key 仅支持大写字母、小写字母、数字以及如下特定字符：`~.-/_!@#%^&*()+=:;`。 +- key 仅支持大写字母、小写字母、数字以及如下特定字符：`-_!@#%^*()+=:;`。 - key 的最大长度为 255 字节。 - value 的最大长度没有限制，但是不能超出配置的共享内存大小。 - 未写入二级缓存的数据，不保证数据可靠性，当发生故障时数据可能会丢失。 \ No newline at end of file diff --git a/docs/source_zh_cn/getting-started/overview.md b/docs/source_zh_cn/getting-started/overview.md index 3cd373f..d836e19 100644 --- a/docs/source_zh_cn/getting-started/overview.md +++ b/docs/source_zh_cn/getting-started/overview.md @@ -1,19 +1,19 @@ # 入门 -yuanrong-datasystem 是一个分布式缓存系统，利用计算集群的 HBM/DRAM/SSD 资源构建近计算多级缓存，提升模型训练及推理、大数据、微服务等场景数据访问性能。 +openYuanrong datasystem 是一个分布式缓存系统，利用计算集群的 HBM/DRAM/SSD 资源构建近计算多级缓存，提升模型训练及推理、大数据、微服务等场景数据访问性能。 ## 整体架构 ![](./image/logical_architecture.png) -yuanrong-datasystem 由三个部分组成： +openYuanrong datasystem 由三个部分组成： - **多语言SDK**：提供 Python/C++ 语言接口，封装 heterogeneous object/KV/object 多种语义，支撑业务实现数据快速读写。 - **heterogeneous object**：基于 NPU 卡的 HBM 内存抽象异构对象接口，实现昇腾 NPU 卡间数据高速直通传输。同时提供 H2D/D2H 高速迁移接口，实现数据快速在 DRAM/HBM 之间传输。 - **KV**：基于共享内存实现免拷贝的 KV 数据读写，实现高性能数据缓存，支持通过对接外部组件提供数据可靠性语义。 - **object**：基于 host 侧共享内存抽象数据对象，实现基于引用计数的生命周期管理，将共享内存封装为 buffer，提供指针直接读写。 -- **worker**：yuanrong-datasystem 的核心组件，用于管理 DRAM/SSD 及元数据，提供近计算缓存能力。 +- **worker**：openYuanron datasystem 的核心组件，用于管理 DRAM/SSD 及元数据，提供近计算缓存能力。 - **共享内存免拷贝**：基于共享内存对外提供数据读写接口，避免 SDK 与 worker 间数据拷贝，提升性能。 - **NPU 间并发通信**：通过异构对象抽象实现卡间直通通信，自动协调 NPU 间 HCCL 收发顺序，实现 NPU 卡间数据并发传输。 - **P2P 数据分发**：大规模数据复制时，实现 P2P 传输负载均衡策略，允许由新的数据接收者提供数据，充分利用卡间链路带宽。 @@ -25,7 +25,7 @@ yuanrong-datasystem 由三个部分组成： ![](./image/deployment.png) -yuanrong-datasystem 的部署视图(如上图所示)： +openYuanrong datasystem 的部署视图(如上图所示)： - 需部署 ETCD 用于集群管理。 - 每个节点需部署 worker 进程并注册到 ETCD。 @@ -41,8 +41,8 @@ yuanrong-datasystem 的部署视图(如上图所示)： ## 安装部署 -yuanrong-datasystem 提供了 pip install 及源码安装两种方式，详细请参考[安装指南](install.md)。 -yuanrong-datasystem 提供了两种部署方式： +openYuanrong datasystem 提供了 pip install 及源码安装两种方式，详细请参考[安装指南](install.md)。 +openYuanrong datasystem 提供了两种部署方式： - [快速进程部署](deploy.md#openyuanrong-datasystem进程部署) - [在 Kubernetes上部署](deploy.md#openyuanrong-datasystem-kubernetes部署) diff --git a/python/ds_client.py b/python/ds_client.py index 3f63389..db37312 100644 --- a/python/ds_client.py +++ b/python/ds_client.py @@ -103,8 +103,7 @@ class DsClient: server_public_key, access_key, secret_key, - tenant_id, - enable_cross_node_connection + tenant_id ) def init(self): diff --git a/python/object_client.py b/python/object_client.py index b9b4dee..ffa9f34 100644 --- a/python/object_client.py +++ b/python/object_client.py @@ -297,7 +297,6 @@ class ObjectClient: access_key(str): The access key used by AK/SK authorize. secret_key(str): The secret key for AK/SK authorize. tenant_id(str): The tenant ID. - enable_cross_node_connection(bool): Indicates whether the client can connect to the standby node. Raises: TypeError: Raise a type error if the input parameter is invalid. @@ -318,7 +317,6 @@ class ObjectClient: access_key="", secret_key="", tenant_id="", - enable_cross_node_connection=False, ): """Constructor of the ObjectClient class @@ -336,7 +334,6 @@ class ObjectClient: oauth_client_secret(str): The client secret for tenant. oauth_url(str): The auth url of IAM. tenant_id(str): The tenant ID. - enable_cross_node_connection(bool): Indicates whether the client can connect to the standby node. Raises: TypeError: Raise a type error if the input parameter is invalid. @@ -351,7 +348,6 @@ class ObjectClient: ["access_key", access_key, str], ["secret_key", secret_key, str], ["tenant_id", tenant_id, str], - ["enable_cross_node_connection", enable_cross_node_connection, bool], ] validator.check_args_types(args) self.client = ds.ObjectClient( @@ -363,8 +359,7 @@ class ObjectClient: server_public_key, access_key, secret_key, - tenant_id, - enable_cross_node_connection, + tenant_id ) @staticmethod diff --git a/src/datasystem/pybind_api/pybind_register_object.cpp b/src/datasystem/pybind_api/pybind_register_object.cpp index 085f971..4304df2 100644 --- a/src/datasystem/pybind_api/pybind_register_object.cpp +++ b/src/datasystem/pybind_api/pybind_register_object.cpp @@ -126,7 +126,7 @@ PybindDefineRegisterer g_pybind_define_f_Client("ObjectClient", PRIORITY_LOW, [] .def(py::init([](const std::string &host, int32_t port, int32_t connectTimeoutMs, const std::string &clientPublicKey, const std::string &clientPrivateKey, const std::string &serverPublicKey, const std::string &accessKey, const std::string &secretKey, - const std::string &tenantId, const bool enableCrossNodeConnection) { + const std::string &tenantId) { ConnectOptions connectOpts{ .host = host, .port = port, .connectTimeoutMs = connectTimeoutMs, @@ -136,7 +136,7 @@ PybindDefineRegisterer g_pybind_define_f_Client("ObjectClient", PRIORITY_LOW, [] .accessKey = accessKey, .secretKey = secretKey, .tenantId = tenantId, - .enableCrossNodeConnection = enableCrossNodeConnection }; + .enableCrossNodeConnection = false }; return std::make_unique(connectOpts); })) diff --git a/tests/ut/CMakeLists.txt b/tests/ut/CMakeLists.txt index e5eeeb5..2710012 100644 --- a/tests/ut/CMakeLists.txt +++ b/tests/ut/CMakeLists.txt @@ -62,5 +62,5 @@ add_datasystem_test(ds_ut TEST_ENVIRONMENTS ${TEST_ENVIRONMENT}) add_datasystem_test(ds_ut_object TEST_ENVIRONMENTS ${TEST_ENVIRONMENT}) add_executable(flags_ut "${CMAKE_CURRENT_SOURCE_DIR}/common/flags/flags_test.cpp") -target_link_libraries(flags_ut ds_flags GTest::gtest GTest::gmock) +target_link_libraries(flags_ut ds_flags GTest::gtest GTest::gmock re2::re2) add_datasystem_test(flags_ut) -- Gitee