feat: support GLM-5.3 Flash dynamic FP8 KV cache with regression cove…

docs/CN/source/tutorial/fp8_kv_quantization.rst

@@ -1,102 +1,91 @@
 .. _tutorial/fp8_kv_quantization_cn:
 
-FP8 KV 量化与校准指南
-======================
+FP8 KV 量化使用指南
+===================
 
-本章节介绍 LightLLM 中 FP8 KV 推理的使用方式，包括：
+通过 ``--llm_kv_type`` 选择 FP8 KV Cache 量化模式。
+运行前请按 :doc:`安装指南 <../getting_started/installation>` 准备环境。
 
-- 使用校准文件进行推理（``fp8kv_sph`` 或 ``fp8kv_spt``）
-- FP8 静态按 head 和按 tensor 的量化模式
-- 常见报错与排查建议
-
-功能概览
---------
-
-LightLLM 的 FP8 KV 推理需要准备好的校准文件（``kv_cache_calib.json``），
-并通过 ``--kv_quant_calibration_config_path`` 加载。
-你可以直接使用 ``test/advanced_config/`` 目录下已有的校准文件，
-也可以使用 `LightCompress <https://github.com/ModelTC/LightCompress>`_ 工具导出，或使用自有兼容文件。
-
-量化模式与后端对应
-------------------
-
-LightLLM 支持两种 FP8 KV 量化模式：
-
-- ``fp8kv_sph``: FP8 静态按 head 量化（Static Per-Head），每个 head 独立 scale，对应 ``fa3`` 后端
-- ``fp8kv_spt``: FP8 静态按 tensor 量化（Static Per-Tensor），K/V 各一个标量 scale，对应 ``flashinfer`` 后端
+选择量化模式
+------------
 
-校准文件与量化模式强相关：
+.. list-table::
+   :header-rows: 1
 
-- ``fp8kv_sph`` 对应 ``per_head`` 校准文件
-- ``fp8kv_spt`` 对应 ``per_tensor`` 校准文件
+   * - 模式
+     - 适用场景
+     - 校准文件
+   * - ``fp8kv_sph``
+     - 静态按 head 量化，需 Hopper GPU
+     - ``per_head``，须包含 Q 校准数据
+   * - ``fp8kv_spt``
+     - 静态按 tensor 量化，需 FlashInfer
+     - ``per_tensor``
+   * - ``fp8kv_dsa``
+     - DeepSeek-V3.2、GLM-5.3 Flash
+     - 不需要
 
-不建议混用不同模式的校准文件。
+静态 FP8 KV
+-----------
 
-使用校准文件启动 FP8 推理
--------------------------
+准备与模型和量化模式匹配的 ``kv_cache_calib.json``，然后指定文件路径启动。
 
-推理模式示例：
+按 head 量化：
 
 .. code-block:: console
 
     $ python -m lightllm.server.api_server \
         --model_dir /path/to/model \
         --llm_kv_type fp8kv_sph \
-        --kv_quant_calibration_config_path /path/to/kv_cache_calib.json
+        --kv_quant_calibration_config_path /path/to/per_head/kv_cache_calib.json
+
+按 tensor 量化：
 
 .. code-block:: console
 
     $ python -m lightllm.server.api_server \
         --model_dir /path/to/model \
         --llm_kv_type fp8kv_spt \
-        --kv_quant_calibration_config_path /path/to/kv_cache_calib.json
+        --kv_quant_calibration_config_path /path/to/per_tensor/kv_cache_calib.json
 
-说明：
+两种模式都会自动选择注意力后端，无需额外指定。
+多卡部署时添加 ``--tp <卡数>``，仍只需提供一份完整的校准文件。
 
-- ``fp8kv_sph`` 和 ``fp8kv_spt`` 模式必须提供 ``--kv_quant_calibration_config_path``。
-- attention backend 会根据量化模式自动选择，无需手动指定。
+动态 FP8 KV
+-----------
 
-.. note::
+DeepSeek-V3.2 和 GLM-5.3 Flash 使用 ``--llm_kv_type fp8kv_dsa``，无需提供校准文件。
+环境中需安装兼容的 FlashMLA；可按安装指南从本仓库的 Dockerfile 构建镜像。
+源码安装用户还需单独安装 FlashMLA，仅安装 ``requirements.txt`` 不够。
 
-   使用 ``fp8kv_spt`` 模式（FP8 静态按 tensor 量化，使用 flashinfer 后端）时，
-   必须安装 ``flashinfer-python==0.6.5``。默认安装的版本是 0.6.3，
-   可能导致运行错误。请使用以下命令安装正确版本：
+以下以 GLM-5.3 Flash 为例，该模型须使用 ``bfloat16``，FP8 KV 模式仅支持 ``fp8kv_dsa``：
 
-   .. code-block:: console
+.. code-block:: console
 
-       $ pip install flashinfer-python==0.6.5
+    $ python -m lightllm.server.api_server \
+        --model_dir /path/to/GLM-5.3-Flash --tp 4 \
+        --data_type bfloat16 --llm_kv_type fp8kv_dsa
 
-校准文件格式
+P/D 分离部署
 ------------
 
-``kv_cache_calib.json`` 主要字段包括：
+使用动态 FP8 KV 进行 P/D 分离部署时，Prefill 和 Decode 两端都须设置 ``--llm_kv_type fp8kv_dsa``。
+GLM-5.3 Flash 可使用单机 8 卡脚本，P/D 各使用 4 卡：
 
-- ``quant_type``: ``per_head`` 或 ``per_tensor``
-- ``num_layers``: 层数
-- ``num_head``: 总 head 数
-- ``scales_shape``: scale 张量形状
-- ``scales``: 实际 scale 数值
-- ``qmin`` / ``qmax``: FP8 范围参数
+.. code-block:: console
 
-加载校准文件时，会校验模型架构、层数、head 数及量化类型是否匹配。
+    $ LLM_KV_TYPE=fp8kv_dsa bash test/start_scripts/glm53/glm53_pd_1p1d.sh \
+        8088 <node_ip> /path/to/GLM-5.3-Flash
 
-多卡说明
---------
-
-在多卡（TP）场景下，系统会根据当前 rank 自动切分本地需要的 head 对应 scale。
-你仍然只需要提供一份全量 ``kv_cache_calib.json``。
+将 ``<node_ip>`` 替换为服务可访问的本机 IP。脚本会同时配置两端的量化模式和传输页大小。
+手动启动时，两端须使用相同的量化模式和 ``--pd_kv_page_size``。
 
 常见问题
 --------
 
-1. 启动时报错需要 ``--kv_quant_calibration_config_path``
-
-   说明你使用了 ``--llm_kv_type fp8kv_sph`` 或 ``fp8kv_spt`` 但未传入校准文件路径。
-
-2. 报错 ``quant_type not match``
-
-   通常是量化模式与校准文件类型不一致。例如拿 ``per_tensor`` 文件去跑 ``fp8kv_sph``。
-
-3. 切换量化模式后效果异常
-
-   建议使用与目标量化模式匹配的校准文件，不要跨模式复用不兼容文件。
+- **提示缺少校准文件或校准类型不匹配**：静态模式必须传入
+  ``--kv_quant_calibration_config_path``，文件须匹配模型及所选模式；
+  ``fp8kv_sph`` 文件还须包含 Q 校准数据。
+- **提示缺少依赖**：按当前安装指南安装依赖；动态模式还需兼容的 FlashMLA。
+- **P/D 传输页容量不足**：同时增大两端的 ``--pd_kv_page_size``，并确保其为
+  ``--page_size`` 的整数倍。

docs/EN/source/tutorial/fp8_kv_quantization.rst

@@ -1,102 +1,98 @@
 .. _tutorial/fp8_kv_quantization_en:
 
-FP8 KV Quantization and Calibration Guide
-=========================================
+FP8 KV Quantization Guide
+=========================
 
-This chapter describes FP8 KV inference in LightLLM, including:
+Select an FP8 KV cache quantization mode with ``--llm_kv_type``.
+Prepare the environment using the :doc:`installation guide <../getting_started/installation>`.
 
-- Running inference with calibration data (``fp8kv_sph`` or ``fp8kv_spt``)
-- FP8 static per-head and per-tensor quantization modes
-- Common errors and troubleshooting
-
-Overview
---------
-
-LightLLM FP8 KV inference requires a prepared calibration file (``kv_cache_calib.json``),
-which is loaded by ``--kv_quant_calibration_config_path``.
-You can use calibration files provided in ``test/advanced_config/``,
-export one with `LightCompress <https://github.com/ModelTC/LightCompress>`_, or use your own compatible file.
-
-Quantization Modes and Backend Mapping
-------------------------------------------
-
-LightLLM supports two FP8 KV quantization modes:
-
-- ``fp8kv_sph``: FP8 Static Per-Head quantization, independent scale per head, uses ``fa3`` backend
-- ``fp8kv_spt``: FP8 Static Per-Tensor quantization, one scalar for K and one scalar for V, uses ``flashinfer`` backend
-
-Calibration files are mode-dependent:
-
-- ``fp8kv_sph`` corresponds to ``per_head`` calibration files
-- ``fp8kv_spt`` corresponds to ``per_tensor`` calibration files
+Choose a Mode
+-------------
 
-Avoid mixing calibration files across different modes.
+.. list-table::
+   :header-rows: 1
+
+   * - Mode
+     - Use case
+     - Calibration file
+   * - ``fp8kv_sph``
+     - Static per-head quantization; requires a Hopper GPU
+     - ``per_head``, including Q calibration data
+   * - ``fp8kv_spt``
+     - Static per-tensor quantization; requires FlashInfer
+     - ``per_tensor``
+   * - ``fp8kv_dsa``
+     - DeepSeek-V3.2 and GLM-5.3 Flash
+     - Not required
+
+Static FP8 KV
+-------------
 
-Start FP8 Inference with Calibration
-------------------------------------
+Prepare a ``kv_cache_calib.json`` compatible with your model and quantization mode,
+then pass its path at startup. Export one with
+`LightCompress <https://github.com/ModelTC/LightCompress>`_ or use an existing compatible file.
 
-Inference mode example:
+Per-head quantization:
 
 .. code-block:: console
 
     $ python -m lightllm.server.api_server \
         --model_dir /path/to/model \
         --llm_kv_type fp8kv_sph \
-        --kv_quant_calibration_config_path /path/to/kv_cache_calib.json
+        --kv_quant_calibration_config_path /path/to/per_head/kv_cache_calib.json
+
+Per-tensor quantization:
 
 .. code-block:: console
 
     $ python -m lightllm.server.api_server \
         --model_dir /path/to/model \
         --llm_kv_type fp8kv_spt \
-        --kv_quant_calibration_config_path /path/to/kv_cache_calib.json
-
-Notes:
+        --kv_quant_calibration_config_path /path/to/per_tensor/kv_cache_calib.json
 
-- ``fp8kv_sph`` and ``fp8kv_spt`` require ``--kv_quant_calibration_config_path``.
-- The attention backend will be automatically selected based on the quantization mode, no need to manually specify.
+Both modes select the attention backend automatically.
+For multiple GPUs, add ``--tp <gpu_count>`` and provide one complete calibration file.
 
-.. note::
-
-   When using ``fp8kv_spt`` mode (FP8 static per-tensor quantization with flashinfer backend), 
-   you must install ``flashinfer-python==0.6.5``. The default installed version is 0.6.3, 
-   which may cause runtime issues. Install the correct version with:
-
-   .. code-block:: console
-
-       $ pip install flashinfer-python==0.6.5
-
-Calibration File Schema
------------------------
-
-Key fields in ``kv_cache_calib.json``:
+Dynamic FP8 KV
+--------------
 
-- ``quant_type``: ``per_head`` or ``per_tensor``
-- ``num_layers``: number of layers
-- ``num_head``: total number of heads
-- ``scales_shape``: shape of the scale tensor
-- ``scales``: actual scale values
-- ``qmin`` / ``qmax``: FP8 numeric range parameters
+For DeepSeek-V3.2 and GLM-5.3 Flash, use ``--llm_kv_type fp8kv_dsa`` without a calibration file.
+A compatible FlashMLA installation is required. You can build an image from this repository's
+Dockerfile as described in the installation guide. When installing from source, install
+FlashMLA separately; ``requirements.txt`` alone is insufficient.
 
-At load time, LightLLM validates architecture, layer count, head count, and quantization type.
+The following example uses GLM-5.3 Flash, which requires ``bfloat16`` and supports only
+``fp8kv_dsa`` for FP8 KV quantization:
 
-Multi-GPU Note
---------------
+.. code-block:: console
 
-In multi-GPU (TP) setups, LightLLM slices the global scales to local rank heads automatically.
-You only need to provide one full ``kv_cache_calib.json`` file.
+    $ python -m lightllm.server.api_server \
+        --model_dir /path/to/GLM-5.3-Flash --tp 4 \
+        --data_type bfloat16 --llm_kv_type fp8kv_dsa
 
-Common Issues
--------------
+Disaggregated P/D Deployment
+----------------------------
 
-1. Error says ``--kv_quant_calibration_config_path`` is required
+For dynamic FP8 KV in a disaggregated deployment, set ``--llm_kv_type fp8kv_dsa``
+on both Prefill and Decode services.
+For GLM-5.3 Flash on a single host with 8 GPUs, the following script uses 4 GPUs per service:
 
-   You are using ``--llm_kv_type fp8kv_sph`` or ``fp8kv_spt`` without a calibration file path.
+.. code-block:: console
 
-2. ``quant_type not match`` error
+    $ LLM_KV_TYPE=fp8kv_dsa bash test/start_scripts/glm53/glm53_pd_1p1d.sh \
+        8088 <node_ip> /path/to/GLM-5.3-Flash
 
-   Usually caused by quantization mode/file mismatch (for example, using a ``per_tensor`` file with ``fp8kv_sph``).
+Replace ``<node_ip>`` with a reachable IP address of the host. The script configures the
+quantization mode and transfer page size for both services. When starting services manually,
+use the same quantization mode and ``--pd_kv_page_size`` on both sides.
 
-3. Abnormal quality after mode switch
+Troubleshooting
+---------------
 
-   Use a calibration file that matches the target quantization mode instead of reusing an incompatible file.
+- **Missing calibration file or calibration type mismatch:** Static modes require
+  ``--kv_quant_calibration_config_path`` with a file matching the model and mode.
+  Files for ``fp8kv_sph`` must also include Q calibration data.
+- **Missing dependencies:** Follow the current installation guide. Dynamic mode also
+  requires a compatible FlashMLA installation.
+- **Insufficient P/D transfer page capacity:** Increase ``--pd_kv_page_size`` on both
+  services and keep it a multiple of ``--page_size``.