[WIP] docs(docs/npu & i18n/en/npu): 对npu部分新添翻译和完善 #53
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
Co-authored-by: sourcery-ai[bot] <58596630+sourcery-ai[bot]@users.noreply.github.com>
Reviewer's GuideThis PR introduces the English translation of the NPU documentation by creating a structured set of MDX and markdown files under the i18n/en directory, using frontmatter and Docusaurus components (Tabs/TabItem) to guide users through environment setup, model compilation, inference tutorials, and common troubleshooting. Flow diagram for troubleshooting excessive NPU inference timeflowchart TD
A[Run inference program] --> B{Long execution time?}
B -- No --> C[Normal inference]
B -- Yes --> D[Check if JIT compilation occurs every run]
D --> E[Use shl.hhb.bm as input to hhb_runtime]
E --> F[Modify main.cpp to use optimized model]
F --> G[Run inference again]
G --> B
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey @LeeJc02 - I've reviewed your changes - here's some feedback:
- Several of the new pages and category folders have empty
_category_.jsonfiles—please fill in at leastlabel(and optionallyposition) so that the sidebar hierarchy renders correctly. - Multiple docs are all set to
sidebar_position: 1—consider auditing and adjusting those numbers to ensure the sections appear in the intended order.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- Several of the new pages and category folders have empty `_category_.json` files—please fill in at least `label` (and optionally `position`) so that the sidebar hierarchy renders correctly.
- Multiple docs are all set to `sidebar_position: 1`—consider auditing and adjusting those numbers to ensure the sections appear in the intended order.
## Individual Comments
### Comment 1
<location> `i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/env.mdx:53` </location>
<code_context>
+Install the SHL library using `pip` within the virtual environment:
+
+```shell-session
+(.venv) debian@revyos-lpi4a:~/npu$ pip3 install shl-python -i https://pypi.tuna.tsinghua.edu.cn/simple
+...
+Successfully installed shl-python-3.2.2
</code_context>
<issue_to_address>
Explicitly mention the importance of matching shl-python version to board compatibility.
Since the install command fetches the latest version, which may be incompatible with some examples, please specify the compatible shl-python version (e.g., 2.6.17) or add a note to prevent confusion and runtime errors.
</issue_to_address>
<suggested_fix>
<<<<<<< SEARCH
Install the SHL library using `pip` within the virtual environment:
```shell-session
(.venv) debian@revyos-lpi4a:~/npu$ pip3 install shl-python -i https://pypi.tuna.tsinghua.edu.cn/simple
...
Successfully installed shl-python-3.2.2
```
=======
Install the SHL library using `pip` within the virtual environment:
:::caution[Version Compatibility]
The `shl-python` package is updated frequently, and the latest version may not be compatible with all boards or example code.
**It is important to install a version of `shl-python` that matches your board and the examples you are following.**
For example, for the LPI4A board, version `2.6.17` is known to be compatible with most provided examples.
Check your board documentation or example requirements for the recommended version.
:::
To install a specific compatible version (e.g., `2.6.17`):
```shell-session
(.venv) debian@revyos-lpi4a:~/npu$ pip3 install shl-python==2.6.17 -i https://pypi.tuna.tsinghua.edu.cn/simple
...
Successfully installed shl-python-2.6.17
```
If you want to install the latest version (not recommended unless you have verified compatibility):
```shell-session
(.venv) debian@revyos-lpi4a:~/npu$ pip3 install shl-python -i https://pypi.tuna.tsinghua.edu.cn/simple
...
Successfully installed shl-python-x.x.x
```
>>>>>>> REPLACE
</suggested_fix>
### Comment 2
<location> `i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/env.mdx:176` </location>
<code_context>
+After loading the NPU driver, the device `/dev/vha0` may require permission adjustment for user access. For convenience, set the device permission to 0666 (read/write for all users):
+
+```shell-session
+$ sudo chmod 0666 /dev/vha0 # Set device permission to 0666
+```
+
</code_context>
<issue_to_address>
Setting device permissions to 0666 may introduce security risks.
Consider adding a warning about the security implications and suggest using udev rules for safer permission management in production or multi-user setups.
</issue_to_address>
<suggested_fix>
<<<<<<< SEARCH
After loading the NPU driver, the device `/dev/vha0` may require permission adjustment for user access. For convenience, set the device permission to 0666 (read/write for all users):
```shell-session
+$ sudo chmod 0666 /dev/vha0 # Set device permission to 0666
+```
+
=======
After loading the NPU driver, the device `/dev/vha0` may require permission adjustment for user access.
> **Warning:**
> Setting device permissions to `0666` (read/write for all users) can introduce security risks, especially in production or multi-user environments. This allows any user or process on the system to access the device, which may not be desirable.
>
> For safer and more maintainable permission management, consider creating a [udev rule](https://wiki.archlinux.org/title/Udev#About_udev_rules) to set appropriate permissions or group ownership for `/dev/vha0`. This approach is recommended for production or multi-user setups.
For quick testing or development on a single-user system, you can temporarily set the device permission to `0666`:
```shell-session
$ sudo chmod 0666 /dev/vha0 # Set device permission to 0666 (not recommended for production)
```
For example, a simple udev rule to set group ownership and permissions might look like:
```shell
# /etc/udev/rules.d/99-vha.rules
SUBSYSTEM=="vha", MODE="0660", GROUP="video"
```
After creating the rule, reload udev rules and replug the device:
```shell-session
$ sudo udevadm control --reload-rules
$ sudo udevadm trigger
```
>>>>>>> REPLACE
</suggested_fix>
### Comment 3
<location> `i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/image-classification/resnet50.mdx:73` </location>
<code_context>
+ --data-scale 0.017 --data-mean "124 117 104" \
+ --board c920 --postprocess save_and_top5 \
+ --input-name "data" --output-name "resnetv17_dense0_fwd" \
+ --input-shape "1 3 224 224" --calibrate-dataset persian_cat.jpg\
+ --quantization-scheme float16
+```
</code_context>
<issue_to_address>
Using a single image for calibration may reduce quantization accuracy.
Using only persian_cat.jpg for calibration may not provide sufficient data for accurate quantization. Consider using a more representative dataset or document the accuracy trade-off if this is intentional.
</issue_to_address>
<suggested_fix>
<<<<<<< SEARCH
$ hhb -D --model-file resnet50-v1-7.onnx \
--data-scale 0.017 --data-mean "124 117 104" \
--board c920 --postprocess save_and_top5 \
--input-name "data" --output-name "resnetv17_dense0_fwd" \
--input-shape "1 3 224 224" --calibrate-dataset persian_cat.jpg\
--quantization-scheme float16
```
=======
$ hhb -D --model-file resnet50-v1-7.onnx \
--data-scale 0.017 --data-mean "124 117 104" \
--board c920 --postprocess save_and_top5 \
--input-name "data" --output-name "resnetv17_dense0_fwd" \
--input-shape "1 3 224 224" --calibrate-dataset path/to/calibration_dataset/ \
--quantization-scheme float16
```
> **Note:**
> For best quantization accuracy, use a representative calibration dataset (e.g., a directory of diverse images) instead of a single image.
> Using only `persian_cat.jpg` for calibration may reduce quantization accuracy. If you intentionally use a single image, document the expected accuracy trade-off.
>>>>>>> REPLACE
</suggested_fix>
### Comment 4
<location> `i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/image-classification/resnet50.mdx:127` </location>
<code_context>
+```shell-session
+$ export OPENCV_DIR=../../modules/opencv/ # Set the path to OpenCV
+$ riscv64-unknown-linux-gnu-g++ main.cpp -I${OPENCV_DIR}/include/opencv4 -L${OPENCV_DIR}/lib \
+ -lopencv_imgproc -lopencv_imgcodecs -L${OPENCV_DIR}/lib/opencv4/3rdparty/ \
+ -llibjpeg-turbo -llibwebp -llibpng -llibtiff -llibopenjp2 \
+ -lopencv_core -ldl -lpthread -lrt -lzlib -lcsi_cv -latomic -static \
+ -o resnet50_example # Compile the program
+```
</code_context>
<issue_to_address>
Consider clarifying the need for static linking and all listed libraries.
-static and explicit library flags may not be required everywhere and could cause build failures if static libraries are unavailable. Suggest noting that these flags should be tailored to the user's environment.
</issue_to_address>
<suggested_fix>
<<<<<<< SEARCH
```shell-session
$ export OPENCV_DIR=../../modules/opencv/ # Set the path to OpenCV
$ riscv64-unknown-linux-gnu-g++ main.cpp -I${OPENCV_DIR}/include/opencv4 -L${OPENCV_DIR}/lib \
-lopencv_imgproc -lopencv_imgcodecs -L${OPENCV_DIR}/lib/opencv4/3rdparty/ \
-llibjpeg-turbo -llibwebp -llibpng -llibtiff -llibopenjp2 \
-lopencv_core -ldl -lpthread -lrt -lzlib -lcsi_cv -latomic -static \
-o resnet50_example # Compile the program
```
=======
```shell-session
$ export OPENCV_DIR=../../modules/opencv/ # Set the path to OpenCV
$ riscv64-unknown-linux-gnu-g++ main.cpp -I${OPENCV_DIR}/include/opencv4 -L${OPENCV_DIR}/lib \
-lopencv_imgproc -lopencv_imgcodecs -lopencv_core -ldl -lpthread -lrt -lcsi_cv -o resnet50_example # Compile the program
```
> **Note:**
> The example above uses a number of explicit library flags and the `-static` option for static linking. These may not be required or available in all environments, and static libraries (such as `libjpeg-turbo`, `libwebp`, `libpng`, `libtiff`, `libopenjp2`, `zlib`, etc.) may not be present or may have different names/locations.
> Adjust the library flags and linking options as needed for your system. If you encounter build errors related to missing libraries, try removing unnecessary flags or use dynamic linking by omitting `-static`.
>>>>>>> REPLACE
</suggested_fix>
### Comment 5
<location> `i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/image-classification/resnet50.mdx:166` </location>
<code_context>
+
+Ensure `LD_LIBRARY_PATH` is correctly set. If the issue persists, run `pip show shl-python` to check the version.
+
+If the version is `3.x.x`, it is too high. The Resnet50 program requires `shl-python` version 2.x. Downgrade with:
+
+```shell-session
</code_context>
<issue_to_address>
Suggest proactively pinning shl-python version in earlier install steps.
Specify the required shl-python version (e.g., 2.6.17) in the installation steps to prevent version mismatch issues.
</issue_to_address>
<suggested_fix>
<<<<<<< SEARCH
Ensure `LD_LIBRARY_PATH` is correctly set. If the issue persists, run `pip show shl-python` to check the version.
If the version is `3.x.x`, it is too high. The Resnet50 program requires `shl-python` version 2.x. Downgrade with:
```shell-session
=======
Ensure `LD_LIBRARY_PATH` is correctly set. If the issue persists, run `pip show shl-python` to check the version.
If the version is `3.x.x`, it is too high. The Resnet50 program requires `shl-python` version 2.x.
**To avoid version mismatch issues, proactively install the required version of `shl-python` (e.g., 2.6.17) before proceeding:**
```shell-session
pip install shl-python==2.6.17
```
If you have already installed a different version, downgrade with:
```shell-session
>>>>>>> REPLACE
</suggested_fix>
### Comment 6
<location> `i18n/en/docusaurus-plugin-content-docs/current/npu/lpi4a/image-classification/resnet50.mdx:180` </location>
<code_context>
+FATAL: could not open driver '/dev/vha0': Permission denied
+```
+
+Check if the current user has read/write permissions for `/dev/vha0`. Set permissions with:
+
+```shell-session
</code_context>
<issue_to_address>
Setting device permissions to 0666 should be accompanied by a security warning.
World read/write permissions can pose security risks. Recommend adding a warning and suggesting udev rules for safer permission management.
Suggested implementation:
```
Check if the current user has read/write permissions for `/dev/vha0`.
:::danger Security Warning
Setting device permissions to `0666` (world read/write) can pose significant security risks, as it allows any user or process on the system to access the device. This may expose the device to unintended or malicious use. **It is recommended to use more restrictive permissions or configure access for specific user groups.**
:::
Set permissions with:
```shell-session
```
```
Set permissions with:
```shell-session
sudo chmod 0666 /dev/vha0
```
Alternatively, for a safer and more permanent solution, consider creating a [udev rule](https://wiki.archlinux.org/title/Udev#About_udev_rules) to manage device permissions for a specific user group:
```shell-session
# Create a group for NPU access if it doesn't exist
sudo groupadd npuusers
# Add your user to the group
sudo usermod -aG npuusers $USER
# Create a udev rule (replace 'vha0' with your device name if different)
echo 'KERNEL=="vha0", GROUP="npuusers", MODE="0660"' | sudo tee /etc/udev/rules.d/99-npu.rules
# Reload udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger
```
This approach restricts device access to users in the `npuusers` group, improving security.
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+173
to
+178
| After loading the NPU driver, the device `/dev/vha0` may require permission adjustment for user access. For convenience, set the device permission to 0666 (read/write for all users): | ||
|
|
||
| ```shell-session | ||
| $ sudo chmod 0666 /dev/vha0 # Set device permission to 0666 | ||
| ``` | ||
|
|
There was a problem hiding this comment.
🚨 suggestion (security): Setting device permissions to 0666 may introduce security risks.
Consider adding a warning about the security implications and suggest using udev rules for safer permission management in production or multi-user setups.
Suggested change
| After loading the NPU driver, the device `/dev/vha0` may require permission adjustment for user access. For convenience, set the device permission to 0666 (read/write for all users): | |
| ```shell-session | |
| $ sudo chmod 0666 /dev/vha0 # Set device permission to 0666 | |
| ``` | |
| After loading the NPU driver, the device `/dev/vha0` may require permission adjustment for user access. | |
| > **Warning:** | |
| > Setting device permissions to `0666` (read/write for all users) can introduce security risks, especially in production or multi-user environments. This allows any user or process on the system to access the device, which may not be desirable. | |
| > | |
| > For safer and more maintainable permission management, consider creating a [udev rule](https://wiki.archlinux.org/title/Udev#About_udev_rules) to set appropriate permissions or group ownership for `/dev/vha0`. This approach is recommended for production or multi-user setups. | |
| For quick testing or development on a single-user system, you can temporarily set the device permission to `0666`: | |
| ```shell-session | |
| $ sudo chmod 0666 /dev/vha0 # Set device permission to 0666 (not recommended for production) |
For example, a simple udev rule to set group ownership and permissions might look like:
# /etc/udev/rules.d/99-vha.rules
SUBSYSTEM=="vha", MODE="0660", GROUP="video"After creating the rule, reload udev rules and replug the device:
$ sudo udevadm control --reload-rules
$ sudo udevadm trigger
Comment on lines
+69
to
+75
| $ hhb -D --model-file resnet50-v1-7.onnx \ | ||
| --data-scale 0.017 --data-mean "124 117 104" \ | ||
| --board c920 --postprocess save_and_top5 \ | ||
| --input-name "data" --output-name "resnetv17_dense0_fwd" \ | ||
| --input-shape "1 3 224 224" --calibrate-dataset persian_cat.jpg\ | ||
| --quantization-scheme float16 | ||
| ``` |
There was a problem hiding this comment.
suggestion: Using a single image for calibration may reduce quantization accuracy.
Using only persian_cat.jpg for calibration may not provide sufficient data for accurate quantization. Consider using a more representative dataset or document the accuracy trade-off if this is intentional.
Suggested change
| $ hhb -D --model-file resnet50-v1-7.onnx \ | |
| --data-scale 0.017 --data-mean "124 117 104" \ | |
| --board c920 --postprocess save_and_top5 \ | |
| --input-name "data" --output-name "resnetv17_dense0_fwd" \ | |
| --input-shape "1 3 224 224" --calibrate-dataset persian_cat.jpg\ | |
| --quantization-scheme float16 | |
| ``` | |
| $ hhb -D --model-file resnet50-v1-7.onnx \ | |
| --data-scale 0.017 --data-mean "124 117 104" \ | |
| --board c920 --postprocess save_and_top5 \ | |
| --input-name "data" --output-name "resnetv17_dense0_fwd" \ | |
| --input-shape "1 3 224 224" --calibrate-dataset path/to/calibration_dataset/ \ | |
| --quantization-scheme float16 |
Note:
For best quantization accuracy, use a representative calibration dataset (e.g., a directory of diverse images) instead of a single image.
Using onlypersian_cat.jpgfor calibration may reduce quantization accuracy. If you intentionally use a single image, document the expected accuracy trade-off.
Comment on lines
+124
to
+131
| ```shell-session | ||
| $ export OPENCV_DIR=../../modules/opencv/ # Set the path to OpenCV | ||
| $ riscv64-unknown-linux-gnu-g++ main.cpp -I${OPENCV_DIR}/include/opencv4 -L${OPENCV_DIR}/lib \ | ||
| -lopencv_imgproc -lopencv_imgcodecs -L${OPENCV_DIR}/lib/opencv4/3rdparty/ \ | ||
| -llibjpeg-turbo -llibwebp -llibpng -llibtiff -llibopenjp2 \ | ||
| -lopencv_core -ldl -lpthread -lrt -lzlib -lcsi_cv -latomic -static \ | ||
| -o resnet50_example # Compile the program | ||
| ``` |
There was a problem hiding this comment.
suggestion: Consider clarifying the need for static linking and all listed libraries.
-static and explicit library flags may not be required everywhere and could cause build failures if static libraries are unavailable. Suggest noting that these flags should be tailored to the user's environment.
Suggested change
| ```shell-session | |
| $ export OPENCV_DIR=../../modules/opencv/ # Set the path to OpenCV | |
| $ riscv64-unknown-linux-gnu-g++ main.cpp -I${OPENCV_DIR}/include/opencv4 -L${OPENCV_DIR}/lib \ | |
| -lopencv_imgproc -lopencv_imgcodecs -L${OPENCV_DIR}/lib/opencv4/3rdparty/ \ | |
| -llibjpeg-turbo -llibwebp -llibpng -llibtiff -llibopenjp2 \ | |
| -lopencv_core -ldl -lpthread -lrt -lzlib -lcsi_cv -latomic -static \ | |
| -o resnet50_example # Compile the program | |
| ``` | |
| ```shell-session | |
| $ export OPENCV_DIR=../../modules/opencv/ # Set the path to OpenCV | |
| $ riscv64-unknown-linux-gnu-g++ main.cpp -I${OPENCV_DIR}/include/opencv4 -L${OPENCV_DIR}/lib \ | |
| -lopencv_imgproc -lopencv_imgcodecs -lopencv_core -ldl -lpthread -lrt -lcsi_cv -o resnet50_example # Compile the program |
Note:
The example above uses a number of explicit library flags and the-staticoption for static linking. These may not be required or available in all environments, and static libraries (such aslibjpeg-turbo,libwebp,libpng,libtiff,libopenjp2,zlib, etc.) may not be present or may have different names/locations.
Adjust the library flags and linking options as needed for your system. If you encounter build errors related to missing libraries, try removing unnecessary flags or use dynamic linking by omitting-static.
Comment on lines
+164
to
+168
| Ensure `LD_LIBRARY_PATH` is correctly set. If the issue persists, run `pip show shl-python` to check the version. | ||
|
|
||
| If the version is `3.x.x`, it is too high. The Resnet50 program requires `shl-python` version 2.x. Downgrade with: | ||
|
|
||
| ```shell-session |
There was a problem hiding this comment.
suggestion: Suggest proactively pinning shl-python version in earlier install steps.
Specify the required shl-python version (e.g., 2.6.17) in the installation steps to prevent version mismatch issues.
Suggested change
| Ensure `LD_LIBRARY_PATH` is correctly set. If the issue persists, run `pip show shl-python` to check the version. | |
| If the version is `3.x.x`, it is too high. The Resnet50 program requires `shl-python` version 2.x. Downgrade with: | |
| ```shell-session | |
| Ensure `LD_LIBRARY_PATH` is correctly set. If the issue persists, run `pip show shl-python` to check the version. | |
| If the version is `3.x.x`, it is too high. The Resnet50 program requires `shl-python` version 2.x. | |
| **To avoid version mismatch issues, proactively install the required version of `shl-python` (e.g., 2.6.17) before proceeding:** | |
| ```shell-session | |
| pip install shl-python==2.6.17 |
If you have already installed a different version, downgrade with:
| FATAL: could not open driver '/dev/vha0': Permission denied | ||
| ``` | ||
|
|
||
| Check if the current user has read/write permissions for `/dev/vha0`. Set permissions with: |
There was a problem hiding this comment.
🚨 suggestion (security): Setting device permissions to 0666 should be accompanied by a security warning.
World read/write permissions can pose security risks. Recommend adding a warning and suggesting udev rules for safer permission management.
Suggested implementation:
Check if the current user has read/write permissions for `/dev/vha0`.
:::danger Security Warning
Setting device permissions to `0666` (world read/write) can pose significant security risks, as it allows any user or process on the system to access the device. This may expose the device to unintended or malicious use. **It is recommended to use more restrictive permissions or configure access for specific user groups.**
:::
Set permissions with:
```shell-session
Set permissions with:
```shell-session
sudo chmod 0666 /dev/vha0
Alternatively, for a safer and more permanent solution, consider creating a udev rule to manage device permissions for a specific user group:
# Create a group for NPU access if it doesn't exist
sudo groupadd npuusers
# Add your user to the group
sudo usermod -aG npuusers $USER
# Create a udev rule (replace 'vha0' with your device name if different)
echo 'KERNEL=="vha0", GROUP="npuusers", MODE="0660"' | sudo tee /etc/udev/rules.d/99-npu.rules
# Reload udev rules
sudo udevadm control --reload-rules
sudo udevadm trigger
This approach restricts device access to users in the npuusers group, improving security.
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
来源：yuque note
npu部分相关文档添加和翻译，正在共同编写中 (WIP)
Signed-off-by: LeeJc02 [email protected]
Summary by Sourcery
Add English translations for NPU documentation under the i18n directory, covering end-to-end model inference guidance on RevyOS.
Documentation: