<dependencies>
    <!-- Spring AI OpenAI -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-model-openai</artifactId>
    </dependency>
    <!-- Spring AI Elasticsearch Vector Store -->
    <dependency>
        <groupId>org.springframework.ai</groupId>
        <artifactId>spring-ai-starter-vector-store-elasticsearch</artifactId>
    </dependency>
    <!-- WebFlux -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter-webflux</artifactId>
    </dependency>
</dependencies>

# application.yml
spring:
  ai:
    openai:
      api-key: ${OPENAI_API_KEY}
      embedding:
        options:
          model: text-embedding-3-small
    vectorstore:
      elasticsearch:
        index-name: document-store
        dimensions: 1536

/**
 * Agentic 切割核心邏輯
 * 
 * 1. 首先使用遞歸切割獲得初步塊
 * 2. 識(shí)別主題轉(zhuǎn)換標(biāo)記詞
 * 3. 在主題邊界處優(yōu)化切割點(diǎn)
 */
public List<Document> splitAgentic(String text, String filename, SplitOptions options) {
    // 第一步：遞歸切割獲得初步塊
    List<TextChunk> initialChunks = recursiveSplitInternal(
        normalizeText(text),
        0,
        chunkSize * 2, // 更大的初始?jí)K
        chunkOverlap,
        0
    );
    
    // 第二步：使用啟發(fā)式規(guī)則優(yōu)化切割點(diǎn)
    for (TextChunk chunk : initialChunks) {
        // 識(shí)別主題轉(zhuǎn)換標(biāo)記詞
        String optimizedContent = optimizeChunkBoundary(content, chunkSize);
        // ...
    }
}

// 主題轉(zhuǎn)換標(biāo)記詞（中英文）
String[] topicMarkers = {
    // 標(biāo)點(diǎn)符號(hào)
    "\n\n", "\n", ". ", "? ", "! ", "。", "？", "！",
    // 中文序列詞
    "首先", "其次", "然后", "接下來(lái)", "最后",
    "第一", "第二", "第三", "另一方面", "此外", "總之"
};

# 上傳長(zhǎng)文檔，使用 Agentic 切割
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=AGENTIC&chunkSize=1500" \
  -F "file=@long-article.txt"

{
  "split_method": "agentic",
  "original_separator": "\n\n",
  "optimization_applied": true,
  "chunk_group": 0
}

/**
 * 代碼感知切割
 * 
 * 1. 檢測(cè)編程語(yǔ)言
 * 2. 解析代碼塊（類(lèi)、方法等）
 * 3. 提取 import 語(yǔ)句
 * 4. 按代碼結(jié)構(gòu)切割
 */
public List<Document> splitCodeAware(String text, String filename, SplitOptions options) {
    // 檢測(cè)語(yǔ)言
    String language = detectLanguage(filename);
    
    // 解析代碼塊
    List<CodeBlock> codeBlocks = parseCodeBlocks(text, language);
    
    // 提取 imports
    List<String> imports = extractImports(text, language);
    
    // 構(gòu)建文檔
    for (CodeBlock block : codeBlocks) {
        Map<String, Object> metadata = buildCodeMetadata(
            filename, chunkIndex, block, imports, language
        );
        // ...
    }
}

// Java 代碼塊解析正則
Pattern pattern = Pattern.compile(
    "(?:(public|private|protected|static|final|abstract|class|interface|enum|record|void|@\\w+)\\s+)?" +
    "(?:<[^>]+>\\s*)?" +
    "(\\w+)\\s*\\([^)]*\\)\\s*(?:throws\\s+\\w+(?:\\s*,\\s*\\w+)*)?\\s*\\{[^}]*\\}" +
    "|(?:public|private|protected)?\\s*(?:static\\s+)?(?:final\\s+)?(?:abstract\\s+)?" +
    "(?:class|interface|enum|record)\\s+(\\w+)",
    Pattern.DOTALL
);

# 上傳 Java 文件
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=CODE_AWARE" \
  -F "file=@UserService.java"
# 上傳 Python 文件
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=CODE_AWARE" \
  -F "file=@main.py"

{
  "split_method": "code_aware",
  "language": "java",
  "block_type": "method",
  "block_name": "getUserById",
  "start_line": 45,
  "imports_count": 12,
  "has_imports": true
}

/**
 * 層次結(jié)構(gòu)切割
 * 
 * 構(gòu)建文檔樹(shù)：文檔 → 章節(jié) → 小節(jié) → 段落
 */
public List<Document> splitHierarchical(String text, String filename, SplitOptions options) {
    // 構(gòu)建層次樹(shù)
    DocumentNode root = buildHierarchicalTree(text, filename);
    
    // 展平樹(shù)為文檔列表
    List<Document> documents = new ArrayList<>();
    flattenTree(root, documents, filename, 0, maxChunkSize);
    
    return documents;
}

/**
 * 構(gòu)建層次樹(shù)
 */
private DocumentNode buildHierarchicalTree(String text, String filename) {
    DocumentNode root = new DocumentNode("root", "document", text, 0, 0);
    
    // 第一層：按章節(jié)分割
    String[] chapters = text.split(
        "(?=(?:^|\\n)\\s*(?:第[一二三四五六七八九十\\d]+[章節(jié)篇]|Chapter\\s+\\d+|\\d+\\.\\s+[^\\n]+))"
    );
    
    // 第二層：按小節(jié)分割
    // 第三層：按段落分割
    // ...
}

# 上傳結(jié)構(gòu)化長(zhǎng)文檔
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=HIERARCHICAL&chunkSize=2000" \
  -F "file=@book.txt"

{
  "split_method": "hierarchical",
  "node_id": "section_0_1",
  "node_type": "section",
  "hierarchy_level": 2,
  "node_index": 1,
  "has_children": true,
  "children_count": 3
}

/**
 * 滑動(dòng)窗口切割
 * 
 * 特點(diǎn)：
 * - 高重疊率（默認(rèn) 50%）
 * - 確保沒(méi)有信息遺漏
 * - 適合檢索增強(qiáng)生成 (RAG)
 */
public List<Document> splitSlidingWindow(String text, String filename, SplitOptions options) {
    int windowSize = options.getChunkSize() != null ? options.getChunkSize() : DEFAULT_CHUNK_SIZE;
    int overlapRatio = options.getChunkOverlap() != null ? options.getChunkOverlap() : 50;
    
    // 計(jì)算步長(zhǎng)
    int stride = Math.max(1, windowSize * (100 - overlapRatio) / 100);
    
    while (startIndex < normalizedText.length()) {
        int endIndex = Math.min(startIndex + windowSize, normalizedText.length());
        
        // 嘗試在句子邊界結(jié)束
        if (endIndex < normalizedText.length()) {
            endIndex = findBestSplitPoint(normalizedText, endIndex);
        }
        
        // 滑動(dòng)窗口
        startIndex += stride;
    }
}

# 高重疊率（70%）- 適合高精度檢索
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=SLIDING_WINDOW&chunkSize=1000&chunkOverlap=70" \
  -F "file=@document.txt"
# 中等重疊率（50%）- 平衡方案
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=SLIDING_WINDOW&chunkSize=1000&chunkOverlap=50" \
  -F "file=@document.txt"

{
  "split_method": "sliding_window",
  "window_start": 0,
  "window_end": 1000,
  "window_size": 1000,
  "stride": 500,
  "overlap_ratio": 50,
  "overlap_with_previous": 0
}

/**
 * 檢測(cè)結(jié)構(gòu)化數(shù)據(jù)格式
 */
private String detectStructuredFormat(String filename, String content) {
    String lower = filename.toLowerCase();
    if (lower.endsWith(".csv")) return "csv";
    if (lower.endsWith(".json")) return "json";
    if (lower.endsWith(".xml")) return "xml";
    if (lower.endsWith(".yaml") || lower.endsWith(".yml")) return "yaml";
    
    // 根據(jù)內(nèi)容檢測(cè)
    String trimmed = content.trim();
    if (trimmed.startsWith("[") || trimmed.startsWith("{")) return "json";
    if (trimmed.startsWith("<?xml") || trimmed.startsWith("<")) return "xml";
    // ...
}

/**
 * CSV 切割 - 保留表頭
 */
private List<Document> splitCsv(String text, String filename, SplitOptions options) {
    int maxRows = options.getChunkSize() != null ? options.getChunkSize() / 50 : 100;
    
    // 提取表頭
    String header = lines[0];
    List<String> headers = parseCsvLine(header);
    
    // 每個(gè)塊都包含表頭
    for (String line : dataLines) {
        if (rowCount >= maxRows) {
            // 保存當(dāng)前塊
            // 新塊以表頭開(kāi)始
            currentChunk.append(header).append("\n");
        }
        currentChunk.append(line).append("\n");
    }
}

/**
 * JSON 切割 - 按對(duì)象/條目分割
 */
private List<Document> splitJson(String text, String filename, SplitOptions options) {
    // JSON 數(shù)組：提取每個(gè)對(duì)象
    if (trimmed.startsWith("[")) {
        List<String> objects = extractJsonObjects(trimmed);
        processJsonObjects(objects, filename, documents, maxSize);
    }
    // JSON 對(duì)象：按頂層鍵分割
    else if (trimmed.startsWith("{")) {
        List<String> entries = extractJsonEntries(trimmed);
        processJsonObjects(entries, filename, documents, maxSize);
    }
}

/**
 * XML 切割 - 按元素分割
 */
private List<Document> splitXml(String text, String filename, SplitOptions options) {
    // 提取 XML 聲明
    String declaration = "";
    int declEnd = text.indexOf("?>");
    if (declEnd > 0) {
        declaration = text.substring(0, declEnd + 2) + "\n";
    }
    
    // 提取主要元素
    List<String> elements = extractXmlElements(text);
    
    // 每個(gè)塊包含聲明
    for (String elem : elements) {
        currentChunk.append(declaration);
        currentChunk.append(elem);
    }
}

# CSV 文件
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=STRUCTURED_DATA" \
  -F "file=@users.csv"
# JSON 文件
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=STRUCTURED_DATA" \
  -F "file=@data.json"
# XML 文件
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=STRUCTURED_DATA" \
  -F "file=@config.xml"
# YAML 文件
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=STRUCTURED_DATA" \
  -F "file=@config.yaml"

{
  "split_method": "structured_data",
  "format": "csv",
  "start_index": 1,
  "end_index": 100,
  "record_count": 100,
  "headers": ["id", "name", "email"],
  "header_count": 3
}

{
  "split_method": "structured_data",
  "format": "json",
  "start_index": 0,
  "end_index": 49,
  "record_count": 50
}

# 基礎(chǔ)策略
POST /api/vector-store/upload?splitStrategy=RECURSIVE
POST /api/vector-store/upload?splitStrategy=MARKDOWN
POST /api/vector-store/upload?splitStrategy=TOKEN
POST /api/vector-store/upload?splitStrategy=SEMANTIC
POST /api/vector-store/upload?splitStrategy=SMART_PARAGRAPH
POST /api/vector-store/upload?splitStrategy=CHARACTER
# 新策略
POST /api/vector-store/upload?splitStrategy=AGENTIC
POST /api/vector-store/upload?splitStrategy=CODE_AWARE
POST /api/vector-store/upload?splitStrategy=HIERARCHICAL
POST /api/vector-store/upload?splitStrategy=SLIDING_WINDOW
POST /api/vector-store/upload?splitStrategy=STRUCTURED_DATA

# 1. Agentic 切割 - 長(zhǎng)文章
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=AGENTIC&chunkSize=1500&chunkOverlap=200" \
  -H "Content-Type: multipart/form-data" \
  -F "file=@article.txt"
# 2. 代碼感知切割 - Java 文件
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=CODE_AWARE" \
  -F "file=@UserService.java"
# 3. 層次結(jié)構(gòu)切割 - 書(shū)籍
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=HIERARCHICAL&chunkSize=3000" \
  -F "file=@book.txt"
# 4. 滑動(dòng)窗口切割 - RAG 場(chǎng)景
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=SLIDING_WINDOW&chunkSize=1000&chunkOverlap=70" \
  -F "file=@knowledge-base.txt"
# 5. 結(jié)構(gòu)化數(shù)據(jù)切割 - CSV
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=STRUCTURED_DATA" \
  -F "file=@products.csv"
# 6. 結(jié)構(gòu)化數(shù)據(jù)切割 - JSON
curl -X POST "http://localhost:8080/api/vector-store/upload?splitStrategy=STRUCTURED_DATA" \
  -F "file=@api-docs.json"

{
  "success": true,
  "message": "File uploaded and processed successfully",
  "data": {
    "filename": "article.txt",
    "chunkCount": 12,
    "totalCharacters": 15420,
    "splitMethod": "AGENTIC",
    "message": "Processed with AGENTIC strategy"
  }
}

// 對(duì)于大文件，建議：
// 1. 使用流式處理
// 2. 增加 chunkSize 減少塊數(shù)
// 3. 使用異步處理

// 推薦配置
SplitOptions options = new SplitOptions()
    .withChunkSize(2000)      // 更大的塊
    .withChunkOverlap(100);   // 較小的重疊

// 批量上傳多個(gè)文件
for (File file : files) {
    // 根據(jù)文件類(lèi)型選擇策略
    SplitStrategy strategy = selectStrategy(file);
    
    documentSplitterService.split(
        readFile(file),
        file.getName(),
        strategy,
        options
    );
}

// 對(duì)于重復(fù)處理的文檔，可以緩存切割結(jié)果
@Cacheable(value = "documentChunks", key = "#filename + '_' + #strategy")
public List<Document> split(String text, String filename, SplitStrategy strategy) {
    // ...
}