Rewrite README for release format

README.md

@@ -2,75 +2,69 @@
 library_name: transformers
 license: apache-2.0
 base_model:
-- openbmb/MiniCPM5-1B
+  - openbmb/MiniCPM5-1B
 pipeline_tag: text-generation
 tags:
-- minicpm
-- llm
-- axera
-- AX650
+  - minicpm5
+  - llm
+  - thinking
+  - axera
+  - ax650
 language:
-- zh
-- en
+  - en
+  - zh
 ---
 
 # MiniCPM5-1B on AXERA NPU
 
-Ready-to-run AX650 deployment package for `openbmb/MiniCPM5-1B`.
+Ready-to-run deployment package for `openbmb/MiniCPM5-1B` on AX650 / NPU3.
 
-- Runtime: `axllm serve` and `axllm run`
-- Target: `AX650 / AX650N aarch64`
-- Model type: text-only LLM
-- Context layout: `prefill_len=128`, `kv_cache_len=2047`, `prefill_max_token_num=1280`
-- Default generation mode: `enable_thinking=false`
-- Included board binary: `bin/axllm`
-
-This package has been validated through the OpenAI-compatible `axllm serve` API.
+- This release packages the AX650 `axllm` runtime together with the compiled text `.axmodel` files.
+- The packaged runtime is configured for text-only inference on AX650 / NPU3.
+- The packaged context layout is `prefill_len=128`, `kv_cache_len=2047`, and `prefill_max_token_num=1280`.
+- Thinking is disabled by default and can be enabled per request through the public OpenAI-compatible API.
+- The package includes the tokenizer, runtime config files, and the validated `bin/axllm` binary for board-side deployment.
 
 ## Supported Platform
 
-- [x] AX650 / AX650N
+- [x] AX650 / NPU3
 
-## Capability
+## Validated Devices
 
-MiniCPM5-1B in this package is a pure text model.
+This package has been validated on the following AX650-based device:
 
-- Text chat: supported
-- Multi-turn text chat: supported
-- Image, video, and audio inputs: not supported
+- AX650 / NPU3 development board
 
-## Performance and Footprint
+## Performance
 
-Measurements below were taken on AX650 / NPU3 with the packaged `axllm` binary. `TTFT` means time to first token. In this table, `TTFT` is measured end-to-end from request arrival at `axllm serve` to the first generated token.
+All measurements below were taken on AX650 / NPU3 with the packaged `axllm` runtime. `TTFT` stands for time to first token. In this table, `TTFT` is measured end-to-end from request arrival at `axllm serve` to the first generated token.
 
-The validated text prompts below were kept within one `128`-token prefill chunk. To avoid one-time startup effects, each `TTFT` row excludes the first request for that prompt pattern. Sustained text-only `Decode` throughput was measured separately with longer text-only generations (`max_tokens=256`).
+The validated text prompts below were kept within one `128`-token prefill chunk. To avoid one-time startup effects, each `TTFT` row excludes the first request for that prompt pattern.
 
 | Scenario | Input tokens | Prefill chunks | TTFT | Decode |
 |---|---:|---:|---:|---:|
-| Text smoke prompt | `24` | `1 x 128` | `160.34 ms avg` (`159.40-161.28 ms`) | `17.96 token/s avg` |
+| Text smoke prompt | `24` | `1 x 128` | `160.34 ms avg` (`159.40-161.28 ms`) | `n/a (single-token reply)` |
 | Short front-end prompt | `14` | `1 x 128` | `157.76 ms avg` (`157.68-157.84 ms`) | `n/a (short reply)` |
 | Multi-turn text prompt | `40` | `1 x 128` | `159.89 ms avg` (`159.19-160.59 ms`) | `n/a (short reply)` |
+| Long text generation reference | `30` | `1 x 128` | `159.91 ms avg` (`159.34-160.49 ms`) | `17.96 token/s avg` |
 
-### Flash Footprint
-
-| Item | Value |
-|---|---:|
-| Text + post axmodels | `1.4 GiB` |
-| Full package, excluding `.git` | `1.9 GiB` |
+The packaged runtime uses the following context layout:
 
-### Startup Runtime Footprint
+- `prefill_len=128`
+- `kv_cache_len=2047`
+- `prefill_max_token_num=1280`
 
-The startup log records `remain_cmm(6692 MB)` after the post axmodel was initialized.
+The `Long text generation reference` row is the recommended sustained text-only decode figure for this package. Very short replies under-report decode speed because EOS and response-tail overhead become relatively larger.
 
-Runtime layout from the same log:
+## Startup Runtime Footprint
 
 | Item | Value |
 |---|---:|
-| `max_token_len` | `2047` |
-| `kv_cache_size` | `256` |
-| `kv_cache_num` | `2047` |
-| `prefill_token_num` | `128` |
-| `prefill_max_token_num` | `1280` |
+| `Flash total (24 text axmodels + post axmodel + embedding bin)` | `1.42 GiB` (`1456.71 MiB`) |
+| `Package flash total (excluding .git/)` | `1.43 GiB` (`1464.24 MiB`) |
+| `Runtime CMM requirement` | `Board-dependent; validate on your target AX650 CMM pool` |
+
+On the validated AX650 board, the packaged startup log confirmed `max_token_len=2047`, `prefill_len=128`, and `prefill_max_token_num=1280`. This README does not present one board's `remain_cmm(...)` value as a package-wide memory requirement, because the absolute remaining CMM pool depends on the board's global memory layout.
 
 ## Package Layout
 
@@ -80,25 +74,72 @@ Runtime layout from the same log:
 ├── bin/
 │   ├── axllm
 │   └── axllm.version.json
+├── config.json
+├── post_config.json
+├── minicpm5_tokenizer.txt
+├── model.embed_tokens.weight.bfloat16.bin
 ├── llama_p128_l0_together.axmodel
 ├── ...
 ├── llama_p128_l23_together.axmodel
-├── llama_post.axmodel
-├── model.embed_tokens.weight.bfloat16.bin
-├── config.json
-├── post_config.json
-└── minicpm5_tokenizer.txt
+└── llama_post.axmodel
+```
+
+This package uses a flat runtime layout. The packaged `axllm` binary reads the root-level runtime files directly, so no extra path arguments are required when you serve the repository root.
+
+## Direct Inference with `axllm`
+
+### Download the Model Package
+
+Download the release package from Hugging Face:
+
+```shell
+mkdir -p AXERA-TECH/MiniCPM5-1B
+cd AXERA-TECH/MiniCPM5-1B
+hf download AXERA-TECH/MiniCPM5-1B --local-dir .
+```
+
+### Install `axllm`
+
+Option 1: use the validated binary included in this repository:
+
+```bash
+chmod +x ./bin/axllm
+```
+
+Option 2: install `axllm` from the public repository:
+
+```shell
+git clone -b axllm https://github.com/AXERA-TECH/ax-llm.git
+cd ax-llm
+./install.sh
+```
+
+Option 3: install with a one-line command:
+
+```shell
+curl -fsSL https://raw.githubusercontent.com/AXERA-TECH/ax-llm/axllm/install.sh | bash
+```
+
+Option 4: download the prebuilt binary from GitHub Actions CI:
+
+If you do not have a local build environment, download the latest CI-generated `axllm` binary from GitHub Actions:
+`https://github.com/AXERA-TECH/ax-llm/actions?query=branch%3Aaxllm`
+Then run:
+
+```shell
+chmod +x axllm
+sudo mv axllm /usr/bin/axllm
 ```
 
-The runtime files are placed at the repository root so the package can be served directly by `axllm`.
+### Run on the Board
 
-## Run on AX650
+This package already includes a validated `bin/axllm` binary for AX650.
 
-From the repository root on the board:
+From the package root on the board:
 
 ```bash
 chmod +x ./bin/axllm
-./bin/axllm serve .
+./bin/axllm serve . --port 8000
 ```
 
 Expected model id:
@@ -107,15 +148,42 @@ Expected model id:
 AXERA-TECH/MiniCPM5-1B-AX650-C128-P1152-CTX2047
 ```
 
-Health check:
+Health check and model listing:
 
 ```bash
 curl http://127.0.0.1:8000/health
+curl http://127.0.0.1:8000/v1/models
+```
+
+Example health output:
+
+```json
+{
+  "concurrency": 0,
+  "max_concurrency": 1,
+  "status": "healthy"
+}
 ```
 
-## Chat Request
+Example model list output:
 
-Default behavior uses no-thinking mode because `config.json` sets `enable_thinking=false`.
+```json
+{
+  "data": [
+    {
+      "created": 1780908633,
+      "id": "AXERA-TECH/MiniCPM5-1B-AX650-C128-P1152-CTX2047",
+      "object": "model",
+      "owned_by": "openai-api"
+    }
+  ],
+  "object": "list"
+}
+```
+
+### Text Request
+
+By default, this package uses no-thinking mode because the packaged `config.json` sets `enable_thinking=false`.
 
 ```bash
 curl http://127.0.0.1:8000/v1/chat/completions \
@@ -123,18 +191,37 @@ curl http://127.0.0.1:8000/v1/chat/completions \
   -d '{
     "model": "AXERA-TECH/MiniCPM5-1B-AX650-C128-P1152-CTX2047",
     "messages": [
-      {"role": "user", "content": "1+1等于几？请简短回答。"}
+      {
+        "role": "user",
+        "content": "中国的首都是哪里？请只回答城市名。"
+      }
     ],
     "max_tokens": 32,
     "temperature": 0
   }'
 ```
 
-This default request does not emit `<think>...</think>` markup.
+Example output:
 
-## Enable Thinking Per Request
+```json
+{
+  "choices": [
+    {
+      "message": {
+        "role": "assistant",
+        "content": "北京"
+      },
+      "finish_reason": "stop"
+    }
+  ],
+  "model": "AXERA-TECH/MiniCPM5-1B-AX650-C128-P1152-CTX2047",
+  "object": "chat.completion"
+}
+```
 
-Use top-level `enable_thinking=true`:
+### Enable Thinking Per Request
+
+To enable explicit reasoning output for a single request, pass top-level `enable_thinking=true`:
 
 ```bash
 curl http://127.0.0.1:8000/v1/chat/completions \
@@ -142,17 +229,36 @@ curl http://127.0.0.1:8000/v1/chat/completions \
   -d '{
     "model": "AXERA-TECH/MiniCPM5-1B-AX650-C128-P1152-CTX2047",
     "messages": [
-      {"role": "user", "content": "中国的首都是哪里？请先思考，再给出简短答案。"}
+      {
+        "role": "user",
+        "content": "中国的首都是哪里？请简短思考后给最终答案。"
+      }
     ],
     "enable_thinking": true,
-    "max_tokens": 128,
+    "max_tokens": 384,
     "temperature": 0
   }'
 ```
 
-When thinking is enabled, the API returns explicit `<think>...</think>` markup so clients can render reasoning and final answer separately.
+Typical output shape:
+
+```json
+{
+  "choices": [
+    {
+      "message": {
+        "role": "assistant",
+        "content": "<think>\n...\n</think>\n\n中国的首都是北京。"
+      },
+      "finish_reason": "stop"
+    }
+  ],
+  "model": "AXERA-TECH/MiniCPM5-1B-AX650-C128-P1152-CTX2047",
+  "object": "chat.completion"
+}
+```
 
-The compatible HuggingFace-style form is also accepted:
+The Hugging Face-style request form is also accepted:
 
 ```json
 {
@@ -162,8 +268,22 @@ The compatible HuggingFace-style form is also accepted:
 }
 ```
 
-## Notes
+When thinking mode is enabled, the service returns client-visible `<think>...</think>` markup so front ends can render reasoning and final answer separately. Follow-up turns also keep the official MiniCPM5 template behavior: previous assistant reasoning content is not reinserted into the next user prompt.
+
+## Browser UI with `lite_webui`
+
+If you want a browser UI for the OpenAI-compatible service started by `axllm serve`, use [AXERA-TECH/lite_webui](https://huggingface.co/AXERA-TECH/lite_webui/tree/main).
+
+Set the OpenAI base URL to `http://<board-ip>:8000` and the model name to `AXERA-TECH/MiniCPM5-1B-AX650-C128-P1152-CTX2047`.
+
+## Conversion References
+
+If you need the original model files or want to rebuild the deployment artifacts, start with:
+
+- Original Hugging Face model: [openbmb/MiniCPM5-1B](https://huggingface.co/openbmb/MiniCPM5-1B)
+- AXERA conversion and deployment workflow: [AXERA-TECH/MiniCPM5-1B.axera](https://github.com/AXERA-TECH/MiniCPM5-1B.axera)
+
+## Discussion
 
-- Previous assistant `<think>...</think>` content is stripped from normal chat history before the next user turn, matching the official MiniCPM5 template behavior.
-- If a thinking response reaches `max_tokens` before the model emits `</think>`, `axllm` closes the client-visible thinking block before finishing the response stream.
-- This release does not include the original HuggingFace `safetensors` weights.
+- GitHub Issues
+- QQ group: `139953715`