diff --git a/docs/en/developer_tutorial/figures/cacert_download.png b/docs/en/developer_tutorial/figures/cacert_download.png new file mode 100644 index 0000000000000000000000000000000000000000..c67a10f0f60680bbb5d19223647cd87901396068 Binary files /dev/null and b/docs/en/developer_tutorial/figures/cacert_download.png differ diff --git a/docs/en/developer_tutorial/figures/requests.png b/docs/en/developer_tutorial/figures/requests.png new file mode 100644 index 0000000000000000000000000000000000000000..1214d06e2718d93ac4e01fd7418a5704c8dd0aa1 Binary files /dev/null and b/docs/en/developer_tutorial/figures/requests.png differ diff --git a/docs/en/developer_tutorial/trouble_shooting.md b/docs/en/developer_tutorial/trouble_shooting.md index 05758b8cb36cd604bfa424c45f32f1e32b250a70..e6c05df167b5ee298e4801c9103c47226d229461 100644 --- a/docs/en/developer_tutorial/trouble_shooting.md +++ b/docs/en/developer_tutorial/trouble_shooting.md @@ -2,64 +2,107 @@ When using openMind Hub Client, you may encounter some problems. This document collects some common problems and their solutions. We will continue to update this document to help you troubleshoot faults. -## Download Interruption +## Certificate Verification Failure: CERTIFICATE_VERIFY_FAILED -If the download of a large file is interrupted due to network or other factors, you can resume the download from the point where it is interrupted. +There are multiple causes for certificate verification failures. The following lists the solutions to different errors. -```python -from openmind_hub import om_hub_download +Solution 1: If the Python root CA certificate does not match the requests library version, use either of the following methods to locate the fault. -om_hub_download(repo_id="owner/repo", filename="file_in_repo", resume_download=True) -``` + ```shell + SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1108)') + ``` -## Certificate Verification Failure ++ Modifying the version of the requests library: -If the following error occurs when a request is sent to an openMind model repository, you need to manually configure the openMind certificate: + ```shell + # Check the version of the requests library. + pip show requests + + # If the requests version is not 2.32.2, install the 2.32.2 version. + pip uninstall requests + pip install requests==2.32.2 + ``` -```commandline -requests.exceptions.SSLError: HTTPSConnectionPool(host='xxx', port=4434): Max retries exceeded with url: /api/v1/file/xxxx (Caused by SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate (_ssl.c:1131)'))) -``` ++ Updating the Python root CA certificate: + + 1. To obtain the local certificate path, run `pip install certifi` or `pip install certifi --upgrade` to install or upgrade the cretifi library. + + ```python + import certifi + + print(certifi.where()) + # -> /path/to/certifi/cacert.pem + ``` + + 2. Obtain the latest certificate from and download the cacert.pem file. + + ![img.png](figures/cacert_download.png) + + 3. Use the new cacert.pem certificate to replace the original one. Back up the certificate before the replacement. + +Solution 2: Manually configure the certificate of the Modelers community. + + ```shell + SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate (_ssl.c:1131)') + ``` -1. Download the certificates from the openMind website. The following describes the procedure for downloading the certificate using Google Chrome. The procedure for downloading the certificate using other browsers is similar. +1. Download the certificate from Modelers Community. The following describes the procedure for downloading the certificate using Google Chrome. The procedure for downloading the certificate using other browsers is similar. In Windows, double-click the certificate to install it. In Linux, refer to the following procedure. - ![img.png](figures/certificate_download_1.png) - ![img_1.png](figures/certificate_download_2.png) - ![img_2.png](figures/certificate_download_3.png) + ![img.png](figures/certificate download 1.png) ![img_1.png](figures/certificate download 2.png) + + ![img_2.png](figures/certificate download 3.png) -2. Move the downloaded certificate to the `/usr/local/share/ca-certificates/` directory (Linux). -3. Run the `update-ca-certificates` command. -4. Add environment variables. Edit the **~/.bashrc** (for Bash shell) or **~/.zshrc** (for Zsh shell) file, add `export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt`, and restart the terminal or run the `source ~/.bashrc` command for the modification to take effect. +2. Move the downloaded certificate to the `/usr/local/share/ca-certificates/` directory. +3. Run `update-ca-certificates`. +4. Add an environment variable. Edit the **~/.bashrc** (for Bash shell) or **~/.zshrc** (for Zsh shell) file, add `export REQUESTS_CA_BUNDLE=/etc/ssl/certs/ca-certificates.crt`, and restart the terminal or run `source ~/.bashrc` for the modification to take effect. If the modification does not take effect, skip certificate verification. This method is used only for tests or emergencies. -1. Run the `pip show requests` command to find the path of the requests library, for example, ![img_2.png](figures/verify.png) -2. Run the `vi /requests/adapters.py` to edit the file. +1. Run `pip show requests` to find the path of the requests library, for example: + + ![img_2.png](figures/requests.png) + +2. Run `vi /requests/adapters.py` to edit the file. 3. Enter `:553` in the command mode to go to line 553. Add `verify=False` to the send() method to skip certificate verification. -## Large File Upload Failure +## Large Git File Upload Failure -```commandline +```shell LFS: Client error &{%!!(string=https) %!!(string=) %!!xxxxxxxxxx %!!(striing=)}s(MISSING) from HTTP 413 ``` -If error 413 occurs when you use Git to upload a large file, use Git LFS to upload the large file instead. For details, see [Uploading Files](../basic_tutorial/upload.md#Uploading Files Using Git). +or + +```shell +LFS: Client error https://modelers.cn/user/repo.git/info/lfs/objects/xxxxxxxxxxxx from HTTP 413 +``` + +When you use **git lfs** to upload files, the size of each file cannot exceed 5 GB. Use `upload_file` or `upload_folder` to upload files. For details, see [Uploading Files](../basic_tutorial/upload.md). ## License Error in README -```commandline +```shell remote: Sorry, your push was rejected during YAML metadata verification: remote: - Error: license must be one of (apache-2.0 mit openrail bigscience-openrail-m creativeml-openrail-m bigscience-bloom-rail-1.0 bigcode-openrail-m afl-3.0 artistic-2.0 bsl-1.0 bsd bsd-2-clause bsd-3-clause bsd-3-clause-clear c-uda cc cc0-1.0 cc-by-2.0 cc-by-2.5 cc-by-3.0 cc-by-4.0 cc-by-sa-3.0 cc-by-sa-4.0 cc-by-nc-2.0 cc-by-nc-3.0 cc-by-nc-4.0 cc-by-nd-4.0 cc-by-nc-nd-3.0 cc-by-nc-nd-4.0 cc-by-nc-sa-2.0 cc-by-nc-sa-3.0 cc-by-nc-sa-4.0 cdla-sharing-1.0 cdla-permissive-1.0 cdla-permissive-2.0 wtfpl ecl-2.0 epl-1.0 epl-2.0 etalab-2.0 eupl-1.1 agpl-3.0 gfdl gpl gpl-2.0 gpl-3.0 lgpl lgpl-2.1 lgpl-3.0 isc lppl-1.3c ms-pl mpl-2.0 odc-by odbl openrail++ osl-3.0 postgresql ofl-1.1 ncsa unlicense zlib pddl lgpl-lr deepfloyd-if-license llama2 gemma unknown llama3 other) -To https://telecom.openmind.cn/xxx/xx.git +To https://modelers.cn/xxx/xx.git ! [remote rejected] main -> main (pre-receive hook declined) -error: failed to push some refs to 'https://telecom.openmind.cn/xxx/xx.git' +error: failed to push some refs to 'https://modelers.cn/xxx/xx.git' ``` Metadata validity is checked in the **REAMDME.md** file in the repository to which files are uploaded. -## Upload Error in Linux +## Upload Failure: NameResolutionError -```commandline -requests.exceptions.ConnectionError: HTTPSConnectionPool(host='xxx',port=443):Max retries exceeded url: /api/v1/file/xxx/xxx/pre_upload...(Caused by NameResolutionError(":Failed to resolve 'telecom.openmind.cn'([Error -3] Temporary failure in name resolution)")) +```shell +requests.exceptions.ConnectionError: HTTPSConnectionPool(host='xxx',port=443):Max retries exceeded url: /api/v1/file/xxx/xxx/pre_upload...(Caused by NameResolutionError(":Failed to resolve 'modelers.cn'([Error -3] Temporary failure in name resolution)")) ``` The domain name is not resolved correctly. Try again later. + +## Download Failure: ChunkedEncodingError + +```shell +requests.exceptions.ChunkedEncodingError: ('Connection broken: IncompleteRead(1247345764 bytes read, 13764675765 more expected)' +``` + +The connection between the client and server is unstable. As a result, data reading is interrupted. Try again, and the download will be resumed. If the number of bytes in the error message remains unchanged after the retry, add `force_download=True` or manually delete the file from the cache and try again. diff --git a/docs/zh/developer_tutorial/trouble_shooting.md b/docs/zh/developer_tutorial/trouble_shooting.md index 03ed21eb18237b17d436f37cbc2b98eb805d463b..19b3612ad3afd3cac6925510bdd4b802e6b00fc0 100644 --- a/docs/zh/developer_tutorial/trouble_shooting.md +++ b/docs/zh/developer_tutorial/trouble_shooting.md @@ -8,13 +8,13 @@ 第一种：Python根CA证书与requests库版本不匹配，请按以下两种方案排查。 - ```commandline + ```shell SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1108)') ``` + 修改requests库的版本： - ```commandline + ```shell # 查看requests库的版本 pip show requests @@ -42,7 +42,7 @@ 第二种：需手动配置魔乐社区的证书。 - ```commandline + ```shell SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: self signed certificate (_ssl.c:1131)') ``` @@ -67,13 +67,13 @@ ## git大文件上传失败 -```commandline +```shell LFS: Client error &{%!!(string=https) %!!(string=) %!!xxxxxxxxxx %!!(striing=)}s(MISSING) from HTTP 413 ``` 或 -```commandline +```shell LFS: Client error https://modelers.cn/user/repo.git/info/lfs/objects/xxxxxxxxxxxx from HTTP 413 ``` @@ -81,7 +81,7 @@ LFS: Client error https://modelers.cn/user/repo.git/info/lfs/objects/xxxxxxxxxxx ## README.md中license错误 -```commandline +```shell remote: Sorry, your push was rejected during YAML metadata verification: remote: - Error: license must be one of (apache-2.0 mit openrail bigscience-openrail-m creativeml-openrail-m bigscience-bloom-rail-1.0 bigcode-openrail-m afl-3.0 artistic-2.0 bsl-1.0 bsd bsd-2-clause bsd-3-clause bsd-3-clause-clear c-uda cc cc0-1.0 cc-by-2.0 cc-by-2.5 cc-by-3.0 cc-by-4.0 cc-by-sa-3.0 cc-by-sa-4.0 cc-by-nc-2.0 cc-by-nc-3.0 cc-by-nc-4.0 cc-by-nd-4.0 cc-by-nc-nd-3.0 cc-by-nc-nd-4.0 cc-by-nc-sa-2.0 cc-by-nc-sa-3.0 cc-by-nc-sa-4.0 cdla-sharing-1.0 cdla-permissive-1.0 cdla-permissive-2.0 wtfpl ecl-2.0 epl-1.0 epl-2.0 etalab-2.0 eupl-1.1 agpl-3.0 gfdl gpl gpl-2.0 gpl-3.0 lgpl lgpl-2.1 lgpl-3.0 isc lppl-1.3c ms-pl mpl-2.0 odc-by odbl openrail++ osl-3.0 postgresql ofl-1.1 ncsa unlicense zlib pddl lgpl-lr deepfloyd-if-license llama2 gemma unknown llama3 other) To https://modelers.cn/xxx/xx.git @@ -93,7 +93,7 @@ error: failed to push some refs to 'https://modelers.cn/xxx/xx.git' ## 上传报错：NameResolutionError -```commandline +```shell requests.exceptions.ConnectionError: HTTPSConnectionPool(host='xxx',port=443):Max retries exceeded url: /api/v1/file/xxx/xxx/pre_upload...(Caused by NameResolutionError(":Failed to resolve 'modelers.cn'([Error -3] Temporary failure in name resolution)")) ``` @@ -101,7 +101,7 @@ requests.exceptions.ConnectionError: HTTPSConnectionPool(host='xxx',port=443):Ma ## 下载报错：ChunkedEncodingError -```commandline +```shell requests.exceptions.ChunkedEncodingError: ('Connection broken: IncompleteRead(1247345764 bytes read, 13764675765 more expected)' ```