#MaaS 用户指南

本指南介绍开发人员和应用用户如何通过 Model as a Service (MaaS) 调用模型。你将了解如何创建 API key、查找可用模型、发送与 OpenAI 兼容的请求，以及查看自己的配额和使用情况。

有关产品概述，请参阅 Model as a Service (MaaS)。有关管理任务，请参阅 MaaS 管理员指南。

#打开我的订阅

1. 打开 Alauda AI 控制台右上角的账户菜单。
2. 选择 My Subscriptions。

MaaS 会在当前页面上方以侧边面板的形式打开。它关联的是你的用户身份，而不是某个项目命名空间，因此你可以从任何视图中打开它。

该面板包含两个选项卡：

• API Keys — 创建和管理你的 MaaS 凭证，并查看访问示例。
• Usage — 查看某个订阅的配额状态和个人使用情况。

#查找你的模型和端点

在 API Keys 选项卡中，Access 部分列出了当前可用的模型。每一行显示模型名称和端点。

选择某个模型可更新示例请求。使用端点或示例请求旁边的复制控件将内容复制到剪贴板。

端点通常具有以下形式：

https://<maas-gateway>/v1

在请求中，将访问列表中显示的模型名称用作 model 值。除非底层 Kubernetes 资源名称同时也是已发布的模型名称，否则不要使用它。

#创建 API key

1. 在 API Keys 选项卡中，单击 Create API Key。
2. 输入一个具有描述性的 key 名称，例如 my-chatbot-dev。
3. 选择要使用的订阅。
4. 选择有效期。根据平台策略，你可以选择预设时长，例如 30 天或 90 天，自定义时长，或永久 key。
5. 单击 Create。
6. 复制明文 key 并妥善保存。

明文 key 仅显示一次，之后无法再检索。该对话框还会提供一个可直接运行的请求，其中已填入新的 key。请像对待密码一样对待该 key：

• 不要将其提交到源代码管理。
• 不要将其包含在浏览器代码或公开 notebook 中。
• 将其存储在 secret manager 或环境变量中。
• 在可能的情况下，为不同应用分别创建独立的 key。
• 如果 key 可能已泄露，请立即吊销。

key 列表会显示 key 名称、状态、订阅、创建时间和最后使用时间。key 可能具有以下状态之一：

• active — 可用于调用已订阅的模型。
• expired — 有效期已结束。
• revoked — 已被禁用，无法使用。

你可以吊销一个处于活动状态的 key。吊销后，你可以从列表中将其删除。

#调用模型

MaaS 提供与 OpenAI 兼容的 API。将网关 URL 和 API key 设置为环境变量：

export MAAS_ENDPOINT="https://<maas-gateway>/v1"
export MAAS_API_KEY="<your-api-key>"

使用 curl 发送聊天补全请求：

curl "${MAAS_ENDPOINT}/chat/completions" \
  -H "Authorization: Bearer ${MAAS_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<published-model-name>",
    "messages": [
      {"role": "user", "content": "Hello"}
    ]
  }'

你也可以使用与 OpenAI 兼容的 Python client：

from openai import OpenAI

client = OpenAI(
    base_url="https://<maas-gateway>/v1",
    api_key="<your-api-key>",
)

response = client.chat.completions.create(
    model="<published-model-name>",
    messages=[{"role": "user", "content": "Hello"}],
)

print(response.choices[0].message.content)

将 <published-model-name> 替换为 Access 列表中显示的模型名称。MaaS 网关会选择与该已发布模型名称关联的后端；你的应用无需知道后端服务 URL。

#理解配额行为

MaaS 配额由管理员针对你订阅中的每个模型进行配置。一个订阅可以包含多个时间窗口，例如按小时限制和按天限制。

配额消耗按用户、订阅和模型分别跟踪。你的 API key 共享同一个用户配额：

• 创建第二个 API key 不会重置或增加你的配额。
• 使用不同 key 发出的请求会计入同一用户额度。
• 其他用户拥有独立的配额桶。

当某个配额窗口接近上限时，请降低请求量，或请管理员检查该订阅。当配额耗尽时，网关会返回 429 Too Many Requests。配额面板会显示已配置的限制、当前使用量（如可用）以及重置时间。

#查看个人使用情况

在 My Subscriptions 中打开 Usage 选项卡：

1. 选择一个订阅。
2. 查看按模型划分的配额条形图。
3. 选择时间范围：Last 24 hours、Last 7 days 或 Last 30 days。
4. 可选：按模型或 API key 过滤图表。
5. 单击刷新以加载最新数据。

使用摘要包括请求数、总 tokens 和缓存 tokens。图表显示随时间变化的 token 序列，包括未缓存输入、缓存输入以及输出 tokens，前提是后端提供这些值。

这是一个个人视图：它只包含使用属于你的 API key 发出的请求。它不会显示其他用户的使用情况，即使你在平台的其他部分是管理员也不例外。

#理解请求错误

当某个模型的 inference service 尚未就绪时，它也可能会在访问列表中可见，但暂时不可用。如果在服务应已就绪后请求仍持续失败，请将模型名称和请求时间提供给管理员。

#安全建议

• 将 API key 远离源代码、Git 仓库、shell 历史记录和客户端应用。
• 使用满足需求的最短有效期。
• 为每个应用或环境使用一个 key，这样在某个 key 泄露时，可以将其吊销而不影响无关应用。
• 在 My Subscriptions 中吊销未使用或已暴露的 key。
• 切勿将 MaaS API key 与外部提供商共享。MaaS 会在网关侧处理上游提供商凭证。