# 常见问题 - 飞桨大语言模型推理部署工具包

跳转至

English

# 常见问题FAQ

## 1.显存不足

1. 启动服务时显存不足：
2. 核对模型和量化方式对应的部署最小卡数，如果不满足则需要增加部署卡数

3. 如果开启了CUDAGraph，尝试通过降低 `gpu_memory_utilization`来为CUDAGraph留存更多的显存，或通过减少 `max_num_seqs`，设置`cudagraph_capture_sizes`来减少CUDAGraph的显存占用。

4. 服务运行期间显存不足：

5. 检查log中是否有类似如下信息，如有，通常是输出block不足导致，需要减小`kv-cache-ratio`

    need_block_len: 1， free_list_len: 0
    step max_id: 2， max_num: 133， encoder block len: 24
    recover seq_id: 2， free_list_len: 144， used_list_len: 134
    need_block_len: 1， free_list_len: 0
    step max_id: 2， max_num: 144， encoder_block_len: 24

建议启用服务管理全局 Block功能，在启动服务前，加入环境变量

    export ENABLE_V1_KVCACHE_SCHEDULER=1

## 2.模型性能差

1. 首先检查输出长度是否符合预期，是否是解码过长导致。 如果场景输出本身较长，请检查log中是否有类似如下信息，如有，通常是输出block不足导致，需要减小`kv-cache-ratio`

    need_block_len: 1， free_list_len: 0
    step max_id: 2， max_num: 133， encoder block len: 24
    recover seq_id: 2， free_list_len: 144， used_list_len: 134
    need_block_len: 1， free_list_len: 0
    step max_id: 2， max_num: 144， encoder_block_len: 24

同样建议启用服务管理全局 Block功能，在启动服务前，加入环境变量

    export ENABLE_V1_KVCACHE_SCHEDULER=1

1. 检查自动profile分配的KVCache block是否符合预期，如果自动profile中受到显存波动影响可能导致分配偏少，可以通过手工设置`num_gpu_blocks_override`参数扩大KVCache block。

## 3.服务可以支持多大并发？

1. 服务部署时推荐配置以下环境变量

`export ENABLE_V1_KVCACHE_SCHEDULER=1`

1. 服务启动时需要配置 `max-num-seqs` 该参数表示 Decode 阶段的最大 Batch 数，当并发超过该值时，多余的请求会进入排队等待处理。 一般情况下，你可以将 `max-num-seqs` 配置为 128，保持在较高范围；实际并发能力由压测客户端决定。

2. `max-num-seqs` 仅表示配置的上限，但服务真正能支持的并发量取决于 KVCache 的总大小 服务启动后，在 `log/worker_process.log` 中会看到类似：

`num_blocks_global: 17131`

这表示当前服务的 KVCache Block 数量为 17131，若 `block_size = 64`（默认），则可缓存 Token 总量为：

`17131 * 64 = 1,096,384 tokens`

如果你的请求平均（输入 + 输出）为 20K tokens，那么服务实际能支持的并发大约为：

`1,096,384 / 20,000 ≈ 53`

## 4. 启用 logprobs 后推理请求卡住

启用 logprobs 后，推理结果会附带每个 token 的logprobs信息，使单条消息体显著变大。在默认配置下，这可能触发 System V Message Queue 的消息大小限制，从而导致推理任务token输出卡住。

不同模式下（MTP / 非 MTP）logprobs 会导致消息体膨胀的规模不同，具体计算如下。

### 消息体大小计算

1. 非 MTP 模式 + logprobs 单条消息体大小：

`((512 * (20 + 1)) + 2) * 8 + 512 * (20 + 1) * 4 + 512 * 8 = 133136 bytes`

1. MTP 模式 + logprobs 单条消息体大小：

`(512 * 6 * (20 + 1) + 512 + 3) * 8 + 512 * 6 * (20 + 1) * 4 + 512 * 6 * 8 = 802840 bytes`

### 问题原因

通过 `ipcs -l` 查看系统默认的 System V 消息队列限制，常见设置如下：

    ------ Messages Limits --------
    max queues system wide = 32000
    max size of message (bytes) = 8192
    default max size of queue (bytes) = 16384

当单条消息体大小超过 max size of message（默认 8192 bytes） 时，进程间通信会被阻塞，最终表现为推理请求卡住。

### 解决方案

调大 System V Message Queue 的消息大小限制。

由于 MTP 下的消息体可接近 800 KB，建议将单条消息大小限制提升至 1MB（1048576 bytes）。

Linux 系统可通过以下命令调整：

    # 提高单条消息的最大允许大小
    sysctl -w kernel.msgmax=1048576

    # 提高单个消息队列的最大容量
    sysctl -w kernel.msgmnb=268435456

> 注意: 若在 Docker 容器中运行，需要启用特权模式（`--privileged`），或在启动参数中显式设置相关内核参数。

### 废弃说明

当前基于 System V Message Queue 的通信机制将在后续版本中被废弃。未来将迁移到更稳定、更高效的通信方式，以彻底解决上述限制问题。