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