模型服务调试指南

本文演示了在使用模型服务终结点时用户可能会遇到的常见问题的调试步骤。 常见问题可能包括用户在终结点无法初始化或启动时遇到的错误、与容器相关的生成失败，或者在操作期间或在终结点上运行模型时出现的问题。

访问和查看日志

Databricks 建议查看生成日志，以便调试和排查模型服务工作负载中的错误。 有关日志以及如何查看日志的信息，请参阅监视模型质量和终结点运行状况。

查看工作区 UI 中模型的事件日志，并检查是否有成功的容器生成消息。 如果一小时后未看到生成消息，请联系 Databricks 支持人员以获取帮助。

如果生成成功，但遇到其他错误，请参阅容器生成成功后的调试。 如果生成失败，请参阅容器生成失败后的调试。

已安装的库包版本

在生成日志中，可以确认已安装的包版本。

• 对于 MLflow 版本，如果没有指定版本，模型服务将使用最新版本。
• 对于自定义 GPU 服务，模型服务会根据公共 PyTorch 和 Tensorflow 文档安装推荐的 cuda 和 cuDNN 版本。

需要 flash-attn 的日志模型

如果你在记录需要 flash-attn 的模型，Databricks 建议使用自定义滚轮版本 flash-attn。 否则，可能会导致生成 ModuleNotFoundError: No module named 'torch' 错误。

若要使用自定义滚轮版本 flash-attn，请将所有 pip 要求指定为列表，并将其作为参数 mlflow.transformers.log_model 传递到函数中。 你还必须指定与 flash attn 滚轮中指定的 CUDA 版本兼容的 pytorch、torch 和 torchvision 版本。

例如，Databricks 建议对 CUDA 11.8 使用以下版本和轮子：

• Pytorch
• Torch 2.0.1+cu118
• Torchvision 0.15.2+cu118
• Flash-Attn

logged_model=mlflow.transformers.log_model(
transformers_model=test_pipeline,
       artifact_path="artifact_path",
       pip_requirements=["--extra-index-url https://download.pytorch.org/whl/cu118", "mlflow==2.13.1", "setuptools<70.0.0", "torch==2.0.1+cu118", "accelerate==0.31.0", "astunparse==1.6.3", "bcrypt==3.2.0", "boto3==1.34.39", "configparser==5.2.0", "defusedxml==0.7.1", "dill==0.3.6", "google-cloud-storage==2.10.0", "ipython==8.15.0", "lz4==4.3.2", "nvidia-ml-py==12.555.43", "optree==0.12.1", "pandas==1.5.3", "pyopenssl==23.2.0", "pytesseract==0.3.10", "scikit-learn==1.3.0", "sentencepiece==0.1.99", "torchvision==0.15.2+cu118", "transformers==4.41.2", "https://github.com/Dao-AILab/flash-attention/releases/download/v2.5.8/flash_attn-2.5.8+cu118torch2.0cxx11abiFALSE-cp311-cp311-linux_x86_64.whl"],
       input_example=input_example,
       registered_model_name=registered_model_name)

部署模型之前的验证检查

Databricks 建议在为模型提供服务之前应用本部分中的指南。 以下参数可以在等待终结点之前提前捕获问题。 在 部署之前，请参阅“验证模型输入 ”，以在部署模型之前验证模型输入。

部署前测试预测

在将模型部署到服务终结点之前，请使用虚拟环境并使用 mlflow.models.predict 输入示例测试脱机预测。 请参阅 MLflow 文档 以获取有关测试预测的更详细指导。

input_example = {
                  "messages":
                  [
                    {"content": "How many categories of products do we have? Name them.", "role": "user"}
                  ]
                }

mlflow.models.predict(
   model_uri = logged_chain_info.model_uri,
   input_data = input_example,
)

在部署之前验证模型输入

模型服务终结点需要特殊格式的 json 输入来验证模型输入在部署前是否适用于服务终结点。 可以在 MLflow 中使用 validate_serving_input 来执行此类验证。

下面是如果您的模型配有有效输入示例进行记录时，在运行过程的工件选项卡中自动生成的代码示例。

from mlflow.models import validate_serving_input

model_uri = 'runs:/<run_id>/<artifact_path>'

serving_payload = """{
 "messages": [
   {
     "content": "How many product categories are there?",
     "role": "user"
   }
 ]
}
"""

# Validate the serving payload works on the model
validate_serving_input(model_uri, serving_payload)

还可以使用 convert_input_example_to_serving_input API 针对记录的模型测试任何输入示例，以生成有效的 json 服务输入。

from mlflow.models import validate_serving_input
from mlflow.models import convert_input_example_to_serving_input

model_uri = 'runs:/<run_id>/<artifact_path>'

# Define INPUT_EXAMPLE with your own input example to the model
# A valid input example is a data instance suitable for pyfunc prediction

serving_payload = convert_input_example_to_serving_input(INPUT_EXAMPLE)

# Validate the serving payload works on the model
validate_serving_input(model_uri, serving_payload)

容器生成成功后的调试

即使容器成功生成，运行模型时或在终结点本身操作期间也可能存在问题。 以下小节详细介绍了常见问题以及如何进行故障排除和调试

缺少依赖项

可能会收到类似 An error occurred while loading the model. No module named <module-name>. 的错误。 此错误可能表明容器缺少依赖项。 验证是否正确表示了容器生成中应包含的所有依赖项。 请特别注意自定义库，并确保 .whl 文件作为项目包含在内。

服务日志循环

如果容器生成失败，请检查服务日志，以查看终结点尝试加载模型时是否注意到它们循环。 如果看到此行为，请尝试下面的步骤：

1. 打开笔记本并附加到使用 Databricks Runtime 版本的 All-Purpose 群集，而不是用于机器学习的 Databricks Runtime。
2. 使用 MLflow 加载模型并尝试从那里进行调试。

还可以在电脑本地加载模型，并从那里进行调试。 使用以下内容在本地加载模型：

import os
import mlflow

os.environ["MLFLOW_TRACKING_URI"] = "databricks://PROFILE"

ARTIFACT_URI = "model_uri"
if '.' in ARTIFACT_URI:
    mlflow.set_registry_uri('databricks-uc')
local_path = mlflow.artifacts.download_artifacts(ARTIFACT_URI)
print(local_path)

conda env create -f local_path/artifact_path/conda.yaml
conda activate mlflow-env

mlflow.pyfunc.load_model(local_path/artifact_path)

将请求发送到终结点时模型失败或超时

在模型上调用 Encountered an unexpected error while evaluating the model. Verify that the input is compatible with the model for inference. 时，可能会收到类似于 predict() 的错误。

predict() 函数中存在代码问题。 Databricks 建议在笔记本中加载 MLflow 中的模型并调用它。 这样做会突出显示 predict() 函数中的问题，并且你可以看到方法中发生失败的位置。

失败请求的根本原因分析

如果对终结点的请求失败，可以使用推理表执行根本原因分析。 推理表会自动记录 Unity 目录表中终结点的所有请求和响应，以便进行查询。

• 有关外部模型、预配的吞吐量工作负载和 AI 代理，请参阅使用启用了 AI 网关的推理表监视提供的模型。

• 有关自定义模型，请参阅 推理表来监视和调试模型。

查询推理表：

1. 在您的工作区中，转到服务选项卡并选择您的终端名称。
2. 在 “推理表 ”部分中，找到推理表的完全限定名称。 例如，my-catalog.my-schema.my-table。
3. 在 Databricks 笔记本中运行以下命令：

   %sql
   SELECT * FROM my-catalog.my-schema.my-table
   

4. 在诸如request、response、request_time以及status_code等列上查看和筛选，以了解请求并缩小结果范围。

   %sql
   SELECT * FROM my-catalog.my-schema.my-table
   WHERE status_code != 200
   

5. 如果为 AI 代理启用了代理跟踪，请参阅 “响应 ”列以查看详细跟踪。 请参阅 为 AI 代理启用推理表。

工作区超过了配置的并发容量

可能会收到 Workspace exceeded provisioned concurrency quota 错误。

可以根据区域可用性增加并发性。 联系 Databricks 帐户团队，并提供工作区 ID 以请求提高并发性。

容器生成失败后的调试

本节详细介绍了构建失败时可能会出现的问题。

OSError: [Errno 28] No space left on device

No space left 错误可能是由于不必要地记录与模型一起记录的过多大型项目。 在 MLflow 中检查是否没有与模型一起记录无关的工件，并尝试重新部署精简后的包。

Azure 防火墙在从 Unity Catalog 部署模型时存在问题

你可能会看到错误： Build could not start due to an internal error. If you are serving a model from UC and Azure Firewall is enabled, this is not supported by default.

请联系 Databricks 客户团队来帮助解决。

由于缺乏 GPU 可用性而导致生成失败

你可能会看到错误：Build could not start due to an internal error - please contact your Databricks representative.。

请联系 Databricks 客户团队来帮助解决。