数据库模型目录、平台接入与自定义模型 ID

Java MaxKB 将供应商、基础模型目录、凭据表单及参数表单存入 PostgreSQL。界面继续使用 MaxKB 的模型管理页，Java 后端适配原有接口，不为本次模型管理改动增加前端补丁。生成和模型发现复用 java-openai 的 UniChatClient。

数据结构

表	保存内容
`max_kb_model_provider`	平台 ID、名称、图标、默认 API 地址、协议、支持类型、凭据表单、参数表单、启用状态和排序
`max_kb_model_catalog`	平台 ID + 模型类型 + 模型 ID 的联合主键、描述、来源、启用状态、更新时间
`max_kb_model`	用户实际创建的模型、权限、所属用户、所选模型 ID、凭据及参数表单

平台目录不保存 API Key。用户模型凭据保存在模型实例中，详情接口只返回掩码；日志、补丁和文档不包含真实密钥。目录表的修改立即影响下次查询，无需重新打包 Java。

运行 scripts/Initialize-Database.ps1，会在原有迁移后执行 008-model-catalog.sql 与 009-model-catalog-snapshot.sql。前者创建数据表和平台，后者登记 2026-10-03 获取的目录快照；两者可重复执行，冲突时不覆盖已有管理配置。旧 JSON 文件不再作为运行时模型目录来源。已有模型实例和 ID 保留；两条默认 Gitee 模型被归入 Gitee 平台。

已配置的平台

平台	默认兼容 API 地址
OpenAI	`https://api.openai.com/v1`
Gitee AI	`https://ai.gitee.com/v1`
OpenRouter	`https://openrouter.ai/api/v1`
硅基流动	`https://api.siliconflow.cn/v1`
DeepSeek	`https://api.deepseek.com`
阿里云百炼	`https://dashscope.aliyuncs.com/compatible-mode/v1`
Kimi	`https://api.moonshot.cn/v1`
智谱 AI	`https://open.bigmodel.cn/api/paas/v4`
Gemini	`https://generativelanguage.googleapis.com/v1beta/openai`
火山方舟	`https://ark.cn-beijing.volces.com/api/v3`
OpenAI 兼容 / 自定义中转、New API / One API	用户填写自己的兼容地址

这里接入的是 OpenAI 兼容的 /chat/completions、/embeddings 接口。Claude 可以通过 OpenRouter 或其他兼容中转选择；这不表示已实现 Anthropic 原生接口、Bedrock 签名认证或所有厂商的图片、音频、工作流能力。平台地域、套餐与密钥必须对应；例如专属套餐不能直接使用普通付费接口地址。

当前导入 OpenRouter 的 378 个文本生成目录项，以及 Gitee 的 78 个候选文本生成、13 个候选向量目录项。OpenRouter 根据输出模态筛选，并排除批处理专用 ID。Gitee /models 不提供能力元数据，脚本只识别明确的文本模型系列和向量命名，排除 OCR、语音、重排等名称；最终以保存时的实际请求为准。其他平台没有可用密钥时不伪造“已实测可用”的模型列表，可手工输入模型 ID 或由管理员发现并登记目录。

在官方界面创建模型

打开“系统 → 模型 → 添加模型”，选择平台。
设置显示名称、私有或公有权限，选择模型类型。
在“基础模型”选择目录项，或输入完整模型 ID 后按回车。可以包含 /、:，例如中转平台给出的供应商前缀及别名；目录不是白名单。
填入对应平台 API 地址与自己的 API Key，保存。

保存时实际调用填写的模型 ID。聊天模型通过 UniChatClient.generate 校验；向量模型使用填写的 ID 发起 embeddings 请求并校验返回维度。保存成功表示该次校验通过，后续是否可用仍受平台额度、权限和模型状态影响。

编辑时保留掩码或留空 Key，沿用原密钥；如果更换 API 地址，必须重新填写新平台的 Key。除两条默认 Gitee 种子模型外，不会在用户模型缺少密钥时自动借用服务器的 Gitee Key。真实 Key 不会出现在模型详情返回值中。

目录接口

所有接口都需要登录。保持官方前端所需的 {code,message,data} 响应结构。

方法	路径	内容
GET	`/api/provider`	已启用平台
GET	`/api/provider/model_type_list?provider=...`	平台模型类型
GET	`/api/provider/model_list?provider=...&model_type=LLM`	数据库模型目录
GET	`/api/provider/model_form?provider=...&model_type=LLM&model_name=...`	凭据表单；自定义 ID 同样可用
GET	`/api/provider/model_params_form?provider=...&model_type=LLM&model_name=...`	平台参数表单
GET / PUT	`/api/model/{id}/model_params_form`	模型实例的参数表单
POST	`/api/provider/catalog/discover`	管理员调用兼容 `/models` 发现模型，不保存请求中的凭据
PUT	`/api/provider/catalog`	管理员登记或停用目录项

发现接口请求为 {"api_base":"https://平台地址/v1","api_key":"自己的密钥"}。返回平台公开给该 Key 的模型 ID；接口未携带完整能力信息时，由管理员明确指定模型类型后登记，不把所有 ID 当作聊天模型。

登记示例：

{
  "provider": "model_default_provider",
  "models": [
    {"name": "vendor/model-id", "model_type": "LLM", "desc": "本单位中转模型", "enabled": true}
  ]
}

同平台、类型及 ID 再次提交会更新原行。设置 enabled:false 隐藏目录项，不删除用户已经保存的模型。一次最多 5000 项，批量操作在事务内完成。普通用户不能修改共享目录。

对于 OpenRouter 和 Gitee，可运行已有同步脚本：

python scripts/Sync-ModelCatalog.py --source openrouter --token-file <管理员令牌文件>
# Gitee 还需在当前进程环境中设置 GITEE_API_KEY
python scripts/Sync-ModelCatalog.py --source gitee --token-file <管理员令牌文件>

脚本只登记本次获取到的候选项，不自动删除未返回的旧项。管理员应按平台下线公告将停用模型设为 enabled:false。令牌文件和密钥不提交到仓库。新增平台可以在数据库复制一行兼容平台配置，修改 provider、name、api_base 和凭据表单中的默认地址；名称和表单均来自数据表。

向量空间约束

当前数据库使用 1024 维向量。创建向量模型时请求 dimensions=1024 并检查返回长度和数值；不支持该维度的模型不能保存为可用实例。不同知识库可以选择不同的兼容向量模型，文档导入、分段新增/编辑及查询均采用所属知识库的模型。跨知识库查询先按模型分组生成查询向量，再合并检索结果。不同模型的相似度分布仍需结合测试集调整阈值。

已有文档的知识库不能直接切换向量模型；已被知识库引用的向量模型不能直接修改模型 ID、类型或 API 地址。需要更换向量空间时，新建模型和知识库，再重新导入文档。被应用或知识库引用的模型不能直接删除。

默认检索向量为 Gitee 的 Qwen3-Embedding-8B，默认生成模型为 deepseek-v4.1-flash。问题改写、证据核验和摘要等辅助步骤继续使用配置的 Gitee 模型；应用选择的新模型用于最终回答。OCR 继续按文档检测策略调用 PaddleOCR-VL-1.5。

验证与边界

本次完成本地协议测试（自定义 ID 原样传递、错误向量维度拒绝、密钥隔离）、真实 Gitee 创建与掩码编辑测试，以及官方 UI 模型目录、自定义 ID 和知识库追问验证。其他平台尚未提供真实 Key，因此不宣称全部平台模型都已完成真实推理测试。目录快照代表获取时的平台列表，不代表永久可用或统一计费。

平台接口说明：OpenRouter 模型目录、Gitee API、百炼 Base URL、Gemini OpenAI 兼容、DeepSeek 模型列表。