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

前言

文搜图接口本身并不复杂——传入一个关键词,指定最多返回多少张图片,系统返回一个相似度 Map。但真正让搜索结果「好用」,关键并不在于调通接口,而在于理解 similarity 和 topKey 背后的语义,以及如何在 UI 层合理地组织和呈现这些结果。

一、这个接口到底返回了什么?

文搜图能力由 AI Core Kit 提供,核心接口是 intelligentSearch.imageSearch,位于 @kit.CoreAIKit 模块下,从 API version 12 开始支持。

调用后返回的是一个 SearchResult 对象,其中只有一个字段需要关注:

similarity: Map<string, number>

这个 Map 的 key 是图片资产 ID,value 是该图片与查询词的相似度分数。分数越高,语义越接近。

顺便提一下 SearchOptions:

字段类型说明
keywordstring文本查询词
topKeynumber最多返回图片数,范围 (1, 100)

这两个字段都是必填的。

二、similarity 的语义是什么

官方对 similarity 的定义是:查询关键词与图片的相似度,value 越大表示越相似。

这里需要理解的是,相似度是语义相似度,不是关键词命中率。系统在端侧通过 AI 模型对图片和文本分别做向量化,然后计算它们在语义空间中的接近程度。这意味着:

  • 搜索「猫」,一张没有「猫」文字但画面是猫咪的图片,可能得到较高的相似度;
  • 搜索「下午茶」,带有咖啡、点心场景的图片,也可能排在前面;
  • 不同设备、不同 AI 模型版本下,同一张图片针对同一查询词的相似度绝对值可能不同。

最后一点特别值得关注,官方文档明确指出不建议硬编码固定阈值来过滤结果。

三、topKey 控制的是什么

topKey 控制的是「系统最多给你返回几张图片」,而不是「你展示几张」。

系统会从图库中找出与查询词语义最接近的图片,按相似度由高到低排序,最多取 topKey 张返回。如果图库中图片数量不足 topKey,实际返回数量会更少。

这里有一个容易误解的地方:topKey 并不是「相似度排名第几名」的截断,它的作用域是「所有分析过的图片集合」。设备图库越丰富,topKey=20 返回的前 20 张质量也相对越高,因为系统有更大的候选集可以排序。

四、搭一个最小实践场景

目标:在图库中添加若干张语义相近但主题不同的图片(比如「夕阳」「海边」「黄昏」「森林」「城市夜景」),然后用不同的查询词搜索,把相似度展示在搜索结果列表里,观察排序变化。

前置配置

首先在 module.json5 中声明权限:

{
  "module": {
    "requestPermissions": [
      {
        "name": "ohos.permission.READ_IMAGEVIDEO",
        "reason": "$string:permission_reason",
        "usedScene": {
          "abilities": ["EntryAbility"],
          "when": "inuse"
        }
      }
    ]
  }
}

ohos.permission.READ_IMAGEVIDEO 是 user_grant 级别权限,仅在 module.json5 里声明是不够的,还需要在运行时动态申请。

五、核心代码实现

5.1 动态申请权限

这段代码解决的是「运行时获取图库读取权限」的问题,是调用文搜图前的必要步骤。

import { abilityAccessCtrl, common, Permissions } from '@kit.AbilityKit';

async function requestReadImagePermission(context: common.UIAbilityContext): Promise<boolean> {
  const atManager = abilityAccessCtrl.createAtManager();
  const permissions: Permissions[] = ['ohos.permission.READ_IMAGEVIDEO'];
  
  const result = await atManager.requestPermissionsFromUser(context, permissions);
  // result.authResults 中每项为 0 表示授权成功,-1 表示被拒绝
  return result.authResults[0] === 0;
}

需要关注的是返回值 authResults——它是一个数组,与传入的 permissions 数组一一对应。这里只申请了一个权限,所以只检查 [0]。

5.2 调用文搜图接口

这段代码解决的是「用关键词搜索图库并获取相似度 Map」的问题。

import { intelligentSearch } from '@kit.CoreAIKit';

async function searchImagesByText(keyword: string, topKey: number): Promise<Map<string, number>> {
  const options: intelligentSearch.SearchOptions = {
    keyword: keyword,
    topKey: topKey,
  };

  try {
    const result = await intelligentSearch.imageSearch(options);
    return result.similarity;
  } catch (err) {
    console.error(`imageSearch failed, code: ${err.code}, message: ${err.message}`);
    return new Map();
  }
}

返回的 Map<string, number> 中,key 是图片的资产 ID(字符串形式的文件 ID),value 是相似度分数。

5.3 用图片 ID 获取缩略图

文搜图只返回 ID,要展示图片需要配合 photoAccessHelper 根据 ID 查出 PhotoAsset,再取缩略图。

这段代码解决的是「把相似度 Map 转换为可展示的图片数据列表」的问题。

import { photoAccessHelper } from '@ohos.file.photoAccessHelper';
import { dataSharePredicates } from '@ohos.data.dataSharePredicates';
import { image } from '@kit.ImageKit';

interface SearchResultItem {
  id: string;
  similarity: number;
  thumbnail: image.PixelMap | undefined;
}

async function buildResultList(
  context: common.UIAbilityContext,
  similarityMap: Map<string, number>
): Promise<SearchResultItem[]> {
  const helper = photoAccessHelper.getPhotoAccessHelper(context);
  const items: SearchResultItem[] = [];

  // 按相似度从高到低排序
  const sortedEntries = [...similarityMap.entries()].sort((a, b) => b[1] - a[1]);

  for (const [id, similarity] of sortedEntries) {
    const predicates = new dataSharePredicates.DataSharePredicates();
    predicates.equalTo(photoAccessHelper.PhotoKeys.ID, id);

    try {
      const fetchResult = await helper.getAssets({ predicates });
      if (fetchResult.getCount() > 0) {
        const asset = await fetchResult.getFirstObject();
        const thumbnail = await asset.getThumbnail({ width: 200, height: 200 });
        items.push({ id, similarity, thumbnail });
      }
      fetchResult.close();
    } catch (err) {
      console.error(`getAssets failed for id ${id}: ${err.message}`);
    }
  }

  return items;
}

真正需要关注的有两处:

  1. similarityMap 本身不保证顺序,需要手动排序后再渲染,否则列表排列是随机的;
  2. fetchResult 用完后要调用 fetchResult.close() 释放资源,否则存在内存泄漏风险。

5.4 UI 展示搜索结果与相似度

这段代码解决的是「把搜索结果渲染为图片列表,并在每张图片上展示相似度分数」的问题。

@Component
struct SearchResultList {
  @State resultItems: SearchResultItem[] = [];
  @State keyword: string = '';
  private context: common.UIAbilityContext = getContext(this) as common.UIAbilityContext;

  async doSearch() {
    const hasPermission = await requestReadImagePermission(this.context);
    if (!hasPermission) {
      return;
    }
    const similarityMap = await searchImagesByText(this.keyword, 20);
    this.resultItems = await buildResultList(this.context, similarityMap);
  }

  build() {
    Column({ space: 12 }) {
      Row({ space: 8 }) {
        TextInput({ placeholder: '输入描述词,例如:夕阳、海边' })
          .layoutWeight(1)
          .onChange((val) => { this.keyword = val; })
        Button('搜索')
          .onClick(() => { this.doSearch(); })
      }
      .padding(12)

      Grid() {
        ForEach(this.resultItems, (item: SearchResultItem) => {
          GridItem() {
            Stack({ alignContent: Alignment.BottomEnd }) {
              if (item.thumbnail) {
                Image(item.thumbnail)
                  .width('100%')
                  .aspectRatio(1)
                  .objectFit(ImageFit.Cover)
                  .borderRadius(8)
              }
              // 在图片右下角展示相似度
              Text((item.similarity * 100).toFixed(1) + '%')
                .fontSize(11)
                .fontColor(Color.White)
                .backgroundColor('#80000000')
                .padding({ left: 6, right: 6, top: 2, bottom: 2 })
                .borderRadius(4)
                .margin(4)
            }
          }
        })
      }
      .columnsTemplate('1fr 1fr 1fr')
      .columnsGap(8)
      .rowsGap(8)
      .padding({ left: 12, right: 12 })
    }
    .width('100%')
    .height('100%')
  }
}

相似度展示为百分比格式(乘以 100 后保留一位小数),放在图片角落,不干扰主要视觉,又让开发者在调试阶段能直接看到模型的评分情况。

六、几个关键点拆开看

1. 为什么用不同的描述词搜索,排序会明显不同

模型对语义的理解是多维度的,「夕阳」和「黄昏」在语义上接近但不完全相同。「夕阳」更侧重太阳本身的视觉,「黄昏」更偏向时间段和氛围。同一组图片用这两个词查询,排在第一的图片很可能不一样。这不是接口的问题,而是语义搜索的基本特性。

2. topKey 设太小和设太大都有代价

设太小:模型返回的候选集被截断,可能丢掉一些实际语义接近的图片。
设太大:buildResultList 阶段需要逐个查询 photoAccessHelper,图片越多,查询耗时越长。建议根据 UI 展示数量来决定,不要无脑设为 100。

3. similarity 的绝对值不应作为业务判断门槛

举个场景:如果开发者写了 if (similarity > 0.7) 来过滤「不相关结果」,在某些设备或某些模型版本下,这个阈值可能把大量实际相关的图片过滤掉;在另一些设备上又过于宽松。官方文档明确指出相似度的绝对值因模型版本不同可能存在偏差,所以正确的做法是使用相对排序,而不是绝对阈值。

4. 图片 ID 与 photoAccessHelper 的关系

文搜图返回的 key 是图片资产 ID(即 PhotoAsset.id 的字符串形式),可以用 PhotoKeys.ID 作为查询条件直接传给 getAssets。这个 ID 在设备图库中是唯一的,不会与视频 ID 混淆。

七、容易踩坑的地方

权限只声明不申请:ohos.permission.READ_IMAGEVIDEO 是 user_grant 权限,仅在 module.json5 中添加不会自动授权。必须在运行时调用 requestPermissionsFromUser,否则 imageSearch 会因为无法访问图库而失败或返回空结果。

忘记排序直接渲染 Map:Map 在遍历时按插入顺序,而 imageSearch 返回的 Map 插入顺序不等于相似度顺序。如果直接 forEach 渲染,列表呈现的顺序就不是「最相关在前」。

fetchResult 未 close:在循环里查询 getAssets 时,每次调用返回的 FetchResult 都需要手动 close(),否则存在资源泄漏。

图库为空或图片极少:在模拟器或刚恢复出厂设置的设备上,图库图片极少,topKey=20 实际可能只返回 2、3 张,不代表接口有问题。

八、实际项目中怎么排查

如果调用后结果异常,建议按以下顺序检查:

  1. 确认 API Level:目标设备和工程配置是否都在 API 12 及以上;
  2. 检查权限状态:打印 authResults[0],确认权限是否已被用户授予;
  3. 检查 catch 中的错误码:err.code 可以定位是权限问题、图库访问失败还是模型推理失败;
  4. 检查图库内容:在设备图库里实际确认有足够数量的图片,且图片类型为 IMAGE 而非 VIDEO;
  5. 检查 topKey 范围:确保传入值在 (1, 100) 之间,超出范围可能导致接口返回错误;
  6. 排查 Map 处理逻辑:在渲染前打印 Map 内容,确认 ID 和相似度分数都正常;
  7. 检查 fetchResult.close():如果出现内存告警,重点排查资源释放逻辑。

开发经验总结

  • similarity 是语义相似度,不是关键词命中率,理解这一点对解释搜索结果差异非常重要;
  • topKey 控制候选集大小,直接影响结果质量和后续查询性能,不应无脑设最大值;
  • 相似度的绝对值不应硬编码为业务过滤阈值,用相对排序更稳定;
  • similarity Map 返回后需要手动按 value 降序排序,再交给列表渲染;
  • ohos.permission.READ_IMAGEVIDEO 是 user_grant 权限,必须动态申请,这一步是整个链路能跑通的前提。

如果你正在用文搜图做搜索功能,可以重点观察一下:在同一图库里,用近义词(比如「海浪」和「海边」)分别搜索,排在前三的图片是否完全一致?语义模型在这类边界词上的表现,往往是决定搜索体验细腻程度的地方。

📝 写在最后

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

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

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

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

Logo

讨论HarmonyOS开发技术,专注于API与组件、DevEco Studio、测试、元服务和应用上架分发等。

更多推荐