Kubeflow KFServing中访问Swagger UI的配置要点

问题背景

在使用Kubeflow KFServing部署机器学习推理服务时，开发者经常需要通过Swagger UI来测试和验证API接口。然而，许多用户会遇到访问Swagger UI时返回404 Not Found错误的情况。

核心问题分析

通过分析用户案例，我们发现主要问题出在访问路径的配置上。用户尝试通过/docs路径访问Swagger UI，但实际上MLServer（KFServing默认使用的推理服务器）的Swagger UI位于/v2/docs路径下。

解决方案详解

1. 正确的Swagger UI访问路径

对于使用MLServer作为推理后端的模型服务（如sklearn模型），Swagger UI的标准访问路径应该是：

http://<your-inference-service-url>/v2/docs

而不是用户尝试的/docs路径。

2. InferenceService配置示例

以下是正确配置支持Swagger UI的InferenceService YAML示例：

apiVersion: "serving.kserve.io/v1beta1"
kind: "InferenceService"
metadata:
  name: "sklearn-iris"
  namespace: kubeflow-user-example-com
spec:
  predictor:
    model:
      args: ["--enable_docs_url=True"]
      modelFormat:
        name: sklearn
      storageUri: "gs://kfserving-examples/models/sklearn/1.0/model"

关键配置项说明：

• args: ["--enable_docs_url=True"]：显式启用Swagger UI文档功能
• modelFormat.name: sklearn：指定使用sklearn模型格式，这会默认使用MLServer作为推理后端

3. 访问流程

1. 部署上述InferenceService后，等待服务状态变为Ready
2. 获取服务的访问URL（通常通过Kubeflow UI或kubectl命令）
3. 在浏览器中访问http://<service-url>/v2/docs

技术原理

MLServer作为KFServing支持的推理服务器之一，遵循V2数据平面协议。其OpenAPI文档默认挂载在/v2/docs路径下，这是MLServer的标准配置。当启用--enable_docs_url=True参数时，服务器会加载Swagger UI资源并使其可通过该路径访问。

常见问题排查

如果按照上述步骤仍然无法访问Swagger UI，建议检查以下方面：

1. 确认服务已成功部署并处于Ready状态
2. 检查网络策略是否允许访问/v2/docs路径
3. 查看Pod日志确认MLServer是否正常启动
4. 验证Ingress或Istio路由配置是否正确

总结

正确访问KFServing中MLServer的Swagger UI需要理解两个关键点：一是必须使用/v2/docs路径而非/docs，二是需要在InferenceService配置中显式启用文档功能。掌握这些要点后，开发者可以更高效地测试和验证机器学习推理服务的API接口。