---

1 -> 背景概述

HarmonyOS 6.0 在其持续演进中，将 AI 能力从单一的“工具调用”模式推升到了“操作系统级智能体框架”的高度。在这一宏观技术变革下，Data Augmentation Kit（数据增强服务）得到了重要扩展——新增了智慧化数据检索 C 接口，正式将知识库、知识检索和知识问答（RAG）等数据底座增强能力纳入系统级服务范畴。

从 HarmonyOS 的发展路线来看，AI 能力经历了三个阶段：API 12-14 的基础能力阶段（文本/图像 Embedding、ASR/TTS 等），API 15-17 的能力增强阶段（多模态、Data Augmentation Kit 端侧 RAG），以及 API 18-21 的智能体时代（HMAF、Agent Framework Kit）。智慧化数据检索 C 接口的加入，标志着第二阶段与第三阶段之间的重要衔接——它为上层智能体提供了本地化的知识获取与推理能力，使应用开发者能够在端侧构建完整的智慧化数据处理流水线。

这套 C 接口的能力范围涵盖了三个核心领域：向量化处理（Embedding）、知识检索（知识图谱检索及语义检索）和知识问答（RAG 问答），并在 HarmonyOS 6.0.0(20) Beta5 版本中正式开放给开发者使用。主场景面向 PC/2in1 设备，同时支持手机、平板等多种设备形态。

本文将从技术架构切入，依次拆解数据向量化、知识检索、知识问答三大能力模块，并提供可直接落地的 C 接口代码示例。

2 -> 核心理念：三层模型与端侧优先

2.1 -> 数据加工 — 检索 — 问答三层分离

Data Augmentation Kit 的设计遵循一个清晰的核心理念：将数据从原始形态转化为可服务的智能能力，必须经过三个独立且衔接的层次。

第一层是 知识加工（Knowledge Processing） 。原始数据（文本、图片或结构化数据）经过 Embedding 模型进行向量化处理后，分别写入向量数据库和倒排索引库。向量数据库负责存储语义特征向量，支持相似性搜索；倒排索引库则负责关键词精确匹配。

第二层是 知识检索（Knowledge Retrieval） 。系统接收到用户查询（Query）后，采用“多路召回 + 重排序”两阶段架构。第一阶段，通过向量召回和倒排召回并行获取候选结果集；第二阶段，通过 RRF（Reciprocal Rank Fusion）或分数融合算法对候选结果进行相关性打分和重新排序，筛选出最相关的若干知识片段。

第三层是 知识问答（RAG） 。将用户问题与第二阶段召回的相关知识片段拼接成提示（Prompt），交由大语言模型生成最终答案，并通过流式方式输出到前端。

把这三层职责拆分开，不仅便于模块化开发和独立调优，也使得每一层都可以根据具体业务需求灵活替换组件（如更换 Embedding 模型、更换 LLM 等），而不会牵动整体架构。

2.2 -> 端侧优先与数据隐私

Data Augmentation Kit 的一个重要设计决策是“端侧优先”。知识库构建、向量化检索、RAG 问答等核心环节均可在端侧独立完成，数据无需上传云端。对于 PC、手机等设备，通过调用 NPU 算力完成向量计算和模型推理，既保证了对时效性的要求，也从根本上规避了敏感数据离开本地设备所带来的隐私风险。

端侧问答模型的引入，使得即使在无网络环境下，应用仍可基于本地知识库提供智能问答服务。这也与 HarmonyOS 6.0 整体的“端侧智能为主、云侧协同为辅”计算架构保持一致。

3 -> C 接口核心能力之一：向量化（Embedding）

3.1 -> 技术要点

智慧化数据检索 C 接口的核心能力之一是将文本、图片等数据转化为高维向量表示。这套接口基于 HarmonyOS 内置的向量数据库能力，支持 floatvector 数据类型的存储和检索。在实际应用中，开发者需要完成以下工作：

1. 选择合适的 Embedding 模型（可选用鸿蒙端侧内置模型或第三方模型），将原始数据转换成固定维度的向量；
2. 使用 C 接口提供的向量数据库 API，将生成的向量与原始数据关联存储；
3. 在进行检索时，将用户查询同样向量化，并通过向量近似度计算获得语义相近的结果。

3.2 -> 约束与限制

• 查询词长度不超过 512 字符；
• 向量近似阈值需要在召回配置中设定；
• 向量召回目前仅支持基于向量数据库的召回方式。

3.3 -> 代码示例（C 接口）

以下示例展示了向量数据库的基础配置与向量召回检索器的创建流程。

#include "dataaugmentation/retrieval/aip_retrieval.h"
#include "dataaugmentation/retrieval/aip_retrieval_config.h"
#include "dataaugmentation/retrieval/aip_retrieval_condition.h"
#include "dataaugmentation/retrieval/aip_retrieval_result.h"

// 1. 创建检索器配置对象
OH_Retrieval_Config *config = OH_Retrieval_CreateConfig();
if (config == NULL) {
    // 错误处理
    return -1;
}

// 2. 配置数据库参数（向量数据库路径、名称等）
OH_Retrieval_DbConfig dbConfig;
dbConfig.dbPath = "/data/data/your.package.name/databases/";
dbConfig.dbName = "knowledge_vector.db";
dbConfig.vector = true;  // 启用向量数据库模式

// 3. 将数据库配置添加到检索器中
int ret = OH_Retrieval_AddConfig(config, RETRIEVAL_CHANNEL_VECTOR, &dbConfig);
if (ret != 0) {
    OH_Retrieval_DestroyConfig(config);
    return -1;
}

// 4. 基于配置创建检索器实例
OH_Retrieval_Retriever *retriever = OH_Retrieval_CreateRetriever(config);
if (retriever == NULL) {
    OH_Retrieval_DestroyConfig(config);
    return -1;
}

// 5. （可选）配置向量召回阈值
OH_Retrieval_VectorRecallConfig vecConfig;
vecConfig.similarityThreshold = 0.75f;  // 相似度阈值，范围[0,1]
vecConfig.topK = 100;                   // 返回的前K个结果

OH_Retrieval_SetVectorConfig(retriever, &vecConfig);

// 清理资源：使用完后销毁配置和检索器
OH_Retrieval_DestroyConfig(config);
OH_Retrieval_DestroyRetriever(retriever);

说明：上述代码中 OH_Retrieval_AddConfig 的第一个参数为检索配置对象，第二个参数 RETRIEVAL_CHANNEL_VECTOR 标识当前配置向量通道，第三个参数为数据库配置指针。OH_Retrieval_SetVectorConfig 用于设定向量召回的相似度阈值和返回数量。

4 -> C 接口核心能力之二：知识检索

4.1 -> 多路召回架构

知识检索是智慧化数据检索的核心环节。此接口采用的方案是“召回（Recall）+ 重排（Re-ranking）”两阶段架构。

召回阶段：

• 向量召回：基于语义相似度，从向量数据库中检索与查询语义相近的知识片段；
• 倒排召回：基于关键词命中，从倒排索引库中检索包含特定词汇的知识片段。

两类召回通道并行执行，最大限度覆盖可能相关的结果。

重排阶段：

召回阶段输出的候选结果集规模较大（deepSize 默认值为 500，RAG 检索召回阶段最多返回 600 个 chunk）。重排模块负责对这些候选结果进行二次筛选和排序，最终输出高质量的相关知识片段。

排序模块支持将结果划分为高、中、低三档，供业务方根据实际需求决定最终检索结果的呈现逻辑。对于向量召回通道，档位划分基于向量分数阈值实现：开发者可设置一个或两个阈值，分别对应高档位和中档位的门槛，低于最终阈值的结果归入低档位。

4.2 -> 条件过滤与精确搜索

检索条件接口 aip_retrieval_condition.h 提供了灵活的检索条件构造能力，支持结果列筛选（responseColumns）、召回深度配置（deepSize）等高级参数。

4.3 -> 代码示例（检索条件构造与检索）

#include "dataaugmentation/retrieval/aip_retrieval_condition.h"

// 1. 创建检索条件对象
OH_Retrieval_Condition *condition = OH_Retrieval_CreateCondition();
if (condition == NULL) {
    // 错误处理
    return -1;
}

// 2. 设置检索文本（用户查询）
const char *queryText = "鸿蒙系统向量检索的使用方法";
OH_Retrieval_SetQueryText(condition, queryText);

// 3. 配置检索参数
OH_Retrieval_SetTopK(condition, 50);          // 最终返回结果数量
OH_Retrieval_SetDeepSize(condition, 500);     // 召回阶段候选结果数量

// 4. 配置过滤条件（可选）
OH_Retrieval_Filter filter;
filter.columnName = "category";
filter.op = OP_EQUAL;
filter.value = "technology";
OH_Retrieval_AddFilter(condition, &filter);

// 5. 指定返回的结果列
const char *responseColumns[] = {"id", "content", "score", "category"};
OH_Retrieval_SetResponseColumns(condition, responseColumns, 4);

// 6. 执行检索（假设已有检索器 retriever）
OH_Retrieval_Result *result = OH_Retrieval_Search(retriever, condition);
if (result != NULL) {
    // 获取结果总数
    uint32_t count = OH_Retrieval_GetResultCount(result);
    
    // 遍历检索结果
    for (uint32_t i = 0; i < count; i++) {
        const char *content = OH_Retrieval_GetResultContent(result, i);
        float score = OH_Retrieval_GetResultScore(result, i);
        // 处理每条检索结果，例如用于 RAG 问答的上下文拼接
    }
    
    OH_Retrieval_DestroyResult(result);
}

// 7. 销毁检索条件对象
OH_Retrieval_DestroyCondition(condition);

5 -> C 接口核心能力之三：知识问答（RAG）

5.1 -> RAG 工作流程

在实际项目中，Data Augmentation Kit 的 RAG 能力需要经历以下完整步骤：

1. 知识加工：数据源经过知识加工链路，产出向量库（*_vector.db）和倒排库两个知识库——这是所有后续工作的前置条件；
2. 创建会话：调用 createRagSession 创建一次 RAG 问答会话；
3. 发起问答：调用 streamRun 发启流式问答，系统自动完成检索 + LLM 生成；
4. 模型交互：通过继承 ChatLLM 类，接入云端模型或鸿蒙端侧问答模型；
5. 答案输出：按流式方式将生成内容逐步输出到前端界面。

一个重要的设计是：大模型交互并未被写死在系统内部，应用开发者可以通过继承 ChatLLM 自由选择对接任意云端大模型，也可以切换至端侧模型以满足隐私和离线场景的需求。

5.2 -> 约束与边界条件

在实际开发中，有几个关键约束值得注意：

• 必须先做知识加工：没有知识加工就没有知识库，RAG 问答链路的输入完全依赖于已加工完成的向量库和倒排库；
• 单线程限制：createRagSession 和 streamRun 不支持多线程调用，不同会话之间可并行但同一会话须串行执行；
• 提问长度限制：用户问题长度上限为 1000 个字符（中文字符按 UTF-8 编码约占用 3 字节，折算后中文场景约 300 字左右）；
• 历史对话的限制：RAG 在问答时最多只看最近 1 轮 QA 历史。若需要更长上下文，需要在前端自行将多轮对话拼接进 prompt 中；
• 检索上限：单次检索最多召回 600 个 chunk，这是知识覆盖度与检索性能之间的平衡点。

5.3 -> 代码示例（RAG 会话创建与流式问答）

下面的示例展示了一个完整的 RAG 问答流程，涵盖自定义 ChatLLM 实现、会话创建和流式问答全过程。

#include "dataaugmentation/rag/aip_rag.h"
#include "dataaugmentation/rag/aip_rag_chatllm.h"

// 第一步：自定义 ChatLLM 客户端（接入具体的大模型）
typedef struct {
    OH_RAG_ChatLLM parent;
    const char *modelEndpoint;  // 模型服务地址
    const char *apiKey;         // API 密钥
} MyChatLLM;

// 实现与大模型的交互逻辑
static const char* MyChatLLM_Invoke(OH_RAG_ChatLLM *chatLLM, 
                                     const char *prompt, 
                                     size_t *outLen) {
    MyChatLLM *myLLM = (MyChatLLM*)chatLLM;
    // 向目标大模型服务发起 HTTP 请求
    // 拼接 prompt，调用云端或端侧模型，获取生成结果
    // 注意：此处应实现完整的 HTTP 客户端逻辑
    const char *response = "根据您的问题，鸿蒙系统支持基于向量数据库的语义检索...";
    *outLen = strlen(response);
    return response;
}

// 第二步：创建 RAG 会话
OH_RAG_Session *session = OH_RAG_CreateSession();
if (session == NULL) {
    // 错误处理
    return -1;
}

// 第三步：配置自定义 ChatLLM（或使用端侧默认模型）
MyChatLLM myLLM = {0};
myLLM.parent.invoke = MyChatLLM_Invoke;
myLLM.modelEndpoint = "https://your-model-endpoint.com/v1/chat";
myLLM.apiKey = "your-api-key";
OH_RAG_SetChatLLM(session, (OH_RAG_ChatLLM*)&myLLM);

// 第四步：配置 RAG 检索参数
OH_RAG_Config ragConfig;
ragConfig.knowledgeBaseId = "your_knowledge_base_id";
ragConfig.recallTopK = 10;      // 检索阶段返回给 LLM 的文档片段数
ragConfig.deepSize = 500;       // 召回阶段候选集大小
OH_RAG_SetConfig(session, &ragConfig);

// 第五步：发起流式问答
const char *userQuestion = "如何使用鸿蒙的 RAG 能力构建一个知识问答系统？";

// 定义流式回调函数
void streamCallback(const char *chunk, int isLast, void *userData) {
    // 将 chunk 逐步渲染到 UI
    printf("%s", chunk);
    fflush(stdout);
    if (isLast) {
        printf("\n[输出完成]\n");
    }
}

// 执行流式问答
int ret = OH_RAG_StreamRun(session, userQuestion, streamCallback, NULL);
if (ret != 0) {
    // 错误处理：检查是否已执行知识加工
    printf("RAG 问答执行失败，请确认已执行知识加工流程\n");
}

// 第六步：销毁会话
OH_RAG_DestroySession(session);

关键提示：以上示例中 OH_RAG_StreamRun 的第二个参数为用户问题，第三个参数为流式输出回调函数。每次推送一个文本片段（chunk）时该回调会被触发一次，当 isLast 为 true 时表示输出结束。如果调用失败，应首先检查知识加工是否已完成 —— 这是 RAG 问答链路能够正常运行的硬性前提。

6 -> 实际应用场景与生态案例

6.1 -> 端侧 RAG 智能助手

在手机和平板场景中，用户上传本地 PDF、办公文档或笔记，应用通过 File API 读取后对文本进行分片和向量化，存入端侧向量数据库。用户提出自然语言问题时，系统在本地完成向量相似度检索，将匹配的文本片段作为上下文，配合端侧小模型生成精准回答。全程无需联网，保证了数据绝对不出端。

6.2 -> 邮件知识与意图检索

Coremail 在鸿蒙 6.0 系统中，依托 ArkData 提供的向量数据库与 RAG 能力，打造了个人邮件知识库。通过对邮件内容进行向量化处理和知识加工形成知识体系，在搜索、意图识别和关联查询等关键环节构建整体架构，使邮件系统在终端层面更贴合用户需求、理解用户意图。Coremail 还计划进一步利用图模型等技术，结合鸿蒙开放能力，将邮件系统从“帮你找到信息”的助手升级为“帮你完成任务”的智能伙伴。

6.3 -> 跨设备知识共享与分布式检索

借助鸿蒙分布式软总线和分布式数据管理能力，向量知识库可以在手机、PC、平板、车机等多设备之间同步。用户在手机端检索知识库并生成的向量索引，可通过分布式数据管理服务同步至车机或 PC；当用户在另一台设备上提同类型问题时，端侧向量数据库可立即返回匹配结果，实现“一次构建、全场景复用”的智能体验。

7 -> 总结与展望

Data Augmentation Kit 的智慧化数据检索 C 接口，为 HarmonyOS 6.0 的应用开发者提供了一个完整、灵活、端侧优先的数据智能解决方案。从数据向量化加工、多路召回的知识检索，到 RAG 流式知识问答，三个核心能力在此接口中系统性地融汇贯通。

这套接口带来的核心价值体现在三个方面：

第一，降低 AI 应用开发门槛。 知识库构建、Embedding 向量化、多路召回与重排、流式 RAG 问答等复杂的 AI 技术环节，被封装为规范统一的 C 接口，开发者无需从底层造轮子即可快速调用。

第二，强化数据隐私保护。 端侧优先的架构设计确保了用户数据不离本地设备，从根本上规避了云端数据泄露风险，满足政务、金融、医疗等对数据安全有严格要求的行业场景。

第三，充分释放端侧 NPU 算力。 通过内置的向量化模型和端侧问答模型，这套接口能够直通硬件 NPU 实现高效计算，在保障实时响应的同时降低了端到端的使用成本。

随着 HarmonyOS 向 API 21 及更高版本演进，以及在 AI 智能体生态（HMAF、Agent Framework Kit）框架下的深度融合，智慧化数据检索能力将成为更宏大智能体应用生态的关键数据供给层。以 HarmonyOS 6 的 Data Augmentation Kit C 接口为起点，开发者将有机会在端侧构建出真正个性化、智能化、安全可控的数据应用，为全场景智慧生态注入新的活力。

---

感谢各位大佬支持！！！
互三啦！！！