快速上手：从注册到第一个对话
本指南将带你完成从注册账号、配置模型、创建智能体到成功调用API的完整流程。预计耗时约10-15分钟。
什么时候用
- 刚注册新账号，需要完成初始配置
- 新接手一个账号，需要快速了解基础操作
- 需要为业务系统对接第一个API调用
你需要准备
- 一个有效的手机号（用于注册和登录）
- 至少一个可用的模型API Key（如OpenAI、Azure等）
- 一个API测试工具（如Postman、OpenAI SDK等）
操作步骤
第 1 步：注册账号
- 打开登录页面，点击底部「注册」按钮
- 在弹出的内测申请窗口中填写联系人、手机号、邮箱
- 完成验证后，等待平台开通（当前为内测阶段）
- 收到开通通知后，回到登录页面使用手机号和密码登录
正式开放后，注册流程将简化为直接填写信息即可完成。
第 2 步：登录并验证
- 在登录页面输入手机号和密码
- 点击验证码图片刷新，输入正确的验证码
- 点击「立即登录」
- 登录成功后会跳转到首页
第 3 步：接入模型供应商
- 点击左侧菜单 「模型管理」
- 点击右上角 「新增供应商」 按钮
- 填写供应商信息：
- 名称：给供应商起个便于识别的名字（如「OpenAI官方」）
- 类型：选择对应的供应商类型（如
openai、openai_compatible等） - API Base URL：填写服务地址（部分类型有默认值，可留空）
- API Key：粘贴你的供应商API Key
- 点击「保存」
详细操作见 02-接入模型供应商。
第 4 步：添加模型
- 在模型管理页面，找到刚添加的供应商，点击 「模型管理」 展开
- 点击 「添加模型」 按钮
- 填写模型信息：
- 供应商模型名称：上游的真实模型名（如
gpt-4o、llama3.1） - 自定义显示名称：在本平台使用的名称（如
GPT-4o），不能以group-开头 - 状态：保持「启用」
- 模型类型：选择
Chat（对话模型） - 额外配置：可选，填写JSON格式的模型参数
- 供应商模型名称：上游的真实模型名（如
- 点击「保存」
提示：部分供应商类型支持 「自动获取模型」 功能，一键导入该供应商的所有可用模型。
详细操作见 03-添加与配置模型。
第 5 步：创建智能体
- 点击左侧菜单 「智能体管理」 -> 「我的智能体」
- 点击右上角 「新增智能体」 按钮
- 填写基础信息：
- 智能体名称：给智能体起个名字（如「客服助手」）
- 初始System Prompt：定义智能体的人设和行为规则
- 模型：选择刚才添加的模型，或留空使用默认模型
- Temperature：可选，调整生成的随机性
- 点击「下一步」，关联技能（可选）
- 点击「下一步」，配置关键词匹配（可选）
- 点击「保存」
详细操作见 06-创建并配置智能体。
第 6 步：创建用户
- 点击左侧菜单 「用户管理」
- 点击右上角 「新增用户」 按钮
- 填写用户信息：
- 用户名：该用户的登录名（如
api_user） - 手机号：可选，用于登录
- 密码：设置一个强密码（至少12位，包含大小写字母、数字和特殊字符）
- 角色：选择
普通用户或管理员
- 用户名：该用户的登录名（如
- 点击「保存」
详细操作见 10-创建用户并分配智能体。
第 7 步：分配智能体
- 在用户管理页面，找到刚创建的用户
- 点击 「更多」 -> 「智能体」
- 在弹出的分配对话框中，勾选要分配的智能体
- 点击「保存」
第 8 步：创建API Key
- 在用户管理页面，对应用户行点击 「更多」 -> 「API Key」
- 在弹出的对话框中点击 「新增API Key」
- 填写Key名称（如「业务系统调用」）
- 点击「保存」
- 重要：复制并安全保存生成的完整API Key（仅显示一次，丢失后无法恢复）
详细操作见 11-管理用户API Key。
第 9 步：调通对话API
现在可以使用刚才创建的API Key调用对话接口了：
- API地址：
https://www.aimatespace.com/openai/v1/chat/completions - 验证成功：收到正常的AI回复
注意：
model字段使用的是 自定义显示名称，不是上游模型名- API Key 属于某个用户，使用该Key调用时会受到该用户的白名单限制
怎么验证成功了
- 登录控制台，能看到完整菜单
- 在「模型管理」中能看到已添加的供应商和模型
- 在「智能体管理」中能看到刚创建的智能体
- 在「用户管理」中能看到刚创建的用户
- 使用API Key调用
/openai/v1/chat/completions能收到正常回复 - 在「会话记录」中能看到刚才的对话记录
常见问题
注册后登录提示「用户不存在」
- 确认已完成内测申请流程并收到开通通知
- 检查手机号输入是否正确，是否带有国家码前缀
添加供应商后测试连接失败
- 确认API Key是否正确且有效
- 检查API Base URL是否可访问（如有）
- 查看网络连接是否正常
创建模型提示「显示名称已存在」
- 检查是否已有同名模型（包括禁用状态的）
- 尝试使用不同的名称
- 确认名称没有以
group-开头
调用API返回401 Unauthorized
- 确认API Key是否完整且正确
- 检查API Key是否属于该且未被禁用
- 确认使用的是
/openai/v1/开头的接口，而不是管理接口
调用API返回403 Forbidden
- 检查该用户是否在模型白名单中添加了该模型
- 确认模型状态为「启用」
- 查看是否配置了客户端白名单限制
深入
三服务架构
平台由三个独立服务组成，各司其职：
| 服务 | 用途 | 你如何用 |
|---|---|---|
| 租户控制台 | 管理面板：用户、Agent、模型、技能等 | 前端网页调用，你用浏览器操作 |
| OpenAI 兼容 | LLM 对话补全、Embedding、图片生成 | 你的业务系统（SDK / cURL）调用 |
| MCP 网关 | 聚合多个上游 MCP Server 的工具 | 外部 MCP 客户端调用 |
控制台网页通过管理接口调用；业务系统调用 /openai/v1/ 走兼容接口。
租户与用户
- 租户：一个独立的隔离单元。每个租户拥有自己的一套用户、模型、Agent 和技能，看不到其他租户的数据。
- 租户管理员：注册租户时自动创建，拥有本租户所有管理权限。
- 普通用户：由管理员创建，只能使用被分配的 Agent 和模型。
模型鉴权摘要
- Agent 路径只看 Agent 绑定（未绑定回退租户默认模型组/默认模型）
- 非 Agent 路径只看用户白名单，白名单为空 = 全拒绝
- 平台管理员/租户 admin 不豁免
请求体中的 model 不能绕过 Agent 绑定：带 agent_id 时用户白名单不参与判断，按 Agent 绑定/租户默认规则鉴权。
模型组在控制台/数据库中的 name 不含 group- 前缀；调用 OpenAI API 时使用 group- 前缀，例如 group-my-group。
配额和限制
| 限制项 | 值 |
|---|---|
| 聊天速率 | 30/min，IP 粒度 |
| 通用速率 | 60/min，IP 粒度 |
| messages 上限 | 500 条 |
| 请求体大小 | 5MB |
| LLM 请求超时 | 60s |
| 工具调用轮数 | 最多 5 轮 |
| n | 必须为 1 |
MCP 网关
工具命名空间：MCP 标准客户端拿到的工具名：{server_name}{tool_name}，例如 weather__get_forecast。 LLM 在 Pipeline 中看到的平台服务端工具使用 mcp 前缀。
| 工具类型 | 示例 | 执行方 |
|---|---|---|
| MCP 客户端工具 | weather__get_forecast | MCP 客户端调用网关 |
| 平台服务端工具 | mcp__weather__get_forecast | 平台 Pipeline 自动执行 |
| 普通客户端工具 | get_weather | 业务系统自己执行 |
错误码速查
平台业务错误：
| 状态码 | error.type | 说明 |
|---|---|---|
| 400 | invalid_request_error | 参数验证失败、agent_id 无效、messages>500、n≠1；指定模型不存在时也会在 message 中说明 |
| 400 | content_policy_violation | 禁用模式阻断 |
| 401 | authentication_error | 平台 API Key 无效或禁用，用户或租户禁用 |
| 403 | permission_error | 模型无权访问，客户端不在白名单 |
| 429 | rate_limit_error | 平台频率超限 |
| 503 | service_unavailable | Agent 路径下无可用默认模型/默认模型组 |
常见接入坑
- base_url 末尾别带 /，避免 SDK 拼成 //chat/completions
- mcp__ 前缀工具是服务端工具，平台自动执行
- 不带 mcp__ 前缀的是客户端工具，需要客户端自己执行后回传
- agent_id 必须是加密字符串，不接受明文整数 ID
- 模型鉴权摘要：Agent 路径看 Agent 绑定/租户默认；非 Agent 路径看用户白名单，白名单为空直接返回 403；管理员不豁免
- DeepSeek thinking 模式跨模型切换时，推理内容平台已自动归一化
- allow_external_role=False 时，客户端传的 system 消息会被自动剥离
- MCP 标准客户端工具名必须使用 {server_name}__{tool_name}
接入检查清单
上线前建议依次验证：
- 能返回模型
- 非流式能返回内容
- 流式请求能正确处理 : PING、event: error 和 [DONE]
- 指定 Agent 时 agent_id 是加密字符串
- 模型组调用使用正确的 group- 名称
- MCP 网关能完成 initialize、tools/list、tools/call
- 控制台调用日志、安全事件和 MCP 调用日志可用于排查
权限边界
| 操作 | 谁可以 |
|---|---|
| 注册租户 | 任何人（公开端点） |
| 登录 | 该租户的任意用户 |
| 管理模型/Agent/用户 | 该租户的 role=admin |
| 调用 /openai/v1/ | 有有效 API Key 且通过鉴权的用户 |
| 查看/修改其他租户数据 | 没有任何人可以（跨租户隔离，会返回 404 "不存在"） |
常见坑（快速上手相关）
模型鉴权规则先看「模型管理」 摘要：Agent 路径只看 Agent 绑定（未绑定才回退租户默认）；非 Agent 路径只看用户模型白名单，白名单为空 = 全部拒绝；平台管理员/租户 admin 调用 API 也不豁免。
忘记 /openai/v1/ 前缀 调用兼容接口时要使用 /openai/v1/chat/completions 或 /openai/v1/models，不要使用 /v1/chat/completions。
用 display_name 调用 model 字段传的是 ModelItem 的 display_name，不是上游模型名。
display_name 不能以 group- 开头 group- 开头被保留给模型组，如果误用会直接报错。
排错速查（快速上手相关）
| 症状 | 可能原因 | 排查路径 |
|---|---|---|
| 401 Unauthorized | Token 过期或无效 | 重新登录 |
| 403 Forbidden | 模型不在白名单，或白名单为空 | 检查用户模型白名单配置 |
| 404 "用户不存在" | ID 错误或该用户不属于你 | 检查加密 ID 是否粘贴完整 |
| 422 校验失败 | 参数格式不对 | 仔细检查输入；查看错误提示 |
| 503 service_unavailable | Agent 未绑定模型且租户没有默认模型 | 给 Agent 绑定模型，或设置租户默认模型 |
| 429 too many requests | 触发限流 | 等待配额刷新或联系平台管理员 |
- 继续配置更多模型和模型组：03-添加与配置模型
- 为用户配置更精细的权限：10-创建用户并分配智能体
- 遇到问题先查排错指南：30-常见错误与处理