mirror of
https://github.com/xinnan-tech/xiaozhi-esp32-server.git
synced 2026-07-22 07:03:53 +08:00
Merge branch 'main' into update-manager-mobile
This commit is contained in:
zhuoqinglian
@@ -0,0 +1,45 @@
|
||||
# 知识库模块全量集成测试报告
|
||||
|
||||
## 1. 测试背景
|
||||
针对 `KnowledgeBaseController` 和 `KnowledgeFilesController` 共 14 个接口进行了深度集成测试。主要解决了本地影子库与 RAGFlow 远程服务之间的状态对齐、数据反序列化兼容性以及批量操作逻辑安全性问题。
|
||||
|
||||
## 2. 修复的核心 Bug 清单 (Hotfixes)
|
||||
|
||||
| 模块 | 问题类型 | 修复方案 | 验证结果 |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **DTO** | `positions` 反序列化失败 | 类型从 `List<Integer>` 提升为 `Object`，支持嵌套数组 | ✅ 已验证 |
|
||||
| **DTO** | 日期格式不兼容 | 针对 RAGFlow 的 RFC 1123 格式，将 `Date` 改为 `String` 透传 | ✅ 已验证 |
|
||||
| **请求** | 检索参数 `null` 拒绝 | 增加 `@JsonInclude(NON_NULL)`，跳过可选字段的空值序列化 | ✅ 已验证 |
|
||||
| **同步** | 状态自愈死锁 | 增加 `CANCEL/FAIL` 状态的 60s 低频同步机制，防止逻辑错误锁定 | ✅ 已验证 |
|
||||
| **逻辑** | 删除守卫逻辑错误 | 将拦截条件从 `status="1"` 修正为 `run="RUNNING"` | ✅ 已验证 |
|
||||
|
||||
## 3. 全量接口测试统计
|
||||
|
||||
### KnowledgeBaseController (7/7)
|
||||
- [x] 分页查询 (`GET /datasets`)
|
||||
- [x] 详情获取 (`GET /datasets/{id}`)
|
||||
- [x] 创建知识库 (`POST /datasets`)
|
||||
- [x] 修改配置 (`PUT /datasets/{id}`)
|
||||
- [x] 物理删除 (`DELETE /datasets/{id}`)
|
||||
- [x] 批量删除 (`DELETE /datasets/batch`)
|
||||
- [x] 模型列表获取 (`GET /datasets/rag-models`)
|
||||
|
||||
### KnowledgeFilesController (7/7)
|
||||
- [x] 文档列表与同步 (`GET /datasets/{id}/documents`)
|
||||
- [x] 状态过滤查询 (`GET /datasets/{id}/documents/status/{s}`)
|
||||
- [x] 文档上传 (`POST /datasets/{id}/documents`)
|
||||
- [x] 触发解析 (`POST /datasets/{id}/chunks`)
|
||||
- [x] 切片详情 (`GET /datasets/{id}/documents/{docId}/chunks`)
|
||||
- [x] 召回测试 (`POST /datasets/{id}/retrieval-test`)
|
||||
- [x] 批量删除文档 (`DELETE /datasets/{id}/documents`)
|
||||
|
||||
## 4. 自动化审计结论
|
||||
通过执行 `comprehensive_audit.ps1` 自动化脚本，模拟了“创建->上传->解析->同步->检索->删除”的完整生产链路。
|
||||
- **解析成功率**：100%
|
||||
- **数据准确性**：DTO 转换无异常，坐标及得分提取正常
|
||||
- **系统安全性**：解析中拦截机制生效
|
||||
- **结论**：**准生产就绪 (Production Ready)**
|
||||
|
||||
---
|
||||
*报告生成时间：2026-02-13*
|
||||
*审核：dora--1206563805@qq.com*
|
||||
@@ -2,7 +2,9 @@ package xiaozhi.common.config;
|
||||
|
||||
import org.springframework.context.annotation.Bean;
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
import org.springframework.http.client.JdkClientHttpRequestFactory;
|
||||
import org.springframework.web.client.RestTemplate;
|
||||
import java.time.Duration;
|
||||
|
||||
/**
|
||||
* RestTemplate配置
|
||||
@@ -12,6 +14,8 @@ public class RestTemplateConfig {
|
||||
|
||||
@Bean
|
||||
public RestTemplate restTemplate() {
|
||||
return new RestTemplate();
|
||||
JdkClientHttpRequestFactory factory = new JdkClientHttpRequestFactory();
|
||||
factory.setReadTimeout(Duration.ofSeconds(30));
|
||||
return new RestTemplate(factory);
|
||||
}
|
||||
}
|
||||
@@ -79,6 +79,22 @@ public class SwaggerConfig {
|
||||
.build();
|
||||
}
|
||||
|
||||
@Bean
|
||||
public GroupedOpenApi knowledgeApi() {
|
||||
return GroupedOpenApi.builder()
|
||||
.group("knowledge")
|
||||
.pathsToMatch("/datasets/**")
|
||||
.build();
|
||||
}
|
||||
|
||||
@Bean
|
||||
public GroupedOpenApi botApi() {
|
||||
return GroupedOpenApi.builder()
|
||||
.group("bot")
|
||||
.pathsToMatch("/api/v1/**")
|
||||
.build();
|
||||
}
|
||||
|
||||
@Bean
|
||||
public OpenAPI customOpenAPI() {
|
||||
return new OpenAPI().info(new Info()
|
||||
|
||||
@@ -250,4 +250,5 @@ public interface ErrorCode {
|
||||
int AGENT_TAG_NAME_EMPTY = 10197; // 标签名称不能为空
|
||||
int AGENT_TAG_NOT_EXIST = 10198; // 标签不存在
|
||||
|
||||
int RAG_DOCUMENT_PARSING_DELETE_ERROR = 10199; // 文档解析中，禁止删除
|
||||
}
|
||||
|
||||
@@ -13,23 +13,25 @@ public class RenException extends RuntimeException {
|
||||
private String msg;
|
||||
|
||||
public RenException(int code) {
|
||||
super(MessageUtils.getMessage(code));
|
||||
this.code = code;
|
||||
this.msg = MessageUtils.getMessage(code);
|
||||
}
|
||||
|
||||
public RenException(int code, String... params) {
|
||||
super(MessageUtils.getMessage(code, params));
|
||||
this.code = code;
|
||||
this.msg = MessageUtils.getMessage(code, params);
|
||||
}
|
||||
|
||||
public RenException(int code, Throwable e) {
|
||||
super(e);
|
||||
super(MessageUtils.getMessage(code), e);
|
||||
this.code = code;
|
||||
this.msg = MessageUtils.getMessage(code);
|
||||
}
|
||||
|
||||
public RenException(int code, Throwable e, String... params) {
|
||||
super(e);
|
||||
super(MessageUtils.getMessage(code, params), e);
|
||||
this.code = code;
|
||||
this.msg = MessageUtils.getMessage(code, params);
|
||||
}
|
||||
|
||||
@@ -12,28 +12,29 @@ import xiaozhi.modules.sys.service.SysParamsService;
|
||||
* 封装了重复的SM2解密、验证码提取和验证逻辑
|
||||
*/
|
||||
public class Sm2DecryptUtil {
|
||||
|
||||
|
||||
/**
|
||||
* 验证码长度
|
||||
*/
|
||||
private static final int CAPTCHA_LENGTH = 5;
|
||||
|
||||
|
||||
/**
|
||||
* 解密SM2加密内容，提取验证码并验证
|
||||
*
|
||||
* @param encryptedPassword SM2加密的密码字符串
|
||||
* @param captchaId 验证码ID
|
||||
* @param captchaService 验证码服务
|
||||
* @param sysParamsService 系统参数服务
|
||||
* @param captchaId 验证码ID
|
||||
* @param captchaService 验证码服务
|
||||
* @param sysParamsService 系统参数服务
|
||||
* @return 解密后的实际密码
|
||||
*/
|
||||
public static String decryptAndValidateCaptcha(String encryptedPassword, String captchaId,
|
||||
CaptchaService captchaService, SysParamsService sysParamsService) {
|
||||
public static String decryptAndValidateCaptcha(String encryptedPassword, String captchaId,
|
||||
CaptchaService captchaService, SysParamsService sysParamsService) {
|
||||
// 获取SM2私钥
|
||||
String privateKeyStr = sysParamsService.getValue(Constant.SM2_PRIVATE_KEY, true);
|
||||
if (StringUtils.isBlank(privateKeyStr)) {
|
||||
throw new RenException(ErrorCode.SM2_KEY_NOT_CONFIGURED);
|
||||
}
|
||||
|
||||
|
||||
// 使用SM2私钥解密密码
|
||||
String decryptedContent;
|
||||
try {
|
||||
@@ -41,19 +42,20 @@ public class Sm2DecryptUtil {
|
||||
} catch (Exception e) {
|
||||
throw new RenException(ErrorCode.SM2_DECRYPT_ERROR);
|
||||
}
|
||||
|
||||
|
||||
// 分离验证码和密码：前5位是验证码，后面是密码
|
||||
if (decryptedContent.length() > CAPTCHA_LENGTH) {
|
||||
String embeddedCaptcha = decryptedContent.substring(0, CAPTCHA_LENGTH);
|
||||
String actualPassword = decryptedContent.substring(CAPTCHA_LENGTH);
|
||||
|
||||
// 验证嵌入的验证码是否正确
|
||||
|
||||
boolean embeddedCaptchaValid = captchaService.validate(captchaId, embeddedCaptcha, true);
|
||||
if (!embeddedCaptchaValid) {
|
||||
throw new RenException(ErrorCode.SMS_CAPTCHA_ERROR);
|
||||
}
|
||||
|
||||
|
||||
return actualPassword;
|
||||
} else if (decryptedContent.length() > 0) {
|
||||
throw new RenException(ErrorCode.SMS_CAPTCHA_ERROR);
|
||||
} else {
|
||||
throw new RenException(ErrorCode.SM2_DECRYPT_ERROR);
|
||||
}
|
||||
|
||||
+1
-1
@@ -66,7 +66,7 @@ public class OtaServiceImpl extends BaseServiceImpl<OtaDao, OtaEntity> implement
|
||||
// 同类固件只保留最新的一条
|
||||
List<OtaEntity> otaList = baseDao.selectList(queryWrapper);
|
||||
if (otaList != null && otaList.size() > 0) {
|
||||
OtaEntity otaBefore = otaList.getFirst();
|
||||
OtaEntity otaBefore = otaList.get(0);
|
||||
entity.setId(otaBefore.getId());
|
||||
baseDao.updateById(entity);
|
||||
return true;
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
package xiaozhi.modules.knowledge.config;
|
||||
|
||||
import org.springframework.context.annotation.Configuration;
|
||||
import org.springframework.scheduling.annotation.EnableScheduling;
|
||||
|
||||
/**
|
||||
* 知识库模块定时任务配置
|
||||
* 启用 Spring Schedule 能力
|
||||
*/
|
||||
@Configuration
|
||||
@EnableScheduling
|
||||
public class RAGTaskConfig {
|
||||
}
|
||||
+11
-5
@@ -26,6 +26,7 @@ import xiaozhi.common.utils.Result;
|
||||
import xiaozhi.common.utils.ToolUtil;
|
||||
import xiaozhi.modules.knowledge.dto.KnowledgeBaseDTO;
|
||||
import xiaozhi.modules.knowledge.service.KnowledgeBaseService;
|
||||
import xiaozhi.modules.knowledge.service.KnowledgeManagerService;
|
||||
import xiaozhi.modules.model.entity.ModelConfigEntity;
|
||||
import xiaozhi.modules.security.user.SecurityUser;
|
||||
|
||||
@@ -36,6 +37,7 @@ import xiaozhi.modules.security.user.SecurityUser;
|
||||
public class KnowledgeBaseController {
|
||||
|
||||
private final KnowledgeBaseService knowledgeBaseService;
|
||||
private final KnowledgeManagerService knowledgeManagerService;
|
||||
|
||||
@GetMapping
|
||||
@Operation(summary = "分页查询知识库列表")
|
||||
@@ -96,6 +98,8 @@ public class KnowledgeBaseController {
|
||||
throw new RenException(ErrorCode.NO_PERMISSION);
|
||||
}
|
||||
|
||||
// [FIX] 注入 ID，防止 Service 层找不到记录
|
||||
knowledgeBaseDTO.setId(existingKnowledgeBase.getId());
|
||||
knowledgeBaseDTO.setDatasetId(datasetId);
|
||||
KnowledgeBaseDTO resp = knowledgeBaseService.update(knowledgeBaseDTO);
|
||||
return new Result<KnowledgeBaseDTO>().ok(resp);
|
||||
@@ -117,7 +121,8 @@ public class KnowledgeBaseController {
|
||||
throw new RenException(ErrorCode.NO_PERMISSION);
|
||||
}
|
||||
|
||||
knowledgeBaseService.deleteByDatasetId(datasetId);
|
||||
// [Architecture Fix] 通过编排层级联删除，防止孤儿数据并解决循环依赖
|
||||
knowledgeManagerService.deleteDatasetWithFiles(datasetId);
|
||||
return new Result<>();
|
||||
}
|
||||
|
||||
@@ -133,15 +138,16 @@ public class KnowledgeBaseController {
|
||||
// 获取当前登录用户ID
|
||||
Long currentUserId = SecurityUser.getUserId();
|
||||
List<String> idList = Arrays.asList(ids.split(","));
|
||||
List<KnowledgeBaseDTO> knowledgeBaseDTOs = Optional.ofNullable(knowledgeBaseService.getByDatasetIdList(idList)).orElseGet(ArrayList::new);
|
||||
List<KnowledgeBaseDTO> knowledgeBaseDTOs = Optional.ofNullable(knowledgeBaseService.getByDatasetIdList(idList))
|
||||
.orElseGet(ArrayList::new);
|
||||
if (ToolUtil.isNotEmpty(knowledgeBaseDTOs)) {
|
||||
knowledgeBaseDTOs.forEach(item->{
|
||||
knowledgeBaseDTOs.forEach(item -> {
|
||||
// 检查权限：用户只能删除自己创建的知识库
|
||||
if (item.getCreator() == null || !item.getCreator().equals(currentUserId)) {
|
||||
throw new RenException(ErrorCode.NO_PERMISSION);
|
||||
}
|
||||
//删除
|
||||
knowledgeBaseService.deleteByDatasetId(item.getDatasetId());
|
||||
// [Architecture Fix] 通过编排层级联删除
|
||||
knowledgeManagerService.deleteDatasetWithFiles(item.getDatasetId());
|
||||
});
|
||||
}
|
||||
return new Result<>();
|
||||
|
||||
+59
-54
@@ -4,6 +4,7 @@ import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
import org.apache.shiro.authz.annotation.RequiresPermissions;
|
||||
import org.springdoc.core.annotations.ParameterObject;
|
||||
import org.springframework.web.bind.annotation.*;
|
||||
import org.springframework.web.multipart.MultipartFile;
|
||||
|
||||
@@ -11,7 +12,6 @@ import com.fasterxml.jackson.core.type.TypeReference;
|
||||
import com.fasterxml.jackson.databind.ObjectMapper;
|
||||
|
||||
import io.swagger.v3.oas.annotations.Operation;
|
||||
import io.swagger.v3.oas.annotations.Parameter;
|
||||
import io.swagger.v3.oas.annotations.tags.Tag;
|
||||
import lombok.AllArgsConstructor;
|
||||
import xiaozhi.common.exception.ErrorCode;
|
||||
@@ -20,6 +20,9 @@ import xiaozhi.common.page.PageData;
|
||||
import xiaozhi.common.utils.Result;
|
||||
import xiaozhi.modules.knowledge.dto.KnowledgeBaseDTO;
|
||||
import xiaozhi.modules.knowledge.dto.KnowledgeFilesDTO;
|
||||
import xiaozhi.modules.knowledge.dto.document.ChunkDTO;
|
||||
import xiaozhi.modules.knowledge.dto.document.DocumentDTO;
|
||||
import xiaozhi.modules.knowledge.dto.document.RetrievalDTO;
|
||||
import xiaozhi.modules.knowledge.service.KnowledgeBaseService;
|
||||
import xiaozhi.modules.knowledge.service.KnowledgeFilesService;
|
||||
import xiaozhi.modules.security.user.SecurityUser;
|
||||
@@ -57,13 +60,13 @@ public class KnowledgeFilesController {
|
||||
public Result<PageData<KnowledgeFilesDTO>> getPageList(
|
||||
@PathVariable("dataset_id") String datasetId,
|
||||
@RequestParam(required = false) String name,
|
||||
@RequestParam(required = false) Integer status,
|
||||
@RequestParam(required = false) String status,
|
||||
@RequestParam(required = false, defaultValue = "1") Integer page,
|
||||
@RequestParam(required = false, defaultValue = "10") Integer page_size) {
|
||||
// 验证知识库权限
|
||||
validateKnowledgeBasePermission(datasetId);
|
||||
|
||||
//组装参数
|
||||
// 组装参数
|
||||
KnowledgeFilesDTO knowledgeFilesDTO = new KnowledgeFilesDTO();
|
||||
knowledgeFilesDTO.setDatasetId(datasetId);
|
||||
knowledgeFilesDTO.setName(name);
|
||||
@@ -77,12 +80,12 @@ public class KnowledgeFilesController {
|
||||
@RequiresPermissions("sys:role:normal")
|
||||
public Result<PageData<KnowledgeFilesDTO>> getPageListByStatus(
|
||||
@PathVariable("dataset_id") String datasetId,
|
||||
@PathVariable("status") Integer status,
|
||||
@PathVariable("status") String status,
|
||||
@RequestParam(required = false, defaultValue = "1") Integer page,
|
||||
@RequestParam(required = false, defaultValue = "10") Integer page_size) {
|
||||
// 验证知识库权限
|
||||
validateKnowledgeBasePermission(datasetId);
|
||||
//组装参数
|
||||
// 组装参数
|
||||
KnowledgeFilesDTO knowledgeFilesDTO = new KnowledgeFilesDTO();
|
||||
knowledgeFilesDTO.setDatasetId(datasetId);
|
||||
knowledgeFilesDTO.setStatus(status);
|
||||
@@ -111,16 +114,29 @@ public class KnowledgeFilesController {
|
||||
return new Result<KnowledgeFilesDTO>().ok(resp);
|
||||
}
|
||||
|
||||
@DeleteMapping("/documents/{document_id}")
|
||||
@Operation(summary = "删除单个文档")
|
||||
@Parameter(name = "document_id", description = "文档ID", required = true)
|
||||
@DeleteMapping("/documents")
|
||||
@Operation(summary = "批量删除文档")
|
||||
@RequiresPermissions("sys:role:normal")
|
||||
public Result<Void> delete(@PathVariable("dataset_id") String datasetId,
|
||||
@RequestBody DocumentDTO.BatchIdReq req) {
|
||||
// 验证知识库权限
|
||||
validateKnowledgeBasePermission(datasetId);
|
||||
|
||||
knowledgeFilesService.deleteDocuments(datasetId, req);
|
||||
return new Result<>();
|
||||
}
|
||||
|
||||
@DeleteMapping("/documents/{document_id}")
|
||||
@Operation(summary = "删除单个文档")
|
||||
@RequiresPermissions("sys:role:normal")
|
||||
public Result<Void> deleteSingle(@PathVariable("dataset_id") String datasetId,
|
||||
@PathVariable("document_id") String documentId) {
|
||||
// 验证知识库权限
|
||||
validateKnowledgeBasePermission(datasetId);
|
||||
|
||||
knowledgeFilesService.deleteByDocumentId(documentId, datasetId);
|
||||
DocumentDTO.BatchIdReq req = new DocumentDTO.BatchIdReq();
|
||||
req.setIds(java.util.Collections.singletonList(documentId));
|
||||
knowledgeFilesService.deleteDocuments(datasetId, req);
|
||||
return new Result<>();
|
||||
}
|
||||
|
||||
@@ -148,64 +164,53 @@ public class KnowledgeFilesController {
|
||||
@GetMapping("/documents/{document_id}/chunks")
|
||||
@Operation(summary = "列出指定文档的切片")
|
||||
@RequiresPermissions("sys:role:normal")
|
||||
public Result<Map<String, Object>> listChunks(@PathVariable("dataset_id") String datasetId,
|
||||
public Result<ChunkDTO.ListVO> listChunks(
|
||||
@PathVariable("dataset_id") String datasetId,
|
||||
@PathVariable("document_id") String documentId,
|
||||
@RequestParam(required = false) String keywords,
|
||||
@RequestParam(required = false, defaultValue = "1") Integer page,
|
||||
@RequestParam(required = false, defaultValue = "1024") Integer page_size,
|
||||
@RequestParam(required = false) String id) {
|
||||
// 验证知识库权限
|
||||
@ParameterObject ChunkDTO.ListReq req) {
|
||||
|
||||
// 验证权限 (内部已包含知识库存在性校验与归属权校验)
|
||||
validateKnowledgeBasePermission(datasetId);
|
||||
|
||||
Map<String, Object> result = knowledgeFilesService.listChunks(datasetId, documentId, keywords, page, page_size, id);
|
||||
return new Result<Map<String, Object>>().ok(result);
|
||||
// 设置默认值
|
||||
if (req.getPage() == null)
|
||||
req.setPage(1);
|
||||
if (req.getPageSize() == null)
|
||||
req.setPageSize(50);
|
||||
|
||||
// 调用服务层获取强类型切片列表
|
||||
ChunkDTO.ListVO result = knowledgeFilesService.listChunks(datasetId, documentId, req);
|
||||
return new Result<ChunkDTO.ListVO>().ok(result);
|
||||
}
|
||||
|
||||
/**
|
||||
* 召回测试
|
||||
*/
|
||||
@PostMapping("/retrieval-test")
|
||||
@Operation(summary = "召回测试")
|
||||
@RequiresPermissions("sys:role:normal")
|
||||
public Result<Map<String, Object>> retrievalTest(@PathVariable("dataset_id") String datasetId,
|
||||
@RequestBody Map<String, Object> params) {
|
||||
public Result<RetrievalDTO.ResultVO> retrievalTest(
|
||||
@PathVariable("dataset_id") String datasetId,
|
||||
@RequestBody RetrievalDTO.TestReq req) {
|
||||
|
||||
// 验证知识库权限
|
||||
validateKnowledgeBasePermission(datasetId);
|
||||
|
||||
try {
|
||||
// 提取参数
|
||||
String question = (String) params.get("question");
|
||||
if (question == null || question.trim().isEmpty()) {
|
||||
return new Result<Map<String, Object>>().error("问题不能为空");
|
||||
}
|
||||
|
||||
List<String> datasetIds = (List<String>) params.get("dataset_ids");
|
||||
List<String> documentIds = (List<String>) params.get("document_ids");
|
||||
Integer page = (Integer) params.get("page");
|
||||
Integer pageSize = (Integer) params.get("page_size");
|
||||
Float similarityThreshold = (Float) params.get("similarity_threshold");
|
||||
Float vectorSimilarityWeight = (Float) params.get("vector_similarity_weight");
|
||||
Integer topK = (Integer) params.get("top_k");
|
||||
String rerankId = (String) params.get("rerank_id");
|
||||
Boolean keyword = (Boolean) params.get("keyword");
|
||||
Boolean highlight = (Boolean) params.get("highlight");
|
||||
List<String> crossLanguages = (List<String>) params.get("cross_languages");
|
||||
Map<String, Object> metadataCondition = (Map<String, Object>) params.get("metadata_condition");
|
||||
|
||||
// 如果未指定数据集ID，使用当前数据集
|
||||
if (datasetIds == null || datasetIds.isEmpty()) {
|
||||
datasetIds = java.util.Arrays.asList(datasetId);
|
||||
}
|
||||
|
||||
Map<String, Object> result = knowledgeFilesService.retrievalTest(
|
||||
question, datasetIds, documentIds, page, pageSize, similarityThreshold,
|
||||
vectorSimilarityWeight, topK, rerankId, keyword, highlight, crossLanguages, metadataCondition);
|
||||
|
||||
return new Result<Map<String, Object>>().ok(result);
|
||||
} catch (Exception e) {
|
||||
return new Result<Map<String, Object>>().error("召回测试失败: " + e.getMessage());
|
||||
// 业务下沉逻辑：如果未指定知识库ID，则设为当前路径中的 datasetId
|
||||
if (req.getDatasetIds() == null || req.getDatasetIds().isEmpty()) {
|
||||
req.setDatasetIds(java.util.Arrays.asList(datasetId));
|
||||
}
|
||||
|
||||
// [Reinforce] 强管控分页参数，防止 RAGFlow 端出现 Negative Slicing 报错
|
||||
if (req.getPage() == null || req.getPage() < 1) {
|
||||
req.setPage(1);
|
||||
}
|
||||
if (req.getPageSize() == null || req.getPageSize() < 1) {
|
||||
req.setPageSize(100);
|
||||
}
|
||||
|
||||
// 调用检索服务，返回强类型聚合对象
|
||||
RetrievalDTO.ResultVO result = knowledgeFilesService.retrievalTest(req);
|
||||
return new Result<RetrievalDTO.ResultVO>().ok(result);
|
||||
}
|
||||
|
||||
/**
|
||||
* 解析JSON字符串为Map对象
|
||||
*/
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
package xiaozhi.modules.knowledge.dao;
|
||||
|
||||
import org.apache.ibatis.annotations.Mapper;
|
||||
import xiaozhi.common.dao.BaseDao;
|
||||
import xiaozhi.modules.knowledge.entity.DocumentEntity;
|
||||
|
||||
/**
|
||||
* 文档 DAO
|
||||
*/
|
||||
@Mapper
|
||||
public interface DocumentDao extends BaseDao<DocumentEntity> {
|
||||
}
|
||||
@@ -19,4 +19,17 @@ public interface KnowledgeBaseDao extends BaseDao<KnowledgeBaseEntity> {
|
||||
*/
|
||||
void deletePluginMappingByKnowledgeBaseId(@Param("knowledgeBaseId") String knowledgeBaseId);
|
||||
|
||||
/**
|
||||
* 通用维度原子更新知识库统计信息
|
||||
*
|
||||
* @param datasetId 数据集ID
|
||||
* @param docDelta 文档数增量
|
||||
* @param chunkDelta 分块数增量
|
||||
* @param tokenDelta Token数增量
|
||||
*/
|
||||
void updateStatsAfterChange(@Param("datasetId") String datasetId,
|
||||
@Param("docDelta") Integer docDelta,
|
||||
@Param("chunkDelta") Long chunkDelta,
|
||||
@Param("tokenDelta") Long tokenDelta);
|
||||
|
||||
}
|
||||
@@ -0,0 +1,102 @@
|
||||
# RAGFlow API Interface Classification
|
||||
|
||||
## 1. External APIs (三方接入体系)
|
||||
**Path Prefix:** `/api/v1`
|
||||
**Authentication:** API Key (`@token_required`)
|
||||
**Primary Use:** External system integration, SDK usage.
|
||||
|
||||
| Interface Type | Python File Path | Class/Function Name | URL Pattern | Notes |
|
||||
|---|---|---|---|---|
|
||||
| **External** | `api/apps/sdk/session.py` | `agent_bot_completions` | `/api/v1/agentbots/<agent_id>/completions` | Agent Bot completion |
|
||||
| **External** | `api/apps/sdk/session.py` | `begin_inputs` | `/api/v1/agentbots/<agent_id>/inputs` | Get Agent Bot inputs |
|
||||
| **External** | `api/apps/sdk/agents.py` | `list_agents` | `/api/v1/agents` | List Agents |
|
||||
| **External** | `api/apps/sdk/agents.py` | `create_agent` | `/api/v1/agents` | Create Agent |
|
||||
| **External** | `api/apps/sdk/agents.py` | `update_agent` | `/api/v1/agents/<agent_id>` | Update Agent |
|
||||
| **External** | `api/apps/sdk/agents.py` | `delete_agent` | `/api/v1/agents/<agent_id>` | Delete Agent |
|
||||
| **External** | `api/apps/sdk/session.py` | `agent_completions` | `/api/v1/agents/<agent_id>/completions` | Agent completion |
|
||||
| **External** | `api/apps/sdk/session.py` | `create_agent_session` | `/api/v1/agents/<agent_id>/sessions` | Create Agent Session |
|
||||
| **External** | `api/apps/sdk/session.py` | `list_agent_session` | `/api/v1/agents/<agent_id>/sessions` | List Agent Sessions |
|
||||
| **External** | `api/apps/sdk/session.py` | `delete_agent_session` | `/api/v1/agents/<agent_id>/sessions` | Delete Agent Session |
|
||||
| **External** | `api/apps/sdk/session.py` | `agents_completion_openai_compatibility` | `/api/v1/agents_openai/<agent_id>/chat/completions` | OpenAI compatible Agent completion |
|
||||
| **External** | `api/apps/sdk/session.py` | `chatbot_completions` | `/api/v1/chatbots/<dialog_id>/completions` | Chatbot completion |
|
||||
| **External** | `api/apps/sdk/session.py` | `chatbots_inputs` | `/api/v1/chatbots/<dialog_id>/info` | Chatbot info |
|
||||
| **External** | `api/apps/sdk/chat.py` | `create` | `/api/v1/chats` | Create Chat |
|
||||
| **External** | `api/apps/sdk/chat.py` | `delete_chats` | `/api/v1/chats` | Delete Chat |
|
||||
| **External** | `api/apps/sdk/chat.py` | `list_chat` | `/api/v1/chats` | List Chats |
|
||||
| **External** | `api/apps/sdk/chat.py` | `update` | `/api/v1/chats/<chat_id>` | Update Chat |
|
||||
| **External** | `api/apps/sdk/session.py` | `chat_completion` | `/api/v1/chats/<chat_id>/completions` | Chat completion |
|
||||
| **External** | `api/apps/sdk/session.py` | `create` | `/api/v1/chats/<chat_id>/sessions` | Create Chat Session |
|
||||
| **External** | `api/apps/sdk/session.py` | `list_session` | `/api/v1/chats/<chat_id>/sessions` | List Chat Sessions |
|
||||
| **External** | `api/apps/sdk/session.py` | `delete` | `/api/v1/chats/<chat_id>/sessions` | Delete Chat Session |
|
||||
| **External** | `api/apps/sdk/session.py` | `update` | `/api/v1/chats/<chat_id>/sessions/<session_id>` | Update Chat Session |
|
||||
| **External** | `api/apps/sdk/session.py` | `chat_completion_openai_like` | `/api/v1/chats_openai/<chat_id>/chat/completions` | OpenAI compatible Chat completion |
|
||||
| **External** | `api/apps/sdk/dataset.py` | `create` | `/api/v1/datasets` | Create Dataset |
|
||||
| **External** | `api/apps/sdk/dataset.py` | `delete` | `/api/v1/datasets` | Delete Dataset |
|
||||
| **External** | `api/apps/sdk/dataset.py` | `list_datasets` | `/api/v1/datasets` | List Datasets |
|
||||
| **External** | `api/apps/sdk/dataset.py` | `update` | `/api/v1/datasets/<dataset_id>` | Update Dataset |
|
||||
| **External** | `api/apps/sdk/doc.py` | `parse` | `/api/v1/datasets/<dataset_id>/chunks` | Parse Document Chunks |
|
||||
| **External** | `api/apps/sdk/doc.py` | `stop_parsing` | `/api/v1/datasets/<dataset_id>/chunks` | Stop Parsing |
|
||||
| **External** | `api/apps/sdk/doc.py` | `upload` | `/api/v1/datasets/<dataset_id>/documents` | Upload Document |
|
||||
| **External** | `api/apps/sdk/doc.py` | `list_docs` | `/api/v1/datasets/<dataset_id>/documents` | List Documents |
|
||||
| **External** | `api/apps/sdk/doc.py` | `delete` | `/api/v1/datasets/<dataset_id>/documents` | Delete Document |
|
||||
| **External** | `api/apps/sdk/doc.py` | `update_doc` | `/api/v1/datasets/<dataset_id>/documents/<document_id>` | Update Document |
|
||||
| **External** | `api/apps/sdk/doc.py` | `download` | `/api/v1/datasets/<dataset_id>/documents/<document_id>` | Download Document |
|
||||
| **External** | `api/apps/sdk/doc.py` | `list_chunks` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks` | List Chunks |
|
||||
| **External** | `api/apps/sdk/doc.py` | `add_chunk` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks` | Add Chunk |
|
||||
| **External** | `api/apps/sdk/doc.py` | `update_chunk` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks/<chunk_id>` | Update Chunk |
|
||||
| **External** | `api/apps/sdk/dataset.py` | `knowledge_graph` | `/api/v1/datasets/<dataset_id>/knowledge_graph` | Knowledge Graph |
|
||||
| **External** | `api/apps/sdk/dataset.py` | `delete_knowledge_graph` | `/api/v1/datasets/<dataset_id>/knowledge_graph` | Delete Knowledge Graph |
|
||||
| **External** | `api/apps/sdk/doc.py` | `metadata_summary` | `/api/v1/datasets/<dataset_id>/metadata/summary` | Metadata Summary |
|
||||
| **External** | `api/apps/sdk/doc.py` | `metadata_batch_update` | `/api/v1/datasets/<dataset_id>/metadata/update` | Batch Update Metadata |
|
||||
| **External** | `api/apps/sdk/dataset.py` | `run_graphrag` | `/api/v1/datasets/<dataset_id>/run_graphrag` | Run GraphRAG |
|
||||
| **External** | `api/apps/sdk/dataset.py` | `run_raptor` | `/api/v1/datasets/<dataset_id>/run_raptor` | Run Raptor |
|
||||
| **External** | `api/apps/sdk/dataset.py` | `trace_graphrag` | `/api/v1/datasets/<dataset_id>/trace_graphrag` | Trace GraphRAG |
|
||||
| **External** | `api/apps/sdk/dataset.py` | `trace_raptor` | `/api/v1/datasets/<dataset_id>/trace_raptor` | Trace Raptor |
|
||||
| **External** | `api/apps/sdk/dify_retrieval.py` | `retrieval` | `/api/v1/dify/retrieval` | Dify Retrieval |
|
||||
| **External** | `api/apps/sdk/files.py` | `get_all_parent_folders` | `/api/v1/file/all_parent_folder` | Get All Parent Folders |
|
||||
| **External** | `api/apps/sdk/files.py` | `convert` | `/api/v1/file/convert` | File Convert |
|
||||
| **External** | `api/apps/sdk/files.py` | `create` | `/api/v1/file/create` | File Create |
|
||||
| **External** | `api/apps/sdk/files.py` | `download_attachment` | `/api/v1/file/download/<attachment_id>` | Download Attachment |
|
||||
| **External** | `api/apps/sdk/files.py` | `get` | `/api/v1/file/get/<file_id>` | Get File |
|
||||
| **External** | `api/apps/sdk/files.py` | `list_files` | `/api/v1/file/list` | List Files |
|
||||
| **External** | `api/apps/sdk/files.py` | `move` | `/api/v1/file/mv` | Move File |
|
||||
| **External** | `api/apps/sdk/files.py` | `get_parent_folder` | `/api/v1/file/parent_folder` | Get Parent Folder |
|
||||
| **External** | `api/apps/sdk/files.py` | `rename` | `/api/v1/file/rename` | Rename File |
|
||||
| **External** | `api/apps/sdk/files.py` | `rm` | `/api/v1/file/rm` | Remove File |
|
||||
| **External** | `api/apps/sdk/files.py` | `get_root_folder` | `/api/v1/file/root_folder` | Get Root Folder |
|
||||
| **External** | `api/apps/sdk/files.py` | `upload` | `/api/v1/file/upload` | Upload File |
|
||||
| **External** | `api/apps/sdk/doc.py` | `retrieval_test` | `/api/v1/retrieval` | Retrieval Test |
|
||||
| **External** | `api/apps/sdk/session.py` | `ask_about_embedded` | `/api/v1/searchbots/ask` | Searchbot Ask |
|
||||
| **External** | `api/apps/sdk/session.py` | `detail_share_embedded` | `/api/v1/searchbots/detail` | Searchbot Detail |
|
||||
| **External** | `api/apps/sdk/session.py` | `mindmap` | `/api/v1/searchbots/mindmap` | Searchbot Mindmap |
|
||||
| **External** | `api/apps/sdk/session.py` | `related_questions_embedded` | `/api/v1/searchbots/related_questions` | Searchbot Related Questions |
|
||||
| **External** | `api/apps/sdk/session.py` | `retrieval_test_embedded` | `/api/v1/searchbots/retrieval_test` | Searchbot Retrieval Test |
|
||||
| **External** | `api/apps/sdk/session.py` | `ask_about` | `/api/v1/sessions/ask` | Session Ask |
|
||||
| **External** | `api/apps/sdk/session.py` | `related_questions` | `/api/v1/sessions/related_questions` | Session Related Questions |
|
||||
| **External** | `api/apps/sdk/agents.py` | `webhook` | `/api/v1/webhook_test/<agent_id>` | Webhook Test |
|
||||
| **External** | `api/apps/sdk/agents.py` | `webhook_trace` | `/api/v1/webhook_trace/<agent_id>` | Webhook Trace |
|
||||
| **External** | `api/apps/sdk/doc.py` | `rm_chunk` | `/api/v1datasets/<dataset_id>/documents/<document_id>/chunks` | Remove Chunk |
|
||||
|
||||
|
||||
## 2. Internal APIs (内部前端体系)
|
||||
**Path Prefix:** `/v1/<app_name>` matches file `api/apps/<app_name>_app.py`
|
||||
**Authentication:** Session/Cookie (`@login_required`)
|
||||
**Primary Use:** RAGFlow Web Frontend.
|
||||
|
||||
**Selected Core Interfaces:**
|
||||
|
||||
| Interface Type | Python File Path | Class/Function Name | URL Pattern | Notes |
|
||||
|---|---|---|---|---|
|
||||
| Internal | `api/apps/user_app.py` | `login` | `/v1/user/login` | User Login (Frontend) |
|
||||
| Internal | `api/apps/user_app.py` | `log_out` | `/v1/user/logout` | User Logout |
|
||||
| Internal | `api/apps/user_app.py` | `user_add` | `/v1/user/register` | User Registration |
|
||||
| Internal | `api/apps/user_app.py` | `user_profile` | `/v1/user/info` | User Profile Info |
|
||||
| Internal | `api/apps/api_app.py` | `new_token` | `/v1/api/new_token` | Generate new API Token |
|
||||
| Internal | `api/apps/conversation_app.py` | `set_conversation` | `/v1/conversation/set` | Create/Update Conversation |
|
||||
| Internal | `api/apps/conversation_app.py` | `completion` | `/v1/conversation/completion` | Chat Conversation Completion |
|
||||
| Internal | `api/apps/kb_app.py` | `list_kbs` | `/v1/kb/list` | List Knowledge Bases |
|
||||
| Internal | `api/apps/kb_app.py` | `create` | `/v1/kb/create` | Create Knowledge Base |
|
||||
| Internal | `api/apps/document_app.py` | `upload` | `/v1/document/upload` | Upload Document to KB |
|
||||
| Internal | `api/apps/document_app.py` | `parse` | `/v1/document/parse` | Parse Document |
|
||||
|
||||
*(For a complete list of all 200+ internal APIs, please refer to the `api_endpoints.txt` file or the full scan results)*
|
||||
+279
@@ -0,0 +1,279 @@
|
||||
# RAGFlow Agent 与 Dify 兼容接口详解 (Agent & Dify Compatibility)
|
||||
|
||||
## 1. Dify 兼容检索 - `retrieval`
|
||||
**接口描述**: 模拟 Dify API 格式的知识库检索接口。此接口主要用于让现有的 Dify 客户端或系统能够方便地接入 RAGFlow 的知识库检索能力。它支持文本检索、混合检索以及通过元数据过滤文档。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/dify/retrieval`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| knowledge_id | string | 是 | - | **知识库 ID**。 |
|
||||
| query | string | 是 | - | **查询文本**。用户输入的检索问题。 |
|
||||
| use_kg | boolean | 否 | false | **使用知识图谱**。是否结合知识图谱进行检索。 |
|
||||
| retrieval_setting | object | 否 | {} | **检索配置**。包含相似度阈值和 Top-K。 |
|
||||
| metadata_condition | object | 否 | {} | **元数据过滤条件**。用于筛选特定文档。 |
|
||||
|
||||
#### 参数详情 (Detail Objects)
|
||||
**retrieval_setting**:
|
||||
```json
|
||||
{
|
||||
"score_threshold": 0.5, // 相似度阈值 (default: 0.0)
|
||||
"top_k": 5 // 返回数量 (default: 1024)
|
||||
}
|
||||
```
|
||||
|
||||
**metadata_condition**:
|
||||
```json
|
||||
{
|
||||
"logic": "and", // 逻辑关系 (and/or)
|
||||
"conditions": [
|
||||
{
|
||||
"name": "author", // 字段名
|
||||
"comparison_operator": "eq",// 运算符 (eq, ne, gt, lt 等)
|
||||
"value": "Alice" // 字段值
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"records": [
|
||||
{
|
||||
"content": "RAGFlow 是一个基于深度文档理解的检索增强生成引擎...",
|
||||
"score": 0.92,
|
||||
"title": "RAGFlow_Introduction.pdf",
|
||||
"metadata": {
|
||||
"doc_id": "doc_uuid_123",
|
||||
"author": "Alice",
|
||||
"publish_year": "2024"
|
||||
}
|
||||
},
|
||||
{
|
||||
"content": "DeepDOC 模型能够精准识别复杂的表格结构...",
|
||||
"score": 0.88,
|
||||
"title": "DeepDOC_Tech_Report.pdf",
|
||||
"metadata": {
|
||||
"doc_id": "doc_uuid_456",
|
||||
"author": "Bob"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 创建 Agent 会话 - `create_agent_session`
|
||||
**接口描述**: 创建一个新的 Agent 会话 (Session)。会话是用户与 Agent 交互的上下文容器，保存了历史对话记录和 DSL（领域特定语言）状态。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/agents/<agent_id>/sessions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | **Agent ID**。 |
|
||||
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| user_id | string | 否 | **用户标识**。用于区分不同终端用户的会话。若不传，默认为当前 Tenant ID。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "session_uuid_new_123",
|
||||
"agent_id": "agent_uuid_abc",
|
||||
"user_id": "user_123",
|
||||
"source": "agent",
|
||||
"dsl": { ... }, // 完整的 Agent DSL 定义
|
||||
"messages": [
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "你好！我是你的智能助手，有什么可以帮你的吗？" // Prologue (开场白)
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 获取 Agent 会话列表 - `list_agent_session`
|
||||
**接口描述**: 分页获取指定 Agent 下的会话列表。支持按 ID 或 User ID 过滤。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/agents/<agent_id>/sessions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | **Agent ID**。 |
|
||||
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| page | int | 否 | 1 | **页码**。 |
|
||||
| page_size | int | 否 | 30 | **每页数量**。 |
|
||||
| orderby | string | 否 | "update_time" | **排序字段**。 |
|
||||
| desc | boolean | 否 | true | **是否降序**。 |
|
||||
| id | string | 否 | - | **会话 ID**。精确筛选。 |
|
||||
| user_id | string | 否 | - | **用户标识**。筛选特定用户的会话。 |
|
||||
| dsl | boolean | 否 | true | **包含 DSL**。是否在返回结果中包含完整的 DSL 结构 (数据量较大)。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": [
|
||||
{
|
||||
"id": "session_uuid_123",
|
||||
"agent_id": "agent_uuid_abc",
|
||||
"user_id": "user_123",
|
||||
"create_time": 1715000000000,
|
||||
"update_time": 1715000050000,
|
||||
"source": "agent",
|
||||
"messages": [
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "Hi there!"
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "What is RAG?"
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 删除 Agent 会话 - `delete_agent_session`
|
||||
**接口描述**: 批量删除 Agent 会话。
|
||||
**请求方法**: `DELETE`
|
||||
**接口地址**: `/api/v1/agents/<agent_id>/sessions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | **Agent ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| ids | array<string> | 否 | **会话 ID 列表**。若不传该参数，将尝试删除(或清空)该 Agent 下的所有会话（需谨慎）。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"ids": ["session_id_1", "session_id_2"]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"success_count": 2,
|
||||
"errors": []
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Agent 对话 (流式) - `agent_completions`
|
||||
**接口描述**: 向 Agent 发送用户问题并获取回复。这是 Agent 交互的核心接口，支持 **Server-Sent Events (SSE)** 流式响应。Agent 会根据编排好的 DSL 流程执行（可能涉及多个节点、知识库检索、LLM 推理等），并实时推送执行过程和最终结果。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/agents/<agent_id>/completions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | **Agent ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| session_id | string | 是 | - | **会话 ID**。必须是 `create_agent_session` 返回的 ID。 |
|
||||
| question | string | 是 | - | **用户问题**。 |
|
||||
| stream | boolean | 否 | true | **是否流式响应**。强烈建议设为 `true` 以获得更好的用户体验。 |
|
||||
| return_trace | boolean | 否 | false | **返回执行轨迹**。如果为 `true`，流式响应中将包含各个节点的执行过程数据 (Trace)。 |
|
||||
|
||||
### 响应参数 (Stream Response)
|
||||
**Content-Type**: `text/event-stream`
|
||||
|
||||
响应是一个 SSE 流，每一行以 `data:` 开头，包含一个 JSON 对象。
|
||||
|
||||
**Event Types**:
|
||||
- `message`: 普通文本消息片段。
|
||||
- `node_finished`: (当 `return_trace=true` 时) 节点执行完成事件，包含节点输出数据。
|
||||
- `message_end`: 消息结束。
|
||||
- `[DONE]`: 流结束标志。
|
||||
|
||||
#### Stream Chunk Examples:
|
||||
|
||||
**1. 文本生成片段 (message)**:
|
||||
```text
|
||||
data:{"code": 0, "message": "success", "data": {"content": "Hello", "reference": {}, "id": "msg_uuid_1"}, "event": "message"}
|
||||
|
||||
data:{"code": 0, "message": "success", "data": {"content": " world", "reference": {}, "id": "msg_uuid_1"}, "event": "message"}
|
||||
```
|
||||
|
||||
**2. 节点执行轨迹 (node_finished, return_trace=true)**:
|
||||
```text
|
||||
data:{"code": 0, "message": "success", "data": {"component_id": "retrieval_node_1", "content": "...", "trace": [...]}, "event": "node_finished"}
|
||||
```
|
||||
|
||||
**3. 最终结束 (DONE)**:
|
||||
```text
|
||||
data:[DONE]
|
||||
```
|
||||
|
||||
#### Non-Stream Response (stream=false)
|
||||
如果不使用流式响应，将等待 Agent 全流程执行完毕后一次性返回 JSON。
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"content": "Hello world! This is the final answer.",
|
||||
"reference": {
|
||||
"chunk_id_1": { ... } // 引用来源
|
||||
},
|
||||
"trace": [ ... ] // 如果 return_trace=true
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,233 @@
|
||||
## 1. 获取 Agent 列表 - `list_agents`
|
||||
**接口描述**: 分页查询当前租户下的所有 Agent 列表，支持按 ID 或标题筛选。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/agents`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
无
|
||||
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| page | int | 否 | 1 | 页码 |
|
||||
| page_size | int | 否 | 30 | 每页条数 |
|
||||
| orderby | string | 否 | update_time | 排序字段 (create_time, update_time, title) |
|
||||
| desc | boolean | 否 | True | 是否降序排列 (True: 降序, False: 升序) |
|
||||
| id | string | 否 | - | 按 Agent ID 精确筛选 |
|
||||
| title | string | 否 | - | 按 Agent 标题精确筛选 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": [
|
||||
{
|
||||
"id": "e0d34e2c-...",
|
||||
"title": "My Assistant",
|
||||
"description": "A helpful AI assistant",
|
||||
"dsl": { ... }, // Agent 的 DSL 流程定义
|
||||
"user_id": "tenant_123",
|
||||
"avatar": "", // 头像 Base64 或 URL
|
||||
"canvas_category": "Agent",
|
||||
"create_time": 1715623400000,
|
||||
"update_time": 1715624500000
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 创建 Agent - `create_agent`
|
||||
**接口描述**: 创建一个新的 Agent，必须包含标题和 DSL 定义。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/agents`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
无
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| title | string | 是 | - | Agent 的名称 (必须唯一) |
|
||||
| dsl | object | 是 | - | Agent 的流程定义 (节点、连线配置) |
|
||||
| description | string | 否 | - | Agent 的功能描述 |
|
||||
| avatar | string | 否 | - | Agent 头像 (Base64 字符串或 URL) |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 更新 Agent - `update_agent`
|
||||
**接口描述**: 更新指定 Agent 的配置信息，支持增量更新（仅传递需要修改的字段）。
|
||||
**请求方法**: `PUT`
|
||||
**接口地址**: `/api/v1/agents/<agent_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | 要更新的 Agent ID |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| title | string | 否 | - | 新的 Agent 名称 |
|
||||
| dsl | object | 否 | - | 新的 DSL 流程定义 |
|
||||
| description | string | 否 | - | 新的功能描述 |
|
||||
| avatar | string | 否 | - | 新的头像 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 删除 Agent - `delete_agent`
|
||||
**接口描述**: 根据 ID 删除指定的 Agent。此操作不可恢复。
|
||||
**请求方法**: `DELETE`
|
||||
**接口地址**: `/api/v1/agents/<agent_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | 要删除的 Agent ID |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
无
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Webhook 测试触发 - `webhook`
|
||||
**接口描述**: 用于测试 Agent 的 Webhook 触发功能。该接口模拟外部系统调用，触发 Agent 按照配置的 "Begin" 节点逻辑开始执行。支持同步等待结果或流式返回（取决于 Agent 配置）。
|
||||
**请求方法**: `POST` (支持 GET/PUT/DELETE 等，取决于 Canvas 配置)
|
||||
**接口地址**: `/api/v1/webhook_test/<agent_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | Agent 的唯一标识符 |
|
||||
|
||||
#### Query / Headers / Body Parameters
|
||||
**说明**: 此接口的参数完全动态，取决于 Agent 画布中 **"Begin" (开始)** 节点的 **Webhook** 配置。
|
||||
- 如果配置了 Query 参数验证，则需在 URL 中传递对应参数。
|
||||
- 如果配置了 Header 验证，则需传递对应 Header。
|
||||
- **Body**: 通常为 JSON 格式，包含 Agent 运行所需的变量（inputs）或上下文数据。
|
||||
|
||||
**Body Example (JSON)**:
|
||||
```json
|
||||
{
|
||||
"inputs": {
|
||||
"topic": "AI Trends",
|
||||
"style": "professional"
|
||||
},
|
||||
"query": "Start generation"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json` (或 `text/event-stream`)
|
||||
|
||||
**即时响应模式 (Immediately)**:
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"data": {
|
||||
"content": "生成的回答内容...",
|
||||
"usage": { ... }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**流式响应模式 (SSE)**:
|
||||
如果不使用 `webhook_test` 而是生产环境 `webhook` 且配置为 SSE，则返回流式数据。但在 `webhook_test` 接口中，通常配合 `webhook_trace` 进行异步调试。
|
||||
|
||||
---
|
||||
|
||||
## 6. Webhook 执行轨迹查询 - `webhook_trace`
|
||||
**接口描述**: 轮询查询 Agent 在 Webhook 测试触发后的执行日志和中间状态。采用长轮询或游标机制，实时获取执行进度。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/webhook_trace/<agent_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | Agent 的唯一标识符 |
|
||||
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| since_ts | float | 否 | 当前时间 | 起始时间戳。返回此时间之后的日志事件。首次调用可不传（获取当前时间作为游标）。 |
|
||||
| webhook_id | string | 否 | - | Webhook 会话 ID。用于锁定特定的某次执行记录。首次轮询时不传，接口会返回新生成的 ID。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"webhook_id": "YWdlbnxxxx...", // 当前追踪的会话 ID (加密串)
|
||||
"finished": false, // 执行是否已结束 (true/false)
|
||||
"next_since_ts": 1715629999.5, // 下一次轮询应使用的 since_ts
|
||||
"events": [ // 本次轮询获取到的新事件列表
|
||||
{
|
||||
"ts": 1715629998.1,
|
||||
"event": "message", // 事件类型: message, start_to_think, finished, error 等
|
||||
"data": {
|
||||
"content": "思考中...",
|
||||
"reference": []
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 💡 最佳实践 (调试流程)
|
||||
1. **初始化**: 调用 `GET /webhook_trace/<id>` (不带参数)，获取 `next_since_ts` (记为 `T0`)。
|
||||
2. **触发**: 调用 `POST /webhook_test/<id>` 发送测试数据。
|
||||
3. **首帧捕获**: 循环调用 `GET /webhook_trace/<id>?since_ts=T0`，直到返回 `webhook_id` (记为 `WID`) 和第一批 `events`。
|
||||
4. **持续追踪**: 使用 `WID` 和响应中的 `next_since_ts` 持续轮询，直到 `data.finished == true`。
|
||||
+164
@@ -0,0 +1,164 @@
|
||||
# RAGFlow 对话交互接口详解 (Chat Completion & OpenAI Compatibility)
|
||||
|
||||
## 5. 对话助手对话 (流式) - `chat_completion`
|
||||
**接口描述**: 发送问题给对话助手 (Assistant/Chat) 并获取回复。这是 RAGFlow 最核心的原生对话接口，支持 **Server-Sent Events (SSE)** 流式响应。它会根据助手绑定的知识库进行 RAG 检索生成。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/chats/<chat_id>/completions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| chat_id | string | 是 | **助手 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| session_id | string | 是 | - | **会话 ID**。从 `create_chat_session` 获取。 |
|
||||
| question | string | 是 | - | **用户问题**。 |
|
||||
| stream | boolean | 否 | true | **是否流式响应**。 |
|
||||
| quote | boolean | 否 | false | **返回引用**。是否在响应中包含检索到的引用片段。 |
|
||||
| doc_ids | string | 否 | - | **限定文档 ID**。多个 ID 用逗号分隔，仅检索指定文档。 |
|
||||
| metadata_condition | object | 否 | {} | **元数据过滤**。用于限定检索范围。 |
|
||||
|
||||
### 响应参数 (Stream Response)
|
||||
**Content-Type**: `text/event-stream`
|
||||
|
||||
每一行数据以 `data:` 开头，包含一个 JSON 对象。
|
||||
|
||||
**Event Example**:
|
||||
```text
|
||||
data:{"code": 0, "message": "success", "data": {"answer": "Hello", "reference": {}}}
|
||||
|
||||
data:{"code": 0, "message": "success", "data": {"answer": " world!", "reference": {}}}
|
||||
|
||||
data:{"code": 0, "message": "success", "data": {"answer": "", "reference": {"chunk_1": {...}}}} // 引用数据
|
||||
```
|
||||
|
||||
### 响应参数 (Non-Stream Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"answer": "Hello world! This is the generated response.",
|
||||
"reference": {
|
||||
"chunk_id_1": {
|
||||
"content_with_weight": "Original text...",
|
||||
"doc_name": "manual.pdf"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. OpenAI 兼容对话 - `chat_completion_openai_like`
|
||||
**接口描述**: 提供与 **OpenAI API (`/v1/chat/completions`)** 完全兼容的接口。允许开发者使用 LangChain、OpenAI Python SDK 或其他支持 OpenAI 协议的工具直接调用 RAGFlow，实现无缝迁移。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/chats_openai/<chat_id>/chat/completions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| chat_id | string | 是 | **助手 ID**。在此上下文中充当 "Base URL" 的一部分。 |
|
||||
|
||||
#### Body Parameters (JSON - OpenAI Standard)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| messages | array | 是 | **消息列表**。包含 `role` (system/user/assistant) 和 `content`。 |
|
||||
| model | string | 是 | **模型名称**。可以是任意非空字符串 (RAGFlow 会使用助手预设的模型)。 |
|
||||
| stream | boolean | 否 | **是否流式**。默认为 `true`。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"model": "ragflow_default",
|
||||
"messages": [
|
||||
{"role": "system", "content": "You are a helpful assistant."},
|
||||
{"role": "user", "content": "Explain quantum physics."}
|
||||
],
|
||||
"stream": true
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Stream Response - OpenAI Format)
|
||||
**Content-Type**: `text/event-stream`
|
||||
|
||||
严格遵循 OpenAI Chunk 格式：
|
||||
|
||||
```text
|
||||
data: {"id": "chatcmpl-123", "object": "chat.completion.chunk", "created": 1715000000, "model": "model", "choices": [{"index": 0, "delta": {"role": "assistant", "content": ""}, "finish_reason": null}]}
|
||||
|
||||
data: {"id": "chatcmpl-123", "object": "chat.completion.chunk", "created": 1715000001, "model": "model", "choices": [{"index": 0, "delta": {"content": "Quantum"}, "finish_reason": null}]}
|
||||
|
||||
data: {"id": "chatcmpl-123", "object": "chat.completion.chunk", "created": 1715000002, "model": "model", "choices": [{"index": 0, "delta": {"content": " physics"}, "finish_reason": null}]}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 嵌入式 Chatbot 对话 - `chatbot_completions`
|
||||
**接口描述**: 专为 **嵌入式窗口 (Embed Window)** 设计的公开对话接口。它通常用于将 RAGFlow 助手作为客服窗口嵌入到第三方网站。与普通接口不同，它通过 `Authorization` Header 传递 **Beta Token** (即 API Key) 进行鉴权，且通常面向最终用户。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/chatbots/<dialog_id>/completions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dialog_id | string | 是 | **助手 ID** (Dialog ID)。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| question | string | 是 | - | **用户问题**。 |
|
||||
| stream | boolean | 否 | true | **是否流式**。 |
|
||||
| session_id | string | 否 | - | **会话 ID**。用于维持上下文。 |
|
||||
| quote | boolean | 否 | false | **返回引用**。 |
|
||||
|
||||
### 响应参数 (Stream Response)
|
||||
**Content-Type**: `text/event-stream`
|
||||
|
||||
与 `chat_completion` 类似，返回 RAGFlow 原生 SSE 格式。
|
||||
|
||||
```text
|
||||
data:{"code": 0, "message": "success", "data": {"answer": "Here is the answer...", "reference": {}}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. Chatbot 初始化信息 - `chatbots_inputs`
|
||||
**接口描述**: 获取嵌入式 Chatbot 的初始化配置信息。通常在前端组件加载时调用，用于展示助手的头像、名称、开场白 (Prologue) 等信息。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/chatbots/<dialog_id>/info`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dialog_id | string | 是 | **助手 ID**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"title": "IT Support Bot", // 助手名称
|
||||
"avatar": "http://...", // 头像 URL
|
||||
"prologue": "Hi! How can I help?" // 开场白
|
||||
}
|
||||
}
|
||||
```
|
||||
+208
@@ -0,0 +1,208 @@
|
||||
# RAGFlow 聊天助手会话管理接口详解 (Chat Assistant Session Management)
|
||||
|
||||
## 1. 创建会话 - `create_chat_session`
|
||||
**接口描述**: 为指定的聊天助手 (Chat/Assistant) 创建一个新的会话。系统会自动加载该助手的开场白 (Prologue) 作为第一条消息。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/chats/<chat_id>/sessions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| chat_id | string | 是 | **助手 ID** (Assistant/Dialog ID)。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| name | string | 否 | "New session" | **会话名称**。 |
|
||||
| user_id | string | 否 | - | **用户标识**。用于区分不同终端用户的会话。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"name": "Consulting regarding RAG",
|
||||
"user_id": "client_001"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "session_uuid_123",
|
||||
"chat_id": "chat_uuid_abc",
|
||||
"name": "Consulting regarding RAG",
|
||||
"user_id": "client_001",
|
||||
"create_time": 1715000000000,
|
||||
"create_date": "2024-05-01 10:00:00",
|
||||
"update_time": 1715000000000,
|
||||
"update_date": "2024-05-01 10:00:00",
|
||||
"messages": [
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "Hi! I am your AI assistant. How can I help you today?" // 自动加载的开场白
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取会话列表 - `list_chat_session`
|
||||
**接口描述**: 分页获取指定助手下的会话列表。支持按名称或用户 ID 过滤。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/chats/<chat_id>/sessions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| chat_id | string | 是 | **助手 ID**。 |
|
||||
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| page | int | 否 | 1 | **页码**。 |
|
||||
| page_size | int | 否 | 30 | **每页数量**。 |
|
||||
| orderby | string | 否 | "create_time" | **排序字段**。 |
|
||||
| desc | boolean | 否 | true | **是否降序**。 |
|
||||
| name | string | 否 | - | **会话名称搜索**。 |
|
||||
| id | string | 否 | - | **会话 ID 精确筛选**。 |
|
||||
| user_id | string | 否 | - | **用户标识筛选**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": [
|
||||
{
|
||||
"id": "session_uuid_123",
|
||||
"chat_id": "chat_uuid_abc",
|
||||
"name": "Consulting regarding RAG",
|
||||
"user_id": "client_001",
|
||||
"create_time": 1715000000000,
|
||||
"create_date": "2024-05-01 10:00:00",
|
||||
"update_time": 1715000050000,
|
||||
"update_date": "2024-05-01 10:00:50",
|
||||
"messages": [
|
||||
{
|
||||
"role": "assistant",
|
||||
"content": "Hi! I am your AI assistant. How can I help you today?"
|
||||
},
|
||||
{
|
||||
"role": "user",
|
||||
"content": "What is RAGFlow?"
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"id": "session_uuid_456",
|
||||
"chat_id": "chat_uuid_abc",
|
||||
"name": "New session",
|
||||
"user_id": "client_002",
|
||||
"create_time": 1714900000000,
|
||||
"create_date": "2024-04-30 09:00:00",
|
||||
"update_time": 1714900000000,
|
||||
"update_date": "2024-04-30 09:00:00",
|
||||
"messages": [ ... ]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 更新会话 - `update_chat_session`
|
||||
**接口描述**: 更新会话信息。目前主要用于 **重命名** 会话。注意：不能通过此接口修改消息记录 (`messages`)。
|
||||
**请求方法**: `PUT`
|
||||
**接口地址**: `/api/v1/chats/<chat_id>/sessions/<session_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| chat_id | string | 是 | **助手 ID**。 |
|
||||
| session_id | string | 是 | **会话 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| name | string | 否 | **新的会话名称**。不可为空字符串。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"name": "RAG Technical Discussion"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 删除会话 - `delete_chat_session`
|
||||
**接口描述**: 批量删除指定助手下的会话。
|
||||
**请求方法**: `DELETE`
|
||||
**接口地址**: `/api/v1/chats/<chat_id>/sessions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| chat_id | string | 是 | **助手 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| ids | array<string> | 否 | **待删除的会话 ID 列表**。若不传该参数，将尝试删除该助手下的**所有会话**（请极其谨慎使用）。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"ids": ["session_uuid_123", "session_uuid_456"]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": null // 若全部删除成功
|
||||
}
|
||||
```
|
||||
|
||||
**Response (部分成功时)**:
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "Partially deleted 1 sessions with 1 errors",
|
||||
"data": {
|
||||
"success_count": 1,
|
||||
"errors": ["The chat doesn't own the session session_uuid_999"]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,213 @@
|
||||
## 1. 创建助手应用 - `create`
|
||||
**接口描述**: 创建一个新的对话助手（Chat Assistant）。支持配置关联知识库、LLM 模型参数、提示词（Prompt）以及开场白等高级设置。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/chats`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
无
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| name | string | 是 | - | 助手应用名称 (租户内唯一) |
|
||||
| avatar | string | 否 | - | 助手头像 (URL 或 Base64 字符串) |
|
||||
| description | string | 否 | "A helpful Assistant" | 助手的功能描述 |
|
||||
| dataset_ids | array | 否 | [] | 关联的知识库 ID 列表 (必须是当前租户有权限访问的知识库) |
|
||||
| llm | object | 否 | - | LLM 模型生成配置 (如模型名称、温度等) |
|
||||
| prompt | object | 否 | - | 提示词引擎与检索配置 (包含 System Prompt, Opener, Rerank 等) |
|
||||
|
||||
**`llm` 对象详细结构**:
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| model_name | string | 是 | - | 模型名称 (例如: `deepseek-chat`, `gpt-4`, `qwen-turbo`) |
|
||||
| temperature | float | 否 | 0.1 | 温度系数 (0.0 ~ 1.0)，越高越随机，越低越确定 |
|
||||
| top_p | float | 否 | 0.3 | 核采样概率阈值 |
|
||||
| max_tokens | int | 否 | 512 | 单次回答的最大 Token 数限制 |
|
||||
| presence_penalty | float | 否 | 0.4 | 话题新鲜度惩罚 (-2.0 ~ 2.0)，正值鼓励讨论新话题 |
|
||||
| frequency_penalty | float | 否 | 0.7 | 频率惩罚 (-2.0 ~ 2.0)，正值减少重复词汇 |
|
||||
|
||||
**`prompt` 对象详细结构**:
|
||||
*注意：此对象包含“提示词配置”与“检索策略配置”两部分。*
|
||||
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| prompt | string | 否 | (内置默认提示词) | **System Prompt (系统提示词)**。给大模型的角色指令，例如 "你是一个客服..."。可使用变量占位符 `{knowledge}`。 |
|
||||
| opener | string | 否 | "Hi! I'm your assistant..." | **开场白**。用户进入对话窗口时，助手自动发送的第一条欢迎语。 |
|
||||
| show_quote | boolean | 否 | true | **显示引用**。回答中是否标注来源文档 (e.g., [1])。 |
|
||||
| variables | array | 否 | `[{"key": "knowledge", "optional": false}]` | **变量列表**。定义用于填充 System Prompt 的变量。`knowledge` 为保留变量，代表检索到的知识片段。 |
|
||||
| rerank_model | string | 否 | - | **重排序模型 ID**。配置后会对检索结果进行二次精排 (如 `BAAI/bge-reranker-v2-m3`)。 |
|
||||
| keywords_similarity_weight | float | 否 | 0.7 | **关键字权重** (0.0 ~ 1.0)。控制混合检索的比例。更接近 1.0 侧重关键字匹配，更接近 0.0 侧重向量语义匹配。 |
|
||||
| similarity_threshold | float | 否 | 0.2 | **相似度阈值** (0.0 ~ 1.0)。低于此相似度的文档块将被过滤，不喂给大模型。 |
|
||||
| top_n | int | 否 | 6 | **Top N**。最终截取并输入给大模型的文档块数量。 |
|
||||
| empty_response | string | 否 | "Sorry! No relevant..." | **空结果回复**。当没有检索到相关知识库内容时的兜底回复。 |
|
||||
| tts | boolean | 否 | false | **启用 TTS**。是否将助手的文本回答自动转为语音播放。 |
|
||||
| refine_multiturn | boolean | 否 | true | **多轮对话优化**。是否根据历史上下文重写用户问题 (Query Rewrite) 以提高检索准确率。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "e0d34e2c-1234-5678-9xxx-xxxxxxxxxxxx",
|
||||
"name": "企业知识库助手",
|
||||
"avatar": "http://example.com/avatar.png",
|
||||
"description": "用于回答员工内部问题的 AI",
|
||||
"dataset_ids": ["kb_123", "kb_456"],
|
||||
"llm": {
|
||||
"model_name": "deepseek-chat",
|
||||
"temperature": 0.1,
|
||||
"top_p": 0.3,
|
||||
"max_tokens": 512,
|
||||
"presence_penalty": 0.4,
|
||||
"frequency_penalty": 0.7
|
||||
},
|
||||
"prompt": {
|
||||
"prompt": "你是一个智能助手，请根据以下知识回答问题：\n{knowledge}",
|
||||
"opener": "你好！有什么可以帮你的？",
|
||||
"show_quote": true,
|
||||
"variables": [
|
||||
{ "key": "knowledge", "optional": false }
|
||||
],
|
||||
"rerank_model": "",
|
||||
"keywords_similarity_weight": 0.7,
|
||||
"similarity_threshold": 0.2,
|
||||
"top_n": 8,
|
||||
"empty_response": "抱歉，知识库中没有找到相关答案。",
|
||||
"tts": false,
|
||||
"refine_multiturn": true
|
||||
},
|
||||
"create_time": 1715623400000,
|
||||
"update_time": 1715624500000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取助手列表 - `list_chat`
|
||||
**接口描述**: 获取当前租户下的所有助手应用列表。支持分页、排序及按名称/ID筛选。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/chats`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
无
|
||||
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| page | int | 否 | 1 | 页码 |
|
||||
| page_size | int | 否 | 30 | 每页条数 |
|
||||
| orderby | string | 否 | create_time | 排序字段 (`create_time`, `update_time`) |
|
||||
| desc | boolean | 否 | true | 是否降序排列 (`true`: 降序, `false`: 升序) |
|
||||
| name | string | 否 | - | 按名称模糊搜索 (支持 partial match) |
|
||||
| id | string | 否 | - | 按 ID 精确筛选 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": [
|
||||
{
|
||||
"id": "e0d34e2c-...",
|
||||
"name": "客服机器人",
|
||||
"avatar": "http://...",
|
||||
"datasets": [
|
||||
{
|
||||
"id": "kb_1",
|
||||
"name": "产品手册",
|
||||
"avatar": "",
|
||||
"chunk_num": 100
|
||||
}
|
||||
],
|
||||
"llm": { ... }, // (结构同 create 接口响应)
|
||||
"prompt": { ... }, // (结构同 create 接口响应)
|
||||
"create_time": 1715623400000
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 更新助手配置 - `update`
|
||||
**接口描述**: 更新指定助手应用的配置信息。支持全量或增量更新部分字段。
|
||||
**请求方法**: `PUT`
|
||||
**接口地址**: `/api/v1/chats/<chat_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| chat_id | string | 是 | 助手应用 ID |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
*(以下所有字段均为可选，仅传递需要修改的字段即可)*
|
||||
|
||||
| 参数名 | 类型 | 默认值 | 说明 |
|
||||
|---|---|---|---|
|
||||
| name | string | - | 新的助手名称 |
|
||||
| avatar | string | - | 新的头像 URL 或 Base64 |
|
||||
| dataset_ids | array | - | **全量替换**关联的知识库 ID 列表 |
|
||||
| llm | object | - | 更新 LLM 配置。需包含 `model_name`，其他字段覆盖更新。 |
|
||||
| prompt | object | - | 更新提示词配置。支持增量更新 (e.g. 只改 `opener`)。 |
|
||||
| show_quotation | boolean | - | 是否显示引用来源 (此字段直接位于根对象下，对应 prompt.show_quote) |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 批量删除助手 - `delete_chats`
|
||||
**接口描述**: 批量删除一个或多个助手应用。
|
||||
**请求方法**: `DELETE`
|
||||
**接口地址**: `/api/v1/chats`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
无
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| ids | array<string> | 是 | 要删除的助手应用 ID 列表。**⚠️ 注意：若列表为空或不传，虽然后端有全量删除逻辑，但在实际业务中应严谨传递 ID。** |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"ids": ["chat_id_1001", "chat_id_1002"]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"success_count": 2, // 成功删除的数量
|
||||
"errors": [] // 失败原因列表 (如 ID 不存在)
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,420 @@
|
||||
## 1. 创建知识库 - `create`
|
||||
**接口描述**: 创建一个新的知识库（Dataset），用于存储和检索文档数据。支持配置嵌入模型（Embedding Model）、解析方法、权限范围等。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/datasets`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
无
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| name | string | 是 | - | **知识库名称**。在同一个租户（Tenant）内必须唯一。 |
|
||||
| avatar | string | 否 | "" | **知识库头像**。Base64 编码的图片字符串。 |
|
||||
| description | string | 否 | "" | **描述信息**。用于说明知识库的用途或内容概要。 |
|
||||
| embedding_model | string | 否 | (系统默认) | **嵌入模型名称** (例如 `BAAI/bge-large-zh-v1.5`)。若不传，则自动使用系统设置的默认 Embedding 模型。 |
|
||||
| permission | string | 否 | "me" | **可见权限**。`me`: 仅自己可见；`team`: 团队内所有成员可见。 |
|
||||
| chunk_method | string | 否 | "naive" | **默认分块解析方法**。当上传文件未指定解析方式时使用。可选值: `naive` (通用), `manual` (手动), `qa` (Q&A拆分), `table` (表格), `paper` (论文), `book` (书籍), `laws` (法律), `presentation` (PPT), `picture` (图片), `one` (单文档), `email` (邮件)。 |
|
||||
| parser_config | object | 否 | (见下文) | **解析器详细配置**。根据 `chunk_method` 的不同而变化。 |
|
||||
|
||||
**`parser_config` 默认配置参数 (Naive 通用模式)**:
|
||||
| 参数名 | 类型 | 默认值 | 说明 |
|
||||
|---|---|---|---|
|
||||
| chunk_token_num | int | 512 | **切片最大 Token 数**。超过该长度会被截断到下一块。 |
|
||||
| delimiter | string | "\\n" | **分段分隔符**。用于识别段落边界。 |
|
||||
| layout_recognize | string | "DeepDOC" | **布局识别模型**。用于处理复杂文档结构 (如 `DeepDOC` 或 `Simple`)。 |
|
||||
| html4excel | boolean | false | **Excel转HTML**。是否将 Excel 表格转为 HTML 格式进行解析。 |
|
||||
| auto_keywords | int | 0 | **自动关键词抽取**。0 表示不抽取；N>0 表示为每个切片抽取 N 个关键词。 |
|
||||
| auto_questions | int | 0 | **自动问题生成**。0 表示不生成；N>0 表示为每个切片生成 N 个相关问题。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "kb_uuid_12345678",
|
||||
"name": "企业产品手册",
|
||||
"avatar": "",
|
||||
"tenant_id": "tenant_001",
|
||||
"description": "存放所有产品相关的说明文档",
|
||||
"embedding_model": "BAAI/bge-large-zh-v1.5",
|
||||
"permission": "me",
|
||||
"chunk_method": "naive",
|
||||
"parser_config": {
|
||||
"chunk_token_num": 512,
|
||||
"delimiter": "\n",
|
||||
"layout_recognize": "DeepDOC",
|
||||
"html4excel": false,
|
||||
"auto_keywords": 0,
|
||||
"auto_questions": 0
|
||||
},
|
||||
"chunk_count": 0,
|
||||
"document_count": 0,
|
||||
"create_time": 1715623400000,
|
||||
"update_time": 1715624500000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 删除知识库 - `delete`
|
||||
**接口描述**: 批量删除一个或多个知识库。删除知识库将连带删除其中的所有文档和索引数据，**不可恢复**。
|
||||
**请求方法**: `DELETE`
|
||||
**接口地址**: `/api/v1/datasets`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
无
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| ids | array<string> | 是 | **ID 列表**。指定要删除的知识库 ID。如果传递 `null`，则会**清空当前租户下所有**知识库（高危操作，请谨慎使用）。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"ids": ["kb_id_101", "kb_id_102"]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "Successfully deleted 2 datasets, 0 failed...",
|
||||
"data": {
|
||||
"success_count": 2, // 成功删除的数量
|
||||
"errors": [] // 失败的 ID 及原因列表
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 获取知识库列表 - `list_datasets`
|
||||
**接口描述**: 获取当前用户（及团队）有权限访问的知识库列表。支持分页、排序和筛选。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/datasets`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
无
|
||||
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| page | int | 否 | 1 | **页码**。从 1 开始。 |
|
||||
| page_size | int | 否 | 30 | **每页条数**。 |
|
||||
| orderby | string | 否 | "create_time" | **排序字段**。可选值: `create_time` (创建时间), `update_time` (更新时间), `document_count` (文档数)。 |
|
||||
| desc | boolean | 否 | true | **是否降序**。`true`: 降序 (最新的在前); `false`: 升序。 |
|
||||
| name | string | 否 | - | **名称筛选**。支持模糊匹配。 |
|
||||
| id | string | 否 | - | **ID 筛选**。精确匹配知识库 ID。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": [
|
||||
{
|
||||
"id": "kb_uuid_123",
|
||||
"name": "HR 政策库",
|
||||
"document_count": 12, // 包含的文档数量
|
||||
"token_num": 10240, // 总 Token 数
|
||||
"chunk_count": 150, // 总切片数
|
||||
"create_time": 1715623400000,
|
||||
"permission": "team",
|
||||
"embedding_model": "BAAI/bge-large-zh-v1.5"
|
||||
}
|
||||
],
|
||||
"total": 1 // 匹配查询条件的总记录数 (用户分页计算)
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 更新知识库配置 - `update`
|
||||
**接口描述**: 更新指定知识库的配置信息。注意：如果知识库内已有解析过的切片，通常不允许修改嵌入模型 (`embedding_model`)。
|
||||
**请求方法**: `PUT`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | 知识库 ID |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
*(以下所有字段均为可选，仅传递需要修改的字段即可)*
|
||||
|
||||
| 参数名 | 类型 | 默认值 | 说明 |
|
||||
|---|---|---|---|
|
||||
| name | string | - | **新名称**。需保持租户内唯一。 |
|
||||
| avatar | string | - | **新头像**。Base64 字符串。 |
|
||||
| description | string | - | **新描述**。 |
|
||||
| permission | string | - | **新权限**。`me` 或 `team`。 |
|
||||
| embedding_model | string | - | **嵌入模型**。**注意**: 仅当知识库为空（chunk_count=0）时才允许修改。 |
|
||||
| chunk_method | string | - | **默认解析方法**。修改后将应用于后续新上传的文件 (旧文件解析方式不变)。 |
|
||||
| parser_config | object | - | **解析器配置**。全量覆盖旧配置 (结构参考 create 接口)。 |
|
||||
| pagerank | int | 0 | **PageRank 权重**。仅在使用 Elasticsearch 引擎且需调整图谱权重时设置。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "kb_uuid_...",
|
||||
"name": "新名称",
|
||||
"update_time": 1715629999000,
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 获取知识图谱数据 - `knowledge_graph`
|
||||
**接口描述**: 获取知识库构建的知识图谱数据，包含节点（Nodes）和边（Edges），用于前端可视化展示（如 ECharts 力导向图）。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/knowledge_graph`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | 知识库 ID |
|
||||
|
||||
#### Query Parameters
|
||||
无
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"graph": {
|
||||
"nodes": [
|
||||
{
|
||||
"id": "node_1",
|
||||
"label": "人工智能", // 节点显示的文本
|
||||
"pagerank": 0.05, // PageRank 权重 (决定节点大小)
|
||||
"color": "#fcb", // 节点颜色
|
||||
"img": "" // 节点图标 (如有)
|
||||
},
|
||||
{
|
||||
"id": "node_2",
|
||||
"label": "机器学习",
|
||||
"pagerank": 0.03,
|
||||
"color": "#e2b"
|
||||
}
|
||||
],
|
||||
"edges": [
|
||||
{
|
||||
"source": "node_1", // 起始节点 ID
|
||||
"target": "node_2", // 目标节点 ID
|
||||
"weight": 0.8, // 边权重 (决定连线粗细)
|
||||
"label": "includes" // 关系名称 (显示在连线上)
|
||||
}
|
||||
]
|
||||
},
|
||||
"mind_map": { // 思维导图结构的保留字段 (通常用于脑图展示)
|
||||
"root": {
|
||||
"id": "root_node",
|
||||
"children": [...]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 清空知识图谱数据 - `delete_knowledge_graph`
|
||||
**接口描述**: 删除指定知识库中已生成的知识图谱索引数据（包括所有实体节点和关系边）。
|
||||
**注意**: 此操作**不会**删除原始文档或普通的向量索引，仅仅是重置图谱结构。如果需要重新生成图谱，请再次调用 `chunk` 相关接口或使用 `run_graphrag`。
|
||||
**请求方法**: `DELETE`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/knowledge_graph`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | 知识库 ID |
|
||||
|
||||
#### Body Parameters
|
||||
无
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 运行/触发 GraphRAG 索引任务 - `run_graphrag`
|
||||
**接口描述**: 触发后台异步任务，对知识库中的文档进行 GraphRAG 索引构建。此过程会使用 LLM 抽取实体（Entities）和关系（Relationships），并构建全局社区摘要。
|
||||
**前提条件**: 知识库中必须包含已解析的文档。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/run_graphrag`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | 知识库 ID |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
*(Body 可为空 `{}`, 后续版本将扩展以下配置参数)*
|
||||
|
||||
| 参数名 | 类型 | 默认值 | 说明 |
|
||||
|---|---|---|---|
|
||||
| entity_types | array | ["organization", "person", "geo", "event"] | **(预留)** 指定要抽取的实体类型列表。 |
|
||||
| method | string | "light" | **(预留)** 构建模式: `light` (轻量级), `general` (标准), `complex` (深度)。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"graphrag_task_id": "task_uuid_12345678" // 异步任务 ID，用于后续追踪进度
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 运行/触发 RAPTOR 递归摘要任务 - `run_raptor`
|
||||
**接口描述**: 触发后台异步任务，对知识库中的文档运行 RAPTOR (Recursive Abstractive Processing for Tree-Organized Retrieval) 算法。
|
||||
**功能说明**: 该算法会递归地对文档块进行聚类和摘要，生成多层级的树状索引，显著提升对长文档和复杂问题的回答能力。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/run_raptor`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | 知识库 ID |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
*(Body 可为空 `{}`, 后续版本将扩展以下配置参数)*
|
||||
|
||||
| 参数名 | 类型 | 默认值 | 说明 |
|
||||
|---|---|---|---|
|
||||
| max_cluster | int | 64 | **(预留)** 最大聚类数。 |
|
||||
| prompt | string | (内置摘要提示词) | **(预留)** 用于生成摘要的 Prompt。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"raptor_task_id": "task_uuid_87654321" // 异步任务 ID
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 查询 GraphRAG 任务进度 - `trace_graphrag`
|
||||
**接口描述**: 查询指定知识库当前 **GraphRAG** 索引构建任务的实时状态。支持长轮询机制监测进度。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/trace_graphrag`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | 知识库 ID |
|
||||
|
||||
#### Query Parameters
|
||||
无
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "task_uuid_12345678", // 任务 ID
|
||||
"doc_id": "doc_uuid_...", // 当前正在处理的文档 ID (如果是多文档任务)
|
||||
"from_page": 0, // 当前处理的起始页码
|
||||
"to_page": 10, // 当前处理的结束页码
|
||||
"progress": 0.45, // **总进度** (0.0 ~ 1.0)。0.0: 未开始/刚开始; 1.0: 完成; -1.0: 失败。
|
||||
"progress_msg": "Extracting entities from chunk 25...", // **当前状态描述**。用于前端展示 Loading 提示。
|
||||
"create_time": 1715623400000,
|
||||
"update_time": 1715624500000
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 查询 RAPTOR 任务进度 - `trace_raptor`
|
||||
**接口描述**: 查询指定知识库当前 **RAPTOR** 递归摘要任务的实时状态。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/trace_raptor`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | 知识库 ID |
|
||||
|
||||
#### Query Parameters
|
||||
无
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "task_uuid_87654321",
|
||||
"progress": 1.0, // 进度值。1.0 表示树构建完成。
|
||||
"progress_msg": "Tree construction completed.", // 状态消息。
|
||||
"create_time": 1715629000000
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,757 @@
|
||||
## 1. 上传文档 - `upload`
|
||||
**接口描述**: 向指定的知识库上传一个或多个文档文件。上传后，文档将立即被存入文件系统/对象存储，并在数据库中创建记录。默认解析状态为 `UNSTART` (未开始)，解析配置将继承自 KnowledgeBase 的默认设置。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/documents`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
**Content-Type**: `multipart/form-data`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。指定文档归属的知识库。 |
|
||||
|
||||
#### Form Data Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| file | file | 是 | **文件二进制流**。支持多文件上传 (Multiple Files)。<br>支持格式: PDF, DOCX, TXT, MD, CS, HTML, CSV, XLSX, PPTX 等。<br>单文件大小限制请参考系统配置 (默认通常为 10MB/100MB)。 |
|
||||
| parent_path | string | 否 | **父级目录路径**。类似于文件系统的文件夹结构，默认为 `/`。如果指定 (如 `/docs/v1/`)，文档将在该虚拟路径下列出。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": [
|
||||
{
|
||||
"id": "e457f92e3c0411ef8d4c0242ac120003",
|
||||
"thumbnail": null,
|
||||
"dataset_id": "d1234567890abcdef1234567890abcde",
|
||||
"chunk_method": "naive",
|
||||
"pipeline_id": null,
|
||||
"parser_config": {
|
||||
"chunk_token_num": 512,
|
||||
"delimiter": "\\n",
|
||||
"layout_recognize": "DeepDOC",
|
||||
"html4excel": false,
|
||||
"auto_keywords": 0,
|
||||
"auto_questions": 0,
|
||||
"topn_tags": 3,
|
||||
"raptor": {
|
||||
"use_raptor": false
|
||||
},
|
||||
"graphrag": {
|
||||
"use_graphrag": false
|
||||
}
|
||||
},
|
||||
"source_type": "local",
|
||||
"type": "pdf",
|
||||
"created_by": "user_id_123",
|
||||
"name": "UserGuide_v2.pdf",
|
||||
"location": "UserGuide_v2.pdf",
|
||||
"size": 102400,
|
||||
"token_count": 0,
|
||||
"chunk_count": 0,
|
||||
"progress": 0.0,
|
||||
"progress_msg": "",
|
||||
"process_begin_at": null,
|
||||
"process_duration": 0.0,
|
||||
"meta_fields": {},
|
||||
"suffix": "pdf",
|
||||
"run": "UNSTART",
|
||||
"status": "1",
|
||||
"create_time": 1715623400123,
|
||||
"create_date": "2024-05-13 10:03:20",
|
||||
"update_time": 1715623400123,
|
||||
"update_date": "2024-05-13 10:03:20"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取文档列表 - `list_docs`
|
||||
**接口描述**: 查询知识库下的文档列表。支持分页检索、关键词搜索、状态筛选等功能。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/documents`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| page | int | 否 | 1 | **页码**。从 1 开始计数。 |
|
||||
| page_size | int | 否 | 30 | **每页数量**。 |
|
||||
| orderby | string | 否 | "create_time" | **排序字段**。支持 `create_time` (创建时间), `name` (文件名), `size` (大小) 等。 |
|
||||
| desc | boolean | 否 | true | **是否降序**。`true` (最新/最大在前), `false` (最旧/最小在前)。 |
|
||||
| id | string | 否 | - | **精确筛选 ID**。仅返回指定 ID 的文档。 |
|
||||
| name | string | 否 | - | **精确筛选文件名**。仅返回指定名称的文档。 |
|
||||
| keywords | string | 否 | - | **模糊搜索**。匹配文档名称包含该关键词的记录。 |
|
||||
| suffix | array | 否 | - | **文件后缀筛选** (如 `pdf`, `docx`)。 |
|
||||
| run | array | 否 | - | **运行状态筛选**。可选值: `UNSTART`, `RUNNING`, `CANCEL`, `DONE`, `FAIL`。 |
|
||||
| create_time_from | int | 否 | 0 | **起始时间戳** (毫秒)。查询在此时间之后创建的文档。 |
|
||||
| create_time_to | int | 否 | 0 | **结束时间戳** (毫秒)。查询在此时间之前创建的文档。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"total": 128,
|
||||
"docs": [
|
||||
{
|
||||
"id": "e457f92e3c0411ef8d4c0242ac120003",
|
||||
"thumbnail": null,
|
||||
"dataset_id": "d1234567890abcdef1234567890abcde",
|
||||
"chunk_method": "naive",
|
||||
"pipeline_id": null,
|
||||
"parser_config": {
|
||||
"chunk_token_num": 512,
|
||||
"delimiter": "\\n",
|
||||
"layout_recognize": "DeepDOC",
|
||||
"html4excel": false,
|
||||
"auto_keywords": 0,
|
||||
"auto_questions": 0,
|
||||
"topn_tags": 3,
|
||||
"raptor": {
|
||||
"use_raptor": false
|
||||
},
|
||||
"graphrag": {
|
||||
"use_graphrag": false
|
||||
}
|
||||
},
|
||||
"source_type": "local",
|
||||
"type": "pdf",
|
||||
"created_by": "user_id_123",
|
||||
"name": "UserGuide_v2.pdf",
|
||||
"location": "UserGuide_v2.pdf",
|
||||
"size": 102400,
|
||||
"token_count": 45000,
|
||||
"chunk_count": 120,
|
||||
"progress": 1.0,
|
||||
"progress_msg": "Parsing finished",
|
||||
"process_begin_at": "2024-05-13 10:05:00",
|
||||
"process_duration": 45.2,
|
||||
"meta_fields": {
|
||||
"author": "RAGFlow Team",
|
||||
"version": "2.0"
|
||||
},
|
||||
"suffix": "pdf",
|
||||
"run": "DONE",
|
||||
"status": "1",
|
||||
"create_time": 1715623400123,
|
||||
"create_date": "2024-05-13 10:03:20",
|
||||
"update_time": 1715623450000,
|
||||
"update_date": "2024-05-13 10:05:45"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 更新文档信息 - `update_doc`
|
||||
**接口描述**: 更新文档的名称、状态或解析配置。
|
||||
**特别注意**: 如果修改了 `chunk_method` 或 `parser_config`，后端会自动将 `run` 状态重置为 `UNSTART`，并清除已有的 chunk 数据，等待重新解析。
|
||||
**请求方法**: `PUT`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
| document_id | string | 是 | **文档 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
*(仅需传递要修改的字段)*
|
||||
|
||||
| 参数名 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| name | string | **新文档名称**。需包含文件后缀且不能改变原始文件类型 (如从 `.pdf` 改为 `.txt` 会导致错误)。 |
|
||||
| enabled | boolean | **启用/禁用**。`true`: 启用 (DEFAULT, 对应 status="1"); `false`: 禁用 (对应 status="0")。禁用后该文档不参与检索。 |
|
||||
| chunk_method | string | **解析方法**。可选值: `naive`, `manual`, `qa`, `table`, `paper`, `book`, `laws`, `presentation`, `picture`, `one`, `knowledge_graph`, `email`。 |
|
||||
| parser_config | object | **解析器详细配置**。应与 `chunk_method` 匹配。以下列出 `naive` (通用) 方法的完整配置参数。 |
|
||||
|
||||
**parser_config (Naive 模式全量参数)**:
|
||||
| 参数名 | 类型 | 默认值 | 说明 |
|
||||
|---|---|---|---|
|
||||
| chunk_token_num | int | 512 | **切片最大 Token 数**。 |
|
||||
| delimiter | string | "\\n" | **分段符**。支持转义字符。 |
|
||||
| layout_recognize | string | "DeepDOC" | **布局识别模型**。可选 `DeepDOC` 或 `Simple`。 |
|
||||
| html4excel | boolean | false | **Excel转HTML**。是否将 Excel 解析为 HTML 表格。 |
|
||||
| auto_keywords | int | 0 | **自动关键词数量**。0 表示不抽取。 |
|
||||
| auto_questions | int | 0 | **自动问题数量**。0 表示不生成。 |
|
||||
| topn_tags | int | 3 | **自动标签数量**。 |
|
||||
| raptor | object | `{ "use_raptor": false }` | **RAPTOR 配置**。设置 `use_raptor: true` 可开启递归摘要索引。 |
|
||||
| graphrag | object | `{ "use_graphrag": false }` | **GraphRAG 配置**。设置 `use_graphrag: true` 可开启图谱增强。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "e457f92e3c0411ef8d4c0242ac120003",
|
||||
"thumbnail": null,
|
||||
"dataset_id": "d1234567890abcdef1234567890abcde",
|
||||
"chunk_method": "naive",
|
||||
"pipeline_id": null,
|
||||
"parser_config": {
|
||||
"chunk_token_num": 1024,
|
||||
"delimiter": "\\n",
|
||||
"layout_recognize": "DeepDOC",
|
||||
"html4excel": false,
|
||||
"auto_keywords": 0,
|
||||
"auto_questions": 0,
|
||||
"topn_tags": 3,
|
||||
"raptor": {
|
||||
"use_raptor": false
|
||||
},
|
||||
"graphrag": {
|
||||
"use_graphrag": false
|
||||
}
|
||||
},
|
||||
"source_type": "local",
|
||||
"type": "pdf",
|
||||
"created_by": "user_id_123",
|
||||
"name": "Renamed_Guide.pdf",
|
||||
"location": "UserGuide_v2.pdf",
|
||||
"size": 102400,
|
||||
"token_count": 45000,
|
||||
"chunk_count": 0,
|
||||
"progress": 0.0,
|
||||
"progress_msg": "",
|
||||
"process_begin_at": null,
|
||||
"process_duration": 0.0,
|
||||
"meta_fields": {},
|
||||
"suffix": "pdf",
|
||||
"run": "UNSTART",
|
||||
"status": "0",
|
||||
"create_time": 1715623400123,
|
||||
"create_date": "2024-05-13 10:03:20",
|
||||
"update_time": 1715629999000,
|
||||
"update_date": "2024-05-13 12:00:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 删除文档 - `delete`
|
||||
**接口描述**: 物理删除一个或多个文档。此操作不可恢复，将同时删除数据库记录、MinIO 中的源文件以及 Elasticsearch 中的所有相关切片索引。
|
||||
**请求方法**: `DELETE`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/documents`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| ids | array<string> | 是 | **文档 ID 列表**。必须指定要删除的文档 ID。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 下载/预览原始文件 - `download`
|
||||
**接口描述**: 获取文档的原始二进制文件流。响应头将会包含 `Content-Disposition` 字段，指示浏览器以附件形式下载。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
| document_id | string | 是 | **文档 ID**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/octet-stream`
|
||||
**Content-Disposition**: `attachment; filename="UserGuide_v2.pdf"`
|
||||
|
||||
*(直接返回文件的二进制数据流)*
|
||||
|
||||
|
||||
## 6. 触发/重试文档解析 - `parse`
|
||||
**接口描述**: 手动触发文档的解析任务。通常在上传文件后、或修改了解析配置（如 `chunk_method`）后调用此接口。支持批量触发。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/chunks`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| document_ids | array<string> | 是 | **文档 ID 列表**。指定需要（重新）解析的文档 ID。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"document_ids": ["doc_id_1", "doc_id_2"]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 停止文档解析 - `stop_parsing`
|
||||
**接口描述**: 停止当前正在进行的文档解析任务。
|
||||
**请求方法**: `DELETE`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/chunks`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| document_ids | array<string> | 是 | **文档 ID 列表**。指定要停止解析的任务。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 获取切片列表 - `list_chunks`
|
||||
**接口描述**: 获取指定文档已解析出的切片（Chunk）列表。支持分页和关键词搜索。返回结果包含文档的详细元数据和具体的切片内容。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
| document_id | string | 是 | **文档 ID**。 |
|
||||
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| page | int | 否 | 1 | **页码**。 |
|
||||
| page_size | int | 否 | 30 | **每页数量**。 |
|
||||
| keywords | string | 否 | - | **搜索关键词**。在切片内容中进行全文检索。 |
|
||||
| id | string | 否 | - | **精确切片 ID**。若指定，则只返回该 ID 对应的切片。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"total": 150,
|
||||
"chunks": [
|
||||
{
|
||||
"id": "e457f92e3c0411ef8d4c0242ac120003_0",
|
||||
"content": "RAGFlow 是一款基于深度文档理解的开源 RAG（检索增强生成）引擎。它旨在为各种规模的企业提供精简的 RAG 工作流。RAGFlow 结合了传统文档处理的稳健性与现代大语言模型（LLM）的生成能力，确保在处理复杂格式数据（如 PDF 表格、扫描件等）时依然能保持极高的召回率和准确性。",
|
||||
"document_id": "doc_uuid_123",
|
||||
"docnm_kwd": "RAGFlow_UserGuide_v2.pdf",
|
||||
"important_keywords": ["RAGFlow", "开源", "深度文档理解", "LLM"],
|
||||
"questions": ["什么是 RAGFlow?", "RAGFlow 的主要特点是什么?"],
|
||||
"image_id": "",
|
||||
"dataset_id": "kb_uuid_456",
|
||||
"available": true,
|
||||
"positions": [1]
|
||||
},
|
||||
{
|
||||
"id": "e457f92e3c0411ef8d4c0242ac120003_1",
|
||||
"content": "主要特性：\n1. **深度文档解析**：内置 DeepDOC 识别引擎，精准还原表格、段落结构。\n2. **多路召回**：支持关键词 + 向量的混合检索。\n3. **可视化编排**：提供基于 Graph 的工作流编排能力。",
|
||||
"document_id": "doc_uuid_123",
|
||||
"docnm_kwd": "RAGFlow_UserGuide_v2.pdf",
|
||||
"important_keywords": ["DeepDOC", "混合检索", "可视化编排"],
|
||||
"questions": [],
|
||||
"image_id": "img_uuid_789",
|
||||
"dataset_id": "kb_uuid_456",
|
||||
"available": true,
|
||||
"positions": [2]
|
||||
}
|
||||
],
|
||||
"doc": {
|
||||
"id": "doc_uuid_123",
|
||||
"name": "RAGFlow_UserGuide_v2.pdf",
|
||||
"chunk_count": 150,
|
||||
"token_count": 45000,
|
||||
"chunk_method": "naive",
|
||||
"run": "DONE",
|
||||
"status": "1",
|
||||
"progress": 1.0,
|
||||
"progress_msg": "Parsing finished",
|
||||
"process_begin_at": "2024-05-13 10:05:00",
|
||||
"process_duration": 45.2,
|
||||
"meta_fields": {
|
||||
"author": "RAGFlow Team",
|
||||
"version": "2.0"
|
||||
},
|
||||
"create_time": 1715623400123,
|
||||
"create_date": "2024-05-13 10:03:20",
|
||||
"update_time": 1715623450000,
|
||||
"update_date": "2024-05-13 10:05:45",
|
||||
"dataset_id": "kb_uuid_456"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 手动新增切片 - `add_chunk`
|
||||
**接口描述**: 向指定文档中手动添加一个新的切片。系统会自动计算该切片的向量嵌入 (Embedding)。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
| document_id | string | 是 | **文档 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| content | string | 是 | **切片内容**。手动输入的文本内容。 |
|
||||
| important_keywords | array<string> | 否 | **重要关键词**。用于关键词检索增强。 |
|
||||
| questions | array<string> | 否 | **预设问题**。用于 Q&A 检索模式增强。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"chunk": {
|
||||
"id": "new_chunk_uuid_999",
|
||||
"content": "这是管理员手动添加的一条补充切片，用于修正文档中缺失的关键信息。",
|
||||
"document_id": "doc_uuid_123",
|
||||
"docnm_kwd": "RAGFlow_UserGuide_v2.pdf",
|
||||
"important_keywords": ["手动添加", "补充信息"],
|
||||
"questions": ["如何手动添加切片?"],
|
||||
"image_id": "",
|
||||
"dataset_id": "kb_uuid_456",
|
||||
"available": true,
|
||||
"positions": []
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 10. 修改切片信息 - `update_chunk`
|
||||
**接口描述**: 修改已存在的切片内容、关键词、可用状态等。修改内容后，系统会自动重新计算向量。
|
||||
**请求方法**: `PUT`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks/<chunk_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
| document_id | string | 是 | **文档 ID**。 |
|
||||
| chunk_id | string | 是 | **切片 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
*(以下字段均为可选，仅传递需修改的字段)*
|
||||
|
||||
| 参数名 | 类型 | 说明 |
|
||||
|---|---|---|
|
||||
| content | string | **新的切片内容**。 |
|
||||
| important_keywords | array<string> | **更新关键词列表**。覆盖原有列表。 |
|
||||
| available | boolean | **启用/禁用**。`true`: 启用 (默认); `false`: 禁用 (检索时将忽略此切片)。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 删除切片 - `rm_chunk`
|
||||
**接口描述**: 批量删除文档中的指定切片。
|
||||
**请求方法**: `DELETE`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
| document_id | string | 是 | **文档 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| chunk_ids | array<string> | 是 | **切片 ID 列表**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "deleted 2 chunks",
|
||||
"data": null
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## 12. 获取元数据摘要 - `metadata_summary`
|
||||
**接口描述**: 获取知识库中所有文档的元数据摘要信息。通常用于前端展示知识库的数据分布概况，例如不同文件类型的数量统计、文件状态分布等。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/metadata/summary`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
|
||||
#### Query Parameters
|
||||
无
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"summary": {
|
||||
"total_doc_count": 120,
|
||||
"total_token_count": 500000,
|
||||
"file_type_distribution": {
|
||||
"pdf": 80,
|
||||
"docx": 30,
|
||||
"txt": 10
|
||||
},
|
||||
"status_distribution": {
|
||||
"1": 118, // 正常启用
|
||||
"0": 2 // 禁用
|
||||
},
|
||||
"custom_metadata": {
|
||||
"author": {
|
||||
"Alice": 50,
|
||||
"Bob": 30
|
||||
},
|
||||
"department": {
|
||||
"HR": 20,
|
||||
"Engineering": 100
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 13. 批量更新元数据 - `metadata_batch_update`
|
||||
**接口描述**: 对知识库中的文档进行批量元数据修改。支持基于复杂的条件筛选文档，然后执行批量更新或删除元数据字段的操作。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/datasets/<dataset_id>/metadata/update`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| dataset_id | string | 是 | **知识库 ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| selector | object | 否 | **筛选器**。定义要更新哪些文档。如果不传，可能作用于全量文档（请谨慎）。 |
|
||||
| updates | array | 否 | **更新操作列表**。包含 `key` 和 `value`。 |
|
||||
| deletes | array | 否 | **删除操作列表**。包含 `key`。 |
|
||||
|
||||
**Request Example (复杂场景)**:
|
||||
```json
|
||||
{
|
||||
"selector": {
|
||||
"document_ids": ["doc_id_101", "doc_id_102"],
|
||||
"metadata_condition": {
|
||||
"logic": "and",
|
||||
"conditions": [
|
||||
{"key": "author", "value": "OldName", "operator": "eq"},
|
||||
{"key": "status", "value": "draft", "operator": "eq"}
|
||||
]
|
||||
}
|
||||
},
|
||||
"updates": [
|
||||
{"key": "author", "value": "Admin"},
|
||||
{"key": "reviewed_by", "value": "ManagerA"}
|
||||
],
|
||||
"deletes": [
|
||||
{"key": "temp_tag"},
|
||||
{"key": "draft_flag"}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"updated": 2, // 实际更新成功的文档数量
|
||||
"matched_docs": 2 // 匹配到的文档数量
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 14. 检索测试 (Hit Test) - `retrieval_test`
|
||||
**接口描述**: 在指定的知识库中进行模拟检索测试。此接口用于验证分段（Chunk）质量、检索参数（相似度阈值、Top K）的效果，是调试 RAG 效果的核心工具。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/retrieval`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
**注意**: 即使是简单的查询，由于包含较多配置参数，本接口也设计为 `POST` 请求。
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
无
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| dataset_ids | array<string> | 是 | - | **目标知识库 ID 列表**。支持跨多个知识库检索。 |
|
||||
| question | string | 是 | - | **用户查询问题**。 |
|
||||
| similarity_threshold | float | 否 | 0.2 | **相似度阈值**。低于此分数的 Chunk 将被过滤。 |
|
||||
| vector_similarity_weight | float | 否 | 0.3 | **向量权重**。混合检索时，向量检索结果的权重 (0~1)。剩余权重归于关键词检索。 |
|
||||
| top_k | int | 否 | 1024 | **初筛数量**。向量检索返回的候选切片数量。 |
|
||||
| rerank_id | string | 否 | - | **重排模型 ID**。若指定，将对检索结果进行 Rerank 二次排序。 |
|
||||
| highlight | boolean | 否 | true | **高亮匹配**。是否在返回内容中高亮关键词。 |
|
||||
| keyword | boolean | 否 | false | **关键词增强**。是否使用 LLM 提取问题关键词以增强检索。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"total": 15,
|
||||
"chunks": [
|
||||
{
|
||||
"id": "e457f92e3c0411ef8d4c0242ac120003_12",
|
||||
"content": "RAGFlow 支持多种文档解析模式，其中 DeepDOC 模式特别适合处理包含大量表格和扫描件的 PDF 文档。它使用深度学习模型识别文档布局，精准提取表格内容。",
|
||||
"document_id": "doc_uuid_123",
|
||||
"dataset_id": "kb_uuid_456",
|
||||
"document_name": "RAGFlow_UserGuide_v2.pdf",
|
||||
"document_keyword": "RAGFlow_UserGuide_v2.pdf",
|
||||
"similarity": 0.88,
|
||||
"vector_similarity": 0.85,
|
||||
"term_similarity": 0.92,
|
||||
"index": 12,
|
||||
"highlight": "RAGFlow 支持多种<em>文档解析模式</em>，其中 <em>DeepDOC</em> 模式特别适合处理包含大量表格和扫描件的 PDF 文档。",
|
||||
"important_keywords": ["DeepDOC", "PDF"],
|
||||
"questions": ["DeepDOC 模式有什么用?"],
|
||||
"image_id": "",
|
||||
"positions": [12]
|
||||
},
|
||||
{
|
||||
"id": "e457f92e3c0411ef8d4c0242ac120003_15",
|
||||
"content": "如果文档主要由纯文本构成，建议使用 Naive 模式。该模式解析速度快，适合通用场景。",
|
||||
"document_id": "doc_uuid_123",
|
||||
"dataset_id": "kb_uuid_456",
|
||||
"document_name": "RAGFlow_UserGuide_v2.pdf",
|
||||
"document_keyword": "RAGFlow_UserGuide_v2.pdf",
|
||||
"similarity": 0.45,
|
||||
"vector_similarity": 0.40,
|
||||
"term_similarity": 0.50,
|
||||
"index": 15,
|
||||
"highlight": "如果文档主要由纯文本构成，建议使用 <em>Naive</em> 模式。",
|
||||
"important_keywords": ["Naive", "纯文本"],
|
||||
"questions": [],
|
||||
"image_id": "",
|
||||
"positions": [15]
|
||||
}
|
||||
],
|
||||
"doc_aggs": [
|
||||
{
|
||||
"doc_name": "RAGFlow_UserGuide_v2.pdf",
|
||||
"doc_id": "doc_uuid_123",
|
||||
"count": 2
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,503 @@
|
||||
# RAGFlow 文件管理接口详解 (File Management API)
|
||||
|
||||
## 1. 上传文件 - `upload`
|
||||
**接口描述**: 上传一个或多个文件到指定文件夹。支持多文件上传 (Multipart)。上传成功后，文件将存储在 MinIO/S3 中，并返回文件元数据列表。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/file/upload`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
**Content-Type**: `multipart/form-data`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Form Data Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| file | file | 是 | **文件二进制流**。支持多文件上传。 |
|
||||
| parent_id | string | 否 | **父级目录 ID**。如果省略，默认上传到根目录 (root)。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": [
|
||||
{
|
||||
"id": "e457f92e3c0411ef8d4c0242ac120003",
|
||||
"parent_id": "root_folder_id_123",
|
||||
"tenant_id": "tenant_uuid_456",
|
||||
"created_by": "user_uuid_789",
|
||||
"type": "pdf",
|
||||
"name": "ProjectReport.pdf",
|
||||
"location": "ProjectReport.pdf",
|
||||
"size": 204800,
|
||||
"source_type": "",
|
||||
"create_time": 1715623400123,
|
||||
"create_date": "2024-05-13 10:03:20",
|
||||
"update_time": 1715623400123,
|
||||
"update_date": "2024-05-13 10:03:20"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 新建文件夹 - `create`
|
||||
**接口描述**: 在指定父目录下创建一个新的文件夹（逻辑目录）。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/file/create`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| name | string | 是 | **文件夹名称**。同一目录下不可重名。 |
|
||||
| parent_id | string | 否 | **父级目录 ID**。省略则默认为根目录。 |
|
||||
| type | string | 是 | **类型**。固定值为 `FOLDER` 创建文件夹。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"name": "Year2024_Reports",
|
||||
"parent_id": "root_folder_id_123",
|
||||
"type": "FOLDER"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "folder_uuid_abc",
|
||||
"parent_id": "root_folder_id_123",
|
||||
"tenant_id": "tenant_uuid_456",
|
||||
"created_by": "user_uuid_789",
|
||||
"name": "Year2024_Reports",
|
||||
"location": "",
|
||||
"size": 0,
|
||||
"type": "folder",
|
||||
"source_type": "",
|
||||
"create_time": 1715623500000,
|
||||
"create_date": "2024-05-13 10:05:00",
|
||||
"update_time": 1715623500000,
|
||||
"update_date": "2024-05-13 10:05:00"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 获取文件列表 - `list_files`
|
||||
**接口描述**: 分页获取指定文件夹下的文件和子文件夹列表。支持按名称模糊搜索。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/file/list`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| parent_id | string | 否 | (Root) | **父级目录 ID**。指定要查看的目录 ID。 |
|
||||
| keywords | string | 否 | - | **搜索关键词**。按文件名模糊搜索。 |
|
||||
| page | int | 否 | 1 | **页码**。 |
|
||||
| page_size | int | 否 | 15 | **每页数量**。 |
|
||||
| orderby | string | 否 | "create_time" | **排序字段**。 |
|
||||
| desc | boolean | 否 | true | **是否降序**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"total": 25,
|
||||
"parent_folder": {
|
||||
"id": "root_folder_id_123",
|
||||
"parent_id": "",
|
||||
"tenant_id": "tenant_uuid_456",
|
||||
"created_by": "system",
|
||||
"name": "ROOT",
|
||||
"location": "",
|
||||
"size": 0,
|
||||
"type": "folder",
|
||||
"source_type": "",
|
||||
"create_time": 1710000000000,
|
||||
"create_date": "2024-03-01 00:00:00",
|
||||
"update_time": 1710000000000,
|
||||
"update_date": "2024-03-01 00:00:00"
|
||||
},
|
||||
"files": [
|
||||
{
|
||||
"id": "folder_uuid_abc",
|
||||
"parent_id": "root_folder_id_123",
|
||||
"tenant_id": "tenant_uuid_456",
|
||||
"created_by": "user_uuid_789",
|
||||
"name": "Year2024_Reports",
|
||||
"location": "",
|
||||
"size": 0,
|
||||
"type": "folder",
|
||||
"source_type": "",
|
||||
"create_time": 1715623500000,
|
||||
"create_date": "2024-05-13 10:05:00",
|
||||
"update_time": 1715623500000,
|
||||
"update_date": "2024-05-13 10:05:00"
|
||||
},
|
||||
{
|
||||
"id": "e457f92e3c0411ef8d4c0242ac120003",
|
||||
"parent_id": "root_folder_id_123",
|
||||
"tenant_id": "tenant_uuid_456",
|
||||
"created_by": "user_uuid_789",
|
||||
"name": "ProjectReport.pdf",
|
||||
"location": "ProjectReport.pdf",
|
||||
"size": 204800,
|
||||
"type": "pdf",
|
||||
"source_type": "",
|
||||
"create_time": 1715623400123,
|
||||
"create_date": "2024-05-13 10:03:20",
|
||||
"update_time": 1715623400123,
|
||||
"update_date": "2024-05-13 10:03:20"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 获取文件流 (下载) - `get`
|
||||
**接口描述**: 通过文件 ID 下载文件内容。不同于获取元数据，该接口直接返回文件的二进制流（Octet-stream 或 Image 等）。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/file/get/<file_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| file_id | string | 是 | **文件 ID**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/octet-stream` (或具体 MIME 类型如 `image/png`)
|
||||
|
||||
*(返回二进制文件流)*
|
||||
|
||||
---
|
||||
|
||||
## 5. 下载附件 - `download_attachment`
|
||||
**接口描述**: 这是一个通用的附件下载接口，通常用于系统内部引用或特定路径的下载。它使用 `attachment_id`（通常对应 MinIO 中的存储路径/Key）来检索文件。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/file/download/<attachment_id>`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| attachment_id | string | 是 | **附件 ID / 存储 Key**。通常对应底层存储的唯一标识符。 |
|
||||
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| ext | string | 否 | "markdown" | **文件扩展名**。用于设置响应头中的 Content-Type。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/octet-stream` (或根据 ext 参数推断)
|
||||
|
||||
*(返回二进制文件流)*
|
||||
|
||||
|
||||
## 6. 重命名文件/文件夹 - `rename`
|
||||
**接口描述**: 修改文件或文件夹的名称。对于文件，通常不允许修改扩展名（后缀）。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/file/rename`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| file_id | string | 是 | **目标文件/文件夹 ID**。 |
|
||||
| name | string | 是 | **新名称**。需符合文件命名规范，且同一目录下不可重名。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"file_id": "file_uuid_123",
|
||||
"name": "New_Report_Final.pdf"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 移动文件/文件夹 - `move`
|
||||
**接口描述**: 批量移动文件或文件夹到指定的目录 (Move)。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/file/mv`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| src_file_ids | array<string> | 是 | **源文件/文件夹 ID 列表**。支持批量移动。 |
|
||||
| dest_file_id | string | 是 | **目标文件夹 ID**。必须是已存在的文件夹 ID。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"src_file_ids": ["file_id_1", "file_id_2"],
|
||||
"dest_file_id": "folder_id_target"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 删除文件/文件夹 - `rm`
|
||||
**接口描述**: 批量删除文件或文件夹。如果是文件夹，将递归删除其下的所有内容。此操作不可恢复。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/file/rm`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| file_ids | array<string> | 是 | **待删除的文件/文件夹 ID 列表**。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"file_ids": ["file_uuid_to_delete_1", "folder_uuid_to_delete_2"]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": true
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 文件转知识库文档 - `convert`
|
||||
**接口描述**: 将已上传的文件（File）导入到指定的知识库（Dataset）中，转换为文档（Document）并进行解析。这是一个“文件 -> 知识库”的桥接操作。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/file/convert`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| file_ids | array<string> | 是 | **源文件 ID 列表**。必须是已存在于文件管理系统中的 ID。 |
|
||||
| kb_ids | array<string> | 是 | **目标知识库 ID 列表**。文件将被同时导入到这些知识库中。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"file_ids": ["file_uuid_pdf_1", "file_uuid_txt_2"],
|
||||
"kb_ids": ["dataset_uuid_A"]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": [
|
||||
{
|
||||
"id": "mapping_uuid_1",
|
||||
"file_id": "file_uuid_pdf_1",
|
||||
"document_id": "doc_uuid_created_in_kb_A",
|
||||
"create_time": 1715623600123,
|
||||
"create_date": "2024-05-13 10:06:40",
|
||||
"update_time": 1715623600123,
|
||||
"update_date": "2024-05-13 10:06:40"
|
||||
},
|
||||
{
|
||||
"id": "mapping_uuid_2",
|
||||
"file_id": "file_uuid_txt_2",
|
||||
"document_id": "doc_uuid_created_in_kb_A",
|
||||
"create_time": 1715623600124,
|
||||
"create_date": "2024-05-13 10:06:40",
|
||||
"update_time": 1715623600124,
|
||||
"update_date": "2024-05-13 10:06:40"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
## 10. 获取根目录信息 - `get_root_folder`
|
||||
**接口描述**: 获取当前用户的根目录文件夹信息。每个用户（Tenant）都有且仅有一个系统自动创建的根目录。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/file/root_folder`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Query Parameters
|
||||
无
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"root_folder": {
|
||||
"id": "root_folder_id_123",
|
||||
"parent_id": "",
|
||||
"tenant_id": "tenant_uuid_456",
|
||||
"created_by": "system",
|
||||
"name": "ROOT",
|
||||
"location": "",
|
||||
"size": 0,
|
||||
"type": "folder",
|
||||
"source_type": "",
|
||||
"create_time": 1710000000000,
|
||||
"create_date": "2024-03-01 00:00:00",
|
||||
"update_time": 1710000000000,
|
||||
"update_date": "2024-03-01 00:00:00"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 获取父目录信息 - `get_parent_folder`
|
||||
**接口描述**: 获取指定文件或文件夹的直接父级目录信息。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/file/parent_folder`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| file_id | string | 是 | **当前文件/文件夹 ID**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"parent_folder": {
|
||||
"id": "root_folder_id_123",
|
||||
"parent_id": "",
|
||||
"tenant_id": "tenant_uuid_456",
|
||||
"created_by": "system",
|
||||
"name": "ROOT",
|
||||
"location": "",
|
||||
"size": 0,
|
||||
"type": "folder",
|
||||
"source_type": "",
|
||||
"create_time": 1710000000000,
|
||||
"create_date": "2024-03-01 00:00:00",
|
||||
"update_time": 1710000000000,
|
||||
"update_date": "2024-03-01 00:00:00"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 12. 获取完整路径 (面包屑) - `get_all_parent_folders`
|
||||
**接口描述**: 获取指定文件或文件夹的所有上级目录列表，形成完整的路径链。返回的列表顺序通常是从根目录到直接父目录（有序）。此接口常用于前端展示“面包屑导航” (Breadcrumbs)。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/file/all_parent_folder`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| file_id | string | 是 | **目标文件/文件夹 ID**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"parent_folders": [
|
||||
{
|
||||
"id": "root_folder_id_123",
|
||||
"parent_id": "",
|
||||
"tenant_id": "tenant_uuid_456",
|
||||
"created_by": "system",
|
||||
"name": "ROOT",
|
||||
"location": "",
|
||||
"size": 0,
|
||||
"type": "folder",
|
||||
"source_type": "",
|
||||
"create_time": 1710000000000,
|
||||
"create_date": "2024-03-01 00:00:00",
|
||||
"update_time": 1710000000000,
|
||||
"update_date": "2024-03-01 00:00:00"
|
||||
},
|
||||
{
|
||||
"id": "folder_project_a_id",
|
||||
"parent_id": "root_folder_id_123",
|
||||
"tenant_id": "tenant_uuid_456",
|
||||
"created_by": "user_id_001",
|
||||
"name": "Project A Docs",
|
||||
"location": "",
|
||||
"size": 0,
|
||||
"type": "folder",
|
||||
"source_type": "",
|
||||
"create_time": 1715000000000,
|
||||
"create_date": "2024-05-01 09:00:00",
|
||||
"update_time": 1715000000000,
|
||||
"update_date": "2024-05-01 09:00:00"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
+228
@@ -0,0 +1,228 @@
|
||||
# RAGFlow 搜索机器人 & AgentBot 接口详解 (SearchBot & AgentBot)
|
||||
|
||||
## 1. 搜索机器人对话 - `ask_about_embedded`
|
||||
**接口描述**: 面向 **SearchBot (搜索机器人)** 的核心对话接口，通常用于嵌入式知识库问答场景。与普通 Chat 不同，它更侧重于从指定的 `kb_ids` 中直接检索答案，且鉴权使用 `Authorization: Bearer <Beta_Token>` (即 API Key)。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/searchbots/ask`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| question | string | 是 | - | **用户问题**。 |
|
||||
| kb_ids | array<string> | 是 | - | **知识库 ID 列表**。限定从哪些知识库中检索。 |
|
||||
| search_id | string | 否 | - | **搜索应用 ID**。如果指定，将使用该搜索应用的配置 (Search App Config)。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"question": "What is the refund policy?",
|
||||
"kb_ids": ["dataset_uuid_1", "dataset_uuid_2"],
|
||||
"search_id": "search_app_uuid_abc"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Stream Response)
|
||||
**Content-Type**: `text/event-stream`
|
||||
|
||||
```text
|
||||
data:{"code": 0, "message": "", "data": {"answer": "According to the ", "reference": {}}}
|
||||
|
||||
data:{"code": 0, "message": "", "data": {"answer": "policy, refunds are processed within 7 days.", "reference": {"chunk_1": {"content_with_weight": "Refunds...", "doc_name": "policy.pdf"}}}}
|
||||
|
||||
data:{"code": 0, "message": "", "data": true} // 结束标志
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取思维导图 - `mindmap`
|
||||
**接口描述**: 根据用户的查询或对话上下文，生成用于前端展示的思维导图数据结构。这通常用于帮助用户梳理复杂的搜索结果或知识结构。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/searchbots/mindmap`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| question | string | 是 | **用户问题/主题**。 |
|
||||
| kb_ids | array<string> | 是 | **知识库 ID 列表**。 |
|
||||
| search_id | string | 否 | **搜索应用 ID**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"root": {
|
||||
"text": "Refund Policy", // 根节点文本
|
||||
"children": [
|
||||
{
|
||||
"text": "Conditions",
|
||||
"children": [
|
||||
{ "text": "Product defect" },
|
||||
{ "text": "Shipping error" }
|
||||
]
|
||||
},
|
||||
{
|
||||
"text": "Timeline",
|
||||
"children": [
|
||||
{ "text": "7-14 business days" }
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 获取相关推荐问题 - `related_questions_embedded`
|
||||
**接口描述**: 根据用户当前的问题，生成一组相关的推荐问题 (Suggest Questions)。常用于搜索结果页底部的“猜你想问”。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/searchbots/related_questions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| question | string | 是 | **用户当前问题**。 |
|
||||
| search_id | string | 否 | **搜索应用 ID**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": [
|
||||
"How to apply for a refund online?",
|
||||
"What items are non-refundable?",
|
||||
"Contact customer support"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 获取 AgentBot 输入项 - `begin_inputs`
|
||||
**接口描述**: 获取 **AgentBot** (嵌入式 Agent) 的初始化信息，特别是前置输入项 (Prolog/Inputs)。这用于在用户开始对话前，展示一个表单让用户输入必要信息（如姓名、邮箱、API Key 等），这些信息会被传递给 Agent 的 `Begin` 节点。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/agentbots/<agent_id>/inputs`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | **Agent ID**。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"title": "Booking Assistant",
|
||||
"avatar": "http://...",
|
||||
"prologue": "Welcome! Please tell me your details.",
|
||||
"inputs": { // `Begin` 节点定义的输入变量
|
||||
"user_name": {
|
||||
"type": "string",
|
||||
"description": "Your Name",
|
||||
"required": true
|
||||
},
|
||||
"email": {
|
||||
"type": "string",
|
||||
"description": "Contact Email",
|
||||
"required": false
|
||||
}
|
||||
},
|
||||
"mode": "chat"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. AgentBot 对话交互 - `agent_bot_completions`
|
||||
**接口描述**: 面向 **AgentBot** 的嵌入式对话接口。与 `agent_completions` 类似，但它专为无需登录的 C 端用户设计，通过 API Key 鉴权。它支持完整的 Agent 流程执行和流式响应。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/agentbots/<agent_id>/completions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | **Agent ID**。 |
|
||||
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| session_id | string | 是 | **会话 ID**。 |
|
||||
| inputs | object | 否 | **前置输入值**。对应 `begin_inputs` 中定义的变量，如 `{"user_name": "Alice"}`。 |
|
||||
| query | string | 否 | **用户输入**。 |
|
||||
| stream | boolean | 否 | **是否流式**。默认 `true`。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"session_id": "session_uuid_123",
|
||||
"inputs": {
|
||||
"user_name": "Bob"
|
||||
},
|
||||
"query": "I want to book a room.",
|
||||
"stream": true
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Stream Response)
|
||||
**Content-Type**: `text/event-stream`
|
||||
|
||||
```text
|
||||
data:{"event": "message", "data": {"content": "Hello Bob, ", "reference": {}}}
|
||||
|
||||
data:{"event": "message", "data": {"content": "when do you want to check in?", "reference": {}}}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. Agent OpenAI 兼容接口 - `agents_completion_openai_compatibility`
|
||||
**接口描述**: 专门针对 Agent 的 **OpenAI 兼容** 接口。这使得外部工具可以像调用 OpenAI Chat Completion 一样调用 RAGFlow 配置好的复杂 Agent。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/agents_openai/<agent_id>/chat/completions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Path Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| agent_id | string | 是 | **Agent ID**。 |
|
||||
|
||||
#### Body Parameters (OpenAI Standard)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| messages | array | 是 | 包含 `role`, `content` 的消息数组。 |
|
||||
| model | string | 是 | 占位符，任意字符串。 |
|
||||
| stream | boolean | 否 | 默认 `true`。 |
|
||||
|
||||
### 响应参数 (Stream Response - OpenAI Format)
|
||||
**Content-Type**: `text/event-stream`
|
||||
|
||||
```text
|
||||
data: {"id": "agent-chat-uuid", "object": "chat.completion.chunk", "created": 1715000000, "model": "ragflow_agent", "choices": [{"index": 0, "delta": {"role": "assistant", "content": ""}, "finish_reason": null}]}
|
||||
|
||||
data: {"id": "agent-chat-uuid", "object": "chat.completion.chunk", "created": 1715000001, "model": "ragflow_agent", "choices": [{"index": 0, "delta": {"content": "Processing your request..."}, "finish_reason": null}]}
|
||||
|
||||
data: [DONE]
|
||||
```
|
||||
+168
@@ -0,0 +1,168 @@
|
||||
# RAGFlow SearchBot 补充与通用会话接口详解 (Session Extras)
|
||||
|
||||
## 1. 获取引用详情 - `detail_share_embedded`
|
||||
**接口描述**: 当用户点击 SearchBot 回复中的引用标号 (e.g., [1]) 时，调用此接口获取该引用的详细内容（包括原文片段、来源文档名等）。此接口通常用于前端展示“引用来源”侧边栏或弹窗。它使用 API Key (Beta Token) 进行鉴权。
|
||||
**请求方法**: `GET`
|
||||
**接口地址**: `/api/v1/searchbots/detail`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Query Parameters
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| search_id | string | 是 | **搜索应用/SearchBot ID**。此接口需要验证调用者是否有权访问该 SearchBot。 |
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"id": "search_app_uuid_123",
|
||||
"title": "IT Knowledge Base",
|
||||
"description": "Tech support search bot",
|
||||
"kb_ids": ["kb_uuid_1", "kb_uuid_2"],
|
||||
"search_config": {
|
||||
"top_k": 5,
|
||||
"similarity_threshold": 0.5
|
||||
},
|
||||
// 注意：此接口目前主要返回 Search App 的详情配置，
|
||||
// 前端通常使用 search_config 或其他信息来辅助展示引用。
|
||||
// 具体引用内容的文本通常已包含在 `ask` 接口的 `reference` 字段中。
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. SearchBot 检索测试 - `retrieval_test_embedded`
|
||||
**接口描述**: 面向 SearchBot 的**检索效果测试**接口。它不通过 LLM 生成答案，而是直接返回 RAG 检索到的文档片段 (`chunks`)。这用于调试 SearchBot 的检索参数（如相似度阈值、Top-K）是否合理。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/searchbots/retrieval_test`
|
||||
**鉴权方式**: Header `Authorization: Bearer <API_KEY>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| kb_id | string/array | 是 | - | **知识库 ID** (或列表)。支持单个 ID 字符串或 ID 列表。 |
|
||||
| question | string | 是 | - | **测试查询词**。 |
|
||||
| page | int | 否 | 1 | **页码**。 |
|
||||
| size | int | 否 | 30 | **每页数量**。 |
|
||||
| doc_ids | array<string> | 否 | - | **限定文档 ID**。仅在指定文档中检索。 |
|
||||
| similarity_threshold | float | 否 | 0.0 | **相似度阈值**。 |
|
||||
| top_k | int | 否 | 1024 | **Top-K 数量**。 |
|
||||
| highlight | boolean | 否 | false | **高亮匹配**。是否在返回内容中标记匹配关键词。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"kb_id": ["dataset_uuid_1"],
|
||||
"question": "refund policy",
|
||||
"top_k": 5,
|
||||
"highlight": true
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": {
|
||||
"total": 12, // 命中总是
|
||||
"chunks": [
|
||||
{
|
||||
"content_with_weight": "Refunds are processed within <em>7 days</em>...", // 支持高亮
|
||||
"doc_name": "policy.pdf",
|
||||
"doc_id": "doc_uuid_101",
|
||||
"similarity": 0.92,
|
||||
"img_id": ""
|
||||
},
|
||||
{
|
||||
"content_with_weight": "Product return guidelines...",
|
||||
"doc_name": "guidelines.docx",
|
||||
"doc_id": "doc_uuid_102",
|
||||
"similarity": 0.88
|
||||
}
|
||||
],
|
||||
"labels": [] // 如果启用了查询标签功能
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 通用会话问答 - `ask_about`
|
||||
**接口描述**: **内部/测试用**的通用会话问答接口。与 `ask_embedded` 不同，此接口通常用于 RAGFlow 控制台内部的“调试”或“预览”功能，鉴权依赖用户的登录 Token (User Token)，且必须显式指定 `dataset_ids`。它不绑定特定的 Chat/Agent/SearchBot 配置。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/sessions/ask`
|
||||
**鉴权方式**: Header `Authorization: Bearer <USER_TOKEN>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 说明 |
|
||||
|---|---|---|---|
|
||||
| question | string | 是 | **用户问题**。 |
|
||||
| dataset_ids | array<string> | 是 | **知识库 ID 列表**。必须是当前用户有权访问的知识库。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"question": "Summary of report",
|
||||
"dataset_ids": ["dataset_uuid_internal_1"]
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Stream Response)
|
||||
**Content-Type**: `text/event-stream`
|
||||
|
||||
```text
|
||||
data:{"code": 0, "message": "", "data": {"answer": "Here is the summary:", "reference": {}}}
|
||||
|
||||
data:{"code": 0, "message": "", "data": {"answer": " The report indicates...", "reference": {}}}
|
||||
|
||||
data:{"code": 0, "message": "", "data": true} // 结束
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 通用相关问题 - `related_questions`
|
||||
**接口描述**: **内部/测试用**的通用相关问题推荐接口。根据用户的问题和行业背景，利用 LLM 生成推荐问题。通常用于内部测试台。
|
||||
**请求方法**: `POST`
|
||||
**接口地址**: `/api/v1/sessions/related_questions`
|
||||
**鉴权方式**: Header `Authorization: Bearer <USER_TOKEN>`
|
||||
|
||||
### 请求参数 (Request)
|
||||
#### Body Parameters (JSON)
|
||||
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|
||||
|---|---|---|---|---|
|
||||
| question | string | 是 | - | **原始问题/关键词**。 |
|
||||
| industry | string | 否 | "" | **行业背景** (e.g., "Finance", "Healthcare")。帮助 LLM 生成更专业的推荐。 |
|
||||
|
||||
**Request Example**:
|
||||
```json
|
||||
{
|
||||
"question": "Data privacy",
|
||||
"industry": "IT"
|
||||
}
|
||||
```
|
||||
|
||||
### 响应参数 (Response)
|
||||
**Content-Type**: `application/json`
|
||||
|
||||
```json
|
||||
{
|
||||
"code": 0,
|
||||
"message": "success",
|
||||
"data": [
|
||||
"GDPR compliance checklist",
|
||||
"Data encryption standards",
|
||||
"User consent management"
|
||||
]
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,98 @@
|
||||
# RAGFlow External API Reference (Grouped by File)
|
||||
|
||||
## File: `api/apps/sdk/agents.py`
|
||||
| Function Name | URL Pattern | Notes |
|
||||
|---|---|---|
|
||||
| `list_agents` | `/api/v1/agents` | List Agents |
|
||||
| `create_agent` | `/api/v1/agents` | Create Agent |
|
||||
| `update_agent` | `/api/v1/agents/<agent_id>` | Update Agent |
|
||||
| `delete_agent` | `/api/v1/agents/<agent_id>` | Delete Agent |
|
||||
| `webhook` | `/api/v1/webhook_test/<agent_id>` | Webhook Test |
|
||||
| `webhook_trace` | `/api/v1/webhook_trace/<agent_id>` | Webhook Trace |
|
||||
|
||||
## File: `api/apps/sdk/chat.py`
|
||||
| Function Name | URL Pattern | Notes |
|
||||
|---|---|---|
|
||||
| `create` | `/api/v1/chats` | Create Chat |
|
||||
| `delete_chats` | `/api/v1/chats` | Delete Chat |
|
||||
| `list_chat` | `/api/v1/chats` | List Chats |
|
||||
| `update` | `/api/v1/chats/<chat_id>` | Update Chat |
|
||||
|
||||
## File: `api/apps/sdk/dataset.py`
|
||||
| Function Name | URL Pattern | Notes |
|
||||
|---|---|---|
|
||||
| `create` | `/api/v1/datasets` | Create Dataset |
|
||||
| `delete` | `/api/v1/datasets` | Delete Dataset |
|
||||
| `list_datasets` | `/api/v1/datasets` | List Datasets |
|
||||
| `update` | `/api/v1/datasets/<dataset_id>` | Update Dataset |
|
||||
| `knowledge_graph` | `/api/v1/datasets/<dataset_id>/knowledge_graph` | Knowledge Graph |
|
||||
| `delete_knowledge_graph` | `/api/v1/datasets/<dataset_id>/knowledge_graph` | Delete Knowledge Graph |
|
||||
| `run_graphrag` | `/api/v1/datasets/<dataset_id>/run_graphrag` | Run GraphRAG |
|
||||
| `run_raptor` | `/api/v1/datasets/<dataset_id>/run_raptor` | Run Raptor |
|
||||
| `trace_graphrag` | `/api/v1/datasets/<dataset_id>/trace_graphrag` | Trace GraphRAG |
|
||||
| `trace_raptor` | `/api/v1/datasets/<dataset_id>/trace_raptor` | Trace Raptor |
|
||||
|
||||
## File: `api/apps/sdk/dify_retrieval.py`
|
||||
| Function Name | URL Pattern | Notes |
|
||||
|---|---|---|
|
||||
| `retrieval` | `/api/v1/dify/retrieval` | Dify Retrieval |
|
||||
|
||||
## File: `api/apps/sdk/doc.py`
|
||||
| Function Name | URL Pattern | Notes |
|
||||
|---|---|---|
|
||||
| `parse` | `/api/v1/datasets/<dataset_id>/chunks` | Parse Document Chunks |
|
||||
| `stop_parsing` | `/api/v1/datasets/<dataset_id>/chunks` | Stop Parsing |
|
||||
| `upload` | `/api/v1/datasets/<dataset_id>/documents` | Upload Document |
|
||||
| `list_docs` | `/api/v1/datasets/<dataset_id>/documents` | List Documents |
|
||||
| `delete` | `/api/v1/datasets/<dataset_id>/documents` | Delete Document |
|
||||
| `update_doc` | `/api/v1/datasets/<dataset_id>/documents/<document_id>` | Update Document |
|
||||
| `download` | `/api/v1/datasets/<dataset_id>/documents/<document_id>` | Download Document |
|
||||
| `list_chunks` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks` | List Chunks |
|
||||
| `add_chunk` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks` | Add Chunk |
|
||||
| `update_chunk` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks/<chunk_id>` | Update Chunk |
|
||||
| `rm_chunk` | `/api/v1/datasets/<dataset_id>/documents/<document_id>/chunks` | Remove Chunk |
|
||||
| `metadata_summary` | `/api/v1/datasets/<dataset_id>/metadata/summary` | Metadata Summary |
|
||||
| `metadata_batch_update` | `/api/v1/datasets/<dataset_id>/metadata/update` | Batch Update Metadata |
|
||||
| `retrieval_test` | `/api/v1/retrieval` | Retrieval Test |
|
||||
|
||||
## File: `api/apps/sdk/files.py`
|
||||
| Function Name | URL Pattern | Notes |
|
||||
|---|---|---|
|
||||
| `get_all_parent_folders` | `/api/v1/file/all_parent_folder` | Get All Parent Folders |
|
||||
| `convert` | `/api/v1/file/convert` | File Convert |
|
||||
| `create` | `/api/v1/file/create` | File Create |
|
||||
| `download_attachment` | `/api/v1/file/download/<attachment_id>` | Download Attachment |
|
||||
| `get` | `/api/v1/file/get/<file_id>` | Get File |
|
||||
| `list_files` | `/api/v1/file/list` | List Files |
|
||||
| `move` | `/api/v1/file/mv` | Move File |
|
||||
| `get_parent_folder` | `/api/v1/file/parent_folder` | Get Parent Folder |
|
||||
| `rename` | `/api/v1/file/rename` | Rename File |
|
||||
| `rm` | `/api/v1/file/rm` | Remove File |
|
||||
| `get_root_folder` | `/api/v1/file/root_folder` | Get Root Folder |
|
||||
| `upload` | `/api/v1/file/upload` | Upload File |
|
||||
|
||||
## File: `api/apps/sdk/session.py`
|
||||
| Function Name | URL Pattern | Notes |
|
||||
|---|---|---|
|
||||
| `agent_bot_completions` | `/api/v1/agentbots/<agent_id>/completions` | Agent Bot completion |
|
||||
| `begin_inputs` | `/api/v1/agentbots/<agent_id>/inputs` | Get Agent Bot inputs |
|
||||
| `agent_completions` | `/api/v1/agents/<agent_id>/completions` | Agent completion |
|
||||
| `create_agent_session` | `/api/v1/agents/<agent_id>/sessions` | Create Agent Session |
|
||||
| `list_agent_session` | `/api/v1/agents/<agent_id>/sessions` | List Agent Sessions |
|
||||
| `delete_agent_session` | `/api/v1/agents/<agent_id>/sessions` | Delete Agent Session |
|
||||
| `agents_completion_openai_compatibility` | `/api/v1/agents_openai/<agent_id>/chat/completions` | OpenAI compatible Agent completion |
|
||||
| `chatbot_completions` | `/api/v1/chatbots/<dialog_id>/completions` | Chatbot completion |
|
||||
| `chatbots_inputs` | `/api/v1/chatbots/<dialog_id>/info` | Chatbot info |
|
||||
| `chat_completion` | `/api/v1/chats/<chat_id>/completions` | Chat completion |
|
||||
| `create` | `/api/v1/chats/<chat_id>/sessions` | Create Chat Session |
|
||||
| `list_session` | `/api/v1/chats/<chat_id>/sessions` | List Chat Sessions |
|
||||
| `delete` | `/api/v1/chats/<chat_id>/sessions` | Delete Chat Session |
|
||||
| `update` | `/api/v1/chats/<chat_id>/sessions/<session_id>` | Update Chat Session |
|
||||
| `chat_completion_openai_like` | `/api/v1/chats_openai/<chat_id>/chat/completions` | OpenAI compatible Chat completion |
|
||||
| `ask_about_embedded` | `/api/v1/searchbots/ask` | Searchbot Ask |
|
||||
| `detail_share_embedded` | `/api/v1/searchbots/detail` | Searchbot Detail |
|
||||
| `mindmap` | `/api/v1/searchbots/mindmap` | Searchbot Mindmap |
|
||||
| `related_questions_embedded` | `/api/v1/searchbots/related_questions` | Searchbot Related Questions |
|
||||
| `retrieval_test_embedded` | `/api/v1/searchbots/retrieval_test` | Searchbot Retrieval Test |
|
||||
| `ask_about` | `/api/v1/sessions/ask` | Session Ask |
|
||||
| `related_questions` | `/api/v1/sessions/related_questions` | Session Related Questions |
|
||||
@@ -0,0 +1,45 @@
|
||||
# RAGFlow API 接口文档索引 (Unofficial Detailed Guide)
|
||||
|
||||
本文档汇集了 RAGFlow 核心模块的 API 详解。所有文档均遵循 **Zero Omissions (无省略)** 原则，全字段展开并包含中文注释。
|
||||
|
||||
## 📚 1. 知识库与文档管理 (Knowledge & Documents)
|
||||
核心的数据管理模块，负责上传文件、解析文档与建立索引。
|
||||
|
||||
- **[知识库管理 (Dataset)](./RAGFlow_Dataset接口详解.md)**
|
||||
- 涵盖知识库的创建、列表查询、更新、删除等接口。
|
||||
- **[文档处理 (Document)](./RAGFlow_Document接口详解.md)**
|
||||
- 涵盖文档的上传 (Upload)、解析配置更新 (Update)、解析状态查询 (Run Status)。
|
||||
- **切片管理**: 解析后的 Chunk 列表查询、增删改查。
|
||||
- **检索测试**: 直接对知识库进行召回测试 (Retrieval Test)。
|
||||
- **[文件管理 (File)](./RAGFlow_File接口详解.md)**
|
||||
- 类似网盘的文件操作体系。
|
||||
- **CRUD**: 上传、下载、列表。
|
||||
- **目录**: 文件夹创建、面包屑导航 (`get_all_parent_folders`)。
|
||||
- **操作**: 移动、重命名、删除、导入知识库 (`convert`).
|
||||
|
||||
## 💬 2. 聊天助手 (Chat Assistant)
|
||||
RAGFlow 原生的对话助手体系，基于 Assistant (Dialog) 模型。
|
||||
|
||||
- **[会话管理 (Chat Session)](./RAGFlow_Chat_Session接口详解.md)**
|
||||
- 管理 `/chats/` 下的会话生命周期。
|
||||
- 创建会话、获取历史记录、重命名、批量删除。
|
||||
- **[对话交互 (Chat Completion)](./RAGFlow_Chat_Completion接口详解.md)**
|
||||
- **Core Chat**: 原生流式对话 (`/chats/<id>/completions`), 支持引用 (`quote`)。
|
||||
- **OpenAI Compatible**: 完美兼容 OpenAI `/v1/chat/completions` 协议。
|
||||
- **Embedded Bot**: 面向 C 端嵌入窗口的对话接口 (`/chatbots/`).
|
||||
|
||||
## 🤖 3. Agent 与 机器人 (Agent & Bots)
|
||||
基于 Graph (DAG) 编排的复杂应用与各类机器人扩展。
|
||||
|
||||
- **[Agent 与 Dify 兼容 (Agent & Dify)](./RAGFlow_Agent_Dify接口详解.md)**
|
||||
- **Agent Session**: Agent 的会话管理与流式对话 (`agent_completions`)。
|
||||
- **Dify Adapter**: 兼容 Dify 协议的检索接口 (`retrieval`).
|
||||
- **[SearchBot 与 AgentBot](./RAGFlow_SearchBot_AgentBot接口详解.md)**
|
||||
- **SearchBot**: 纯搜索机器人，支持思维导图 (`mindmap`)、相关问题 (`related_questions`).
|
||||
- **AgentBot**: 嵌入式 Agent，支持前置表单 (`begin_inputs`).
|
||||
- **Agent OpenAI**: Agent 的 OpenAI 兼容接口。
|
||||
|
||||
## 🛠️ 4. 其他 (Extras)
|
||||
- **[通用与补充接口 (Session Extras)](./RAGFlow_Session_Extra接口详解.md)**
|
||||
- **引用详情**: 获取 SearchBot 引用来源 (`detail_share_embedded`).
|
||||
- **通用问答**: 内部调试用的直接问答 (`ask_about`).
|
||||
@@ -0,0 +1,68 @@
|
||||
package xiaozhi.modules.knowledge.dto;
|
||||
|
||||
import java.io.Serializable;
|
||||
import java.util.Date;
|
||||
import java.util.Map;
|
||||
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import lombok.Data;
|
||||
|
||||
/**
|
||||
* 文档 DTO
|
||||
*/
|
||||
@Data
|
||||
@Schema(description = "知识库文档")
|
||||
public class DocumentDTO implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "本地ID")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "知识库ID")
|
||||
private String datasetId;
|
||||
|
||||
@Schema(description = "RAGFlow文档ID")
|
||||
private String documentId;
|
||||
|
||||
@Schema(description = "文档名称")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "文件大小")
|
||||
private Long size;
|
||||
|
||||
@Schema(description = "文件类型")
|
||||
private String type;
|
||||
|
||||
@Schema(description = "分块方法")
|
||||
private String chunkMethod;
|
||||
|
||||
@Schema(description = "解析配置")
|
||||
private Map<String, Object> parserConfig;
|
||||
|
||||
@Schema(description = "处理状态 (1:解析中 3:成功 4:失败)")
|
||||
private Integer status;
|
||||
|
||||
@Schema(description = "错误信息")
|
||||
private String error;
|
||||
|
||||
@Schema(description = "分块数量")
|
||||
private Integer chunkCount;
|
||||
|
||||
@Schema(description = "Token数量")
|
||||
private Long tokenCount;
|
||||
|
||||
@Schema(description = "是否启用")
|
||||
private Integer enabled;
|
||||
|
||||
@Schema(description = "创建时间")
|
||||
private Date createdAt;
|
||||
|
||||
@Schema(description = "更新时间")
|
||||
private Date updatedAt;
|
||||
|
||||
@Schema(description = "上传进度 (虚拟字段)")
|
||||
private Double progress;
|
||||
|
||||
@Schema(description = "缩略图/预览图 (虚拟字段)")
|
||||
private String thumbnail;
|
||||
}
|
||||
@@ -26,9 +26,30 @@ public class KnowledgeBaseDTO implements Serializable {
|
||||
@Schema(description = "知识库名称")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "知识库头像(Base64)")
|
||||
private String avatar;
|
||||
|
||||
@Schema(description = "知识库描述")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "嵌入模型名称")
|
||||
private String embeddingModel;
|
||||
|
||||
@Schema(description = "权限设置: me/team")
|
||||
private String permission;
|
||||
|
||||
@Schema(description = "分块方法")
|
||||
private String chunkMethod;
|
||||
|
||||
@Schema(description = "解析器配置(JSON String)")
|
||||
private String parserConfig;
|
||||
|
||||
@Schema(description = "分块总数")
|
||||
private Long chunkCount;
|
||||
|
||||
@Schema(description = "总Token数")
|
||||
private Long tokenNum;
|
||||
|
||||
@Schema(description = "状态(0:禁用 1:启用)")
|
||||
private Integer status;
|
||||
|
||||
|
||||
+27
-4
@@ -6,10 +6,12 @@ import java.util.Date;
|
||||
import java.util.Map;
|
||||
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import lombok.Data;
|
||||
|
||||
@Data
|
||||
@Schema(description = "知识库文档")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public class KnowledgeFilesDTO implements Serializable {
|
||||
|
||||
@Serial
|
||||
@@ -35,7 +37,19 @@ public class KnowledgeFilesDTO implements Serializable {
|
||||
@Schema(description = "文件路径")
|
||||
private String filePath;
|
||||
|
||||
@Schema(description = "元数据字段")
|
||||
@Schema(description = "解析进度 (0.0 ~ 1.0)")
|
||||
private Double progress;
|
||||
|
||||
@Schema(description = "缩略图 (Base64 或 URL)")
|
||||
private String thumbnail;
|
||||
|
||||
@Schema(description = "解析耗时 (单位: 秒)")
|
||||
private Double processDuration;
|
||||
|
||||
@Schema(description = "来源类型 (local, s3, url 等)")
|
||||
private String sourceType;
|
||||
|
||||
@Schema(description = "元数据字段 (Map 格式)")
|
||||
private Map<String, Object> metaFields;
|
||||
|
||||
@Schema(description = "分块方法")
|
||||
@@ -44,10 +58,10 @@ public class KnowledgeFilesDTO implements Serializable {
|
||||
@Schema(description = "解析器配置")
|
||||
private Map<String, Object> parserConfig;
|
||||
|
||||
@Schema(description = "状态")
|
||||
private Integer status;
|
||||
@Schema(description = "可用状态 (1: 启用/正常, 0: 禁用/失效)")
|
||||
private String status;
|
||||
|
||||
@Schema(description = "文档解析状态")
|
||||
@Schema(description = "运行状态 (UNSTART/RUNNING/CANCEL/DONE/FAIL)")
|
||||
private String run;
|
||||
|
||||
@Schema(description = "创建者")
|
||||
@@ -62,6 +76,15 @@ public class KnowledgeFilesDTO implements Serializable {
|
||||
@Schema(description = "更新时间")
|
||||
private Date updatedAt;
|
||||
|
||||
@Schema(description = "分块数量")
|
||||
private Integer chunkCount;
|
||||
|
||||
@Schema(description = "Token数量")
|
||||
private Long tokenCount;
|
||||
|
||||
@Schema(description = "解析错误信息")
|
||||
private String error;
|
||||
|
||||
// 文档解析状态常量定义
|
||||
private static final Integer STATUS_UNSTART = 0;
|
||||
private static final Integer STATUS_RUNNING = 1;
|
||||
|
||||
@@ -0,0 +1,421 @@
|
||||
package xiaozhi.modules.knowledge.dto.agent;
|
||||
|
||||
import lombok.*;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import java.io.Serializable;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import jakarta.validation.constraints.*;
|
||||
|
||||
@Schema(description = "智能体 (Agent) 管理聚合 DTO")
|
||||
public class AgentDTO {
|
||||
|
||||
// ========== 1. Agent 管理 (CRUD) - 对应 RAGFlow_Agent接口详解 ==========
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Agent 创建请求")
|
||||
public static class CreateReq implements Serializable {
|
||||
@Schema(description = "Agent 标题", requiredMode = Schema.RequiredMode.REQUIRED, example = "My Agent")
|
||||
@NotBlank(message = "Agent 标题不能为空")
|
||||
@JsonProperty("title")
|
||||
private String title;
|
||||
|
||||
@Schema(description = "DSL 定义 (画布 JSON)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotNull(message = "DSL 定义不能为空")
|
||||
@JsonProperty("dsl")
|
||||
private Map<String, Object> dsl;
|
||||
|
||||
@Schema(description = "描述", example = "这是一个测试 Agent")
|
||||
@JsonProperty("description")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "头像 URL", example = "http://example.com/avatar.png")
|
||||
@JsonProperty("avatar")
|
||||
private String avatar;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Agent 更新请求")
|
||||
public static class UpdateReq implements Serializable {
|
||||
@Schema(description = "Agent 标题", example = "Updated Agent")
|
||||
@JsonProperty("title")
|
||||
private String title;
|
||||
|
||||
@Schema(description = "DSL 定义 (画布 JSON)")
|
||||
@JsonProperty("dsl")
|
||||
private Map<String, Object> dsl;
|
||||
|
||||
@Schema(description = "描述")
|
||||
@JsonProperty("description")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "头像 URL")
|
||||
@JsonProperty("avatar")
|
||||
private String avatar;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Agent 列表请求")
|
||||
public static class ListReq implements Serializable {
|
||||
@Schema(description = "页码", defaultValue = "1")
|
||||
@JsonProperty("page")
|
||||
@Builder.Default
|
||||
private Integer page = 1;
|
||||
|
||||
@Schema(description = "每页大小", defaultValue = "10")
|
||||
@JsonProperty("page_size")
|
||||
@Builder.Default
|
||||
private Integer pageSize = 10;
|
||||
|
||||
@Schema(description = "排序字段", defaultValue = "update_time")
|
||||
@JsonProperty("orderby")
|
||||
@Builder.Default
|
||||
private String orderby = "update_time";
|
||||
|
||||
@Schema(description = "是否降序", defaultValue = "true")
|
||||
@JsonProperty("desc")
|
||||
@Builder.Default
|
||||
private Boolean desc = true;
|
||||
|
||||
@Schema(description = "Agent ID 过滤")
|
||||
@JsonProperty("id")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "标题模糊搜索")
|
||||
@JsonProperty("title")
|
||||
private String title;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Agent 响应对象")
|
||||
public static class AgentVO implements Serializable {
|
||||
@Schema(description = "Agent ID")
|
||||
@JsonProperty("id")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "标题")
|
||||
@JsonProperty("title")
|
||||
private String title;
|
||||
|
||||
@Schema(description = "描述")
|
||||
@JsonProperty("description")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "头像")
|
||||
@JsonProperty("avatar")
|
||||
private String avatar;
|
||||
|
||||
@Schema(description = "DSL 定义")
|
||||
@JsonProperty("dsl")
|
||||
private Map<String, Object> dsl;
|
||||
|
||||
@Schema(description = "创建者 ID")
|
||||
@JsonProperty("user_id")
|
||||
private String userId;
|
||||
|
||||
@Schema(description = "画布分类")
|
||||
@JsonProperty("canvas_category")
|
||||
private String canvasCategory;
|
||||
|
||||
@Schema(description = "创建时间 (时间戳)")
|
||||
@JsonProperty("create_time")
|
||||
private Long createTime;
|
||||
|
||||
@Schema(description = "更新时间 (时间戳)")
|
||||
@JsonProperty("update_time")
|
||||
private Long updateTime;
|
||||
}
|
||||
|
||||
// ========== 2. Webhook 调试与追踪 - 对应 RAGFlow_Agent接口详解 ==========
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Webhook 触发请求 (参数动态)")
|
||||
public static class WebhookTriggerReq implements Serializable {
|
||||
@Schema(description = "输入变量", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotNull(message = "输入变量不能为空")
|
||||
@JsonProperty("inputs")
|
||||
private Map<String, Object> inputs;
|
||||
|
||||
@Schema(description = "查询词", example = "Hello")
|
||||
@JsonProperty("query")
|
||||
private String query;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Webhook 追踪请求")
|
||||
public static class WebhookTraceReq implements Serializable {
|
||||
@Schema(description = "时间戳游标", example = "1700000000.0")
|
||||
@JsonProperty("since_ts")
|
||||
private Double sinceTs;
|
||||
|
||||
@Schema(description = "Webhook ID")
|
||||
@JsonProperty("webhook_id")
|
||||
private String webhookId;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Webhook 追踪响应")
|
||||
public static class WebhookTraceVO implements Serializable {
|
||||
@Schema(description = "Webhook ID")
|
||||
@JsonProperty("webhook_id")
|
||||
private String webhookId;
|
||||
|
||||
@Schema(description = "是否结束")
|
||||
@JsonProperty("finished")
|
||||
private Boolean finished;
|
||||
|
||||
@Schema(description = "下一次查询的时间戳游标")
|
||||
@JsonProperty("next_since_ts")
|
||||
private Double nextSinceTs;
|
||||
|
||||
@Schema(description = "事件列表")
|
||||
@JsonProperty("events")
|
||||
private List<TraceEvent> events;
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "追踪事件项")
|
||||
public static class TraceEvent implements Serializable {
|
||||
@Schema(description = "时间戳")
|
||||
@JsonProperty("ts")
|
||||
private Double ts;
|
||||
|
||||
@Schema(description = "事件类型")
|
||||
@JsonProperty("event")
|
||||
private String event;
|
||||
|
||||
@Schema(description = "事件数据")
|
||||
@JsonProperty("data")
|
||||
private Object data;
|
||||
}
|
||||
}
|
||||
|
||||
// ========== 3. Agent 会话 (Session) - 对应 RAGFlow_Agent_Dify接口详解 ==========
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Session 创建请求")
|
||||
public static class SessionCreateReq implements Serializable {
|
||||
@Schema(description = "用户 ID")
|
||||
@JsonProperty("user_id")
|
||||
private String userId;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Session 列表请求")
|
||||
public static class SessionListReq implements Serializable {
|
||||
@Schema(description = "页码", defaultValue = "1")
|
||||
@JsonProperty("page")
|
||||
@Builder.Default
|
||||
private Integer page = 1;
|
||||
|
||||
@Schema(description = "每页大小", defaultValue = "10")
|
||||
@JsonProperty("page_size")
|
||||
@Builder.Default
|
||||
private Integer pageSize = 10;
|
||||
|
||||
@Schema(description = "排序字段", defaultValue = "create_time")
|
||||
@JsonProperty("orderby")
|
||||
@Builder.Default
|
||||
private String orderby = "create_time";
|
||||
|
||||
@Schema(description = "是否降序", defaultValue = "true")
|
||||
@JsonProperty("desc")
|
||||
@Builder.Default
|
||||
private Boolean desc = true;
|
||||
|
||||
@Schema(description = "Session ID")
|
||||
@JsonProperty("id")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "用户 ID")
|
||||
@JsonProperty("user_id")
|
||||
private String userId;
|
||||
|
||||
@Schema(description = "是否返回 DSL")
|
||||
@JsonProperty("dsl")
|
||||
@Builder.Default
|
||||
private Boolean dsl = false;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Session 批量删除请求")
|
||||
public static class SessionBatchDeleteReq implements Serializable {
|
||||
@Schema(description = "会话 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("ids")
|
||||
@NotEmpty(message = "ID列表不能为空")
|
||||
private List<String> ids;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Session 响应对象")
|
||||
public static class SessionVO implements Serializable {
|
||||
@Schema(description = "Session ID")
|
||||
@JsonProperty("id")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "Agent ID")
|
||||
@JsonProperty("agent_id")
|
||||
private String agentId;
|
||||
|
||||
@Schema(description = "用户 ID")
|
||||
@JsonProperty("user_id")
|
||||
private String userId;
|
||||
|
||||
@Schema(description = "来源")
|
||||
@JsonProperty("source")
|
||||
private String source;
|
||||
|
||||
@Schema(description = "DSL 定义")
|
||||
@JsonProperty("dsl")
|
||||
private Map<String, Object> dsl;
|
||||
|
||||
@Schema(description = "消息列表")
|
||||
@JsonProperty("messages")
|
||||
private List<Map<String, Object>> messages;
|
||||
}
|
||||
|
||||
// ========== 4. Agent 对话 (Completion) - 对应 RAGFlow_Agent_Dify接口详解 ==========
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Completion 对话请求")
|
||||
public static class CompletionReq implements Serializable {
|
||||
@Schema(description = "会话 ID", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotBlank(message = "会话 ID 不能为空")
|
||||
@JsonProperty("session_id")
|
||||
private String sessionId;
|
||||
|
||||
@Schema(description = "用户问题")
|
||||
@JsonProperty("question")
|
||||
private String question;
|
||||
|
||||
@Schema(description = "是否流式返回", defaultValue = "true")
|
||||
@JsonProperty("stream")
|
||||
@Builder.Default
|
||||
private Boolean stream = true;
|
||||
|
||||
@Schema(description = "是否返回追踪信息", defaultValue = "false")
|
||||
@JsonProperty("return_trace")
|
||||
@Builder.Default
|
||||
private Boolean returnTrace = false;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Completion 对话响应")
|
||||
public static class CompletionVO implements Serializable {
|
||||
@Schema(description = "会话 ID")
|
||||
@JsonProperty("id")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "回复内容")
|
||||
@JsonProperty("content")
|
||||
private String content;
|
||||
|
||||
@Schema(description = "引用来源")
|
||||
@JsonProperty("reference")
|
||||
private Map<String, Object> reference;
|
||||
|
||||
@Schema(description = "追踪信息")
|
||||
@JsonProperty("trace")
|
||||
private List<Object> trace;
|
||||
}
|
||||
|
||||
// ========== 5. Dify 兼容检索 - 对应 RAGFlow_Agent_Dify接口详解 ==========
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Dify 兼容检索请求")
|
||||
public static class DifyRetrievalReq implements Serializable {
|
||||
@Schema(description = "知识库 ID")
|
||||
@JsonProperty("knowledge_id")
|
||||
private String knowledgeId;
|
||||
|
||||
@Schema(description = "查询词")
|
||||
@JsonProperty("query")
|
||||
private String query;
|
||||
|
||||
@Schema(description = "检索设置")
|
||||
@JsonProperty("retrieval_setting")
|
||||
private Map<String, Object> retrievalSetting;
|
||||
|
||||
@Schema(description = "元数据过滤条件")
|
||||
@JsonProperty("metadata_condition")
|
||||
private Map<String, Object> metadataCondition;
|
||||
|
||||
@Schema(description = "是否使用知识图谱")
|
||||
@JsonProperty("use_kg")
|
||||
private Boolean useKg;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "Dify 兼容检索响应")
|
||||
public static class DifyRetrievalVO implements Serializable {
|
||||
@Schema(description = "检索结果列表")
|
||||
@JsonProperty("records")
|
||||
private List<Record> records;
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "检索记录")
|
||||
public static class Record implements Serializable {
|
||||
@Schema(description = "内容")
|
||||
@JsonProperty("content")
|
||||
private String content;
|
||||
|
||||
@Schema(description = "相似度分数")
|
||||
@JsonProperty("score")
|
||||
private Double score;
|
||||
|
||||
@Schema(description = "标题")
|
||||
@JsonProperty("title")
|
||||
private String title;
|
||||
|
||||
@Schema(description = "元数据")
|
||||
@JsonProperty("metadata")
|
||||
private Map<String, Object> metadata;
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,126 @@
|
||||
package xiaozhi.modules.knowledge.dto.bot;
|
||||
|
||||
import lombok.*;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import java.io.Serializable;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import jakarta.validation.constraints.*;
|
||||
|
||||
@Schema(description = "外部机器人 (Bot) 聚合 DTO")
|
||||
public class BotDTO {
|
||||
|
||||
// ========== 1. SearchBot (检索机器人) ==========
|
||||
|
||||
// 对应 /api/v1/searchbots/ask
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "SearchBot 提问请求")
|
||||
public static class SearchAskReq implements Serializable {
|
||||
@Schema(description = "用户问题", requiredMode = Schema.RequiredMode.REQUIRED, example = "What is RAG?")
|
||||
@NotBlank(message = "问题不能为空")
|
||||
@JsonProperty("question")
|
||||
private String question;
|
||||
|
||||
@Schema(description = "是否返回引用", defaultValue = "false")
|
||||
@JsonProperty("quote")
|
||||
@Builder.Default
|
||||
private Boolean quote = false;
|
||||
|
||||
@Schema(description = "是否流式返回", defaultValue = "true")
|
||||
@JsonProperty("stream")
|
||||
@Builder.Default
|
||||
private Boolean stream = true;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "SearchBot 提问响应")
|
||||
public static class SearchAskVO implements Serializable {
|
||||
@Schema(description = "回答内容")
|
||||
@JsonProperty("answer")
|
||||
private String answer;
|
||||
|
||||
@Schema(description = "引用来源 (Value 结构通常对应 RetrievalDTO.HitVO)")
|
||||
@JsonProperty("reference")
|
||||
private Map<String, Object> reference;
|
||||
}
|
||||
|
||||
// 对应 /api/v1/searchbots/related_questions
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "相关问题请求")
|
||||
public static class RelatedQuestionReq implements Serializable {
|
||||
@Schema(description = "用户问题", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotBlank(message = "问题不能为空")
|
||||
@JsonProperty("question")
|
||||
private String question;
|
||||
}
|
||||
|
||||
// 对应 /api/v1/searchbots/mindmap
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "思维导图请求")
|
||||
public static class MindMapReq implements Serializable {
|
||||
@Schema(description = "用户问题", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotBlank(message = "问题不能为空")
|
||||
@JsonProperty("question")
|
||||
private String question;
|
||||
}
|
||||
|
||||
// ========== 2. AgentBot (嵌入式 Agent) ==========
|
||||
|
||||
// 对应 /api/v1/agentbots/{id}/inputs
|
||||
@Data
|
||||
@Builder
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "AgentBot 输入参数请求")
|
||||
public static class AgentInputsReq implements Serializable {
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "AgentBot 输入参数定义响应")
|
||||
public static class AgentInputsVO implements Serializable {
|
||||
@Schema(description = "表单变量定义列表")
|
||||
@JsonProperty("variables")
|
||||
private List<Map<String, Object>> variables;
|
||||
}
|
||||
|
||||
// 对应 /api/v1/agentbots/{id}/completions
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "AgentBot 对话请求")
|
||||
public static class AgentCompletionReq implements Serializable {
|
||||
@Schema(description = "输入参数值")
|
||||
@JsonProperty("inputs")
|
||||
private Map<String, Object> inputs;
|
||||
|
||||
@Schema(description = "用户查询", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotBlank(message = "查询内容不能为空")
|
||||
@JsonProperty("question")
|
||||
private String question;
|
||||
|
||||
@Schema(description = "是否流式返回", defaultValue = "true")
|
||||
@JsonProperty("stream")
|
||||
@Builder.Default
|
||||
private Boolean stream = true;
|
||||
|
||||
@Schema(description = "会话 ID")
|
||||
@JsonProperty("session_id")
|
||||
private String sessionId;
|
||||
}
|
||||
}
|
||||
+50
@@ -0,0 +1,50 @@
|
||||
package xiaozhi.modules.knowledge.dto.chat;
|
||||
|
||||
import java.io.Serializable;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import lombok.Data;
|
||||
|
||||
/**
|
||||
* 聊天对话请求 DTO (OpenAI 兼容格式)
|
||||
*/
|
||||
@Data
|
||||
@Schema(description = "聊天对话请求")
|
||||
public class ChatCompletionRequest implements Serializable {
|
||||
|
||||
@Schema(description = "模型标识 (对应 agent_id 或 bot_id)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("model")
|
||||
private String model;
|
||||
|
||||
@Schema(description = "对话消息列表", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("messages")
|
||||
private List<Message> messages;
|
||||
|
||||
@Schema(description = "是否流式返回", defaultValue = "false")
|
||||
@JsonProperty("stream")
|
||||
private Boolean stream = false;
|
||||
|
||||
@Schema(description = "温度系数 (0-1)", defaultValue = "0.7")
|
||||
@JsonProperty("temperature")
|
||||
private Double temperature;
|
||||
|
||||
@Schema(description = "Session ID (可选，用于延续会话)")
|
||||
@JsonProperty("session_id")
|
||||
private String sessionId;
|
||||
|
||||
@Schema(description = "其他RAGFlow特定参数 (可选)")
|
||||
private Map<String, Object> extra;
|
||||
|
||||
@Data
|
||||
public static class Message implements Serializable {
|
||||
@Schema(description = "角色 (system, user, assistant)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String role;
|
||||
|
||||
@Schema(description = "内容", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String content;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,523 @@
|
||||
package xiaozhi.modules.knowledge.dto.chat;
|
||||
|
||||
import lombok.*;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import java.io.Serializable;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import jakarta.validation.constraints.*;
|
||||
|
||||
/**
|
||||
* 对话管理聚合 DTO
|
||||
* <p>
|
||||
* 容器类，内含对话助手、会话和消息的所有请求/响应对象。
|
||||
* </p>
|
||||
*/
|
||||
@Schema(description = "对话管理聚合 DTO")
|
||||
public class ChatDTO {
|
||||
|
||||
// ========== 1. 对话助手 (Assistant/Bot) 相关 ==========
|
||||
|
||||
/**
|
||||
* 提示词配置
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "提示词配置")
|
||||
public static class PromptConfig implements Serializable {
|
||||
|
||||
@Schema(description = "系统提示词", example = "你是一个专业的客服助手...")
|
||||
@JsonProperty("prompt")
|
||||
private String systemPrompt;
|
||||
|
||||
@Schema(description = "开场白", example = "您好，我是您的智能助手，请问有什么可以帮您？")
|
||||
private String opener;
|
||||
|
||||
@Schema(description = "空结果回复", example = "抱歉，我没有找到相关信息。")
|
||||
@JsonProperty("empty_response")
|
||||
private String emptyResponse;
|
||||
|
||||
@Schema(description = "是否展示引用", example = "true")
|
||||
@JsonProperty("show_quote")
|
||||
private Boolean quote;
|
||||
|
||||
@Schema(description = "是否启用 TTS", example = "false")
|
||||
private Boolean tts;
|
||||
|
||||
@Schema(description = "相似度阈值 (0.0 - 1.0)", example = "0.2")
|
||||
@JsonProperty("similarity_threshold")
|
||||
private Float similarityThreshold;
|
||||
|
||||
@Schema(description = "关键词相似度权重 (0.0 - 1.0)", example = "0.7")
|
||||
@JsonProperty("keywords_similarity_weight")
|
||||
private Float vectorSimilarityWeight;
|
||||
|
||||
@Schema(description = "检索 Top N", example = "6")
|
||||
@JsonProperty("top_n")
|
||||
private Integer topK;
|
||||
|
||||
@Schema(description = "Rerank 模型", example = "rerank_model_001")
|
||||
@JsonProperty("rerank_model")
|
||||
private String rerankId;
|
||||
|
||||
@Schema(description = "是否启用多轮对话优化", example = "false")
|
||||
@JsonProperty("refine_multiturn")
|
||||
private Boolean refineMultigraph;
|
||||
|
||||
@Schema(description = "变量列表")
|
||||
private List<Map<String, Object>> variables;
|
||||
}
|
||||
|
||||
/**
|
||||
* LLM 配置
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "LLM 模型配置")
|
||||
public static class LLMConfig implements Serializable {
|
||||
|
||||
@NotBlank(message = "模型名称不能为空")
|
||||
@Schema(description = "模型名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "gpt-4")
|
||||
@JsonProperty("model_name")
|
||||
private String modelName;
|
||||
|
||||
@Schema(description = "温度参数 (0.0 - 2.0)", example = "0.7")
|
||||
private Float temperature;
|
||||
|
||||
@Schema(description = "Top P 采样", example = "0.9")
|
||||
@JsonProperty("top_p")
|
||||
private Float topP;
|
||||
|
||||
@Schema(description = "最大 Token 数", example = "4096")
|
||||
@JsonProperty("max_tokens")
|
||||
private Integer maxTokens;
|
||||
|
||||
@Schema(description = "存在惩罚", example = "0.0")
|
||||
@JsonProperty("presence_penalty")
|
||||
private Float presencePenalty;
|
||||
|
||||
@Schema(description = "频率惩罚", example = "0.0")
|
||||
@JsonProperty("frequency_penalty")
|
||||
private Float frequencyPenalty;
|
||||
}
|
||||
|
||||
/**
|
||||
* 创建助手请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "创建助手请求")
|
||||
public static class AssistantCreateReq implements Serializable {
|
||||
|
||||
@NotBlank(message = "助手名称不能为空")
|
||||
@Schema(description = "助手名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "智能客服助手")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "助手头像 (Base64 编码)", example = "")
|
||||
private String avatar;
|
||||
|
||||
@Schema(description = "关联的知识库 ID 列表", example = "[\"kb_001\", \"kb_002\"]")
|
||||
@JsonProperty("dataset_ids")
|
||||
private List<String> datasetIds;
|
||||
|
||||
@Schema(description = "助手描述", example = "这是一个智能客服助手")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "LLM 模型配置")
|
||||
@JsonProperty("llm")
|
||||
private LLMConfig llm;
|
||||
|
||||
@Schema(description = "提示词配置")
|
||||
@JsonProperty("prompt")
|
||||
private PromptConfig promptConfig;
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新助手请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "更新助手请求")
|
||||
public static class AssistantUpdateReq implements Serializable {
|
||||
|
||||
@Schema(description = "助手名称", example = "智能客服助手 V2")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "助手头像 (Base64 编码)", example = "")
|
||||
private String avatar;
|
||||
|
||||
@Schema(description = "关联的知识库 ID 列表", example = "[\"kb_001\", \"kb_002\"]")
|
||||
@JsonProperty("dataset_ids")
|
||||
private List<String> datasetIds;
|
||||
|
||||
@Schema(description = "助手描述", example = "这是一个智能客服助手")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "LLM 模型配置")
|
||||
@JsonProperty("llm")
|
||||
private LLMConfig llm;
|
||||
|
||||
@Schema(description = "提示词配置")
|
||||
@JsonProperty("prompt")
|
||||
private PromptConfig promptConfig;
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询助手列表请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "查询助手列表请求")
|
||||
public static class AssistantListReq implements Serializable {
|
||||
|
||||
@Schema(description = "页码 (从 1 开始)", example = "1")
|
||||
private Integer page;
|
||||
|
||||
@Schema(description = "每页数量", example = "30")
|
||||
@JsonProperty("page_size")
|
||||
private Integer pageSize;
|
||||
|
||||
@Schema(description = "按名称过滤 (模糊匹配)", example = "客服")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "排序字段: create_time / update_time", example = "create_time")
|
||||
private String orderby;
|
||||
|
||||
@Schema(description = "是否降序", example = "true")
|
||||
private Boolean desc;
|
||||
|
||||
@Schema(description = "按 ID 精确筛选", example = "assistant_001")
|
||||
private String id;
|
||||
}
|
||||
|
||||
/**
|
||||
* 助手详情 VO
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "助手详情 VO")
|
||||
public static class AssistantVO implements Serializable {
|
||||
|
||||
@Schema(description = "助手 ID", example = "assistant_001")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "租户 ID", example = "tenant_001")
|
||||
@JsonProperty("tenant_id")
|
||||
private String tenantId;
|
||||
|
||||
@Schema(description = "助手名称", example = "智能客服助手")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "助手头像", example = "")
|
||||
private String avatar;
|
||||
|
||||
@Schema(description = "关联的知识库 ID 列表")
|
||||
@JsonProperty("dataset_ids")
|
||||
private List<String> datasetIds;
|
||||
|
||||
@Schema(description = "关联的知识库列表 (详情)")
|
||||
private List<SimpleDatasetVO> datasets;
|
||||
|
||||
@Schema(description = "助手描述")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "LLM 模型配置")
|
||||
@JsonProperty("llm")
|
||||
private LLMConfig llm;
|
||||
|
||||
@Schema(description = "提示词配置")
|
||||
@JsonProperty("prompt")
|
||||
private PromptConfig promptConfig;
|
||||
|
||||
@Schema(description = "创建时间 (时间戳)", example = "1700000000000")
|
||||
@JsonProperty("create_time")
|
||||
private Long createTime;
|
||||
|
||||
@Schema(description = "更新时间 (时间戳)", example = "1700000001000")
|
||||
@JsonProperty("update_time")
|
||||
private Long updateTime;
|
||||
}
|
||||
|
||||
/**
|
||||
* 删除助手请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "删除助手请求")
|
||||
public static class AssistantDeleteReq implements Serializable {
|
||||
|
||||
@Schema(description = "要删除的助手 ID 列表", example = "[\"assistant_001\", \"assistant_002\"]")
|
||||
private List<String> ids;
|
||||
}
|
||||
|
||||
// ========== 2. 会话 (Session) 相关 ==========
|
||||
|
||||
/**
|
||||
* 创建会话请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "创建会话请求")
|
||||
public static class SessionCreateReq implements Serializable {
|
||||
|
||||
@Schema(description = "会话名称", example = "技术咨询会话")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "用户 ID", example = "user_001")
|
||||
@JsonProperty("user_id")
|
||||
private String userId;
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新会话请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "更新会话请求")
|
||||
public static class SessionUpdateReq implements Serializable {
|
||||
|
||||
@Schema(description = "会话名称", example = "技术咨询会话 - 更新")
|
||||
private String name;
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询会话列表请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "查询会话列表请求")
|
||||
public static class SessionListReq implements Serializable {
|
||||
|
||||
@Schema(description = "助手 ID", example = "assistant_001")
|
||||
@JsonProperty("assistant_id")
|
||||
private String assistantId;
|
||||
|
||||
@Schema(description = "页码 (从 1 开始)", example = "1")
|
||||
private Integer page;
|
||||
|
||||
@Schema(description = "每页数量", example = "30")
|
||||
@JsonProperty("page_size")
|
||||
private Integer pageSize;
|
||||
|
||||
@Schema(description = "按名称过滤", example = "技术")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "排序字段", example = "create_time")
|
||||
private String orderby;
|
||||
|
||||
@Schema(description = "是否降序", example = "true")
|
||||
private Boolean desc;
|
||||
|
||||
@Schema(description = "会话 ID 精确筛选", example = "session_001")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "用户标识筛选", example = "user_001")
|
||||
@JsonProperty("user_id")
|
||||
private String userId;
|
||||
}
|
||||
|
||||
/**
|
||||
* 会话详情 VO
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "会话详情 VO")
|
||||
public static class SessionVO implements Serializable {
|
||||
|
||||
@Schema(description = "会话 ID", example = "session_001")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "助手 ID", example = "assistant_001")
|
||||
@JsonProperty("chat_id")
|
||||
private String chatId;
|
||||
|
||||
@Schema(description = "助手 ID (兼容旧版)", example = "assistant_001")
|
||||
@JsonProperty("assistant_id")
|
||||
private String assistantId;
|
||||
|
||||
@Schema(description = "会话名称", example = "技术咨询会话")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "创建时间 (时间戳)", example = "1700000000000")
|
||||
@JsonProperty("create_time")
|
||||
private Long createTime;
|
||||
|
||||
@Schema(description = "更新时间 (时间戳)", example = "1700000001000")
|
||||
@JsonProperty("update_time")
|
||||
private Long updateTime;
|
||||
|
||||
@Schema(description = "创建日期", example = "2024-05-01 10:00:00")
|
||||
@JsonProperty("create_date")
|
||||
private String createDate;
|
||||
|
||||
@Schema(description = "更新日期", example = "2024-05-01 10:00:00")
|
||||
@JsonProperty("update_date")
|
||||
private String updateDate;
|
||||
|
||||
@Schema(description = "用户 ID", example = "user_001")
|
||||
@JsonProperty("user_id")
|
||||
private String userId;
|
||||
|
||||
@Schema(description = "对话历史消息列表")
|
||||
private List<Map<String, Object>> messages;
|
||||
}
|
||||
|
||||
/**
|
||||
* 删除会话请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "删除会话请求")
|
||||
public static class SessionDeleteReq implements Serializable {
|
||||
|
||||
@Schema(description = "要删除的会话 ID 列表", example = "[\"session_001\", \"session_002\"]")
|
||||
private List<String> ids;
|
||||
}
|
||||
|
||||
// ========== 3. 消息/对话 (Completion) 相关 ==========
|
||||
|
||||
/**
|
||||
* 发送消息请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "发送消息请求")
|
||||
public static class CompletionReq implements Serializable {
|
||||
|
||||
@NotBlank(message = "问题内容不能为空")
|
||||
@Schema(description = "用户问题", requiredMode = Schema.RequiredMode.REQUIRED, example = "请介绍一下你们的产品")
|
||||
private String question;
|
||||
|
||||
@Schema(description = "是否使用流式响应 (SSE)", example = "true")
|
||||
@Builder.Default
|
||||
private Boolean stream = true;
|
||||
|
||||
@NotBlank(message = "会话 ID 不能为空")
|
||||
@Schema(description = "会话 ID (可选，不传则创建新会话)", example = "session_001")
|
||||
@JsonProperty("session_id")
|
||||
private String sessionId;
|
||||
|
||||
@Schema(description = "是否展示引用", example = "true")
|
||||
private Boolean quote;
|
||||
|
||||
@Schema(description = "指定检索的文档 ID 列表 (逗号分隔)", example = "doc_001,doc_002")
|
||||
@JsonProperty("doc_ids")
|
||||
private String docIds;
|
||||
|
||||
@Schema(description = "元数据过滤条件")
|
||||
@JsonProperty("metadata_condition")
|
||||
private Map<String, Object> metadataCondition;
|
||||
}
|
||||
|
||||
/**
|
||||
* 消息响应 VO
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "消息响应 VO")
|
||||
public static class CompletionVO implements Serializable {
|
||||
|
||||
@Schema(description = "AI 回答内容")
|
||||
private String answer;
|
||||
|
||||
@Schema(description = "引用信息")
|
||||
private Reference reference;
|
||||
|
||||
@Schema(description = "会话 ID", example = "session_001")
|
||||
@JsonProperty("session_id")
|
||||
private String sessionId;
|
||||
|
||||
@Schema(description = "任务 ID (用于流式响应追踪)", example = "task_001")
|
||||
@JsonProperty("task_id")
|
||||
private String taskId;
|
||||
|
||||
/**
|
||||
* 引用信息 (检索命中结果)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "引用信息")
|
||||
public static class Reference implements Serializable {
|
||||
|
||||
@Schema(description = "命中的文档块列表")
|
||||
private List<xiaozhi.modules.knowledge.dto.document.RetrievalDTO.HitVO> chunks;
|
||||
|
||||
@Schema(description = "文档聚合信息")
|
||||
@JsonProperty("doc_aggs")
|
||||
private List<DocAgg> docAggs;
|
||||
}
|
||||
|
||||
/**
|
||||
* 文档聚合信息
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "文档聚合信息")
|
||||
public static class DocAgg implements Serializable {
|
||||
|
||||
@Schema(description = "文档 ID", example = "doc_001")
|
||||
@JsonProperty("doc_id")
|
||||
private String docId;
|
||||
|
||||
@Schema(description = "文档名称", example = "产品手册.pdf")
|
||||
@JsonProperty("doc_name")
|
||||
private String docName;
|
||||
|
||||
@Schema(description = "命中次数", example = "3")
|
||||
private Integer count;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 简易知识库 VO (用于 Assistant 列表)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "简易知识库 VO")
|
||||
public static class SimpleDatasetVO implements Serializable {
|
||||
@Schema(description = "知识库 ID")
|
||||
private String id;
|
||||
@Schema(description = "知识库名称")
|
||||
private String name;
|
||||
@Schema(description = "头像")
|
||||
private String avatar;
|
||||
@Schema(description = "分块数量")
|
||||
@JsonProperty("chunk_num")
|
||||
private Integer chunkNum;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,79 @@
|
||||
package xiaozhi.modules.knowledge.dto.common;
|
||||
|
||||
import lombok.*;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import java.io.Serializable;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import jakarta.validation.constraints.*;
|
||||
|
||||
@Schema(description = "通用扩展功能 DTO")
|
||||
public class CommonDTO {
|
||||
|
||||
// ========== 1. 引用详情 (detail_share_embedded) ==========
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "引用详情请求")
|
||||
public static class ReferenceDetailReq implements Serializable {
|
||||
@Schema(description = "切片 ID", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotBlank(message = "切片 ID 不能为空")
|
||||
@JsonProperty("chunk_id")
|
||||
private String chunkId;
|
||||
|
||||
@Schema(description = "知识库 ID")
|
||||
@JsonProperty("knowledge_id")
|
||||
private String knowledgeId;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "引用详情响应")
|
||||
public static class ReferenceDetailVO implements Serializable {
|
||||
@Schema(description = "切片 ID")
|
||||
@JsonProperty("chunk_id")
|
||||
private String chunkId;
|
||||
|
||||
@Schema(description = "完整内容")
|
||||
@JsonProperty("content_with_weight")
|
||||
private String contentWithWeight;
|
||||
|
||||
@Schema(description = "文档名称")
|
||||
@JsonProperty("doc_name")
|
||||
private String docName;
|
||||
|
||||
@Schema(description = "图片 ID 列表")
|
||||
@JsonProperty("img_id")
|
||||
private String imageId; // 注意：RAGFlow 有时返回 String 有时返回 List，需根据实际情况确认，暂定 String 用于 ID
|
||||
|
||||
@Schema(description = "文档 ID")
|
||||
@JsonProperty("doc_id")
|
||||
private String docId;
|
||||
}
|
||||
|
||||
// ========== 2. 通用问答 (ask_about) - 调试用 ==========
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "通用问答请求 (调试用)")
|
||||
public static class AskAboutReq implements Serializable {
|
||||
@Schema(description = "用户问题", requiredMode = Schema.RequiredMode.REQUIRED, example = "What is this dataset about?")
|
||||
@NotBlank(message = "问题不能为空")
|
||||
@JsonProperty("question")
|
||||
private String question;
|
||||
|
||||
@Schema(description = "数据集 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotEmpty(message = "数据集列表不能为空")
|
||||
@JsonProperty("dataset_ids")
|
||||
private List<String> datasetIds;
|
||||
}
|
||||
|
||||
// 响应通常复用 String 或者简单的 Map 结构，视具体实现而定，暂不定义专用 VO
|
||||
}
|
||||
@@ -0,0 +1,447 @@
|
||||
package xiaozhi.modules.knowledge.dto.dataset;
|
||||
|
||||
import lombok.*;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import java.io.Serializable;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import jakarta.validation.constraints.*;
|
||||
|
||||
/**
|
||||
* 知识库管理聚合 DTO
|
||||
* <p>
|
||||
* 容器类，内含知识库模块所有请求/响应对象的静态内部类定义。
|
||||
* </p>
|
||||
*/
|
||||
@Schema(description = "知识库管理聚合 DTO")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public class DatasetDTO {
|
||||
|
||||
// ========== 通用内部类 ==========
|
||||
|
||||
/**
|
||||
* 解析器配置
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "解析器配置")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class ParserConfig implements Serializable {
|
||||
|
||||
@Schema(description = "分块 token 数量", example = "128")
|
||||
@JsonProperty("chunk_token_num")
|
||||
private Integer chunkTokenNum;
|
||||
|
||||
@Schema(description = "分隔符", example = "\\n!?;。；！？")
|
||||
private String delimiter;
|
||||
|
||||
@Schema(description = "布局识别模型: DeepDOC / Simple", example = "DeepDOC")
|
||||
@JsonProperty("layout_recognize")
|
||||
private String layoutRecognize;
|
||||
|
||||
@Schema(description = "是否将 Excel 转为 HTML", example = "false")
|
||||
private Boolean html4excel;
|
||||
|
||||
@Schema(description = "自动生成关键词数量 (0 表示关闭)", example = "0")
|
||||
@JsonProperty("auto_keywords")
|
||||
private Integer autoKeywords;
|
||||
|
||||
@Schema(description = "自动生成问题数量 (0 表示关闭)", example = "0")
|
||||
@JsonProperty("auto_questions")
|
||||
private Integer autoQuestions;
|
||||
}
|
||||
|
||||
// ========== 请求类 ==========
|
||||
|
||||
/**
|
||||
* 创建知识库请求 (映射接口 1: create)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "创建知识库请求")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class CreateReq implements Serializable {
|
||||
|
||||
@NotBlank(message = "知识库名称不能为空")
|
||||
@Schema(description = "知识库名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "my_dataset")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "知识库头像 (Base64 编码)", example = "")
|
||||
private String avatar;
|
||||
|
||||
@Schema(description = "知识库描述", example = "用于存储产品文档")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "嵌入模型名称", example = "BAAI/bge-large-zh-v1.5")
|
||||
@JsonProperty("embedding_model")
|
||||
private String embeddingModel;
|
||||
|
||||
@Schema(description = "权限设置: me / team", example = "me")
|
||||
private String permission;
|
||||
|
||||
@Schema(description = "分块方法: naive / manual / qa / table / paper / book / laws / presentation / picture / one / knowledge_graph / email", example = "naive")
|
||||
@JsonProperty("chunk_method")
|
||||
private String chunkMethod;
|
||||
|
||||
@Schema(description = "解析器配置")
|
||||
@JsonProperty("parser_config")
|
||||
private ParserConfig parserConfig;
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新知识库请求 (映射接口 4: update)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "更新知识库请求")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class UpdateReq implements Serializable {
|
||||
|
||||
@Schema(description = "知识库名称", example = "updated_dataset")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "知识库头像 (Base64 编码)", example = "")
|
||||
private String avatar;
|
||||
|
||||
@Schema(description = "知识库描述", example = "更新后的描述")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "权限设置: me / team", example = "team")
|
||||
private String permission;
|
||||
|
||||
@Schema(description = "嵌入模型名称", example = "BAAI/bge-large-zh-v1.5")
|
||||
@JsonProperty("embedding_model")
|
||||
private String embeddingModel;
|
||||
|
||||
@Schema(description = "分块方法: naive / manual / qa / table / paper / book / laws / presentation / picture / one / knowledge_graph / email", example = "naive")
|
||||
@JsonProperty("chunk_method")
|
||||
private String chunkMethod;
|
||||
|
||||
@Schema(description = "解析器配置")
|
||||
@JsonProperty("parser_config")
|
||||
private ParserConfig parserConfig;
|
||||
|
||||
@Schema(description = "PageRank 权重 (0-100)", example = "50")
|
||||
private Integer pagerank;
|
||||
}
|
||||
|
||||
/**
|
||||
* 查询知识库列表请求 (映射接口 3: list_datasets)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "查询知识库列表请求")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class ListReq implements Serializable {
|
||||
|
||||
@Schema(description = "页码 (从 1 开始)", example = "1")
|
||||
private Integer page;
|
||||
|
||||
@Schema(description = "每页数量", example = "30")
|
||||
@JsonProperty("page_size")
|
||||
private Integer pageSize;
|
||||
|
||||
@Schema(description = "排序字段: create_time / update_time", example = "create_time")
|
||||
private String orderby;
|
||||
|
||||
@Schema(description = "是否降序", example = "true")
|
||||
private Boolean desc;
|
||||
|
||||
@Schema(description = "按名称过滤 (模糊匹配)", example = "my_dataset")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "按知识库 ID 过滤", example = "abc123")
|
||||
private String id;
|
||||
}
|
||||
|
||||
/**
|
||||
* 批量删除知识库请求 (映射接口 2: delete)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "批量删除知识库请求")
|
||||
public static class BatchIdReq implements Serializable {
|
||||
|
||||
@NotNull(message = "知识库 ID 列表不能为空")
|
||||
@Size(min = 1, message = "至少需要一个知识库 ID")
|
||||
@Schema(description = "知识库 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED, example = "[\"id1\", \"id2\"]")
|
||||
private List<String> ids;
|
||||
}
|
||||
|
||||
/**
|
||||
* 运行 GraphRAG 请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "运行 GraphRAG 请求")
|
||||
public static class RunGraphRagReq implements Serializable {
|
||||
|
||||
@Schema(description = "实体类型列表", example = "[\"person\", \"organization\"]")
|
||||
@JsonProperty("entity_types")
|
||||
private List<String> entityTypes;
|
||||
|
||||
@Schema(description = "构建方法: light / fast / full", example = "light")
|
||||
private String method;
|
||||
}
|
||||
|
||||
/**
|
||||
* 运行 RAPTOR 请求
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "运行 RAPTOR 请求")
|
||||
public static class RunRaptorReq implements Serializable {
|
||||
|
||||
@Schema(description = "最大聚类数", example = "64")
|
||||
@JsonProperty("max_cluster")
|
||||
private Integer maxCluster;
|
||||
|
||||
@Schema(description = "自定义提示词", example = "请总结以下内容...")
|
||||
private String prompt;
|
||||
}
|
||||
|
||||
/**
|
||||
* 异步任务 ID 响应 VO (映射接口 7/8: run_graphrag/run_raptor)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "异步任务 ID 响应")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class TaskIdVO implements Serializable {
|
||||
|
||||
@Schema(description = "GraphRAG 任务 ID", example = "task_uuid_12345678")
|
||||
@JsonProperty("graphrag_task_id")
|
||||
private String graphragTaskId;
|
||||
|
||||
@Schema(description = "RAPTOR 任务 ID", example = "task_uuid_87654321")
|
||||
@JsonProperty("raptor_task_id")
|
||||
private String raptorTaskId;
|
||||
}
|
||||
|
||||
// ========== 响应类 ==========
|
||||
|
||||
/**
|
||||
* 知识库详情 VO (映射接口 1/3 的返回数据项)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "知识库详情 VO")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class InfoVO implements Serializable {
|
||||
|
||||
@Schema(description = "知识库 ID", example = "abc123")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "知识库名称", example = "my_dataset")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "知识库头像 (Base64 编码)", example = "")
|
||||
private String avatar;
|
||||
|
||||
@Schema(description = "租户 ID", example = "tenant_001")
|
||||
@JsonProperty("tenant_id")
|
||||
private String tenantId;
|
||||
|
||||
@Schema(description = "知识库描述", example = "用于存储产品文档")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "嵌入模型名称", example = "BAAI/bge-large-zh-v1.5")
|
||||
@JsonProperty("embedding_model")
|
||||
private String embeddingModel;
|
||||
|
||||
@Schema(description = "权限设置: me / team", example = "me")
|
||||
private String permission;
|
||||
|
||||
@Schema(description = "分块方法", example = "naive")
|
||||
@JsonProperty("chunk_method")
|
||||
private String chunkMethod;
|
||||
|
||||
@Schema(description = "解析器配置")
|
||||
@JsonProperty("parser_config")
|
||||
private ParserConfig parserConfig;
|
||||
|
||||
@Schema(description = "分块总数", example = "1024")
|
||||
@JsonProperty("chunk_count")
|
||||
private Long chunkCount;
|
||||
|
||||
@Schema(description = "文档总数", example = "50")
|
||||
@JsonProperty("document_count")
|
||||
private Long documentCount;
|
||||
|
||||
@Schema(description = "创建时间 (时间戳)", example = "1700000000000")
|
||||
@JsonProperty("create_time")
|
||||
private Long createTime;
|
||||
|
||||
@Schema(description = "更新时间 (时间戳)", example = "1700000001000")
|
||||
@JsonProperty("update_time")
|
||||
private Long updateTime;
|
||||
|
||||
@Schema(description = "总 Token 数", example = "102400")
|
||||
@JsonProperty("token_num")
|
||||
private Long tokenNum;
|
||||
|
||||
@Schema(description = "创建日期 (格式: yyyy-MM-dd HH:mm:ss)")
|
||||
@JsonProperty("create_date")
|
||||
private String createDate;
|
||||
|
||||
@Schema(description = "最后更新日期 (格式: yyyy-MM-dd HH:mm:ss)")
|
||||
@JsonProperty("update_date")
|
||||
private String updateDate;
|
||||
}
|
||||
|
||||
/**
|
||||
* 批量操作响应 VO
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "批量操作响应 VO")
|
||||
public static class BatchOperationVO implements Serializable {
|
||||
|
||||
@Schema(description = "成功操作数量", example = "5")
|
||||
@JsonProperty("success_count")
|
||||
private Integer successCount;
|
||||
|
||||
@Schema(description = "错误列表")
|
||||
private List<Object> errors;
|
||||
}
|
||||
|
||||
// ========== 知识图谱相关 ==========
|
||||
|
||||
/**
|
||||
* 知识图谱数据 VO (映射接口 5: knowledge_graph)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "知识图谱数据 VO")
|
||||
public static class GraphVO implements Serializable {
|
||||
|
||||
@Schema(description = "图谱节点列表")
|
||||
private List<Node> nodes;
|
||||
|
||||
@Schema(description = "图谱边列表")
|
||||
private List<Edge> edges;
|
||||
|
||||
@Schema(description = "思维导图数据")
|
||||
@JsonProperty("mind_map")
|
||||
private Map<String, Object> mindMap;
|
||||
|
||||
/**
|
||||
* 图谱节点
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "图谱节点")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class Node implements Serializable {
|
||||
|
||||
@Schema(description = "节点 ID", example = "node_001")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "节点标签", example = "产品")
|
||||
private String label;
|
||||
|
||||
@Schema(description = "PageRank 值", example = "0.85")
|
||||
private Double pagerank;
|
||||
|
||||
@Schema(description = "节点颜色", example = "#FF5733")
|
||||
private String color;
|
||||
|
||||
@Schema(description = "节点图片 URL", example = "https://example.com/icon.png")
|
||||
private String img;
|
||||
}
|
||||
|
||||
/**
|
||||
* 图谱边
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "图谱边")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class Edge implements Serializable {
|
||||
|
||||
@Schema(description = "源节点 ID", example = "node_001")
|
||||
private String source;
|
||||
|
||||
@Schema(description = "目标节点 ID", example = "node_002")
|
||||
private String target;
|
||||
|
||||
@Schema(description = "边权重", example = "0.75")
|
||||
private Double weight;
|
||||
|
||||
@Schema(description = "边标签 (关系描述)", example = "属于")
|
||||
private String label;
|
||||
}
|
||||
}
|
||||
|
||||
// ========== 异步任务追踪 (GraphRAG/RAPTOR) ==========
|
||||
|
||||
/**
|
||||
* 异步任务追踪 VO (映射接口 9/10: 任务进度返回)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "异步任务追踪 VO")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class TaskTraceVO implements Serializable {
|
||||
|
||||
@Schema(description = "任务 ID", example = "task_001")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "文档 ID", example = "doc_001")
|
||||
@JsonProperty("doc_id")
|
||||
private String docId;
|
||||
|
||||
@Schema(description = "起始页码", example = "1")
|
||||
@JsonProperty("from_page")
|
||||
private Integer fromPage;
|
||||
|
||||
@Schema(description = "结束页码", example = "10")
|
||||
@JsonProperty("to_page")
|
||||
private Integer toPage;
|
||||
|
||||
@Schema(description = "进度百分比 (0.0 - 1.0)", example = "0.75")
|
||||
private Double progress;
|
||||
|
||||
@Schema(description = "进度消息", example = "正在处理第 5 页...")
|
||||
@JsonProperty("progress_msg")
|
||||
private String progressMsg;
|
||||
|
||||
@Schema(description = "创建时间 (时间戳)", example = "1700000000000")
|
||||
@JsonProperty("create_time")
|
||||
private Long createTime;
|
||||
|
||||
@Schema(description = "更新时间 (时间戳)", example = "1700000001000")
|
||||
@JsonProperty("update_time")
|
||||
private Long updateTime;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,182 @@
|
||||
package xiaozhi.modules.knowledge.dto.document;
|
||||
|
||||
import lombok.*;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import java.io.Serializable;
|
||||
import java.util.List;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import jakarta.validation.constraints.*;
|
||||
|
||||
/**
|
||||
* 切片管理聚合 DTO
|
||||
*/
|
||||
@Schema(description = "切片管理聚合 DTO")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public class ChunkDTO {
|
||||
|
||||
/**
|
||||
* 新增切片请求参数
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "新增切片请求参数")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class AddReq implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "切片内容", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotBlank(message = "切片内容不能为空")
|
||||
private String content;
|
||||
|
||||
@Schema(description = "重要关键词列表")
|
||||
@JsonProperty("important_keywords")
|
||||
private List<String> importantKeywords;
|
||||
|
||||
@Schema(description = "预设问题列表")
|
||||
private List<String> questions;
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新切片请求参数
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "更新切片请求参数")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class UpdateReq implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "新的切片内容")
|
||||
private String content;
|
||||
|
||||
@Schema(description = "更新关键词列表 (覆盖原有列表)")
|
||||
@JsonProperty("important_keywords")
|
||||
private List<String> importantKeywords;
|
||||
|
||||
@Schema(description = "启用/禁用 (true: 启用, false: 禁用)")
|
||||
private Boolean available;
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取切片列表请求参数
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "获取切片列表请求参数")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class ListReq implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "页码 (默认 1)")
|
||||
private Integer page;
|
||||
|
||||
@Schema(description = "每页数量 (默认 30)")
|
||||
@JsonProperty("page_size")
|
||||
private Integer pageSize;
|
||||
|
||||
@Schema(description = "搜索关键词 (全文检索)")
|
||||
private String keywords;
|
||||
|
||||
@Schema(description = "精确切片 ID")
|
||||
private String id;
|
||||
}
|
||||
|
||||
/**
|
||||
* 批量删除切片请求参数
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "批量删除切片请求参数")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class RemoveReq implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "切片 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("chunk_ids")
|
||||
@NotEmpty(message = "切片ID列表不能为空")
|
||||
private List<String> chunkIds;
|
||||
}
|
||||
|
||||
/**
|
||||
* 文档切片信息 VO
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "文档切片信息")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class InfoVO implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "切片 ID (通常为 document_id + 索引)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String id;
|
||||
|
||||
@Schema(description = "切片文本内容 (全文检索的主要对象)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String content;
|
||||
|
||||
@Schema(description = "所属文档 ID", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("document_id")
|
||||
private String documentId;
|
||||
|
||||
@Schema(description = "文档名称 / 关键词")
|
||||
@JsonProperty("docnm_kwd")
|
||||
private String docnmKwd;
|
||||
|
||||
@Schema(description = "重要关键词列表 (用于关键词增强检索)")
|
||||
@JsonProperty("important_keywords")
|
||||
private List<String> importantKeywords;
|
||||
|
||||
@Schema(description = "预设问题列表 (用于 Q&A 模式增强)")
|
||||
private List<String> questions;
|
||||
|
||||
@Schema(description = "关联的图片 ID")
|
||||
@JsonProperty("image_id")
|
||||
private String imageId;
|
||||
|
||||
@Schema(description = "所属知识库 ID")
|
||||
@JsonProperty("dataset_id")
|
||||
private String datasetId;
|
||||
|
||||
@Schema(description = "切片是否可用 (true: 参与检索, false: 被禁用)")
|
||||
private Boolean available;
|
||||
|
||||
@Schema(description = "切片在原文中的位置索引列表 (RAGFlow返回嵌套数组, 如 [[start, end, filename]])")
|
||||
private List<List<Object>> positions;
|
||||
|
||||
@Schema(description = "Token ID 列表")
|
||||
@JsonProperty("token")
|
||||
private List<Integer> token;
|
||||
}
|
||||
|
||||
/**
|
||||
* 分片列表聚合响应
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "分片列表聚合响应")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class ListVO implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "切片信息列表")
|
||||
private List<InfoVO> chunks;
|
||||
|
||||
@Schema(description = "关联的文档详细信息")
|
||||
private DocumentDTO.InfoVO doc;
|
||||
|
||||
@Schema(description = "总记录数")
|
||||
private Long total;
|
||||
}
|
||||
}
|
||||
+407
@@ -0,0 +1,407 @@
|
||||
package xiaozhi.modules.knowledge.dto.document;
|
||||
|
||||
import lombok.*;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import java.io.Serializable;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import com.fasterxml.jackson.annotation.JsonAlias;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import jakarta.validation.constraints.*;
|
||||
|
||||
/**
|
||||
* 文档管理聚合 DTO
|
||||
*/
|
||||
@Schema(description = "文档管理聚合 DTO")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public class DocumentDTO {
|
||||
|
||||
/**
|
||||
* 上传文档请求参数
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "上传文档请求参数")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class UploadReq implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "知识库 ID (必须指定归属)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("dataset_id")
|
||||
@NotBlank(message = "知识库ID不能为空")
|
||||
private String datasetId;
|
||||
|
||||
@Schema(description = "文件名 (如果指定，则覆盖原始文件名)")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "分块方法")
|
||||
@JsonProperty("chunk_method")
|
||||
private DocumentDTO.InfoVO.ChunkMethod chunkMethod;
|
||||
|
||||
@Schema(description = "解析参数配置")
|
||||
@JsonProperty("parser_config")
|
||||
private DocumentDTO.InfoVO.ParserConfig parserConfig;
|
||||
|
||||
@Schema(description = "虚拟文件夹路径 (默认为 /)")
|
||||
@JsonProperty("parent_path")
|
||||
private String parentPath;
|
||||
|
||||
@Schema(description = "元数据字段")
|
||||
@JsonProperty("meta")
|
||||
private Map<String, Object> metaFields;
|
||||
|
||||
@Schema(description = "文件二进制流 (支持 PDF, DOCX, TXT, MD 等多种格式)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotNull(message = "上传文件不能为空")
|
||||
private org.springframework.web.multipart.MultipartFile file;
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新文档请求参数
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "更新文档请求参数")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class UpdateReq implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "新文档名称 (必须包含文件后缀，且不能更改原始类型)")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "启用/禁用状态 (true: 启用, false: 禁用; 禁用后不参与检索)")
|
||||
private Boolean enabled;
|
||||
|
||||
@Schema(description = "新解析方法 (修改此项会重置解析状态)")
|
||||
@JsonProperty("chunk_method")
|
||||
private InfoVO.ChunkMethod chunkMethod;
|
||||
|
||||
@Schema(description = "新解析器详细配置 (应与 chunk_method 配套使用)")
|
||||
@JsonProperty("parser_config")
|
||||
private InfoVO.ParserConfig parserConfig;
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取文档列表请求参数
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "获取文档列表请求参数")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class ListReq implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "页码 (默认: 1)")
|
||||
private Integer page;
|
||||
|
||||
@Schema(description = "每页数量 (默认: 30)")
|
||||
@JsonProperty("page_size")
|
||||
private Integer pageSize;
|
||||
|
||||
@Schema(description = "排序字段 (可选: create_time, name, size; 默认: create_time)")
|
||||
private String orderby;
|
||||
|
||||
@Schema(description = "是否降序排列 (true: 最新/最大在前; false: 最旧/最小在前; 默认: true)")
|
||||
private Boolean desc;
|
||||
|
||||
@Schema(description = "精确筛选: 文档 ID")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "精确筛选: 文档完整名称 (含后缀)")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "模糊搜索: 文档名称关键词")
|
||||
private String keywords;
|
||||
|
||||
@Schema(description = "筛选: 文件后缀列表 (如 ['pdf', 'docx'])")
|
||||
private List<String> suffix;
|
||||
|
||||
@Schema(description = "筛选: 运行状态列表")
|
||||
private List<InfoVO.RunStatus> run;
|
||||
|
||||
@Schema(description = "筛选: 起始创建时间 (时间戳, 毫秒)")
|
||||
@JsonProperty("create_time_from")
|
||||
private Long createTimeFrom;
|
||||
|
||||
@Schema(description = "筛选: 结束创建时间 (时间戳, 毫秒)")
|
||||
@JsonProperty("create_time_to")
|
||||
private Long createTimeTo;
|
||||
}
|
||||
|
||||
/**
|
||||
* 批量文档操作请求参数 (用于删除、解析等)
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "批量文档操作请求参数")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class BatchIdReq implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "文档 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("ids") // 为了兼容性，也可以考虑支持 document_ids，但这里统一叫 ids
|
||||
@JsonAlias("document_ids")
|
||||
@NotEmpty(message = "文档ID列表不能为空")
|
||||
private List<String> ids;
|
||||
}
|
||||
|
||||
/**
|
||||
* 知识库文档信息 VO
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "知识库文档信息")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class InfoVO implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "文档 ID (唯一标识)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String id;
|
||||
|
||||
@Schema(description = "文档缩略图 URL (Base64 或 链接)")
|
||||
private String thumbnail;
|
||||
|
||||
@Schema(description = "所属知识库 ID", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("dataset_id")
|
||||
private String datasetId;
|
||||
|
||||
@Schema(description = "文档解析方法 (决定了文档如何被切片)")
|
||||
@JsonProperty("chunk_method")
|
||||
private ChunkMethod chunkMethod;
|
||||
|
||||
@Schema(description = "关联的 ETL Pipeline ID (如有)")
|
||||
@JsonProperty("pipeline_id")
|
||||
private String pipelineId;
|
||||
|
||||
@Schema(description = "文档解析器的详细配置")
|
||||
@JsonProperty("parser_config")
|
||||
private ParserConfig parserConfig;
|
||||
|
||||
@Schema(description = "来源类型 (如 local, s3, url 等)")
|
||||
@JsonProperty("source_type")
|
||||
private String sourceType;
|
||||
|
||||
@Schema(description = "文档文件类型 (如 pdf, docx, txt)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String type;
|
||||
|
||||
@Schema(description = "创建者用户 ID")
|
||||
@JsonProperty("created_by")
|
||||
private String createdBy;
|
||||
|
||||
@Schema(description = "文档名称 (包含扩展名)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String name;
|
||||
|
||||
@Schema(description = "文件存储路径或位置标识")
|
||||
private String location;
|
||||
|
||||
@Schema(description = "文件大小 (单位: Bytes)")
|
||||
private Long size;
|
||||
|
||||
@Schema(description = "包含的 Token 总数 (解析后统计)")
|
||||
@JsonProperty("token_count")
|
||||
private Long tokenCount;
|
||||
|
||||
@Schema(description = "包含的切片 (Chunk) 总数")
|
||||
@JsonProperty("chunk_count")
|
||||
private Long chunkCount;
|
||||
|
||||
@Schema(description = "解析进度 (0.0 ~ 1.0, 1.0 表示完成)")
|
||||
private Double progress;
|
||||
|
||||
@Schema(description = "当前进度描述或错误信息")
|
||||
@JsonProperty("progress_msg")
|
||||
private String progressMsg;
|
||||
|
||||
@Schema(description = "开始处理的时间戳 (RAGFlow返回RFC1123格式)")
|
||||
@JsonProperty("process_begin_at")
|
||||
private String processBeginAt;
|
||||
|
||||
@Schema(description = "处理总耗时 (单位: 秒)")
|
||||
@JsonProperty("process_duration")
|
||||
private Double processDuration;
|
||||
|
||||
@Schema(description = "自定义元数据字段 (Key-Value 键值对)")
|
||||
@JsonProperty("meta_fields")
|
||||
private Map<String, Object> metaFields;
|
||||
|
||||
@Schema(description = "文件后缀名 (不含点)")
|
||||
private String suffix;
|
||||
|
||||
@Schema(description = "文档解析运行状态")
|
||||
private RunStatus run;
|
||||
|
||||
@Schema(description = "文档可用状态 (1: 启用/正常, 0: 禁用/失效)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String status;
|
||||
|
||||
@Schema(description = "创建时间 (时间戳, 毫秒)", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("create_time")
|
||||
private Long createTime;
|
||||
|
||||
@Schema(description = "创建日期 (RAGFlow返回RFC1123格式)")
|
||||
@JsonProperty("create_date")
|
||||
private String createDate;
|
||||
|
||||
@Schema(description = "最后更新时间 (时间戳, 毫秒)")
|
||||
@JsonProperty("update_time")
|
||||
private Long updateTime;
|
||||
|
||||
@Schema(description = "最后更新日期 (RAGFlow返回RFC1123格式)")
|
||||
@JsonProperty("update_date")
|
||||
private String updateDate;
|
||||
|
||||
/**
|
||||
* 解析方法枚举 (ChunkMethod)
|
||||
*/
|
||||
public enum ChunkMethod {
|
||||
@Schema(description = "通用模式: 适用于大多数纯文本或混合文档")
|
||||
@JsonProperty("naive")
|
||||
NAIVE,
|
||||
@Schema(description = "手动模式: 允许用户手动编辑切片")
|
||||
@JsonProperty("manual")
|
||||
MANUAL,
|
||||
@Schema(description = "问答模式: 专门优化 Q&A 格式的文档")
|
||||
@JsonProperty("qa")
|
||||
QA,
|
||||
@Schema(description = "表格模式: 专门优化 Excel 或 CSV 等表格数据")
|
||||
@JsonProperty("table")
|
||||
TABLE,
|
||||
@Schema(description = "论文模式: 针对学术论文排版优化")
|
||||
@JsonProperty("paper")
|
||||
PAPER,
|
||||
@Schema(description = "书籍模式: 针对书籍章节结构优化")
|
||||
@JsonProperty("book")
|
||||
BOOK,
|
||||
@Schema(description = "法律法规模式: 针对法律条文结构优化")
|
||||
@JsonProperty("laws")
|
||||
LAWS,
|
||||
@Schema(description = "演示文稿模式: 针对 PPT 等演示文件优化")
|
||||
@JsonProperty("presentation")
|
||||
PRESENTATION,
|
||||
@Schema(description = "图片模式: 针对图片内容进行 OCR 和描述")
|
||||
@JsonProperty("picture")
|
||||
PICTURE,
|
||||
@Schema(description = "整体模式: 将整个文档作为一个切片")
|
||||
@JsonProperty("one")
|
||||
ONE,
|
||||
@Schema(description = "知识图谱模式: 提取实体关系构建图谱")
|
||||
@JsonProperty("knowledge_graph")
|
||||
KNOWLEDGE_GRAPH,
|
||||
@Schema(description = "邮件模式: 针对邮件格式优化")
|
||||
@JsonProperty("email")
|
||||
EMAIL;
|
||||
}
|
||||
|
||||
/**
|
||||
* 运行状态枚举 (RunStatus)
|
||||
*/
|
||||
public enum RunStatus {
|
||||
@Schema(description = "未开始: 等待解析队列")
|
||||
@JsonProperty("UNSTART")
|
||||
UNSTART,
|
||||
@Schema(description = "进行中: 正在解析或索引")
|
||||
@JsonProperty("RUNNING")
|
||||
RUNNING,
|
||||
@Schema(description = "已取消: 用户手动取消")
|
||||
@JsonProperty("CANCEL")
|
||||
CANCEL,
|
||||
@Schema(description = "已完成: 解析成功")
|
||||
@JsonProperty("DONE")
|
||||
DONE,
|
||||
@Schema(description = "失败: 解析过程中出错")
|
||||
@JsonProperty("FAIL")
|
||||
FAIL;
|
||||
}
|
||||
|
||||
/**
|
||||
* 布局识别模型枚举
|
||||
*/
|
||||
public enum LayoutRecognize {
|
||||
@Schema(description = "深度文档理解模型: 适合复杂排版")
|
||||
@JsonProperty("DeepDOC")
|
||||
DeepDOC,
|
||||
@Schema(description = "简单规则模型: 适合纯文本")
|
||||
@JsonProperty("Simple")
|
||||
Simple;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "文档解析器参数配置")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class ParserConfig implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "切片最大 Token 数 (建议值: 512, 1024, 2048)")
|
||||
@JsonProperty("chunk_token_num")
|
||||
private Integer chunkTokenNum;
|
||||
|
||||
@Schema(description = "分段分隔符 (支持转义字符, 如 \\n)")
|
||||
private String delimiter;
|
||||
|
||||
@Schema(description = "布局识别模型 (DeepDOC/Simple)")
|
||||
@JsonProperty("layout_recognize")
|
||||
private LayoutRecognize layoutRecognize;
|
||||
|
||||
@Schema(description = "是否将 Excel 转换为 HTML 表格")
|
||||
@JsonProperty("html4excel")
|
||||
private Boolean html4excel;
|
||||
|
||||
@Schema(description = "自动提取关键词数量 (0 表示不提取)")
|
||||
@JsonProperty("auto_keywords")
|
||||
private Integer autoKeywords;
|
||||
|
||||
@Schema(description = "自动生成问题数量 (0 表示不生成)")
|
||||
@JsonProperty("auto_questions")
|
||||
private Integer autoQuestions;
|
||||
|
||||
@Schema(description = "自动生成标签数量")
|
||||
@JsonProperty("topn_tags")
|
||||
private Integer topnTags;
|
||||
|
||||
@Schema(description = "RAPTOR 高级索引配置")
|
||||
private RaptorConfig raptor;
|
||||
|
||||
@Schema(description = "GraphRAG 知识图谱配置")
|
||||
@JsonProperty("graphrag")
|
||||
private GraphRagConfig graphRag;
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "RAPTOR (递归摘要索引) 配置")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class RaptorConfig implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
@Schema(description = "是否启用 RAPTOR 索引")
|
||||
@JsonProperty("use_raptor")
|
||||
private Boolean useRaptor;
|
||||
}
|
||||
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "GraphRAG (图增强检索) 配置")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class GraphRagConfig implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
@Schema(description = "是否启用 GraphRAG 索引")
|
||||
@JsonProperty("use_graphrag")
|
||||
private Boolean useGraphRag;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
+307
@@ -0,0 +1,307 @@
|
||||
package xiaozhi.modules.knowledge.dto.document;
|
||||
|
||||
import lombok.*;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import java.io.Serializable;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import com.fasterxml.jackson.annotation.JsonInclude;
|
||||
import com.fasterxml.jackson.annotation.JsonIgnoreProperties;
|
||||
import jakarta.validation.constraints.*;
|
||||
|
||||
/**
|
||||
* 检索与元数据管理聚合 DTO
|
||||
*/
|
||||
@Schema(description = "检索与元数据管理聚合 DTO")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public class RetrievalDTO {
|
||||
|
||||
/**
|
||||
* 文档聚合信息 (VO)
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "文档聚合信息")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class DocAggVO implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "文档名称")
|
||||
@JsonProperty("doc_name")
|
||||
private String docName;
|
||||
|
||||
@Schema(description = "文档 ID")
|
||||
@JsonProperty("doc_id")
|
||||
private String docId;
|
||||
|
||||
@Schema(description = "数量")
|
||||
private Integer count;
|
||||
}
|
||||
|
||||
/**
|
||||
* 检索测试请求参数
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "检索测试请求参数")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
@JsonInclude(JsonInclude.Include.NON_NULL)
|
||||
public static class TestReq implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "知识库 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("dataset_ids")
|
||||
@NotEmpty(message = "知识库ID列表不能为空")
|
||||
private List<String> datasetIds;
|
||||
|
||||
@Schema(description = "文档 ID 列表 (可选，用于限定检索范围)")
|
||||
@JsonProperty("document_ids")
|
||||
private List<String> documentIds;
|
||||
|
||||
@Schema(description = "检索问题", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@NotBlank(message = "检索问题不能为空")
|
||||
private String question;
|
||||
|
||||
@Schema(description = "页码 (默认 1)")
|
||||
private Integer page;
|
||||
|
||||
@Schema(description = "每页数量 (默认 10)")
|
||||
@JsonProperty("page_size")
|
||||
private Integer pageSize;
|
||||
|
||||
@Schema(description = "相似度阈值 (默认 0.2)")
|
||||
@JsonProperty("similarity_threshold")
|
||||
private Float similarityThreshold;
|
||||
|
||||
@Schema(description = "向量相似度权重 (默认 0.3)")
|
||||
@JsonProperty("vector_similarity_weight")
|
||||
private Float vectorSimilarityWeight;
|
||||
|
||||
@Schema(description = "返回 Top K 切片 (默认 1024)")
|
||||
@JsonProperty("top_k")
|
||||
private Integer topK;
|
||||
|
||||
@Schema(description = "重排序模型 ID")
|
||||
@JsonProperty("rerank_id")
|
||||
private String rerankId;
|
||||
|
||||
@Schema(description = "是否高亮关键词")
|
||||
private Boolean highlight;
|
||||
|
||||
@Schema(description = "是否启用关键词检索")
|
||||
private Boolean keyword;
|
||||
|
||||
@Schema(description = "跨语言翻译列表 (可选)")
|
||||
@JsonProperty("cross_languages")
|
||||
private List<String> crossLanguages;
|
||||
|
||||
@Schema(description = "元数据过滤条件 (JSON 对象)")
|
||||
@JsonProperty("metadata_condition")
|
||||
private Map<String, Object> metadataCondition;
|
||||
}
|
||||
|
||||
/**
|
||||
* 检索命中结果 (VO)
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "检索命中切片详情")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class HitVO implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "切片 ID", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String id;
|
||||
|
||||
@Schema(description = "切片内容", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String content;
|
||||
|
||||
@Schema(description = "所属文档 ID", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("document_id")
|
||||
private String documentId;
|
||||
|
||||
@Schema(description = "所属知识库 ID")
|
||||
@JsonProperty("dataset_id")
|
||||
private String datasetId;
|
||||
|
||||
@Schema(description = "文档名称")
|
||||
@JsonProperty("document_name")
|
||||
private String documentName;
|
||||
|
||||
@Schema(description = "文档关键词")
|
||||
@JsonProperty("document_keyword")
|
||||
private String documentKeyword;
|
||||
|
||||
@Schema(description = "综合相似度", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private Float similarity;
|
||||
|
||||
@Schema(description = "向量相似度")
|
||||
@JsonProperty("vector_similarity")
|
||||
private Float vectorSimilarity;
|
||||
|
||||
@Schema(description = "关键词相似度")
|
||||
@JsonProperty("term_similarity")
|
||||
private Float termSimilarity;
|
||||
|
||||
@Schema(description = "索引位置")
|
||||
private Integer index;
|
||||
|
||||
@Schema(description = "高亮内容")
|
||||
private String highlight;
|
||||
|
||||
@Schema(description = "重要关键词列表")
|
||||
@JsonProperty("important_keywords")
|
||||
private List<String> importantKeywords;
|
||||
|
||||
@Schema(description = "预设问题列表")
|
||||
private List<String> questions;
|
||||
|
||||
@Schema(description = "图片 ID")
|
||||
@JsonProperty("image_id")
|
||||
private String imageId;
|
||||
|
||||
@Schema(description = "位置索引 (RAGFlow返回嵌套数组, 如 [[start, end, filename]])")
|
||||
private Object positions;
|
||||
}
|
||||
|
||||
/**
|
||||
* 知识库元数据摘要 (VO)
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "知识库元数据摘要信息")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class MetaSummaryVO implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "文档总数", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("total_doc_count")
|
||||
private Long totalDocCount;
|
||||
|
||||
@Schema(description = "Token 总数", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
@JsonProperty("total_token_count")
|
||||
private Long totalTokenCount;
|
||||
|
||||
@Schema(description = "文件类型分布 (key: 文件后缀, value: 数量)")
|
||||
@JsonProperty("file_type_distribution")
|
||||
private Map<String, Long> fileTypeDistribution;
|
||||
|
||||
@Schema(description = "文状态分布 (key: 状态码, value: 数量)")
|
||||
@JsonProperty("status_distribution")
|
||||
private Map<String, Long> statusDistribution;
|
||||
|
||||
@Schema(description = "自定义元数据统计 (key: 字段名, value: 数量/值)")
|
||||
@JsonProperty("custom_metadata")
|
||||
private Map<String, Object> customMetadata;
|
||||
}
|
||||
|
||||
/**
|
||||
* 批量更新元数据请求参数
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "批量更新元数据请求参数")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class MetaBatchReq implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "筛选器: 用于指定要更新的文档范围 (默认全部)")
|
||||
private Selector selector;
|
||||
|
||||
@Schema(description = "新增或更新的元数据列表")
|
||||
private List<UpdateItem> updates;
|
||||
|
||||
@Schema(description = "需要删除的元数据键列表")
|
||||
private List<DeleteItem> deletes;
|
||||
|
||||
/**
|
||||
* 文档筛选器
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "元数据更新筛选器")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class Selector implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "指定文档 ID 列表")
|
||||
@JsonProperty("document_ids")
|
||||
private List<String> documentIds;
|
||||
|
||||
@Schema(description = "元数据条件匹配 (key: 字段名, value: 匹配值)")
|
||||
@JsonProperty("metadata_condition")
|
||||
private Map<String, Object> metadataCondition;
|
||||
}
|
||||
|
||||
/**
|
||||
* 更新项
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "元数据更新项")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class UpdateItem implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "元数据键名", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String key;
|
||||
|
||||
@Schema(description = "元数据值", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private Object value;
|
||||
}
|
||||
|
||||
/**
|
||||
* 删除项
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "元数据删除项")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class DeleteItem implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "需删除的元数据键名", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private String key;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 召回测试结果聚合响应
|
||||
*/
|
||||
@Data
|
||||
@Builder
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Schema(description = "召回测试结果聚合响应")
|
||||
@JsonIgnoreProperties(ignoreUnknown = true)
|
||||
public static class ResultVO implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@Schema(description = "检索命中的切片列表")
|
||||
private List<HitVO> chunks;
|
||||
|
||||
@Schema(description = "文档分布统计")
|
||||
@JsonProperty("doc_aggs")
|
||||
private List<DocAggVO> docAggs;
|
||||
|
||||
@Schema(description = "总命中记录数")
|
||||
private Long total;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,363 @@
|
||||
package xiaozhi.modules.knowledge.dto.file;
|
||||
|
||||
import lombok.*;
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import java.io.Serializable;
|
||||
import java.util.List;
|
||||
import com.fasterxml.jackson.annotation.JsonProperty;
|
||||
import jakarta.validation.constraints.*;
|
||||
import org.springframework.web.multipart.MultipartFile;
|
||||
|
||||
/**
|
||||
* 文件管理聚合 DTO
|
||||
* <p>
|
||||
* 容器类，内含文件模块所有请求/响应对象的静态内部类定义。
|
||||
* </p>
|
||||
*/
|
||||
@Schema(description = "文件管理聚合 DTO")
|
||||
public class FileDTO {
|
||||
|
||||
// ========== 请求类 ==========
|
||||
|
||||
/**
|
||||
* 文件上传请求 (对应接口 1: upload)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "文件上传请求")
|
||||
public static class UploadReq implements Serializable {
|
||||
|
||||
@NotNull(message = "文件不能为空")
|
||||
@Schema(description = "上传的文件", requiredMode = Schema.RequiredMode.REQUIRED)
|
||||
private MultipartFile file;
|
||||
|
||||
@Schema(description = "父文件夹 ID (为空则上传到根目录)", example = "folder_001")
|
||||
@JsonProperty("parent_id")
|
||||
private String parentId;
|
||||
}
|
||||
|
||||
/**
|
||||
* 新建文件夹请求 (对应接口 2: create)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "新建文件夹请求")
|
||||
public static class CreateReq implements Serializable {
|
||||
|
||||
@NotBlank(message = "文件夹名称不能为空")
|
||||
@Schema(description = "文件夹名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "新建文件夹")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "父文件夹 ID (为空则创建在根目录)", example = "folder_001")
|
||||
@JsonProperty("parent_id")
|
||||
private String parentId;
|
||||
|
||||
@NotBlank(message = "类型不能为空")
|
||||
@Schema(description = "类型: FOLDER", requiredMode = Schema.RequiredMode.REQUIRED, example = "FOLDER")
|
||||
@Builder.Default
|
||||
private String type = "FOLDER";
|
||||
}
|
||||
|
||||
/**
|
||||
* 重命名请求 (对应接口 6: rename)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "重命名请求")
|
||||
public static class RenameReq implements Serializable {
|
||||
|
||||
@NotBlank(message = "文件 ID 不能为空")
|
||||
@Schema(description = "文件/文件夹 ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "file_001")
|
||||
@JsonProperty("file_id")
|
||||
private String fileId;
|
||||
|
||||
@NotBlank(message = "新名称不能为空")
|
||||
@Schema(description = "新名称", requiredMode = Schema.RequiredMode.REQUIRED, example = "重命名后的文件")
|
||||
private String name;
|
||||
}
|
||||
|
||||
/**
|
||||
* 移动请求 (对应接口 7: move)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "移动请求")
|
||||
public static class MoveReq implements Serializable {
|
||||
|
||||
@NotEmpty(message = "源文件 ID 列表不能为空")
|
||||
@Schema(description = "源文件/文件夹 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED, example = "[\"file_001\", \"file_002\"]")
|
||||
@JsonProperty("src_file_ids")
|
||||
private List<String> srcFileIds;
|
||||
|
||||
@NotBlank(message = "目标文件夹 ID 不能为空")
|
||||
@Schema(description = "目标文件夹 ID", requiredMode = Schema.RequiredMode.REQUIRED, example = "folder_002")
|
||||
@JsonProperty("dest_file_id")
|
||||
private String destFileId;
|
||||
}
|
||||
|
||||
/**
|
||||
* 批量删除请求 (对应接口 8: rm)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "批量删除请求")
|
||||
public static class RemoveReq implements Serializable {
|
||||
|
||||
@NotEmpty(message = "文件 ID 列表不能为空")
|
||||
@Schema(description = "文件/文件夹 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED, example = "[\"file_001\", \"file_002\"]")
|
||||
@JsonProperty("file_ids")
|
||||
private List<String> fileIds;
|
||||
}
|
||||
|
||||
/**
|
||||
* 导入知识库请求 (对应接口 9: convert)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "导入知识库请求")
|
||||
public static class ConvertReq implements Serializable {
|
||||
|
||||
@NotEmpty(message = "文件 ID 列表不能为空")
|
||||
@Schema(description = "文件 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED, example = "[\"file_001\", \"file_002\"]")
|
||||
@JsonProperty("file_ids")
|
||||
private List<String> fileIds;
|
||||
|
||||
@NotEmpty(message = "知识库 ID 列表不能为空")
|
||||
@Schema(description = "目标知识库 ID 列表", requiredMode = Schema.RequiredMode.REQUIRED, example = "[\"kb_001\"]")
|
||||
@JsonProperty("kb_ids")
|
||||
private List<String> kbIds;
|
||||
}
|
||||
|
||||
/**
|
||||
* 列表查询请求 (对应接口 3: list_files)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "列表查询请求")
|
||||
public static class ListReq implements Serializable {
|
||||
|
||||
@Schema(description = "父文件夹 ID (为空则查询根目录)", example = "folder_001")
|
||||
@JsonProperty("parent_id")
|
||||
private String parentId;
|
||||
|
||||
@Schema(description = "关键词搜索", example = "文档")
|
||||
private String keywords;
|
||||
|
||||
@Schema(description = "页码 (从 1 开始)", example = "1")
|
||||
private Integer page;
|
||||
|
||||
@Schema(description = "每页数量", example = "30")
|
||||
@JsonProperty("page_size")
|
||||
private Integer pageSize;
|
||||
|
||||
@Schema(description = "排序字段: create_time / update_time / name / size", example = "create_time")
|
||||
private String orderby;
|
||||
|
||||
@Schema(description = "是否降序", example = "true")
|
||||
private Boolean desc;
|
||||
}
|
||||
|
||||
// ========== 响应类 ==========
|
||||
|
||||
/**
|
||||
* 文件/文件夹基础信息 VO
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "文件/文件夹基础信息")
|
||||
public static class InfoVO implements Serializable {
|
||||
|
||||
@Schema(description = "文件/文件夹 ID", example = "file_001")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "父文件夹 ID", example = "folder_001")
|
||||
@JsonProperty("parent_id")
|
||||
private String parentId;
|
||||
|
||||
@Schema(description = "租户 ID", example = "tenant_001")
|
||||
@JsonProperty("tenant_id")
|
||||
private String tenantId;
|
||||
|
||||
@Schema(description = "创建者 ID", example = "user_001")
|
||||
@JsonProperty("created_by")
|
||||
private String createdBy;
|
||||
|
||||
@Schema(description = "类型: FOLDER / FILE", example = "FOLDER")
|
||||
private String type;
|
||||
|
||||
@Schema(description = "名称", example = "我的文件夹")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "路径位置", example = "/root/folder")
|
||||
private String location;
|
||||
|
||||
@Schema(description = "文件大小 (字节)", example = "1024")
|
||||
private Long size;
|
||||
|
||||
@Schema(description = "来源类型", example = "local")
|
||||
@JsonProperty("source_type")
|
||||
private String sourceType;
|
||||
|
||||
@Schema(description = "创建时间 (时间戳)", example = "1700000000000")
|
||||
@JsonProperty("create_time")
|
||||
private Long createTime;
|
||||
|
||||
@Schema(description = "创建日期 (格式化)", example = "2024-01-15 10:30:00")
|
||||
@JsonProperty("create_date")
|
||||
private String createDate;
|
||||
|
||||
@Schema(description = "更新时间 (时间戳)", example = "1700000001000")
|
||||
@JsonProperty("update_time")
|
||||
private Long updateTime;
|
||||
|
||||
@Schema(description = "更新日期 (格式化)", example = "2024-01-15 11:00:00")
|
||||
@JsonProperty("update_date")
|
||||
private String updateDate;
|
||||
|
||||
@Schema(description = "文件扩展名", example = "pdf")
|
||||
private String extension;
|
||||
}
|
||||
|
||||
/**
|
||||
* 列表响应 VO (对应接口 3: list_files)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "文件列表响应")
|
||||
public static class ListVO implements Serializable {
|
||||
|
||||
@Schema(description = "总记录数", example = "100")
|
||||
private Long total;
|
||||
|
||||
@Schema(description = "当前父文件夹信息")
|
||||
@JsonProperty("parent_folder")
|
||||
private InfoVO parentFolder;
|
||||
|
||||
@Schema(description = "文件/文件夹列表")
|
||||
private List<InfoVO> files;
|
||||
|
||||
@Schema(description = "面包屑导航路径")
|
||||
private List<InfoVO> breadcrumb;
|
||||
}
|
||||
|
||||
/**
|
||||
* 转换结果项 VO (对应接口 9: convert)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "文件转换结果项")
|
||||
public static class ConvertVO implements Serializable {
|
||||
|
||||
@Schema(description = "转换记录 ID", example = "convert_001")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "源文件 ID", example = "file_001")
|
||||
@JsonProperty("file_id")
|
||||
private String fileId;
|
||||
|
||||
@Schema(description = "目标文档 ID", example = "doc_001")
|
||||
@JsonProperty("document_id")
|
||||
private String documentId;
|
||||
|
||||
@Schema(description = "创建时间 (时间戳)", example = "1700000000000")
|
||||
@JsonProperty("create_time")
|
||||
private Long createTime;
|
||||
|
||||
@Schema(description = "创建日期 (格式化)", example = "2024-01-15 10:30:00")
|
||||
@JsonProperty("create_date")
|
||||
private String createDate;
|
||||
|
||||
@Schema(description = "更新时间 (时间戳)", example = "1700000001000")
|
||||
@JsonProperty("update_time")
|
||||
private Long updateTime;
|
||||
|
||||
@Schema(description = "更新日期 (格式化)", example = "2024-01-15 11:00:00")
|
||||
@JsonProperty("update_date")
|
||||
private String updateDate;
|
||||
}
|
||||
|
||||
/**
|
||||
* 转换状态 VO (对应接口 10: get_convert_status)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "文件转换状态")
|
||||
public static class ConvertStatusVO implements Serializable {
|
||||
|
||||
@Schema(description = "转换状态: pending / processing / completed / failed", example = "completed")
|
||||
private String status;
|
||||
|
||||
@Schema(description = "转换进度 (0.0 - 1.0)", example = "1.0")
|
||||
private Float progress;
|
||||
|
||||
@Schema(description = "状态消息", example = "转换完成")
|
||||
private String message;
|
||||
}
|
||||
|
||||
/**
|
||||
* 面包屑 VO (对应接口 12: all_parent_folder)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "面包屑导航 (所有父文件夹)")
|
||||
public static class BreadcrumbVO implements Serializable {
|
||||
|
||||
@Schema(description = "父文件夹列表 (从根到当前的路径)")
|
||||
@JsonProperty("parent_folders")
|
||||
private List<InfoVO> parentFolders;
|
||||
}
|
||||
|
||||
/**
|
||||
* 根目录信息 VO (对应接口 10: get_root_folder)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "根目录信息")
|
||||
public static class RootFolderVO implements Serializable {
|
||||
|
||||
@Schema(description = "根文件夹信息")
|
||||
@JsonProperty("root_folder")
|
||||
private InfoVO rootFolder;
|
||||
}
|
||||
|
||||
/**
|
||||
* 父目录信息 VO (对应接口 11: get_parent_folder)
|
||||
*/
|
||||
@Data
|
||||
@NoArgsConstructor
|
||||
@AllArgsConstructor
|
||||
@Builder
|
||||
@Schema(description = "父目录信息")
|
||||
public static class ParentFolderVO implements Serializable {
|
||||
|
||||
@Schema(description = "父文件夹信息")
|
||||
@JsonProperty("parent_folder")
|
||||
private InfoVO parentFolder;
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,97 @@
|
||||
package xiaozhi.modules.knowledge.entity;
|
||||
|
||||
import java.io.Serializable;
|
||||
import java.util.Date;
|
||||
|
||||
import com.baomidou.mybatisplus.annotation.FieldFill;
|
||||
import com.baomidou.mybatisplus.annotation.IdType;
|
||||
import com.baomidou.mybatisplus.annotation.TableField;
|
||||
import com.baomidou.mybatisplus.annotation.TableId;
|
||||
import com.baomidou.mybatisplus.annotation.TableName;
|
||||
|
||||
import io.swagger.v3.oas.annotations.media.Schema;
|
||||
import lombok.Data;
|
||||
|
||||
/**
|
||||
* 文档表 (Shadow DB for RAGFlow Documents)
|
||||
* 对应表名: ai_knowledge_document
|
||||
*/
|
||||
@Data
|
||||
@TableName(value = "ai_rag_knowledge_document", autoResultMap = true)
|
||||
@Schema(description = "知识库文档表")
|
||||
public class DocumentEntity implements Serializable {
|
||||
private static final long serialVersionUID = 1L;
|
||||
|
||||
@TableId(type = IdType.ASSIGN_UUID)
|
||||
@Schema(description = "本地唯一ID")
|
||||
private String id;
|
||||
|
||||
@Schema(description = "知识库ID (关联 ai_rag_dataset.dataset_id)")
|
||||
private String datasetId;
|
||||
|
||||
@Schema(description = "RAGFlow文档ID (远程ID)")
|
||||
private String documentId;
|
||||
|
||||
@Schema(description = "文档名称")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "文件大小(Bytes)")
|
||||
private Long size;
|
||||
|
||||
@Schema(description = "文件类型(pdf/doc/txt等)")
|
||||
private String type;
|
||||
|
||||
@Schema(description = "分块方法")
|
||||
private String chunkMethod;
|
||||
|
||||
@Schema(description = "解析配置(JSON String)")
|
||||
private String parserConfig;
|
||||
|
||||
@Schema(description = "可用状态 (1: 启用/正常, 0: 禁用/失效)")
|
||||
private String status;
|
||||
|
||||
@Schema(description = "运行状态 (UNSTART/RUNNING/CANCEL/DONE/FAIL)")
|
||||
private String run;
|
||||
|
||||
@Schema(description = "解析进度 (0.0 ~ 1.0)")
|
||||
private Double progress;
|
||||
|
||||
@Schema(description = "缩略图 (Base64 或 URL)")
|
||||
private String thumbnail;
|
||||
|
||||
@Schema(description = "解析耗时 (单位: 秒)")
|
||||
private Double processDuration;
|
||||
|
||||
@Schema(description = "自定义元数据 (JSON 格式)")
|
||||
private String metaFields;
|
||||
|
||||
@Schema(description = "来源类型 (local, s3, url 等)")
|
||||
private String sourceType;
|
||||
|
||||
@Schema(description = "解析错误信息")
|
||||
private String error;
|
||||
|
||||
@Schema(description = "分块数量")
|
||||
private Integer chunkCount;
|
||||
|
||||
@Schema(description = "Token数量")
|
||||
private Long tokenCount;
|
||||
|
||||
@Schema(description = "是否启用 (0:禁用 1:启用)")
|
||||
private Integer enabled;
|
||||
|
||||
@Schema(description = "创建者")
|
||||
@TableField(fill = FieldFill.INSERT)
|
||||
private Long creator;
|
||||
|
||||
@Schema(description = "创建时间")
|
||||
@TableField(fill = FieldFill.INSERT)
|
||||
private Date createdAt;
|
||||
|
||||
@Schema(description = "更新时间")
|
||||
@TableField(fill = FieldFill.UPDATE)
|
||||
private Date updatedAt;
|
||||
|
||||
@Schema(description = "最新同步时间")
|
||||
private Date lastSyncAt;
|
||||
}
|
||||
+29
-1
@@ -23,15 +23,43 @@ public class KnowledgeBaseEntity {
|
||||
@Schema(description = "知识库ID")
|
||||
private String datasetId;
|
||||
|
||||
@Schema(description = "RAG模型配置ID")
|
||||
// @Deprecated
|
||||
@Schema(description = "RAG模型配置ID (连接RAGFlow的凭证指针)")
|
||||
private String ragModelId;
|
||||
|
||||
@Schema(description = "租户ID")
|
||||
private String tenantId;
|
||||
|
||||
@Schema(description = "知识库名称")
|
||||
private String name;
|
||||
|
||||
@Schema(description = "知识库头像(Base64)")
|
||||
private String avatar;
|
||||
|
||||
@Schema(description = "知识库描述")
|
||||
private String description;
|
||||
|
||||
@Schema(description = "嵌入模型名称")
|
||||
private String embeddingModel;
|
||||
|
||||
@Schema(description = "权限设置: me/team")
|
||||
private String permission;
|
||||
|
||||
@Schema(description = "分块方法")
|
||||
private String chunkMethod;
|
||||
|
||||
@Schema(description = "解析器配置(JSON String)")
|
||||
private String parserConfig;
|
||||
|
||||
@Schema(description = "分块总数")
|
||||
private Long chunkCount;
|
||||
|
||||
@Schema(description = "文档总数")
|
||||
private Long documentCount;
|
||||
|
||||
@Schema(description = "总Token数")
|
||||
private Long tokenNum;
|
||||
|
||||
@Schema(description = "状态(0:禁用 1:启用)")
|
||||
private Integer status;
|
||||
|
||||
|
||||
+64
-49
@@ -3,10 +3,14 @@ package xiaozhi.modules.knowledge.rag;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
import org.springframework.web.multipart.MultipartFile;
|
||||
import xiaozhi.modules.knowledge.dto.dataset.DatasetDTO;
|
||||
|
||||
import xiaozhi.common.page.PageData;
|
||||
import xiaozhi.modules.knowledge.dto.KnowledgeFilesDTO;
|
||||
import xiaozhi.modules.knowledge.dto.document.DocumentDTO;
|
||||
import xiaozhi.modules.knowledge.dto.document.ChunkDTO;
|
||||
import xiaozhi.modules.knowledge.dto.document.RetrievalDTO;
|
||||
import java.util.function.Consumer;
|
||||
|
||||
/**
|
||||
* 知识库API适配器抽象基类
|
||||
@@ -46,35 +50,24 @@ public abstract class KnowledgeBaseAdapter {
|
||||
* @return 分页数据
|
||||
*/
|
||||
public abstract PageData<KnowledgeFilesDTO> getDocumentList(String datasetId,
|
||||
Map<String, Object> queryParams,
|
||||
Integer page,
|
||||
Integer limit);
|
||||
DocumentDTO.ListReq req);
|
||||
|
||||
/**
|
||||
* 根据文档ID获取文档详情
|
||||
*
|
||||
* @param datasetId 知识库ID
|
||||
* @return 文档详情
|
||||
* @param datasetId 知识库ID
|
||||
* @param documentId 文档ID
|
||||
* @return 文档详情 (强类型 InfoVO)
|
||||
*/
|
||||
public abstract KnowledgeFilesDTO getDocumentById(String datasetId, String documentId);
|
||||
public abstract DocumentDTO.InfoVO getDocumentById(String datasetId, String documentId);
|
||||
|
||||
/**
|
||||
* 上传文档到知识库
|
||||
*
|
||||
* @param datasetId 知识库ID
|
||||
* @param file 上传的文件
|
||||
* @param name 文档名称
|
||||
* @param metaFields 元数据字段
|
||||
* @param chunkMethod 分块方法
|
||||
* @param parserConfig 解析器配置
|
||||
* @param req 上传请求参数
|
||||
* @return 上传的文档信息
|
||||
*/
|
||||
public abstract KnowledgeFilesDTO uploadDocument(String datasetId,
|
||||
MultipartFile file,
|
||||
String name,
|
||||
Map<String, Object> metaFields,
|
||||
String chunkMethod,
|
||||
Map<String, Object> parserConfig);
|
||||
public abstract KnowledgeFilesDTO uploadDocument(DocumentDTO.UploadReq req);
|
||||
|
||||
/**
|
||||
* 根据状态分页查询文档列表
|
||||
@@ -91,12 +84,12 @@ public abstract class KnowledgeBaseAdapter {
|
||||
Integer limit);
|
||||
|
||||
/**
|
||||
* 删除文档
|
||||
* 删除文档 (支持批量删除)
|
||||
*
|
||||
* @param datasetId 知识库ID
|
||||
* @param documentId 文档ID
|
||||
* @param datasetId 知识库ID
|
||||
* @param req 包含文档ID列表的请求对象
|
||||
*/
|
||||
public abstract void deleteDocument(String datasetId, String documentId);
|
||||
public abstract void deleteDocument(String datasetId, DocumentDTO.BatchIdReq req);
|
||||
|
||||
/**
|
||||
* 解析文档（切块）
|
||||
@@ -112,32 +105,21 @@ public abstract class KnowledgeBaseAdapter {
|
||||
*
|
||||
* @param datasetId 知识库ID
|
||||
* @param documentId 文档ID
|
||||
* @param keywords 关键词过滤
|
||||
* @param page 页码
|
||||
* @param pageSize 每页数量
|
||||
* @param chunkId 切片ID
|
||||
* @return 切片列表信息
|
||||
* @param req 列表请求参数 (分页、关键词等)
|
||||
* @return 切片列表VO
|
||||
*/
|
||||
public abstract Map<String, Object> listChunks(String datasetId,
|
||||
public abstract ChunkDTO.ListVO listChunks(String datasetId,
|
||||
String documentId,
|
||||
String keywords,
|
||||
Integer page,
|
||||
Integer pageSize,
|
||||
String chunkId);
|
||||
ChunkDTO.ListReq req);
|
||||
|
||||
/**
|
||||
* 召回测试 - 从知识库中检索相关切片
|
||||
*
|
||||
* @param question 用户查询
|
||||
* @param datasetIds 数据集ID列表
|
||||
* @param documentIds 文档ID列表
|
||||
* @param retrievalParams 检索参数
|
||||
* @param req 检索测试请求参数
|
||||
* @return 召回测试结果
|
||||
*/
|
||||
public abstract Map<String, Object> retrievalTest(String question,
|
||||
List<String> datasetIds,
|
||||
List<String> documentIds,
|
||||
Map<String, Object> retrievalParams);
|
||||
public abstract RetrievalDTO.ResultVO retrievalTest(
|
||||
RetrievalDTO.TestReq req);
|
||||
|
||||
/**
|
||||
* 测试连接
|
||||
@@ -170,25 +152,27 @@ public abstract class KnowledgeBaseAdapter {
|
||||
/**
|
||||
* 创建数据集
|
||||
*
|
||||
* @param createParams 创建参数
|
||||
* @return 数据集ID
|
||||
* @param req 创建参数
|
||||
* @return 数据集详情
|
||||
*/
|
||||
public abstract String createDataset(Map<String, Object> createParams);
|
||||
public abstract DatasetDTO.InfoVO createDataset(DatasetDTO.CreateReq req);
|
||||
|
||||
/**
|
||||
* 更新数据集
|
||||
*
|
||||
* @param datasetId 数据集ID
|
||||
* @param updateParams 更新参数
|
||||
* @param datasetId 数据集ID
|
||||
* @param req 更新参数
|
||||
* @return 数据集详情
|
||||
*/
|
||||
public abstract void updateDataset(String datasetId, Map<String, Object> updateParams);
|
||||
public abstract DatasetDTO.InfoVO updateDataset(String datasetId, DatasetDTO.UpdateReq req);
|
||||
|
||||
/**
|
||||
* 删除数据集
|
||||
*
|
||||
* @param datasetId 数据集ID
|
||||
* @param req 删除请求参数（包含ID列表）
|
||||
* @return 批量操作结果
|
||||
*/
|
||||
public abstract void deleteDataset(String datasetId);
|
||||
public abstract DatasetDTO.BatchOperationVO deleteDataset(DatasetDTO.BatchIdReq req);
|
||||
|
||||
/**
|
||||
* 获取数据集的文档数量
|
||||
@@ -197,4 +181,35 @@ public abstract class KnowledgeBaseAdapter {
|
||||
* @return 文档数量
|
||||
*/
|
||||
public abstract Integer getDocumentCount(String datasetId);
|
||||
|
||||
/**
|
||||
* 发送流式请求 (SSE)
|
||||
*
|
||||
* @param endpoint API端点
|
||||
* @param body 请求体
|
||||
* @param onData 数据回调
|
||||
*/
|
||||
public abstract void postStream(String endpoint, Object body, Consumer<String> onData);
|
||||
|
||||
/**
|
||||
* SearchBot 提问
|
||||
*
|
||||
* @param config RAG配置
|
||||
* @param body 请求体
|
||||
* @param onData 数据回调
|
||||
* @return 响应对象
|
||||
*/
|
||||
public abstract Object postSearchBotAsk(Map<String, Object> config, Object body,
|
||||
Consumer<String> onData);
|
||||
|
||||
/**
|
||||
* AgentBot 对话
|
||||
*
|
||||
* @param config RAG配置
|
||||
* @param agentId Agent ID
|
||||
* @param body 请求体
|
||||
* @param onData 数据回调
|
||||
*/
|
||||
public abstract void postAgentBotCompletion(Map<String, Object> config, String agentId, Object body,
|
||||
Consumer<String> onData);
|
||||
}
|
||||
+10
-1
@@ -22,6 +22,9 @@ public class KnowledgeBaseAdapterFactory {
|
||||
// 适配器实例缓存
|
||||
private static final Map<String, KnowledgeBaseAdapter> adapterCache = new ConcurrentHashMap<>();
|
||||
|
||||
// 最大缓存实例数，防止内存泄露 (Issue 9)
|
||||
private static final int MAX_CACHE_SIZE = 50;
|
||||
|
||||
static {
|
||||
// 注册内置适配器类型
|
||||
registerAdapter("ragflow", xiaozhi.modules.knowledge.rag.impl.RAGFlowAdapter.class);
|
||||
@@ -61,7 +64,13 @@ public class KnowledgeBaseAdapterFactory {
|
||||
// 创建新的适配器实例
|
||||
KnowledgeBaseAdapter adapter = createAdapter(adapterType, config);
|
||||
|
||||
// 缓存适配器实例
|
||||
// 缓存适配器实例 (带容量限制检查)
|
||||
if (adapterCache.size() >= MAX_CACHE_SIZE) {
|
||||
log.warn("适配器缓存已达上限 ({})，执行内存保护性清除", MAX_CACHE_SIZE);
|
||||
// 简单处理：直接清空，生产环境下建议使用 LRU
|
||||
adapterCache.clear();
|
||||
}
|
||||
|
||||
adapterCache.put(cacheKey, adapter);
|
||||
log.info("创建并缓存适配器实例: {}", cacheKey);
|
||||
|
||||
|
||||
@@ -0,0 +1,278 @@
|
||||
package xiaozhi.modules.knowledge.rag;
|
||||
|
||||
import java.time.Duration;
|
||||
import java.nio.charset.StandardCharsets;
|
||||
import java.util.Collections;
|
||||
import java.util.Map;
|
||||
|
||||
import org.springframework.boot.web.client.RestTemplateBuilder;
|
||||
import org.springframework.http.HttpEntity;
|
||||
import org.springframework.http.HttpHeaders;
|
||||
import org.springframework.http.HttpMethod;
|
||||
import org.springframework.http.MediaType;
|
||||
import org.springframework.http.ResponseEntity;
|
||||
import org.springframework.util.MultiValueMap;
|
||||
import org.springframework.web.client.RestTemplate;
|
||||
import org.springframework.http.client.SimpleClientHttpRequestFactory;
|
||||
|
||||
import java.text.SimpleDateFormat;
|
||||
import java.util.TimeZone;
|
||||
import java.util.Locale;
|
||||
import java.net.URLEncoder;
|
||||
import java.io.UnsupportedEncodingException;
|
||||
import java.net.http.HttpClient;
|
||||
import java.net.http.HttpRequest;
|
||||
import java.net.http.HttpResponse;
|
||||
import java.net.URI;
|
||||
import java.io.OutputStream;
|
||||
import java.io.ByteArrayOutputStream;
|
||||
import java.io.IOException;
|
||||
import java.util.function.Consumer;
|
||||
|
||||
import com.fasterxml.jackson.databind.ObjectMapper;
|
||||
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import xiaozhi.common.exception.ErrorCode;
|
||||
import xiaozhi.common.exception.RenException;
|
||||
|
||||
/**
|
||||
* RAGFlow HTTP Client
|
||||
* 统一处理HTTP通信、鉴权、超时与错误解析
|
||||
*/
|
||||
@Slf4j
|
||||
public class RAGFlowClient {
|
||||
|
||||
private final String baseUrl;
|
||||
private final String apiKey;
|
||||
private final RestTemplate restTemplate;
|
||||
private final ObjectMapper objectMapper;
|
||||
|
||||
// 默认超时时间 (秒)
|
||||
private static final int DEFAULT_TIMEOUT = 30;
|
||||
|
||||
public RAGFlowClient(String baseUrl, String apiKey) {
|
||||
this(baseUrl, apiKey, DEFAULT_TIMEOUT);
|
||||
}
|
||||
|
||||
public RAGFlowClient(String baseUrl, String apiKey, int timeoutSeconds) {
|
||||
this.baseUrl = baseUrl.endsWith("/") ? baseUrl.substring(0, baseUrl.length() - 1) : baseUrl;
|
||||
this.apiKey = apiKey;
|
||||
this.objectMapper = new ObjectMapper();
|
||||
// [Reinforce] 兼容 RAGFlow 返回的 RFC 1123 日期格式 (如: Tue, 10 Feb 2026 10:27:35 GMT)
|
||||
this.objectMapper
|
||||
.setDateFormat(new SimpleDateFormat("EEE, dd MMM yyyy HH:mm:ss 'GMT'", Locale.US));
|
||||
this.objectMapper.setTimeZone(TimeZone.getTimeZone("GMT"));
|
||||
|
||||
// 优先从 Spring 上下文中获取池化的 RestTemplate Bean (Issue 3: 连接池化)
|
||||
RestTemplate pooledTemplate = null;
|
||||
try {
|
||||
pooledTemplate = xiaozhi.common.utils.SpringContextUtils.getBean(RestTemplate.class);
|
||||
} catch (Exception e) {
|
||||
log.warn("无法从 SpringContext 获取池化 RestTemplate，将退化为简单连接模式: {}", e.getMessage());
|
||||
}
|
||||
|
||||
if (false) { // Force new RestTemplate for debugging
|
||||
this.restTemplate = pooledTemplate;
|
||||
log.debug("RAGFlowClient 已成功挂载全局池化 RestTemplate");
|
||||
} else {
|
||||
// 兜底方案：配置超时并创建简单 RestTemplate
|
||||
log.info("RAGFlowClient 初始化: 使用独立 RestTemplate (Debug Mode)");
|
||||
SimpleClientHttpRequestFactory factory = new SimpleClientHttpRequestFactory();
|
||||
factory.setConnectTimeout(timeoutSeconds * 1000);
|
||||
factory.setReadTimeout(timeoutSeconds * 1000);
|
||||
this.restTemplate = new RestTemplate(factory);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 发送 GET 请求
|
||||
*/
|
||||
public Map<String, Object> get(String endpoint, Map<String, Object> queryParams) {
|
||||
String url = buildUrl(endpoint, queryParams);
|
||||
log.debug("GET {}", url);
|
||||
return execute(url, HttpMethod.GET, null);
|
||||
}
|
||||
|
||||
/**
|
||||
* 发送 POST 请求 (JSON)
|
||||
*/
|
||||
public Map<String, Object> post(String endpoint, Object body) {
|
||||
String url = buildUrl(endpoint, null);
|
||||
log.info("RAGFlow Client POST Request: URL={}, BodyType={}", url,
|
||||
body != null ? body.getClass().getName() : "null");
|
||||
try {
|
||||
return execute(url, HttpMethod.POST, body);
|
||||
} catch (Exception e) {
|
||||
log.error("RAGFlow Client POST Failed: URL={}", url, e);
|
||||
throw e;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 发送 DELETE 请求
|
||||
*/
|
||||
public Map<String, Object> delete(String endpoint, Object body) {
|
||||
String url = buildUrl(endpoint, null);
|
||||
log.debug("DELETE {}", url);
|
||||
return execute(url, HttpMethod.DELETE, body);
|
||||
}
|
||||
|
||||
/**
|
||||
* 发送 PUT 请求
|
||||
*/
|
||||
public Map<String, Object> put(String endpoint, Object body) {
|
||||
String url = buildUrl(endpoint, null);
|
||||
log.debug("PUT {}", url);
|
||||
return execute(url, HttpMethod.PUT, body);
|
||||
}
|
||||
|
||||
/**
|
||||
* 发送 Multipart 请求 (文件上传)
|
||||
*/
|
||||
public Map<String, Object> postMultipart(String endpoint, MultiValueMap<String, Object> parts) {
|
||||
String url = buildUrl(endpoint, null);
|
||||
log.debug("POST MULTIPART {}", url);
|
||||
|
||||
HttpHeaders headers = new HttpHeaders();
|
||||
headers.setContentType(MediaType.MULTIPART_FORM_DATA);
|
||||
headers.setBearerAuth(apiKey);
|
||||
// 为了防止中文文件名乱码，某些环境可能需要设置 Charset，但在 Multipart 中通常由 Part header 控制
|
||||
|
||||
HttpEntity<MultiValueMap<String, Object>> requestEntity = new HttpEntity<>(parts, headers);
|
||||
|
||||
return doExecute(url, HttpMethod.POST, requestEntity);
|
||||
}
|
||||
|
||||
private Map<String, Object> execute(String url, HttpMethod method, Object body) {
|
||||
HttpHeaders headers = new HttpHeaders();
|
||||
headers.setContentType(MediaType.APPLICATION_JSON);
|
||||
headers.setBearerAuth(apiKey);
|
||||
// 强制 UTF-8
|
||||
headers.setAcceptCharset(Collections.singletonList(StandardCharsets.UTF_8));
|
||||
|
||||
HttpEntity<Object> requestEntity = new HttpEntity<>(body, headers);
|
||||
return doExecute(url, method, requestEntity);
|
||||
}
|
||||
|
||||
private Map<String, Object> doExecute(String url, HttpMethod method, HttpEntity<?> requestEntity) {
|
||||
try {
|
||||
ResponseEntity<String> response = restTemplate.exchange(url, method, requestEntity, String.class);
|
||||
|
||||
if (!response.getStatusCode().is2xxSuccessful()) {
|
||||
log.error("RAGFlow API Error Status: {}", response.getStatusCode());
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, "HTTP " + response.getStatusCode());
|
||||
}
|
||||
|
||||
String responseBody = response.getBody();
|
||||
if (responseBody == null) {
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, "Empty Response");
|
||||
}
|
||||
|
||||
@SuppressWarnings("unchecked")
|
||||
Map<String, Object> map = objectMapper.readValue(responseBody, Map.class);
|
||||
|
||||
Integer code = (Integer) map.get("code");
|
||||
if (code != null && code != 0) {
|
||||
String msg = (String) map.get("message");
|
||||
log.error("RAGFlow Business Error: code={}, msg={}", code, msg);
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, msg != null ? msg : "Unknown RAGFlow Error");
|
||||
}
|
||||
|
||||
// 返回 data 字段，如果 data 不存在则返回整个 map (视具体情况，通常 RAGFlow 返回 code=0, data=...)
|
||||
// 兼容性处理：如果 external caller 需要 check code，这里已经 check 过了。
|
||||
// 统一返回 wrap 了 code 的 map 还是只返回 data?
|
||||
// 根据分析报告，旧逻辑 check code==0 后取 data.
|
||||
// 这里我们返回整个 Map，让 Adapter 决定怎么取，或者我们直接在这里剥离？
|
||||
// 建议：为了灵活性，返回全量 Map，但在 Client 层做 code!=0 的抛错。
|
||||
return map;
|
||||
|
||||
} catch (RenException re) {
|
||||
throw re;
|
||||
} catch (Exception e) {
|
||||
log.error("RAGFlow Client Execute Error! URL: {}, Method: {}, Body Type: {}", url, method,
|
||||
requestEntity.getBody() != null ? requestEntity.getBody().getClass().getName() : "null");
|
||||
log.error("Full exception stack trace: ", e);
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, "Request Failed: " + e.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
private String buildUrl(String endpoint, Map<String, Object> queryParams) {
|
||||
StringBuilder sb = new StringBuilder(baseUrl);
|
||||
if (!endpoint.startsWith("/")) {
|
||||
sb.append("/");
|
||||
}
|
||||
sb.append(endpoint);
|
||||
|
||||
if (queryParams != null && !queryParams.isEmpty()) {
|
||||
sb.append("?");
|
||||
queryParams.forEach((k, v) -> {
|
||||
if (v != null) {
|
||||
try {
|
||||
sb.append(k).append("=")
|
||||
.append(URLEncoder.encode(v.toString(),
|
||||
StandardCharsets.UTF_8.name()))
|
||||
.append("&");
|
||||
} catch (UnsupportedEncodingException e) {
|
||||
log.warn("参数编码失败: k={}, v={}", k, v);
|
||||
sb.append(k).append("=").append(v).append("&");
|
||||
}
|
||||
}
|
||||
});
|
||||
// 移除最后一个 &
|
||||
sb.setLength(sb.length() - 1);
|
||||
}
|
||||
return sb.toString();
|
||||
}
|
||||
|
||||
/**
|
||||
* 发送流式 POST 请求 (SSE)
|
||||
* 使用 Java 21 HttpClient 实现
|
||||
*
|
||||
* @param endpoint API端点
|
||||
* @param body 请求体
|
||||
* @param onData 数据回调（每收到一行数据调用一次）
|
||||
*/
|
||||
public void postStream(String endpoint, Object body, Consumer<String> onData) {
|
||||
try {
|
||||
String url = buildUrl(endpoint, null);
|
||||
log.debug("POST STREAM {}", url);
|
||||
|
||||
String jsonBody = objectMapper.writeValueAsString(body);
|
||||
|
||||
HttpClient httpClient = HttpClient.newBuilder()
|
||||
.connectTimeout(Duration.ofSeconds(DEFAULT_TIMEOUT))
|
||||
.build();
|
||||
|
||||
HttpRequest request = HttpRequest.newBuilder()
|
||||
.uri(URI.create(url))
|
||||
.header("Content-Type", "application/json")
|
||||
.header("Authorization", "Bearer " + apiKey)
|
||||
.POST(HttpRequest.BodyPublishers.ofString(jsonBody, StandardCharsets.UTF_8))
|
||||
.build();
|
||||
|
||||
// 发送请求并处理流式响应
|
||||
httpClient.send(request, HttpResponse.BodyHandlers.ofInputStream())
|
||||
.body()
|
||||
.transferTo(new OutputStream() {
|
||||
private final ByteArrayOutputStream buffer = new ByteArrayOutputStream();
|
||||
|
||||
@Override
|
||||
public void write(int b) throws IOException {
|
||||
if (b == '\n') {
|
||||
String line = buffer.toString(StandardCharsets.UTF_8);
|
||||
if (!line.trim().isEmpty()) {
|
||||
onData.accept(line);
|
||||
}
|
||||
buffer.reset();
|
||||
} else {
|
||||
buffer.write(b);
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
} catch (Exception e) {
|
||||
log.error("RAGFlow Stream Request Error", e);
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, "Stream Request Failed: " + e.getMessage());
|
||||
}
|
||||
}
|
||||
}
|
||||
+455
-892
File diff suppressed because it is too large
Load Diff
+10
@@ -93,4 +93,14 @@ public interface KnowledgeBaseService extends BaseService<KnowledgeBaseEntity> {
|
||||
* @return RAG模型列表
|
||||
*/
|
||||
List<ModelConfigEntity> getRAGModels();
|
||||
|
||||
/**
|
||||
* 更新知识库统计信息 (用于被文件服务回调)
|
||||
*
|
||||
* @param datasetId 知识库ID
|
||||
* @param docDelta 文档数增量
|
||||
* @param chunkDelta 分块数增量
|
||||
* @param tokenDelta Token数增量
|
||||
*/
|
||||
void updateStatistics(String datasetId, Integer docDelta, Long chunkDelta, Long tokenDelta);
|
||||
}
|
||||
+42
-31
@@ -7,6 +7,9 @@ import org.springframework.web.multipart.MultipartFile;
|
||||
|
||||
import xiaozhi.common.page.PageData;
|
||||
import xiaozhi.modules.knowledge.dto.KnowledgeFilesDTO;
|
||||
import xiaozhi.modules.knowledge.dto.document.ChunkDTO;
|
||||
import xiaozhi.modules.knowledge.dto.document.RetrievalDTO;
|
||||
import xiaozhi.modules.knowledge.dto.document.DocumentDTO;
|
||||
|
||||
/**
|
||||
* 知识库文档服务接口
|
||||
@@ -28,9 +31,9 @@ public interface KnowledgeFilesService {
|
||||
*
|
||||
* @param documentId 文档ID
|
||||
* @param datasetId 知识库ID
|
||||
* @return 文档详情
|
||||
* @return 文档详情 (强类型 InfoVO)
|
||||
*/
|
||||
KnowledgeFilesDTO getByDocumentId(String documentId, String datasetId);
|
||||
DocumentDTO.InfoVO getByDocumentId(String documentId, String datasetId);
|
||||
|
||||
/**
|
||||
* 上传文档到知识库
|
||||
@@ -48,12 +51,12 @@ public interface KnowledgeFilesService {
|
||||
Map<String, Object> parserConfig);
|
||||
|
||||
/**
|
||||
* 根据文档ID和知识库ID删除文档
|
||||
* 批量删除文档
|
||||
*
|
||||
* @param documentId 文档ID
|
||||
* @param datasetId 知识库ID
|
||||
* @param datasetId 知识库ID
|
||||
* @param req 删除请求参数 (含文档ID列表)
|
||||
*/
|
||||
void deleteByDocumentId(String documentId, String datasetId);
|
||||
void deleteDocuments(String datasetId, DocumentDTO.BatchIdReq req);
|
||||
|
||||
/**
|
||||
* 获取RAG配置信息
|
||||
@@ -77,36 +80,44 @@ public interface KnowledgeFilesService {
|
||||
*
|
||||
* @param datasetId 知识库ID
|
||||
* @param documentId 文档ID
|
||||
* @param keywords 关键词过滤
|
||||
* @param page 页码
|
||||
* @param pageSize 每页数量
|
||||
* @param chunkId 切片ID
|
||||
* @param req 切片列表请求参数
|
||||
* @return 切片列表信息
|
||||
*/
|
||||
Map<String, Object> listChunks(String datasetId, String documentId, String keywords,
|
||||
Integer page, Integer pageSize, String chunkId);
|
||||
ChunkDTO.ListVO listChunks(String datasetId, String documentId, ChunkDTO.ListReq req);
|
||||
|
||||
/**
|
||||
* 召回测试 - 从指定数据集或文档中检索相关切片
|
||||
* 召回测试
|
||||
*
|
||||
* @param question 用户查询或查询关键词
|
||||
* @param datasetIds 数据集ID列表
|
||||
* @param documentIds 文档ID列表
|
||||
* @param page 页码
|
||||
* @param pageSize 每页数量
|
||||
* @param similarityThreshold 最小相似度阈值
|
||||
* @param vectorSimilarityWeight 向量相似度权重
|
||||
* @param topK 参与向量余弦计算的切片数量
|
||||
* @param rerankId 重排模型ID
|
||||
* @param keyword 是否启用关键词匹配
|
||||
* @param highlight 是否启用高亮显示
|
||||
* @param crossLanguages 跨语言翻译列表
|
||||
* @param metadataCondition 元数据过滤条件
|
||||
* @param req 检索测试请求参数
|
||||
* @return 召回测试结果
|
||||
*/
|
||||
Map<String, Object> retrievalTest(String question, List<String> datasetIds, List<String> documentIds,
|
||||
Integer page, Integer pageSize, Float similarityThreshold,
|
||||
Float vectorSimilarityWeight, Integer topK, String rerankId,
|
||||
Boolean keyword, Boolean highlight, List<String> crossLanguages,
|
||||
Map<String, Object> metadataCondition);
|
||||
RetrievalDTO.ResultVO retrievalTest(RetrievalDTO.TestReq req);
|
||||
|
||||
/**
|
||||
* 保存文档影子记录
|
||||
*/
|
||||
void saveDocumentShadow(String datasetId, KnowledgeFilesDTO result, String originalName, String chunkMethod,
|
||||
Map<String, Object> parserConfig);
|
||||
|
||||
/**
|
||||
* 批量删除文档影子记录并同步统计数据
|
||||
*
|
||||
* @param documentIds 文档ID列表
|
||||
* @param datasetId 数据集ID
|
||||
* @param chunkDelta 待扣减的总分块数
|
||||
* @param tokenDelta 待扣减的总Token数
|
||||
*/
|
||||
void deleteDocumentShadows(List<String> documentIds, String datasetId, Long chunkDelta, Long tokenDelta);
|
||||
|
||||
/**
|
||||
* 根据数据集ID清理所有关联文档 (级联删除专用)
|
||||
*
|
||||
* @param datasetId 数据集ID
|
||||
*/
|
||||
void deleteDocumentsByDatasetId(String datasetId);
|
||||
|
||||
/**
|
||||
* 同步所有处于 RUNNING 状态的文档 (供定时任务调用)
|
||||
*/
|
||||
void syncRunningDocuments();
|
||||
}
|
||||
+24
@@ -0,0 +1,24 @@
|
||||
package xiaozhi.modules.knowledge.service;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
/**
|
||||
* 知识库模块领域编排服务
|
||||
* 用于处理跨 KnowledgeBase 和 KnowledgeFiles 的复杂业务流程，彻底解决 Service 间的循环依赖问题。
|
||||
*/
|
||||
public interface KnowledgeManagerService {
|
||||
|
||||
/**
|
||||
* 级联删除知识库及其下属所有文档 (包括本地 DB 和 RAGFlow 远程数据)
|
||||
*
|
||||
* @param datasetId 知识库 ID
|
||||
*/
|
||||
void deleteDatasetWithFiles(String datasetId);
|
||||
|
||||
/**
|
||||
* 批量级联删除知识库
|
||||
*
|
||||
* @param datasetIds 知识库 ID 列表
|
||||
*/
|
||||
void batchDeleteDatasetsWithFiles(List<String> datasetIds);
|
||||
}
|
||||
+283
-513
@@ -1,19 +1,14 @@
|
||||
package xiaozhi.modules.knowledge.service.impl;
|
||||
|
||||
import java.io.Serializable;
|
||||
import java.util.HashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
import org.apache.commons.lang3.StringUtils;
|
||||
import org.springframework.stereotype.Service;
|
||||
import org.springframework.web.client.RestTemplate;
|
||||
import com.baomidou.mybatisplus.core.conditions.query.QueryWrapper;
|
||||
import com.baomidou.mybatisplus.core.metadata.IPage;
|
||||
import com.baomidou.mybatisplus.extension.plugins.pagination.Page;
|
||||
import com.fasterxml.jackson.databind.ObjectMapper;
|
||||
|
||||
import lombok.AllArgsConstructor;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.apache.commons.lang3.StringUtils;
|
||||
import org.springframework.stereotype.Service;
|
||||
import org.springframework.transaction.annotation.Transactional;
|
||||
import org.springframework.beans.BeanUtils;
|
||||
import xiaozhi.common.constant.Constant;
|
||||
import xiaozhi.common.exception.ErrorCode;
|
||||
import xiaozhi.common.exception.RenException;
|
||||
@@ -22,10 +17,10 @@ import xiaozhi.common.redis.RedisKeys;
|
||||
import xiaozhi.common.redis.RedisUtils;
|
||||
import xiaozhi.common.service.impl.BaseServiceImpl;
|
||||
import xiaozhi.common.utils.ConvertUtils;
|
||||
import xiaozhi.common.utils.MessageUtils;
|
||||
import xiaozhi.common.utils.ToolUtil;
|
||||
import xiaozhi.common.utils.JsonUtils;
|
||||
import xiaozhi.modules.knowledge.dao.KnowledgeBaseDao;
|
||||
import xiaozhi.modules.knowledge.dto.KnowledgeBaseDTO;
|
||||
import xiaozhi.modules.knowledge.dto.dataset.DatasetDTO;
|
||||
import xiaozhi.modules.knowledge.entity.KnowledgeBaseEntity;
|
||||
import xiaozhi.modules.knowledge.rag.KnowledgeBaseAdapter;
|
||||
import xiaozhi.modules.knowledge.rag.KnowledgeBaseAdapterFactory;
|
||||
@@ -35,6 +30,15 @@ import xiaozhi.modules.model.entity.ModelConfigEntity;
|
||||
import xiaozhi.modules.model.service.ModelConfigService;
|
||||
import xiaozhi.modules.security.user.SecurityUser;
|
||||
|
||||
import java.util.Collections;
|
||||
import java.util.HashMap;
|
||||
import java.util.List;
|
||||
import java.util.Map;
|
||||
|
||||
/**
|
||||
* 知识库服务实现类 (Refactored)
|
||||
* 集成 RAGFlow Adapter 与 Shadow DB 模式
|
||||
*/
|
||||
@Service
|
||||
@AllArgsConstructor
|
||||
@Slf4j
|
||||
@@ -46,200 +50,50 @@ public class KnowledgeBaseServiceImpl extends BaseServiceImpl<KnowledgeBaseDao,
|
||||
private final ModelConfigDao modelConfigDao;
|
||||
private final RedisUtils redisUtils;
|
||||
|
||||
@Override
|
||||
public KnowledgeBaseEntity selectById(Serializable datasetId) {
|
||||
if (datasetId == null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// 先从Redis获取缓存
|
||||
String key = RedisKeys.getKnowledgeBaseCacheKey(datasetId.toString());
|
||||
KnowledgeBaseEntity cachedEntity = (KnowledgeBaseEntity) redisUtils.get(key);
|
||||
if (cachedEntity != null) {
|
||||
return cachedEntity;
|
||||
}
|
||||
|
||||
// 如果缓存中没有，则从数据库获取
|
||||
KnowledgeBaseEntity entity = knowledgeBaseDao.selectById(datasetId);
|
||||
if (entity == null) {
|
||||
return null;
|
||||
}
|
||||
|
||||
// 存入Redis缓存
|
||||
redisUtils.set(key, entity);
|
||||
|
||||
return entity;
|
||||
}
|
||||
|
||||
@Override
|
||||
public PageData<KnowledgeBaseDTO> getPageList(KnowledgeBaseDTO knowledgeBaseDTO, Integer page, Integer limit) {
|
||||
long curPage = page;
|
||||
long pageSize = limit;
|
||||
Page<KnowledgeBaseEntity> pageInfo = new Page<>(curPage, pageSize);
|
||||
|
||||
Page<KnowledgeBaseEntity> pageInfo = new Page<>(page, limit);
|
||||
QueryWrapper<KnowledgeBaseEntity> queryWrapper = new QueryWrapper<>();
|
||||
|
||||
// 添加查询条件
|
||||
if (knowledgeBaseDTO != null) {
|
||||
queryWrapper.like(StringUtils.isNotBlank(knowledgeBaseDTO.getName()), "name", knowledgeBaseDTO.getName());
|
||||
queryWrapper.eq(knowledgeBaseDTO.getStatus() != null, "status", knowledgeBaseDTO.getStatus());
|
||||
queryWrapper.eq("creator", knowledgeBaseDTO.getCreator());
|
||||
}
|
||||
|
||||
// 添加排序规则：按创建时间降序
|
||||
queryWrapper.orderByDesc("created_at");
|
||||
|
||||
IPage<KnowledgeBaseEntity> knowledgeBaseEntityIPage = knowledgeBaseDao.selectPage(pageInfo, queryWrapper);
|
||||
IPage<KnowledgeBaseEntity> iPage = knowledgeBaseDao.selectPage(pageInfo, queryWrapper);
|
||||
PageData<KnowledgeBaseDTO> pageData = getPageData(iPage, KnowledgeBaseDTO.class);
|
||||
|
||||
// 获取分页数据
|
||||
PageData<KnowledgeBaseDTO> pageData = getPageData(knowledgeBaseEntityIPage, KnowledgeBaseDTO.class);
|
||||
|
||||
// 为每个知识库获取文档数量
|
||||
// Enrich with Document Count from RAG (Optional / Lazy)
|
||||
if (pageData != null && pageData.getList() != null) {
|
||||
for (KnowledgeBaseDTO knowledgeBase : pageData.getList()) {
|
||||
try {
|
||||
Integer documentCount = getDocumentCountFromRAG(knowledgeBase.getDatasetId(),
|
||||
knowledgeBase.getRagModelId());
|
||||
knowledgeBase.setDocumentCount(documentCount);
|
||||
} catch (Exception e) {
|
||||
// 构建详细的错误信息，包含异常类型和消息
|
||||
String baseErrorMessage = e.getClass().getSimpleName() + " - 获取知识库文档数量失败";
|
||||
String errorMessage = baseErrorMessage + (e.getMessage() != null ? ": " + e.getMessage() : "");
|
||||
log.warn("知识库 {} {}", knowledgeBase.getDatasetId(), errorMessage);
|
||||
knowledgeBase.setDocumentCount(0); // 设置默认值
|
||||
}
|
||||
for (KnowledgeBaseDTO dto : pageData.getList()) {
|
||||
enrichDocumentCount(dto);
|
||||
}
|
||||
}
|
||||
|
||||
return pageData;
|
||||
}
|
||||
|
||||
private void enrichDocumentCount(KnowledgeBaseDTO dto) {
|
||||
try {
|
||||
if (StringUtils.isNotBlank(dto.getDatasetId()) && StringUtils.isNotBlank(dto.getRagModelId())) {
|
||||
KnowledgeBaseAdapter adapter = getAdapterByModelId(dto.getRagModelId());
|
||||
if (adapter != null) {
|
||||
dto.setDocumentCount(adapter.getDocumentCount(dto.getDatasetId()));
|
||||
}
|
||||
}
|
||||
} catch (Exception e) {
|
||||
log.warn("无法获取知识库 {} 的文档计数: {}", dto.getName(), e.getMessage());
|
||||
dto.setDocumentCount(0);
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
public KnowledgeBaseDTO getById(String id) {
|
||||
if (StringUtils.isBlank(id)) {
|
||||
throw new RenException(ErrorCode.IDENTIFIER_NOT_NULL);
|
||||
}
|
||||
|
||||
KnowledgeBaseEntity entity = knowledgeBaseDao.selectById(id);
|
||||
if (entity == null) {
|
||||
throw new RenException(ErrorCode.Knowledge_Base_RECORD_NOT_EXISTS);
|
||||
}
|
||||
|
||||
return ConvertUtils.sourceToTarget(entity, KnowledgeBaseDTO.class);
|
||||
}
|
||||
|
||||
@Override
|
||||
public KnowledgeBaseDTO save(KnowledgeBaseDTO knowledgeBaseDTO) {
|
||||
if (knowledgeBaseDTO == null) {
|
||||
throw new RenException(ErrorCode.PARAMS_GET_ERROR);
|
||||
}
|
||||
|
||||
// 检查是否存在同名知识库
|
||||
checkDuplicateKnowledgeBaseName(knowledgeBaseDTO, null);
|
||||
|
||||
String datasetId = null;
|
||||
// 调用RAG API创建数据集
|
||||
try {
|
||||
Map<String, Object> ragConfig = getValidatedRAGConfig(knowledgeBaseDTO.getRagModelId());
|
||||
datasetId = createDatasetInRAG(
|
||||
knowledgeBaseDTO.getName(),
|
||||
knowledgeBaseDTO.getDescription(),
|
||||
ragConfig);
|
||||
} catch (Exception e) {
|
||||
// 如果RAG API调用失败，直接抛出异常
|
||||
throw e;
|
||||
}
|
||||
|
||||
// 验证数据集ID是否已存在
|
||||
KnowledgeBaseEntity existingEntity = knowledgeBaseDao.selectOne(
|
||||
new QueryWrapper<KnowledgeBaseEntity>().eq("dataset_id", datasetId));
|
||||
if (existingEntity != null) {
|
||||
// 如果datasetId已存在，删除RAG中的数据集并抛出异常
|
||||
try {
|
||||
Map<String, Object> ragConfig = getValidatedRAGConfig(knowledgeBaseDTO.getRagModelId());
|
||||
deleteDatasetInRAG(datasetId, ragConfig);
|
||||
} catch (Exception deleteException) {
|
||||
// 提供更详细的错误信息，包括异常类型和消息
|
||||
String errorMessage = "删除重复datasetId的RAG数据集失败: " + deleteException.getClass().getSimpleName();
|
||||
if (deleteException.getMessage() != null) {
|
||||
errorMessage += " - " + deleteException.getMessage();
|
||||
}
|
||||
log.warn(errorMessage, deleteException);
|
||||
}
|
||||
throw new RenException(ErrorCode.DB_RECORD_EXISTS);
|
||||
}
|
||||
|
||||
// 创建本地实体并保存
|
||||
KnowledgeBaseEntity entity = ConvertUtils.sourceToTarget(knowledgeBaseDTO, KnowledgeBaseEntity.class);
|
||||
entity.setDatasetId(datasetId);
|
||||
knowledgeBaseDao.insert(entity);
|
||||
|
||||
return ConvertUtils.sourceToTarget(entity, KnowledgeBaseDTO.class);
|
||||
}
|
||||
|
||||
@Override
|
||||
public KnowledgeBaseDTO update(KnowledgeBaseDTO knowledgeBaseDTO) {
|
||||
if (knowledgeBaseDTO == null || StringUtils.isBlank(knowledgeBaseDTO.getId())) {
|
||||
throw new RenException(ErrorCode.IDENTIFIER_NOT_NULL);
|
||||
}
|
||||
|
||||
// 检查记录是否存在
|
||||
KnowledgeBaseEntity existingEntity = knowledgeBaseDao.selectById(knowledgeBaseDTO.getId());
|
||||
if (existingEntity == null) {
|
||||
throw new RenException(ErrorCode.Knowledge_Base_RECORD_NOT_EXISTS);
|
||||
}
|
||||
|
||||
// 检查是否存在同名知识库（排除当前记录）
|
||||
checkDuplicateKnowledgeBaseName(knowledgeBaseDTO, knowledgeBaseDTO.getId());
|
||||
|
||||
// 验证数据集ID是否与其他记录冲突
|
||||
if (StringUtils.isNotBlank(knowledgeBaseDTO.getDatasetId())) {
|
||||
KnowledgeBaseEntity conflictEntity = knowledgeBaseDao.selectOne(
|
||||
new QueryWrapper<KnowledgeBaseEntity>()
|
||||
.eq("dataset_id", knowledgeBaseDTO.getDatasetId())
|
||||
.ne("id", knowledgeBaseDTO.getId()));
|
||||
if (conflictEntity != null) {
|
||||
throw new RenException(ErrorCode.DB_RECORD_EXISTS);
|
||||
}
|
||||
}
|
||||
|
||||
boolean needRagValidation = StringUtils.isNotBlank(knowledgeBaseDTO.getDatasetId())
|
||||
&& StringUtils.isNotBlank(knowledgeBaseDTO.getRagModelId());
|
||||
|
||||
if (needRagValidation) {
|
||||
try {
|
||||
// 先校验RAG配置
|
||||
Map<String, Object> ragConfig = getValidatedRAGConfig(knowledgeBaseDTO.getRagModelId());
|
||||
|
||||
// 调用RAG API更新数据集
|
||||
updateDatasetInRAG(
|
||||
knowledgeBaseDTO.getDatasetId(),
|
||||
knowledgeBaseDTO.getName(),
|
||||
knowledgeBaseDTO.getDescription(),
|
||||
ragConfig);
|
||||
|
||||
log.info("RAG API更新成功，datasetId: {}", knowledgeBaseDTO.getDatasetId());
|
||||
} catch (Exception e) {
|
||||
// 提供更详细的错误信息，包括异常类型和消息
|
||||
String errorMessage = "更新RAG数据集失败: " + e.getClass().getSimpleName();
|
||||
if (e.getMessage() != null) {
|
||||
errorMessage += " - " + e.getMessage();
|
||||
}
|
||||
log.error(errorMessage, e);
|
||||
throw e;
|
||||
}
|
||||
} else {
|
||||
log.warn("datasetId或ragModelId为空，跳过RAG更新");
|
||||
}
|
||||
|
||||
KnowledgeBaseEntity entity = ConvertUtils.sourceToTarget(knowledgeBaseDTO, KnowledgeBaseEntity.class);
|
||||
knowledgeBaseDao.updateById(entity);
|
||||
|
||||
// 删除缓存
|
||||
if (entity.getDatasetId() != null) {
|
||||
redisUtils.delete(RedisKeys.getKnowledgeBaseCacheKey(entity.getId()));
|
||||
}
|
||||
|
||||
return ConvertUtils.sourceToTarget(entity, KnowledgeBaseDTO.class);
|
||||
}
|
||||
|
||||
@@ -248,400 +102,316 @@ public class KnowledgeBaseServiceImpl extends BaseServiceImpl<KnowledgeBaseDao,
|
||||
if (StringUtils.isBlank(datasetId)) {
|
||||
throw new RenException(ErrorCode.PARAMS_GET_ERROR);
|
||||
}
|
||||
|
||||
KnowledgeBaseEntity entity = knowledgeBaseDao.selectOne(
|
||||
new QueryWrapper<KnowledgeBaseEntity>().eq("dataset_id", datasetId));
|
||||
|
||||
// [Production Fix] 兼容性查找：优先通过 dataset_id 找，找不到通过主键 id 找，确保前端传哪种 UUID 都能命中
|
||||
KnowledgeBaseEntity entity = knowledgeBaseDao
|
||||
.selectOne(new QueryWrapper<KnowledgeBaseEntity>()
|
||||
.eq("dataset_id", datasetId)
|
||||
.or()
|
||||
.eq("id", datasetId));
|
||||
if (entity == null) {
|
||||
throw new RenException(ErrorCode.Knowledge_Base_RECORD_NOT_EXISTS);
|
||||
}
|
||||
return ConvertUtils.sourceToTarget(entity, KnowledgeBaseDTO.class);
|
||||
}
|
||||
|
||||
@Override
|
||||
@Transactional(rollbackFor = Exception.class)
|
||||
public KnowledgeBaseDTO save(KnowledgeBaseDTO dto) {
|
||||
// 1. Validation
|
||||
checkDuplicateName(dto.getName(), null);
|
||||
KnowledgeBaseAdapter adapter = null;
|
||||
|
||||
// 2. RAG Creation
|
||||
String datasetId = null;
|
||||
try {
|
||||
// 若未指定 RAG 模型，自动使用系统默认
|
||||
if (StringUtils.isBlank(dto.getRagModelId())) {
|
||||
List<ModelConfigEntity> models = getRAGModels();
|
||||
if (models != null && !models.isEmpty()) {
|
||||
dto.setRagModelId(models.get(0).getId());
|
||||
} else {
|
||||
throw new RenException(ErrorCode.RAG_CONFIG_NOT_FOUND, "未指定且无可用默认 RAG 模型");
|
||||
}
|
||||
}
|
||||
|
||||
Map<String, Object> ragConfig = getValidatedRAGConfig(dto.getRagModelId());
|
||||
adapter = KnowledgeBaseAdapterFactory.getAdapter((String) ragConfig.get("type"),
|
||||
ragConfig);
|
||||
|
||||
DatasetDTO.CreateReq createReq = ConvertUtils.sourceToTarget(dto, DatasetDTO.CreateReq.class);
|
||||
createReq.setName(SecurityUser.getUser().getUsername() + "_" + dto.getName());
|
||||
|
||||
DatasetDTO.InfoVO ragResponse = adapter.createDataset(createReq);
|
||||
if (ragResponse == null || StringUtils.isBlank(ragResponse.getId())) {
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, "RAG创建返回无效: 缺失ID");
|
||||
}
|
||||
datasetId = ragResponse.getId();
|
||||
|
||||
// 3. Local Save (Shadow)
|
||||
KnowledgeBaseEntity entity = ConvertUtils.sourceToTarget(dto, KnowledgeBaseEntity.class);
|
||||
|
||||
// [Production Fix] 统一本地 ID 与 RAGFlow ID，防止前端调用 /delete 或 /update 时因 ID 混淆（本地
|
||||
// UUID vs RAG UUID）导致 10163 错误
|
||||
entity.setId(datasetId);
|
||||
entity.setDatasetId(datasetId);
|
||||
entity.setStatus(1); // Default Enabled
|
||||
|
||||
// ✅ FULL PERSISTENCE: 严格全量回写 (User Requirement)
|
||||
// 使用强类型 DTO 属性获取，不再从 Map 中手动解析 Key
|
||||
entity.setTenantId(ragResponse.getTenantId());
|
||||
entity.setChunkMethod(ragResponse.getChunkMethod());
|
||||
entity.setEmbeddingModel(ragResponse.getEmbeddingModel());
|
||||
entity.setPermission(ragResponse.getPermission());
|
||||
|
||||
if (StringUtils.isBlank(entity.getAvatar())) {
|
||||
entity.setAvatar(ragResponse.getAvatar());
|
||||
}
|
||||
|
||||
// Parse Config (JSON)
|
||||
if (ragResponse.getParserConfig() != null) {
|
||||
entity.setParserConfig(JsonUtils.toJsonString(ragResponse.getParserConfig()));
|
||||
}
|
||||
|
||||
// Numeric fields
|
||||
entity.setChunkCount(ragResponse.getChunkCount() != null ? ragResponse.getChunkCount() : 0L);
|
||||
entity.setDocumentCount(ragResponse.getDocumentCount() != null ? ragResponse.getDocumentCount() : 0L);
|
||||
entity.setTokenNum(ragResponse.getTokenNum() != null ? ragResponse.getTokenNum() : 0L);
|
||||
|
||||
// 清空 creator/updater，让 FieldMetaObjectHandler 从 SecurityUser 自动填充
|
||||
// ConvertUtils 会把 DTO 中的 creator=0 拷贝过来，导致 strictInsertFill 跳过填充
|
||||
entity.setCreator(null);
|
||||
entity.setUpdater(null);
|
||||
|
||||
knowledgeBaseDao.insert(entity);
|
||||
return ConvertUtils.sourceToTarget(entity, KnowledgeBaseDTO.class);
|
||||
} catch (Exception e) {
|
||||
log.error("RAG创建或本地保存失败", e);
|
||||
// 如果datasetId已生成但在保存本地时失败，尝试回滚RAG (Best Effort)
|
||||
if (StringUtils.isNotBlank(datasetId)) {
|
||||
try {
|
||||
if (adapter != null)
|
||||
adapter.deleteDataset(
|
||||
DatasetDTO.BatchIdReq.builder().ids(Collections.singletonList(datasetId)).build());
|
||||
} catch (Exception rollbackEx) {
|
||||
log.error("RAG回滚失败: {}", datasetId, rollbackEx);
|
||||
}
|
||||
}
|
||||
if (e instanceof RenException) {
|
||||
throw (RenException) e;
|
||||
}
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, "创建知识库失败: " + e.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
@Override
|
||||
@Transactional(rollbackFor = Exception.class)
|
||||
@SuppressWarnings("deprecation")
|
||||
public KnowledgeBaseDTO update(KnowledgeBaseDTO dto) {
|
||||
log.info("Update Service Called: ID={}, DatasetID={}", dto.getId(), dto.getDatasetId());
|
||||
KnowledgeBaseEntity entity = knowledgeBaseDao.selectById(dto.getId());
|
||||
if (entity == null) {
|
||||
log.error("Update failed: Entity not found for ID={}", dto.getId());
|
||||
throw new RenException(ErrorCode.Knowledge_Base_RECORD_NOT_EXISTS);
|
||||
}
|
||||
|
||||
checkDuplicateName(dto.getName(), dto.getId());
|
||||
|
||||
// 验证数据集ID是否与其他记录冲突
|
||||
if (StringUtils.isNotBlank(dto.getDatasetId())) {
|
||||
KnowledgeBaseEntity conflictEntity = knowledgeBaseDao.selectOne(
|
||||
new QueryWrapper<KnowledgeBaseEntity>()
|
||||
.eq("dataset_id", dto.getDatasetId())
|
||||
.ne("id", dto.getId()));
|
||||
if (conflictEntity != null) {
|
||||
throw new RenException(ErrorCode.DB_RECORD_EXISTS);
|
||||
}
|
||||
}
|
||||
|
||||
// RAG Update if needed
|
||||
if (StringUtils.isNotBlank(entity.getDatasetId()) && StringUtils.isNotBlank(dto.getRagModelId())) {
|
||||
try {
|
||||
// 🤖 AUTO-FILL: 若 DTO 未传 ragModelId (极少情况)，尝试复用 Entity 中的
|
||||
if (StringUtils.isBlank(dto.getRagModelId())) {
|
||||
dto.setRagModelId(entity.getRagModelId());
|
||||
}
|
||||
|
||||
// [FIX] 智能补全：如果 DTO 里的关键字段为空，则使用 Entity 里的旧值
|
||||
// 确保发给 RAGFlow 的请求包含所有必填项 (Partial Update Support)
|
||||
if (StringUtils.isBlank(dto.getPermission())) {
|
||||
dto.setPermission(entity.getPermission());
|
||||
}
|
||||
if (StringUtils.isBlank(dto.getChunkMethod())) {
|
||||
dto.setChunkMethod(entity.getChunkMethod());
|
||||
}
|
||||
|
||||
KnowledgeBaseAdapter adapter = getAdapterByModelId(dto.getRagModelId());
|
||||
if (adapter != null) {
|
||||
DatasetDTO.UpdateReq updateReq = ConvertUtils.sourceToTarget(dto, DatasetDTO.UpdateReq.class);
|
||||
|
||||
// 1. 必填/核心字段前缀处理
|
||||
if (StringUtils.isNotBlank(dto.getName())) {
|
||||
updateReq.setName(SecurityUser.getUser().getUsername() + "_" + dto.getName());
|
||||
}
|
||||
|
||||
// 2. 解析器配置支持 (如果 DTO 里有字符串形式的配置，尝试转换，但优先建议 DTO 化)
|
||||
if (StringUtils.isNotBlank(dto.getParserConfig())) {
|
||||
try {
|
||||
DatasetDTO.ParserConfig parserConfig = JsonUtils.parseObject(dto.getParserConfig(),
|
||||
DatasetDTO.ParserConfig.class);
|
||||
updateReq.setParserConfig(parserConfig);
|
||||
} catch (Exception e) {
|
||||
log.warn("解析 parser_config 失败，跳过同步", e);
|
||||
}
|
||||
}
|
||||
|
||||
adapter.updateDataset(entity.getDatasetId(), updateReq);
|
||||
log.info("RAG更新成功: {}", entity.getDatasetId());
|
||||
}
|
||||
} catch (Exception e) {
|
||||
log.error("RAG更新失败", e);
|
||||
// 恢复事务一致性：RAG失败则整体回滚
|
||||
if (e instanceof RenException) {
|
||||
throw (RenException) e;
|
||||
}
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, "RAG更新失败: " + e.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
BeanUtils.copyProperties(dto, entity);
|
||||
knowledgeBaseDao.updateById(entity);
|
||||
|
||||
// Clean cache
|
||||
redisUtils.delete(RedisKeys.getKnowledgeBaseCacheKey(entity.getId()));
|
||||
|
||||
return ConvertUtils.sourceToTarget(entity, KnowledgeBaseDTO.class);
|
||||
}
|
||||
|
||||
/**
|
||||
* 根据知识库ID集合查询知识库
|
||||
* @param datasetIdList 知识库ID集合
|
||||
* @return
|
||||
*/
|
||||
@Override
|
||||
public List<KnowledgeBaseDTO> getByDatasetIdList(List<String> datasetIdList) {
|
||||
//判断参数
|
||||
if (ToolUtil.isEmpty(datasetIdList)) {
|
||||
throw new RenException(ErrorCode.PARAMS_GET_ERROR);
|
||||
}
|
||||
//批量查询
|
||||
List<KnowledgeBaseEntity> entityList = knowledgeBaseDao.selectList(
|
||||
new QueryWrapper<KnowledgeBaseEntity>().in("dataset_id", datasetIdList));
|
||||
if (ToolUtil.isEmpty(entityList)) {
|
||||
throw new RenException(ErrorCode.Knowledge_Base_RECORD_NOT_EXISTS);
|
||||
}
|
||||
return ConvertUtils.sourceToTarget(entityList, KnowledgeBaseDTO.class);
|
||||
}
|
||||
|
||||
@Override
|
||||
@Transactional(rollbackFor = Exception.class)
|
||||
public void deleteByDatasetId(String datasetId) {
|
||||
if (StringUtils.isBlank(datasetId)) {
|
||||
throw new RenException(ErrorCode.PARAMS_GET_ERROR);
|
||||
}
|
||||
|
||||
log.info("=== 开始通过datasetId删除操作 ===");
|
||||
log.info("删除datasetId: {}", datasetId);
|
||||
|
||||
KnowledgeBaseEntity entity = knowledgeBaseDao.selectOne(
|
||||
new QueryWrapper<KnowledgeBaseEntity>().eq("dataset_id", datasetId));
|
||||
KnowledgeBaseEntity entity = knowledgeBaseDao
|
||||
.selectOne(new QueryWrapper<KnowledgeBaseEntity>().eq("dataset_id", datasetId));
|
||||
|
||||
// 1. 恢复 404 校验：找不到记录抛异常
|
||||
if (entity == null) {
|
||||
log.warn("记录不存在，datasetId: {}", datasetId);
|
||||
throw new RenException(ErrorCode.Knowledge_Base_RECORD_NOT_EXISTS);
|
||||
}
|
||||
redisUtils.delete(RedisKeys.getKnowledgeBaseCacheKey(entity.getId()));
|
||||
|
||||
log.info("找到记录: ID={}, datasetId={}, ragModelId={}",
|
||||
entity.getId(), entity.getDatasetId(), entity.getRagModelId());
|
||||
|
||||
// 先调用RAG API删除数据集
|
||||
// 2. RAG Delete (Strict Mode)
|
||||
// 恢复严格一致性：RAG 删除失败则抛出异常，触发事务回滚，不允许已删除本地但保留远程的脏数据
|
||||
boolean apiDeleteSuccess = false;
|
||||
if (StringUtils.isNotBlank(entity.getDatasetId()) && StringUtils.isNotBlank(entity.getRagModelId())) {
|
||||
if (StringUtils.isNotBlank(entity.getRagModelId()) && StringUtils.isNotBlank(entity.getDatasetId())) {
|
||||
try {
|
||||
log.info("开始调用RAG API删除数据集");
|
||||
// 在删除前进行RAG配置校验
|
||||
Map<String, Object> ragConfig = getValidatedRAGConfig(entity.getRagModelId());
|
||||
deleteDatasetInRAG(entity.getDatasetId(), ragConfig);
|
||||
log.info("RAG API删除调用完成");
|
||||
KnowledgeBaseAdapter adapter = getAdapterByModelId(entity.getRagModelId());
|
||||
if (adapter != null) {
|
||||
adapter.deleteDataset(
|
||||
DatasetDTO.BatchIdReq.builder().ids(Collections.singletonList(datasetId)).build());
|
||||
}
|
||||
apiDeleteSuccess = true;
|
||||
} catch (Exception e) {
|
||||
// 提供更详细的错误信息，包括异常类型和消息
|
||||
String errorMessage = "删除RAG数据集失败: " + e.getClass().getSimpleName();
|
||||
if (e.getMessage() != null) {
|
||||
errorMessage += " - " + e.getMessage();
|
||||
log.error("RAG删除失败，触发回滚", e);
|
||||
if (e instanceof RenException) {
|
||||
throw (RenException) e;
|
||||
}
|
||||
log.error(errorMessage, e);
|
||||
throw e;
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, "RAG删除失败: " + e.getMessage());
|
||||
}
|
||||
} else {
|
||||
log.warn("datasetId或ragModelId为空，跳过RAG删除");
|
||||
apiDeleteSuccess = true; // 没有RAG数据集，视为成功
|
||||
}
|
||||
|
||||
// API删除成功后再删除本地记录
|
||||
// 3. Local Delete (Safe Order)
|
||||
// 恢复正确顺序：先删子表 (Plugin Mapping)，再删主表 (Entity)
|
||||
if (apiDeleteSuccess) {
|
||||
log.info("开始删除ai_agent_plugin_mapping表中与知识库ID '{}' 相关的映射记录", entity.getId());
|
||||
|
||||
// 先删除相关的插件映射记录
|
||||
log.info("开始删除关联数据, entityId: {}", entity.getId());
|
||||
knowledgeBaseDao.deletePluginMappingByKnowledgeBaseId(entity.getId());
|
||||
log.info("插件映射记录删除完成");
|
||||
|
||||
int deleteCount = knowledgeBaseDao.deleteById(entity.getId());
|
||||
log.info("本地数据库删除结果: {}", deleteCount > 0 ? "成功" : "失败");
|
||||
redisUtils.delete(RedisKeys.getKnowledgeBaseCacheKey(entity.getId()));
|
||||
}
|
||||
}
|
||||
|
||||
log.info("=== 通过datasetId删除操作结束 ===");
|
||||
@Override
|
||||
public List<KnowledgeBaseDTO> getByDatasetIdList(List<String> datasetIdList) {
|
||||
if (datasetIdList == null || datasetIdList.isEmpty()) {
|
||||
return Collections.emptyList();
|
||||
}
|
||||
// [Production Fix] 批量兼容性查找
|
||||
QueryWrapper<KnowledgeBaseEntity> queryWrapper = new QueryWrapper<>();
|
||||
queryWrapper.in("dataset_id", datasetIdList).or().in("id", datasetIdList);
|
||||
List<KnowledgeBaseEntity> list = knowledgeBaseDao.selectList(queryWrapper);
|
||||
return ConvertUtils.sourceToTarget(list, KnowledgeBaseDTO.class);
|
||||
}
|
||||
|
||||
@Override
|
||||
public Map<String, Object> getRAGConfig(String ragModelId) {
|
||||
if (StringUtils.isBlank(ragModelId)) {
|
||||
throw new RenException(ErrorCode.PARAMS_GET_ERROR);
|
||||
}
|
||||
|
||||
// 从缓存获取模型配置
|
||||
ModelConfigEntity modelConfig = modelConfigService.getModelByIdFromCache(ragModelId);
|
||||
if (modelConfig == null || modelConfig.getConfigJson() == null) {
|
||||
throw new RenException(ErrorCode.RAG_CONFIG_NOT_FOUND);
|
||||
}
|
||||
|
||||
// 验证是否为RAG类型配置
|
||||
if (!Constant.RAG_CONFIG_TYPE.equals(modelConfig.getModelType().toUpperCase())) {
|
||||
throw new RenException(ErrorCode.RAG_CONFIG_TYPE_ERROR);
|
||||
}
|
||||
|
||||
Map<String, Object> config = modelConfig.getConfigJson();
|
||||
|
||||
// 验证必要的配置参数
|
||||
validateRagConfig(config);
|
||||
|
||||
// 返回配置信息
|
||||
return config;
|
||||
return getValidatedRAGConfig(ragModelId);
|
||||
}
|
||||
|
||||
@Override
|
||||
public Map<String, Object> getRAGConfigByDatasetId(String datasetId) {
|
||||
if (StringUtils.isBlank(datasetId)) {
|
||||
throw new RenException(ErrorCode.RAG_DATASET_ID_NOT_NULL);
|
||||
}
|
||||
|
||||
// 根据datasetId查询知识库信息
|
||||
KnowledgeBaseDTO knowledgeBase = getByDatasetId(datasetId);
|
||||
if (knowledgeBase == null) {
|
||||
log.warn("未找到datasetId为{}的知识库", datasetId);
|
||||
throw new RenException(ErrorCode.Knowledge_Base_RECORD_NOT_EXISTS);
|
||||
}
|
||||
|
||||
// 如果知识库指定了ragModelId，使用该配置
|
||||
String ragModelId = knowledgeBase.getRagModelId();
|
||||
if (StringUtils.isBlank(ragModelId)) {
|
||||
log.warn("知识库datasetId为{}未配置ragModelId", datasetId);
|
||||
KnowledgeBaseEntity entity = knowledgeBaseDao
|
||||
.selectOne(new QueryWrapper<KnowledgeBaseEntity>().eq("dataset_id", datasetId));
|
||||
if (entity == null || StringUtils.isBlank(entity.getRagModelId())) {
|
||||
throw new RenException(ErrorCode.RAG_CONFIG_NOT_FOUND);
|
||||
}
|
||||
return getRAGConfig(entity.getRagModelId());
|
||||
}
|
||||
|
||||
// 获取并返回RAG配置
|
||||
return getRAGConfig(ragModelId);
|
||||
@Override
|
||||
@Transactional(rollbackFor = Exception.class)
|
||||
public void updateStatistics(String datasetId, Integer docDelta, Long chunkDelta, Long tokenDelta) {
|
||||
log.info("递增更新知识库统计: datasetId={}, docs={}, chunks={}, tokens={}", datasetId, docDelta, chunkDelta, tokenDelta);
|
||||
knowledgeBaseDao.updateStatsAfterChange(datasetId, docDelta, chunkDelta, tokenDelta);
|
||||
}
|
||||
|
||||
@Override
|
||||
public List<ModelConfigEntity> getRAGModels() {
|
||||
// 查询RAG类型的模型配置
|
||||
QueryWrapper<ModelConfigEntity> queryWrapper = new QueryWrapper<ModelConfigEntity>()
|
||||
.select("id", "model_name")
|
||||
return modelConfigDao.selectList(new QueryWrapper<ModelConfigEntity>()
|
||||
.select("id", "model_name", "config_json") // Explicitly select needed fields
|
||||
.eq("model_type", Constant.RAG_CONFIG_TYPE)
|
||||
.eq("is_enabled", 1)
|
||||
.orderByDesc("is_default")
|
||||
.orderByDesc("create_date");
|
||||
|
||||
List<ModelConfigEntity> modelConfigs = modelConfigDao.selectList(queryWrapper);
|
||||
return modelConfigs;
|
||||
.orderByDesc("create_date"));
|
||||
}
|
||||
|
||||
/**
|
||||
* 验证RAG配置中是否包含必要的参数
|
||||
*/
|
||||
private void validateRagConfig(Map<String, Object> config) {
|
||||
if (config == null) {
|
||||
// --- Helpers ---
|
||||
|
||||
private void checkDuplicateName(String name, String excludeId) {
|
||||
if (StringUtils.isBlank(name))
|
||||
return;
|
||||
QueryWrapper<KnowledgeBaseEntity> qw = new QueryWrapper<>();
|
||||
qw.eq("name", name).eq("creator", SecurityUser.getUserId());
|
||||
if (excludeId != null)
|
||||
qw.ne("id", excludeId);
|
||||
if (knowledgeBaseDao.selectCount(qw) > 0) {
|
||||
throw new RenException(ErrorCode.KNOWLEDGE_BASE_NAME_EXISTS);
|
||||
}
|
||||
}
|
||||
|
||||
private KnowledgeBaseAdapter getAdapterByModelId(String modelId) {
|
||||
Map<String, Object> config = getValidatedRAGConfig(modelId);
|
||||
return KnowledgeBaseAdapterFactory.getAdapter((String) config.get("type"), config);
|
||||
}
|
||||
|
||||
private Map<String, Object> getValidatedRAGConfig(String modelId) {
|
||||
ModelConfigEntity configEntity = modelConfigService.getModelByIdFromCache(modelId);
|
||||
if (configEntity == null || configEntity.getConfigJson() == null) {
|
||||
throw new RenException(ErrorCode.RAG_CONFIG_NOT_FOUND);
|
||||
}
|
||||
|
||||
// 从配置中提取必要的参数
|
||||
String baseUrl = (String) config.get("base_url");
|
||||
String apiKey = (String) config.get("api_key");
|
||||
|
||||
// 验证base_url是否存在且非空
|
||||
if (StringUtils.isBlank(baseUrl)) {
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR_URL_NULL);
|
||||
}
|
||||
|
||||
// 验证api_key是否存在且非空
|
||||
if (StringUtils.isBlank(apiKey)) {
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR_API_KEY_NULL);
|
||||
}
|
||||
|
||||
// 检查api_key是否包含占位符
|
||||
if (apiKey.contains("你")) {
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR_API_KEY_INVALID);
|
||||
}
|
||||
|
||||
// 验证base_url格式
|
||||
if (!baseUrl.startsWith("http://") && !baseUrl.startsWith("https://")) {
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR_URL_INVALID);
|
||||
Map<String, Object> config = new HashMap<>(configEntity.getConfigJson());
|
||||
if (!config.containsKey("type")) {
|
||||
config.put("type", "ragflow");
|
||||
}
|
||||
return config;
|
||||
}
|
||||
|
||||
/**
|
||||
* 从RAG配置中提取适配器类型
|
||||
*
|
||||
* @param config RAG配置
|
||||
* @return 适配器类型
|
||||
*/
|
||||
private String extractAdapterType(Map<String, Object> config) {
|
||||
if (config == null) {
|
||||
throw new RenException(ErrorCode.RAG_CONFIG_NOT_FOUND);
|
||||
}
|
||||
|
||||
// 从配置中提取适配器类型
|
||||
String adapterType = (String) config.get("type");
|
||||
|
||||
// 验证适配器类型是否存在且非空
|
||||
if (StringUtils.isBlank(adapterType)) {
|
||||
throw new RenException(ErrorCode.RAG_ADAPTER_TYPE_NOT_FOUND);
|
||||
}
|
||||
|
||||
// 验证适配器类型是否已注册
|
||||
if (!KnowledgeBaseAdapterFactory.isAdapterTypeRegistered(adapterType)) {
|
||||
throw new RenException(ErrorCode.RAG_ADAPTER_TYPE_NOT_SUPPORTED,
|
||||
"不支持的适配器类型: " + adapterType);
|
||||
}
|
||||
|
||||
return adapterType;
|
||||
}
|
||||
|
||||
/**
|
||||
* 使用适配器创建数据集
|
||||
*/
|
||||
private String createDatasetInRAG(String name, String description, Map<String, Object> ragConfig) {
|
||||
log.info("开始使用适配器创建数据集, name: {}", name);
|
||||
|
||||
try {
|
||||
// 从RAG配置中提取适配器类型
|
||||
String adapterType = extractAdapterType(ragConfig);
|
||||
|
||||
// 使用适配器工厂获取适配器实例
|
||||
KnowledgeBaseAdapter adapter = KnowledgeBaseAdapterFactory.getAdapter(adapterType, ragConfig);
|
||||
|
||||
// 构建数据集创建参数
|
||||
Map<String, Object> createParams = new HashMap<>();
|
||||
String username = SecurityUser.getUser().getUsername();
|
||||
createParams.put("name", username + "_" + name);
|
||||
if (StringUtils.isNotBlank(description)) {
|
||||
createParams.put("description", description);
|
||||
}
|
||||
|
||||
// 调用适配器的创建数据集方法
|
||||
String datasetId = adapter.createDataset(createParams);
|
||||
|
||||
log.info("数据集创建成功，datasetId: {}", datasetId);
|
||||
return datasetId;
|
||||
|
||||
} catch (Exception e) {
|
||||
// 直接传递底层适配器的详细错误信息
|
||||
log.error("创建数据集失败", e);
|
||||
if (e instanceof RenException) {
|
||||
throw (RenException) e;
|
||||
}
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, e.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 使用适配器更新数据集
|
||||
*/
|
||||
private void updateDatasetInRAG(String datasetId, String name, String description,
|
||||
Map<String, Object> ragConfig) {
|
||||
log.info("开始使用适配器更新数据集，datasetId: {}, name: {}", datasetId, name);
|
||||
|
||||
try {
|
||||
// 从RAG配置中提取适配器类型
|
||||
String adapterType = extractAdapterType(ragConfig);
|
||||
|
||||
// 使用适配器工厂获取适配器实例
|
||||
KnowledgeBaseAdapter adapter = KnowledgeBaseAdapterFactory.getAdapter(adapterType, ragConfig);
|
||||
|
||||
// 构建数据集更新参数
|
||||
Map<String, Object> updateParams = new HashMap<>();
|
||||
String username = SecurityUser.getUser().getUsername();
|
||||
updateParams.put("name", username + "_" + name);
|
||||
if (StringUtils.isNotBlank(description)) {
|
||||
updateParams.put("description", description);
|
||||
}
|
||||
|
||||
// 调用适配器的更新数据集方法
|
||||
adapter.updateDataset(datasetId, updateParams);
|
||||
|
||||
log.info("数据集更新成功，datasetId: {}", datasetId);
|
||||
|
||||
} catch (Exception e) {
|
||||
// 直接传递底层适配器的详细错误信息
|
||||
log.error("更新数据集失败", e);
|
||||
if (e instanceof RenException) {
|
||||
throw (RenException) e;
|
||||
}
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, e.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 使用适配器删除数据集
|
||||
*/
|
||||
private void deleteDatasetInRAG(String datasetId, Map<String, Object> ragConfig) {
|
||||
log.info("开始使用适配器删除数据集，datasetId: {}", datasetId);
|
||||
|
||||
try {
|
||||
// 从RAG配置中提取适配器类型
|
||||
String adapterType = extractAdapterType(ragConfig);
|
||||
|
||||
// 使用适配器工厂获取适配器实例
|
||||
KnowledgeBaseAdapter adapter = KnowledgeBaseAdapterFactory.getAdapter(adapterType, ragConfig);
|
||||
|
||||
// 调用适配器的删除数据集方法
|
||||
adapter.deleteDataset(datasetId);
|
||||
|
||||
log.info("数据集删除成功，datasetId: {}", datasetId);
|
||||
|
||||
} catch (Exception e) {
|
||||
// 直接传递底层适配器的详细错误信息
|
||||
log.error("删除数据集失败", e);
|
||||
if (e instanceof RenException) {
|
||||
throw (RenException) e;
|
||||
}
|
||||
throw new RenException(ErrorCode.RAG_API_ERROR, e.getMessage());
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 获取RAG配置并验证
|
||||
*/
|
||||
private Map<String, Object> getValidatedRAGConfig(String ragModelId) {
|
||||
if (StringUtils.isBlank(ragModelId)) {
|
||||
throw new RenException(ErrorCode.RAG_MODEL_ID_NOT_NULL);
|
||||
}
|
||||
|
||||
Map<String, Object> ragConfig = getRAGConfig(ragModelId);
|
||||
|
||||
// 验证RAG配置参数
|
||||
validateRagConfig(ragConfig);
|
||||
|
||||
return ragConfig;
|
||||
}
|
||||
|
||||
/**
|
||||
* 检查是否存在同名知识库
|
||||
*
|
||||
* @param knowledgeBaseDTO 知识库DTO
|
||||
* @param excludeId 排除的ID（更新时使用）
|
||||
*/
|
||||
private void checkDuplicateKnowledgeBaseName(KnowledgeBaseDTO knowledgeBaseDTO, String excludeId) {
|
||||
if (StringUtils.isNotBlank(knowledgeBaseDTO.getName())) {
|
||||
Long currentUserId = SecurityUser.getUserId();
|
||||
QueryWrapper<KnowledgeBaseEntity> queryWrapper = new QueryWrapper<KnowledgeBaseEntity>()
|
||||
.eq("name", knowledgeBaseDTO.getName())
|
||||
.eq("creator", currentUserId);
|
||||
|
||||
// 如果提供了排除ID，则排除该记录
|
||||
if (StringUtils.isNotBlank(excludeId)) {
|
||||
queryWrapper.ne("id", excludeId);
|
||||
}
|
||||
|
||||
long count = knowledgeBaseDao.selectCount(queryWrapper);
|
||||
if (count > 0) {
|
||||
throw new RenException(ErrorCode.KNOWLEDGE_BASE_NAME_EXISTS,
|
||||
MessageUtils.getMessage(ErrorCode.KNOWLEDGE_BASE_NAME_EXISTS));
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* 从适配器获取知识库的文档数量
|
||||
*/
|
||||
private Integer getDocumentCountFromRAG(String datasetId, String ragModelId) {
|
||||
if (StringUtils.isBlank(datasetId) || StringUtils.isBlank(ragModelId)) {
|
||||
log.warn("datasetId或ragModelId为空，无法获取文档数量");
|
||||
return 0;
|
||||
}
|
||||
|
||||
log.info("开始获取知识库 {} 的文档数量", datasetId);
|
||||
|
||||
try {
|
||||
// 获取RAG配置
|
||||
Map<String, Object> ragConfig = getValidatedRAGConfig(ragModelId);
|
||||
|
||||
// 从RAG配置中提取适配器类型
|
||||
String adapterType = extractAdapterType(ragConfig);
|
||||
|
||||
// 使用适配器工厂获取适配器实例
|
||||
KnowledgeBaseAdapter adapter = KnowledgeBaseAdapterFactory.getAdapter(adapterType, ragConfig);
|
||||
|
||||
// 调用适配器的获取文档数量方法
|
||||
Integer documentCount = adapter.getDocumentCount(datasetId);
|
||||
|
||||
log.info("获取知识库 {} 的文档数量成功: {}", datasetId, documentCount);
|
||||
return documentCount;
|
||||
|
||||
} catch (Exception e) {
|
||||
// 构建详细的错误信息，包含异常类型和消息
|
||||
String baseErrorMessage = e.getClass().getSimpleName() + " - 获取知识库文档数量失败";
|
||||
String errorMessage = baseErrorMessage + (e.getMessage() != null ? ": " + e.getMessage() : "");
|
||||
log.error(errorMessage, e);
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
}
|
||||
+522
-1023
File diff suppressed because it is too large
Load Diff
+47
@@ -0,0 +1,47 @@
|
||||
package xiaozhi.modules.knowledge.service.impl;
|
||||
|
||||
import lombok.RequiredArgsConstructor;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import org.springframework.stereotype.Service;
|
||||
import org.springframework.transaction.annotation.Transactional;
|
||||
import xiaozhi.modules.knowledge.service.KnowledgeBaseService;
|
||||
import xiaozhi.modules.knowledge.service.KnowledgeFilesService;
|
||||
import xiaozhi.modules.knowledge.service.KnowledgeManagerService;
|
||||
|
||||
import java.util.List;
|
||||
|
||||
@Service
|
||||
@Slf4j
|
||||
@RequiredArgsConstructor
|
||||
public class KnowledgeManagerServiceImpl implements KnowledgeManagerService {
|
||||
|
||||
private final KnowledgeBaseService knowledgeBaseService;
|
||||
private final KnowledgeFilesService knowledgeFilesService;
|
||||
|
||||
@Override
|
||||
@Transactional(rollbackFor = Exception.class)
|
||||
public void deleteDatasetWithFiles(String datasetId) {
|
||||
log.info("=== 级联删除开始: datasetId={} ===", datasetId);
|
||||
|
||||
// 1. 先调用文件服务，清理该数据集下的所有文档记录 (含 RAGFlow 端)
|
||||
log.info("Step 1: 清理关联文档...");
|
||||
knowledgeFilesService.deleteDocumentsByDatasetId(datasetId);
|
||||
|
||||
// 2. 再调用知识库服务，彻底注销数据集 (含 RAGFlow 端)
|
||||
log.info("Step 2: 删除数据集主体...");
|
||||
knowledgeBaseService.deleteByDatasetId(datasetId);
|
||||
|
||||
log.info("=== 级联删除成功: datasetId={} ===", datasetId);
|
||||
}
|
||||
|
||||
@Override
|
||||
@Transactional(rollbackFor = Exception.class)
|
||||
public void batchDeleteDatasetsWithFiles(List<String> datasetIds) {
|
||||
if (datasetIds == null || datasetIds.isEmpty())
|
||||
return;
|
||||
log.info("=== 批量级联删除开始: count={} ===", datasetIds.size());
|
||||
for (String id : datasetIds) {
|
||||
deleteDatasetWithFiles(id);
|
||||
}
|
||||
}
|
||||
}
|
||||
+39
@@ -0,0 +1,39 @@
|
||||
package xiaozhi.modules.knowledge.task;
|
||||
|
||||
import org.springframework.scheduling.annotation.Scheduled;
|
||||
import org.springframework.stereotype.Component;
|
||||
|
||||
import lombok.AllArgsConstructor;
|
||||
import lombok.extern.slf4j.Slf4j;
|
||||
import xiaozhi.modules.knowledge.service.KnowledgeFilesService;
|
||||
|
||||
/**
|
||||
* 知识库文档状态同步定时任务
|
||||
*
|
||||
* 作用：
|
||||
* 1. 自动扫描处于 "RUNNING" (解析中) 状态的文档
|
||||
* 2. 调用 RAGFlow 接口获取最新状态
|
||||
* 3. 状态翻转 (RUNNING -> SUCCESS/FAIL) 时，同步更新数据库
|
||||
* 4. [关键] 解析成功时，补偿更新知识库的统计信息 (TokenCount)
|
||||
*/
|
||||
@Component
|
||||
@AllArgsConstructor
|
||||
@Slf4j
|
||||
public class DocumentStatusSyncTask {
|
||||
|
||||
private final KnowledgeFilesService knowledgeFilesService;
|
||||
|
||||
/**
|
||||
* 每 30 秒执行一次同步
|
||||
* 采用 fixedDelay，确保上一次执行完 30 秒后才开始下一次，防止积压
|
||||
*/
|
||||
@Scheduled(fixedDelay = 30000)
|
||||
public void syncRunningDocuments() {
|
||||
try {
|
||||
// log.debug("开始执行文档状态同步任务...");
|
||||
knowledgeFilesService.syncRunningDocuments();
|
||||
} catch (Exception e) {
|
||||
log.error("文档状态同步任务异常", e);
|
||||
}
|
||||
}
|
||||
}
|
||||
+5
-5
@@ -56,7 +56,7 @@ public class SysUserServiceImpl extends BaseServiceImpl<SysUserDao, SysUserEntit
|
||||
if (users == null || users.isEmpty()) {
|
||||
return null;
|
||||
}
|
||||
SysUserEntity entity = users.getFirst();
|
||||
SysUserEntity entity = users.get(0);
|
||||
return ConvertUtils.sourceToTarget(entity, SysUserDTO.class);
|
||||
}
|
||||
|
||||
@@ -197,7 +197,7 @@ public class SysUserServiceImpl extends BaseServiceImpl<SysUserDao, SysUserEntit
|
||||
*/
|
||||
private String generatePassword() {
|
||||
StringBuilder password = new StringBuilder();
|
||||
|
||||
|
||||
// 确保包含至少一个数字
|
||||
password.append("0123456789".charAt(random.nextInt(10)));
|
||||
// 确保包含至少一个小写字母
|
||||
@@ -206,12 +206,12 @@ public class SysUserServiceImpl extends BaseServiceImpl<SysUserDao, SysUserEntit
|
||||
password.append("ABCDEFGHIJKLMNOPQRSTUVWXYZ".charAt(random.nextInt(26)));
|
||||
// 确保包含至少一个特殊符号
|
||||
password.append("!@#$%^&*()".charAt(random.nextInt(10)));
|
||||
|
||||
|
||||
// 生成剩余的8个字符
|
||||
for (int i = 4; i < 12; i++) {
|
||||
password.append(CHARACTERS.charAt(random.nextInt(CHARACTERS.length())));
|
||||
}
|
||||
|
||||
|
||||
// 打乱密码中字符的顺序
|
||||
char[] passwordChars = password.toString().toCharArray();
|
||||
for (int i = 0; i < passwordChars.length; i++) {
|
||||
@@ -220,7 +220,7 @@ public class SysUserServiceImpl extends BaseServiceImpl<SysUserDao, SysUserEntit
|
||||
passwordChars[i] = passwordChars[randomIndex];
|
||||
passwordChars[randomIndex] = temp;
|
||||
}
|
||||
|
||||
|
||||
return new String(passwordChars);
|
||||
}
|
||||
|
||||
|
||||
@@ -17,4 +17,7 @@ public class VoiceCloneDTO {
|
||||
|
||||
@Schema(description = "用户ID")
|
||||
private Long userId;
|
||||
|
||||
@Schema(description = "语言")
|
||||
private String languages;
|
||||
}
|
||||
|
||||
+3
@@ -28,6 +28,9 @@ public class VoiceCloneResponseDTO {
|
||||
@Schema(description = "声音id")
|
||||
private String voiceId;
|
||||
|
||||
@Schema(description = "语言")
|
||||
private String languages;
|
||||
|
||||
@Schema(description = "用户ID（关联用户表）")
|
||||
private Long userId;
|
||||
|
||||
|
||||
@@ -31,6 +31,9 @@ public class VoiceCloneEntity {
|
||||
@Schema(description = "声音id")
|
||||
private String voiceId;
|
||||
|
||||
@Schema(description = "语言")
|
||||
private String languages;
|
||||
|
||||
@Schema(description = "用户 ID（关联用户表）")
|
||||
private Long userId;
|
||||
|
||||
|
||||
+1
@@ -116,6 +116,7 @@ public class VoiceCloneServiceImpl extends BaseServiceImpl<VoiceCloneDao, VoiceC
|
||||
entity.setVoiceId(voiceId);
|
||||
entity.setName(namePrefix + "_" + index);
|
||||
entity.setUserId(dto.getUserId());
|
||||
entity.setLanguages(dto.getLanguages());
|
||||
entity.setTrainStatus(0); // 默认训练中
|
||||
batchInsertList.add(entity);
|
||||
}
|
||||
|
||||
@@ -0,0 +1,4 @@
|
||||
-- 给声音克隆表添加语言字段
|
||||
SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'ai_voice_clone' AND COLUMN_NAME = 'languages');
|
||||
SET @sql = IF(@col_exists = 0, 'ALTER TABLE `ai_voice_clone` ADD COLUMN `languages` VARCHAR(50) DEFAULT NULL COMMENT ''语言'' AFTER `voice_id`', 'SELECT ''Column languages already exists'' AS msg');
|
||||
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
|
||||
@@ -0,0 +1,69 @@
|
||||
-- 增加一下ragflow返回的参数（创建/查询知识库时返回）
|
||||
SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'ai_rag_dataset' AND COLUMN_NAME = 'tenant_id');
|
||||
SET @sql = IF(@col_exists = 0, 'ALTER TABLE `ai_rag_dataset` ADD COLUMN `tenant_id` varchar(32) DEFAULT NULL COMMENT ''租户ID''', 'SELECT ''Column tenant_id already exists'' AS msg');
|
||||
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
|
||||
|
||||
SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'ai_rag_dataset' AND COLUMN_NAME = 'avatar');
|
||||
SET @sql = IF(@col_exists = 0, 'ALTER TABLE `ai_rag_dataset` ADD COLUMN `avatar` text DEFAULT NULL COMMENT ''知识库头像 (Base64)''', 'SELECT ''Column avatar already exists'' AS msg');
|
||||
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
|
||||
|
||||
SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'ai_rag_dataset' AND COLUMN_NAME = 'embedding_model');
|
||||
SET @sql = IF(@col_exists = 0, 'ALTER TABLE `ai_rag_dataset` ADD COLUMN `embedding_model` varchar(50) DEFAULT NULL COMMENT ''嵌入模型名称''', 'SELECT ''Column embedding_model already exists'' AS msg');
|
||||
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
|
||||
|
||||
SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'ai_rag_dataset' AND COLUMN_NAME = 'permission');
|
||||
SET @sql = IF(@col_exists = 0, 'ALTER TABLE `ai_rag_dataset` ADD COLUMN `permission` varchar(20) DEFAULT ''me'' COMMENT ''权限设置：me/team''', 'SELECT ''Column permission already exists'' AS msg');
|
||||
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
|
||||
|
||||
SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'ai_rag_dataset' AND COLUMN_NAME = 'chunk_method');
|
||||
SET @sql = IF(@col_exists = 0, 'ALTER TABLE `ai_rag_dataset` ADD COLUMN `chunk_method` varchar(50) DEFAULT NULL COMMENT ''分块方法''', 'SELECT ''Column chunk_method already exists'' AS msg');
|
||||
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
|
||||
|
||||
SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'ai_rag_dataset' AND COLUMN_NAME = 'parser_config');
|
||||
SET @sql = IF(@col_exists = 0, 'ALTER TABLE `ai_rag_dataset` ADD COLUMN `parser_config` text DEFAULT NULL COMMENT ''解析器配置 (JSON)''', 'SELECT ''Column parser_config already exists'' AS msg');
|
||||
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
|
||||
|
||||
SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'ai_rag_dataset' AND COLUMN_NAME = 'chunk_count');
|
||||
SET @sql = IF(@col_exists = 0, 'ALTER TABLE `ai_rag_dataset` ADD COLUMN `chunk_count` bigint(20) DEFAULT 0 COMMENT ''分块总数''', 'SELECT ''Column chunk_count already exists'' AS msg');
|
||||
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
|
||||
|
||||
SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'ai_rag_dataset' AND COLUMN_NAME = 'document_count');
|
||||
SET @sql = IF(@col_exists = 0, 'ALTER TABLE `ai_rag_dataset` ADD COLUMN `document_count` bigint(20) DEFAULT 0 COMMENT ''文档总数''', 'SELECT ''Column document_count already exists'' AS msg');
|
||||
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
|
||||
|
||||
SET @col_exists = (SELECT COUNT(*) FROM INFORMATION_SCHEMA.COLUMNS WHERE TABLE_SCHEMA = DATABASE() AND TABLE_NAME = 'ai_rag_dataset' AND COLUMN_NAME = 'token_num');
|
||||
SET @sql = IF(@col_exists = 0, 'ALTER TABLE `ai_rag_dataset` ADD COLUMN `token_num` bigint(20) DEFAULT 0 COMMENT ''总 Token 数''', 'SELECT ''Column token_num already exists'' AS msg');
|
||||
PREPARE stmt FROM @sql; EXECUTE stmt; DEALLOCATE PREPARE stmt;
|
||||
|
||||
-- 文档表 (Shadow DB for RAGFlow)
|
||||
-- 留存一份文档id，把ragflow远端文档id和本地id关联起来（只是备份一份元信息链接，实际上文件内容的存储还是在ragflow）
|
||||
DROP TABLE IF EXISTS `ai_rag_knowledge_document`;
|
||||
CREATE TABLE `ai_rag_knowledge_document` (
|
||||
`id` varchar(36) NOT NULL COMMENT '本地唯一ID',
|
||||
`dataset_id` varchar(36) NOT NULL COMMENT '知识库ID (关联 ai_rag_dataset)',
|
||||
`document_id` varchar(64) NOT NULL COMMENT 'RAGFlow文档ID (远程ID)',
|
||||
`name` varchar(255) DEFAULT NULL COMMENT '文档名称',
|
||||
`size` bigint(20) DEFAULT NULL COMMENT '文件大小(Bytes)',
|
||||
`type` varchar(20) DEFAULT NULL COMMENT '文件类型',
|
||||
`chunk_method` varchar(50) DEFAULT NULL COMMENT '分块方法',
|
||||
`parser_config` text COMMENT '解析配置(JSON)',
|
||||
`status` varchar(10) DEFAULT '1' COMMENT '可用状态 (1:启用 0:禁用)',
|
||||
`run` varchar(32) DEFAULT 'UNSTART' COMMENT '运行状态 (UNSTART/RUNNING/CANCEL/DONE/FAIL)',
|
||||
`progress` double DEFAULT '0' COMMENT '解析进度 (0.0 ~ 1.0)',
|
||||
`thumbnail` mediumtext COMMENT '缩略图 (Base64 或 URL)',
|
||||
`process_duration` double DEFAULT '0' COMMENT '解析耗时 (单位: 秒)',
|
||||
`meta_fields` text COMMENT '自定义元数据 (JSON)',
|
||||
`source_type` varchar(32) DEFAULT 'local' COMMENT '来源类型 (local, s3, url 等)',
|
||||
`error` text COMMENT '错误信息',
|
||||
`chunk_count` int(11) DEFAULT '0' COMMENT '分块数量',
|
||||
`token_count` bigint(20) DEFAULT '0' COMMENT 'Token数量',
|
||||
`enabled` tinyint(1) DEFAULT '1' COMMENT '启用状态',
|
||||
`creator` bigint(20) DEFAULT NULL COMMENT '创建者',
|
||||
`created_at` datetime DEFAULT NULL COMMENT '创建时间',
|
||||
`updated_at` datetime DEFAULT NULL COMMENT '更新时间',
|
||||
`last_sync_at` datetime DEFAULT NULL COMMENT '最后同步时间',
|
||||
PRIMARY KEY (`id`),
|
||||
UNIQUE KEY `uk_doc_id` (`document_id`),
|
||||
KEY `idx_dataset_id` (`dataset_id`),
|
||||
KEY `idx_status` (`status`)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='知识库文档表';
|
||||
@@ -557,4 +557,17 @@ databaseChangeLog:
|
||||
- sqlFile:
|
||||
encoding: utf8
|
||||
path: classpath:db/changelog/202603091051.sql
|
||||
|
||||
- changeSet:
|
||||
id: 202603101723
|
||||
author: RanChen
|
||||
changes:
|
||||
- sqlFile:
|
||||
encoding: utf8
|
||||
path: classpath:db/changelog/202603101723.sql
|
||||
- changeSet:
|
||||
id: 202603111131
|
||||
author: DaGou12138
|
||||
changes:
|
||||
- sqlFile:
|
||||
encoding: utf8
|
||||
path: classpath:db/changelog/202603111131.sql
|
||||
|
||||
@@ -204,4 +204,6 @@
|
||||
10195=OTA\u4E0A\u4F20\u6B21\u6570\u8D85\u8FC7\u9650\u5236
|
||||
10196=\u6807\u7B7E\u540D\u79F0\u5DF2\u5B58\u5728
|
||||
10197=\u6807\u7B7E\u540D\u79F0\u4E0D\u80FD\u4E3A\u7A7A
|
||||
10198=\u6807\u7B7E\u4E0D\u5B58\u5728
|
||||
10198=\u6807\u7B7E\u4E0D\u5B58\u5728
|
||||
10199=\u89E3\u6790\u4E2D\u6587\u4EF6\u6682\u4E0D\u652F\u6301\u6B64\u64CD\u4F5C
|
||||
|
||||
|
||||
@@ -204,4 +204,6 @@
|
||||
10195=OTA-Upload-Anzahl \u00FCberschreitet das Limit
|
||||
10196=Tag-Name existiert bereits
|
||||
10197=Tag-Name darf nicht leer sein
|
||||
10198=Tag nicht gefunden
|
||||
10198=Tag nicht gefunden
|
||||
10199=Dateianalyse l\u00E4uft, dieser Vorgang wird nicht unterst\u00FCtzt
|
||||
|
||||
|
||||
@@ -204,4 +204,6 @@
|
||||
10195=OTA upload times exceed the limit
|
||||
10196=Tag name already exists
|
||||
10197=Tag name cannot be empty
|
||||
10198=Tag not found
|
||||
10198=Tag not found
|
||||
10199=Parsing in progress, this operation is not supported
|
||||
|
||||
|
||||
@@ -202,6 +202,8 @@
|
||||
10193=ID thi\u1EBFt b\u1ECB kh\u00F4ng th\u1EC3 tr\u1ED1ng
|
||||
10194=Kh\u00F4ng t\u00ECm th\u1EA5y thi\u1EBFt b\u1ECB ho\u1EB7c thi\u1EBFt b\u1ECB kh\u00F4ng tr\u1EF1c tuy\u1EBFn
|
||||
10195=S\u1ED1 l\u1EA7n t\u1EA3i l\u00EAn OTA v\u01B0\u1EE3t qu\u00E1 gi\u1EDBi h\u1EA1n
|
||||
10196=T\u00EAn th\u1EB9� \u0111\u00E3 t\u1ED3n t\u1EA1i
|
||||
10197=T\u00EAn th\u1EB9� kh\u00F4ng th\u1EC3 \u0111\u1EC3 tr\u1ED1ng
|
||||
10198=Kh\u00F4ng t\u00ECm th\u1EA5y th\u1EB9�
|
||||
10196=T\u00EAn th\u1EB9\uFFFD \u0111\u00E3 t\u1ED3n t\u1EA1i
|
||||
10197=T\u00EAn th\u1EB9\uFFFD kh\u00F4ng th\u1EC3 \u0111\u1EC3 tr\u1ED1ng
|
||||
10198=Kh\u00F4ng t\u00ECm th\u1EA5y th\u1EB9\uFFFD
|
||||
10199=T\u1EC7p \u0111ang \u0111\u01B0\u1EE3c ph\u00E2n t\u00EDch, thao t\u00E1c n\u00E0y kh\u00F4ng \u0111\u01B0\u1EE3c h\u1ED7 tr\u1EE3
|
||||
|
||||
|
||||
@@ -201,4 +201,5 @@
|
||||
10192=\u9002\u914D\u5668\u7C7B\u578B\u672A\u627E\u5230
|
||||
10193=\u8BBE\u5907ID\u4E0D\u80FD\u4E3A\u7A7A
|
||||
10194=\u8BBE\u5907\u4E0D\u5B58\u5728\u6216\u4E0D\u5728\u7EBF
|
||||
10195=OTA\u4E0A\u4F20\u6B21\u6570\u8D85\u8FC7\u9650\u5236
|
||||
10195=OTA\u4E0A\u4F20\u6B21\u6570\u8D85\u8FC7\u9650\u5236
|
||||
10196=\u89E3\u6790\u4E2D\u6587\u4EF6\u6682\u4E0D\u652F\u6301\u6B64\u64CD\u4F5C
|
||||
|
||||
@@ -204,4 +204,6 @@
|
||||
10195=OTA\u4E0A\u4F20\u6B21\u6578\u8D85\u904E\u9650\u5236
|
||||
10196=\u6A19\u7C64\u540D\u7A31\u5DF2\u5B58\u5728
|
||||
10197=\u6A19\u7C64\u540D\u7A31\u4E0D\u80FD\u4E3A\u7A7A
|
||||
10198=\u6A19\u7C64\u4E0D\u5B58\u5728
|
||||
10198=\u6A19\u7C64\u4E0D\u5B58\u5728
|
||||
10199=\u89E3\u6790\u4E2D\u6587\u4EF6\u66AB\u4E0D\u652F\u6301\u6B64\u64CD\u4F5C
|
||||
|
||||
|
||||
@@ -23,4 +23,14 @@
|
||||
WHERE plugin_id = #{knowledgeBaseId}
|
||||
</delete>
|
||||
|
||||
<!-- 通用维度原子更新知识库统计信息 -->
|
||||
<update id="updateStatsAfterChange">
|
||||
UPDATE ai_rag_dataset
|
||||
SET document_count = document_count + #{docDelta},
|
||||
chunk_count = chunk_count + #{chunkDelta},
|
||||
token_num = token_num + #{tokenDelta},
|
||||
updated_at = NOW()
|
||||
WHERE dataset_id = #{datasetId}
|
||||
</update>
|
||||
|
||||
</mapper>
|
||||
@@ -3,7 +3,7 @@
|
||||
|
||||
<mapper namespace="xiaozhi.modules.voiceclone.dao.VoiceCloneDao">
|
||||
<select id="getTrainSuccess" resultType="xiaozhi.modules.model.dto.VoiceDTO">
|
||||
select id, name, voice_id as voiceDemo
|
||||
select id, name, voice_id as voiceDemo, languages
|
||||
from ai_voice_clone
|
||||
where model_id = #{modelId} and user_id = #{userId} and train_status = 2
|
||||
</select>
|
||||
|
||||
@@ -25,6 +25,11 @@
|
||||
</el-option>
|
||||
</el-select>
|
||||
</el-form-item>
|
||||
|
||||
<el-form-item :label="$t('voiceClone.languages')" prop="languages">
|
||||
<el-input v-model="form.languages" :placeholder="$t('voiceClone.languagesPlaceholder')" style="width: 100%">
|
||||
</el-input>
|
||||
</el-form-item>
|
||||
</el-form>
|
||||
|
||||
<div slot="footer" class="dialog-footer">
|
||||
@@ -70,6 +75,9 @@ export default {
|
||||
],
|
||||
userId: [
|
||||
{ required: true, message: this.$t('voiceClone.userIdRequired'), trigger: 'change' }
|
||||
],
|
||||
languages: [
|
||||
{ required: true, message: this.$t('voiceClone.languagesRequired'), trigger: 'blur' }
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
@@ -1132,6 +1132,9 @@ export default {
|
||||
'voiceClone.platformNamePlaceholder': 'Bitte Plattformname auswählen',
|
||||
'voiceClone.voiceIdPlaceholder': 'Bitte Stimmen-ID eingeben und Enter drücken',
|
||||
'voiceClone.userIdPlaceholder': 'Bitte Schlüsselwort eingeben, um Kontoinhaber auszuwählen',
|
||||
'voiceClone.languages': 'Sprachen',
|
||||
'voiceClone.languagesPlaceholder': 'Bitte Sprachen eingeben, z.B.: Deutsch, English',
|
||||
'voiceClone.languagesRequired': 'Bitte Sprachen eingeben',
|
||||
'voiceClone.waitingUpload': 'Wartet auf Upload',
|
||||
'voiceClone.waitingTraining': 'Wartet auf Klon',
|
||||
'voiceClone.training': 'Training',
|
||||
|
||||
@@ -1132,6 +1132,9 @@ export default {
|
||||
'voiceClone.platformNamePlaceholder': 'Please select platform name',
|
||||
'voiceClone.voiceIdPlaceholder': 'Please enter voice ID and press Enter',
|
||||
'voiceClone.userIdPlaceholder': 'Please enter keyword to select account owner',
|
||||
'voiceClone.languages': 'Languages',
|
||||
'voiceClone.languagesPlaceholder': 'Please enter languages, e.g.: Chinese, English',
|
||||
'voiceClone.languagesRequired': 'Please enter languages',
|
||||
'voiceClone.waitingUpload': 'Waiting for upload',
|
||||
'voiceClone.waitingTraining': 'Waiting for clone',
|
||||
'voiceClone.training': 'Training',
|
||||
|
||||
@@ -1132,6 +1132,9 @@ export default {
|
||||
'voiceClone.platformNamePlaceholder': 'Por favor, selecione o nome da plataforma',
|
||||
'voiceClone.voiceIdPlaceholder': 'Por favor, insira o ID da voz e pressione Enter',
|
||||
'voiceClone.userIdPlaceholder': 'Por favor, insira palavra-chave para selecionar o proprietário da conta',
|
||||
'voiceClone.languages': 'Idiomas',
|
||||
'voiceClone.languagesPlaceholder': 'Por favor, insira idiomas, ex.: Português, English',
|
||||
'voiceClone.languagesRequired': 'Por favor, insira idiomas',
|
||||
'voiceClone.waitingUpload': 'Aguardando envio',
|
||||
'voiceClone.waitingTraining': 'Aguardando clonagem',
|
||||
'voiceClone.training': 'Treinando',
|
||||
|
||||
@@ -1132,6 +1132,9 @@ export default {
|
||||
'voiceClone.platformNamePlaceholder': 'Vui lòng chọn tên nền tảng',
|
||||
'voiceClone.voiceIdPlaceholder': 'Vui lòng nhập ID giọng nói và nhấn Enter',
|
||||
'voiceClone.userIdPlaceholder': 'Vui lòng nhập từ khóa để chọn chủ sở hữu tài khoản',
|
||||
'voiceClone.languages': 'Ngôn ngữ',
|
||||
'voiceClone.languagesPlaceholder': 'Vui lòng nhập ngôn ngữ, ví dụ: Tiếng Việt, English',
|
||||
'voiceClone.languagesRequired': 'Vui lòng nhập ngôn ngữ',
|
||||
'voiceClone.waitingUpload': 'Đang chờ tải lên',
|
||||
'voiceClone.waitingTraining': 'Đang chờ nhân bản',
|
||||
'voiceClone.training': 'Đang huấn luyện',
|
||||
|
||||
@@ -189,7 +189,7 @@ export default {
|
||||
'editVoiceDialog.remarkPlaceholder': '请输入备注内容',
|
||||
'editVoiceDialog.generatePreview': '生成试听',
|
||||
'editVoiceDialog.defaultVoiceName': '湾湾小何',
|
||||
'editVoiceDialog.defaultLanguageType': '中文',
|
||||
'editVoiceDialog.defaultLanguageType': '普通话',
|
||||
'editVoiceDialog.requiredVoiceCode': '请输入音色编码',
|
||||
'editVoiceDialog.requiredVoiceName': '请输入音色名称',
|
||||
|
||||
@@ -1132,6 +1132,9 @@ export default {
|
||||
'voiceClone.platformNamePlaceholder': '请选择平台名称',
|
||||
'voiceClone.voiceIdPlaceholder': '请输入音色ID并按回车',
|
||||
'voiceClone.userIdPlaceholder': '请输入关键词选择归属账号',
|
||||
'voiceClone.languages': '语言',
|
||||
'voiceClone.languagesPlaceholder': '请输入语言，如：中文、English',
|
||||
'voiceClone.languagesRequired': '请输入语言',
|
||||
'voiceClone.waitingUpload': '待上传',
|
||||
'voiceClone.waitingTraining': '待复刻',
|
||||
'voiceClone.training': '训练中',
|
||||
|
||||
@@ -189,7 +189,7 @@ export default {
|
||||
'editVoiceDialog.remarkPlaceholder': '請輸入備註內容',
|
||||
'editVoiceDialog.generatePreview': '生成試聽',
|
||||
'editVoiceDialog.defaultVoiceName': '灣灣小何',
|
||||
'editVoiceDialog.defaultLanguageType': '中文',
|
||||
'editVoiceDialog.defaultLanguageType': '普通話',
|
||||
'editVoiceDialog.requiredVoiceCode': '請輸入音色編碼',
|
||||
'editVoiceDialog.requiredVoiceName': '請輸入音色名稱',
|
||||
|
||||
@@ -1132,6 +1132,9 @@ export default {
|
||||
'voiceClone.platformNamePlaceholder': '請選擇平台名稱',
|
||||
'voiceClone.voiceIdPlaceholder': '請輸入音色ID並按回车',
|
||||
'voiceClone.userIdPlaceholder': '請輸入关键词選擇歸屬帳號',
|
||||
'voiceClone.languages': '語言',
|
||||
'voiceClone.languagesPlaceholder': '請輸入語言，如：中文、English',
|
||||
'voiceClone.languagesRequired': '請輸入語言',
|
||||
'voiceClone.waitingUpload': '待上傳',
|
||||
'voiceClone.waitingTraining': '待複刻',
|
||||
'voiceClone.training': '訓練中',
|
||||
|
||||
@@ -34,6 +34,8 @@
|
||||
</span>
|
||||
</template>
|
||||
</el-table-column>
|
||||
<el-table-column :label="$t('voiceClone.languages')" prop="languages"
|
||||
align="center"></el-table-column>
|
||||
<el-table-column :label="$t('voiceClone.trainStatus')" prop="trainStatus" align="center">
|
||||
<template slot-scope="scope">
|
||||
<div class="status-button" :class="getStatusButtonClass(scope.row)">
|
||||
|
||||
@@ -32,6 +32,8 @@
|
||||
align="center"></el-table-column>
|
||||
<el-table-column :label="$t('voiceClone.platformName')" prop="modelName"
|
||||
align="center"></el-table-column>
|
||||
<el-table-column :label="$t('voiceClone.languages')" prop="languages"
|
||||
align="center"></el-table-column>
|
||||
<el-table-column :label="$t('voiceClone.trainStatus')" prop="trainStatus" align="center">
|
||||
<template slot-scope="scope">
|
||||
{{ getTrainStatusText(scope.row) }}
|
||||
@@ -122,7 +124,8 @@ export default {
|
||||
voiceCloneForm: {
|
||||
modelId: "",
|
||||
voiceIds: [],
|
||||
userId: null
|
||||
userId: null,
|
||||
languages: ""
|
||||
}
|
||||
};
|
||||
},
|
||||
@@ -198,7 +201,8 @@ export default {
|
||||
this.voiceCloneForm = {
|
||||
modelId: "",
|
||||
voiceIds: [],
|
||||
userId: null
|
||||
userId: null,
|
||||
languages: ""
|
||||
};
|
||||
this.$nextTick(() => {
|
||||
if (this.$refs.voiceCloneForm) {
|
||||
|
||||
@@ -753,7 +753,10 @@ export default {
|
||||
|
||||
// 根据选中的语言筛选音色
|
||||
const filteredVoices = allVoices.filter(voice => {
|
||||
if (!voice.languages) return false;
|
||||
if (!voice.languages) {
|
||||
// 对于没有语言信息的克隆音色，始终显示
|
||||
return Boolean(voice.isClone);
|
||||
}
|
||||
const languagesArray = voice.languages.split(/[、；;,，]/).map(lang => lang.trim()).filter(lang => lang);
|
||||
return languagesArray.includes(this.selectedLanguage);
|
||||
});
|
||||
|
||||
@@ -21,7 +21,6 @@ async def sendAudioMessage(conn: "ConnectionHandler", sentenceType, audios, text
|
||||
if conn.tts.tts_audio_first_sentence:
|
||||
conn.logger.bind(tag=TAG).info(f"发送第一段语音: {text}")
|
||||
conn.tts.tts_audio_first_sentence = False
|
||||
await send_tts_message(conn, "start", None)
|
||||
|
||||
if sentenceType == SentenceType.FIRST:
|
||||
# 同一句子的后续消息加入流控队列，其他情况立即发送
|
||||
@@ -204,7 +203,6 @@ def _start_background_sender(conn: "ConnectionHandler", rate_controller, flow_co
|
||||
|
||||
conn.last_activity_time = time.time() * 1000
|
||||
await _do_send_audio(conn, packet, flow_control)
|
||||
conn.client_is_speaking = True
|
||||
|
||||
# 使用 start_sending 启动后台循环
|
||||
rate_controller.start_sending(send_callback)
|
||||
@@ -232,12 +230,10 @@ async def _send_audio_with_rate_control(
|
||||
# 预缓冲：前N个包直接发送
|
||||
if flow_control["packet_count"] < PRE_BUFFER_COUNT:
|
||||
await _do_send_audio(conn, packet, flow_control)
|
||||
conn.client_is_speaking = True
|
||||
elif send_delay > 0:
|
||||
# 固定延迟模式
|
||||
await asyncio.sleep(send_delay)
|
||||
await _do_send_audio(conn, packet, flow_control)
|
||||
conn.client_is_speaking = True
|
||||
else:
|
||||
# 动态流控模式：仅添加到队列，由后台循环负责发送
|
||||
rate_controller.add_audio(packet)
|
||||
@@ -318,3 +314,5 @@ async def send_stt_message(conn: "ConnectionHandler", text):
|
||||
json.dumps({"type": "stt", "text": stt_text, "session_id": conn.session_id})
|
||||
)
|
||||
await send_tts_message(conn, "start")
|
||||
# 发送start消息后客户端状态会处于说话中状态，同步服务端状态
|
||||
conn.client_is_speaking = True
|
||||
|
||||
@@ -33,6 +33,7 @@ class TTSProvider(TTSProviderBase):
|
||||
self.api_key = config.get("api_key")
|
||||
if not self.api_key:
|
||||
raise ValueError("api_key is required for CosyVoice TTS")
|
||||
self.report_on_last = True
|
||||
|
||||
# WebSocket配置
|
||||
self.ws_url = "wss://dashscope.aliyuncs.com/api-ws/v1/inference/"
|
||||
|
||||
@@ -104,6 +104,7 @@ class TTSProvider(TTSProviderBase):
|
||||
self.access_key_secret = config.get("access_key_secret")
|
||||
self.appkey = config.get("appkey")
|
||||
self.format = config.get("format", "pcm")
|
||||
self.report_on_last = True
|
||||
|
||||
# 音色配置 - CosyVoice大模型音色
|
||||
if config.get("private_voice"):
|
||||
|
||||
@@ -40,6 +40,7 @@ class TTSProviderBase(ABC):
|
||||
self.tts_audio_queue = queue.Queue()
|
||||
self.tts_audio_first_sentence = True
|
||||
self.before_stop_play_files = []
|
||||
self.report_on_last = False
|
||||
|
||||
self.tts_text_buff = []
|
||||
self.punctuations = (
|
||||
@@ -322,7 +323,7 @@ class TTSProviderBase(ABC):
|
||||
def _audio_play_priority_thread(self):
|
||||
# 需要上报的文本和音频列表
|
||||
enqueue_text = None
|
||||
enqueue_audio = None
|
||||
enqueue_audio = []
|
||||
while not self.conn.stop_event.is_set():
|
||||
text = None
|
||||
try:
|
||||
@@ -342,14 +343,24 @@ class TTSProviderBase(ABC):
|
||||
|
||||
# 收到下一个文本开始或会话结束时进行上报
|
||||
if sentence_type is not SentenceType.MIDDLE:
|
||||
# 上报TTS数据
|
||||
if enqueue_text is not None and enqueue_audio is not None:
|
||||
enqueue_tts_report(self.conn, enqueue_text, enqueue_audio)
|
||||
enqueue_audio = []
|
||||
enqueue_text = text
|
||||
if self.report_on_last:
|
||||
# 累积模式：适用于全程只有一个语音流的TTS（如seed-tts-2.0）
|
||||
# FIRST时只记录文本，音频持续累积，仅在LAST时统一上报
|
||||
if text:
|
||||
enqueue_text = text
|
||||
if sentence_type == SentenceType.LAST:
|
||||
enqueue_tts_report(self.conn, enqueue_text, enqueue_audio)
|
||||
enqueue_audio = []
|
||||
enqueue_text = None
|
||||
else:
|
||||
# 非累积模式：每个句子分别上报
|
||||
if enqueue_text is not None:
|
||||
enqueue_tts_report(self.conn, enqueue_text, enqueue_audio)
|
||||
enqueue_audio = []
|
||||
enqueue_text = text
|
||||
|
||||
# 收集上报音频数据
|
||||
if isinstance(audio_datas, bytes) and enqueue_audio is not None:
|
||||
if isinstance(audio_datas, bytes):
|
||||
enqueue_audio.append(audio_datas)
|
||||
|
||||
# 发送音频
|
||||
|
||||
@@ -148,6 +148,8 @@ class TTSProvider(TTSProviderBase):
|
||||
self.access_token = config.get("access_token")
|
||||
self.cluster = config.get("cluster")
|
||||
self.resource_id = config.get("resource_id")
|
||||
self.resource_type = True if self.resource_id == "seed-tts-2.0" else False
|
||||
self.report_on_last = self.resource_type
|
||||
self.activate_session = False
|
||||
if config.get("private_voice"):
|
||||
self.voice = config.get("private_voice")
|
||||
@@ -511,7 +513,7 @@ class TTSProvider(TTSProviderBase):
|
||||
if res.optional.event == EVENT_SessionCanceled:
|
||||
logger.bind(tag=TAG).debug(f"释放服务端资源成功～～")
|
||||
self.activate_session = False
|
||||
elif res.optional.event == EVENT_TTSSentenceStart:
|
||||
elif not self.resource_type and res.optional.event == EVENT_TTSSentenceStart:
|
||||
json_data = json.loads(res.payload.decode("utf-8"))
|
||||
self.tts_text = json_data.get("text", "")
|
||||
logger.bind(tag=TAG).debug(f"句子语音生成开始: {self.tts_text}")
|
||||
@@ -522,8 +524,17 @@ class TTSProvider(TTSProviderBase):
|
||||
res.optional.event == EVENT_TTSResponse
|
||||
and res.header.message_type == AUDIO_ONLY_RESPONSE
|
||||
):
|
||||
# 处理seed-tts-2.0文本字幕
|
||||
if self.resource_type and self.conn.tts_MessageText:
|
||||
logger.bind(tag=TAG).info(
|
||||
f"句子语音生成成功： {self.conn.tts_MessageText}"
|
||||
)
|
||||
self.tts_audio_queue.put(
|
||||
(SentenceType.FIRST, [], self.conn.tts_MessageText)
|
||||
)
|
||||
self.conn.tts_MessageText = None
|
||||
self.wav_to_opus_data_audio_raw_stream(res.payload, callback=self.handle_opus)
|
||||
elif res.optional.event == EVENT_TTSSentenceEnd:
|
||||
elif not self.resource_type and res.optional.event == EVENT_TTSSentenceEnd:
|
||||
logger.bind(tag=TAG).info(f"句子语音生成成功：{self.tts_text}")
|
||||
elif res.optional.event == EVENT_SessionFinished:
|
||||
logger.bind(tag=TAG).debug(f"会话结束～～")
|
||||
|
||||
@@ -76,6 +76,7 @@ class TTSProvider(TTSProviderBase):
|
||||
self.app_id = config.get("app_id")
|
||||
self.api_key = config.get("api_key")
|
||||
self.api_secret = config.get("api_secret")
|
||||
self.report_on_last = True
|
||||
|
||||
# 接口地址
|
||||
self.api_url = config.get("api_url", "wss://cbm01.cn-huabei-1.xf-yun.com/v1/private/mcd9m97e6")
|
||||
|
||||
Reference in New Issue
Block a user