目录

retrieval（智慧化数据平台）

智慧数据平台（ArkData Intelligence Platform，AIP）提供端侧的数据智慧化能力，实现数据和AI智能在端侧闭环。作为端侧智慧化能力底座，将支持以下能力：

起始版本： 6.0.0(20)

导入模块

import { retrieval } from '@kit.DataAugmentationKit';

getRetriever

getRetriever(config: RetrievalConfig): Promise<Retriever>

获取检索器，进行多路检索召回。使用promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

参数：

参数名 类型 必填 说明
config RetrievalConfig 是 检索器的配置信息。该参数用于配置检索器的行为，包括不同检索回路的配置信息数组。其中，channelConfigs字段为必填项，表示不同检索回路的配置信息数组。

返回值：

类型 说明
Promise<Retriever> Promise对象，返回检索器对象。

示例：

import { retrieval } from '@kit.DataAugmentationKit';
import { relationalStore } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Page {
  async retrieve() {
    let vectorDBConfig:retrieval.DbConfig = {
      name:"vector_store_test.db",
      securityLevel:relationalStore.SecurityLevel.S3
    }

    let invidxDBConfig:retrieval.DbConfig = {
      name:"invidx_store_test.db",
      securityLevel:relationalStore.SecurityLevel.S3
    }
    let context: Context | undefined = this.getUIContext().getHostContext();
    if (context == undefined) {
      console.info("getHostContext failed.");
      return;
    }
    let channelConfigVector:retrieval.ChannelConfig = {
      channelType:retrieval.ChannelType.VECTOR_DATABASE,
      context:context,
      dbConfig:vectorDBConfig
    }

    let channelConfigInvIdx:retrieval.ChannelConfig = {
      channelType:retrieval.ChannelType.INVERTED_INDEX_DATABASE,
      context:context,
      dbConfig:invidxDBConfig
    }

    let retrievalConfig:retrieval.RetrievalConfig = {
      channelConfigs:[channelConfigInvIdx, channelConfigVector]
    }

    let globalRetriever:retrieval.Retriever | undefined;
    // 获取检索器
    await retrieval.getRetriever(retrievalConfig)
      .then((retriever:retrieval.Retriever) => {
        globalRetriever = retriever;
        console.info("globalRetriever is success");
      })
      .catch((err:BusinessError) => {
        globalRetriever = undefined;
        console.error("Failed to get Retriever and code is " + err.code);
      })
  }

  build() {
    Column() {
      Text('test')
    }
  }
}

RetrievalConfig

管理召回的配置

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 必填 说明
channelConfigs Array<ChannelConfig> 是 不同检索回路的配置信息数组。

ChannelConfig

管理每个检索回路的配置信息。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
channelType ChannelType 否 否 当前检索回路的数据库类型。
context common.BaseContext 否 否

应用的上下文。

FA模型的应用Context定义。

Stage模型的应用Context定义。
dbConfig DbConfig 否 否 当前检索回路的数据库配置。

ChannelType

数据库类型枚举。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 值 说明
VECTOR_DATABASE 0 向量数据库。
INVERTED_INDEX_DATABASE 1 倒排数据库。

DbConfig

type DbConfig = relationalStore.StoreConfig

数据库配置。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

类型 说明
relationalStore.StoreConfig 数据库配置。

Retriever

检索器，用于多路检索召回。

下列接口都需先使用retrieval.getRetriever获取到检索器实例，再通过此实例调用对应接口。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

[h2]retrieveRdb

retrieveRdb(query: string, condition: RetrievalCondition): Promise<RdbRecords>

给定检索条件（包含查询词分词、召回条件），从一个关系型数据库检索召回满足条件的数据，使用Promise异步回调。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

参数：

参数名 类型 必填 说明
query string 是 当前检索的查询词,长度上限为1000字节。
condition RetrievalCondition 是 检索条件。

返回值：

类型 说明
Promise<RdbRecords> Promise对象，返回检索召回数据。

错误码：

以下错误码的详细介绍请参见ArkTS API错误码。

错误码ID 错误信息
1021200001 The database is corrupted.
1021200002 The database is closed.
1021200003 The database is busy.
1021200004 The database is out of memory.
1021200100 SQLite: Generic error.
1021200101 SQLite: Access permission denied.
1021200102 SQLite: The database file is locked.
1021200103 SQLite: Some kind of disk I/O error occurred.
1021200104 SQLite: The WAL file size exceeds the default limit.
1021200105 SQLite: Unable to open the database file.
1021201000 Retrieval: An error occurred during the reacall phase.
1021201001 Retrieval: An error occurred during the re-ranking phase.
1021201002 Retrieval: The value of the numerical parameter is outside the constrained range.
1021201003 Retrieval: There are invalid primary keys.
1021201004 Retrieval: A re-ranking algorithm that does not support composite primary keys was used.
1021201005 Retrieval: There are fields with empty strings.
1021201006 Retrieval: The filter input is invalid.
1021201007 Retrieval: There are invalid recall names in RecallCondition.
1021201008 Retrieval: The vector similarity threshold in VectorQuery is higher than the tiered threshold in VectorRerankParameter.
1021201009 Retrieval: RerankMethod parameters do not match the channel type.
1021201010 Retrieval: There exists a parameter value that should not be empty but is actually empty
1021200012 Unable to generate embeddings.

示例：

import { retrieval } from '@kit.DataAugmentationKit';
import { relationalStore } from '@kit.ArkData';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Page {
 
async retrieve() {
    let vectorDBConfig:retrieval.DbConfig = {
      name:"vector_test.db",
      securityLevel:relationalStore.SecurityLevel.S3
    }

    let invidxDBConfig:retrieval.DbConfig = {
      name:"files_test.db",
      securityLevel:relationalStore.SecurityLevel.S3
    }
    let context: Context | undefined = this.getUIContext().getHostContext();
    if (context == undefined) {
      console.info("getHostContext failed.");
      return;
    }
    let channelConfigVector:retrieval.ChannelConfig = {
      channelType:retrieval.ChannelType.VECTOR_DATABASE,
      context:context,
      dbConfig:vectorDBConfig
    }

    let channelConfigInvIdx:retrieval.ChannelConfig = {
      channelType:retrieval.ChannelType.INVERTED_INDEX_DATABASE,
      context:context,
      dbConfig:invidxDBConfig
    }

    let retrievalConfig:retrieval.RetrievalConfig = {
      channelConfigs:[channelConfigInvIdx, channelConfigVector]
    }

    let globalRetriever:retrieval.Retriever | undefined;
    await retrieval.getRetriever(retrievalConfig)
      .then((retriever:retrieval.Retriever) => {
        globalRetriever = retriever;
        console.info("globalRetriever is success");
      })
      .catch((err:BusinessError) => {
        globalRetriever = undefined;
        console.error("Failed to get Retriever and code is " + err.code);
      })

    let fieldWeight:Record<string, number> = {
      "filename":4.0
    }

    let fieldSlops:Record<string, number> = {
      "filename":5
    }

    let bm25Strategy:retrieval.Bm25Strategy = {
      bm25Weight:1.5,
      columnWeight:fieldWeight
    }

    let exactStrategy:retrieval.ExactMatchingStrategy = {
      exactMatchingWeight:1.2,
      columnWeight:fieldWeight
    }

    let outOfOrderStrategy:retrieval.ProximityStrategy = {
      proximityWeight:1.0,
      columnWeight:fieldWeight,
      columnSlops:fieldSlops
    }

    let invertedIndexStrategies:Array<retrieval.InvertedIndexStrategy> = [bm25Strategy, exactStrategy, outOfOrderStrategy]

    let recallConditionInvIdx:retrieval.InvertedIndexRecallCondition ={
      ftsTableName:"files",
      primaryKey:["fileid"],
      fromClause:"files",
      responseColumns:["fileid", "filename", "keywords"],
      deepSize:2,
      invertedIndexStrategies:invertedIndexStrategies,
      recallName:"invIdxRecall"
    }

    // 这里 floatArray 是输入的query的表征向量，根据实际情况需要修改。可通过向量化接口生成，也可由开发者自行提供
    let floatArray = new Float32Array([0.006954, -0.079041, 0.046173, 0.157959, -0.017212, 0.037018, -0.072083, -0.028488, -0.099854, 0.044037, -0.008911, -0.063049, 0.035950, -0.105835, 0.057739, 0.060364, -0.062042, 0.044159, 0.143188, 0.123901, -0.069641, -0.061920, -0.086731, -0.092468, 0.092957, -0.027649, -0.005497, -0.039276, 0.017502, -0.046570, -0.115906, 0.081177, -0.153931, -0.040588, 0.123474, -0.099060, 0.062042, 0.026352, -0.041382, -0.099548, 0.071167, -0.120850, 0.082642, 0.026398, -0.035614, -0.008545, -0.076660, -0.031067, 0.192017, -0.052582, 0.005310, 0.052734, 0.199463, 0.075195, -0.070740, -0.035950, 0.073120, 0.089172, 0.075989, 0.003582, 0.050201, -0.012787, 0.016647, -0.053619, 0.001906, -0.060181, -0.068359, -0.114502, -0.045013, 0.004547, -0.004673, -0.148071, 0.126343, 0.019394, -0.063110, -0.055908, 0.071228, 0.002369, 0.041412, 0.126709, -0.053467, 0.127808, 0.055420, 0.206177, 0.002169, -0.001452, 0.095520, -0.042511, 0.099243, -0.164185, 0.093384, -0.014618, -0.129150, -0.238770, -0.085327, 0.051300, -0.020004, 0.010063, -0.084351, -0.003567, 0.064941, -0.205322, -0.158936, -0.074768, 0.104370, 0.197021, -0.080688, -0.066772, -0.036346, 0.034912, -0.019760, 0.110474, 0.128662, 0.094727, 0.024948, -0.033356, -0.081848, 0.054474, -0.065857, -0.156494, 0.002527, 0.097595, -0.027420, 0.039185, 0.063965, 0.220093, 0.029556, -0.115417]);

    let vectorQuery:retrieval.VectorQuery = {
      column:"keywords",
      value:floatArray,
      similarityThreshold:0.35
    }

    let recallConditionVector:retrieval.VectorRecallCondition = {
      vectorQuery:vectorQuery,
      fromClause:"vector",
      primaryKey:["fileid"],
      responseColumns:["filename_text", "filename", "int64_value", "double_value", "bool_value", "blob_value"],
      recallName:"vectorRecall",
      deepSize:2
    }

    let vectorWeights:Record<string, number> = {
      "vectorRecall":0.5
    }

    let invidxWeights:Record<string, number> = {
      "vectorRecall":0.5
    }

    let vectorRerankParameter:retrieval.VectorRerankParameter = {
      vectorWeights:vectorWeights,
      thresholds:[0.55, 0.45]
    }

    let invidxRerankParameter:retrieval.InvertedIndexRerankParameter = {
      invertedIndexWeights:invidxWeights,
    }

    let parameters:Record<retrieval.ChannelType, retrieval.RerankParameter> = {
      0:vectorRerankParameter,
      1:invidxRerankParameter
    }

    let rerankMethod:retrieval.RerankMethod = {
      rerankType:retrieval.RerankType.RRF,
      parameters:parameters,
      isSoftmaxNormalized:true
    }

    let groundTruthIds: Array<string> = ['1','2', '3'];
    let explain : retrieval.ExplanationConfig ={
      groundTruths: groundTruthIds
    }

    let retrievalCondition:retrieval.RetrievalCondition = {
      rerankMethod:rerankMethod,
      recallConditions:[recallConditionInvIdx, recallConditionVector],
      resultCount:2,
      explanation:explain
    }


    if (globalRetriever != undefined) {
      let query:string = "运动直播场景";
      // 执行检索
      globalRetriever.retrieveRdb(query, retrievalCondition)
        .then((rdbdata:retrieval.RdbRecords) => {

          console.info(`#########  retrieval result ############`);
          for (let i = 0; i < rdbdata.records.length; i++) {
            console.info(` primaryKey is ${rdbdata.records[i].primaryKey}`);
            Object.keys(rdbdata.records[i].columns).forEach((key) => {
              if (rdbdata.records && rdbdata.records[i]) {
                let value = rdbdata.records[i].columns[key];
                console.info(`recall Scores Key: ${key}, Value: ${value}`);
              }
            });
            console.info(`score is ${rdbdata.records[i].score}`);

            Object.keys(rdbdata.records[i].recallScores).forEach((channelType) => {
              if (rdbdata.records) {
                let scores:Record<string, retrieval.RecallScore>  = rdbdata.records[i].recallScores[channelType];
                Object.keys(scores).forEach((key)=>{
                  let value = scores[key];
                  console.info(`recall Scores channelType is ${channelType}, Key: ${key}, score: ${value.score}`);
                });
              }
            });
            console.info("recall Scores", rdbdata.records[i].recallScores.toString());
            Object.keys(rdbdata.records[i].features).forEach((key) => {
              if (rdbdata.records && rdbdata.records[i]) {
                let value = rdbdata.records[i].features[key];
                console.info(`features Key: ${key}, Value: ${value}`);
              }
            });
            console.info(`similarityLevel is ${rdbdata.records[i].similarityLevel}`);

          }

          console.info(`#########  missdGroundTruthsPrimaryKey ############`);
          if(rdbdata.missedGroundTruths != undefined && rdbdata.missedGroundTruths.length != 0){
            for (let i = 0; i < rdbdata.missedGroundTruths.length; i++) {
              console.info(`missdGroundTruthsPrimaryKey is ${rdbdata.missedGroundTruths[i].primaryKey}`);
              Object.keys(rdbdata.missedGroundTruths[i].columns).forEach((key) => {
                if (rdbdata.missedGroundTruths && rdbdata.missedGroundTruths[i]) {
                  let value = rdbdata.missedGroundTruths[i].columns[key];
                  console.info(`missdGroundTruths recall Scores Key: ${key}, Value: ${value}`);
                }
              });
              console.info(` missdGroundTruths score is ${rdbdata.missedGroundTruths[i].score}`);

              Object.keys(rdbdata.missedGroundTruths[i].recallScores).forEach((channelType) => {
                if (rdbdata.missedGroundTruths) {
                  let scores:Record<string, retrieval.RecallScore>  = rdbdata.missedGroundTruths[i].recallScores[channelType];
                  Object.keys(scores).forEach((key)=>{
                    let value = scores[key];
                    console.info(`missdGroundTruths recall Scores channelType is ${channelType}, Key: ${key}, score: ${value.score}`);
                  });
                }
              });
              console.info("missdGroundTruths recall Scores", rdbdata.missedGroundTruths[i].recallScores.toString());
              Object.keys(rdbdata.missedGroundTruths[i].features).forEach((key) => {
                if (rdbdata.missedGroundTruths && rdbdata.missedGroundTruths[i]) {
                  let value = rdbdata.missedGroundTruths[i].features[key];
                  console.info(`missdGroundTruths features Key: ${key}, Value: ${value}`);
                }
              });
              console.info(`missdGroundTruths similarityLevel is ${rdbdata.missedGroundTruths[i].similarityLevel}`);
            }
          }
          console.info("retrieval success.");
        })
        .catch((err:BusinessError) => {
          console.error("Failure in retrieveRdb and code is " + err.code);
        })
    }
  }

  build() {
    Column() {
      Text('test')
    }
  }
}

RetrievalCondition

检索条件。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
recallConditions Array<RecallCondition> 否 否 召回的条件，数组中的每个元素对应一个召回操作。
rerankMethod RerankMethod 否 是 重排方法。其参数rerankType默认值为RRF算法，参数parameters默认值遵循RecallCondition中相应检索回路的参数。
resultCount number 否 是 重排后允许返回结果的最大数量。默认值为500。必须为大于等于1的正整数。
explanation ExplanationConfig 否 是 检索解释

ExplanationConfig

检索解释配置

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
groundTruths Array<string> 否 否 待解释的文档id，为字符串类型可取任意值。

RecallCondition

type RecallCondition = InvertedIndexRecallCondition | VectorRecallCondition

召回操作的条件。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

类型 说明
InvertedIndexRecallCondition 倒排召回条件。
VectorRecallCondition 向量召回条件。

InvertedIndexRecallCondition

倒排检索的召回条件。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
ftsTableName string 否 否 倒排检索所用的fts（Full-Text Search）数据表的名称，用于执行bm25函数输入。必须为存在的表名且不能为空字符串。
fromClause string 否 否

查询目标索引名。不能为空字符串。

fromClause指定的表中包含filters中涉及的所有字段，允许两种输入：

1. 和ftsTableName填一样的值，则倒排检索将仅局限在倒排表内进行检索。

2. 提供完整select...join语句的方式，来连接fts表之外的元素表，作为检索表（注意，使用此模式时，该select语句中必须有rowid字段且必须是fts表的rowid。例如当ftsTableName为“files”时，存在一个元素表metadata需要参与filters过滤，则应如下定义fromClause："SELECT files.rowid as rowid, * FROM metadata JOIN files ON metadata.fileid = files.fileid"。）
primaryKey Array<ColumnName> 否 否 召回结果主键字段，会作为召回字段之一，作为多路召回文档聚合依据。一次查询中所有召回操作的主键字段数量之和必须和相等且不能为空。
responseColumns Array<ColumnName> 否 否 需要额外召回的字段集合。Array<ColumnName>中ColumnName不得为空。
invertedIndexStrategies Array<InvertedIndexStrategy> 否 是 召回策略列表，决定了倒排表应当如何打分。如果为空，则默认执行全表匹配。
recallName RecallName 否 是 当前检索回路的名称，作为重排阶段识别依据。默认值为随机字符串。构造方法中可以不构建该参数，如果有这个参数则值不能为空字符串。
filters Array<FilterInfo> 否 是 附加的过滤条件。
deepSize number 否 是 重排阶段包含当前召回过程的最大结果数。默认值500，必须为正整数。

ColumnName

type ColumnName = string

数据表的列名，类型为字符串。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

类型 说明
string 数据表列名对应的类型，为字符串类型可取任意值。

RecallName

type RecallName = string

召回回路名称，类型为字符串，用于给倒排和向量两路召回取名。例如出现两路向量召回时，给两路向量取名做区分。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

类型 说明
string 召回路径名称对应的类型，类型为字符串，可取任意值。

FilterInfo

过滤器信息。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
columns Array<ColumnName> 否 否 被过滤的列名称。
operator Operator 否 是 过滤条件中的操作算子。operator和filterValue、operator和filterRange至少有一组同时设置，过滤功能才能生效。
filterValue FilterValue 否 是 过滤条件中的过滤值。
filterRange FilterRange 否 是 过滤条件中的过滤范围。

FilterValue

type FilterValue = string | number | bigint

过滤条件中的过滤值。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

类型 说明
string FilterValue 收到的类型为string则过滤条件为字符串类型
number FilterValue 收到的类型为number则过滤条件为数字类型
bigint FilterValue 收到的类型为bigint则过滤条件为int64类型

FilterRange

过滤条件中的过滤值范围。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 必填 说明
max number 是 最大过滤值。
min number 是 最小过滤值，取值需小于最大过滤值。

Operator

过滤条件中的操作算子。column为数据库表中的字段名，filterValue为该字段的取值。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 值 说明
OP_EQ '=' <column>等于<filterValue>。
OP_NE '!=' <column>不等于<filterValue>。
OP_LT '<' <column>小于<filterValue>，其中<filterValue>为数值。
OP_LE '<=' <column>小于等于<filterValue>，其中<filterValue>为数值。
OP_GT '>' <column>大于<filterValue>，其中<filterValue>为数值。
OP_GE '>=' <column>大于等于<filterValue>，其中<filterValue>为数值。
OP_IN 'IN' <column> IN <filterValue>，其中<filterValue>为string且通过','组合。
OP_NOT_IN 'NOT_IN' <column> NOT IN <filterValue>，其中<filterValue>为string且通过','拼接。
OP_BETWEEN 'BETWEEN' <column>的值在 <filterRange.min> 和 <filterRange.max>之间。
OP_LIKE 'LIKE' 通过LIKE匹配含有<filterValue>的<column> ,其中<filterValue>为string。
OP_NOT_LIKE 'NOT_LIKE' <column> NOT LIKE <filterValue>，其中<filterValue>为string。

InvertedIndexStrategy

type InvertedIndexStrategy = Bm25Strategy | ExactMatchingStrategy | ProximityStrategy

倒排召回策略。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

类型 说明
Bm25Strategy 部分命中策略，检索目标只要命中查询词中的80%核心词就可以被召回，召回结果基于bm25算法进行评分，适用于对检索目标匹配要求较宽松的场景。
ExactMatchingStrategy 精确命中策略，要求检索目标和查询词完全匹配才能被召回，适用于对检索目标匹配要求较严格的场景。
ProximityStrategy 乱序命中策略，查询词的分词结果在检索目标中不必严格按照原本顺序出现，各个分词结果在指定间隔内都出现即可召回，适用于对检索目标匹配要求中等的场景。

Bm25Strategy

倒排检索所用的bm25策略。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
bm25Weight number 否 否 bm25策略的打分权重，在多种倒排策略并存的情况下，控制该策略对最终召回结果的评分影响程度。
columnWeight Record<ColumnName, number> 否 是

指定该策略运用于倒排表的哪些字段，以及这些字段对应的权重（用于控制字段匹配情况对最终结果的影响程度）

如果字段为空，则默认该策略运用于倒排表的全部字段，会默认增加1个配置，字段名为倒排表名，权重值为1.0。

如果不为空，则字段名不为空字符串，权重值为非负数。

ExactMatchingStrategy

倒排检索所用的精确场景匹配策略。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
exactMatchingWeight number 否 否 精确场景匹配策略的打分权重，在多种倒排策略并存的情况下，控制该策略对最终召回结果的评分影响程度。
columnWeight Record<ColumnName, number> 否 是

指定该策略运用于倒排表的哪些字段，以及这些字段对应的权重（用于控制字段匹配情况对最终结果的影响程度）

如果字段为空，则默认该策略运用于倒排表的全部字段，会默认增加1个配置，字段名为倒排表名，权重值为1.0。

如果不为空，则字段名不为空字符串，权重值为非负数。

ProximityStrategy

倒排检索所用的近似与乱序匹配策略。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
proximityWeight number 否 否 近似与乱序匹配策略的打分权重，在多种倒排策略并存的情况下，控制该策略对最终召回结果的评分影响程度。
columnWeight Record<ColumnName, number> 否 是

指定该策略运用于倒排表的哪些字段，以及这些字段对应的权重（用于控制字段匹配情况对最终结果的影响程度）

如果字段为空，则默认该策略运用于倒排表的全部字段，会默认增加1个配置，字段名为倒排表名，权重值为1.0。

如果不为空，则字段名不为空字符串，权重值为非负数。
columnSlops Record<ColumnName, number> 否 是 每个字段使用的偏移量配置。默认值和columnWeight相同的字段，值为10。字段不能为空，对应值必须为非负数。

VectorRecallCondition

向量检索的召回条件。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
vectorQuery VectorQuery 否 否 用于向量检索的查询词向量。
fromClause string 否 否

查询目标索引名。不能为空字符串。

fromClause指定的表中包含filters中涉及的所有字段，接受两种输入：

1. 和ftsTableName填一样的值，则倒排检索将仅局限在倒排表内进行检索；

2. 提供完整select...join语句的方式，来连接fts表之外的元素表，作为倒排这一路的被检索表。（使用此模式时，该select语句中必须有rowid字段且必须定义为fts表的rowid。例如：当ftsTableName为“files”时，存在一个元素表metadata需要参与filters过滤，则应如下定义fromClause："SELECT files.rowid as rowid, * FROM metadata JOIN files ON metadata.fileid = files.fileid"。）。
primaryKey Array<ColumnName> 否 否 召回结果主键字段，会作为召回字段之一，作为多路召回文档聚合依据。一次查询中所有RecallCondition的主键字段数量必须相等且不能为空。
responseColumns Array<ColumnName> 否 否 需要额外召回的字段集合。ColumnName不得为空。
recallName RecallName 否 是 当前检索回路的名称，作为重排阶段识别依据。默认值为随机字符串，不能为空字符串
filters Array<FilterInfo> 否 是 额外的过滤条件。
deepSize number 否 是 当前召回过程给重排阶段返回的最大结果数。默认值500，必须为正整数。

VectorQuery

根据查询词生成的向量。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
column ColumnName 否 否 待匹配向量字段名。必须为指定的向量数据库中存在的向量类型字段。
value Float32Array 否 是

向量列的向量值。

如果未定义value字段，系统将尝试将原始query生成向量。目前在PC上支持自动生成。

从HarmonyOS 6.0.0 Beta2版本开始，此参数由“必填”变更为“可选”。
similarityThreshold number 否 是 向量阈值，用于过滤不相似向量的阈值。默认值为1，取值范围为[0, VectorRerankParameter中有效thresholds的最小值]，包含边界值。

RerankMethod

重排策略的参数。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
rerankType RerankType 否 否 重排算法，取值类型为枚举类RerankType，可选项为RRF、FUSED_SCORE，分别指向rrf排序算法以及分数融合排序算法。默认值为RRF。
parameters Record<ChannelType, RerankParameter> 否 是 每个召回回路对应的重排参数。如果上述检索参数RetrievalCondition中的存在的channelType未在parameters中配置重排参数，则会自动填充该channelType对应的重排参数默认值。倒排的重排参数默认值参考InvertedIndexRerankParameter，向量的重排参数默认值参考VectorRerankParameter。
isSoftmaxNormalized boolean 否 是 FUSED_SCORE模式下，是否使用softmax函数归一化计算重排最终得分。默认为false。true表示使用softmax函数归一化计算重排最终得分，false表示不使用。

RerankType

重排算法的类型。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 值 说明
RRF 0

Reciprocal Rank Fusion(RRF)方法。根据各路召回位置信息进行分档排序。

适用场景：对结果多样性要求较高的场景，希望每路结果平等输出。
FUSION_SCORE 1 基于得分的召回融合方法。根据各路相关性分数进行分档排序。适用场景：对相关性准确性要求高、召回分数可靠且注重结果的排序稳定性的场景。

RerankParameter

type RerankParameter = InvertedIndexRerankParameter| VectorRerankParameter

重排算法的参数配置。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

类型 说明
InvertedIndexRerankParameter 重排参数为InvertedIndexRerankParameter。
VectorRerankParameter 重排参数为VectorRerankParameter。

InvertedIndexRerankParameter

用于倒排索引的重排算法的参数。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
invertedIndexWeights Record<RecallName, number> 否 否

每路召回的重排权重，体现各路召回在重排过程中的重要性。key为各路召回RecallCondition的RecallName，value为对应那一路召回的权重。

权重值必须为非负数。如果未定义某一路召回的权重，则默认值为1。

VectorRerankParameter

用于向量数据的重排算法的参数。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
vectorWeights Record<RecallName, number> 否 否 每路召回的重排权重，体现各路召回在重排过程中的重要性。key为各路召回RecallCondition的RecallName，value为对应那一路召回的权重。权重值必须为非负数。如果未定义某一路召回的权重，则默认值为1。
thresholds Array<number> 否 是

向量召回的分档阈值，用户应当从[0, 1]范围内给3个值，高、中、低档最低分，赋值对应cosine()相似度得分，越高越相关；

如果是2个值，则分出高、中两档，剩下结果都是低档；

如果是1个值，则除了高档剩下结果都是低档。

当给出多于3个值，则使用从大到小排序后前3个数值，后面忽略。如果未定义，默认值为[0.6, 0.45, 0.4]。
numberInspector Record<RecallName, ColumnName> 否 是 向量召回数字匹配降档策略配置，如果查询中存在数字，但是对应目标字段中的数字和查询数字不匹配，则将该检索结果的相关性降低。key为对应向量召回条件中的RecallName，value为对应模式匹配字段名。默认值为空。

RdbRecords

检索结果。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
records Array<ItemInfo> 否 否 检索结果
missedGroundTruths Array<ItemInfo> 否 是 未检索到指定文档的信息

ItemInfo

检索结果中每条数据的特定内容。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
primaryKey string 否 否 检索结果的主键。
columns Record<string, relationalStore.ValueType> 否 否 召回列及其内容。
score number 否 否 检索重排后的最终得分，其反映了重排记录与查询词之间的相似度。score取值大于等于0。
recallScores Record<ChannelType, Record<string, RecallScore>> 否 否

每路召回的得分，其反映了每路召回对该结果的相关性评估。key为该路RecallCondition的scoreKey；

- 如果这里没有体现RetrievalCondition中的某一路RecallCondition的scoreKey，则代表该路召回认为该结果相关性过低不予召回。
features Record<string, number> 否 否

不同倒排策略的得分，用于评估检索结果在不同策略下的表现。目前支持的倒排策略及得分为：

- "exact_phase"：文档字段精确命中查询语句的得分。

- "out_of_order_phase"：文档字段命中近似乱序匹配策略的得分。

- "token_bm25"：文档字段bm25策略得分。

- "core_count"：文档单个匹配字段内核心词总数。
similarityLevel SimilarityLevel 否 否 根据语义向量距离以及文本匹配程度，对检索结果按照相关性分档，方便对结果进行进一步筛选和过滤。取值包括NONE（保留值）、LOW（语义相似）、MEDIUM（语义中等）、HIGH（语义差异大）。

RecallScore

召回过程的得分。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 类型 只读 可选 说明
score number 否 否 召回得分。
isReverseQuery boolean 否 否 表示得分是否来自反查过程。true表示来自反查过程，false表示来自原始召回过程。

SimilarityLevel

根据语义向量距离以及文本匹配程度，对检索结果按照相关性的高中低分档，方便对结果进行进一步筛选并且过滤。

模型约束： 此接口仅可在Stage模型下使用。

系统能力： SystemCapability.DataAugmentation.Retrieval

起始版本： 6.0.0(20)

名称 值 说明
NONE 0 保留值，暂无特定含义。
LOW 1 结果和Query的语义向量距离小，表示语义更相似。该等级表示检索结果与查询词具有高度语义相关性。
MEDIUM 2 结果和Query的语义向量距离中等，表示语义相似性中等。该等级表示检索结果与查询词具有中等语义相关性。
HIGH 3 结果和Query的语义向量距离大，表示语义差异较大，相关性低。该等级表示检索结果与查询词具有较低语义相关性。