嵌入调试接口.md 27 KB

嵌入调试接口

本文引用的文件

  • EmbeddingDebugController.java
  • EmbeddingService.java
  • OnnxEmbeddingEngine.java
  • EmbeddingProperties.java
  • application.yaml
  • EmbeddingDebugDTO.java
  • EmbeddingDebugVO.java

目录

  1. 简介
  2. 项目结构定位
  3. 核心组件
  4. 架构总览
  5. 接口规范
  6. 详细组件分析
  7. 依赖关系分析
  8. 性能与资源特性
  9. 调试结果解读
  10. 部署与故障排查
  11. 结论

简介

嵌入调试接口是用于验证本地 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.*"]

图示来源

  • EmbeddingDebugController.java:23-62
  • EmbeddingService.java:39-120
  • OnnxEmbeddingEngine.java:41-120
  • EmbeddingProperties.java:1-58

章节来源

  • EmbeddingDebugController.java:1-62
  • EmbeddingService.java:1-120
  • OnnxEmbeddingEngine.java:1-120
  • EmbeddingProperties.java:1-58

核心组件

  • EmbeddingDebugController:REST 控制器,暴露 /embedding/debug,负责计时、调用批量嵌入、构造相似度矩阵并封装为统一返回体。
  • EmbeddingService:本地嵌入服务,统一入口;负责开关校验、分批推理、向量维度校验、余弦相似度计算、模型预热与生命周期管理。
  • OnnxEmbeddingEngine:ONNX 推理引擎,负责加载分词器、创建 ORT 会话、构建输入张量、执行推理、CLS 池化与 L2 归一化。
  • EmbeddingProperties:配置绑定类,映射 zsjz.embedding.*,包含开关、模型路径、维度、最大序列长度、批大小、线程数、优化级别和预热策略。
  • EmbeddingDebugDTO / EmbeddingDebugVO:调试接口的请求与响应数据对象。

章节来源

  • EmbeddingDebugController.java:1-62
  • EmbeddingService.java:1-120
  • OnnxEmbeddingEngine.java:1-120
  • EmbeddingProperties.java:1-58
  • EmbeddingDebugDTO.java:1-19
  • EmbeddingDebugVO.java:1-24

架构总览

调试接口的完整调用链如下:

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>"

图示来源

  • EmbeddingDebugController.java:35-62
  • EmbeddingService.java:70-120
  • OnnxEmbeddingEngine.java:41-120

接口规范

基本信息

项目 说明
路径 /embedding/debug
方法 POST
内容类型 JSON
用途 人工验证本地 embedding 模型是否正常,包括维度、归一化、语义区分度
业务路由关系 不参与业务路由,仅调试本地 ONNX 模型
统一返回体 Result<EmbeddingDebugVO>

请求体:EmbeddingDebugDTO

字段定义如下:

字段名 类型 必填 约束 含义
texts List<String> 是 非空,最多 16 条 待嵌入的原始文本,顺序决定返回向量顺序

请求示例

{
  "texts": [
    "转账给可疑账户",
    "对方账户存在洗钱风险",
    "正常消费支付订单"
  ]
}

章节来源

  • EmbeddingDebugDTO.java:1-19

响应体:EmbeddingDebugVO

字段定义如下:

字段名 类型 含义
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": "成功"
}

章节来源

  • EmbeddingDebugVO.java:1-24

详细组件分析

EmbeddingDebugController:调试控制器

控制器职责明确且轻量:

  1. 接收 @Valid 校验后的 EmbeddingDebugDTO。
  2. 记录 System.currentTimeMillis() 作为开始时间。
  3. 调用 EmbeddingService.embedBatch(texts) 获取向量列表。
  4. 计算耗时并存入 EmbeddingDebugVO.embedMillis。
  5. 调用 EmbeddingService.getDimension() 设置维度。
  6. 将向量列表直接放入响应。
  7. 调用内部 similarityMatrix 计算两两余弦相似度矩阵。
  8. 通过 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"]
    

图示来源

  • EmbeddingDebugController.java:35-62

章节来源

  • EmbeddingDebugController.java:1-62

EmbeddingService:本地嵌入服务

服务层承担以下关键职责:

  • 开关校验:所有公开方法先检查 properties.isEnabled(),未启用时抛出 EmbeddingException。
  • 单文本嵌入:embed(text) 调用引擎并校验输出维度。
  • 批量嵌入:embedBatch(texts) 按 batchSize 分批,避免单次批次过大导致内存峰值过高。
  • 维度校验:实际向量长度必须与 dimensions 配置一致,防止写错 pgvector 表维度。
  • 余弦相似度:实现完整余弦公式,兼容归一化和未归一化向量;当两个向量为零向量时返回 0。
  • 维度查询: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 : "调用推理"
    

图示来源

  • EmbeddingService.java:39-244
  • EmbeddingProperties.java:1-58
  • OnnxEmbeddingEngine.java:41-299

章节来源

  • EmbeddingService.java:39-244

OnnxEmbeddingEngine:ONNX 推理引擎

引擎面向 bge-m3 导出物,兼容同类 XLM-RoBERTa/BERT 结构模型,核心流程如下:

  1. 懒加载:首次调用 ensureLoaded() 才加载分词器和 ORT 会话。
  2. 模型目录校验:要求 modelDir 下存在 tokenizer.json 与 onnx/model.onnx,不存在则回退到 model.onnx。
  3. 分词器初始化:显式传入 modelMaxLength,避免 DJL 缺省按 512 截断。
  4. 会话选项:支持图优化级别和 intra-op 线程数配置。
  5. 输入探测:动态读取模型输入名,仅支持 input_ids、attention_mask、token_type_ids、position_ids。
  6. 张量构建:批量 padding、补全可选输入。
  7. 推理执行:session.run(inputs)。
  8. 池化与归一化:取 CLS 位置或第一层输出,执行 L2 归一化。
  9. 维度缓存:首次推理后填充 dimension。
  10. 线程安全:会话 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(["返回向量列表"])
    

图示来源

  • OnnxEmbeddingEngine.java:41-180
  • OnnxEmbeddingEngine.java:201-299

章节来源

  • OnnxEmbeddingEngine.java:1-299

EmbeddingProperties:配置项

配置前缀为 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 启动时是否后台预热模型

章节来源

  • EmbeddingProperties.java:1-58
  • application.yaml:120-170

依赖关系分析

调试接口依赖链如下:

graph LR
    DTO["EmbeddingDebugDTO"] --> Controller["EmbeddingDebugController"]
    VO["EmbeddingDebugVO"] --> Controller
    Controller --> Service["EmbeddingService"]
    Service --> Engine["OnnxEmbeddingEngine"]
    Service --> Properties["EmbeddingProperties"]
    Engine --> Model["bge-m3 ONNX 模型"]

图示来源

  • EmbeddingDebugController.java:23-62
  • EmbeddingService.java:39-120
  • OnnxEmbeddingEngine.java:41-120
  • EmbeddingDebugDTO.java:1-19
  • EmbeddingDebugVO.java:1-24

耦合与内聚特点:

  • 控制器只负责 HTTP 层适配和结果组装,业务逻辑下沉至服务层。
  • 服务层屏蔽了分批、维度校验、预热等细节,对外提供稳定 API。
  • 引擎层专注 ONNX Runtime 集成,对上层只暴露嵌入与维度查询。
  • 配置通过 EmbeddingProperties 集中管理,便于环境变量覆盖和多环境部署。

章节来源

  • EmbeddingDebugController.java:1-62
  • EmbeddingService.java:1-120
  • OnnxEmbeddingEngine.java:1-120
  • EmbeddingProperties.java:1-58

性能与资源特性

模型加载与内存占用

  • 模型权重常驻堆外内存,约 2.5~3GB。
  • 懒加载模式:首次调用时才载入权重,启动不阻塞。
  • 可通过 eager-load=true 或 warmUpAsync() 提前预热,避免首调延迟。
  • 模型加载耗时通常在 20~60 秒之间,取决于磁盘和网络。

向量维度配置

  • 默认维度为 1024,对应 bge-m3 dense 向量。
  • getDeclaredDimension() 仅读配置,适合建表、状态展示。
  • getDimension() 会触发模型加载,适合需要真实输出维度的场景。
  • 实际向量长度与配置不一致时会抛出异常,防止写入错误维度的 pgvector 列。

归一化行为

  • 引擎在 CLS 池化后执行 L2 归一化。
  • 已归一化向量的余弦相似度等价于点积,但服务层仍按完整余弦公式计算,以兼容外部未归一化向量。
  • 零向量余弦相似度返回 0。

批量大小

  • 请求层限制最多 16 条文本。
  • 服务层按 batch-size 分批推理,默认 8。
  • 批内由分词器按最长文本 padding,因此同批中文本越长,内存和计算开销越大。

CPU/GPU 性能

  • 当前实现基于 ONNX Runtime CPU 会话,没有显式 GPU 后端切换逻辑。
  • 可通过 intra-op-threads 调整 intra-op 并行线程数;设为 0 时使用 ONNX Runtime 默认策略。
  • opt-level 支持 NO_OPT、BASIC_OPT、EXTENDED_OPT、ALL_OPT;更高级别可能提升推理速度,但首次加载更慢。
  • 长文本会增加 token 数量,显著增加 CPU 推理耗时。

接口耗时构成

embedMillis 主要包含:

  1. 首次模型懒加载耗时(若尚未预热)。
  2. 分词器批量编码耗时。
  3. ONNX Runtime 推理耗时。
  4. CLS 池化与 L2 归一化耗时。
  5. 相似度矩阵计算耗时(O(n²) 次余弦计算)。

章节来源

  • EmbeddingService.java:39-120
  • OnnxEmbeddingEngine.java:41-299
  • EmbeddingProperties.java:1-58
  • application.yaml:120-170

调试结果解读

dimension

  • 表示向量维度。
  • 对于 bge-m3,预期值为 1024。
  • 若不为 1024,应检查模型目录是否正确、是否使用了其他 embedding 模型、以及 zsjz.embedding.dimensions 配置是否匹配。

embedMillis

  • 表示从发起批量嵌入到完成的时间。
  • 首次调用可能包含模型加载时间。
  • 建议多次调用取平均值,排除首次加载抖动。
  • 若耗时异常偏高,可检查:
    • 是否未预热模型。
    • 是否一次性传入过长文本。
    • 是否设置了过多 intra-op 线程导致竞争。
    • 是否磁盘 I/O 较慢。

vectors

  • 数组长度为输入文本条数。
  • 每个向量长度为 dimension。
  • 向量已 L2 归一化。
  • 顺序与请求 texts 严格对应。
  • 可用于后续自定义相似度计算、聚类或可视化。

similarity

  • 二维数组,大小为 n×n,其中 n 为输入文本条数。
  • similarity[i][j] 表示第 i 条与第 j 条文本的余弦相似度。
  • 对角线 similarity[i][i] 应为 1.0。
  • 相似语义的文本通常具有较高相似度。
  • 值范围理论上接近 [-1, 1];已归一化向量更接近 [0, 1] 的正区间。
  • 值被四舍五入到小数点后四位,便于日志和前端展示。

典型诊断规则

现象 可能原因 处理建议
dimension 不是 1024 模型目录指向非 bge-m3 模型,或配置维度错误 核对 model-path 与 dimensions
首次调用耗时很长 懒加载模型权重 启用 eager-load 或手动预热
相似度全部接近 0 文本差异极大或模型未正确加载 用同义短句测试,确认模型可用
相似度对角线不是 1.0 向量未归一化或维度不一致 检查引擎归一化逻辑和维度校验
批量报错 某条文本为空或分词后长度不一致 检查输入清洗和最大序列长度

章节来源

  • EmbeddingDebugController.java:47-62
  • EmbeddingDebugVO.java:1-24
  • OnnxEmbeddingEngine.java:201-299

部署与故障排查

前置条件

  1. 本地 embedding 模型已下载并解压到指定目录。
  2. 模型目录包含:
    • tokenizer.json
    • onnx/model.onnx
    • 可选外部权重 model.onnx_data
  3. zsjz.embedding.enabled 设置为 true。
  4. 服务器有足够堆外内存承载约 2.5~3GB 模型权重。
  5. Java 运行时版本与 ONNX Runtime native 库兼容。

配置文件位置

配置位于 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 是否启动时预热

章节来源

  • application.yaml:120-170
  • EmbeddingProperties.java:1-58

常见问题与排查步骤

模型目录不存在

  • 表现:加载分词器或 ONNX 会话时报错。
  • 原因:model-path 指向的路径不存在。
  • 排查:
    • 确认相对路径是按工作目录解析。
    • 确认绝对路径或相对路径确实存在。
    • 确认目录下包含 tokenizer.json 与 onnx/model.onnx。

缺少 ONNX 模型文件

  • 表现:提示未找到 model.onnx。
  • 原因:模型目录结构不符合约定。
  • 排查:
    • 优先期望 onnx/model.onnx。
    • 不支持时回退 model.onnx。
    • 检查外部权重 model.onnx_data 是否与主文件同目录。

模型输入不兼容

  • 表现:提示模型存在引擎无法供给的输入或缺少必需输入。
  • 原因:导出的 ONNX 模型输入名不符合预期。
  • 排查:
    • 检查模型输入是否包含 input_ids。
    • 检查是否出现未知输入名。
    • 确认使用的是 bge-m3 或兼容 XLM-RoBERTa/BERT 结构的导出模型。

输出维度不一致

  • 表现:抛出维度不一致异常。
  • 原因:实际模型输出维度与 dimensions 配置不符。
  • 排查:
    • 修改 zsjz.embedding.dimensions 与实际模型一致。
    • 重建向量索引,避免 pgvector 表维度损坏。

向量长度为 0

  • 表现:余弦相似度计算失败或结果为 0。
  • 原因:输入为空文本,或归一化后出现零向量。
  • 排查:
    • 确保 texts 中不含空字符串或纯空白文本。
    • 检查分词后是否被截断为空。
    • 调整 max-seq-len 和输入清洗逻辑。

预热失败

  • 表现:后台预热线程打印预热失败日志。
  • 原因:模型路径、分词器或 ONNX 会话初始化失败。
  • 排查:
    • 查看应用日志中的具体异常信息。
    • 确认模型文件完整且可读。
    • 确认 JVM 权限和 native 库加载正常。

内存不足

  • 表现:进程 OOM 或堆外内存溢出。
  • 原因:模型权重常驻堆外内存,加上 JVM 堆、其他组件内存。
  • 排查:
    • 评估服务器物理内存是否足够。
    • 避免同时运行多个 embedding 实例。
    • 控制批量大小和文本长度。

章节来源

  • OnnxEmbeddingEngine.java:41-120
  • OnnxEmbeddingEngine.java:201-299
  • EmbeddingService.java:201-244

结论

嵌入调试接口是一个面向本地 ONNX embedding 模型的轻量验证工具。它通过 EmbeddingDebugController.debug 暴露 /embedding/debug,借助 EmbeddingService 和 OnnxEmbeddingEngine 完成文本向量化、维度校验、L2 归一化和余弦相似度计算。其核心价值在于帮助运维和研发人员快速确认本地 bge-m3 模型是否可加载、能否输出 1024 维向量、是否具备基本语义区分能力。

使用该接口时,应重点关注:

  • 模型目录结构和文件完整性。
  • zsjz.embedding.enabled、model-path、dimensions 配置一致性。
  • 首次调用时的懒加载延迟。
  • 批量大小、文本长度和 CPU 资源。
  • similarity 矩阵的对角线和语义相近文本的相似度趋势。

该接口不应被视为生产业务路由的一部分;业务向量能力仍应通过 EmbeddingProvider 统一管理本地与在线 embedding 模型。