总览
产品使用说明书
角色、术语、两条核心链路和页面入口。
适用版本:2026-11-11
在线入口:/manual(开放平台卷公开,产品控制台卷需内部登录)
维护原则:这份说明书面向使用者,不替代技术接入文档。接口字段以 业务接入 为准,部署与运维以 运维手册 为准。
一、这份说明书解决什么问题
Cosmo Core 的功能已经覆盖识别人工复核、模型迭代、设备与项目管理、开放平台接入和运营管理。功能多起来之后,只看 README 或接口文档很难回答这些问题:
- 我作为客户/开发者,第一次接入应该从哪里开始?
- 我作为复核人员,怎么连续处理样本、怎么保存修正、怎么创建数据集?
- 我作为管理员,怎么发布模型、处理失败任务、查看调用追踪?
- 页面上每个字段是什么意思?哪些能改,哪些不能改?
- 出错时应该先看哪里,谁能处理?
这份说明书按“开放平台”和“产品控制台”两条使用路径组织。
二、两卷导航
| 卷 | 面向谁 | 入口 | 内容 |
|---|---|---|---|
| 开放平台卷 | 客户、业务方、开发者、账号 owner | /open | 申请接入、登录、应用、密钥、接入代码、用量、调用追踪、任务、成员、常见问题 |
| 产品控制台卷 | 平台管理员、复核人员、运营 | /console-next | 概览、识别、记录、复核、模型、设备、项目、监控、应用接入、管理中心、账号菜单 |
三、先分清两个入口
开放平台 /open
面向外部客户和开发者,重点是“把业务接进来”:
- 阅读产品能力、接口文档和 API 参考
- 提交接入申请
- 查询申请进度
- 登录后创建应用、领取密钥、复制接入代码
- 查看调用用量、按 request_id 追踪
- 管理成员和异步任务
- 修改应用名称、状态和复核回调地址
产品控制台 /console-next
面向平台内部人员,重点是“把平台运营好”:
- 查看识别记录和待复核样本
- 在画布上复核、修正、丢弃、创建数据集
- 上传、验证、评估、发布、回滚模型
- 管理设备、项目、应用、账号、人员、旧凭据
- 查看运行监控、通知、失败任务和调用追踪
- 查看体验事件和审计记录
官网 /、登录页 /login、产品大屏 /showcase 是公开页面,不属于这两个业务入口。
四、按角色快速开始
客户 / 业务方
- 打开
/open - 阅读「文档」和「API 参考」
- 提交「申请接入」
- 保存申请号,用申请号 + 联系人查询审核进度
- 审核通过后登录开放平台
- 创建应用、发放测试密钥、复制接入代码
- 跑通第一次调用后查看用量和调用追踪
- 需要协作时邀请成员
详见 开放平台卷。
复核人员
- 登录后进入
/console-next/review - 选择待复核样本,打开复核画布
- 检查原预测,必要时修改框和类别
- 保存、丢弃或保存并下一条
- 用已复核样本创建训练集/评估集快照
复核人员的侧栏只有:识别工作台、识别记录、样本工作台、调用追踪。
平台管理员
- 登录后进入
/console-next/overview - 先看「今天先做」
- 从管理中心审批接入申请、建账号/人员/应用
- 从模型中心上传、验证、评估、发布模型
- 从设备/项目管理侧配置
- 从运行监控和通知中心处理异常
- 使用调用追踪按 request_id 排障
详见 产品控制台卷。
五、基础概念
| 术语 | 含义 |
|---|---|
| 业务账号 | 开放平台的归属边界,一个客户/业务方一个账号,账号下可以有多个应用和成员 |
| 应用 App | 一次接入的边界,有 APP ID、环境(测试/生产)、状态、回调地址、可用模型、能力、配额、IP 白名单 |
| 密钥 Key | 应用下的调用凭据,只保存哈希,明文只在发放时展示一次;可轮换、撤销、到期 |
| 回调签名密钥 | 用于业务方验证平台回调的 HMAC 密钥,owner 可见,可轮换 |
| 项目 Project | 归属/统计维度,不是安全隔离;可关联设备、凭据、用量 |
| 业务凭据 | 开放平台上线前的旧调用凭据,保留兼容;新接入应使用应用密钥 |
| request_id | 一次识别的唯一 ID;用于反馈、复核、调用追踪和排障 |
| 样本 revision | 样本复核修订号;并发修改时用于冲突检查 |
| 数据集快照 | 从人工标注生成不可变训练/评估集,包含图片、标注、权重版本和哈希 |
| 证据等级 | 模型发布时的评估证据等级,从低到高;不是所有等级都能直接发布 |
| 异步任务 | 通过 /v1/vision/tasks 创建的识别任务,结果和回调可查询 |
| 临时密码 | 新建人员/成员账号时只展示一次,首次登录后建议修改 |
六、两条最重要的业务链路
链路 A:从申请到第一条成功调用
客户提交申请
→ 运营在管理中心审批
→ 自动开通业务账号和首个登录账号
→ 客户登录开放平台
→ 创建应用 → 发放测试密钥
→ 复制 cURL/接入代码
→ 发起第一次识别
→ 查看 request_id、结果图和用量
→ 配置回调/成员/生产应用
对应页面:/open/apply → /open/console → 概览接入进度 → 应用与密钥 → 调用与追踪。
链路 B:从识别到模型发布
业务图片识别
→ 记录保存原预测和权重哈希
→ 低置信/零检出/反馈进入复核池
→ 复核人员修正/确认/丢弃
→ 已复核样本生成不可变数据集
→ 上传新模型版本
→ 验证 → 独立评估/外部报告/影子实测
→ 发布或回滚
→ 新调用绑定新版本
对应页面:识别工作台 → 识别记录 → 样本工作台 → 模型中心 → 运行监控。
七、页面入口总表
| 页面 | 路由 | 谁能进 | 用途 |
|---|---|---|---|
| 产品官网 | / | 公开 | 产品介绍、登录/控制台入口 |
| 登录页 | /login | 公开 | 账号密码 / API Key 登录 |
| 产品大屏 | /showcase | 公开/管理员数据 | 演示 |
| 开放平台 | /open | 公开/登录 | 文档、申请、控制台 |
| 开放平台控制台 | /open/console | 登录 | 应用、密钥、用量、追踪、任务、成员 |
| Vue 控制台 | /console-next | admin/review | 默认内部工作台 |
| 调用追踪(内部) | /console-next/trace | admin/review | 按 request_id 看完整链路 |
| API 文档 | /open/docs / /open/reference | 公开 | 接口说明和 OpenAPI 参考 |
| 完整 OpenAPI | /admin/openapi.json | 管理员 | 含管理端的完整契约 |
八、阅读顺序建议
第一次接触项目:
九、文档边界
- 本说明书讲“怎么用、字段什么意思、流程怎么走”;
- 业务接入 讲接口、参数、错误码和鉴权;
- 运维手册 讲安装、部署、备份、证书、回滚;
- 界面设计 讲视觉和交互规范;
- 实施清单 和 验收记录 讲做到哪、验证过什么。
如果本说明书与代码/接口文档冲突,以代码和 业务接入 为准;页面文案以实际页面为准。