知识与向量检索.md 32 KB

知识与向量检索

本文引用的文件

  • sql/knowledge_base.sql
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/controller/KnowledgeBaseController.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/service/KnowledgeBaseService.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/service/KnowledgeDocService.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeDocIndexer.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeDocParser.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/KnowledgeProperties.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/entity/KnowledgeBase.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/entity/KnowledgeDoc.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/entity/KnowledgeDocDownloadLog.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeVectorMapper.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/mapper/KnowledgeDocMapper.java
  • ai-server/src/main/java/com/zsjz/ai/module/knowledge/event/KnowledgeDocIndexEvent.java
  • ai-server/src/main/java/com/zsjz/ai/module/embedding/controller/EmbeddingDebugController.java
  • ai-server/src/main/java/com/zsjz/ai/module/embedding/service/EmbeddingService.java
  • ai-server/src/main/java/com/zsjz/ai/module/embedding/config/EmbeddingProperties.java
  • ai-server/src/main/java/com/zsjz/ai/module/agent/rag/EmbeddingProvider.java
  • ai-server/src/main/java/com/zsjz/ai/module/agent/tools/KnowledgeSearchTool.java
  • ai-electron/frontend/src/ai/api/knowledgeApi.ts
  • ai-electron/frontend/src/ai/views/aiKnowledge/index.vue
  • ai-electron/frontend/src/ai/components/KnowledgeDocModal.vue

目录

  1. 引言
  2. 项目结构
  3. 核心组件
  4. 架构总览
  5. 详细组件分析
  6. 依赖关系分析
  7. 性能与容量
  8. 运维与排障
  9. 结论
  10. 附录:接口与配置速查

引言

本模块为系统提供“知识库 + 文档管理 + pgvector 向量索引 + Agent/RAG 语义检索”的完整闭环。用户通过前端上传文档,后端使用 Tika 提取全文、按配置分块、调用嵌入模型生成向量,并写入 PostgreSQL 的 pgvector 列;Agent 在研判方案中绑定知识库后,可通过 search_knowledge 工具召回相关片段作为提示上下文。

该模块与以下能力解耦但协作:

  • 清洗模板与 AI 智能清洗:走独立的模板向量索引路径,不混入知识库表。
  • Agent Schema Catalog(表结构 RAG):由 RagSchemaSearchTool 和 RagSchemaService 维护 DuckDB 表结构的向量索引。
  • 本地/在线嵌入模型:统一通过 EmbeddingProvider 路由,本地模式使用 ONNX bge-m3,在线模式回退到模型管理中的 embedding 模型。

项目结构

知识库模块集中在 ai-server/src/main/java/com/zsjz/ai/module/knowledge,包含控制器、服务、实体、事件、解析器、索引器和 Mapper;向量推理位于 embedding 与 agent.rag 子模块;前端知识库页面位于 Electron 前端的 ai 视图与 API 层。

graph TB
    FE["前端<br/>aiKnowledge/index.vue<br/>KnowledgeDocModal.vue<br/>knowledgeApi.ts"] --> CTRL["KnowledgeBaseController"]
    CTRL --> KB_SVC["KnowledgeBaseService"]
    CTRL --> DOC_SVC["KnowledgeDocService"]
    DOC_SVC --> EVENT["KnowledgeDocIndexEvent"]
    EVENT --> INDEXER["KnowledgeDocIndexer"]
    INDEXER --> PARSER["KnowledgeDocParser"]
    INDEXER --> PROVIDER["EmbeddingProvider"]
    PROVIDER --> LOCAL["EmbeddingService<br/>bge-m3 ONNX"]
    PROVIDER --> ONLINE["在线 embedding 模型"]
    INDEXER --> VMAP["KnowledgeVectorMapper"]
    VMAP --> PG["PostgreSQL<br/>pgvector 表 kb_vec_{kbId}{tag}_d{dims}"]
    CTRL --> DB["knowledge_base / knowledge_doc / download_log"]

图表来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeBaseService.java:1-209
  • KnowledgeDocService.java:1-247
  • KnowledgeDocIndexer.java:1-359
  • KnowledgeDocParser.java:1-55
  • EmbeddingProvider.java:1-201
  • EmbeddingService.java:1-244
  • KnowledgeVectorMapper.java:1-64
  • knowledgeApi.ts:1-97
  • aiKnowledge/index.vue:1-120
  • KnowledgeDocModal.vue:1-120

章节来源

  • sql/knowledge_base.sql:1-70
  • KnowledgeBaseController.java:1-122

核心组件

组件 职责 关键行为
KnowledgeBaseController HTTP 入口 列出/创建/编辑/删除知识库;上传、下载、删除、重试文档;下载返回裸流。
KnowledgeBaseService 知识库生命周期 内置库只读、自建库归属校验;删除时级联清理文件、向量、下载记录并解绑方案。
KnowledgeDocService 文档业务逻辑 上传校验、Tika 提取、sidecar 落盘、PENDING→发布事件;下载审计;删除重索引。
KnowledgeDocParser 文本抽取 Tika AutoDetect 解析 PDF/Word/表格等,超限截断但不丢弃已解析内容。
KnowledgeDocIndexer 异步向量化与检索 单线程队列消费事件;分块、并发嵌入、幂等插入 pgvector;top-k 相似检索。
EmbeddingProvider 嵌入模型路由 本地 ONNX 与在线模型二选一;隔离表名 tag;维度校验与不可用降级。
EmbeddingService 本地嵌入实现 bge-m3 1024 维 L2 归一化向量;批量推理、余弦相似度、预热与维度校验。
KnowledgeVectorMapper pgvector SQL 动态建表、按 doc_id 去重插入、按 kbId 过滤检索、按 kb/doc 删除。
KnowledgeDocDownloadLog 下载审计 记录谁在何时下载了哪个文件名快照。
KnowledgeSearchTool Agent 工具 暴露 search_knowledge,封装知识库语义检索结果给 LLM。
前端知识库页面 可视化操作 展示内置/自建库、我的文档列表、状态标签、上传/下载/重试/删除。

章节来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeBaseService.java:1-209
  • KnowledgeDocService.java:1-247
  • KnowledgeDocIndexer.java:1-359
  • KnowledgeVectorMapper.java:1-64

架构总览

知识库流程分为两条线:数据面(上传、存储、审计)和索引面(解析、分块、嵌入、pgvector)。两者通过 Spring 事件解耦,避免上传请求被向量化耗时阻塞。

sequenceDiagram
    participant User as "用户"
    participant FE as "前端知识库页面"
    participant API as "KnowledgeBaseController"
    participant DocSvc as "KnowledgeDocService"
    participant Store as "LocalFileStorageUtil"
    participant Parser as "KnowledgeDocParser"
    participant Event as "KnowledgeDocIndexEvent"
    participant Indexer as "KnowledgeDocIndexer"
    participant Embed as "EmbeddingProvider"
    participant Pg as "pgvector 表"

    User->>FE: 选择文件并点击上传
    FE->>API: POST /knowledge-bases/{id}/docs
    API->>DocSvc: upload(userId, id, file)
    DocSvc->>Store: 保存原件 file_path
    DocSvc->>Parser: extract(file, maxChars)
    Parser-->>DocSvc: fullText
    DocSvc->>Store: 写入 sidecar .txt
    DocSvc->>DocSvc: 登记 knowledge_doc(PENDING)
    DocSvc->>Event: publish(docId)
    Event-->>Indexer: onDocIndexEvent(docId)
    Indexer->>Indexer: 读取 sidecar 或兜底重抽
    Indexer->>Embed: embed(chunk)
    Embed-->>Indexer: vector
    Indexer->>Pg: INSERT kb_vec_{kbId}{tag}_d{dims}
    Indexer->>DocSvc: UPDATE index_status=READY

图表来源

  • KnowledgeBaseController.java:60-122
  • KnowledgeDocService.java:70-150
  • KnowledgeDocParser.java:1-55
  • KnowledgeDocIndexEvent.java:1-59
  • KnowledgeDocIndexer.java:100-220
  • EmbeddingProvider.java:140-201

详细组件分析

知识库与文档实体设计

知识库采用两层隔离:

  • 知识库本体隔离:内置库全局可见可绑定,仅管理员维护;自建库仅创建者可见。
  • 文档层隔离:文档列表、下载、删除、重试仅对上传者开放;RAG 检索则基于绑定的知识库全量文档,不与文档清单隔离耦合。

    classDiagram
    class KnowledgeBase {
        +Long id
        +Long userId
        +Integer isBuiltin
        +String name
        +String description
        +isBuiltin() boolean
    }
    
    class KnowledgeDoc {
        +Long id
        +Long kbId
        +Long userId
        +String fileName
        +String filePath
        +String sidecarPath
        +String mime
        +Long sizeBytes
        +Integer charCount
        +Integer chunkCount
        +String indexStatus
        +String failReason
        +Integer downloadCount
    }
    
    class KnowledgeDocDownloadLog {
        +Long id
        +Long kbId
        +Long docId
        +Long userId
        +String fileName
        +LocalDateTime downloadTime
    }
    
    KnowledgeBase "1" -- "many" KnowledgeDoc : "包含"
    KnowledgeDoc "1" -- "many" KnowledgeDocDownloadLog : "被下载"
    

图表来源

  • KnowledgeBase.java:1-57
  • KnowledgeDoc.java:1-81
  • KnowledgeDocDownloadLog.java:1-45
  • sql/knowledge_base.sql:10-65

章节来源

  • KnowledgeBase.java:1-57
  • KnowledgeDoc.java:1-81
  • KnowledgeDocDownloadLog.java:1-45
  • sql/knowledge_base.sql:1-70

上传、解析与索引流水线

上传链路是同步的,但向量化是异步的:

  1. 校验知识库可见性与上传权限。
  2. 校验后缀白名单、文件大小、单用户文档数上限。
  3. 保存原件到 data/files/knowledge/{kbId}/doc/{uuid}.ext。
  4. 使用 Tika 提取全文,写入同名 .txt sidecar。
  5. 登记 knowledge_doc,初始状态 PENDING;提取失败记 FAILED。
  6. 发布 KnowledgeDocIndexEvent,索引器从单线程队列消费。
  7. 索引器加载全文(优先 sidecar,缺失时兜底重抽),分块、调用嵌入模型、写 pgvector。
  8. 成功置 READY 并更新 chunk_count;失败保留 fail_reason。

    flowchart TD
    Start(["上传开始"]) --> Validate["校验知识库与权限<br/>后缀/大小/数量上限"]
    Validate --> SaveOriginal["保存原件 file_path"]
    SaveOriginal --> Extract["Tika 提取全文"]
    Extract --> ExtractOk{"提取成功?"}
    ExtractOk -->|否| MarkFailed["标记 FAILED 并记录原因"]
    ExtractOk -->|是| WriteSidecar["写入 sidecar .txt"]
    WriteSidecar --> Register["登记 knowledge_doc<br/>status=PENDING"]
    Register --> Publish["发布索引事件"]
    MarkFailed --> End(["返回上传结果"])
    Publish --> Queue["单线程索引队列"]
    Queue --> LoadFull["加载全文<br/>sidecar 优先,否则兜底重抽"]
    LoadFull --> Chunk["分块<br/>size/overlap/maxChunks"]
    Chunk --> EmbedLoop["并发嵌入每个 chunk"]
    EmbedLoop --> InsertVec["INSERT pgvector<br/>ON CONFLICT DO NOTHING"]
    InsertVec --> BudgetCheck{"预算用尽?"}
    BudgetCheck -->|是| Truncated["记录 truncated 提示"]
    BudgetCheck -->|否| Done{"全部完成?"}
    Truncated --> Done
    Done --> Ready["UPDATE READY + chunk_count"]
    Ready --> End
    

图表来源

  • KnowledgeDocService.java:70-150
  • KnowledgeDocParser.java:1-55
  • KnowledgeDocIndexer.java:120-220
  • KnowledgeDocIndexEvent.java:1-59

章节来源

  • KnowledgeDocService.java:70-200
  • KnowledgeDocParser.java:1-55
  • KnowledgeDocIndexer.java:100-220
  • KnowledgeDocIndexEvent.java:1-59

向量存储与检索

向量存储在 PostgreSQL pgvector 表中,表名规则为:

  • kb_vec_{kbId}{tag}_d{dims}
  • tag 用于区分本地/在线模型:本地模式为 _bge_m3,在线模式为空串。
  • dims 为向量维度:默认 1024,兼容 1536 等。

每条向量记录包含:

  • doc_id:主键,形如 docId:chunkNo。
  • content:chunk 文本。
  • payload:JSONB,强制包含 kbId、docId、docName、chunkNo。
  • embedding:pgvector 向量列。

检索时先按 cosine 距离排序,再按 payload->>'kbId' 过滤,最后应用阈值与 topK。

sequenceDiagram
    participant Agent as "Agent"
    participant Tool as "KnowledgeSearchTool"
    participant Indexer as "KnowledgeDocIndexer"
    participant Embed as "EmbeddingProvider"
    participant Mapper as "KnowledgeVectorMapper"
    participant Pg as "pgvector 表"

    Agent->>Tool: search_knowledge(query, top_k)
    Tool->>Indexer: search(query, kbId)
    Indexer->>Embed: embed(query)
    Embed-->>Indexer: query_vector
    Indexer->>Mapper: searchInKb(table, vector, kbId, threshold, topK)
    Mapper->>Pg: SELECT ... WHERE payload->>'kbId'=kbId ORDER BY score DESC LIMIT topK
    Pg-->>Mapper: hits
    Mapper-->>Indexer: rows
    Indexer-->>Tool: SearchHit[]
    Tool-->>Agent: content/source/score

图表来源

  • KnowledgeSearchTool.java:1-66
  • KnowledgeDocIndexer.java:240-320
  • KnowledgeVectorMapper.java:30-64
  • EmbeddingProvider.java:140-201

章节来源

  • KnowledgeVectorMapper.java:1-64
  • KnowledgeDocIndexer.java:220-359
  • KnowledgeSearchTool.java:1-66

知识库、清洗模板与 Agent Schema Catalog 的关系

  • 知识库向量索引:面向用户上传的业务文档,表前缀 kb_vec_,检索工具 search_knowledge。
  • 清洗模板向量索引:面向 AI 智能清洗的模板元数据,独立于知识库,由 AiCleanTemplateVectorIndex 维护。
  • Agent Schema Catalog:面向 DuckDB 表结构的语义检索,由 RagSchemaService 和 RagSchemaSearchTool 提供 search_table_schema。
  • 三者共享 EmbeddingProvider 提供的嵌入能力,但数据源、表结构和检索工具互不干扰。

    graph LR
    KB["知识库文档<br/>kb_vec_*"] --> SEARCH_KB["search_knowledge"]
    CLEAN["清洗模板<br/>ai_clean_template_vector_index"] --> SEARCH_CLEAN["AI 智能清洗内部检索"]
    SCHEMA["DuckDB 表结构<br/>RagSchemaService"] --> SEARCH_SCHEMA["search_table_schema"]
    EMB["EmbeddingProvider<br/>本地/在线模型"] --> KB
    EMB --> CLEAN
    EMB --> SCHEMA
    

图表来源

  • KnowledgeSearchTool.java:1-66
  • RagSchemaSearchTool.java:1-52
  • EmbeddingProvider.java:1-201

章节来源

  • KnowledgeSearchTool.java:1-66
  • RagSchemaSearchTool.java:1-52
  • EmbeddingProvider.java:1-201

依赖关系分析

知识库模块依赖以下外部能力:

  • Spring 事务与事件:TransactionSynchronizationManager 保证 afterCommit 发布事件。
  • Sa-Token:StpUtil.getLoginIdAsLong() 获取当前用户。
  • MyBatis Plus:实体与基础 Mapper。
  • Apache Tika:多格式文本抽取。
  • PostgreSQL pgvector:向量列与余弦相似度算子 <=>。
  • ONNX Runtime:本地 bge-m3 嵌入推理。
  • AgentScope:Tool、ToolResultBlock、ToolResults 包装工具返回值。

    graph TB
    Controller["KnowledgeBaseController"] --> Service["KnowledgeBaseService / KnowledgeDocService"]
    Service --> Parser["KnowledgeDocParser"]
    Service --> Event["KnowledgeDocIndexEvent"]
    Event --> Indexer["KnowledgeDocIndexer"]
    Indexer --> Provider["EmbeddingProvider"]
    Provider --> Local["EmbeddingService"]
    Provider --> Online["在线 embedding 模型"]
    Indexer --> VectorMapper["KnowledgeVectorMapper"]
    VectorMapper --> PG["pgvector"]
    Controller --> SaToken["Sa-Token"]
    Service --> Storage["LocalFileStorageUtil"]
    

图表来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeDocIndexEvent.java:1-59
  • KnowledgeDocIndexer.java:1-359
  • EmbeddingProvider.java:1-201

章节来源

  • KnowledgeBaseController.java:1-122
  • KnowledgeDocIndexEvent.java:1-59
  • KnowledgeDocIndexer.java:1-359

性能与容量

向量维度

  • 默认本地模型为 bge-m3,输出 1024 维稠密向量,且已 L2 归一化。
  • 维度由 zsjz.embedding.dimensions 声明,实际推理时会校验一致性;不一致会报错,防止写坏 pgvector 表。
  • 删除向量时兼容 1024 与 1536 两种维度,以应对历史数据。

索引刷新策略

  • 索引不是实时刷新:上传后立即返回 PENDING,前端轮询状态。
  • 索引器使用单线程守护队列,避免多个文档同时打满嵌入模型。
  • 单个文档内的 chunk 嵌入使用虚拟线程并发,受 index-concurrency 闸门限制。
  • 每次重索引会先删除旧向量行,再重新插入,保证幂等。
  • 没有定时刷新的后台任务;刷新触发点为上传、重试。

文档去重

  • 向量插入使用 ON CONFLICT (doc_id) DO NOTHING,其中 doc_id = docId:chunkNo,天然防止同 chunk 重复插入。
  • 重索引前显式 DELETE FROM ... WHERE payload->>'docId' = docId,确保旧向量清空后再重建。
  • 文档本身没有唯一指纹去重:同一文件多次上传会生成多条 knowledge_doc 记录。

检索召回率调优

可调参数包括:

  • zsjz.knowledge.chunkSize:分块大小,太小碎片多,太大丢失局部语义。
  • zsjz.knowledge.chunkOverlap:重叠字符,提高边界连续性。
  • zsjz.knowledge.maxChunks:单文档最大块数,超出截断并标注。
  • zsjz.knowledge.scoreThreshold:cosine 相似度阈值,默认 0.3。
  • zsjz.knowledge.topK:默认返回 8 个片段。
  • 嵌入模型切换会影响向量空间,本地/在线模型必须分开建表。

性能注意事项

  • 本地嵌入首次加载约 2.3GB 权重,建议使用 eager-load=true 或手动预热。
  • 嵌入为 CPU 密集型任务,index-concurrency 不宜设置过高,避免内存与 CPU 争抢。
  • 大文档可能触发 index-budget-seconds 超时,剩余 chunk 会被跳过。
  • 向量检索使用 pgvector 的 <=> 算子,建议为常用知识库向量表建立合适的索引策略(例如 HNSW/IVFFlat,取决于部署环境)。
  • 下载使用裸流,前端必须带 x-token 请求头,否则会被鉴权拦截。

[本节为通用性能指导,未直接分析具体代码行]

运维与排障

常见问题与处理

现象 可能原因 处理建议
文档一直停留在 PENDING 事件未发布或索引队列异常 检查日志中“发布索引事件失败”;点击“重试索引”。
文档状态 FAILED 并带原因 Tika 提取失败或嵌入服务不可用 查看 fail_reason;确认 Tika 支持该文件类型;检查本地模型目录或在线 embedding 配置。
检索无结果 向量表不存在、维度不匹配、阈值过高 确认嵌入模型可用;检查 kb_vec_{kbId}{tag}_d{dims} 是否存在;降低 scoreThreshold。
本地模型报错维度不一致 zsjz.embedding.dimensions 与实际模型不符 修正配置并重建向量索引。
下载返回未登录 前端直链不带 token 前端必须使用 fetch 带 x-token,不要使用 <a href>。
删除知识库后仍有残留向量 模型开关切换导致表名不同 索引器删除逻辑已兼容本地/在线 tag 与双维度;若仍异常需人工清理对应表。

章节来源

  • KnowledgeDocService.java:150-247
  • KnowledgeDocIndexer.java:100-220
  • EmbeddingService.java:201-244
  • knowledgeApi.ts:60-97

调试嵌入模型

调试接口 /embedding/debug 用于验证本地嵌入模型是否正常工作:

  • 输入一组文本。
  • 返回向量数组、嵌入耗时、维度。
  • 返回两两余弦相似度矩阵,便于判断语义区分度。

使用步骤:

  1. 确保 zsjz.embedding.enabled=true 且模型目录存在。
  2. 调用 POST /embedding/debug,请求体为文本数组。
  3. 检查返回维度是否为 1024,对角线相似度接近 1,不同文本相似度较低。

章节来源

  • EmbeddingDebugController.java:1-62
  • EmbeddingService.java:1-200
  • EmbeddingProperties.java:1-58

示例:上传文档、查看索引状态、调试 embedding、相似检索

上传文档

  • 前端打开知识库卡片,点击“管理文档”,选择文件上传。
  • 后端返回 indexStatus=PENDING,前端每 3 秒轮询,直到 READY 或 FAILED。
  • 若失败,点击“重试索引”恢复。

查看索引状态

  • “我的上传文档”弹窗显示每个文档的状态标签:PENDING、INDEXING、READY、FAILED。
  • FAILED 时悬停可查看失败原因。
  • READY 时显示已向量化块数。

调试 embedding

  • 调用 /embedding/debug,传入若干测试句子。
  • 检查返回的 dimension、embedMillis、vectors、similarity。
  • 若维度不为 1024 或相似度矩阵异常,检查模型路径与配置。

进行相似检索

  • 当研判方案绑定了知识库,Agent 会自动注册 search_knowledge 工具。
  • Agent 根据问题自然语言调用该工具,返回片段内容、来源文档名与相似度。
  • 若知识库未绑定或嵌入不可用,工具返回空结果或错误信息。

章节来源

  • aiKnowledge/index.vue:1-120
  • KnowledgeDocModal.vue:1-120
  • knowledgeApi.ts:1-97
  • KnowledgeSearchTool.java:1-66

结论

知识库模块通过清晰的职责分层实现了文档管理、异步向量化和 Agent/RAG 检索的完整闭环。其核心优势在于:

  • 双层隔离:知识库可见性与文档上传者隔离,兼顾共享知识与管理安全。
  • 异步索引:上传不阻塞,索引失败可重试,状态透明。
  • 模型可插拔:本地 ONNX 与在线 embedding 模型统一路由,表名隔离避免向量空间污染。
  • Agent 友好:search_knowledge 工具让 LLM 能按需召回领域知识,减少幻觉。

在生产环境中,建议合理配置分块大小、重叠、阈值和并发度,并根据数据规模考虑 pgvector 索引策略;同时启用本地模型预热以降低首次检索延迟。

[本节为总结性内容,未直接分析具体代码行]

附录:接口与配置速查

知识库 API

方法 路径 说明 权限
GET /knowledge-bases 列出内置 + 我的知识库 已登录
POST /knowledge-bases 新建自建知识库 已登录
PUT /knowledge-bases/{id} 编辑知识库 自建库主人
DELETE /knowledge-bases/{id} 删除知识库 自建库主人
GET /knowledge-bases/{id}/docs 我的上传文档列表 知识库可见 + 上传者本人
POST /knowledge-bases/{id}/docs 上传文档 自建库主人或内置库管理员
DELETE /knowledge-bases/{id}/docs/{docId} 删除文档 上传者本人
POST /knowledge-bases/{id}/docs/{docId}/reindex 重试索引 上传者本人
GET /knowledge-bases/{id}/docs/{docId}/download 下载文档 上传者本人

章节来源

  • KnowledgeBaseController.java:30-122
  • knowledgeApi.ts:1-97

嵌入调试 API

方法 路径 请求体 响应字段
POST /embedding/debug 文本数组 dimension、embedMillis、vectors、similarity

章节来源

  • EmbeddingDebugController.java:1-62

关键配置项

配置键 默认值 说明
zsjz.knowledge.enabled true 是否启用知识库功能
zsjz.knowledge.maxFileMb 50 单文件大小上限
zsjz.knowledge.maxDocsPerUser 200 单用户单库文档上限
zsjz.knowledge.chunkSize 1000 分块字符数
zsjz.knowledge.chunkOverlap 100 分块重叠字符数
zsjz.knowledge.maxChunks 2000 单文档最大块数
zsjz.knowledge.indexBudgetSeconds 900 单文档索引预算秒数
zsjz.knowledge.indexConcurrency 8 嵌入并发闸门
zsjz.knowledge.topK 8 检索返回片段数
zsjz.knowledge.scoreThreshold 0.3 相似度阈值
zsjz.embedding.enabled true 本地嵌入开关
zsjz.embedding.modelPath bge-m3 本地模型目录
zsjz.embedding.dimensions 1024 向量维度
zsjz.embedding.batchSize 8 批量推理批次大小
zsjz.embedding.eagerLoad false 启动时预热模型

章节来源

  • KnowledgeProperties.java:1-65
  • EmbeddingProperties.java:1-58