FastW2V-JNI：从模型到移动端语义检索的完整落地实践

重磅推荐专栏：
《大模型AIGC》
《课程大纲》
《知识星球》

本专栏致力于探索和讨论当今最前沿的技术趋势和应用领域，包括但不限于ChatGPT和Stable Diffusion等。我们将深入研究大型模型的开发和应用，以及与之相关的人工智能生成内容（AIGC）技术。通过深入的技术解析和实践经验分享，旨在帮助读者更好地理解和应用这些领域的最新进展

github 项目地址：https://github.com/xiaoyesoso/FastW2V-JNI

本文基于当前 FastW2V-JNI 仓库源码撰写，目标是从「为什么要做」到「如何实现」，系统性拆解一个支持 Word2Vec + BERT (ONNX Runtime) 的中文语义检索引擎，并完整跑在 Android 端离线环境中。

文章内容将围绕：

• 项目整体设计与目录结构
• Word2Vec 与 BERT 两套引擎的对比与实现
• ONNX Runtime 推理链路（以 CoROM-Tiny 为例）
• 相似度检索引擎的实现（SimilaritySearch）
• JNI 层与 Android 集成实践
• 性能、内存与工程实践经验

同时结合：

• 关键代码片段（带详细注释）
• Mermaid 图（流程图、时序图、类图）
• 结合原模型仓库中的结构图
• 多张总结性表格

方便你既能「看懂」，也能「照着改造自己项目」。

一、项目背景：为什么是 FastW2V-JNI？

在很多中文业务场景里，我们经常会遇到类似的需求：

• 手里有一堆 FAQ / QA 数据，希望用户提问时自动匹配最合适的一条；
• 场景在 App 内部，甚至在离线环境（如车机、嵌入式设备）中；
• 对隐私、安全有要求，希望尽量在本地完成语义计算；
• 设备算力有限，不能上来就塞一个巨大的大模型。

传统方案要么是：

• 后端部署大模型服务，App 通过 HTTP 调用：
  • 好处：模型能力强，易更新；
  • 缺点：依赖网络、延迟高、隐私风险、维护成本高。
• App 内部使用“关键词匹配 + if-else”：
  • 好处：简单直接；
  • 缺点：可维护性差，泛化能力极弱，稍微变换问法就匹配不到。

FastW2V-JNI给出的答案是一条「工程化的中道」：

• 模型层使用两套引擎：
  • 传统Word2Vec：利用大规模预训练词向量，快速且轻量；
  • 现代BERT (CoROM-Tiny)：基于 Transformer 的中文句向量模型，语义表达更强；
• 底层核心逻辑使用C++17实现，性能可控；
• 通过JNI对外暴露统一接口，方便 Android / Java 项目集成；
• 使用ONNX Runtime在端侧执行 BERT 推理；
• 整套方案完全支持离线运行，模型与数据都在本地。

一句话概括：

FastW2V-JNI 是一个“面向移动端的双引擎中文语义检索内核”，同时兼顾性能与语义能力。

二、总体架构总览

2.1 目录结构与模块拆分

先看仓库顶层的目录结构（简化，以核心模块为主）：

. ├── src/ # 核心 C++ 源代码 │ ├── BertEmbedder.cpp # BERT (ONNX) 推理实现 │ ├── BertTokenizer.cpp # BERT 中文 WordPiece 分词 │ ├── SimilaritySearch.cpp # 向量检索 & 余弦相似度 │ ├── TextEmbedder.cpp # 嵌入器统一封装 │ └── W2VEmbedder.cpp # Word2Vec 嵌入实现 ├── include/ # C++ 头文件 │ ├── BertEmbedder.h │ ├── BertTokenizer.h │ ├── SimilaritySearch.h │ ├── TextEmbedder.h │ ├── W2VEmbedder.h │ ├── W2VEngine.h # 组合引擎（给 JNI 用） │ └── com_example_w2v_W2VNative.h ├── jni/ # JNI 层 (C++ 实现 + Java 声明) │ ├── W2VNative.java │ └── com_example_w2v_W2VNative.cpp ├── android_test/ # Android Demo 工程 │ ├── w2v_version/ # 使用 Word2Vec 的 Demo App │ └── bert_version/ # 使用 BERT (ONNX Runtime) 的 Demo App ├── models/ │ └── nlp_corom_sentence-embedding_chinese-tiny/ │ └── resources/ │ └── dual-encoder.png # 原模型的双塔示意图 ├── scripts/ │ └── convert_model.py # CoROM 模型导出 ONNX 的脚本 ├── data/ │ └── qa_list.csv # 示例 QA 数据 ├── README.md └── README_CN.md

从「层次」角度划分，整个项目可以分为三层：

1. 模型与向量层（Embedding Layer）

   • W2VEmbedder：负责 Word2Vec 模型加载、分词、句向量生成；
   • BertEmbedder+BertTokenizer：负责 BERT (ONNX Runtime) 推理和 WordPiece 分词；
   • TextEmbedder：在上层统一包装，外部只关心“给文本 -> 出向量”。

2. 检索层（Search Layer）

   • SimilaritySearch：负责存储 QA 对、计算余弦相似度、返回匹配结果。

3. 桥接与应用层（Bridge & App Layer）

   • W2VEngine：把嵌入层与检索层组合成一个“引擎实例”；
   • JNI 层（com_example_w2v_W2VNative.cpp+W2VNative.java）：把 C++ 能力暴露给 Java/Android；
   • Android Demo App：展示如何在真实 App 中使用引擎。

2.2 总体架构 Mermaid 图

下面用一个 Mermaid 流程图直观地展示从 App 调用到底层模型的整个调用链路：

可以看到，Java 侧只需要和W2VNative打交道，其余所有细节（模型类型选择、ONNX Runtime 推理、Word2Vec 加载、相似度计算等）都隐藏在 C++ 内部。

三、双引擎设计：Word2Vec vs BERT

FastW2V-JNI 有两套主干“向量引擎”：

• Word2Vec 引擎：基于腾讯 AI Lab 中文词向量（轻量版），适合对性能要求极高、语义要求中等的场景；
• BERT (CoROM-Tiny) 引擎：基于 ModelScope 上的iic/nlp_corom_sentence-embedding_chinese-tiny模型，语义表达更强。

3.1 两套引擎对比一览

下面用一个表来概览两者差异：

3.2 统一入口：TextEmbedder

无论底层是 Word2Vec 还是 BERT，外部（包括W2VEngine和 JNI）只依赖TextEmbedder这个统一接口：

// include/TextEmbedder.hclassTextEmbedder{public:enumModelType{MODEL_W2V,// 强制使用 Word2VecMODEL_BERT,// 强制使用 BERTMODEL_AUTO// 自动识别：.onnx => BERT，其它 => W2V};TextEmbedder();~TextEmbedder();// 根据模型路径和类型初始化boolinitialize(conststd::string&model_path,ModelType type=MODEL_AUTO);// BERT 专用初始化（需要额外 vocab 文件）boolinitialize_bert(conststd::string&model_path,conststd::string&vocab_path);// 单条文本生成向量std::vector<float>embed(conststd::string&text);// 批量文本生成向量std::vector<std::vector<float>>embed_batch(conststd::vector<std::string>&texts);intget_embedding_dim()const;size_tget_memory_usage()const;boolis_initialized()const;voidrelease();private:classImpl;// Pimpl 惯用法隐藏实现细节std::unique_ptr<Impl>impl_;};

TextEmbedder.cpp中的核心逻辑是：根据模型路径与指定枚举，选择对应引擎，并对外提供统一的embed接口。

// src/TextEmbedder.cpp（核心片段，添加说明性注释）classTextEmbedder::Impl{public:std::unique_ptr<W2VEmbedder>w2v_ptr;// Word2Vec 引擎std::unique_ptr<BertEmbedder>bert_ptr;// BERT 引擎boolis_bert=false;// 当前是否使用 BERTboolinitialize(conststd::string&model_path,ModelType type){LOGI("初始化 Embedder: path=%s, type=%d",model_path.c_str(),type);// 1）自动识别模型类型：带 .onnx 后缀则视为 BERTif(type==MODEL_AUTO){if(model_path.find(".onnx")!=std::string::npos){type=MODEL_BERT;}else{type=MODEL_W2V;}}// 2）根据类型初始化对应引擎if(type==MODEL_BERT){LOGI("选择 BERT 引擎");bert_ptr=std::unique_ptr<BertEmbedder>(newBertEmbedder());// 根据 ONNX 文件路径推导 vocab.txt 所在位置std::string vocab_path;size_t last_slash=model_path.find_last_of("/\\");if(last_slash!=std::string::npos){vocab_path=model_path.substr(0,last_slash+1)+"vocab.txt";}else{vocab_path="vocab.txt";}// 初始化 BERT 引擎（ONNX 模型 + vocab.txt）if(bert_ptr->initialize(model_path,vocab_path)){is_bert=true;returntrue;}returnfalse;}else{LOGI("选择 Word2Vec 引擎");w2v_ptr=std::unique_ptr<W2VEmbedder>(newW2VEmbedder());if(w2v_ptr->initialize(model_path)){is_bert=false;returntrue;}returnfalse;}}boolinitialize_bert(conststd::string&model_path,conststd::string&vocab_path){LOGI("强制初始化 BERT: model=%s, vocab=%s",model_path.c_str(),vocab_path.c_str());bert_ptr=std::unique_ptr<BertEmbedder>(newBertEmbedder());if(bert_ptr->initialize(model_path,vocab_path)){is_bert=true;returntrue;}returnfalse;}std::vector<float>embed(conststd::string&text){// 运行时根据 is_bert 选择对应引擎if(is_bert){if(bert_ptr){returnbert_ptr->embed(text);}else{LOGI("错误: is_bert=true 但 bert_ptr 为空");}}else{if(w2v_ptr){returnw2v_ptr->embed(text);}else{LOGI("错误: is_bert=false 但 w2v_ptr 为空");}}// 失败则返回空向量returnstd::vector<float>();}intget_embedding_dim()const{if(is_bert&&bert_ptr)returnbert_ptr->get_embedding_dim();if(!is_bert&&w2v_ptr)returnw2v_ptr->get_embedding_dim();return0;}size_tget_memory_usage()const{if(is_bert&&bert_ptr)returnbert_ptr->get_memory_usage();if(!is_bert&&w2v_ptr)returnw2v_ptr->get_memory_usage();return0;}boolis_initialized()const{if(is_bert)returnbert_ptr&&bert_ptr->is_initialized();returnw2v_ptr&&w2v_ptr->is_initialized();}};

可以看到：

• TextEmbedder对外隐藏了 Word2Vec 和 BERT 的具体实现；
• 上层只需要知道：“我传一个模型路径进来，之后就可以用embed得到向量”；
• 这为后续支持更多模型（如 MiniLM、bge、m3e 等）留下了很好的扩展空间。

四、Word2Vec 引擎实现：从词向量到句向量

4.1 模型格式与加载

Word2Vec 引擎对应实现文件为src/W2VEmbedder.cpp，它支持两种常见的词向量格式：

1. 自定义二进制格式：首行是vocab_size dim，后续每行由word+embedding_dim维的二进制 float 组成；
2. 纯文本格式：每行形如word x1 x2 x3 ...。

加载逻辑核心片段如下：

// src/W2VEmbedder.cpp（核心片段，带注释）boolW2VEmbedder::initialize(conststd::string&model_path){// 以二进制方式打开文件，尝试读取“带头信息”的自定义格式std::ifstreamfile(model_path,std::ios::binary);if(!file.is_open())returnfalse;// 读取首行 header，例如 "50000 200"std::string header;std::getline(file,header);std::istringstreamheader_stream(header);intvocab_size=0;header_stream>>vocab_size>>embedding_dim_;if(vocab_size<=0||embedding_dim_<=0){// 情况一：首行不是合法 header，认为是“纯文本格式”file.close();std::ifstreamfile2(model_path);std::string line;while(std::getline(file2,line)){std::istringstreamiss(line);std::string word;iss>>word;// 先读出词std::vector<float>vec;floatval;// 逐个读取后续的浮点数while(iss>>val)vec.push_back(val);if(!vec.empty()){// 第一次遇到向量时确定 embedding_dim_if(embedding_dim_==0)embedding_dim_=vec.size();word_vectors_[word]=vec;// 记录最长词长，用于后续中文切词时的最大匹配长度max_word_len_=std::max(max_word_len_,(int)word.length());}}}else{// 情况二：带 header 的二进制格式for(inti=0;i<vocab_size;++i){std::string word;file>>word;// 先读出词本身（以空格结尾）file.get();// 跳过一个空格std::vector<float>vec(embedding_dim_);// 直接从文件中读 embedding_dim_ * sizeof(float) 字节file.read((char*)vec.data(),embedding_dim_*sizeof(float));word_vectors_[word]=vec;max_word_len_=std::max(max_word_len_,(int)word.length());}}// 准备一个全 0 向量，用于 OOV 或空文本zero_vector_.assign(embedding_dim_,0.0f);initialized_=true;returntrue;}

4.2 中文分词策略：基于词表的最大匹配 + 回退字符切分

由于 Word2Vec 模型通常是“词级别”的，句子向量需要先做分词。这里采用的是一个兼顾简单与效果的策略：

1. 对英文数字部分用类似“token until non-alnum”的方式切分；
2. 对中文使用基于词表的最长匹配策略：
   • 从当前位置开始，以max_word_len_为上界向后尝试；
   • 如果某个子串在word_vectors_中存在，就作为一个词切分；
   • 找不到则回退为单个 UTF-8 字符。

关键代码片段如下：

// src/W2VEmbedder.cpp（中文分词核心逻辑，附注释）std::vector<std::string>W2VEmbedder::tokenize_chinese(conststd::string&text){std::vector<std::string>tokens;size_t i=0;while(i<text.length()){// 1）ASCII 分支：英文 / 数字 / 下划线if((text[i]&0x80)==0){if(isspace(text[i])){// 跳过空白字符i++;continue;}std::string token;// 连续的 [a-zA-Z0-9_] 视为一个 tokenwhile(i<text.length()&&(text[i]