推理后端管理

GPUStack 允许管理员配置推理后端及后端版本。

本文是 Inference Backend 页面的操作指南。内置后端及其支持的能力，参见内置推理后端。

自定义后端的配置指导和经过验证可用的示例，参见自定义推理后端。

后端来源

GPUStack 支持三类推理后端：

• Built-in：GPUStack 维护的预配置后端（例如 vLLM、MindIE、VoxBox），不可删除。
• Community：社区后端市场共享的后端，可按需启用。
• Custom：通过自己的配置创建的后端，可自由添加、编辑和删除。

内置和社区列表可通过 OTA 更新，无需升级 GPUStack。也可以将任一列表指向自己维护的文档。参见 OTA 内容更新。

参数说明

环境变量

可以在两个层级定义环境变量：

• 后端级（Default Environment Variables）：适用于此后端的所有版本。
• 版本级（Environment Variables）：特定于某个版本，覆盖后端级变量。

可以通过 {{VAR_NAME}} 语法在命令中引用环境变量。

示例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

backend_name: my-backend-custom
default_env:
  MODEL_CACHE_DIR: /cache
  LOG_LEVEL: info
version_configs:
  v1:
    image_name: my-image:v1
    custom_framework: cuda
    run_command: "serve {{model_path}} --cache {{MODEL_CACHE_DIR}} --log-level {{LOG_LEVEL}} --port {{port}}"
    env:
      MODEL_CACHE_DIR: /custom-cache # Overrides backend-level value

此示例中：

• MODEL_CACHE_DIR 在后端级设置为 /cache。
• 版本 v1 将它覆盖为 /custom-cache。
• 所有版本的 LOG_LEVEL 都保持为 info。
• 两个变量都通过 {{VAR_NAME}} 语法在命令中引用。

Version Configs 参数说明：

参数格式

Flag Format 控制 GPUStack 组装后端启动命令时，各个 --key value 参数对的呈现方式。它在后端级配置，适用于使用此后端的所有模型部署，并在 Worker 组装容器启动命令时生效。

可用值：

• Space Separated (--key value)：以空格分隔，呈现为 --key value。
• Equal Sign (--key=value)：以 = 连接，呈现为 --key=value。
• 留空（默认）：不进行规范化，保留 Backend Parameters 中输入的原样参数。

如果推理引擎的命令行解析器只接受其中一种形式，可用此字段强制采用一致的参数风格，无需逐个手动改写参数。

示例：

将后端的 Flag Format 设为 Equal Sign (--key=value) 后，使用此后端的部署若具有以下 Backend Parameters：

1

--tensor-parallel-size 2 --max-model-len 8192 --lora-modules a=/path1 b=/path2

启动命令会被规范化为：

1

vllm serve Qwen/Qwen3.5-0.8B --tensor-parallel-size=2 --max-model-len=8192 --lora-modules a=/path1 b=/path2

--tensor-parallel-size 和 --max-model-len 转换为等号形式，--lora-modules 因包含多个值，仍保留空格分隔形式。

添加自定义推理后端

1. 单击右上角的 "Add Backend" 按钮。
2. 可以填写表单或粘贴 YAML 定义来添加自定义推理后端。字段含义参见上方参数说明。
3. 后端名称创建后不可修改。自定义后端名称必须以 "-custom" 结尾（表单已预填）。
4. 单击 "Save" 提交。

添加自定义推理后端有两种方式：

• 通过 UI 表单：进入 Model Service > Inference Backends 页面，单击 Add Custom Inference Backend 按钮。
• 通过 YAML 配置：导入包含后端配置的 YAML 文件。

启用社区推理后端

这些后端本质上是带有 "community" 来源标签的自定义后端，让你无需手动配置即可快速创建自定义后端。

1. 在 Inference Backend 页面，单击右上角的 "Add Backend" 按钮。
2. 选择 "Community"，浏览市场中的可用社区后端。
3. 找到要使用的后端，在卡片操作菜单中单击 "Enable"。
4. 启用后，该后端即可用于模型部署。要禁用它，请从 Inference Backend 页面删除此后端。

编辑推理后端或添加自定义版本

1. 在 Inference Backend 页面找到目标后端，从卡片右上角的下拉菜单中选择 "Edit"。
2. 修改后端属性（名称不可更改），或添加新版本。
3. 对于内置后端，自定义版本必须以 "-custom" 结尾（表单已预填）。
4. 单击 "Save" 提交。

示例：为内置 vLLM 推理后端添加自定义版本

1. 在 Inference Backend 页面找到 vLLM 推理后端，从卡片右上角的下拉菜单中选择 "Edit"。
2. 在 Version Configs 部分单击 "Add Version"。
3. 按以下方式填写字段：

• Version：0.19.0
• Image Name：vllm/vllm-openai:v0.19.0
• Framework：cuda
• Override Image Entrypoint：vllm serve
• Execution Command：{{model_path}} --host {{worker_ip}} --port {{port}} --served-model-name {{model_name}}

4. 单击 "Save" 提交。

示例：为内置 SGLang 推理后端添加自定义版本

1. 在 Inference Backend 页面找到 SGLang 推理后端，从卡片右上角的下拉菜单中选择 "Edit"。
2. 在 Version Configs 部分单击 "Add Version"。
3. 按以下方式填写字段：

• Version：0.5.10
• Image Name：lmsysorg/sglang:v0.5.10
• Framework：cuda
• Override Image Entrypoint：sglang serve
• Execution Command：--model-path {{model_path}} --host {{worker_ip}} --port {{port}}

4. 单击 "Save" 提交。

删除自定义推理后端

1. 在 Inference Backend 页面找到目标后端，从卡片右上角的下拉菜单中选择 "Delete"。
2. 内置后端不可删除。
3. 在确认对话框中单击 "Delete"。

列出推理后端版本

在 Inference Backend 页面单击后端卡片任意位置（操作按钮除外），打开弹窗，浏览所有内置版本和自定义添加的版本。

灵活测试部署

使用此模式可以快速验证或调整镜像和启动命令，无需编辑后端定义。

1. 进入 Deployments 页面，单击 "Deploy Model" 按钮，选择任意模型来源。
2. 在 Basic 选项卡中打开 "Backend" 下拉菜单，从 "Built-in" 部分选择 "Custom"。
3. 将出现两个字段：image_name 和 run_command。它们仅为本次部署覆盖后端配置。
4. 检查其余必填设置并提交部署。

自定义推理后端的限制

自定义推理后端不支持跨多个 Worker 的分布式推理。