• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# 应用数据向量化 (ArkTS)
2<!--Kit: ArkData-->
3<!--Subsystem: DistributedDataManager-->
4<!--Owner: @my-2024; @cuile44; @pancodax-->
5<!--Designer: @fysun17; @AnruiWang; @xd_94-->
6<!--Tester: @yippo; @logic42-->
7<!--Adviser: @ge-yafang-->
8
9## 场景介绍
10
11在数字化向智能化演进的关键阶段，构建智慧化服务已成为应用开发者提升产品竞争力的必然选择。
12
13当前，系统提供ArkData智慧数据平台（ArkData Intelligence Platform，AIP），提供端侧数据智慧化构建，使应用数据向量化，通过嵌入模型将非结构化的文本、图像等多模态数据，转换成具有语义的向量。
14
15从API version 15开始，支持应用数据向量化。
16
17## 基本概念
18
19在智慧化数据构建过程中，涉及以下基本概念，请先了解相关含义。
20
21### 向量化
22向量化主要是指通过嵌入模型将高维非结构化数据（如文字、图像）映射为低维连续向量的嵌入技术。嵌入技术通过模型捕捉数据之间的语义关系，将抽象概念转化为可计算的数学表示，使计算机能够理解非结构化数据。目前，嵌入技术广泛应用于自然语言处理（语义搜索）、图像识别（特征提取）、推荐系统（用户/物品表征）等领域。
23
24### 多模态嵌入模型
25应用数据向量化，主要通过嵌入模型实现。当前支持多模态嵌入模型，能将文本和图像这两种不同数据模态转换到同一个向量空间，支持单模态（文搜文、图搜图）和跨模态（文搜图、图搜文）的语义表征能力。
26
27### 文本分块
28数据向量化时，文本数据长度受限，可通过AIP分块接口切分文本，高效实现数据向量化。
29
30## 实现机制
31
32应用可借助智慧数据平台能力，实现智慧化数据的构建，将应用数据转化为可计算的向量，相关能力均运行在应用进程内，数据不出应用，保证隐私安全。
33
34## 运作机制
35应用数据向量化，将应用原数据向量化并存储在向量数据库中。
36
37## 约束限制
38- 考虑到数据向量化处理的计算量和资源占用较大，当前仅支持在2in1设备上使用。
39- 嵌入模型的推理过程可使用NPU加速。与NPU计算相比，纯CPU的计算在时延和功耗上都有较大差距，建议采用NPU加速。
40- 模型推理单次可处理的文本长度上限为512个字符，支持中英文。
41- 模型推理单次可处理的图像大小小于20MB。
42
43## 接口说明
44
45以下是智慧数据向量化功能的相关接口。更多接口及使用方式请见[智慧数据平台](../reference/apis-arkdata/js-apis-data-intelligence.md)。
46
47| 接口名称 | 描述 |
48| -------- | -------- |
49| getTextEmbeddingModel(config: ModelConfig): Promise&lt;TextEmbedding&gt; | 获取文本嵌入模型。 |
50| loadModel(): Promise&lt;void&gt; | 加载文本嵌入模型。 |
51| splitText(text: string, config: SplitConfig): Promise&lt;Array&lt;string&gt;&gt; | 获取文本的分块。 |
52| getEmbedding(text: string): Promise&lt;Array&lt;number&gt;&gt; | 获取给定文本的嵌入向量。 |
53| getEmbedding(batchTexts: Array&lt;string&gt;): Promise&lt;Array&lt;Array&lt;number&gt;&gt;&gt; | 获取给定批次文本的嵌入向量。 |
54| releaseModel(): Promise&lt;void&gt; | 释放文本嵌入模型。 |
55| getImageEmbeddingModel(config: ModelConfig): Promise&lt;ImageEmbedding&gt; | 获取图像嵌入模型。 |
56| loadModel(): Promise&lt;void&gt; | 加载图像嵌入模型。 |
57| getEmbedding(image: Image): Promise&lt;Array&lt;number&gt;&gt; | 获取给定图像的嵌入向量。 |
58| releaseModel(): Promise&lt;void&gt; | 释放图像嵌入模型。 |
59
60## 文本向量化开发步骤
61
621. 导入模块。
63
64   ```ts
65   import { intelligence } from '@kit.ArkData';
66   ```
67
682. 获取文本嵌入模型。
69   调用getTextEmbeddingModel方法，获取文本嵌入模型。示例代码如下所示：
70
71   ```ts
72   import { BusinessError } from '@kit.BasicServicesKit';
73
74   let textConfig:intelligence.ModelConfig = {
75     version:intelligence.ModelVersion.BASIC_MODEL,
76     isNpuAvailable:false,
77     cachePath:"/data"
78   }
79   let textEmbedding:intelligence.TextEmbedding;
80
81   intelligence.getTextEmbeddingModel(textConfig)
82     .then((data:intelligence.TextEmbedding) => {
83       console.info("Succeeded in getting TextModel");
84       textEmbedding = data;
85     })
86     .catch((err:BusinessError) => {
87       console.error("Failed to get TextModel and code is " + err.code);
88     })
89   ```
90
913. 加载文本嵌入模型。
92   调用loadModel方法，加载文本嵌入模型。示例代码如下所示：
93
94   ```ts
95   textEmbedding.loadModel()
96     .then(() => {
97       console.info("Succeeded in loading Model");
98     })
99     .catch((err:BusinessError) => {
100       console.error("Failed to load Model and code is " + err.code);
101     })
102   ```
103
1044. 获取文本的分块。当数据长度超过限定时，使用splitText()接口将其分块，然后再进行数据向量化。
105   调用splitText方法，获取文本的分块结果。示例代码如下所示：
106
107   ```ts
108   let splitConfig:intelligence.SplitConfig = {
109     size:10,
110     overlapRatio:0.1
111   }
112   let splitText = 'text';
113
114   intelligence.splitText(splitText, splitConfig)
115     .then((data:Array<string>) => {
116       console.info("Succeeded in splitting Text");
117     })
118     .catch((err:BusinessError) => {
119       console.error("Failed to split Text and code is " + err.code);
120     })
121   ```
122
1235. 获取给定文本的嵌入向量。给定的文本数据可以是单个文本或文本集合。
124   调用getEmbedding方法，获取给定单个文本或文本集合的嵌入向量。示例代码如下所示：
125
126   ```ts
127   let text = 'text';
128   textEmbedding.getEmbedding(text)
129     .then((data:Array<number>) => {
130       console.info("Succeeded in getting Embedding");
131     })
132     .catch((err:BusinessError) => {
133       console.error("Failed to get Embedding and code is " + err.code);
134     })
135   ```
136
137   ```ts
138   let batchTexts = ['text1','text2'];
139   textEmbedding.getEmbedding(batchTexts)
140     .then((data:Array<Array<number>>) => {
141       console.info("Succeeded in getting Embedding");
142     })
143     .catch((err:BusinessError) => {
144       console.error("Failed to get Embedding and code is " + err.code);
145     })
146   ```
147
1486. 释放文本嵌入模型。
149   调用releaseModel方法，释放文本嵌入模型。示例代码如下所示：
150
151   ```ts
152   textEmbedding.releaseModel()
153     .then(() => {
154       console.info("Succeeded in releasing Model");
155     })
156     .catch((err:BusinessError) => {
157       console.error("Failed to release Model and code is " + err.code);
158     })
159   ```
160
161## 图像向量化开发步骤
162
1631. 导入模块。
164
165   ```ts
166   import { intelligence } from '@kit.ArkData';
167   ```
168
1692. 获取图像嵌入模型。
170   调用getImageEmbeddingModel方法，获取图像嵌入模型。示例代码如下所示：
171
172   ```ts
173   let imageConfig:intelligence.ModelConfig = {
174     version:intelligence.ModelVersion.BASIC_MODEL,
175     isNpuAvailable:false,
176     cachePath:"/data"
177   }
178   let imageEmbedding:intelligence.ImageEmbedding;
179
180   intelligence.getImageEmbeddingModel(imageConfig)
181     .then((data:intelligence.ImageEmbedding) => {
182       console.info("Succeeded in getting ImageModel");
183       imageEmbedding = data;
184     })
185     .catch((err:BusinessError) => {
186       console.error("Failed to get ImageModel and code is " + err.code);
187     })
188   ```
189
1903. 加载图像嵌入模型。
191   调用loadModel方法，加载图像嵌入模型。示例代码如下所示：
192
193   ```ts
194   imageEmbedding.loadModel()
195     .then(() => {
196        console.info("Succeeded in loading Model");
197     })
198     .catch((err:BusinessError) => {
199        console.error("Failed to load Model and code is " + err.code);
200     })
201   ```
202
2034. 获取给定图像的嵌入向量。
204   调用getEmbedding方法，获取给定图像的嵌入向量。示例代码如下所示：
205
206    ```ts
207    let image = "file://<packageName>/data/storage/el2/base/haps/entry/files/xxx.jpg";
208    imageEmbedding.getEmbedding(image)
209      .then((data:Array<number>) => {
210        console.info("Succeeded in getting Embedding");
211      })
212      .catch((err:BusinessError) => {
213        console.error("Failed to get Embedding and code is " + err.code);
214      })
215    ```
216
2175. 释放图像嵌入模型。
218   调用releaseModel方法，释放图像嵌入模型。示例代码如下所示：
219
220    ```ts
221    imageEmbedding.releaseModel()
222      .then(() => {
223        console.info("Succeeded in releasing Model");
224      })
225      .catch((err:BusinessError) => {
226        console.error("Failed to release Model and code is " + err.code);
227      })
228    ```
229