MaaS 用户指南

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

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

打开“我的订阅”

  1. 打开 Alauda AI Platform 控制台右上角的账户菜单。
  2. 选择 我的订阅。

MaaS 会在当前页面上方的侧面板中打开。它与您的用户身份相关,而不是与项目命名空间相关,因此您可以从任何视图打开它。在 2.9 中,可用的模型名称是已发布模型面向客户端的名称,该名称可能不同于底层 Kubernetes 服务名称或提供商模型名称。

该面板包含两个选项卡:

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

查找模型和端点

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

选择一个模型以更新示例请求。使用端点或示例请求旁边的复制控件,将其复制到剪贴板。

端点通常采用以下形式:

https://<maas-gateway>/v1

使用访问列表中显示的已发布模型名称作为请求中的 model 值。这是管理员配置的 clientModelName。除非管理员特意将底层 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 中。
  • 将其存储在密钥管理器或环境变量中。
  • 尽可能为不同的应用创建不同的 key。
  • 如果 key 可能已泄露,请立即将其撤销。

key 列表显示 key 名称、状态、订阅、创建时间和最后使用时间。key 可以处于以下状态之一:

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

您可以 Revoke 活跃的 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 客户端:

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 或提供商模型名称。

流式响应和完成检查

设置 "stream": true 后,MaaS 会以由 data: 行组成的 Server-Sent Events (SSE) 流返回答案,并以 data: [DONE] 哨兵结束。如果流在中途被截断——无论是因为上游模型停止发送,还是因为客户端断开连接——HTTP 状态仍为 200,因为响应标头已在内容被截断前发送。仅凭状态代码无法判断流是否已完成。

使用 [DONE] 哨兵检查完整性:完整的流以 data: [DONE] 结束;被截断的流不会发出该哨兵。

使用 OpenAI SDK:

  • Python / Node.js:迭代流直到结束,并检查最后一个块。完整流的最后一个块会将 finish_reason 设置为 stop、length 或 content_filter 等终止值;值为 null 或缺少块,表示流未正常结束。
  • 在请求中添加 stream_options={"include_usage": True}。完整流的最后一个块包含 usage 块;被截断的流没有此类块。

使用 curl 时,读取每一行,直到看到 data: [DONE]。如果在该行到达之前连接关闭,则响应不完整。

示例 — 使用 Python 进行流式处理并验证完成情况:

from openai import OpenAI

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

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

final = None
for chunk in stream:
    final = chunk
    if chunk.choices:
        delta = chunk.choices[0].delta
        if delta and delta.content:
            print(delta.content, end="", flush=True)

complete = final is not None and getattr(final, "usage", None) is not None
if not complete:
    # Treat as a truncated stream: retry, log, or surface a warning.
    ...

被截断的流可能不包含最终的使用量报告。不要仅根据 HTTP 状态推断 token 消耗量或配额扣减情况;请检查平台使用量和配额视图。

如果需要针对截断情况重试,请重试整个请求。无法恢复部分传输的流。重试可能导致上游再次处理该请求,因此请在重试前评估重复处理的风险。

了解配额行为

MaaS 配额由管理员为订阅中的每个模型配置。一个订阅可以包含多个时间窗口,例如每小时限制和每日限制。

配额消耗按用户、订阅和模型进行跟踪。您的 API 密钥共享您的用户配额:

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

当配额窗口接近限制时,请减少请求量,或请求管理员检查订阅。当配额耗尽时,网关会返回 429 Too Many Requests。配额面板会显示已配置的限制、当前使用量(如果可用)以及重置时间。

查看个人使用情况

在 我的订阅 中打开 使用情况 选项卡:

  1. 选择一个订阅。
  2. 查看每个模型的配额条。
  3. 选择时间范围:过去 24 小时、过去 7 天 或 过去 30 天。
  4. 可选:按模型或 API 密钥筛选图表。
  5. 单击刷新以加载最新数据。

使用情况摘要包括请求数、令牌总数和缓存令牌数。图表显示一段时间内的令牌序列,包括后端提供这些值时的未缓存输入令牌、缓存输入令牌和输出令牌。

这是个人视图:仅包含使用属于您的 API 密钥发出的请求。即使您是平台其他部分的管理员,也不会显示其他用户的使用情况。

了解请求错误

状态含义操作
401 UnauthorizedAPI 密钥缺失、无效、已过期或已撤销。检查 Authorization 标头,并在必要时创建新密钥。
403 Forbidden您无权访问请求的模型,或没有适用的订阅。确认模型名称,并联系 MaaS 管理员。
429 Too Many Requests用户、模型或时间窗口的订阅配额已耗尽。等待配额重置,或请求管理员检查限制。
5xx网关或模型后端遇到错误。适时重试;如果问题持续存在,请联系平台管理员。

模型也可能显示在访问列表中,但由于其推理服务尚未就绪而暂时不可用。如果服务应该已经就绪后请求仍持续失败,请向管理员提供模型名称和请求时间。

安全建议

  • 不要将 API 密钥存放在源代码、Git 仓库、Shell 历史记录和客户端应用程序中。
  • 使用满足需求的最短有效期。
  • 为每个应用程序或环境使用一个密钥,这样在密钥泄露时可以将其撤销,而不会中断无关的应用程序。
  • 从我的订阅中撤销未使用或已暴露的密钥。
  • 切勿与外部提供商共享 MaaS API 密钥。MaaS 会在网关端处理上游提供商凭证。