MaaS 用户指南
本指南介绍开发者和应用用户如何通过 Model as a Service (MaaS) 调用模型。您将了解如何创建 API key、查找可用的已发布模型、发送兼容 OpenAI 的请求,以及查看自己的配额和使用情况。
有关产品概览,请参阅 Model as a Service (MaaS)。有关管理任务,请参阅 MaaS 管理员指南。
打开“我的订阅”
- 打开 Alauda AI Platform 控制台右上角的账户菜单。
- 选择 我的订阅。
MaaS 会在当前页面上方的侧面板中打开。它与您的用户身份相关,而不是与项目命名空间相关,因此您可以从任何视图打开它。在 2.9 中,可用的模型名称是已发布模型面向客户端的名称,该名称可能不同于底层 Kubernetes 服务名称或提供商模型名称。
该面板包含两个选项卡:
- API Keys — 创建和管理 MaaS 凭证,并查找访问示例。
- Usage — 查看订阅的配额状态和个人使用情况。
查找模型和端点
在 API Keys 选项卡中,Access 部分列出了当前可供您使用的模型。每一行显示模型名称和端点。
选择一个模型以更新示例请求。使用端点或示例请求旁边的复制控件,将其复制到剪贴板。
端点通常采用以下形式:
使用访问列表中显示的已发布模型名称作为请求中的 model 值。这是管理员配置的 clientModelName。除非管理员特意将底层 Kubernetes 资源或提供商部署使用的名称设置为相同的客户端模型名称,否则不要使用这些名称。
创建 API key
- 在 API Keys 选项卡中,单击 Create API Key。
- 输入描述性 key 名称,例如
my-chatbot-dev。 - 选择要使用的订阅。
- 选择有效期。根据平台策略,您可以选择 30 天或 90 天等预设期限、自定义时长或永久 key。
- 单击 Create。
- 复制明文 key 并妥善保存。
明文 key 仅显示一次,之后无法再次获取。该对话框还会提供一个已填入新 key、可直接运行的请求。请像保护密码一样保护 key:
- 不要将其提交到源代码管理系统。
- 不要将其包含在浏览器代码或公共 notebook 中。
- 将其存储在密钥管理器或环境变量中。
- 尽可能为不同的应用创建不同的 key。
- 如果 key 可能已泄露,请立即将其撤销。
key 列表显示 key 名称、状态、订阅、创建时间和最后使用时间。key 可以处于以下状态之一:
active— 可用于调用已订阅的模型。expired— 有效期已结束。revoked— 已禁用,无法使用。
您可以 Revoke 活跃的 key。撤销后,可以将其从列表中删除。
调用模型
MaaS 提供与 OpenAI 兼容的 API。将网关 URL 和 API key 设置为环境变量:
使用 curl 发送聊天补全请求:
您也可以使用与 OpenAI 兼容的 Python 客户端:
将 <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 进行流式处理并验证完成情况:
被截断的流可能不包含最终的使用量报告。不要仅根据 HTTP 状态推断 token 消耗量或配额扣减情况;请检查平台使用量和配额视图。
如果需要针对截断情况重试,请重试整个请求。无法恢复部分传输的流。重试可能导致上游再次处理该请求,因此请在重试前评估重复处理的风险。
了解配额行为
MaaS 配额由管理员为订阅中的每个模型配置。一个订阅可以包含多个时间窗口,例如每小时限制和每日限制。
配额消耗按用户、订阅和模型进行跟踪。您的 API 密钥共享您的用户配额:
- 创建第二个 API 密钥不会重置或增加您的配额。
- 使用不同密钥发出的请求会计入同一个用户配额。
- 其他用户拥有独立的配额桶。
当配额窗口接近限制时,请减少请求量,或请求管理员检查订阅。当配额耗尽时,网关会返回 429 Too Many Requests。配额面板会显示已配置的限制、当前使用量(如果可用)以及重置时间。
查看个人使用情况
在 我的订阅 中打开 使用情况 选项卡:
- 选择一个订阅。
- 查看每个模型的配额条。
- 选择时间范围:过去 24 小时、过去 7 天 或 过去 30 天。
- 可选:按模型或 API 密钥筛选图表。
- 单击刷新以加载最新数据。
使用情况摘要包括请求数、令牌总数和缓存令牌数。图表显示一段时间内的令牌序列,包括后端提供这些值时的未缓存输入令牌、缓存输入令牌和输出令牌。
这是个人视图:仅包含使用属于您的 API 密钥发出的请求。即使您是平台其他部分的管理员,也不会显示其他用户的使用情况。
了解请求错误
模型也可能显示在访问列表中,但由于其推理服务尚未就绪而暂时不可用。如果服务应该已经就绪后请求仍持续失败,请向管理员提供模型名称和请求时间。
安全建议
- 不要将 API 密钥存放在源代码、Git 仓库、Shell 历史记录和客户端应用程序中。
- 使用满足需求的最短有效期。
- 为每个应用程序或环境使用一个密钥,这样在密钥泄露时可以将其撤销,而不会中断无关的应用程序。
- 从我的订阅中撤销未使用或已暴露的密钥。
- 切勿与外部提供商共享 MaaS API 密钥。MaaS 会在网关端处理上游提供商凭证。