知识卡片搜索只靠标题包含关系，很难找到表达不同但含义接近的内容。向量数据库可以把文本向量与业务字段保存在同一数据层，再通过距离排序返回候选项；工程上还要处理模型版本、维度不一致和设备能力缺失。

方案面向HarmonyOS 6.1.1 Release SDK（API 24），系统Kit调用进入适配层，命令约束、状态归并和恢复策略进入可测试的业务层。范围包含状态与资源生命周期设计、失败恢复和验收合同，不包含业务内容生产、服务端协议改造以及特定厂商网页或媒体源的兼容承诺。

语义检索先固定向量合同

方案为每条知识卡片保存id、title、category、embedding、embeddingVersion和updatedAt。向量生成器输出固定维度Float32Array，写入前检查长度与有限数值；查询先按category和可见状态过滤，再计算距离并取TopK。

状态数量不是越多越好。每个状态必须回答三个问题：当前允许哪些命令、收到迟到事件怎样处理、页面退出后是否还可以更新UI。下面的状态对象携带operationId，新的操作开始后，旧操作回调会被拒绝。

export enum VectorSearchState {
  CHECKING = 'checking',
  INDEXING = 'indexing',
  READY = 'ready',
  SEARCHING = 'searching',
  DEGRADED = 'degraded',
  REBUILDING = 'rebuilding'
}

export interface VectorSearchSnapshot {
  state: VectorSearchState;
  progress: number;
  message: string;
  operationId: number;
  updatedAt: number;
}

export type VectorSearchEvent =
  | { type: 'START'; operationId: number }
  | { type: 'PROGRESS'; operationId: number; progress: number }
  | { type: 'SUCCESS'; operationId: number }
  | { type: 'FAIL'; operationId: number; message: string };

export function acceptEvent(
  snapshot: VectorSearchSnapshot,
  event: VectorSearchEvent
): boolean {
  return event.type === 'START' || event.operationId === snapshot.operationId;
}

floatvector与业务字段怎样同表管理

启动时先调用isVectorSupported，不支持就切到RDB关键词索引，页面仍提供搜索。模型升级新建embeddingVersion并后台分批重算，检索阶段只比较同版本向量。阈值和TopK分开配置：TopK限制数量，阈值负责拒绝低相关结果。

这套分层把系统事实和产品行为分开：Kit适配器负责获得事实，领域对象决定是否接受事件，页面只渲染快照。更换API版本或加入真机能力时，只需要替换适配器；状态归并和异常策略仍可在模拟器中重复验证。

TopK查询还需要哪些过滤条件

下面是主题专属的接入或核心算法代码。示例刻意保留资源创建、前置条件和清理逻辑，因为高频故障往往出现在成功调用之外。

import { relationalStore } from '@kit.ArkData';

export interface VectorDocument {
  id: number;
  title: string;
  category: string;
  embedding: number[];
  embeddingVersion: number;
}

export class VectorContract {
  constructor(private dimension: number, private modelVersion: number) {}

  validate(document: VectorDocument): void {
    if (document.embeddingVersion !== this.modelVersion) {
      throw new Error('MODEL_VERSION_MISMATCH');
    }
    if (document.embedding.length !== this.dimension) {
      throw new Error('VECTOR_DIMENSION_MISMATCH');
    }
    if (document.embedding.some(value => !Number.isFinite(value))) {
      throw new Error('VECTOR_VALUE_INVALID');
    }
  }

  async capability(): Promise<'VECTOR' | 'KEYWORD'> {
    return relationalStore.isVectorSupported() ? 'VECTOR' : 'KEYWORD';
  }

  normalize(values: number[]): number[] {
    const norm = Math.sqrt(values.reduce((sum, value) => sum + value * value, 0));
    if (norm === 0) throw new Error('ZERO_VECTOR');
    return values.map(value => value / norm);
  }
}

代码迁入业务工程时，应把错误码转换为稳定的领域错误，不让页面直接判断系统错误字符串。对于异步回调，还要在写入状态前比较operationId或资源版本；仅检查组件是否存在，无法阻止旧任务污染新页面。

模型升级为什么不能原地混用

异常注入按钮用于稳定复现应用侧恢复路径。真实错误发生时，诊断记录同时保存错误码、权限结果、设备能力和用户可见状态；敏感原始数据不进入日志，截图只呈现与问题直接相关的结果。

能力检测失败时退回关键词索引

页面层不直接调用Kit，而是通过动作按钮驱动同一份状态模型。这样既能在系统能力可用时接真实适配器，也能在模拟器缺少硬件时验证错误页面、幂等逻辑和资源清理。

@Component
struct VectorSearchPanel {
  @State stateText: string = 'CHECKING';
  @State progress: number = 0;
  @State logs: string[] = [];

  private append(message: string): void {
    const time = new Date().toLocaleTimeString();
    this.logs = [`${time}  ${message}`, ...this.logs].slice(0, 8);
  }

  private startDemo(): void {
    this.stateText = 'INDEXING';
    this.progress = 20;
    this.append('开始：ArkData向量数据库相似检索');
  }

  private injectFailure(): void {
    this.stateText = 'REBUILDING';
    this.append('已注入可恢复故障');
  }

  build() {
    Column({ space: 12 }) {
      Text('ArkData向量数据库相似检索').fontSize(24).fontWeight(FontWeight.Bold)
      Text(this.stateText).fontSize(18).fontColor('#2563EB')
      Progress({ value: this.progress, total: 100 }).width('100%')
      Row({ space: 12 }) {
        Button('开始实验').onClick(() => this.startDemo())
        Button('注入故障').onClick(() => this.injectFailure())
      }
      ForEach(this.logs, (item: string) => Text(item).fontSize(13))
    }.padding(20).width('100%')
  }
}

构造同义表达、同词异义、跨分类噪声、零向量和旧模型五类样本。验收同时记录TopK、距离、阈值、过滤前后数量和降级路径；同义样本应进入前列，跨分类项被过滤，低相关查询返回明确空状态。

向量检索的质量不能只看某一次结果是否“像”。测试集应保存查询、期望候选和不可接受候选，模型或阈值变化后重复计算召回率。向量属于派生数据，原文和业务主键才是事实来源；索引损坏时可以重建，不能反向用向量恢复正文。批量重算要限制并发和温度，页面查询优先于后台索引。隐私文本是否允许向量化需要单独分级，敏感字段默认不进入embedding输入。即使全部本地处理，也要提供清理索引和按业务记录删除派生向量的路径。

验收记录至少包括SDK版本、模拟器系统版本、操作顺序、预期状态、实际状态和截图编号。快速点击、返回再进入、故障后重试和页面销毁是必测项；涉及资源的主题还要显示活动对象计数，涉及异步任务的主题要验证迟到结果不会改变当前页面。

构造可解释的检索验收集

这套方案的技术闭环由“输入约束—状态模型—Kit适配—异常恢复—可观察验收”组成。业务状态不持有系统对象，适配器不直接操作页面，异常路径有明确的恢复动作，后续SDK升级时可以分别回归每一层。

官方资料：VectorStore相关开发文档