👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 HarmonyOS 的过程都记录在这里。
  
  🛠️ 主要方向:ArkTS 语言基础、HarmonyOS 原生应用(Stage 模型、UIAbility/ServiceAbility)、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战,以及 Android → 鸿蒙的迁移踩坑与复盘。
  🧭 内容节奏:从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘,让每篇都有可落地的代码与方法论。
  💡 我相信:写作是把知识内化的过程,分享是让生态更繁荣的方式。
  
   如果你也想拥抱鸿蒙、热爱成长,欢迎关注我,一起交流进步!🚀

前言

本文聚焦 HarmonyOS 7(API 26)新增的文本搜索图片能力,围绕 CoreVisionKit 中的 textSearchImage 接口展开。

文章将重点放在一个实际开发问题上:用户输入的文字描述并不总是规范的关键词,如何利用系统提供的跨模态图片检索能力,在查询输入、搜索调用、相似度理解和结果展示几个环节,设计一套更容易维护、便于验证的搜图流程。

这里需要先明确一个版本边界:华为官方 API Reference 将 textSearchImage 标注为 API 26.0.0 起支持,并明确要求在 Stage 模型下使用。因此,不能将这项能力直接描述成所有 HarmonyOS 旧版本都支持的通用图片搜索接口。

一、先把场景缩小:应用内相册的自然语言搜图

这里选择一个比较典型、也容易复现的场景:应用内相册搜索。

假设应用已经保存了一批图片,用户希望通过文字找到其中某张图片。

传统的关键词搜索通常依赖图片名称、标签或者人工维护的分类。例如:

  • 用户输入“海边”,只能匹配事先建立了海边标签的图片。

  • 用户输入“夕阳下的海滩”,如果图片没有对应标签,就可能无法找到。

  • 用户记得图片里有一辆红色汽车,却不知道图片叫什么名字,也没有办法通过文件名准确定位。

HarmonyOS 7 提供的文本搜索图片能力,解决的正是这类问题。

华为官方将其描述为基于自然语言理解和图像跨模态检索的能力。用户可以直接输入描述性文本,从应用沙箱中的图片库检索匹配图片,不需要事先为每张图片手动建立文字标签。

这里有一个重要区别:

普通关键词搜索关注的是文字是否匹配,而文搜图关注的是文字描述与图像内容之间的语义匹配。

例如,图片文件名可能只是:

IMG_20260801_001.jpg

用户却可以输入:

海边的落日

系统根据文本与图像之间的匹配关系返回结果。

因此,文搜图的开发重点不只是把搜索框接入一个 API,还需要考虑图片如何进入检索库、用户输入如何处理、返回结果如何排序,以及图片数据发生变化后如何维护索引。

二、先核对官方能力和版本边界

正式写代码之前,先确认使用的是哪一套能力。

1. 对应 Kit 和 API

本次实践使用

HarmonyOS 7.0 对应的开发套件 API 版本为 26.0.0。

需要特别说明,API 26.0.0 开始采用语义化版本号格式。因此,工程配置中涉及该版本的 SDK 字段应按照字符串版本号处理,而不能直接照搬旧版本的数字配置方式。

2. 官方支持范围

根据 Core Vision Kit 官方能力说明,目前需要关注以下限制:

这里容易忽略的是模拟器限制。

如果只在 DevEco Studio 中通过模拟器检查页面布局,并不能证明文搜图服务能够正常工作。真正验证这项能力,需要准备符合要求的目标设备。

3. 工程配置

开发环境建议使用 DevEco Studio 26.0.0 配套的 HarmonyOS SDK。

工程级 build-profile.json5 中有几个版本字段需要了解:

  • compileSdkVersion:编译应用所使用的 SDK 版本。

  • targetSdkVersion:应用目标 SDK 版本。

  • compatibleSdkVersion:应用要求兼容的最低 SDK 版本。

对于 HarmonyOS 运行环境,compileSdkVersion 可以不显式配置,默认使用 DevEco Studio 内置的 SDK。如果显式配置,则必须与当前 DevEco Studio 配套的 SDK 版本一致。

API 26.0.0 及以上版本的相关配置采用字符串形式,例如:

"targetSdkVersion": "26.0.0"

需要注意,不能为了使用文搜图接口,就不考虑实际兼容需求而直接把整个应用的最低兼容版本提高到 26.0.0。

如果应用仍然需要运行在旧版本设备上,应保留合理的最低兼容版本,并为不支持文搜图的设备设计其他搜索方式。

4. 权限配置

这组 textSearchImage 接口的官方 API 说明列出了系统能力和 Stage 模型要求,没有列出需要额外声明的专属运行时权限。

但图片路径必须满足应用沙箱访问要求。

如果图片来自图库选择、网络下载等其他业务流程,还需要按照对应的数据访问方式完成授权和文件处理,不能把这些流程与文搜图接口本身混为一谈。

三、从用户输入到结果排序,整个流程应该怎么设计?

理解接口之前,可以先把业务流程拆开。

一个完整的应用内文搜图功能,大致包含以下几个阶段:

用户输入文字描述
        |
        v
输入内容校验与预处理
        |
        v
确认检索服务已经初始化
        |
        v
调用 textSearchImage.search()
        |
        v
获得图片匹配结果
        |
        v
读取 similarity 相似度
        |
        v
按照相似度进行降序排序
        |
        v
结合业务规则筛选
        |
        v
展示最终图片列表

其中有两个阶段尤其值得重视。

一个是用户输入。

另一个是搜索结果排序。

如果输入内容不符合接口要求,即使服务初始化成功,也可能无法获得预期结果。

如果拿到结果后直接按照数组原始顺序展示,也可能没有充分利用接口返回的相似度信息。

下面分别拆开分析。

1. 用户输入:保留描述性语义

文搜图的一个特点是支持描述性文本。

因此,不建议在业务层强行把所有输入转换成单一关键词。

实际开发时,可以进行适度预处理:

  • 去除输入首尾空格。

  • 检查输入是否为空。

  • 检查输入长度。

  • 对不符合接口参数约束的内容进行提示。

  • 不随意删除用户描述中的有效信息。

例如:

const query = this.searchText.trim();

这一步看起来很简单,但可以避免空白输入直接进入检索流程。

根据官方 API Reference,search() 的 query 参数有明确约束:

  • 长度范围为1~100。

  • 不支持纯数字。

  • 不支持纯字母。

  • 支持中文,以及数字、字母或符号组合。

这里有一个需要特别说明的文档细节:官方 API Reference 的参数说明与同页示例存在不一致,参数说明写明不支持纯字母,但示例中使用了 landscape。

为了避免将不确定行为当成稳定能力,本文代码按照参数约束进行保守校验。纯英文单词的实际支持情况,建议在目标设备上使用对应 SDK 单独验证。

2. 图片入库:不要忽略图片特征索引

文搜图不是直接遍历图片文件名称。

官方提供的 insertImage() 方法用于将图片特征插入数据库。

接口形式:

textSearchImage.insertImage(imagePath, scope)

其中:

imagePath 长度范围为1~128,要求提供有效的图片沙箱路径。

scope 长度范围为1~32,支持字母或数字。

例如:

const imagePath = '/实际应用沙箱目录中的图片路径';
const scope = 'album01';

const result = await textSearchImage.insertImage(imagePath, scope);

这里需要明确:示例中的路径必须替换成真实存在的应用沙箱路径,不能直接传入网络图片 URL,也不能把任意外部文件路径当作已经满足要求的沙箱路径。

如果应用有图片导入流程,可以在图片成功保存到应用沙箱后,再调用 insertImage() 建立对应的检索记录。

这也意味着,图片文件管理和图片特征索引需要保持一致。

例如:

  • 新增图片后,需要建立索引。

  • 删除图片后,需要删除对应索引记录。

  • 图片文件发生替换时,需要同步维护原有索引。

否则,检索库中的记录可能与实际图片文件不一致。

四、核心代码:实现初始化、图片入库和搜索排序

这部分使用 ArkTS 和 ArkUI 搭建一个最小实践场景。

目标不是实现完整相册,而是把文搜图最关键的几个接口串起来。

1. 导入依赖

官方文档提供的主要导入方式如下:

import { textSearchImage } from '@kit.CoreVisionKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

其中:

  • textSearchImage:提供图片特征入库、文本搜索、删除和释放等能力。

  • BusinessError:用于处理接口调用异常。

  • hilog:用于输出开发调试日志。

2. 实现最小页面

下面的代码重点展示四件事:

  1. 页面出现时初始化服务。

  2. 提供图片特征入库方法。

  3. 接收用户输入并执行文本搜索。

  4. 根据相似度对结果进行降序排列。

import { textSearchImage } from '@kit.CoreVisionKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct TextSearchPage {
  @State searchText: string = '';
  @State resultMessage: string = '';
  @State serviceReady: boolean = false;
  @State busy: boolean = false;

  private scope: string = 'album01';

  // 页面出现时初始化服务
  async aboutToAppear(): Promise<void> {
    try {
      this.serviceReady = await textSearchImage.init();

      this.resultMessage = this.serviceReady
        ? '文搜图服务初始化成功'
        : '文搜图服务初始化失败';

    } catch (error) {
      const err = error as BusinessError;
      this.resultMessage = `初始化异常:${err.code}`;
    }
  }

  // 页面退出时释放服务
  async aboutToDisappear(): Promise<void> {
    if (!this.serviceReady) {
      return;
    }

    try {
      await textSearchImage.release();
    } catch (error) {
      const err = error as BusinessError;
      hilog.error(0x0000, 'TextSearch', `Release failed: ${err.code}`);
    } finally {
      this.serviceReady = false;
    }
  }

  // 将已经保存到应用沙箱的图片加入索引
  private async indexImage(imagePath: string): Promise<void> {
    if (!this.serviceReady || this.busy) {
      return;
    }

    this.busy = true;

    try {
      const inserted = await textSearchImage.insertImage(
        imagePath,
        this.scope
      );

      this.resultMessage = inserted
        ? '图片特征入库成功'
        : '图片特征入库失败';

    } catch (error) {
      const err = error as BusinessError;

      this.resultMessage = `图片入库异常:${err.code}`;

      hilog.error(
        0x0000,
        'TextSearch',
        `Insert failed: ${err.code}, ${err.message}`
      );
    } finally {
      this.busy = false;
    }
  }

  // 执行文搜图
  private async searchImages(): Promise<void> {
    const query = this.searchText.trim();

    if (!this.serviceReady) {
      this.resultMessage = '检索服务尚未初始化';
      return;
    }

    if (query.length < 1 || query.length > 100) {
      this.resultMessage = '请输入1~100长度范围内的描述';
      return;
    }

    // 按 API 参数说明进行保守校验
    if (/^[0-9]+$/.test(query) ||
        /^[A-Za-z]+$/.test(query)) {
      this.resultMessage = '请使用描述性文本进行搜索';
      return;
    }

    // 避免同一特性并发调用
    if (this.busy) {
      return;
    }

    this.busy = true;

    try {
      const results = await textSearchImage.search(
        query,
        this.scope,
        100
      );

      // 根据 similarity 从高到低排列
      const rankedResults = results.slice().sort(
        (left, right) => right.similarity - left.similarity
      );

      if (rankedResults.length === 0) {
        this.resultMessage = '没有找到匹配图片';
        return;
      }

      this.resultMessage = rankedResults.map(
        (item, index) => {
          return `${index + 1}. ${item.imagePath} | 相似度:${item.similarity.toFixed(3)}`;
        }
      ).join('\n');

    } catch (error) {
      const err = error as BusinessError;

      this.resultMessage = `搜索异常:${err.code}`;

      hilog.error(
        0x0000,
        'TextSearch',
        `Search failed: ${err.code}, ${err.message}`
      );

    } finally {
      this.busy = false;
    }
  }

  build() {
    Column() {
      Text('应用内图片搜索')
        .fontSize(22)
        .margin(12)

      TextInput({
        placeholder: '例如:海边的落日、雨天的城市街道'
      })
        .width('90%')
        .onChange((value: string) => {
          this.searchText = value;
        })

      Button(this.busy ? '处理中...' : '搜索图片')
        .onClick(() => {
          void this.searchImages();
        })

      Text(this.resultMessage)
        .width('90%')
        .margin(12)
    }
    .width('100%')
    .padding(16)
  }
}

这段代码按照华为官方接口定义组织,属于最小实践示例,未声称已经在 DevEco Studio 中编译或经过真机验证。

其中,indexImage() 是供图片导入流程调用的方法。调用之前,需要确保传入的 imagePath 已经指向真实存在的应用沙箱图片文件。

3. 真正需要关注的代码

第一,初始化和释放必须有明确的生命周期管理。

官方开发指南建议在 aboutToAppear() 中调用:

await textSearchImage.init();

在 aboutToDisappear() 中调用:

await textSearchImage.release();

这两个方法分别负责初始化和释放文本搜索图片分析器服务。

不要在每次点击搜索按钮时都重复初始化服务。

第二,图片入库和搜索必须使用相同的 scope。

例如:

await textSearchImage.insertImage(
  imagePath,
  'album01'
);

搜索时也应使用:

await textSearchImage.search(
  query,
  'album01',
  100
);

如果两处使用的作用域不同,就不能按照预期搜索到对应作用域下插入的图片。

第三,结果排序是应用层可以明确控制的部分。

代码中最重要的排序逻辑是:

const rankedResults = results.slice().sort(
  (left, right) => right.similarity - left.similarity
);

这里没有创造新的系统接口,而是利用 API 返回的相似度属性进行业务层排序。

五、从用户输入到结果排序,怎样进一步提高准确率?

接口接通只是第一步。

实际产品中,如果希望用户搜索时得到更符合预期的图片,还需要从以下几个方面进行设计。

1. 不要把自然语言搜索重新做成关键词搜索

文搜图最有价值的地方,是允许用户描述图片内容。

例如:

海边的落日

比单独输入:

海

包含了更多场景信息。

在应用设计中,可以适当提供搜索提示,让用户知道可以描述:

  • 图片中的主体。

  • 图片发生的场景。

  • 图片的颜色和外观。

  • 图片中的动作或状态。

例如:

一只趴在沙发上的橘猫

夜晚街道上的红色汽车

桌面上的白色耳机

这些都是自然语言描述的输入方式。

这里不需要人为规定用户必须按照固定格式输入。

对于文搜图来说,过度限制用户表达方式,反而会削弱自然语言搜索的体验。

2. 合理使用 topKey

search() 方法提供第三个参数:

topKey

它用于设置满足匹配条件时返回图片数量的上限。

官方规定:

const results = await textSearchImage.search(
  query,
  'album01',
  100
);

这里设置为100,目的是在接口允许的范围内保留较多候选结果。

为什么不直接设置成5?

因为如果业务层还需要进行进一步筛选,过早缩小候选集合,可能导致原本值得展示的图片没有进入后续处理环节。

但也不是返回数量越多,搜索准确率就一定越高。

比较合理的处理方式是:

  • 根据业务展示需求设置候选数量。

  • 获取接口返回的相似度。

  • 对候选结果进行排序。

  • 再结合实际业务需求进行筛选。

需要明确,topKey 控制的是返回数量上限,并不是搜索准确率参数。

3. 正确理解 similarity

这是整个文搜图实践中最值得关注的一个属性。

官方返回的 ImageObject 包含三个字段:

其中:

imageObject.similarity

取值范围为:

−1≤similarity≤1-1 \leq similarity \leq 1−1≤similarity≤1

数值越大,表示图片与相关文本的相似度越高。

这里需要避免一个常见误解:

相似度不是准确率百分比。

例如:

similarity = 0.85

不能直接理解为:

图片有85%的概率是正确结果

官方文档定义的是相似度,并没有将它定义为分类置信度或搜索准确率百分比。

因此,业务层可以按照相似度进行降序排列,但不应该直接把某个固定分数当作适用于所有图片库的准确率标准。

4. 不要忽略图片索引质量

用户输入再准确,如果图片没有正确进入检索库,最终也无法得到预期结果。

这里建议建立一套简单的图片索引管理机制:

尤其是删除图片时,不能只删除文件,而忽略检索数据库中的图片记录。

删除操作可以使用:

await textSearchImage.deleteImage(
  imagePath,
  'album01'
);

这样可以删除对应作用域下的图片记录。

如果只删除文件,没有同步处理索引,后续搜索就可能返回已经不存在的图片路径。

5. 通过固定测试集验证排序效果

如果希望真正知道搜索准确率有没有改善,不能只用一两条查询语句判断。

建议在开发阶段建立一个固定的测试集合。

例如,准备一组应用沙箱中的图片,并为测试查询人工标注相关图片。

可以使用两个比较直观的指标。

Precision@K(前K项准确率)

观察前K个结果中,有多少图片真正符合用户搜索意图。

Precision@K=前K项相关结果数量KPrecision@K = \frac{前K项相关结果数量}{K}Precision@K=K前K项相关结果数量

Recall@K(前K项召回率)

观察所有已标注的相关图片中,有多少被包含在前K个结果中。

Recall@K=前K项相关结果数量全部相关结果数量Recall@K = \frac{前K项相关结果数量}{全部相关结果数量}Recall@K=全部相关结果数量前K项相关结果数量

例如,比较同一图片库下不同描述方式的搜索结果,可以观察输入表达是否影响候选图片的匹配情况。

这套测试方式不会改变系统算法,但能够帮助开发者判断:

  • 哪些描述方式更容易得到相关结果。

  • 是否存在相似度较高但实际不相关的图片。

  • 前几项结果是否足够符合用户预期。

  • 是否需要调整业务层展示规则。

不要在没有实际测试的情况下,直接宣称某种输入方式可以提高多少百分比的准确率。

六、开发过程中容易出现的几个问题

问题一:只关注 search,没有提前插入图片

search() 的搜索对象是已经插入图片特征的图片库。

如果只完成搜索接口,却没有调用 insertImage() 建立图片索引,搜索流程就缺少必要的数据基础。

排查时应先确认图片入库是否成功。

问题二:图片路径不符合要求

官方错误码中:

1013100001 表示图像不可用。

可能原因包括:

  • 图片路径为空。

  • 图片路径不是本应用的沙箱地址。

  • 图片尺寸不符合要求。

建议重点检查:

imagePath

是否为真实有效的沙箱路径,以及图片宽高是否满足官方要求。

不要直接把网络 URL 传入 insertImage()。

问题三:同一特性被并发调用

Core Vision Kit 有一个比较重要的调用限制:

支持多个用户同时接入,但不支持同一用户并发调用同一个特性。

例如,同一个进程在同一时间多次调用同一个特性,可能返回系统繁忙错误。

因此,实际项目中不建议使用下面这种思路同时发起大量同类请求:

// 不建议并发执行同一特性的多个请求

更合理的方式是通过统一的任务管理机制,对图片入库、搜索和删除等操作进行串行调度。

示例代码中的 busy 状态只是单页面级别的简单保护。如果多个页面或服务共享文搜图能力,还应进一步统一管理调用队列,并确保正在执行的任务结束后再释放服务。

问题四:模型能力更新后没有处理数据库

官方文档明确给出了错误码:

1013100003

表示模型能力已经更新。

对应的处理方式是调用:

await textSearchImage.clearData();

该方法会清除数据库中的全部数据。

这里需要特别注意:清空数据库后,原有图片特征记录也会被清除。

因此,不能简单地调用一次 clearData() 就认为索引维护完成,还需要按照应用实际保存的图片清单重新建立索引。

问题五:把相似度当成固定阈值

不同的查询内容和图片集合,可能产生不同的相似度分布。

官方 API 并没有规定一个通用的业务过滤阈值。

因此,不建议直接写死:

if (similarity > 0.8) {
  // 一定是正确结果
}

更合理的做法是先通过固定测试集观察结果,再决定是否需要业务层阈值筛选。

七、实际项目中的排查顺序

当文搜图没有返回预期结果时,可以按照下面的顺序检查。

这里需要区分一个问题:搜索结果为空,并不一定意味着接口调用失败。

如果接口正常返回空数组,应先检查图片索引、scope 和查询描述,不要直接把它当作系统服务异常处理。

八、Core Vision Kit 与 C++ 智慧化数据检索不要混用

这里补充一个容易被忽略的技术边界。

华为官方还提供了另一份《智慧化数据检索-C++》开发指南。

这套方案采用召回与重排两个阶段:

  • 召回阶段:从候选数据中筛选可能匹配的结果,ArkData 提供向量召回能力。

  • 重排阶段:对召回结果进行二次筛选和排序。

官方资料还介绍了 RRF 和分数融合排序等方式。

这与本文使用的 ArkTS textSearchImage 并不是同一套接口。

两者需要区分

还有一个细节:Core Vision Kit 的 similarity 取值范围是(-1,1),而 C++ 智慧化数据检索指南中向量召回的分档阈值采用(0,1)范围。

两者的分数定义和使用方式不能直接混用。

如果当前需求只是应用内图片搜索,优先从 Core Vision Kit 入手即可。

如果后续需要更复杂的多策略召回、条件过滤和融合重排,再单独研究 C++ 智慧化数据检索方案。

开发经验总结

从这次文搜图能力的官方接口分析和最小实践来看,有几个值得记住的地方:

  1. 版本要确认准确。 textSearchImage 从 API 26.0.0 开始支持,对应 HarmonyOS 7.0,不能直接当作旧版本通用能力。

  2. 图片索引是搜索的基础。 通过 insertImage() 将图片特征加入数据库,搜索时使用对应的 scope。

  3. 用户输入应尽量保留语义。 对输入进行必要校验即可,不要过度转换成传统关键词搜索。

  4. 相似度排序需要明确处理。 ImageObject.similarity 范围为(-1,1),数值越大越相似,应用可以据此进行降序排序,但不能把相似度直接解释为准确率百分比。

  5. 索引维护和生命周期同样重要。 初始化、释放、图片删除、模型能力更新以及并发调用,都需要纳入统一管理。

文搜图真正值得关注的地方,不仅是让用户可以通过文字找到图片,而是让应用从依赖人工标签的检索方式,逐步转向理解图片内容与用户描述之间的语义关系。

对于开发者来说,接入 textSearchImage.search() 只是开始。图片索引是否完整、用户描述是否合理、候选结果如何排序,以及结果是否符合真实搜索意图,才是决定最终使用体验的关键。

在实际开发中,还可以进一步思考一个问题:

当两张图片的文本相似度非常接近时,应用应该只依据 similarity 排序,还是结合图片时间、业务分类等信息进行二次排序?

这也是文搜图从系统能力接入走向完整产品功能时,值得继续研究的方向。

📝 写在最后

如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!

我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!

感谢你的阅读,我们下篇文章再见~👋

✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐