算子融合、量化、Tensor并行、ContinuousBatching等。
纯模型推理时，报错出现“out of memory, need block”，具体报错信息示例如下图：
通常是由于大图片或者视频导致的序列增长，导致预分配的KV cache不够用。
在“run_pa.sh”脚本中修改“max_input_length”，根据实际应用场景，设置一个更大的值。
单卡专家数较多，平均每个专家分到token不多，当精度有差异的场景下，有可能遇到chat接口比非chat接口性能更差的情况。
chat接口激活的专家分布更均衡，但单卡激活的专家数更多，需要搬运的专家也多，会导致性能变差，造成GMM算子性能波动。
这个是chat/no chat接口导致的固有差异，属于正常现象。
需要确认MindIE LLM和ATB，CANN，torch，torch_npu是否匹配，ABI=0/1的选择是否正确 。
当模型在模型侧使用torch.distributed多卡分布时，从服务侧拉起出现没有MASTER_ADDR或者MASTER_PORT环境变量：
没有设置环境变量MASTER_ADDR或MASTER_PORT。
可以通过如下两种方式设置环境变量：
- 在代码中设置：
通过环境变量设置：
[object Object]
服务侧拉起模型时出现“Max retries exceeded with url”报错，具体报错信息如下：
大概率是内网访问的问题。
以Qwen-VL为例，打开权重文件夹下tokenization_qwen.py文件，按照如下29~30行修改：
Service侧加载模型后快速退出程序，出现“Socket bind failed”报错，具体日志如下：
MindIE Motor使用HTTP或者HTTPS协议进行通信，让客户端先断开连接可以减少服务器的负担，保证资源的合理释放，包括端口资源等。
进入配置文件修改对应的“port”、“managementPort”和“metricsPort”参数。为避免该类问题发生，请在断开服务进程之前确保先断开请求。或使用**lsof -i :{port}**查看端口状态，若仍被残留进程占用，使用kill信号清理残留进程。其中_{port}_替换为查看的端口号。
服务侧成功拉起，发送请求却迟迟无法得到响应。
可查看模型侧日志，可能是out of memory。
在配置文件中，更改“npuDeviceIds”和“npuMemSize”。
若服务化拉起失败，优先查看日志信息，日志路径默认在“/root/mindie/log/debug”下。
可尝试protobuf升级，pip install protobuf==5.28。
拉起服务化时，遇到Check_path: config.json failed报错，具体报错信息如下：
模型权重路径下的模型配置文件“config.json”没有640的权限。
可通过如下两种方法修改权限：
执行如下命令，修改“config.json文件”的权限，：
[object Object]执行如下命令，修改模型权重整个文件夹的权限：
[object Object]
拉起服务时，出现“pybind11::error_already_set”报错，具体报错信息如下：
模型侧的三方依赖不正确，此时需要重新安装模型依赖的三方包。
根据模型的“requirements.txt”文件，重新安装第三方依赖，依赖文件默认路径为：“{MindIE安装目录}/atb_llm/requirements/models/requirements__{model}._txt”
拉起服务时core dump无报错日志。
模型侧的三方依赖不正确，如Protobuf等，此时需要重新安装模型依赖的三方包。
根据模型的“requirements.txt”文件，重新安装第三方依赖，依赖文件默认路径为：“{MindIE安装目录}/atb_llm/requirements/models/requirements_{model}.txt”
开启环境变量后，运行模型推理，根据加速库日志中的第一个error进一步定位。
确定性计算，是指在输入数据集等输入条件不变时，多次运行推理应用，输出结果每次保持一致。
- 将模型后处理部分从sampling改为greedy后，可以基本保证输出文本的稳定性。
- 由于确定性计算的问题，输出可能存在略微差异。
- 由于matmul算子在不同行上的累加顺序不完全相同，加之浮点精度没有加法交换律的特性，导致不同行上即使输入完全相同，计算结果也会存在一定的误差。
- 可以通过设置环境变量export ATB_MATMUL_SHUFFLE_K_ENABLE=0将加速库matmul的shuffle k功能关闭，关闭之后可以保证所有行上算子累加顺序一致，但matmul性能会下降10%左右 。
调度框架代码（block查询模式下）是可以保证确定性的，但是在CPU负载等环境因素的影响下，可能会对请求到达时间产生影响，最终影响调度的确定性。例如，客户外部服务查询引擎后得知可以提交10个请求，第一次运行时，10个请求快速到达并组成batch；但第二次运行时，受环境影响部分请求到达较晚，仅有5个请求组成了batch；那么两次运行的结果就会产生差异。
纯模型推理时遇到定位困难的报错。
由于模型推理中有异步执行，导致报错信息可能不是真实报错信息，需要同步后进行定位。
设置环境变量“export ASCEND_LAUNCH_BLOCKING=1”，打开同步运行后再进行定位。
确定性计算，是指在输入数据集等输入条件不变时，多次运行推理应用，输出结果每次保持一致。
模型层面：
通信算子：
[object Object]MatMul：
[object Object]推理引擎：
MindIE：基于block进行新request的获取。
TGI：暂不支持。
检查tokenizer在token转id时，是否使用了正确的模型路径。
推理过程中，D节点在拉取KV cache时，出现“Pull kv failed”的“ERROR”级别报错日志，并且CANN的status_code中出现了timeout的错误码。
PD分离场景中，D节点的KV cache需要从P节点那里拉取，出现这个错误，说明从P到D的KV cache传输超时，极有可能是网络质量差导致的。
（推荐）使用如下命令查看网络重传次数，如果有部分卡网络重传次数过高，请检查该光模块。
[object Object]在MindIE的配置文件“ModelDeployConfig”字段中设置"kv_trans_timeout" 为“5”，表示Pull kv的超时时间为5秒。这样设置可能会掩盖由网络问题导致的推理性能问题，请谨慎设置。
部署MindIE LLM服务时，出现LLMPythonModel initializes fail的报错，如下图所示。
ibis缺少Python依赖。
进入/Service安装路径/logs目录，打开Python日志，根据日志报错信息，安装需要的依赖。
*### 问题描述
部署MindIE LLM服务，加载模型时出现out of memory报错提示，如下图所示。
权重太大，内存不足。
将config.json文件中ModelConfig的npuMemSize调小，比如调成8。
部署MindIE LLM服务时，出现atb_llm.runner无法import，如下图所示。
由于Python版本不是配套版本3.10，或者pip对应的Python版本不是目标版本3.10，找不到对应的包。可以通过python和pip -v查看对应的Python版本进行确认。
使用以下命令打开bashrc文件。
[object Object]在bashrc文件内添加如下环境变量，保存并退出。
[object Object]使用以下命令使环境变量生效。
[object Object]使用以下命令建立软链接。
[object Object]
部署MindIE LLM服务时，找不到tlsCert等路径，如下图所示。
开启HTTPS服务时，未将需要的证书放到对应的目录下。
将生成服务器证书、CA证书、和服务器私钥等认证需要的文件，放置在对应的目录。
报错详细信息如下所示：
glibc.so本身的bug。
执行以下命令：
加载1300B大小的模型时耗时过长（约3个小时）。其中"B"代表"Billion"，即十亿。
未使用异步加载。
通过设置环境变量OMP_NUM_THREADS进行模型加载优化，OMP_NUM_THREADS用于设置OpenMP（Open Multi-Processing）并行编程框架的线程数量，设置后加载1300B大小的模型只要10分钟左右。
此外，使用下面命令启动NPU显存碎片收集。
多模态模型输入（image_url/video_url/audio_url）时出现类似以下报错提示：
OpenAI接口：
[object Object]vLLM接口：
[object Object]Triton接口：
[object Object]
可能输入的图片、音频或者视频是base64编码格式（Base64 编码后的数据通常是原始数据的4/3倍），导致整个message/prompt/text_input超过4MB而出现报错。
[object Object]方式一：参考接口约束
OpenAI接口：
请求参数中的messages参数下所有字段的字符数被限制为不大于4MB，详情请参见推理接口。
vLLM接口：
请求参数中的prompt参数下所有字段的字符数被限制为不大于4MB，详情请参见《MindIE LLM开发指南》中的“API接口说明 > RESTful API参考 > EndPoint业务面RESTful接口 > 兼容vLLM 0.6.4版本接口 > 文本/流式推理接口”。
Triton接口：
请求参数中的text_input参数下所有字段的字符数被限制为不大于4MB，详情请参见《MindIE LLM开发指南》中的“API接口说明 > RESTful API参考 > EndPoint业务面RESTful接口 > 兼容Triton接口 > 文本推理接口”。
[object Object]
方式二：手动修改源码
比如修改输入inputs大小的限制为10MB，代码修改示例如下所示：
图 1 示例一
图 2 示例二
多模态模型推理服务时，文件MindIE-LLM-master\examples\atb_models\atb_llm\models\qwen2_vl\flash_causal_qwen2_using_mrope.py出现类似以下报错提示：
图 1 报错信息
图 2 报错文件
图 3 报错文件
可能是concat相关的某个算子，tensor 5在某个维度上是1，与要求的维度上是2大小不一致。可能与squeeze有关，因为squeeze会去掉大小为1的维度。
示例：如果某个算子（如：concat、matmul等），希望这个维度存在并匹配某个值（如：2），那被squeeze删除后shape就会报错。
[object Object][object Object]
修改代码，如下所示：
运行Qwen2.5-VL系列模型失败并出现类似以下报错提示：
报错提示一：
[object Object]报错提示二：
[object Object]
模型配置等不支持，一般是因为安装的依赖不正确，需要安装对应的依赖文件。
[object Object]报错提示一处理方式：
根据每个模型所需依赖安装对应的requirements.txt 文件。
所有模型需要安装的通用依赖文件所在路径为：
[object Object]不同的模型对应的依赖安装文件在models路径下，比如qwen2-vl 模型：
[object Object]
安装命令如下所示：
[object Object]报错提示二处理方式：
使用以下命令排查驱动版本是否配套，驱动最低版本23.0.7才能运行，建议安装驱动版本为24.1.RC2及以上。
[object Object]初始环境变量检查下是否都已经配置好，并且已经生效。
检查系统空闲内存是否充足。
使用以下命令查看free的内存大小，需保证大于权重大小/机器数。
[object Object]根据经验，尽量保证free_mem >= (权重大小/机器数) * 1.3。
[object Object]
导入以下环境变量：
[object Object]排查多机服务化参数配置是否一致。
重启服务器，并重新启动服务。
[object Object]
纯模型推理和服务化拉起/推理时，出现各种Out of memory（OOM）报错，报错信息类似如下所示：
- 模型权重文件较大。
- 用户输入shape超大（batch size较大、过长的文本、过大的图片、音频或视频）。
- 配置文件参数配置超大。
适当调高NPU_MEMORY_FRACTION环境变量的值（代表内存分配比例，默认值为0.8），参考示例如下所示。
[object Object]适当调低服务化配置文件config.json中maxSeqLen、maxInputTokenLen、maxPrefillBatchSize、maxPrefillTokens、maxBatchSize等参数的值，主要是调整maxPrefillTokens、maxSeqLen和maxPrefillTokens参数。
- maxPrefillTokens需要大于等于maxInputToken。
- maxPrefillTokens会影响到atb初始化阶段的workspace，其值过大时拉起服务后可能直接出现Out of memory报错。
调整npuMemSize（代表单个NPU可以用来申请KV Cache的size上限，默认值为-1，表示自动分配KV Cache；大于0表示手动分配，会根据设置的值固定分配KV Cache大小）参数值。
npuMemSize = 单卡总内存 * 内存分配比例
使用更多显卡，比如当前使用2张卡，可以适当增加至4张或者8张，前提是需要确认当前模型在当前硬件中支持几张卡。
多模态模型进行推理时出现类似以下报错提示：
或者：
使用的模型在当前版本可能不支持该硬件环境。
输入shape过大，self-attention算子不支持。
使用的模型在当前版本可能不支持该硬件环境
输入shape过大，self-attention算子不支持
将服务化配置文件config.json中的maxPrefillTokens参数适当调小。
多模态模型输入image_url/video_url/audio_url格式进行推理时，出现类似以下报错提示：
image_url/video_url/audio_url参数中的值未符合指定的要求。
[object Object]Image
格式一：{"type": "image_url", "image_url": image_url}， 此类格式的image_url支持本地路径、jpg图片的base64编码、http和https协议url。
格式二：{"type": "image_url", "image_url": {"url": {image_url}}}，此类格式的image_url支持本地路径、jpg图片的base64编码、http和https协议url。
格式三：{"type": "image_url", "image_url": {"url": "file://{local_path}"}，此类格式仅支持本地路径。
格式四：{"type": "image_url", "image_url": {"url": f"data:<mime_type>/<subtype>;base64,<base64_data>"}}，此类格式仅支持base64编码，源格式可以为jpg、jpeg、png，对应的MIME如下表所示。
Video
格式一：{"type": "video_url", "video_url": video_url}， 此类格式的video_url支持本地路径、http和https协议url。
格式二：{"type": "video_url", "video_url": {"url": {video_url}}}，此类格式的video_url支持本地路径、http和https协议url。
格式三：{"type": "video_url", "video_url": {"url": "file://{local_path}"}，此类格式仅支持本地路径。
格式四：{"type": "video_url", "video_url": {"url": f"data:<mime_type>/<subtype>;base64,<base64_data>"}}，此类格式仅支持base64编码，源格式可以为mp4、avi、wmv，对应的MIME如下表所示。另，由于视频编码的后的长度可能超出MindIE Service服务化请求字符长度的最大上限，因此并不建议使用base64编码格式传输视频。
Audio
格式一：{"type": "audio_url", "audio_url": audio_url}， 此类格式的audio_url支持本地路径、http和https协议url。
格式二：{"type": "audio_url", "audio_url": {"url": {audio_url}}}，此类格式的audio_url支持本地路径、http和https协议url。
格式三：{"type": "audio_url", "audio_url": {"url": "file://{local_path}"}}，此类格式仅支持本地路径。
格式四：{"type": "audio_url", "audio_url": {"url": f"data:<mime_type>/<subtype>;base64,<base64_data>"}}，此类格式仅支持base64编码，源格式可以为mp3、wav、flac，对应的MIME如下表所示。
[object Object]undefined
格式五：{"type": "input_audio", "input_audio": {"data": f"{audio_base64}", "format": "wav"}}，当type为input_audio时，仅支持base64编码格式，源格式支持mp3、wav、flac，同时，必须通过format字段明确源格式类型。
Qwen2-VL系列模型Tokenizer报错（其他模型也有可能报错，报错无关于模型），出现类似以下报错提示：
图 1 报错提示
- 模型适配的transformers/tokenizer版本不正确。
- trust_remote_code参数配置为false。
- 服务化的config.json文件、模型权重路径和模型config.json文件权限不正确。
- 模型权重文件下可能缺少config.json文件。
- 词表文件损坏。
模型适配的transformers/tokenizer版本不正确。
确认每个模型需要安装依赖的transformers的版本，一般在模型文件的requirements.txt文件中可查看。然后查看模型权重路径下的config.json文件中的transformers版本号是否一致。
使用以下tokenizer校验方法，创建一个Python脚本，如果运行成功，则tokenizer加载无问题。
[object Object]
trust_remote_code参数配置为false。
- 将trust_remote_code参数配置为true。
服务化的config.json文件、模型权重路径和模型config.json文件权限不正确。
- 将服务化的config.json文件、模型权重路径和模型config.json文件权限修改为640。
模型权重文件下可能缺少config.json文件。
- 如果缺少config.json文件，将其补齐。
词表文件损坏。
使用以下命令检查tokenizer.json文件的完整性
[object Object]
MindIE部署Qwen2.5系列模型执行量化推理时出现以下报错信息：
或
未配置quantize字段。
[object Object]执行量化推理时，需要在量化权重所在路径的config.json文件中添加quantize字段，值为当前量化权重的量化方式，示例如下：
使用MindIE进行推理，相同输入，组batch顺序不同时，模型推理输出结果不同。
[object Object]由于matmul算子在不同行上的累加顺序不完全相同，且浮点精度没有加法交换律的特性，导致不同行上即使输入完全相同，计算结果也会存在一定的误差。
[object Object]确定性计算，是指在输入数据集等输入条件不变时，多次运行推理应用，输出结果每次保持一致。可以通过设置环境变量export ATB_MATMUL_SHUFFLE_K_ENABLE=0将加速库matmul的shuffle k功能关闭，关闭之后可以保证所有行上算子累加顺序一致，但matmul性能会下降10%左右 。
通信算子：
MatMul：
启动MindIE LLM服务时，出现Gloo连接错误，日志显示类似信息：
该错误通常出现在多机部署场景下，核心原因是Gloo组件自动选择了错误的网络接口（网卡），导致节点间通信失败。
通过环境变量显式指定Gloo使用的网络接口：
查看可用网卡： 在每个节点执行以下命令查看网卡名称：
[object Object]常见网卡命名格式：
[object Object]、[object Object]、[object Object]等设置环境变量： 在启动服务前，为每个节点设置
[object Object]环境变量：[object Object]容器部署注意事项：
- 使用Docker时，需将容器网络模式设置为
[object Object]模式 - 每个机器的网卡名称可能不同，需分别配置为本机的网卡名称
- 使用Docker时，需将容器网络模式设置为
Kubernetes部署注意事项：
- Kubernetes集群中，网卡名称通常映射为
[object Object] - 大EP部署时，可以在
[object Object]脚本中配置环境变量
- Kubernetes集群中，网卡名称通常映射为
设置完成后重新启动服务，检查是否仍出现Gloo连接错误。