跳到主要内容

ai_check_info

什么是 AI 鉴权参数 ?​

画布中已经集成了 AI 的能力，每次使用 AI 能力的时候都需要携带一些校验参数，用于检测当前用户是否有权限来使用 AI 能力，包含画布 id、用户 id，AI 签名，操作唯一标识等。

AI 鉴权参数 推荐由开发者自己的服务器生成，因为这样可以避免直接将用于生成签名的 salt 基于网络进行传输。开发者自己的服务端应自行妥善存储 salt 数据，并基于 salt 生成签名，这样服务端就能仅依靠签名机制验证 AI 使用的合法性。

最终需要生成的参数结构为：

interface AiCheckInfo {
  /** AI会话剩余次数 */
  inPackageRemain: number;
  /** 其他来源AI操作次数，比如团队购买次数 */
  outPackageRemain: number;
  extraInfo: {
    /**
     * 应用 ID，可于控制台/应用管理中查看 appId。使用白板 sdk 的必要参数之一。如若错误则不能使用白板
     *
     * **注：**
     * 此信息为敏感信息，请尽量不要写在前端项目中
     */
    appId: string;
    /** 登入的用户 ID，同一 userId，画布侧会视为同一个用户 */
    userId: string;
    /** 白板 ID，用于唯一标识画布  */
    boardId: string;
    /** 当前时间戳。*/
    ts: number;
    /** 16 位 uuid，用于标识本次操作 */
    key: string;
    /**
     * 通过加密算法加密的 AI 鉴权所需参数
     *
     * **注：**
     * 请尽量让服务端生成该参数，在前端代码中生成该参数相当于直接暴露了加密算法
     * */
    sign: string;
    /** 事件类型，AI 鉴权场景就是默认值 'ai' */
    event: string;
    /** 大数据模型 */
    model: string;
  };
}

AI 鉴权参数生成方式​

最主要的是要生成 sign 属性，它需要的前置参数为：

interface SignGenerateParams {
  /** 登入的用户 ID，同一 userId，画布侧会视为同一个用户 */
  userId: string;
  /** 白板 ID，用于唯一标识画布  */
  boardId: string;
  /** 当前时间戳。*/
  ts: number;
  /** 16 位 uuid，用于标识本次操作，不传会自动生成 */
  key?: string;
  /**
   * 加密算法需要的盐
   *
   * **注：**
   * 请尽量让服务端生成该参数，在前端代码中生成该参数相当于直接暴露了加密算法
   * */
  salt: string;
  /** 事件类型，AI 鉴权场景就是默认值 'ai' */
  event: string;
  /** 大数据模型，当前仅支持 wenxin' */
  model: string;
}

计算 sign 的方式:
​

首先将 SignGenerateParams 中的各参数（除 salt 外）拼接成字符串，再通过 HMAC-sha1 签名并以 Hex 格式输出，即可得到签名值。

Node 环境下 JS 示例：

import CryptoJS from 'crypto-js';

const params: SignGenerateParams = {...}
const {key, ts, userId, boardId, salt, event, model} = params
// 将参数名与参数值拼接成字符串
const content = = `${key}${ts}${userId}${boardId}${event}${model}`;
// 使用分配的应用秘钥来加密生成签名
const mac = CryptoJS.HmacSHA1(p, salt);
const sign = mac.toString(CryptoJS.enc.Hex).toUpperCase();

快速集成 AI 鉴权参数生成能力​

为方便 Node 服务端开发者快捷生成 AI 鉴权参数，我们提供了可以基于 npm 引入的工具库：

  • 安装依赖：
npm i @plaso-infi/whiteboard-ext-tools
  • 使用工具函数

注意：AiCheckParams 和 SignGenerateParams 不是重合的，SignGenerateParams 仅仅是生成 AiCheckInfo 的 sign 字段所需要的参数，而 AiCheckParams 暂时没有开放 event 和 model 属性，在内部使用了默认值。

// @plaso-infi/whiteboard-ext-tools 库自带 d.ts 类型声明
import { getAiCheckExtraInfo, type AiCheckParams } from "@plaso-infi/whiteboard-ext-tools";

interface AiCheckParams {
  /**
   * 应用 ID，可于控制台/应用管理中查看 appId。使用白板 sdk 的必要参数之一。如若错误则不能使用白板
   *
   * **注：**
   * 此信息为敏感信息，请尽量不要写在前端项目中
   */
  appId: string;
  /** 登入的用户 ID，同一 userId，画布侧会视为同一个用户 */
  userId: string;
  /** 白板 ID，用于唯一标识画布  */
  boardId: string;
  /** 当前时间戳。*/
  ts: number;
  /** 16 位 uuid，用于标识本次操作 */
  key?: string;
  /**
   * 加密算法需要的盐
   *
   * **注：**
   * 请尽量让服务端生成该参数，在前端代码中生成该参数相当于直接暴露了加密算法
   * */
  salt: string;
   /** 事件类型，AI 鉴权场景就是默认值 'ai' */
  event: string;
  /** 大数据模型 */
  model: string;
  /** AI会话剩余次数 */
  inPackageRemain: number;
  /** 其他来源AI操作次数，比如团队购买次数 */
  outPackageRemain: number;
}

// AiCheckParams 会对AI 鉴权参数做类型检查
// 注意：如果使用
const params: AiCheckParams = {...};
// 获取完整AI 鉴权参数
const aiCheckInfo: AiCheckInfo = getAiCheckExtraInfo(params);