#MaaS 管理员指南

本指南说明平台管理员如何管理 Model as a Service (MaaS)：发布模型服务、创建订阅、强制执行 token 配额、配置可选的 guardrails，以及查看使用情况。

有关产品概览，请参见 Model as a Service (MaaS)。有关开发人员工作流，请参见 MaaS 用户指南。

#发布平台推理服务

模型所有者可以从服务的管理页面发布一个由平台托管的推理服务。该服务必须是 LLMInferenceService。

1. 打开包含该推理服务的项目或命名空间。
2. 打开服务管理页面。
3. 在服务操作中，选择 Publish to MaaS。
4. 输入可选的显示名称和描述。
5. 单击 Publish。

发布后会创建一个 MaaS 模型引用。该模型随后会显示在管理员的 MaaS → Models → Published Models 列表中，并可添加到订阅中。

取消发布会将模型从 MaaS 目录中移除。引用该模型的现有订阅将不再能解析到它，因此请在取消发布之前，从这些订阅中移除或替换该模型。

#导入外部模型服务

当模型托管在平台外部，或者不是由 LLMInferenceService 表示时，请使用外部模型服务。

1. 在 Administrator 视图中，打开 MaaS → Models。
2. 在 Model Services 选项卡上，单击 Import External Model Service。
3. 输入该服务的小写名称。
4. 输入提供商的 OpenAI 兼容端点，并在需要时包含其 API base path。例如，当提供商要求 /v1 请求时，请使用 https://host/v1。
5. 如果提供商需要，请输入上游 API key。若端点不需要凭证，则留空。
6. 单击 Create。

API key 会存储在 Kubernetes Secret 中，并由网关在调用提供商时注入。消费者的 MaaS API key 与提供商的上游 key 是分开的凭证：开发人员只能获取 MaaS key。

#从外部服务发布模型

导入服务后：

1. 在 Model Services 选项卡上，打开该服务的操作菜单。
2. 选择 Publish Models。
3. 添加、重命名或移除该服务公开的模型名称。
4. 单击 Save。

每个已发布的模型都会成为一个可订阅的独立模型。因此，一个外部服务可以公开多个模型名称，而这些模型可以使用相同的端点和上游凭证。

Published Models 选项卡会显示模型名称、命名空间、引用目标和就绪阶段。使用类型筛选器可区分 External 模型和由 Inference Service 支持的模型。

#创建订阅

订阅是模型访问和 token 配额的单位。用户在调用某个模型之前，必须是包含该模型的订阅的订阅者。

1. 在 Administrator 视图中，打开 MaaS → Subscriptions。
2. 单击 Create Subscription。
3. 输入订阅名称。
4. 按用户名添加一个或多个订阅者。
5. 添加一个或多个已发布模型。
6. 为每个模型配置至少一个 token 限制和时间窗口。
7. 可选地为同一模型添加更多配额层级。
8. 单击 Save。

对于每个模型，表单接受以百万 token 计的限制以及一个时间窗口，例如 Minute、Hour 或 Day。例如，您可以设置每小时 100M token 和每天 1000M token。所有已配置的层级都会被强制执行。

一个订阅可以包含多个模型，并且每个模型都可以具有不同的限制。这使您无需为每个模型单独创建网关，就能提供不同的访问层级。

订阅列表会显示订阅名称、模型、订阅者和当前阶段。使用行操作菜单可以查看、编辑或删除订阅。

#配置 guardrails

MaaS 可选地使用已配置的内容 guardrails 来检查模型请求和响应。

#启用 guardrails

1. 打开 MaaS → Guardrails。
2. 单击 Edit settings。
3. 启用 guardrails。
4. 选择失败策略：
   • End request on guardrails failure (FailClosed) 会在 guardrails 引擎无法完成检查时拒绝或结束请求。
   • Ignore guardrails on failure (FailOpen) 会在 guardrails 引擎失败时允许请求继续。
5. 保存设置。

禁用 guardrails 会移除数据平面集成。即使订阅上仍保留 guardrail 设置，在全局功能被禁用时也不会生效。

#创建 guardrail 配置

1. 在 Guardrails 页面上，单击 Create Config。
2. 使用小写字母、数字和连字符输入配置 ID。
3. 配置 guardrail 模型，包括模型类型、模型名称和 base URL。
4. 为 guardrail 模型添加可选的 API key。凭证会存储为 Kubernetes Secrets，并通过环境变量暴露给 guardrails 引擎。
5. 编辑 config.yaml 内容。
6. 当配置需要 Colang flows 时，编辑 rails.co 内容。
7. 单击 Save。

一个配置可以包含多个 guardrail 模型，但在同一配置中，每种模型类型必须唯一。Guardrails 列表会显示某个配置是否已附加到订阅。

#将 guardrails 附加到订阅模型

在创建或编辑订阅时，为某个模型启用 guardrails，并选择一个可用的 guardrail 配置。该设置按模型应用，因此同一订阅中的不同模型可以使用不同的配置，或者不使用 guardrails。

#查看使用情况和报告

#订阅管理使用情况

Subscriptions 页面会显示订阅及其已配置的限制。在可用时，使用订阅的使用情况视图来查看所选订阅和模型的 token 消耗。

#使用情况报告

打开 MaaS → Report，查看管理员级别的使用情况：

1. 选择时间范围：Last 1 day、Last 7 days、Last 30 days、Last 90 days 或 Last 1 year。
2. 可选地选择一个订阅。
3. 按用户名搜索。
4. 单击刷新以重新加载数据。

报告显示以下内容：

• 用户名
• 订阅
• 总 token 数
• 输入 token
• 缓存 token
• 输出 token
• 推理 token

单击 Export CSV 可导出筛选后的报告。导出对话框允许您按订阅、用户、API key 或模型对数据分组，并按天或按月对时间分组。

使用数据旨在提供运行可见性、配额观察和 showback。它不是计费结算记录。