通过

模型服务调试指南

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

：：：tip 在调试之前验证部署问题？ 从 部署前验证 开始，在常见问题发生之前捕获常见问题。 :::

调试容器构建

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

工作区 UI 中的事件日志（单击 “事件 ”选项卡）包含有关容器生成进度的信息。 成功构建容器通过事件类型SERVED_ENTITY_CONTAINER_EVENT及消息Container image creation finished successfully进行突出显示。 如果在创建终结点一小时后看不到任何生成事件或消息，请联系 Databricks 支持人员以获取帮助。

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

容器生成成功后进行调试

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

注释

如果模型代码返回 MlflowException 错误，预期响应代码将映射到 4xx 响应。 Databricks 将这些模型代码错误视为客户引起的错误，因为它们可以根据生成的错误消息来解决。 5xx 错误代码专用于表示由 Databricks 导致的错误。

缺少依赖项

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

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

在模型上调用 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 目录表中的终结点，以便进行查询。

查询推理表：

  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 以请求提高并发性。

工作区超过并行请求限制

可能会收到以下 HTTP 429 错误： Exceeded max number of parallel requests. Please contact your Databricks representative to increase the limit 此限制表示已达到可并行发送的最大请求数的工作区限制。 有关此 限制的详细信息，请参阅模型服务限制和区域 。

Databricks 建议移动到 路由优化终结点，其中已删除此限制。 如果无法移动到路由优化的终结点，可以减少发送推理请求的客户端数，或联系 Databricks 代表，以增加配额。

并发请求过多

可能会收到以下 429 错误： Too many concurrent requests. Consider increasing the provisioned concurrency of the served entity. 此错误表示终结点的当前预配并发无法处理传入流量。 如果已为终结点启用自动缩放，系统将自动预配额外的并发性，使其达到终结点配置的限制，以处理增加的负载。 如果未启用自动缩放，请考虑手动增加预配的并发性或启用自动缩放来处理流量高峰。

容器生成失败后调试

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

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 可用性而导致生成失败

由于 GPU 提供和可用性方面的限制，GPU 生成可能会失败，并出现以下错误： Build could not start due to an internal error - please contact your Databricks representative.

请联系 Databricks 客户团队来帮助解决。 根据区域可用性，团队可以预配更多 GPU 资源。

已安装的库包版本

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 使用以下版本和轮子：


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)
  • Last updated on