diff --git a/README.md b/README.md index dcd6d660cd717150fd5540ecb282bf2886e9b85a..7db47eb06ad69b8496b0692762df76e806079150 100644 --- a/README.md +++ b/README.md @@ -1,48 +1,183 @@ -# openMind Hub Client +

-## 简介 +

+ + Badge + + + Visit our community + + + + +

-openMind Hub Client可以帮助您在不离开开发环境的情况下与社区进行交互。您可以轻松创建和管理仓库,下载和上传文件以及从模型库获取有用的模型和数据集元数据。 +--- -## 安装 +## 📝 简介 -关于openMind Hub Client的安装步骤,推荐用户参考[《安装》](./docs/zh/install.md)文档,以确保顺利并正确地完成安装过程。 +openMind Hub Client 可以帮助您在不离开开发环境的情况下与社区进行交互。您可以轻松创建和管理仓库,下载和上传文件以及从模型库获取有用的模型和数据集元数据。 -## 下载文件 +**为什么使用 openMind Hub Client?** -例如,下载[t5_small](https://modelers.cn/models/PyTorch-NPU/t5_small/)模型配置文件: +openMind Hub Client 提供了统一的SDK,为用户提供了与多个社区交互的良好体验。 + +使您可以在不离开开发环境,下载与上传文件时,拥有良好的性能与操作体验。 + +**openMind Hub Client目前支持的关键特性**: + +- [下载文件](https://gitee.com/ascend/openmind-hub/tree/v0.9/docs/zh/basic_tutorial/download.md) +- [上传文件](https://gitee.com/ascend/openmind-hub/tree/v0.9/docs/zh/basic_tutorial/upload.md) +- [文件管理](https://gitee.com/ascend/openmind-hub/tree/v0.9/docs/zh/api_reference/om_file_system.md) +- [与多社区交互](https://gitee.com/ascend/openmind-hub/tree/v0.9/docs/zh/basic_tutorial/third-party_platform.md) +- [仓库卡片](https://gitee.com/ascend/openmind-hub/tree/v0.9/docs/zh/api_reference/repocard.md) + +--- + +## 🚀 更新日志 + +2024/11: openMind Hub Client v0.9.0版本发布,新增支持Gitee AI、HuggingFace社区。 + +--- + +## 🛠️ 安装 + +### 版本配套 + +| openmind-hub版本 | Python版本 | openmind版本 | +|:--------------:|:--------:|:----------:| +| 0.9 | 3.8-3.10 | 0.9 | + +使用pip方式安装openMind Hub Client,可根据实际需求选择对应命令进行安装。 + +- 默认安装方式,可与魔乐社区进行交互。 + + ```shell + pip install openmind_hub + ``` + +- 安装所有对接的第三方社区模块,可与所有已对接的第三方社区进行交互,详见[第三方社区对接](https://gitee.com/ascend/openmind-hub/tree/v0.9/docs/zh/basic_tutorial/third-party_platform.md)。 + + ```shell + pip install openmind_hub[all] + ``` + +- 安装指定社区模块,可与魔乐或指定社区进行交互。 + + ```shell + pip install openmind_hub[openi] + pip install openmind_hub[huggingface] + ... + ``` + +源代码安装: + +```shell +git clone https://gitee.com/Ascend/openmind-hub.git + +cd openmind-hub + +pip install -e . +``` + +openMind Hub Client的安装步骤,推荐用户参考[安装openmind Hub Client](https://gitee.com/ascend/openmind-hub/tree/v0.9/docs/zh/install.md)文档,以确保顺利并正确地完成安装过程。 + +--- + +## 🧰 快速上手 + +### 获取token + +在进行需要鉴权的操作,如上传文件、创建仓库前等,请先于交互的社区中获取token,如[魔乐社区获取token](https://modelers.cn/my/tokens)。 + +### 下载文件 + +- 下载单个文件 ```py from openmind_hub import om_hub_download -om_hub_download(repo_id="PyTorch-NPU/t5_small", filename="config.json") +om_hub_download(repo_id="PyTorch-NPU/t5_small", filename="README.md") ``` -详见[《下载指南》](./docs/zh/basic_tutorial/download.md)。 +- 下载整个仓库 + +```py +from openmind_hub import snapshot_download + +snapshot_download("PyTorch-NPU/t5_small") +``` + +下载细节请见[下载文件](https://gitee.com/ascend/openmind-hub/tree/v0.9/docs/zh/basic_tutorial/download.md)。 + +默认缓存路径为 ~/.cache/openmind/hub, 缓存机制详解请见[缓存系统](https://gitee.com/ascend/openmind-hub/tree/v0.9/docs/zh/basic_tutorial/cache.md)。 -## 访问令牌 +### 创建仓库 -访问私有仓库资源、创建仓库和上传文件等场景都需要使用访问令牌(即token)才能与社区进行交互。请[创建访问令牌](https://modelers.cn/my/tokens)并妥善保存,令牌内容仅会在创建时显示。 +```py +from openmind_hub import create_repo + +create_repo(repo_id="Me/repo_name", token="My_token") +``` -## 上传文件 +### 上传文件 -使用`upload_folder`为您的仓库上传文件,示例如下: +- 上传单个文件 + +```py +from openmind_hub import upload_file + +upload_file( + path_or_fileobj="/home/lysandre/dummy-test/README.md", + path_in_repo="README.md", + repo_id="PyTorch-NPU/t5_small", + token="My_token", +) +``` + +- 上传整个文件夹 ```py from openmind_hub import upload_folder + upload_folder( - repo_id="owner/repo", - folder_path="./folder_to_upload", - token="xxx", + folder_path="/path/to/local", + repo_id="PyTorch-NPU/t5_small", + token="My_token", ) ``` -+ `token`:对目标仓库具有可写权限的访问令牌,必选。 -+ `repo_id`:文件要上传到的仓库,必选。 -+ `folder_path`:要上传目录的绝对路径或相对路径,上传的内容不包含该目录本身,必选。支持字符串或Path类型,如:`"./folder"`或`Path("./folder")`。 +更多细节请见[上传文件](https://gitee.com/ascend/openmind-hub/tree/v0.9/docs/zh/basic_tutorial/upload.md)。 + +--- + +## 📚 贡献 + +1. 在上传PR之前,请确保所有测试都通过。首先在本地运行如下命令。 + +```shell +# The scripts below run on system default python version by default. If you want to use other python version, set the env +# PY_VERSION. For example, `PY_VERSION=3.8 ./ci/lint.sh` +# Lint check +./ci/lint.sh +# Unit test +./ci/unit_test.sh +# Functional test, Please generate the HUB_TOKEN from openmind by yourself and use it privatelly. +HUB_TOKEN=your_hub_token ./ci/functional_test.sh +``` + +2. 当您推送或更新PR(Pull Request)后,系统将自动触发CI(持续集成)构建和测试流程。若所有CI构建和测试均顺利通过,`ci-success`标记将自动添加到您的PR中。然而,若出现CI故障,您可以点击CI日志链接查看失败原因,并在本地进行必要的修复。一旦您完成了修复并希望重新运行CI作业,只需在PR中留下评论`/recheck`即可。 + +--- + +## 🔒 安全声明 + +为保障使用过程安全,推荐用户参考[安全声明](https://gitee.com/ascend/openmind-hub/tree/v0.9/security_statement.md)了解相关安全信息,进行必要的安全加固。 + +--- -详见[《上传文件》](./docs/zh/basic_tutorial/upload.md)。 +## 📖 许可证 +MulanPSL v2 +openMind Library使用木兰宽松许可证第2版(MulanPSL v2),详见[License](http://license.coscl.org.cn/MulanPSL2)文件。 -## 安全声明 -为保障使用过程安全,推荐用户参考[《安全声明》](./security_statement.md)了解相关安全信息,进行必要的安全加固。 \ No newline at end of file diff --git a/docs/zh/install.md b/docs/zh/install.md index fde53d8ad108a513333296384bf05d496311e0dd..3a00d98c08091e43c7e863034d410be5f6b92a47 100644 --- a/docs/zh/install.md +++ b/docs/zh/install.md @@ -44,7 +44,7 @@ ```shell pip install openmind_hub[openi] - pip install openmind_hub[huggingface_hub] + pip install openmind_hub[huggingface] ``` ## 验证安装 diff --git a/sources/images/logo.png b/sources/images/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..17af241c429f6bf81e49869ab1c9f46f3c6cce23 Binary files /dev/null and b/sources/images/logo.png differ