接入概览

更新时间:
复制 MD 格式

本手册适用于提供“BYOK限额和统计”扩展的 K8S 版本,协议版本为 /spi/v1。安装版本须支持八个接口;文档可读不代表当前安装已开放该能力。

从这里开始

你要做什么

阅读内容

第一次对接,确认地址、凭据和用户身份

快速开始

提供组织、成员及每日消费数据

统计接口

接收成员限额、返回实时组织额度

额度接口

检查联调结果或定位失败

联调验收与排障

谁调用谁

管理员 → 千问办公控制台 → 千问办公服务 → 企业 SPI 适配服务 → 企业额度与用量系统
                                         ← HTTP 200 + JSON ←

你需要实现右侧的 HTTP 接口。千问办公发起请求,企业服务验证 Token 与组织、执行操作并返回约定的 JSON。浏览器不直接调用企业 SPI。

接入方式

调用方向

凭据与用途

OpenAPI

企业应用 → 千问办公

开放平台应用 API Key;调用办公能力

本手册的业务 SPI

千问办公 → 企业服务

独立 SPI Token;读取统计、设置及读取限额

模型 BYOK

千问办公 → 模型 Provider

模型配置中的 Endpoint 与可选 API Key;执行模型请求

计量/限额 SPI 可处理未绑定三方账号的组织成员。模型侧独立的强制三方身份配置仍按原策略执行;客户模型服务实际计量必须与 SPI 采用同一稳定主体,不能仅凭 SPI 联调通过认定模型端到端可用。

需要实现哪些接口

八个接口共用一个服务地址、Token 和启用开关,不能在控制台分别开启统计或额度。下表“调用时机”说明当前宿主行为;不要仅凭连通性检测通过判断全部接口已完成。

接口名称

Method 与路径

职责

调用时机

获取最新统计日期

GET /spi/v1/usage/meta

最新完整数据日期

统计刷新、手动连通性检测

查询组织用量概览

GET /spi/v1/usage/overview

组织历史用量

按日期和五个周期构建快照

查询成员用量列表

GET /spi/v1/usage/members

成员历史用量

构建快照,读取全部分页

查询成员每日用量趋势

GET /spi/v1/usage/members/{external_user_id}/trend

成员每日趋势

查看成员趋势时按需读取

查询额度规则与周期

GET /spi/v1/quota/context

额度约束与当前周期

校验额度、确定周期边界

查询成员额度

POST /spi/v1/quota/users/query

已应用的成员额度

SDK 显式查询;当前产品不强制写后回读

设置成员限额

PUT /spi/v1/quota/users

设置单个成员的绝对限额

后台派发与重试额度变更

查询组织额度

GET /spi/v1/quota/org

实时组织总额度与已用量

查询组织额度

对接前先约定三个值

值

含义

本手册的合成示例

组织 ID

千问办公组织 UUID;映射到企业账本租户

11111111-1111-4111-8111-111111111111

内部用户 ID

当前组织的稳定用户 UUID,字段 qw_user_id

22222222-2222-4222-8222-222222222222

第三方用户 ID

IAM 当前已绑定的企业用户标识;保留大小写和前导零

employee-1001

计量单位

统计用 credit 数字,额度用 minor 整数字符串

500 credit = "5000000" minor

示例中的域名、身份和数据仅用于说明。真实联调应使用测试组织、本组织测试用户及独立测试凭据。

下一步:准备连接并发起首次请求。