跳转至正文

llm-d-modelservice

ModelService 是一个 Helm chart，通过以声明式方式管理用于基础模型服务的 Kubernetes 资源，简化了在 llm-d 上的 LLM 部署。它通过模块化预设实现可复现、可扩展且可调优的模型部署，并与 llm-d 生态系统组件（包括 vLLM、Gateway API Inference Extension、LeaderWorkerSet）无缝集成。它为部署、基准测试和调优 LLM 推理工作负载提供了一条极具见地且灵活的路径。

ModelService Helm Chart 提案于 2025 年 6 月 10 日获得批准。阅读更多关于路线图、动机和其他考虑过的替代方案的信息，请点击此处。

内容摘要

支持的活跃场景

  • P/D 分离（Prefill/Decode disaggregation）
  • 多节点推理，利用数据并行
  • 每个 DP 秩（rank）一个 pod

与 llm-d 组件集成

  • llm-d-infra 中的快速入门指南依赖于 ModelService
  • 灵活配置 llm-d-inference-scheduler 进行路由
  • 在 P/D 分离中使用 llm-d-routing-sidecar
  • 用于 llm-d-benchmark 中的基准测试实验
  • 针对仅 CPU 工作负载轻松使用 llm-d-inference-sim
  • 允许使用 llm-d-fast-model-actuation。关于快速模型加载技术的更多信息请见此处

快速入门​

将此仓库添加到 Helm。

helm repo add llm-d-modelservice https://llm-d-incubation.github.io/llm-d-modelservice/
helm repo update

ModelService 运行的前提是已在 Kubernetes 集群中安装了 llm-d-infra，它会安装所需的必备组件和 CRD。阅读 llm-d 指南以获取更多信息。

路由​

模型部署后，推理请求必须路由到该模型。为此，可以使用 Kubernetes Gateway API Inference Extension (GAIE) Helm charts。这些 charts 的定义在此处。例如，要创建一个 InferencePool，请使用 chart oci://registry.k8s.io/gateway-api-inference-extension/charts/inferencepool。

关联关系​

请注意，当同时使用 GAIE inferencepool chart 和 modelservice chart 时，将存在以下关系：

  • modelservice 字段 modelArtifact.routing.servicePort 应与 GAIE 字段 inferencePool.targetPortNumber 匹配，或者是 inferencePool.targets 列表中的一个条目（取决于 InferencePool 的 apiVersion）。
  • modelservice 字段 modelArtifact.labels 应匹配 GAIE 字段 inferencePool.modelServers.matchLabels。请注意，除了 modelArtifacts.labels 字段中指定的标签外，还会添加 llm-d.ai/role 字段。

HTTPRoute​

除了部署 GAIE chart 之外，通常还需要一个 HTTPRoute 来将 Gateway 连接到 InferencePool。创建 HTTPRoute 不属于这两个 chart 的范畴。一些示例请见此处。

示例​

有关如何使用此 Helm chart，请参阅示例。某些示例包含网关名称等组件的占位符。使用 --set 标志来覆盖占位符。例如，

helm install cpu-only llm-d-modelservice -f examples/values-cpu.yaml --set prefill.replicas=0 --set "routing.parentRefs[0].name=MYGATEWAY"

查看 Helm 的官方文档以获取更多指导。

配置项（Values）​

以下是您可以设置的配置项。

键描述类型默认值
modelArtifacts.name模型名称，格式为 namespace/modelId。必填。string无
modelArtifacts.uri模型权重 URI。当前支持的格式包括 hf://、pvc:// 和 oci://string无
modelArtifacts.size用于创建下载模型所需的 emptyDir 卷的大小。string无
modelArtifacts.authSecretName对于下载需要令牌的 hf:// 权重，包含 HF_TOKEN 的 Secret 名称。string无
modelArtifacts.mountPath挂载为存储模型而创建的卷的路径string/model-cache
multinode决定使用 Deployments (false) 还是 LeaderWorkerSets (true) 来创建 P/Dboolfalse
routing.servicePort路由代理边车（sidecar）监听的端口。
如果没有边车，则这是请求发送到的端口。		int无
routing.proxy.image边车使用的镜像stringghcr.io/llm-d/llm-d-routing-sidecar:0.0.6
routing.proxy.targetPortvLLM 解码（decode）容器监听的端口。
如果存在代理，它将把请求转发到此端口。		string无
routing.proxy.debugLevel路由代理的调试级别int5
routing.proxy.parentRefs[*].name推理网关的名称string无
decode.create如果为 true，则创建 decode Deployment 或 LeaderWorkerSetListtrue
decode.annotations应添加到 Deployment 或 LeaderWorkerSet 的注解（Annotations）Dict
decode.tolerations应添加到 Deployment 或 LeaderWorkerSet 的容忍度（Tolerations）List[]
decode.replicas解码 pod 的副本数int1
decode.extraConfig额外的 pod 配置dict
decode.containers[*].namedecode deployment/LWS 的容器名称string无
decode.containers[*].imagedecode deployment/LWS 的容器镜像string无
decode.containers[*].argsdecode 容器的参数列表。List[string][]
decode.containers[*].modelCommand命令的性质。可选 vllmServe、imageDefault 或 customstringimageDefault
decode.containers[*].commanddecode 容器的命令列表。List[string][]
decode.containers[*].portsdecode 容器的端口列表。List[Port][]
decode.containers[*].extraConfig额外的容器配置dict
decode.initContainers.应添加的初始化容器列表（如果启用，则在路由代理之外添加）List[Container]无
decode.parallelism.tensor张量并行度int1
decode.parallelism.data数据并行度int1
decode.parallelism.dataLocal局部数据并行度int1
decode.parallelism.workers实现数据并行的工作节点数量int1
decode.acceleratorTypes.labelKey节点上标识所承载 GPU 类型的标签键string无
decode.acceleratorTypes.labelValue节点上标识所承载 GPU 类型的标签值string无
prefill支持与 decode 相同的字段见上文见上文
extraObjects随主应用程序一起部署的其他 Kubernetes 对象List[]

加速器资源配置​

该 chart 根据并行度设置自动计算加速器资源（例如 nvidia.com/gpu、google.com/tpu）。但是，您可以通过在容器规范中显式设置资源来覆盖此设置。

优先级

  1. 如果您在容器规范中显式设置了 resources.limits.<accelerator>，则使用该值
  2. 否则，该值将根据 parallelism.tensor * parallelism.dataLocal 自动计算。如果您使用此策略，vLLM 并行参数（如 --tensor-parallel-size 和 --data-parallel-size-local）及其对应值将自动添加到第一个容器中

示例 - 自动计算（默认）

decode:
  parallelism:
    tensor: 4
  containers:
    - name: vllm
      # nvidia.com/gpu will be auto-set to 4

示例 - 用户覆盖

decode:
  parallelism:
    tensor: 8  # Used for --tensor-parallel-size
  containers:
    - name: vllm
      resources:
        limits:
          google.com/tpu: "4"  # Explicitly set (TPUs: TP=8 needs 4 TPUs)

这对于 TPU 等加速器非常有用，因为这些加速器的张量并行度并不等于加速器的数量。

贡献​

我们欢迎对 llm-d-modelservice 做出贡献！请参阅我们的贡献指南，了解有关如何为本项目做出贡献的详细信息，包括提交 issue、拉取请求（pull request）以及开发环境搭建的准则。

随着项目的不断演进，如果您发现无法满足您的使用场景，请开启 ticket。

联系方式​

在 llm-d Slack 工作区的 #sig-model-service 频道参与讨论或提问！有关如何加入工作区的详细信息可以在此处找到。

内容来源

此内容自动从 llm-d-incubation/llm-d-modelservice 仓库 main 分支下的 README.md 同步。

📝 如需建议更改，请编辑源文件或创建 issue。