Windows 部署 Java MaxKB 与远程模型

Java MaxKB 使用 tio-boot 提供 HTTP 接口，复用 MaxKB 的前端。PostgreSQL 保存业务数据与向量，Gitee 提供推理、向量和 OCR 服务。本地不需要加载大模型权重。

安装 pgvector

extension "vector" is not available 表示 PostgreSQL 服务端缺少扩展文件。只在客户端安装依赖、只执行 CREATE EXTENSION 都不能安装服务端二进制。

确认实际运行的 PostgreSQL 安装目录。执行 SELECT version(); SHOW data_directory;，并检查 Windows 服务的可执行文件路径。
安装 Visual Studio Build Tools 的 C++ 工具，打开 x64 Native Tools Command Prompt。
从 pgvector 官方仓库获取源码。将 PGROOT 指向正在运行的 PostgreSQL 安装目录；编译架构应与数据库一致。

set "PGROOT=D:\Program Files\PostgreSQL\<实际主版本目录>"
git clone https://github.com/pgvector/pgvector.git
cd pgvector
nmake /F Makefile.win
nmake /F Makefile.win install

安装后，目标 PostgreSQL 目录中应存在 lib/vector.dll、share/extension/vector.control 及相应 SQL 文件。然后连接业务数据库执行：

CREATE EXTENSION IF NOT EXISTS vector;
SELECT extname FROM pg_extension WHERE extname = 'vector';
SELECT '[1,2,3]'::vector;

扩展注册以数据库为单位。如果服务器在容器或远程机器中，应在实际运行数据库的环境安装。

本地配置

在 java-maxkb/maxkb-web/my.txt 中维护本地连接信息：

jdbc.url=jdbc:postgresql://127.0.0.1:5432/<实际数据库名>
jdbc.user=<数据库用户>
jdbc.pswd=<数据库密码>
app.admin.secret.key=<本机生成的随机签名密钥>
server.port=10060
app.env=dev
jdbc.showSql=false

每个配置占一行，文件末尾保留换行。数据库名使用连接配置中的实际值，不依赖项目名称。将以下配置放入相邻的 secrets.txt：

GITEE_API_KEY=<自己的密钥>

这两个文件应保持在 Git 忽略列表中，不把密钥复制到前端环境文件、SQL、截图或文档。

初始化数据库

项目提供可重复执行的脚本：

.\scripts\Initialize-Database.ps1 -PostgresBin 'D:\Program Files\PostgreSQL\<实际主版本目录>\bin'

脚本读取 my.txt 的连接参数，依次创建业务表，并执行模型、文件名容量、关键词检索、会话摘要、隔离执行器、用户令牌版本及数据库模型目录迁移。使用 CREATE ... IF NOT EXISTS 和幂等模型插入，不通过删除业务表来初始化。对已有旧结构，仍应先备份并按对应迁移脚本升级。

默认模型配置如下：

用途	模型	说明
推理	`deepseek-v4.1-flash`	通过 Gitee 的兼容接口生成流式回答
向量	`Qwen3-Embedding-8B`	远程生成 1024 维向量，文档和查询使用相同模型与维度
扫描文档 OCR	`PaddleOCR-VL-1.5`	通过异步文档解析接口处理扫描页

选择向量模型时兼顾中文文档检索与服务部署成本；本方案采用较大参数规模的远程模型，并使用 1024 维存储。模型质量仍应以自己的知识库测试集评估。模型 ID 和可用性以 Gitee 当前模型列表为准。

向量缓存同时包含模型标识、维度和内容摘要。更换向量模型或维度后，应重新生成已有文档的向量，不能混用不同向量空间。

构建与启动

前端目录使用原项目 MaxKB/ui，先在该目录执行 npm install。Java 项目根目录执行：

.\scripts\Start-Local.ps1 -Build

需要指定本地可执行文件时，传入 -JavaExecutable、-NodeExecutable、-MavenExecutable。Java 运行环境需要支持项目使用的语言特性。

默认前端地址为 http://localhost:3000/ui/，Java 后端端口为 10060。脚本在后台启动进程，后端日志位于 maxkb-web/logs，前端日志位于 MaxKB/ui/.local。修改代码后应停止相应旧进程、重新构建并启动。

初始管理员凭据沿用数据库设计章节的种子数据。用于正式环境前，应配置自己的身份认证和部署参数。

检索与多轮问答

前端提交确认后的分段时，应保留解析阶段返回的文件 id。后端先完成远程向量请求，再用事务保存文档与分段。只有成功提交后，文档状态才标为完成。

支持向量检索、关键词相似度检索和混合检索。向量检索使用余弦相似度；关键词检索使用 PostgreSQL 的文本片段相似度；混合检索将两类得分相加。已停用或已删除的文档和分段不参加检索。

多轮处理过程为：读取同一会话的持久摘要及近期问答，将省略主题的追问改写为独立检索问题。单次提问内执行“检索、证据核验、按缺口再次检索”的循环，然后把历史上下文、累计资料和当前问题交给推理模型。只有历史 token 超出预算才压缩。界面的历史轮数仅作为压缩后近期原文保留目标，不单独触发压缩。配置与接口见上下文压缩，隔离 Python 执行见隔离 Python 执行。

调试配置按会话保存，避免不同调试窗口互相覆盖。回答保存成功后才发出流结束事件，紧接着的追问可以读取上一轮回答。分享访客凭据限制在聊天相关接口，历史记录读取还会校验应用和会话归属。

原版 MaxKB 已包含历史对话与问题改写处理，Java 实现也支持这条多轮检索问答路径。这里的多轮检索不等同于任意工具调用或完整工作流执行。

模型目录已经改为数据库维护，平台接入及用户自定义模型 ID 见支持自定义模型。