本文引用的文件
嵌入调试接口是用于验证本地 ONNX embedding 模型是否正常工作的人工测试入口。它通过 Spring MVC 控制器暴露一个 POST 端点,接收一批文本,调用 EmbeddingService 使用进程内 OnnxEmbeddingEngine 执行推理,生成向量并计算两两余弦相似度矩阵,最终返回维度、耗时、向量数组和相似度矩阵。该接口仅用于本地模型能力验证,不参与业务路由;业务侧统一通过 EmbeddingProvider 选择本地或在线 embedding 模型。
嵌入调试功能集中在 ai-server 模块的 embedding 子模块中,采用“控制器 → 服务层 → 推理引擎”的分层结构:
graph TB
Client["客户端"] --> Controller["EmbeddingDebugController<br/>POST /embedding/debug"]
Controller --> Service["EmbeddingService<br/>embedBatch / cosineSimilarity / getDimension"]
Service --> Engine["OnnxEmbeddingEngine<br/>ONNX Runtime 会话"]
Engine --> Model["bge-m3 ONNX 模型<br/>tokenizer.json + model.onnx"]
Service --> Config["EmbeddingProperties<br/>zsjz.embedding.*"]
图示来源
章节来源
/embedding/debug,负责计时、调用批量嵌入、构造相似度矩阵并封装为统一返回体。zsjz.embedding.*,包含开关、模型路径、维度、最大序列长度、批大小、线程数、优化级别和预热策略。章节来源
调试接口的完整调用链如下:
sequenceDiagram
participant Client as "客户端"
participant Controller as "EmbeddingDebugController"
participant Service as "EmbeddingService"
participant Engine as "OnnxEmbeddingEngine"
participant Model as "bge-m3 ONNX 模型"
Client->>Controller: "POST /embedding/debug<br/>EmbeddingDebugDTO"
Controller->>Controller: "记录开始时间"
Controller->>Service: "embedBatch(texts)"
Service->>Service: "按 batch-size 分批"
Service->>Engine: "embed(chunk)"
Engine->>Engine: "ensureLoaded()"
Engine->>Model: "读取 tokenizer.json / model.onnx"
Engine->>Engine: "分词、构造输入张量"
Engine->>Model: "ORT 会话推理"
Engine-->>Service: "L2 归一化后的 float[] 列表"
Service-->>Controller: "float[] 列表"
Controller->>Controller: "记录结束时间"
Controller->>Service: "getDimension()"
Controller->>Service: "cosineSimilarity(a,b)"
Service-->>Controller: "余弦相似度"
Controller-->>Client: "Result<EmbeddingDebugVO>"
图示来源
| 项目 | 说明 |
|---|---|
| 路径 | /embedding/debug |
| 方法 | POST |
| 内容类型 | JSON |
| 用途 | 人工验证本地 embedding 模型是否正常,包括维度、归一化、语义区分度 |
| 业务路由关系 | 不参与业务路由,仅调试本地 ONNX 模型 |
| 统一返回体 | Result<EmbeddingDebugVO> |
字段定义如下:
| 字段名 | 类型 | 必填 | 约束 | 含义 |
|---|---|---|---|---|
texts |
List<String> |
是 | 非空,最多 16 条 | 待嵌入的原始文本,顺序决定返回向量顺序 |
{
"texts": [
"转账给可疑账户",
"对方账户存在洗钱风险",
"正常消费支付订单"
]
}
章节来源
字段定义如下:
| 字段名 | 类型 | 含义 |
|---|---|---|
dimension |
int |
输出向量维度;默认 bge-m3 为 1024 |
embedMillis |
long |
本次批量嵌入的耗时(毫秒) |
vectors |
List<float[]> |
与输入顺序一致的向量数组,每个元素已做 L2 归一化 |
similarity |
List<List<Double>> |
两两余弦相似度矩阵,similarity[i][j] 表示第 i 条与第 j 条文本的相似度 |
{
"code": 200,
"data": {
"dimension": 1024,
"embedMillis": 123,
"vectors": [
[0.0123, -0.0456, 0.0789],
[-0.0321, 0.0654, 0.0987],
[0.0111, 0.0222, 0.0333]
],
"similarity": [
[1.0, 0.85, 0.12],
[0.85, 1.0, 0.09],
[0.12, 0.09, 1.0]
]
},
"message": "成功"
}
章节来源
控制器职责明确且轻量:
@Valid 校验后的 EmbeddingDebugDTO。System.currentTimeMillis() 作为开始时间。EmbeddingService.embedBatch(texts) 获取向量列表。EmbeddingDebugVO.embedMillis。EmbeddingService.getDimension() 设置维度。similarityMatrix 计算两两余弦相似度矩阵。Result.succeed(vo) 返回统一结果。相似度矩阵计算逻辑:
embeddingService.cosineSimilarity(row, col)。相似度值四舍五入到小数点后四位。
flowchart TD
Start(["进入 debug 方法"]) --> TimeStart["记录开始时间"]
TimeStart --> BatchEmbed["调用 embedBatch 获取向量"]
BatchEmbed --> TimeEnd["记录结束时间并计算耗时"]
TimeEnd --> BuildVO["构造 EmbeddingDebugVO"]
BuildVO --> SetDimension["设置 dimension"]
SetDimension --> SetVectors["设置 vectors"]
SetVectors --> ComputeSim["计算 similarity 矩阵"]
ComputeSim --> Round4["对相似度四舍五入到四位小数"]
Round4 --> Return["返回 Result.success"]
图示来源
章节来源
服务层承担以下关键职责:
properties.isEnabled(),未启用时抛出 EmbeddingException。embed(text) 调用引擎并校验输出维度。embedBatch(texts) 按 batchSize 分批,避免单次批次过大导致内存峰值过高。dimensions 配置一致,防止写错 pgvector 表维度。getDimension() 会触发模型懒加载;getDeclaredDimension() 仅读配置,不加载模型。isAvailable() 不加载权重,只判断开关和模型目录是否存在。warmUp() 同步预热;warmUpAsync() 后台守护线程异步预热。生命周期:实现 AutoCloseable,Spring 销毁时关闭引擎。
classDiagram
class EmbeddingService {
-EmbeddingProperties properties
-Path modelDir
-OnnxEmbeddingEngine engine
+init() void
+embed(text) float[]
+embedBatch(texts) List~float[]~
+cosineSimilarity(a, b) double
+getDimension() int
+getDeclaredDimension() int
+isEnabled() boolean
+isAvailable() boolean
+getModelName() String
+isReady() boolean
+warmUp() void
+warmUpAsync() void
-checkEnabled() void
-checkDimension(vector) float[]
-resolveModelDir(modelPath) Path
+close() void
}
class EmbeddingProperties {
+boolean enabled
+String modelPath
+int dimensions
+int maxSeqLen
+int batchSize
+int intraOpThreads
+String optLevel
+boolean eagerLoad
}
class OnnxEmbeddingEngine {
+ensureLoaded() void
+embed(texts) List~float[]~
+getDimension() int
+isReady() boolean
+close() void
}
EmbeddingService --> EmbeddingProperties : "读取配置"
EmbeddingService --> OnnxEmbeddingEngine : "调用推理"
图示来源
章节来源
引擎面向 bge-m3 导出物,兼容同类 XLM-RoBERTa/BERT 结构模型,核心流程如下:
ensureLoaded() 才加载分词器和 ORT 会话。modelDir 下存在 tokenizer.json 与 onnx/model.onnx,不存在则回退到 model.onnx。modelMaxLength,避免 DJL 缺省按 512 截断。input_ids、attention_mask、token_type_ids、position_ids。session.run(inputs)。dimension。线程安全:会话 run 线程安全;分词器操作串行化以避免原生句柄并发问题。
flowchart TD
Start(["调用 embed(texts)"]) --> Ensure["ensureLoaded()"]
Ensure --> Tokenize["batchEncode 分词"]
Tokenize --> BuildInputs["构造 input_ids 与 attention_mask"]
BuildInputs --> OptionalInputs{"是否需要 token_type_ids / position_ids"}
OptionalInputs -->|需要| AddOptional["补全可选输入张量"]
OptionalInputs -->|不需要| RunSession["session.run(inputs)"]
AddOptional --> RunSession
RunSession --> ExtractOutput["提取 last_hidden_state 或首个输出"]
ExtractOutput --> Pool["CLS 池化或取 pooled 输出"]
Pool --> Normalize["L2 归一化"]
Normalize --> CacheDim["缓存输出维度"]
CacheDim --> End(["返回向量列表"])
图示来源
章节来源
配置前缀为 zsjz.embedding,常用项如下:
| 配置键 | 类型 | 默认值 | 含义 |
|---|---|---|---|
enabled |
boolean |
true |
是否启用本地 embedding 模型 |
model-path |
String |
bge-m3 |
模型目录,需含 tokenizer.json 与 onnx/model.onnx |
dimensions |
int |
1024 |
bge-m3 声明维度,用于建表和状态展示 |
max-seq-len |
int |
8192 |
单文本最大 token 数,超出截断 |
batch-size |
int |
8 |
批量推理每批文本条数 |
intra-op-threads |
int |
0 |
ORT intra-op 并行线程数,0 表示使用默认策略 |
opt-level |
String |
BASIC_OPT |
ONNX 图优化级别 |
eager-load |
boolean |
false |
启动时是否后台预热模型 |
章节来源
调试接口依赖链如下:
graph LR
DTO["EmbeddingDebugDTO"] --> Controller["EmbeddingDebugController"]
VO["EmbeddingDebugVO"] --> Controller
Controller --> Service["EmbeddingService"]
Service --> Engine["OnnxEmbeddingEngine"]
Service --> Properties["EmbeddingProperties"]
Engine --> Model["bge-m3 ONNX 模型"]
图示来源
耦合与内聚特点:
EmbeddingProperties 集中管理,便于环境变量覆盖和多环境部署。章节来源
eager-load=true 或 warmUpAsync() 提前预热,避免首调延迟。getDeclaredDimension() 仅读配置,适合建表、状态展示。getDimension() 会触发模型加载,适合需要真实输出维度的场景。batch-size 分批推理,默认 8。intra-op-threads 调整 intra-op 并行线程数;设为 0 时使用 ONNX Runtime 默认策略。opt-level 支持 NO_OPT、BASIC_OPT、EXTENDED_OPT、ALL_OPT;更高级别可能提升推理速度,但首次加载更慢。embedMillis 主要包含:
章节来源
zsjz.embedding.dimensions 配置是否匹配。dimension。texts 严格对应。similarity[i][j] 表示第 i 条与第 j 条文本的余弦相似度。similarity[i][i] 应为 1.0。| 现象 | 可能原因 | 处理建议 |
|---|---|---|
dimension 不是 1024 |
模型目录指向非 bge-m3 模型,或配置维度错误 | 核对 model-path 与 dimensions |
| 首次调用耗时很长 | 懒加载模型权重 | 启用 eager-load 或手动预热 |
| 相似度全部接近 0 | 文本差异极大或模型未正确加载 | 用同义短句测试,确认模型可用 |
| 相似度对角线不是 1.0 | 向量未归一化或维度不一致 | 检查引擎归一化逻辑和维度校验 |
| 批量报错 | 某条文本为空或分词后长度不一致 | 检查输入清洗和最大序列长度 |
章节来源
tokenizer.jsononnx/model.onnxmodel.onnx_datazsjz.embedding.enabled 设置为 true。配置位于 application.yaml 的 zsjz.embedding 段,并支持环境变量覆盖。例如:
| 环境变量 | 对应配置 | 说明 |
|---|---|---|
ZSJZ_EMBEDDING_ENABLED |
zsjz.embedding.enabled |
开启本地 embedding |
ZSJZ_EMBEDDING_MODEL_PATH |
zsjz.embedding.model-path |
模型目录路径 |
ZSJZ_EMBEDDING_DIMENSIONS |
zsjz.embedding.dimensions |
向量维度 |
ZSJZ_EMBEDDING_MAX_SEQ_LEN |
zsjz.embedding.max-seq-len |
最大序列长度 |
ZSJZ_EMBEDDING_BATCH_SIZE |
zsjz.embedding.batch-size |
批大小 |
ZSJZ_EMBEDDING_INTRA_OP_THREADS |
zsjz.embedding.intra-op-threads |
intra-op 线程数 |
ZSJZ_EMBEDDING_OPT_LEVEL |
zsjz.embedding.opt-level |
图优化级别 |
ZSJZ_EMBEDDING_EAGER_LOAD |
zsjz.embedding.eager-load |
是否启动时预热 |
章节来源
model-path 指向的路径不存在。tokenizer.json 与 onnx/model.onnx。model.onnx。onnx/model.onnx。model.onnx。model.onnx_data 是否与主文件同目录。input_ids。dimensions 配置不符。zsjz.embedding.dimensions 与实际模型一致。texts 中不含空字符串或纯空白文本。max-seq-len 和输入清洗逻辑。章节来源
嵌入调试接口是一个面向本地 ONNX embedding 模型的轻量验证工具。它通过 EmbeddingDebugController.debug 暴露 /embedding/debug,借助 EmbeddingService 和 OnnxEmbeddingEngine 完成文本向量化、维度校验、L2 归一化和余弦相似度计算。其核心价值在于帮助运维和研发人员快速确认本地 bge-m3 模型是否可加载、能否输出 1024 维向量、是否具备基本语义区分能力。
使用该接口时,应重点关注:
zsjz.embedding.enabled、model-path、dimensions 配置一致性。similarity 矩阵的对角线和语义相近文本的相似度趋势。该接口不应被视为生产业务路由的一部分;业务向量能力仍应通过 EmbeddingProvider 统一管理本地与在线 embedding 模型。