1# @ohos.data.intelligence (ArkData Intelligence Platform) 2 3ArkData Intelligence Platform (AIP) provides application data vectorization, which leverages embedding models to convert multi-modal data such as unstructured text and images into semantic vectors. 4 5 6> **NOTE** 7> 8> 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. 9> 10> Considering the significant computing workload and resources of data vectorization processing, the APIs are only available to 2-in-1 device applications. 11 12 13## Modules to Import 14 15```ts 16import { intelligence } from '@kit.ArkData'; 17``` 18 19## intelligence.getTextEmbeddingModel 20 21getTextEmbeddingModel(config: ModelConfig): Promise<TextEmbedding> 22 23Obtains a text embedding model. This API uses a promise to return the result. 24 25**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 26 27**Parameters** 28 29| Name | Type | Mandatory| Description | 30| ------------ | --------------------------------------- | ---- | :--------------------------------- | 31| config | [ModelConfig](#modelconfig) | Yes | Configuration of the embedded model to obtain.| 32 33**Return value** 34 35| Type | Description | 36| ----------------------------- | ------------------------------------ | 37| Promise<[TextEmbedding](#textembedding)> | Promise used to return the text embedding model object.| 38 39**Error codes** 40 41For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 42 43| **ID**| **Error Message** | 44| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 45| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 46| 801 | Capability not supported. | 47| 31300000 | Inner error. | | 48 49**Example** 50 51```ts 52import { BusinessError } from '@kit.BasicServicesKit'; 53 54let textConfig:intelligence.ModelConfig = { 55 version:intelligence.ModelVersion.BASIC_MODEL, 56 isNpuAvailable:false, 57 cachePath:"/data" 58} 59let textEmbedding:intelligence.TextEmbedding; 60 61intelligence.getTextEmbeddingModel(textConfig) 62 .then((data:intelligence.TextEmbedding) => { 63 console.info("Succeeded in getting TextModel"); 64 textEmbedding = data; 65 }) 66 .catch((err:BusinessError) => { 67 console.error("Failed to get TextModel and code is " + err.code); 68 }) 69``` 70 71## intelligence.getImageEmbeddingModel 72 73getImageEmbeddingModel(config: ModelConfig): Promise<ImageEmbedding> 74 75Obtains an image embedding model. This API uses a promise to return the result. 76 77**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 78 79**Parameters** 80 81| Name | Type | Mandatory| Description | 82| ------------ | --------------------------------------- | ---- | :--------------------------------- | 83| config | [ModelConfig](#modelconfig) | Yes | Configuration of the embedded model to obtain.| 84 85**Return value** 86 87| Type | Description | 88| ----------------------------- | ------------------------------------ | 89| Promise<[ImageEmbedding](#imageembedding)> | Promise used to return the image embedding model object.| 90 91**Error codes** 92 93For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 94 95| **ID**| **Error Message** | 96| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 97| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 98| 801 | Capability not supported. | 99| 31300000 | Inner error. | | 100 101**Example** 102 103```ts 104import { BusinessError } from '@kit.BasicServicesKit'; 105 106let imageConfig:intelligence.ModelConfig = { 107 version:intelligence.ModelVersion.BASIC_MODEL, 108 isNpuAvailable:false, 109 cachePath:"/data" 110} 111let imageEmbedding:intelligence.ImageEmbedding; 112 113intelligence.getImageEmbeddingModel(imageConfig) 114 .then((data:intelligence.ImageEmbedding) => { 115 console.info("Succeeded in getting ImageModel"); 116 imageEmbedding = data; 117 }) 118 .catch((err:BusinessError) => { 119 console.error("Failed to get ImageModel and code is " + err.code); 120 }) 121``` 122 123## intelligence.splitText 124 125splitText(text: string, config: SplitConfig): Promise<Array<string>> 126 127Splits text. 128 129**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 130 131**Parameters** 132 133| Name | Type | Mandatory| Description | 134| ------------ | --------------------------------------- | ---- | :--------------------------------- | 135| text | string | Yes | Text to split, which can be any value.| 136| config | [SplitConfig](#splitconfig) | Yes | Configuration for splitting the text.| 137 138**Return value** 139 140| Type | Description | 141| ----------------------------- | ------------------------------------ | 142| Promise<Array<string>> | Promise used to return the blocks of the text.| 143 144**Error codes** 145 146For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 147 148| **ID**| **Error Message** | 149| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 150| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 151| 801 | Capability not supported. | 152| 31300000 | Inner error. | | 153 154**Example** 155 156```ts 157import { BusinessError } from '@kit.BasicServicesKit'; 158 159let splitConfig:intelligence.SplitConfig = { 160 size:10, 161 overlapRatio:0.1 162} 163let splitText = 'text'; 164 165intelligence.splitText(splitText, splitConfig) 166 .then((data:Array<string>) => { 167 console.info("Succeeded in splitting Text"); 168 }) 169 .catch((err:BusinessError) => { 170 console.error("Failed to split Text and code is " + err.code); 171 }) 172``` 173 174## ModelConfig 175 176Represents the configuration an embedded model. 177 178**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 179 180| Name | Type | Mandatory| Description | 181| ---------- | --------------------- | ---- | ------------------------------------------------------------ | 182| version | [ModelVersion](#modelversion) | Yes |Version of the model.| 183| 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.| 184| 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: **""**| 185 186## ModelVersion 187 188Enumerates the model versions. 189 190**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 191 192| Name | Value | Description | 193| ---------- | ---------- | ---------------------- | 194| BASIC_MODEL | 0 | Basic embedding model version. | 195 196## Image 197 198type Image = string 199 200Represents the URI of an image, which is of the string type. 201 202**System capability**: SystemCapability.DistributedDataManager.RelationalStore.Core 203 204| Type | Description | 205| ---------------------------- | --------------------- | 206| string | Image URI, which cannot exceed 512 characters.| 207 208## SplitConfig 209 210Represents the configuration for text splitting. 211 212**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 213 214| Name | Type | Mandatory| Description | 215| ---------- | --------------------- | ---- | ------------------------------------------------------------ | 216| size | number | Yes |Maximum size of a block. The value is a non-negative integer.| 217| 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.| 218 219 220## TextEmbedding 221 222Provides APIs for manipulating text embedding models. 223 224Before calling any of the following APIs, you must obtain a **TextEmbedding** instance by using [intelligence.getTextEmbeddingModel](#intelligencegettextembeddingmodel). 225 226**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 227 228### loadModel 229 230loadModel(): Promise<void> 231 232Loads this embedding model. This API uses a promise to return the result. 233 234**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 235 236**Return value** 237 238| Type | Description | 239| ----------------------------- | ------------------------------------ | 240| Promise<void> | Promise that returns no value.| 241 242**Error codes** 243 244For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 245 246| **ID**| **Error Message** | 247| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 248| 801 | Capability not supported. | 249| 31300000 | Inner error. | | 250 251**Example** 252 253```ts 254import { BusinessError } from '@kit.BasicServicesKit'; 255 256textEmbedding.loadModel() 257 .then(() => { 258 console.info("Succeeded in loading Model"); 259 }) 260 .catch((err:BusinessError) => { 261 console.error("Failed to load Model and code is " + err.code); 262 }) 263``` 264 265### releaseModel 266 267releaseModel(): Promise<void> 268 269Releases this embedding model. This API uses a promise to return the result. 270 271**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 272 273**Return value** 274 275| Type | Description | 276| ----------------------------- | ------------------------------------ | 277| Promise<void> | Promise that returns no value.| 278 279**Error codes** 280 281For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 282 283| **ID**| **Error Message** | 284| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 285| 801 | Capability not supported. | 286| 31300000 | Inner error. | | 287 288**Example** 289 290```ts 291import { BusinessError } from '@kit.BasicServicesKit'; 292 293textEmbedding.releaseModel() 294 .then(() => { 295 console.info("Succeeded in releasing Model"); 296 }) 297 .catch((err:BusinessError) => { 298 console.error("Failed to release Model and code is " + err.code); 299 }) 300``` 301 302### getEmbedding 303 304getEmbedding(text: string): Promise<Array<number>> 305 306Obtains the embedding vector of the given text. 307 308Before calling this API, ensure that an embedding model is successfully loaded by using [loadModel](#loadmodel). 309 310**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 311 312**Parameters** 313 314| Name | Type | Mandatory| Description | 315| ------------ | --------------------------------------- | ---- | :--------------------------------- | 316| text | string | Yes | Text for the embedding model, which cannot exceed 512 characters.| 317 318**Return value** 319 320| Type | Description | 321| ----------------------------- | ------------------------------------ | 322| Promise<Array<number>> | Promise used to return the vectorization result.| 323 324**Error codes** 325 326For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 327 328| **ID**| **Error Message** | 329| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 330| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 331| 801 | Capability not supported. | 332| 31300000 | Inner error. | | 333 334**Example** 335 336```ts 337import { BusinessError } from '@kit.BasicServicesKit'; 338 339 340textEmbedding.loadModel(); 341let text = 'text'; 342textEmbedding.getEmbedding(text) 343 .then((data:Array<number>) => { 344 console.info("Succeeded in getting Embedding"); 345 }) 346 .catch((err:BusinessError) => { 347 console.error("Failed to get Embedding and code is " + err.code); 348 }) 349``` 350 351### getEmbedding 352 353getEmbedding(batchTexts: Array<string>): Promise<Array<Array<number>>> 354 355Obtains the embedding vector of a given batch of texts. 356 357Before calling this API, ensure that an embedding model is successfully loaded by using [loadModel](#loadmodel). 358 359**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 360 361**Parameters** 362 363| Name | Type | Mandatory| Description | 364| ------------ | --------------------------------------- | ---- | :--------------------------------- | 365| batchTexts | Array<string> | Yes | Batch of texts, each of which cannot exceed 512 characters.| 366 367**Return value** 368 369| Type | Description | 370| ----------------------------- | ------------------------------------ | 371| Promise<Array<Array<number>>> | Promise used to return the vectorization result.| 372 373**Error codes** 374 375For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 376 377| **ID**| **Error Message** | 378| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 379| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 380| 801 | Capability not supported. | 381| 31300000 | Inner error. | | 382 383**Example** 384 385```ts 386import { BusinessError } from '@kit.BasicServicesKit'; 387 388 389textEmbedding.loadModel(); 390let batchTexts = ['text1','text2']; 391textEmbedding.getEmbedding(batchTexts) 392 .then((data:Array<Array<number>>) => { 393 console.info("Succeeded in getting Embedding"); 394 }) 395 .catch((err:BusinessError) => { 396 console.error("Failed to get Embedding and code is " + err.code); 397 }) 398``` 399 400## ImageEmbedding 401 402Provides APIs for manipulating image embedding models. 403 404Before calling any of the following APIs, you must obtain a **ImageEmbedding** instance by using [intelligence.getImageEmbeddingModel](#intelligencegetimageembeddingmodel). 405 406**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 407 408### loadModel 409 410loadModel(): Promise<void> 411 412Loads this embedding model. This API uses a promise to return the result. 413 414**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 415 416**Return value** 417 418| Type | Description | 419| ----------------------------- | ------------------------------------ | 420| Promise<void> | Promise that returns no value.| 421 422**Error codes** 423 424For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 425 426| **ID**| **Error Message** | 427| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 428| 801 | Capability not supported. | 429| 31300000 | Inner error. | | 430 431**Example** 432 433```ts 434import { BusinessError } from '@kit.BasicServicesKit'; 435 436imageEmbedding.loadModel() 437 .then(() => { 438 console.info("Succeeded in loading Model"); 439 }) 440 .catch((err:BusinessError) => { 441 console.error("Failed to load Model and code is " + err.code); 442 }) 443``` 444 445### releaseModel 446 447releaseModel(): Promise<void> 448 449Releases this embedding model. This API uses a promise to return the result. 450 451**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 452 453**Return value** 454 455| Type | Description | 456| ----------------------------- | ------------------------------------ | 457| Promise<void> | Promise that returns no value.| 458 459**Error codes** 460 461For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 462 463| **ID**| **Error Message** | 464| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 465| 801 | Capability not supported. | 466| 31300000 | Inner error. | | 467 468**Example** 469 470```ts 471import { BusinessError } from '@kit.BasicServicesKit'; 472 473imageEmbedding.releaseModel() 474 .then(() => { 475 console.info("Succeeded in releasing Model"); 476 }) 477 .catch((err:BusinessError) => { 478 console.error("Failed to release Model and code is " + err.code); 479 }) 480``` 481 482### getEmbedding 483 484getEmbedding(image: Image): Promise<Array<number>> 485 486Obtains the embedding vector of the given image. 487 488Before calling this API, ensure that an embedding model is successfully loaded by using [loadModel](#loadmodel). 489 490**System capability**: SystemCapability.DistributedDataManager.DataIntelligence.Core 491 492**Parameters** 493 494| Name | Type | Mandatory| Description | 495| ------------ | --------------------------------------- | ---- | :--------------------------------- | 496| image | [Image](#image) | Yes | URI of the target image.| 497 498**Return value** 499 500| Type | Description | 501| ----------------------------- | ------------------------------------ | 502| Promise<Array<number>> | Promise used to return the vectorization result.| 503 504**Error codes** 505 506For details about the error codes, see [Common Error Codes](../errorcode-universal.md) and [AIP Error Codes](errorcode-intelligence.md). 507 508| **ID**| **Error Message** | 509| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | 510| 401 | Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types. | 511| 801 | Capability not supported. | 512| 31300000 | Inner error. | | 513 514**Example** 515 516```ts 517import { BusinessError } from '@kit.BasicServicesKit'; 518 519imageEmbedding.loadModel(); 520let image = 'file://<packageName>/data/storage/el2/base/haps/entry/files/xxx.jpg'; 521imageEmbedding.getEmbedding(image) 522 .then((data:Array<number>) => { 523 console.info("Succeeded in getting Embedding"); 524 }) 525 .catch((err:BusinessError) => { 526 console.error("Failed to get Embedding and code is " + err.code); 527 }) 528``` 529
