SuperBizAgent-java/mvp/issues/rag/rag-upload-chunk-parameter-drift.md

RAG 上传切片参数未真正生效

状态：待规划
严重程度：低
发现时间：2026-07-04
范围：文档上传接口、切片配置、API 行为一致性

---

现象

上传接口暴露了 chunkSize 和 chunkOverlap 参数，但实际切片主要使用全局 DocumentChunkConfig。这会造成 API 表面能力和真实行为不一致。

---

当前实现

• DocumentController 的上传接口接收 chunkSize 和 chunkOverlap。
• 这些字段会进入 DocumentUploadRequest。
• DocumentChunkService 的切片阈值主要来自 DocumentChunkConfig。
• 单次上传请求中的参数没有真正覆盖切片配置。

---

影响

• 调用方以为可以控制切片大小，但实际无法影响结果。
• 测试时容易误判“参数调优无效”的原因。
• 面试中如果展示 API，会被追问参数是否真实生效。

---

建议修复

两个方向二选一：

1. 如果 MVP 不需要请求级切片参数，就从接口中移除或标记为暂不支持。
2. 如果需要支持，就让 DocumentChunkService 接收 per-request chunk options，并记录到文档 metadata 中。

建议面试项目中优先选择第二种，因为它更能体现工程闭环：API、配置、落库、追踪一致。

---

相关文件

• src/main/java/com/superbiz/agent/controller/DocumentController.java
• src/main/java/com/superbiz/agent/service/DocumentManagementService.java
• src/main/java/com/superbiz/agent/service/DocumentChunkService.java
• src/main/java/com/superbiz/agent/config/DocumentChunkConfig.java