Make RKLLM model card easier to use

README.md

@@ -12,53 +12,63 @@ tags:
 - gemma-3
 ---
 
-# gemma-3-4b-it-RKLLM
+# gemma-3-4b-it · RKLLM
 
-RKLLM-converted Gemma 3 4B IT language-model artifacts for Rockchip RK3576 and RK3588 NPUs.
+Text generation on Rockchip RK3576 and RK3588, converted from [google/gemma-3-4b-it](https://huggingface.co/google/gemma-3-4b-it).
 
-Important: the upstream [google/gemma-3-4b-it](https://huggingface.co/google/gemma-3-4b-it) model is multimodal/VLM-capable, but this repository contains only RKLLM language-model binaries. The converted model exposed here is LLM-only: it does not accept images and does not include an RKNN vision encoder.
+**The files currently published here are text-only.** The source model supports images, but this conversion does not include a vision encoder.
 
-These hardware-specific `.rkllm` files require a compatible Rockchip RKLLM runtime. They are not Transformers checkpoints and cannot be loaded directly with Transformers, llama.cpp, or Ollama.
+- **Conversion toolkit:** RKLLM Toolkit 1.2.3.
+- **Inputs / output:** text → text.
+- **License:** `gemma`; the [upstream model card](https://huggingface.co/google/gemma-3-4b-it) describes its terms and intended use.
 
-## Base model
+## Choose your files
 
-- Upstream model: [google/gemma-3-4b-it](https://huggingface.co/google/gemma-3-4b-it)
-- License: Gemma Terms of Use
-- Upstream type: VLM/multimodal
-- RKLLM type: LLM-only
+Use the files for your board’s exact SoC. `w4a16` uses 4-bit weights and 16-bit activations; `w4a16_g128` adds a weight group size of 128. `w8a8` uses 8-bit weights and activations. File size below is download size, not total runtime RAM.
 
-Review Google's Gemma terms before use or redistribution.
-
-## Conversion and variants
-
-### Toolkit version
+| Board | Quantization | Size | Language model |
+| --- | --- | --- | --- |
+| RK3576 | `w4a16` | 3.42 GiB | [gemma-3-4b-it_RK3576_w4a16.rkllm](RK3576/gemma-3-4b-it_RK3576_w4a16.rkllm) |
+| RK3576 | `w8a8` | 4.92 GiB | [gemma-3-4b-it_RK3576_w8a8.rkllm](RK3576/gemma-3-4b-it_RK3576_w8a8.rkllm) |
+| RK3588 | `w8a8` | 4.90 GiB | [gemma-3-4b-it_RK3588_w8a8.rkllm](RK3588/gemma-3-4b-it_RK3588_w8a8.rkllm) |
 
-**RKLLM Toolkit: v1.2.3**
+## Run on your board
 
-Use a file built for the exact target SoC.
+With Docker installed on a matching Rockchip board, this example starts the **RK3576 w4a16** model and its API on port 8001:
 
-| Target | Quantization | File | SHA256 |
-| --- | --- | --- | --- |
-| RK3576 | W4A16 | [gemma-3-4b-it_RK3576_w4a16.rkllm](RK3576/gemma-3-4b-it_RK3576_w4a16.rkllm) | `0e6d6298453f483e832a7982bcdf1acdf895a47c6777e93eb3c1e43e82cf8fc2` |
-| RK3576 | W8A8 | [gemma-3-4b-it_RK3576_w8a8.rkllm](RK3576/gemma-3-4b-it_RK3576_w8a8.rkllm) | `b077e9ee75f837230dbf1be948a03d39942abd90ab23343399fa13b7d19526cf` |
-| RK3588 | W8A8 | [gemma-3-4b-it_RK3588_w8a8.rkllm](RK3588/gemma-3-4b-it_RK3588_w8a8.rkllm) | `aa04fce6ca2e418cd946814f1563fe8ed7e56dfbf5cf99ced4e753739287ee80` |
+```bash
+sudo docker run --rm -d --name rkllm \
+  --privileged -v /dev:/dev -p 8001:8001 \
+  ghcr.io/hanzo-huang/rkllm-docker/llm/gemma-3-4b-it:rk3576-w4a16
+```
 
-The repository also includes `gemma-3-4b-it_data_quant.json`, used as calibration data during conversion.
+The image includes its model file. See [rkllm-docker](https://github.com/Hanzo-Huang/rkllm-docker#readme) for API requests, other board variants, and configuration.
 
-## Usage
+To download the files separately instead:
 
 ```bash
 hf download HanzoHuang/gemma-3-4b-it-RKLLM \
   RK3576/gemma-3-4b-it_RK3576_w4a16.rkllm \
-  --local-dir gemma-3-4b-it-RKLLM
+  --local-dir ./models
 ```
 
-Run the file with the RKLLM runtime and the upstream Gemma instruction prompt format. For Docker deployment, see [Hanzo-Huang/rkllm-docker](https://github.com/Hanzo-Huang/rkllm-docker).
+These are native RKLLM/RKNN artifacts. Use a compatible RKLLM runtime and the model’s correct chat template when integrating them in another application.
+
+## Release notes
+
+No per-variant board benchmark is published here. Quantized output may differ from the original model; check responses on your own workloads. Use the toolkit version listed above when checking runtime compatibility.
 
-## Limitations
+<details>
+<summary>SHA-256 checksums</summary>
+
+```text
+0e6d6298453f483e832a7982bcdf1acdf895a47c6777e93eb3c1e43e82cf8fc2  RK3576/gemma-3-4b-it_RK3576_w4a16.rkllm
+b077e9ee75f837230dbf1be948a03d39942abd90ab23343399fa13b7d19526cf  RK3576/gemma-3-4b-it_RK3576_w8a8.rkllm
+aa04fce6ca2e418cd946814f1563fe8ed7e56dfbf5cf99ced4e753739287ee80  RK3588/gemma-3-4b-it_RK3588_w8a8.rkllm
+```
 
-Vision input is not supported by these artifacts. Conversion can change output quality relative to the upstream model; validate the result on your target device.
+</details>
 
-## Acknowledgements
+## Credits
 
-Thanks to Google, Rockchip, and the RKLLM community.
+Original model: [google/gemma-3-4b-it](https://huggingface.co/google/gemma-3-4b-it). Conversion tools: [Rockchip RKLLM](https://github.com/airockchip/rknn-llm).