应用数据向量化 (ArkTS)

场景介绍

在数字化向智能化演进的关键阶段，构建智慧化服务已成为应用开发者提升产品竞争力的必然选择。

当前，系统提供ArkData智慧数据平台（ArkData Intelligence Platform，AIP），提供端侧数据智慧化构建，使应用数据向量化，通过嵌入模型将非结构化的文本、图像等多模态数据，转换成具有语义的向量。

从API version 15开始，支持应用数据向量化。

基本概念

在智慧化数据构建过程中，涉及以下基本概念，请先了解相关含义。

向量化

向量化主要是指通过嵌入模型将高维非结构化数据（如文字、图像）映射为低维连续向量的嵌入技术。嵌入技术通过模型捕捉数据之间的语义关系，将抽象概念转化为可计算的数学表示，使计算机能够理解非结构化数据。目前，嵌入技术广泛应用于自然语言处理（语义搜索）、图像识别（特征提取）、推荐系统（用户/物品表征）等领域。

多模态嵌入模型

应用数据向量化，主要通过嵌入模型实现。当前支持多模态嵌入模型，能将文本和图像这两种不同数据模态转换到同一个向量空间，支持单模态（文搜文、图搜图）和跨模态（文搜图、图搜文）的语义表征能力。

文本分块

数据向量化时，文本数据长度受限，可通过AIP分块接口切分文本，高效实现数据向量化。

实现机制

应用可借助智慧数据平台能力，实现智慧化数据的构建，将应用数据转化为可计算的向量，相关能力均运行在应用进程内，数据不出应用，保证隐私安全。

运作机制

应用数据向量化，将应用原数据向量化并存储在向量数据库中。

约束限制

• 文本向量化模型：
  • API版本26.0.0之前，支持在PC/2in1设备上使用文本向量化模型。
  • 从API版本26.0.0开始，支持在PC/2in1、Phone和Tablet设备上使用文本向量化模型。
  • 其中，针对Phone和Tablet设备，仅支持在Kirin 9010s及以上版本的设备上使用文本向量化模型。
• 图像向量化模型：仅支持在PC/2in1设备上使用。
• 嵌入模型的推理过程可使用NPU加速。与NPU计算相比，纯CPU的计算在时延和功耗上都有较大差距，建议采用NPU加速。
• 模型推理单次可处理的文本长度上限为512个字符，支持中英文。
• 模型推理单次可处理的图像大小小于20MB。
• 生成的向量仅在本设备有效，不可用于跨设备检索。

接口说明

以下是智慧数据向量化功能的相关接口。更多接口及使用方式请见智慧数据平台。

文本向量化开发步骤

1. 导入模块。

   import { intelligence } from '@kit.ArkData';
   import { BusinessError } from '@kit.BasicServicesKit';

   Index.ets

2. 获取文本嵌入模型。

   • 针对PC/2in1设备：使用端侧嵌入模型，需配置模型版本、是否使用NPU加速及模型缓存路径。示例代码如下所示：

     let textConfig: intelligence.ModelConfig = {
       version: intelligence.ModelVersion.BASIC_MODEL,
       isNpuAvailable: false,
       cachePath: "/data"
     }
     let textEmbedding: intelligence.TextEmbedding;
     let modelInfo:  intelligence.CloudModelInfo;

     Index.ets

     intelligence.getTextEmbeddingModel(textConfig)
       .then((data: intelligence.TextEmbedding) => {
         console.info('Succeeded in getting TextModel');
         textEmbedding = data;
         // ...
       })
       .catch((err: BusinessError) => {
         console.error('Failed to get TextModel and code is ' + err.code);
         // ...
       })

     Index.ets

   • 针对Phone/Tablet设备：使用云侧嵌入模型，需调用getSupportedCloudModel方法获取云侧模型信息并配置下载模型使用的网络策略。示例代码如下所示：

     intelligence.getSupportedCloudModel()
       .then((info: Array<intelligence.CloudModelInfo>) => {
         console.info('Succeeded in getting supported model');
         if (info.length > 0) {
           modelInfo = info[0];
         }
       })

     if (modelInfo !== undefined) {
       textConfig.modelInfo = modelInfo;
       textConfig.networkPolicy = intelligence.NetworkPolicy.WIFI_ONLY;
     }
     intelligence.getTextEmbeddingModel(textConfig)
       .then((data: intelligence.TextEmbedding) => {
         console.info('Succeeded in getting TextModel');
         textEmbedding = data;
         // ...
       })
       .catch((err: BusinessError) => {
         console.error('Failed to get TextModel and code is ' + err.code);
         // ...
       })

3. 加载文本嵌入模型。

   调用loadModel方法，加载文本嵌入模型。示例代码如下所示：

   textEmbedding.loadModel()
     .then(() => {
       console.info('Succeeded in loading Model');
       // ...
     })
     .catch((err: BusinessError) => {
       console.error('Failed to load Model and code is ' + err.code);
       // ...
     })

   Index.ets

4. 获取文本的分块。当数据长度超过限定时，使用splitText()接口将其分块，然后再进行数据向量化。

   调用splitText方法，获取文本的分块结果。示例代码如下所示：

   let splitConfig:intelligence.SplitConfig = {
     size: 10,
     overlapRatio: 0.1
   }
   let splitText = 'text';
   
   intelligence.splitText(splitText, splitConfig)
     .then((data: Array<string>) => {
       console.info('Succeeded in splitting Text');
       // ...
     })
     .catch((err: BusinessError) => {
       console.error('Failed to split Text and code is ' + err.code);
       // ...
     })

   Index.ets

5. 获取给定文本的嵌入向量。给定的文本数据可以是单个文本或文本集合。

   调用getEmbedding方法，获取给定单个文本或文本集合的嵌入向量。示例代码如下所示：

   let text = 'text';
   textEmbedding.getEmbedding(text)
     .then((data: Array<number>) => {
       console.info('Succeeded in getting Embedding');
       // ...
     })
     .catch((err: BusinessError) => {
       console.error('Failed to get Embedding and code is ' + err.code);
       // ...
     })
   
   let batchTexts = ['text1','text2'];
   textEmbedding.getEmbedding(batchTexts)
     .then((data: Array<Array<number>>) => {
       console.info('Succeeded in getting Embedding');
       // ...
     })
     .catch((err: BusinessError) => {
       console.error('Failed to get Embedding and code is ' + err.code);
       // ...
     })

   Index.ets

6. 释放文本嵌入模型。

   调用releaseModel方法，释放文本嵌入模型。示例代码如下所示：

   textEmbedding.releaseModel()
     .then(() => {
       console.info('Succeeded in releasing Model');
       // ...
     })
     .catch((err: BusinessError) => {
       console.error('Failed to release Model and code is ' + err.code);
       // ...
     })

   Index.ets

图像向量化开发步骤

1. 导入模块。

   import { intelligence } from '@kit.ArkData';
   import { BusinessError } from '@kit.BasicServicesKit';

   Index.ets

2. 获取图像嵌入模型。

   调用getImageEmbeddingModel方法，获取图像嵌入模型。示例代码如下所示：

   let imageConfig: intelligence.ModelConfig = {
     version: intelligence.ModelVersion.BASIC_MODEL,
     isNpuAvailable: false,
     cachePath: "/data"
   }
   let imageEmbedding: intelligence.ImageEmbedding;

   Index.ets

   intelligence.getImageEmbeddingModel(imageConfig)
     .then((data: intelligence.ImageEmbedding) => {
       console.info('Succeeded in getting ImageModel');
       imageEmbedding = data;
       // ...
     })
     .catch((err: BusinessError) => {
       console.error('Failed to get ImageModel and code is ' + err.code);
       // ...
     })

   Index.ets

3. 加载图像嵌入模型。

   调用loadModel方法，加载图像嵌入模型。示例代码如下所示：

   imageEmbedding.loadModel()
     .then(() => {
       console.info('Succeeded in loading Model');
       // ...
     })
     .catch((err: BusinessError) => {
       console.error('Failed to load Model and code is ' + err.code);
       // ...
     })

   Index.ets

4. 获取给定图像的嵌入向量。

   调用getEmbedding方法，获取给定图像的嵌入向量。示例代码如下所示：

   let image = 'file://<packageName>/data/storage/el2/base/haps/entry/files/xxx.jpg';
   imageEmbedding.getEmbedding(image)
     .then((data: Array<number>) => {
       console.info('Succeeded in getting Embedding');
       // ...
     })
     .catch((err: BusinessError) => {
       console.error('Failed to get Embedding and code is ' + err.code);
       // ...
     })

   Index.ets

5. 释放图像嵌入模型。

   调用releaseModel方法，释放图像嵌入模型。示例代码如下所示：

   imageEmbedding.releaseModel()
     .then(() => {
       console.info('Succeeded in releasing Model');
       // ...
     })
     .catch((err: BusinessError) => {
       console.error('Failed to release Model and code is ' + err.code);
       // ...
     })

   Index.ets