向量检索
基于 pgvector 的相似度检索，适合语义相近但用词不同的提问。
01 · 文档解析
先检测文档，再决定怎么解析
同一份 PDF 里可能既有文字层又有扫描页。MossKB 逐页判断，把能直接抽取的交给程序，把需要识别的交给 OCR。
| 文档情况 | 解析路径 |
|---|---|
| 文字型 PDF | 直接抽取文本与结构，不消耗 OCR 额度 |
| 本地结构化文件 | 按格式就地提取，保留标题与段落关系 |
| 扫描页 / 图片 | 交给远程 OCR 模型识别，默认 PaddleOCR-VL-1.5 |
| 混合 PDF | 逐页检测，逐页选择上面的路径 |
| 在线网页 | 抓取正文并清理导航、页脚等噪声节点 |
解析结果可校对
- 解析预览保留文件 ID，前端提交分段时必须带上它
- 自动拆分后的分段可以在界面里逐条检查、修改与删除
- 解析是异步任务，长文档不会卡住上传页面
- 向量化在分段确认后进行，向量维度与知识库选定的模型一致
向量维度必须与知识库创建时选择的模型一致：默认 Qwen3-Embedding-8B 返回 1024 维。已有文档的知识库不能直接切换向量空间，需要新建知识库并重新导入。
02 · 检索
向量、关键词与混合检索
三种检索模式在应用里可切换，底层的向量索引与全文索引都在同一套 PostgreSQL 里。
关键词检索
基于 pg_trgm 的文本匹配，适合编号、名称、专有名词必须命中的情况。
混合检索
两种结果融合排序，兼顾语义召回与字面命中，是默认推荐模式。
文档与查询使用知识库选定的同一个向量模型；模型权重不必在本机，指向兼容的远程 embeddings 服务即可，也支持替换为离线部署的向量模型。
03 · 迭代检索
一次提问，多轮找资料
普通 RAG 只检索一次，资料不足时模型只能硬答。MossKB 让同一次提问内部多走几轮。
- 检索：按问题先取一批片段
- 判断：由模型判断资料是否足以回答
- 补充检索：不足时改写检索词，再取一轮
- 最终回答：带引用片段作答，并保留整个过程
界面上能看到每一轮用到的检索词、新增片段数，以及仍然缺失的资料，排查「为什么答错了」不再靠猜。
04 · 上下文
历史超过预算才压缩
长会话要么丢信息，要么烧 token。MossKB 用一个明确阈值来决策。
- 读取当前会话最近的问答与摘要
- 只有 token 超过预算才触发压缩
- 超过对话轮数不会单独触发压缩，避免无谓的信息损失
- 界面显示已压缩轮数与保留的近期原文，可核对
05 · 模型管理
平台目录 + 自定义模型 ID
平台信息、候选模型目录与用户创建的模型实例分开存放，运行时不再读固定供应商配置文件，改目录不需要重新编译。
- 预置 OpenAI、Gitee、OpenRouter、硅基流动、DeepSeek、百炼、Kimi、智谱、Gemini 兼容接口、火山方舟与自定义中转入口
- 目录里没有的模型可以手动输入完整模型 ID，回车即用
- 保存校验使用实际填写的模型 ID，避免「填了不存在的模型」到运行时才报错
- 编辑时掩码 Key 保留原凭据；更换 API 地址必须重新填写该平台的 Key
- 管理员可通过接口发现候选模型并登记，停用项需要明确设置而不是自动消失
| 用途 | 默认模型 |
|---|---|
| 最终回答 / 改写 / 核验 / 摘要 | deepseek-v4.1-flash（Gitee 兼容接口） |
| 向量检索 | Qwen3-Embedding-8B，1024 维 |
| 扫描页与图片 OCR | PaddleOCR-VL-1.5（异步文档解析） |
06 · 多用户
账号级资源隔离
一个实例可以给多个团队用，但彼此看不到对方的资料。
- 管理员登录后在「系统 → 用户 → 创建用户」新增账号
- 普通账号拥有自己的应用、知识库与私有模型，按所属资源隔离
- 停用账号或重置密码会让旧令牌立刻失效
- 管理员保留全局管理权限，日常使用与配置分离
需要数据库与进程也完全独立时，应分别部署实例，而不是依赖账号隔离。
07 · 隔离 Python 执行器
用户代码从不以 Java 进程的身份运行
函数库里的代码需要真的执行，但不能因此把服务器交出去。执行器有两种实现，由配置选择，默认 Docker。
| runner | 适用环境 | 隔离方式 |
|---|---|---|
docker（默认） |
Windows 与 Linux；引擎可在本机，也可在局域网内已装 Docker 的主机 | 一次性容器：断网、只读根文件系统、非 root、内存 / CPU / pids 上限、tmpfs |
host |
Linux（含容器内部署），不需要 Docker | runuser 切到沙箱用户 + 独立目录 + 白名单环境变量；不断网、无只读根、无资源上限 |
两种 runner 的共同点
- 应用密钥不会进入用户代码
- 超时会连同子进程整棵树一起终止
- runner 不可用时明确拒绝执行，不回退到宿主机 Python
host runner 的现实限制
- java-mosskb 必须以 root 运行，否则无法切换用户
- 不提供断网与只读根文件系统
- 含密钥的配置文件应设置为仅属主可读
08 · 嵌入与开放 API
三种嵌入方式与一套接口
- 公开访问链接：启停、重置短令牌、设置访问次数、来源白名单与对话语言
- 浮窗脚本：第三方页面引入 script 后，右下角出现对话入口
- iframe：整页或局部嵌入，适合办公系统与移动端容器页
- 开放 API：业务系统直接调用，用于智能审核与智能决策
访客按公开访问链接上配置的当日次数限制提问，超出后由运营在后台调整。
iframe 嵌入片段
<iframe
src="https://cloud.mosskb.cn/ui/#/chat/<应用令牌>"
style="width:100%;height:100%;border:0"
allow="microphone">
</iframe>令牌与显示设置由应用概览维护，重置令牌后需要重新嵌入。
技术架构
请求链路
后端只负责编排与存储；模型权重、OCR 与向量都可以是远程服务，本机需要的只是 JDK、PostgreSQL 和可选的 Docker 客户端。
接入层
MossKB 前端Vue 3 + Vite，挂在 /ui/
浮窗脚本 / iframe第三方页面嵌入
业务系统直接调用 /api
/api 与 SSE
服务层（java-mosskb）
mosskb-webtio-boot HTTP 入口与鉴权
mosskb-business文档解析 / 检索 / 问答
JDBC · UniChatClient · HTTP
依赖服务
PostgreSQLpgvector + pg_trgm
兼容 OpenAI 的推理服务默认 deepseek-v4.1-flash
远程向量模型Qwen3-Embedding-8B，1024 维
远程 OCRPaddleOCR-VL-1.5
隔离 Python 执行器一次性容器 / runuser 沙箱
运行环境
部署与验证
Windows 与 Linux 提供同名脚本，数据库初始化脚本是幂等的，可以在已有数据库上重复执行。
| 依赖 | 说明 |
|---|---|
| JDK 21 | 后端运行环境 |
| Maven | 构建后端 |
| Node.js / npm | 构建前端 |
| PostgreSQL | 需要安装 pgvector 与 pg_trgm 扩展 |
| Docker（可选） | 仅隔离 Python 执行功能需要，不必装在本机 |
# 1. 初始化数据库（幂等，可重复执行）
.\scripts\Initialize-Database.ps1
# 2. 构建并启动后端与前端
.\scripts\Start-Local.ps1 -Build
# 3. 跑回归测试
mvn test
# 4. 部署后冒烟检查
.\scripts\Test-Deployment.ps1 -PostgresBin 'D:\Program Files\PostgreSQL\18\bin'Linux 与 WSL 使用 ./scripts/Initialize-Database.sh、./scripts/Start-Local.sh --build。前端默认在 http://localhost:3000/ui/，接口在 http://localhost:10060/api。
常见问题
上手前值得先知道的几件事
必须把模型部署在本机吗？
不必须。聊天模型、向量模型与 OCR 都可以指向远程服务，本机只需要 Java 运行时与 PostgreSQL。反过来，如果要求完全离线，也可以替换为自建的推理与向量服务，配置项与接口都留好了。
数据库已经有数据，还能升级吗？
可以。初始化脚本会建立扩展、业务表、索引与外键，并补齐旧库缺少的列，可以重复执行。需要清空重建时才加 -Reset，它会先删除业务表。升级前请先备份。
安装扩展时提示 extension "vector" is not available 怎么办？
这表示缺失的是扩展的二进制文件，而不是 SQL。需要在实际运行 PostgreSQL 的机器上安装 pgvector 的文件，再连接业务数据库启用扩展；只执行 SQL 无法安装缺失的二进制。
能换向量模型吗？
新建知识库时可以选。已有文档的知识库不能直接切换向量空间，因为维度与向量分布都变了，需要新建知识库并重新导入文档。默认向量模型返回 1024 维。
和上游 MaxKB 的关系是什么？
MossKB 是独立的 Java 实现，前端基于官方界面并保留必要定制。后端、数据库结构与接口都以 Java 技术栈重新实现，部署方式与运行依赖与上游不同，文档与部署脚本请看本项目仓库。
哪些能力还没有实现？
统计分析、向量库的其它替代方案、以及完整的工作流编排能力尚未全部实现；界面上有菜单或文档里有设计示例，都不代表已经可用。这一页只列已经跑通的功能。