┌─→ BM25 关键词检索（稀疏检索）─→ 候选集 A
用户 Query ────────→┤
                    └─→ 向量语义检索（稠密检索）─→ 候选集 B
                                                  │
                                             融合排序（RRF/加权）
                                                  │
                                             最终 Top-K

Query → [查询改写] → 混合检索（BM25 + 向量）→ 召回大池子 Top-100
       → Rerank 精排 → Top-3~8 → LLM

score = α × norm(BM25_score) + (1 − α) × norm(vector_score)

score(doc) = Σ 1 / (k + rankᵢ(doc))     （k 常用 60）

文档 → 分块 → ① 建立 BM25 倒排索引（Lucene）
            → ② 计算 embedding → 建立向量索引（Lucene HNSW）

用户 Query → ③ 关键词查询 → Lucene BM25 → 候选集 A（含 docId、rank）
          → ④ embedding(query) → Lucene 向量查询 → 候选集 B（含 docId、rank）
          → ⑤ RRF 融合排序 → Top-K
          → ⑥ 取出 chunk 原文 → 送 LLM

<!-- Lucene：核心 + 高级分析 + 高亮（含向量索引） -->
<dependency>
    <groupId>org.apache.lucene</groupId>
    <artifactId>lucene-core</artifactId>
    <version>9.11.1</version>
</dependency>
<dependency>
    <groupId>org.apache.lucene</groupId>
    <artifactId>lucene-analysis-common</artifactId>
    <version>9.11.1</version>
</dependency>
<dependency>
    <groupId>org.apache.lucene</groupId>
    <artifactId>lucene-queries</artifactId>
    <version>9.11.1</version>
</dependency>

<!-- 中文分词：IKAnalyzer -->
<dependency>
    <groupId>com.janeluo</groupId>
    <artifactId>ikanalyzer</artifactId>
    <version>2012_u6</version>
</dependency>

<!-- Embedding：可用 ONNX/ML 库，或调用外部 Embedding API（如 OpenAI / bge） -->
<!-- 本文用简单的随机向量演示流程，生产请替换为真实 Embedding 模型 -->

import org.apache.lucene.analysis.Analyzer;
import org.apache.lucene.analysis.TokenStream;
import org.apache.lucene.analysis.tokenattributes.CharTermAttribute;
import org.apache.lucene.document.*;
import org.apache.lucene.index.*;
import org.apache.lucene.search.*;
import org.apache.lucene.search.similarities.BM25Similarity;
import org.apache.lucene.store.ByteBuffersDirectory;
import org.apache.lucene.store.Directory;
import org.wltea.analyzer.lucene.IKAnalyzer;

import java.io.StringReader;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * 混合检索演示：Lucene 同时建立 BM25 文本索引 + HNSW 向量索引
 * 说明：embedding 用随机向量演示，生产请接入真实 Embedding 模型
 */
public class HybridSearchDemo {

    // 简单递归式分块：按段落/句子切，控制最大 token 数（近似用字符模拟）
    static List<String> chunkText(String text, int maxChars, int overlap) {
        List<String> chunks = new ArrayList<>();
        int start = 0;
        while (start < text.length()) {
            int end = Math.min(text.length(), start + maxChars);
            // 尽量在句号/换行处切（示意）
            if (end < text.length()) {
                int cut = text.lastIndexOf("。", end);
                if (cut > start + maxChars / 2) end = cut + 1;
            }
            chunks.add(text.substring(start, end));
            if (end >= text.length()) break;
            start = Math.max(start + 1, end - overlap); // 带 overlap 滑动
        }
        return chunks;
    }

    // 真实工程请调用 Embedding 模型（如 ONNX 加载 bge-m3，或 HTTP 调外部 API）
    static float[] embed(String text) {
        // 演示：确定性伪随机向量，维度 4
        float[] v = new float[4];
        int seed = text.hashCode();
        v[0] = ((seed >> 0) & 0xff) / 255f;
        v[1] = ((seed >> 8) & 0xff) / 255f;
        v[2] = ((seed >> 16) & 0xff) / 255f;
        v[3] = ((seed >> 24) & 0xff) / 255f;
        return normalize(v);
    }

    static float[] normalize(float[] v) {
        float norm = 0f;
        for (float x : v) norm += x * x;
        norm = (float) Math.sqrt(norm);
        for (int i = 0; i < v.length; i++) v[i] /= norm; // L2 归一化 → 内积=余弦
        return v;
    }

    public static void main(String[] args) throws Exception {
        // ---------- 1. 准备文档（模拟 RAG 语料） ----------
        List<String> docs = List.of(
            "RAG 文本分块策略包括固定长度分块、递归字符分块和语义分块。",
            "chunkSize 通常设置为 400 到 500 个 token，overlap 设为 10% 到 25%。",
            "父子分块使用小子块检索、大父块生成，兼顾精确与完整。",
            "向量检索常用余弦相似度，归一化后内积与余弦等价。",
            "混合检索结合 BM25 关键词检索与向量语义检索，用 RRF 融合排名。"
        );

        // ---------- 2. 建立双索引（BM25 文本 + 向量） ----------
        Directory dir = new ByteBuffersDirectory(); // 内存目录，生产用 FSDirectory
        Analyzer analyzer = new IKAnalyzer();       // 中文分词

        IndexWriterConfig iwc = new IndexWriterConfig(analyzer);
        iwc.setSimilarity(new BM25Similarity());    // 默认即 BM25
        IndexWriter writer = new IndexWriter(dir, iwc);

        Map<Integer, String> idToText = new HashMap<>();
        int docId = 0;
        for (String doc : docs) {
            for (String chunk : chunkText(doc, 100, 20)) {
                Document luceneDoc = new Document();
                luceneDoc.add(new StringField("id", String.valueOf(docId), Field.Store.YES));
                luceneDoc.add(new TextField("content", chunk, Field.Store.YES)); // BM25 索引
                luceneDoc.add(new KnnFloatVectorField("vector", embed(chunk)));  // HNSW 向量索引
                idToText.put(docId, chunk);
                docId++;
            }
        }
        writer.commit();
        writer.close();

        // ---------- 3. 用户查询 ----------
        String query = "如何设置 chunkSize 和 overlap？";
        int topK = 3;

        // ---------- 4. 路径 A：BM25 关键词检索 ----------
        IndexReader reader = DirectoryReader.open(dir);
        IndexSearcher searcher = new IndexSearcher(reader);
        searcher.setSimilarity(new BM25Similarity());

        org.apache.lucene.queryparser.classic.QueryParser parser =
            new org.apache.lucene.queryparser.classic.QueryParser(
                "content", analyzer);
        Query bm25Query = parser.parse(query);

        List<ResultItem> bm25Hits = new ArrayList<>();
        for (ScoreDoc sd : searcher.search(bm25Query, 10).scoreDocs) {
            Document d = searcher.storedFields().document(sd.doc);
            bm25Hits.add(new ResultItem(d.get("id"), sd.doc, 0, sd.score));
        }

        // ---------- 5. 路径 B：向量语义检索 ----------
        float[] queryVector = embed(query);
        List<ResultItem> vecHits = new ArrayList<>();
        KnnFloatVectorQuery knnQuery = new KnnFloatVectorQuery("vector", queryVector, 10);
        for (ScoreDoc sd : searcher.search(knnQuery, 10).scoreDocs) {
            Document d = searcher.storedFields().document(sd.doc);
            vecHits.add(new ResultItem(d.get("id"), sd.doc, 1, sd.score));
        }
        reader.close();

        // ---------- 6. RRF 融合排序 ----------
        List<String> finalRank = rrfFuse(bm25Hits, vecHits, topK);

        // ---------- 7. 输出结果 ----------
        System.out.println("=== 混合检索 Top-" + topK + " ===");
        for (String id : finalRank) {
            System.out.println("[" + id + "] " + idToText.get(Integer.parseInt(id)));
        }
    }

    /** 结果项：docId、来源（0=BM25,1=向量）、rank、原始分数 */
    record ResultItem(String id, int doc, int source, float score) {}

    /** RRF 融合：只依赖排名，k=60 */
    static List<String> rrfFuse(List<ResultItem> a, List<ResultItem> b, int topK) {
        final int K = 60;
        Map<String, Double> rrf = new HashMap<>();

        // 给每一路的候选按其排名打分：1 / (K + rank)
        addRrfScore(rrf, a);
        addRrfScore(rrf, b);

        // 按 RRF 得分降序输出 topK
        return rrf.entrySet().stream()
            .sorted(Map.Entry.<String, Double>comparingByValue().reversed())
            .limit(topK)
            .map(Map.Entry::getKey)
            .toList();
    }

    static void addRrfScore(Map<String, Double> rrf, List<ResultItem> items) {
        int rank = 1;
        for (ResultItem item : items) {
            rrf.merge(item.id(), 1.0 / (60 + rank), Double::sum);
            rank++;
        }
    }
}

// 方式一：本地 ONNX（如 bge-m3 转 ONNX，用 onnxruntime 推理）
//   float[] embed(String text) {
//       // 加载 Model，对 text 做 tokenize → 推理 → 取 pool 后向量 → normalize
//   }

// 方式二：HTTP 调用 Embedding API（如 OpenAI / 自建服务）
//   float[] embed(String text) {
//       // HttpClient POST /v1/embeddings {input: text}
//       // 解析返回向量 → normalize
//   }

┌─ Java 应用 ───────────────────────────┐
│  HybridService                        │
│   ├─ BM25: 调 Elasticsearch REST API   │
│   │        (match_query 到 content 字段)│
│   ├─ Vector: 调 Milvus / Qdrant SDK    │
│   │        (collection.search 向量)     │
│   └─ RRF: 对两组 (id, rank) 融合        │
└───────────────────────────────────────┘

// 伪代码：ES 返回 (id, _score)，Milvus 返回 (id, score)
// 把两边的"排名"提出来，丢给与上面相同的 rrfFuse() 即可。