模型管理
项目目标
本项目旨在构建一个功能完备的 RAG（Retrieval-Augmented Generation）系统，主要目标包括：
- 知识库管理：支持创建、更新和删除知识库，便于用户高效维护内容。
- 文档处理：包括文档的拆分、片段的向量化处理，以提升检索效率和准确性。
- 问答系统：提供高效的向量检索和实时生成回答的能力，支持复杂汇总类问题的处理。
- 系统优化：通过统计分析和推理问答调试，不断优化系统性能和用户体验。
系统核心概念
在 RAG 系统中，以下是几个核心概念：
- 应用：知识库的集合。每个应用可以自定义提示词，以满足不同的个性化需求。
- 知识库：由多个文档组成，便于用户对内容进行分类和管理。
- 文档：系统中对应的真实文档内容。
- 片段：文档经过拆分后的最小内容单元，用于更高效的处理和检索。
功能实现步骤
数据库设计 查看 01.md
设计并实现项目所需的数据表结构与数据库方案，为后续的数据操作打下坚实基础。用户登录 查看 02.md
实现了安全可靠的用户认证系统，保护用户数据并限制未经授权的访问。模型管理 查看 03.md
支持针对不同平台的模型（如 OpenAI、Google Gemini、Claude）进行管理与配置。知识库管理 查看 04.md
提供创建、更新及删除知识库的功能，方便用户维护与管理文档内容。文档拆分 查看 05.md
可将文档拆分为多个片段，便于后续向量化和检索操作。片段向量 查看 06.md
将文本片段进行向量化处理，以便进行语义相似度计算及高效检索。命中率测试 查看 07.md
通过语义相似度和 Top-N 算法，检索并返回与用户问题最相关的文档片段，用于评估检索的准确性。文档管理 查看 08.md
提供上传和管理文档的功能，上传后可自动拆分为片段便于进一步处理。片段管理 查看 09.md
允许对已拆分的片段进行增、删、改、查等操作，确保内容更新灵活可控。问题管理 查看 10.md
为片段指定相关问题，以提升检索时的准确性与关联度。应用管理 查看 11.md
提供创建和配置应用（智能体）的功能，并可关联指定模型和知识库。向量检索 查看 12.md
基于语义相似度，在知识库中高效检索与用户问题最匹配的片段。推理问答调试 查看 13.md
提供检索与问答性能的评估工具，帮助开发者进行系统优化与调试。对话问答 查看 14.md
为用户提供友好的人机交互界面，结合检索到的片段与用户问题实时生成回答。统计分析 查看 15.md
对用户的提问与系统回答进行数据化分析，并以可视化图表的形式呈现系统使用情况。用户管理 查看 16.md
提供多用户管理功能，包括用户的增删改查及权限控制。API 管理 查看 17.md
对外提供标准化 API，便于外部系统集成和调用本系统的功能。存储文件到 S3 查看 18.md
将用户上传的文件存储至 S3 等对象存储平台，提升文件管理的灵活性与可扩展性。文档解析优化 查看 19.md
介绍与对比常见的文档解析方案，并提供提升文档解析速度和准确性的优化建议。片段汇总 查看 20.md
对片段内容进行汇总，以提升总结类问题的查询与回答效率。文档多分块与检索 查看 21.md
将片段进一步拆分为句子并进行向量检索，提升检索的准确度与灵活度。多文档支持 查看 22.md
兼容多种文档格式，包括.doc,.docx,.xls,.xlsx,.ppt,.pptx等。对话日志 查看 23.md
记录并展示对话日志，用于后续分析和问题回溯。检索性能优化 查看 24.md
提供整库扫描和分区检索等多种方式，进一步提高检索速度和效率。Milvus 查看 25.md
将向量数据库切换至 Milvus，以在大规模向量检索场景中获得更佳的性能与可扩展性。文档解析方案和费用对比 查看 26.md
对比不同文档解析方案在成本、速度、稳定性等方面的差异，为用户提供更加经济高效的选择。爬取网页数据 查看 27.md
支持从网页中抓取所需内容，后续处理流程与本地文档一致：分段、向量化、存储与检索。
接口设计
本文将详细介绍 maxk-kb 系统中模型管理的实现，包括其接口设计、后端代码实现以及整体架构。通过这一介绍，您将了解如何通过 API 进行模型的添加、更新、查询和删除，以及后端如何处理这些请求。
tio-boot 提供了一系列 RESTful API，用于管理不同提供者的模型。这些接口涵盖了模型提供者的获取、模型类型和列表的查询、模型的增删改查等操作。以下将逐一介绍这些接口及其响应格式。
获取模型提供者列表
请求
GET http://192.168.3.8:3000/api/provider
响应
{
"code": 200,
"message": "成功",
"data": [
{
"provider": "model_azure_provider",
"name": "Azure OpenAI",
"icon": "<svg ...></svg>"
},
{
"provider": "model_wenxin_provider",
"name": "千帆大模型",
"icon": "<svg ...></svg>"
}
// 其他提供者
]
}
说明
该接口返回所有可用的模型提供者，包括提供者名称、标识符以及图标。
获取模型列表
根据不同的查询参数，模型列表的获取有所不同。
根据模型名称查询
请求
GET http://192.168.3.8:3000/api/model?name=<model_name>响应
{ "message": null, "data": [], "code": 200 }说明
通过指定模型名称查询模型，返回匹配的模型列表。
根据提供者查询
请求
GET http://192.168.3.8:3000/api/model?name=&provider=model_openai_provider响应
{ "message": null, "data": [], "code": 200 }说明
通过指定模型提供者查询模型，返回该提供者下的所有模型。
获取模型类型列表
请求
GET http://192.168.3.8:3000/api/provider/model_type_list?provider=model_openai_provider
响应
{
"message": "成功",
"data": [
{
"value": "LLM",
"key": "大语言模型"
},
{
"value": "EMBEDDING",
"key": "向量模型"
}
],
"code": 200
}
说明
该接口返回指定提供者支持的模型类型列表，如大语言模型（LLM）和向量模型（EMBEDDING）。
获取模型详情
请求
GET http://localhost:3000/api/model/442895624269676544
响应
{
"code": 200,
"message": "成功",
"data": {
"id": "111",
"provider": "model_openai_provider",
"name": "text-embbeding-3-large",
"model_type": "EMBEDDING",
"model_name": "text-embedding-ada-002",
"status": "SUCCESS",
"meta": {},
"credential": {
"api_base": "https://api.openai.com/v1",
"api_key": "sk-Mt7nR***************eaG9"
},
"permission_type": "PRIVATE"
}
}
说明
通过模型 ID 获取具体模型的详细信息，包括提供者、模型类型、名称、状态及凭证信息等。
添加模型
添加向量模型
请求
POST http://192.168.3.8:3000/api/model请求体
{ "name": "text-embedding-3-large", "model_type": "EMBEDDING", "model_name": "text-embedding-3-large", "permission_type": "PRIVATE", "credential": { "api_base": "https://api.openai.com/v1", "api_key": "xxxx" }, "provider": "model_openai_provider" }添加大语言模型
请求
POST http://localhost:3000/api/model请求体
{ "name": "gpt-4o-mini", "model_type": "LLM", "model_name": "gpt-4o-mini", "permission_type": "PRIVATE", "credential": { "api_base": "https://api.openai.com/v1", "api_key": "sk-xxx" }, "provider": "model_openai_provider" }
说明
通过 POST 请求可以添加新的模型，需提供模型名称、类型、具体名称、权限类型、凭证信息及所属提供者。
更新模型
请求
PUT http://localhost:3000/api/model/442895624269676544
请求体
{
"name": "text-embedding-3-larg",
"permission_type": "PRIVATE",
"model_type": "EMBEDDING",
"model_name": "text-embedding-3-large",
"credential": {
"api_base": "https://api.openai.com",
"api_key": "sk-M*******************************************eaG9"
}
}
说明
通过 PUT 请求更新指定 ID 的模型信息，包括名称、类型、权限及凭证信息。
删除模型
请求
DELETE http://localhost:3000/api/model/442895624269676544
说明
通过 DELETE 请求删除指定 ID 的模型。
后端代码实现
maxk-kb 的后端采用 Java 语言的 tio-boot 框架实现，主要包括控制器、服务层和数据访问层（DAO）。以下将详细解析各部分代码及其功能。
ApiProviderController 控制器
package com.litongjava.maxkb.controller;
import java.net.URL;
import java.util.ArrayList;
import java.util.List;
import com.jfinal.kit.Kv;
import com.litongjava.annotation.RequestPath;
import com.litongjava.maxkb.enumeration.ModelProvider;
import com.litongjava.model.result.ResultVo;
import com.litongjava.tio.boot.http.TioRequestContext;
import com.litongjava.tio.http.common.HttpResponse;
import com.litongjava.tio.utils.hutool.FileUtil;
import com.litongjava.tio.utils.hutool.ResourceUtil;
import lombok.extern.slf4j.Slf4j;
@RequestPath("/api/provider")
@Slf4j
public class ApiProviderController {
@RequestPath
public HttpResponse index() {
URL resource = ResourceUtil.getResource("json/api_provider.json");
StringBuilder jsonString = FileUtil.readURLAsString(resource);
HttpResponse response = TioRequestContext.getResponse();
response.setJson(jsonString.toString());
return response;
}
@RequestPath("/model_type_list")
public ResultVo model_type_list() {
List<Kv> kvs = new ArrayList<>();
kvs.add(Kv.by("key", "大语言模型").set("value", "LLM"));
kvs.add(Kv.by("key", "向量模型").set("value", "EMBEDDING"));
return ResultVo.ok("成功", kvs);
}
@RequestPath("/model_list")
public HttpResponse model_list(String provider, String model_type) {
model_type = model_type.toLowerCase();
String filename = provider + "_" + model_type + ".json";
log.info("filename:{}", filename);
URL resource = ResourceUtil.getResource("json/" + filename);
StringBuilder jsonString = FileUtil.readURLAsString(resource);
HttpResponse response = TioRequestContext.getResponse();
response.setJson(jsonString.toString());
return response;
}
public HttpResponse model_form(String provider, String model_type, String model_name) {
String filename = null;
if (ModelProvider.model_openai_provider.getName().equals(provider)) {
filename = provider + "_model_form.json";
}
log.info("filename:{}", filename);
URL resource = ResourceUtil.getResource("json/" + filename);
StringBuilder jsonString = FileUtil.readURLAsString(resource);
HttpResponse response = TioRequestContext.getResponse();
response.setJson(jsonString.toString());
return response;
}
}
功能说明
index方法：处理/api/provider的GET请求，读取api_provider.json文件，返回所有模型提供者的信息。model_type_list方法：处理/api/provider/model_type_list的GET请求，返回指定提供者支持的模型类型列表。model_list方法：处理/api/provider/model_list的GET请求，根据提供者和模型类型返回相应的模型列表。model_form方法：根据提供者、模型类型和模型名称返回模型表单配置，用于前端动态生成表单。
ApiModelController 控制器
package com.litongjava.maxkb.controller;
import com.litongjava.annotation.Delete;
import com.litongjava.annotation.EnableCORS;
import com.litongjava.annotation.Get;
import com.litongjava.annotation.Post;
import com.litongjava.annotation.Put;
import com.litongjava.annotation.RequestPath;
import com.litongjava.jfinal.aop.Aop;
import com.litongjava.maxkb.service.ModelService;
import com.litongjava.maxkb.vo.ModelVo;
import com.litongjava.model.result.ResultVo;
import com.litongjava.tio.boot.http.TioRequestContext;
import com.litongjava.tio.http.common.HttpRequest;
import com.litongjava.tio.utils.json.FastJson2Utils;
@RequestPath("/api/model")
@EnableCORS
public class ApiModelController {
ModelService modelService = Aop.get(ModelService.class);
@Get
public ResultVo index(HttpRequest request) {
String name = request.getParam("name");
return modelService.list(name);
}
@Post
public ResultVo save(HttpRequest request) {
Long userId = TioRequestContext.getUserIdLong();
String bodyString = request.getBodyString();
ModelVo modelVo = FastJson2Utils.parse(bodyString, ModelVo.class);
return modelService.save(userId, modelVo);
}
@Put("/{id}")
public ResultVo update(HttpRequest request, Long id) {
Long userId = TioRequestContext.getUserIdLong();
String bodyString = request.getBodyString();
ModelVo modelVo = FastJson2Utils.parse(bodyString, ModelVo.class);
modelVo.setId(id);
return modelService.save(userId, modelVo);
}
@Delete("/{id}")
public ResultVo delete(Long id) {
return modelService.delete(id);
}
@Get("/{id}")
public ResultVo get(Long id) {
return modelService.get(id);
}
}
功能说明
index方法：处理/api/model的GET请求，获取查询参数name并调用服务层方法返回模型列表。save方法：处理/api/model的POST请求，解析请求体中的模型信息，调用服务层保存模型。update方法：处理/api/model/{id}的PUT请求，更新指定 ID 的模型信息。delete方法：处理/api/model/{id}的DELETE请求，删除指定 ID 的模型。get方法：处理/api/model/{id}的GET请求，获取指定 ID 的模型详情。
ModelService 服务层
package com.litongjava.maxkb.service;
import java.io.IOException;
import java.util.ArrayList;
import java.util.List;
import org.postgresql.util.PGobject;
import com.jfinal.kit.Kv;
import com.litongjava.db.activerecord.Db;
import com.litongjava.db.activerecord.Row;
import com.litongjava.jfinal.aop.Aop;
import com.litongjava.kit.RecordUtils;
import com.litongjava.maxkb.constant.TableNames;
import com.litongjava.maxkb.dao.ModelDao;
import com.litongjava.maxkb.enumeration.ModelProvider;
import com.litongjava.maxkb.enumeration.ModelType;
import com.litongjava.maxkb.vo.CredentialVo;
import com.litongjava.maxkb.vo.ModelVo;
import com.litongjava.model.result.ResultVo;
import com.litongjava.openai.chat.ChatMessage;
import com.litongjava.openai.chat.OpenAiChatRequestVo;
import com.litongjava.openai.client.OpenAiClient;
import com.litongjava.openai.constants.OpenAiModels;
import com.litongjava.openai.embedding.EmbeddingRequestVo;
import com.litongjava.tio.utils.hutool.DataMaskingUtil;
import com.litongjava.tio.utils.json.JsonUtils;
import lombok.extern.slf4j.Slf4j;
import okhttp3.Response;
@Slf4j
public class ModelService {
/**
* 获取模型列表
*
* @param name 模型名称
* @return ResultVo
*/
public ResultVo list(String name) {
String[] jsonFields = new String[] { "meta" };
String sql = null;
if (name == null) {
sql = "select id,provider,name,model_type,model_name,status,meta,permission_type,user_id from %s";
sql = String.format(sql, TableNames.max_kb_model);
List<Row> list = Db.findWithJsonField(sql, jsonFields);
List<Kv> kvs = new ArrayList<>();
for (Row r : list) {
Kv kv = r.toKv();
kv.set("id", kv.get("id").toString());
kv.set("user_id", kv.get("user_id").toString());
PGobject meta = kv.getAs("meta");
if (meta == null || meta.isNull()) {
kv.set("meta", "{}");
} else {
kv.set("meta", JsonUtils.parseObject(meta.getValue()));
}
kvs.add(kv);
}
return ResultVo.ok(kvs);
}
sql = "select id,provider,name,model_type,model_name,status,meta,permission_type,user_id from %s where name=?";
sql = String.format(sql, TableNames.max_kb_model);
List<Row> list = Db.findWithJsonField(sql, jsonFields, name);
List<Kv> recordsToKv = RecordUtils.recordsToKv(list, false);
return ResultVo.ok(recordsToKv);
}
/**
* 保存或更新模型
*
* @param userId 用户ID
* @param modelVo 模型信息
* @return ResultVo
*/
public ResultVo save(Long userId, ModelVo modelVo) {
String name = modelVo.getName();
log.info("name:{}", name);
if (Db.exists(TableNames.max_kb_model, "name", name)) {
return ResultVo.fail(400, "模型名称【" + name + "】已存在");
}
String model_type = modelVo.getModel_type();
String provider = modelVo.getProvider();
if (ModelProvider.model_openai_provider.getName().equals(provider)) {
if (ModelType.EMBEDDING.getName().equals(model_type)) {
EmbeddingRequestVo embeddingRequestVo = new EmbeddingRequestVo();
embeddingRequestVo.input("Hi").model(OpenAiModels.text_embedding_3_small);
String api_base = modelVo.getCredential().getApi_base();
String api_key = modelVo.getCredential().getApi_key();
String bodyString = JsonUtils.toJson(embeddingRequestVo);
// 发送请求
try (Response response = OpenAiClient.embeddings(api_base, api_key, bodyString)) {
if (!response.isSuccessful()) {
// 获取响应内容
String string = response.body().string();
return ResultVo.fail(400, "校验失败,请检查参数是否正确:" + string);
}
} catch (IOException e) {
e.printStackTrace();
return ResultVo.fail(500, e.getMessage());
}
} else {
if (ModelType.LLM.getName().equals(model_type)) {
String api_base = modelVo.getCredential().getApi_base();
String api_key = modelVo.getCredential().getApi_key();
// 消息
List<ChatMessage> messages = new ArrayList<>();
ChatMessage message = new ChatMessage().role("user").content("hi");
messages.add(message);
OpenAiChatRequestVo openAiChatRequestVo = new OpenAiChatRequestVo();
openAiChatRequestVo.setStream(false);
openAiChatRequestVo.setModel(OpenAiModels.gpt_4o_mini);
openAiChatRequestVo.setMessages(messages);
String bodyString = JsonUtils.toJson(openAiChatRequestVo);
// 发送请求
try (Response response = OpenAiClient.chatCompletions(api_base, api_key, bodyString)) {
if (!response.isSuccessful()) {
// 获取响应内容
String string = response.body().string();
return ResultVo.fail(500, "校验失败,请检查参数是否正确:" + string);
}
} catch (IOException e) {
e.printStackTrace();
return ResultVo.fail(500, e.getMessage());
}
}
}
}
Aop.get(ModelDao.class).saveOrUpdate(userId, modelVo);
return ResultVo.ok();
}
/**
* 删除模型
*
* @param id 模型ID
* @return ResultVo
*/
public ResultVo delete(Long id) {
boolean ok = Aop.get(ModelDao.class).deleteById(id);
if (ok) {
return ResultVo.ok();
} else {
return ResultVo.fail();
}
}
/**
* 获取模型详情
*
* @param id 模型ID
* @return ResultVo
*/
public ResultVo get(Long id) {
Row row = Db.findById(TableNames.max_kb_model, id);
Object credential = row.getColumns().remove("credential");
Kv kv = row.toKv();
if (credential instanceof String) {
String credentialStr = (String) credential;
CredentialVo credentialVo = JsonUtils.parse(credentialStr, CredentialVo.class);
String api_key = credentialVo.getApi_key();
credentialVo.setApi_key(DataMaskingUtil.maskApiKey(api_key));
kv.set("credential", credentialVo);
}
return ResultVo.ok(kv);
}
}
功能说明
list方法：根据模型名称查询模型列表。如果未提供名称，则返回所有模型。查询结果包括模型的基本信息，如 ID、提供者、类型、名称等。save方法：保存或更新模型信息。在保存前，先验证模型名称是否已存在。对于 OpenAI 提供者的模型，根据模型类型（LLM 或 EMBEDDING）进行不同的校验，通过向 OpenAI 发送测试请求验证凭证的有效性。如果验证通过，则调用 DAO 层保存或更新模型信息。delete方法：删除指定 ID 的模型。get方法：获取指定 ID 的模型详情，返回模型的所有信息，并对敏感信息（如 API Key）进行脱敏处理。
ModelDao 数据访问层
package com.litongjava.maxkb.dao;
import java.util.Map;
import com.litongjava.db.activerecord.Db;
import com.litongjava.db.activerecord.Row;
import com.litongjava.maxkb.constant.TableNames;
import com.litongjava.maxkb.vo.ModelVo;
import com.litongjava.tio.utils.snowflake.SnowflakeIdUtils;
public class ModelDao {
/**
* 保存模型
*
* @param map 模型信息
*/
public void save(Map<String, Object> map) {
Db.save(TableNames.max_kb_model, Row.fromMap(map));
}
/**
* 根据ID删除模型
*
* @param id 模型ID
* @return 是否成功
*/
public boolean deleteById(Long id) {
return Db.deleteById(TableNames.max_kb_model, id);
}
/**
* 保存或更新模型
*
* @param userId 用户ID
* @param modelVo 模型信息
* @return 是否成功
*/
public boolean saveOrUpdate(Long userId, ModelVo modelVo) {
Row row = new Row();
row.set("name", modelVo.getName())
.set("model_type", modelVo.getModel_type())
.set("model_name", modelVo.getModel_name())
.set("permission_type", modelVo.getPermission_type())
.set("credential", modelVo.getCredential())
.set("user_id", userId)
.set("status", "SUCCESS");
String provider = modelVo.getProvider();
if (provider != null) {
row.set("provider", provider);
}
Long id = modelVo.getId();
if (id != null) {
row.set("id", id);
return Db.update(TableNames.max_kb_model, "id", row, new String[] { "credential" });
} else {
row.set("id", SnowflakeIdUtils.id());
return Db.save(TableNames.max_kb_model, row, new String[] { "credential" });
}
}
}
功能说明
save方法：保存新的模型记录。deleteById方法：根据模型 ID 删除模型记录。saveOrUpdate方法：根据是否存在 ID 决定是保存新模型还是更新现有模型。生成唯一 ID 使用 Snowflake 算法。
总结
通过本文的介绍，我们详细了解了 maxk-kb 系统中模型管理的实现，包括 API 接口设计和后端代码实现。系统通过清晰的 RESTful API 提供了模型的增删改查功能，后端采用分层架构，控制器负责处理请求，服务层处理业务逻辑，数据访问层负责与数据库交互。同时，通过与 OpenAI 等模型提供者的集成，确保了模型凭证的有效性和安全性。
这种模块化和层次化的设计不仅提高了系统的可维护性和扩展性，也为未来集成更多模型提供者和类型打下了坚实的基础。对于需要管理多种机器学习模型的系统，maxk-kb 的实现提供了一个优秀的参考范例。