用户手册

用户手册

> 面向用平台调用大模型的开发者与终端用户：从账号登录、申请 API 密钥、发起第一次 OpenAI 兼容调用，到核对用量账单与排查常见错误码，完整覆盖调用侧全生命周期，是大模型接入的一本通。

1. 账号与登录

平台不向个人发放体验账号，账号有两个来源：平台管理员开户（账号密码登录）与企业统一身份（登录页提供的 CAS / LDAP 等统一登录入口，以登录页实际显示为准）。

用统一身份首次登录成功后，平台会自动为您创建账号（JIT 开户），并按身份系统返回的信息同步部门、角色与所属租户——无需任何人手工开号。此后每次登录都会重新同步组织信息：若您在身份系统中被停用，再次登录将被拒绝。登录被锁、遗忘密码或统一登录页报错，请联系平台管理员；统一认证页面的报错多出在贵司身份系统侧，先确认账号状态再重试。组织同步机制详见多租户与 SSO。

2. 登录后的界面

普通用户登录后进入开发者门户。平台首页是公开的模型广场——未登录也可浏览已发布的模型、端点能力与公示价格，并可按端点类型筛选。模型卡片可能带展示状态徽标：「部分展示」表示同名模型中有一部分被隐藏或暂无可用渠道，「无法展示」表示该模型当前没有可用渠道、不出现在广场列表。

门户工作区的主要导航：

管理员登录后额外拥有管理后台，门户与管理台顶部互有快捷切换入口。

3. 密钥：从申请到销亡

调用 API 必须使用 sk- 开头的密钥，两条获取路径：

• 申请审批链（涉及数据安全等级的正式密钥必走）：工作区 →「密钥申请」→ 新建申请，写清用途、数据安全等级（公开 / 内部 / 敏感）、端点场景与模型范围，提交后由本租户管理员审批（申请人不能自批，被驳回可修改重提）。批准后签发的密钥自动绑定申请单声明的等级与场景。
• 直接新建：工作区 →「API 密钥」→ 新建，可一次批量创建多把，配置名称、允许场景（聊天 / 向量化 / 图像 / 语音等，不勾选 = 不限制）、额度、模型白名单、IP 白名单、过期时间（永久 / 1 个月 / 1 天 / 1 小时）与路由策略。注意：数据安全等级字段仅管理员可设，敏感级密钥请走申请审批链。

密钥明文仅显示一次，请立即复制并妥善保存；关闭弹窗后无法再次查看。

日常运维：

• 月度用量卡：密钥列表展开即见——今日调用次数、今日额度消耗与成本、本月 Token 与请求数、月度额度进度条，哪把钥烧了多少钱不用翻日志；
• 调整走审批：对已签发密钥点「发起调整」提交变更单（新额度 / 数据等级 / 模型白名单，原因必填），由另一名管理员批准后立即生效——影响计费与数据边界的项不允许持有者自己改；
• 禁用随时可逆（配置原样保留）；删除是单向门——密钥立即失效（后续调用 401）、额度配置同事务清理，界面无恢复入口，临时收权请用禁用。

密钥体系全貌见密钥管理。

4. 发起调用

平台网关兼容 OpenAI 接口协议，SDK 接入只需替换 base_url 与 api_key 两个参数。以对话补全为例（模型名以模型广场公示为准）：

curl -s https://api.example.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-你的密钥" \
  -d '{
    "model": "模型名",
    "messages": [
      {"role": "user", "content": "你好，请介绍一下你自己。"}
    ]
  }'

常用端点：对话补全 POST /v1/chat/completions、文本向量化 POST /v1/embeddings、图像生成 POST /v1/images/generations、语音合成 POST /v1/audio/speech、语音转写 POST /v1/audio/transcriptions。完整端点与参数见端点总表。

每个响应都带 X-Oneapi-Request-Id 响应头——报障时把这个编号提供给管理员，可在调用日志中精确定位那一次请求。

5. 额度、钱包与账单

管理员可对密钥 / 模型配置四个维度的额度，超限返回 429 并附明确错误码：

未配置额度的维度不受限制。被明确拒绝的请求（429 / 403 等）不计数不扣费；选路失败（503，无可用渠道）不消耗日调用额度——只有真正转发出去的请求才计费。机制详见配额与限流。

费用入口都在钱包页：余额统计、在线充值（预设或自定义金额，受最低充值限额约束）、兑换码、我的订阅与扣费偏好。订阅是预购的额度包（标明价格、包含额度、有效期与重置周期），与钱包余额构成两条资金池，扣费偏好决定一次调用先扣哪边：

流式长请求会预扣额度、结束后按实际用量多退少补，短时间的余额波动属正常。支付订单的完整历史在钱包页「订单历史」中查看。

6. 查账：使用日志

工作区 →「使用日志」按三分区组织：通用（对话、向量化等）、绘图、任务（异步任务型调用）。每次调用一行流水：模型、Token、计费、错误码、耗时；支持按时间 / 模型 / 密钥 / 任务 ID 筛选，可导出 CSV（与页面同口径，对账以导出件为准）。任务类调用的产物预览与详情就在对应分区的详情弹窗内。

拿 Request-Id 找管理员定位后，详情里能看到争议场景最常用的几组信息：模型映射对照（你请求的模型名 vs 上游实际执行的模型名）、扣费来源（订阅还是钱包、分组倍率、分项费用）、auto 决策留痕（model="auto" 请求的候选评分与最终选择，见智能路由）。日志体系全貌见审计与日志。

7. 安全设置

• 工作区 →「安全与访问」：开启两步验证 / Passkey、管理登录会话。敏感操作（如重置安全设置）前需要先完成二次验证；
• 浏览器端登录态突然全部失效的常见原因：管理员禁用账号、身份源停用信号、安全策略变更——重新登录即可；若登录仍失败，说明账号已被停用，需联系管理员；
• 密钥泄露处置：立即在「API 密钥」页删除该密钥（已删密钥立即 401），再走申请签发新密钥，必要时请管理员核查该密钥近期调用流水。

会话与凭据机制详见用户与会话管理。

8. 排障速查

排障前先确认三件事：密钥有效、模型名与广场公示完全一致、账户与密钥额度充足。

完整错误码表见错误码总表。

9. 进阶能力

以下能力对终端用户透明或半透明，均使用同一把 sk- 密钥：

• 响应缓存：命中缓存的调用输入侧按折扣计费（管理侧可配），语义命中响应带相似度可审计；
• 批量 API：离线大批量任务上传文件、建批、下载结果，子请求独立计费并享批量折扣；
• MCP 工具网关：POST /mcp 用同一把密钥发现并调用工具服务，与模型调用共享当日限额；
• 内容安全护栏：命中拦截规则的请求返回明确错误码且不计费；仅审计模式对结果做标识不打断。

相关阅读

• 首次上手：快速开始 · 端点与参数：端点总表 · 错误码：错误码总表
• 平台能力全景：核心能力 · 平台管理侧：管理员手册