1# @ohos.data.intelligence (ArkData Intelligence Platform) 2 3The ArkData Intelligence Platform (AIP) provides on-device data intelligence capabilities, enabling AI-powered data processing data on devices. To underpin AI-powered processing on devices, the AIP aims to build the following capabilities: 4- Multimodal embedding model: leverages embedding models to generate vector representations for multimodal data, mapping text, images, and other data into a unified vector space for semantic-based multimodal knowledge retrieval. 5- Multimodal data storage: supports on-device storage for vectors, inverted indexes, and other multimodal data, eliminating the need to send raw data to the server for processing. This reduces the risk of data leakage. 6- Knowledge retrieval: enables semantic retrieval of user knowledge based on capabilities such as semantic indexing, knowledge graphs, recall, and re-ranking. 7- Knowledge generation and collation: implements efficient data organization and knowledge generation based on user data such as user documents, messages, emails, photos, videos, calendar events, and screen context, enabling the transformation of data into knowledge. 8 9> **NOTE** 10> 11> The initial APIs of this module are supported since API version 15. Newly added APIs will be marked with a superscript to indicate their earliest API version. 12> 13> Considering the significant computing workload and resources of data vectorization processing, the APIs are only available to 2-in-1 device applications. 14 15 16## Modules to Import 17 18```ts 19import { intelligence } from '@kit.ArkData'; 20``` 21 22## intelligence.getTextEmbeddingModel 23 24getTextEmbeddingModel(config: ModelConfig): Promise<TextEmbedding> 25 26Obtains a text embedding model. This API uses a promise to return the result. 27 28**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 29 30**Parameters** 31 32| Name | Type | Mandatory| Description | 33| ------------ | --------------------------------------- | ---- | :--------------------------------- | 34| config | [ModelConfig](#modelconfig) | Yes | Configuration of the embedded model to obtain.| 35 36**Return value** 37 38| Type | Description | 39| ----------------------------- | ------------------------------------ | 40| Promise<[TextEmbedding](#textembedding)> | Promise used to return the text embedding model object.| 41 42**Error codes** 43 44For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 45 46| **ID**| **Error Message** | 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**Example** 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 78Obtains an image embedding model. This API uses a promise to return the result. 79 80**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 81 82**Parameters** 83 84| Name | Type | Mandatory| Description | 85| ------------ | --------------------------------------- | ---- | :--------------------------------- | 86| config | [ModelConfig](#modelconfig) | Yes | Configuration of the embedded model to obtain.| 87 88**Return value** 89 90| Type | Description | 91| ----------------------------- | ------------------------------------ | 92| Promise<[ImageEmbedding](#imageembedding)> | Promise used to return the image embedding model object.| 93 94**Error codes** 95 96For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 97 98| **ID**| **Error Message** | 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**Example** 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 130Splits text. 131 132**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 133 134**Parameters** 135 136| Name | Type | Mandatory| Description | 137| ------------ | --------------------------------------- | ---- | :--------------------------------- | 138| text | string | Yes | Text to split, which can be any value.| 139| config | [SplitConfig](#splitconfig) | Yes | Configuration for splitting the text.| 140 141**Return value** 142 143| Type | Description | 144| ----------------------------- | ------------------------------------ | 145| Promise<Array<string>> | Promise used to return the blocks of the text.| 146 147**Error codes** 148 149For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 150 151| **ID**| **Error Message** | 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**Example** 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 179Represents the configuration an embedded model. 180 181**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 182 183| Name | Type | Mandatory| Description | 184| ---------- | --------------------- | ---- | ------------------------------------------------------------ | 185| version | [ModelVersion](#modelversion) | Yes |Version of the model.| 186| isNpuAvailable | boolean | Yes | Whether to use the NPU to accelerate the vectorization process. The value **true** means to use the NPU, and the value **false** means the opposite. If this parameter is set to **true** but the device does not support NPUs, loading an embedding model will trigger error 31300000.| 187| cachePath | string | No | Local directory for model caching if the NPU is used. The value is in the /xxx/xxx/xxx format, for example, **/data**. The path cannot exceed 512 characters. <br>Default value: **""**| 188 189## ModelVersion 190 191Enumerates the model versions. 192 193**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 194 195| Name | Value | Description | 196| ---------- | ---------- | ---------------------- | 197| BASIC_MODEL | 0 | Basic embedding model version. | 198 199## Image 200 201type Image = string 202 203Represents the URI of an image, which is of the string type. 204 205**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 206 207| Type | Description | 208| ---------------------------- | --------------------- | 209| string | Image URI, which cannot exceed 512 characters.| 210 211## SplitConfig 212 213Represents the configuration for text splitting. 214 215**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 216 217| Name | Type | Mandatory| Description | 218| ---------- | --------------------- | ---- | ------------------------------------------------------------ | 219| size | number | Yes |Maximum size of a block. The value is a non-negative integer.| 220| overlapRatio | number | Yes | Overlap ratio between adjacent blocks. <br>Value range: [0,1]<br>The value **0** indicates the lowest overlap ratio, and **1** indicates the highest overlap ratio.| 221 222 223## TextEmbedding 224 225Provides APIs for manipulating text embedding models. 226 227Before calling any of the following APIs, you must obtain a **TextEmbedding** instance by using [intelligence.getTextEmbeddingModel](#intelligencegettextembeddingmodel). 228 229**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 230 231### loadModel 232 233loadModel(): Promise<void> 234 235Loads this embedding model. This API uses a promise to return the result. 236 237**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 238 239**Return value** 240 241| Type | Description | 242| ----------------------------- | ------------------------------------ | 243| Promise<void> | Promise that returns no value.| 244 245**Error codes** 246 247For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 248 249| **ID**| **Error Message** | 250| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 251| 801 | Capability not supported. | 252| 31300000 | Inner error. | | 253 254**Example** 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 272Releases this embedding model. This API uses a promise to return the result. 273 274**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 275 276**Return value** 277 278| Type | Description | 279| ----------------------------- | ------------------------------------ | 280| Promise<void> | Promise that returns no value.| 281 282**Error codes** 283 284For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 285 286| **ID**| **Error Message** | 287| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 288| 801 | Capability not supported. | 289| 31300000 | Inner error. | | 290 291**Example** 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 309Obtains the embedding vector of the given text. 310 311Before calling this API, ensure that an embedding model is successfully loaded by using [loadModel](#loadmodel). 312 313**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 314 315**Parameters** 316 317| Name | Type | Mandatory| Description | 318| ------------ | --------------------------------------- | ---- | :--------------------------------- | 319| text | string | Yes | Text for the embedding model. It cannot exceed 512 characters.| 320 321**Return value** 322 323| Type | Description | 324| ----------------------------- | ------------------------------------ | 325| Promise<Array<number>> | Promise used to return the vectorization result.| 326 327**Error codes** 328 329For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 330 331| **ID**| **Error Message** | 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**Example** 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 358Obtains the embedding vector of a given batch of texts. 359 360Before calling this API, ensure that an embedding model is successfully loaded by using [loadModel](#loadmodel). 361 362**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 363 364**Parameters** 365 366| Name | Type | Mandatory| Description | 367| ------------ | --------------------------------------- | ---- | :--------------------------------- | 368| batchTexts | Array<string> | Yes | Batch of texts, each of which cannot exceed 512 characters.| 369 370**Return value** 371 372| Type | Description | 373| ----------------------------- | ------------------------------------ | 374| Promise<Array<Array<number>>> | Promise used to return the vectorization result.| 375 376**Error codes** 377 378For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 379 380| **ID**| **Error Message** | 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**Example** 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 405Provides APIs for manipulating image embedding models. 406 407Before calling any of the following APIs, you must obtain a **ImageEmbedding** instance by using [intelligence.getImageEmbeddingModel](#intelligencegetimageembeddingmodel). 408 409**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 410 411### loadModel 412 413loadModel(): Promise<void> 414 415Loads this embedding model. This API uses a promise to return the result. 416 417**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 418 419**Return value** 420 421| Type | Description | 422| ----------------------------- | ------------------------------------ | 423| Promise<void> | Promise that returns no value.| 424 425**Error codes** 426 427For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 428 429| **ID**| **Error Message** | 430| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 431| 801 | Capability not supported. | 432| 31300000 | Inner error. | | 433 434**Example** 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 452Releases this embedding model. This API uses a promise to return the result. 453 454**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 455 456**Return value** 457 458| Type | Description | 459| ----------------------------- | ------------------------------------ | 460| Promise<void> | Promise that returns no value.| 461 462**Error codes** 463 464For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 465 466| **ID**| **Error Message** | 467| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 468| 801 | Capability not supported. | 469| 31300000 | Inner error. | | 470 471**Example** 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 489Obtains the embedding vector of the given image. 490 491Before calling this API, ensure that an embedding model is successfully loaded by using [loadModel](#loadmodel). 492 493**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 494 495**Parameters** 496 497| Name | Type | Mandatory| Description | 498| ------------ | --------------------------------------- | ---- | :--------------------------------- | 499| image | [Image](#image) | Yes | URI of the target image.| 500 501**Return value** 502 503| Type | Description | 504| ----------------------------- | ------------------------------------ | 505| Promise<Array<number>> | Promise used to return the vectorization result.| 506 507**Error codes** 508 509For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 510 511| **ID**| **Error Message** | 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**Example** 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``` 532
