1# @ohos.data.intelligence (智慧数据平台) 2 3智慧数据平台（ArkData Intelligence Platform，AIP）提供端侧的数据智慧化能力，完成数据和AI智能在端侧闭环。作为端侧智慧化能力底座，将构建以下能力： 4- 多模态嵌入模型：使用嵌入模型（Embedding Model）对多模态数据生成向量表征，将文本、图片等数据映射到同一向量空间，支撑基于语义的多模态知识检索。 5- 多模态数据存储：支持端侧向量、倒排索引等多模态数据存储，避免将原始数据发送到服务器进行处理，减少了数据泄露的风险。 6- 知识检索：逐步构建语义索引、知识图谱、召回、重排等能力，支持用户知识的语义化检索。 7- 知识生成与整理：基于用户文档、消息、电子邮件、照片、视频、日历事件、屏幕上下文等数据，支持高效数据整理与知识生成，实现数据到知识的转换。 8 9> **说明：** 10> 11> 本模块首批接口从API version 15开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。 12> 13> 考虑到数据向量化处理的计算量和资源占用较大，当前仅支持在2in1设备上使用。 14 15 16## 导入模块 17 18```ts 19import { intelligence } from '@kit.ArkData'; 20``` 21 22## intelligence.getTextEmbeddingModel 23 24getTextEmbeddingModel(config: ModelConfig): Promise<TextEmbedding> 25 26获取文本嵌入模型，使用Promise异步回调。 27 28**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 29 30**参数：** 31 32| 参数名 | 类型 | 必填 | 说明 | 33| ------------ | --------------------------------------- | ---- | :--------------------------------- | 34| config | [ModelConfig](#modelconfig) | 是 | 嵌入模型的配置信息。 | 35 36**返回值：** 37 38| 类型 | 说明 | 39| ----------------------------- | ------------------------------------ | 40| Promise<[TextEmbedding](#textembedding)> | Promise对象，返回文本嵌入模型对象。 | 41 42**错误码：** 43 44以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[智慧数据平台错误码](errorcode-intelligence.md)。 45 46| **错误码ID** | **错误信息** | 47| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 48| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 49| 801 | Capability not supported. | 50| 31300000 | Inner error. | | 51 52**示例：** 53 54```ts 55import { BusinessError } from '@kit.BasicServicesKit'; 56 57let textConfig:intelligence.ModelConfig = { 58 version:intelligence.ModelVersion.BASIC_MODEL, 59 isNpuAvailable:false, 60 cachePath:"/data" 61} 62let textEmbedding:intelligence.TextEmbedding; 63 64intelligence.getTextEmbeddingModel(textConfig) 65 .then((data:intelligence.TextEmbedding) => { 66 console.info("Succeeded in getting TextModel"); 67 textEmbedding = data; 68 }) 69 .catch((err:BusinessError) => { 70 console.error("Failed to get TextModel and code is " + err.code); 71 }) 72``` 73 74## intelligence.getImageEmbeddingModel 75 76getImageEmbeddingModel(config: ModelConfig): Promise<ImageEmbedding> 77 78获取图像嵌入模型。使用Promise异步回调。 79 80**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 81 82**参数：** 83 84| 参数名 | 类型 | 必填 | 说明 | 85| ------------ | --------------------------------------- | ---- | :--------------------------------- | 86| config | [ModelConfig](#modelconfig) | 是 | 嵌入模型的配置信息。 | 87 88**返回值：** 89 90| 类型 | 说明 | 91| ----------------------------- | ------------------------------------ | 92| Promise<[ImageEmbedding](#imageembedding)> | Promise对象，返回图像嵌入模型对象。 | 93 94**错误码：** 95 96以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[智慧数据平台错误码](errorcode-intelligence.md)。 97 98| **错误码ID** | **错误信息** | 99| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 100| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 101| 801 | Capability not supported. | 102| 31300000 | Inner error. | | 103 104**示例：** 105 106```ts 107import { BusinessError } from '@kit.BasicServicesKit'; 108 109let imageConfig:intelligence.ModelConfig = { 110 version:intelligence.ModelVersion.BASIC_MODEL, 111 isNpuAvailable:false, 112 cachePath:"/data" 113} 114let imageEmbedding:intelligence.ImageEmbedding; 115 116intelligence.getImageEmbeddingModel(imageConfig) 117 .then((data:intelligence.ImageEmbedding) => { 118 console.info("Succeeded in getting ImageModel"); 119 imageEmbedding = data; 120 }) 121 .catch((err:BusinessError) => { 122 console.error("Failed to get ImageModel and code is " + err.code); 123 }) 124``` 125 126## intelligence.splitText 127 128splitText(text: string, config: SplitConfig): Promise<Array<string>> 129 130获取文本的分块。 131 132**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 133 134**参数：** 135 136| 参数名 | 类型 | 必填 | 说明 | 137| ------------ | --------------------------------------- | ---- | :--------------------------------- | 138| text | string | 是 | 用于分块的文本，可取任意值。 | 139| config | [SplitConfig](#splitconfig) | 是 | 文本分块的配置信息。 | 140 141**返回值：** 142 143| 类型 | 说明 | 144| ----------------------------- | ------------------------------------ | 145| Promise<Array<string>> | Promise对象，返回分块结果的数组对象。 | 146 147**错误码：** 148 149以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[智慧数据平台错误码](errorcode-intelligence.md)。 150 151| **错误码ID** | **错误信息** | 152| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 153| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 154| 801 | Capability not supported. | 155| 31300000 | Inner error. | | 156 157**示例：** 158 159```ts 160import { BusinessError } from '@kit.BasicServicesKit'; 161 162let splitConfig:intelligence.SplitConfig = { 163 size:10, 164 overlapRatio:0.1 165} 166let splitText = 'text'; 167 168intelligence.splitText(splitText, splitConfig) 169 .then((data:Array<string>) => { 170 console.info("Succeeded in splitting Text"); 171 }) 172 .catch((err:BusinessError) => { 173 console.error("Failed to split Text and code is " + err.code); 174 }) 175``` 176 177## ModelConfig 178 179管理嵌入模型的配置信息。 180 181**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 182 183| 名称 | 类型 | 必填 | 说明 | 184| ---------- | --------------------- | ---- | ------------------------------------------------------------ | 185| version | [ModelVersion](#modelversion) | 是 |模型的版本。 | 186| isNpuAvailable | boolean | 是 | 指示是否使用NPU加速向量化过程，true表示使用，false表示不使用。如果设备不支持NPU，调用加载模型会失败，并抛出错误码31300000。 | 187| cachePath | string | 否 | 如果使用NPU进行加速，则需要本地路径进行模型缓存。格式为/xxx/xxx/xxx，xxx为路径地址，例如"/data"。长度上限为512个字符。默认值为""。 | 188 189## ModelVersion 190 191模型版本枚举。 192 193**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 194 195| 名称 | 值 | 说明 | 196| ---------- | ---------- | ---------------------- | 197| BASIC_MODEL | 0 | 基本嵌入模型版本。 | 198 199## Image 200 201type Image = string 202 203表示图片的URI地址，对应为string类型。 204 205**系统能力：** SystemCapability.DistributedDataManager.RelationalStore.Core 206 207| 类型 | 说明 | 208| ---------------------------- | --------------------- | 209| string | 图片的URI地址。长度上限为512个字符。 | 210 211## SplitConfig 212 213管理文本分块的配置信息。 214 215**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 216 217| 名称 | 类型 | 必填 | 说明 | 218| ---------- | --------------------- | ---- | ------------------------------------------------------------ | 219| size | number | 是 |分块的最大大小，取值为非负整数。 | 220| overlapRatio | number | 是 | 相邻分块之间的重叠比率。范围为[0,1]，0表示重叠比率最低，1表示重叠比率最高。 | 221 222 223## TextEmbedding 224 225描述多模态嵌入模型的文本嵌入函数。 226 227下列接口都需先使用[intelligence.getTextEmbeddingModel](#intelligencegettextembeddingmodel)获取到TextEmbedding实例，再通过此实例调用对应接口。 228 229**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 230 231### loadModel 232 233loadModel(): Promise<void> 234 235加载嵌入模型，使用Promise异步回调。 236 237**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 238 239**返回值：** 240 241| 类型 | 说明 | 242| ----------------------------- | ------------------------------------ | 243| Promise<void> | 无返回结果的Promise对象。 | 244 245**错误码：** 246 247以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[智慧数据平台错误码](errorcode-intelligence.md)。 248 249| **错误码ID** | **错误信息** | 250| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 251| 801 | Capability not supported. | 252| 31300000 | Inner error. | | 253 254**示例：** 255 256```ts 257import { BusinessError } from '@kit.BasicServicesKit'; 258 259textEmbedding.loadModel() 260 .then(() => { 261 console.info("Succeeded in loading Model"); 262 }) 263 .catch((err:BusinessError) => { 264 console.error("Failed to load Model and code is " + err.code); 265 }) 266``` 267 268### releaseModel 269 270releaseModel(): Promise<void> 271 272释放嵌入模型，使用Promise异步回调。 273 274**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 275 276**返回值：** 277 278| 类型 | 说明 | 279| ----------------------------- | ------------------------------------ | 280| Promise<void> | 无返回结果的Promise对象。 | 281 282**错误码：** 283 284以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[智慧数据平台错误码](errorcode-intelligence.md)。 285 286| **错误码ID** | **错误信息** | 287| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 288| 801 | Capability not supported. | 289| 31300000 | Inner error. | | 290 291**示例：** 292 293```ts 294import { BusinessError } from '@kit.BasicServicesKit'; 295 296textEmbedding.releaseModel() 297 .then(() => { 298 console.info("Succeeded in releasing Model"); 299 }) 300 .catch((err:BusinessError) => { 301 console.error("Failed to release Model and code is " + err.code); 302 }) 303``` 304 305### getEmbedding 306 307getEmbedding(text: string): Promise<Array<number>> 308 309获取给定文本的嵌入向量。 310 311该接口需先调用[loadModel](#loadmodel)加载嵌入模型，加载成功后调用getEmbedding。 312 313**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 314 315**参数：** 316 317| 参数名 | 类型 | 必填 | 说明 | 318| ------------ | --------------------------------------- | ---- | :--------------------------------- | 319| text | string | 是 | 嵌入模型的输入文本。长度上限为512个字符。 | 320 321**返回值：** 322 323| 类型 | 说明 | 324| ----------------------------- | ------------------------------------ | 325| Promise<Array<number>> | Promise对象，返回向量化结果的数组对象。 | 326 327**错误码：** 328 329以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[智慧数据平台错误码](errorcode-intelligence.md)。 330 331| **错误码ID** | **错误信息** | 332| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 333| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 334| 801 | Capability not supported. | 335| 31300000 | Inner error. | | 336 337**示例：** 338 339```ts 340import { BusinessError } from '@kit.BasicServicesKit'; 341 342 343textEmbedding.loadModel(); 344let text = 'text'; 345textEmbedding.getEmbedding(text) 346 .then((data:Array<number>) => { 347 console.info("Succeeded in getting Embedding"); 348 }) 349 .catch((err:BusinessError) => { 350 console.error("Failed to get Embedding and code is " + err.code); 351 }) 352``` 353 354### getEmbedding 355 356getEmbedding(batchTexts: Array<string>): Promise<Array<Array<number>>> 357 358获取给定批次文本的嵌入向量。 359 360该接口需先调用[loadModel](#loadmodel)加载嵌入模型，加载成功后调用getEmbedding。 361 362**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 363 364**参数：** 365 366| 参数名 | 类型 | 必填 | 说明 | 367| ------------ | --------------------------------------- | ---- | :--------------------------------- | 368| batchTexts | Array<string> | 是 | 嵌入模型的文本输入批次。单个文本长度上限为512个字符。 | 369 370**返回值：** 371 372| 类型 | 说明 | 373| ----------------------------- | ------------------------------------ | 374| Promise<Array<Array<number>>> | Promise对象，返回向量化结果的数组对象。 | 375 376**错误码：** 377 378以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[智慧数据平台错误码](errorcode-intelligence.md)。 379 380| **错误码ID** | **错误信息** | 381| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 382| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 383| 801 | Capability not supported. | 384| 31300000 | Inner error. | | 385 386**示例：** 387 388```ts 389import { BusinessError } from '@kit.BasicServicesKit'; 390 391 392textEmbedding.loadModel(); 393let batchTexts = ['text1','text2']; 394textEmbedding.getEmbedding(batchTexts) 395 .then((data:Array<Array<number>>) => { 396 console.info("Succeeded in getting Embedding"); 397 }) 398 .catch((err:BusinessError) => { 399 console.error("Failed to get Embedding and code is " + err.code); 400 }) 401``` 402 403## ImageEmbedding 404 405描述多模态嵌入模型的图像嵌入函数。 406 407下列接口都需先使用[intelligence.getImageEmbeddingModel](#intelligencegetimageembeddingmodel)获取到ImageEmbedding实例，再通过此实例调用对应接口。 408 409**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 410 411### loadModel 412 413loadModel(): Promise<void> 414 415加载嵌入模型，使用Promise异步回调。 416 417**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 418 419**返回值：** 420 421| 类型 | 说明 | 422| ----------------------------- | ------------------------------------ | 423| Promise<void> | 无返回结果的Promise对象。 | 424 425**错误码：** 426 427以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[智慧数据平台错误码](errorcode-intelligence.md)。 428 429| **错误码ID** | **错误信息** | 430| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 431| 801 | Capability not supported. | 432| 31300000 | Inner error. | | 433 434**示例：** 435 436```ts 437import { BusinessError } from '@kit.BasicServicesKit'; 438 439imageEmbedding.loadModel() 440 .then(() => { 441 console.info("Succeeded in loading Model"); 442 }) 443 .catch((err:BusinessError) => { 444 console.error("Failed to load Model and code is " + err.code); 445 }) 446``` 447 448### releaseModel 449 450releaseModel(): Promise<void> 451 452释放嵌入模型，使用Promise异步回调。 453 454**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 455 456**返回值：** 457 458| 类型 | 说明 | 459| ----------------------------- | ------------------------------------ | 460| Promise<void> | 无返回结果的Promise对象。 | 461 462**错误码：** 463 464以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[智慧数据平台错误码](errorcode-intelligence.md)。 465 466| **错误码ID** | **错误信息** | 467| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 468| 801 | Capability not supported. | 469| 31300000 | Inner error. | | 470 471**示例：** 472 473```ts 474import { BusinessError } from '@kit.BasicServicesKit'; 475 476imageEmbedding.releaseModel() 477 .then(() => { 478 console.info("Succeeded in releasing Model"); 479 }) 480 .catch((err:BusinessError) => { 481 console.error("Failed to release Model and code is " + err.code); 482 }) 483``` 484 485### getEmbedding 486 487getEmbedding(image: Image): Promise<Array<number>> 488 489获取给定图像的嵌入向量。 490 491该接口需先调用[loadModel](#loadmodel)加载嵌入模型，加载成功后调用getEmbedding。 492 493**系统能力：** SystemCapability.DistributedDataManager.DataIntelligence.Core 494 495**参数：** 496 497| 参数名 | 类型 | 必填 | 说明 | 498| ------------ | --------------------------------------- | ---- | :--------------------------------- | 499| image | [Image](#image) | 是 | 嵌入模型的输入图像类型的URI地址。 | 500 501**返回值：** 502 503| 类型 | 说明 | 504| ----------------------------- | ------------------------------------ | 505| Promise<Array<number>> | Promise对象，返回向量化结果的数组对象。 | 506 507**错误码：** 508 509以下错误码的详细介绍请参见[通用错误码](../errorcode-universal.md)和[智慧数据平台错误码](errorcode-intelligence.md)。 510 511| **错误码ID** | **错误信息** | 512| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 513| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 514| 801 | Capability not supported. | 515| 31300000 | Inner error. | | 516 517**示例：** 518 519```ts 520import { BusinessError } from '@kit.BasicServicesKit'; 521 522imageEmbedding.loadModel(); 523let image = 'file://<packageName>/data/storage/el2/base/haps/entry/files/xxx.jpg'; 524imageEmbedding.getEmbedding(image) 525 .then((data:Array<number>) => { 526 console.info("Succeeded in getting Embedding"); 527 }) 528 .catch((err:BusinessError) => { 529 console.error("Failed to get Embedding and code is " + err.code); 530 }) 531```
