demon-slaying-rag 0.1.0__tar.gz

demon_slaying_rag-0.1.0/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: demon-slaying-rag
+Version: 0.1.0
+Summary: A modular RAG retrieval class based on LangChain and Chroma
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: chromadb>=1.0
+Requires-Dist: langchain-chroma>=1.0
+Requires-Dist: langchain-core>=1.0
+Requires-Dist: langchain-community>=0.4
+Requires-Dist: langchain-openai>=1.0
+Requires-Dist: langchain-classic>=1.0
+Requires-Dist: dashscope>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: jieba>=0.42
+Requires-Dist: rank-bm25>=0.2
+Provides-Extra: publish
+Requires-Dist: build; extra == "publish"
+Requires-Dist: twine; extra == "publish"
+
+# demon-slaying-rag
+
+一个可配置的**模块化 RAG 检索器**：只负责"从已有 Chroma 知识库里把最相关的片段取回来"，不包含入库、切分与答案生成。
+
+核心是 `ModularRAG` 类，把早期脚本里散落的检索参数集中成一份 `config` 字典，并按三阶段流水线执行：
+
+```
+问题
+ │
+ ├─ 检索前优化  pre_retrieval   归一化 → (可选)查询改写 → (可选)HyDE 假设答案
+ │
+ ├─ 混合召回    hybrid_retrieval 纯向量检索 或 向量+BM25 经 RRF 融合
+ │
+ └─ 检索后处理  post_retrieval   去重 → (可选)重排 → (可选)相似度过滤
+                               → 截断 top_k → (可选)上下文压缩 → (可选)重排顺序
+ │
+返回 List[Document]（带 retrieval_rank / context_position 等元数据）
+```
+
+---
+
+## 环境要求
+
+- Python >= 3.11（已在 3.13 上验证）
+- 依赖（`pip install .` 会自动安装）：
+
+| 依赖 | 用途 |
+| --- | --- |
+| `chromadb` / `langchain-chroma` | 向量库连接（`Chroma`） |
+| `langchain-core` | `Document`、`RunnableLambda` |
+| `langchain-community` | `DashScopeEmbeddings`、`BM25Retriever`、`DashScopeRerank`、`LongContextReorder` |
+| `langchain-openai` | 通过 DashScope 兼容接口调用 `qwen-plus` 做改写 / HyDE / 压缩 |
+| `langchain-classic` | `EnsembleRetriever`（RRF 融合）、`LLMChainExtractor`（上下文压缩） |
+| `dashscope` | 通义 Embedding / Rerank 的 SDK |
+| `jieba` + `rank-bm25` | 混合检索的 BM25 分词与实现（仅混合检索需要） |
+| `python-dotenv` | 读取 `.env` 中的 `DASHSCOPE_API_KEY` |
+
+## 安装
+
+本项目未发布到 PyPI，使用本地安装：
+
+```bash
+# 可编辑安装（推荐本地开发）
+pip install -e .
+
+# 或普通安装
+pip install .
+
+# 额外安装打包发布工具
+pip install -e ".[publish]"
+```
+
+## 前置条件
+
+1. **知识库必须已存在**：`persist_directory` 指向的目录下必须有 `chroma.sqlite3`，否则构造函数直接抛 `FileNotFoundError`。
+2. **不会自动建集合**：内部使用 `create_collection_if_not_exists=False`，集合不存在时报错，而不是静默创建一个空库（避免"检索结果永远为空"的排查黑洞）。
+3. **API Key**：在项目根目录放一个 `.env`，或直接设置环境变量。
+
+```bash
+# Linux / macOS
+export DASHSCOPE_API_KEY="sk-xxxx"
+
+# Windows PowerShell
+setx DASHSCOPE_API_KEY "sk-xxxx"
+```
+
+```ini
+# .env
+DASHSCOPE_API_KEY=sk-xxxx
+```
+
+> 入库（切分 + 向量化 + 写 Chroma）不在本模块职责内，请用你已有的离线建库脚本生成知识库。
+
+---
+
+## 快速开始
+
+```python
+from demon_slaying_rag import ModularRAG
+
+rag = ModularRAG({
+    # ---- 基础连接 ----
+    "persist_directory": "./chroma_db",     # Chroma 目录（含 chroma.sqlite3）
+    "collection_name": "study",
+    "embedding_model": "text-embedding-v4",
+    # ---- 召回 ----
+    "top_k": 5,
+    "recall_top_k": 20,
+    # ---- 检索前优化 ----
+    "pre_retrieval": {
+        "enabled": False,
+        "rewrite_query": False,
+        "hyde": False,
+        "model": "qwen-plus",
+    },
+    # ---- 混合召回 ----
+    "hybrid_retrieval": {
+        "enabled": True,
+        "weights": [0.5, 0.5],              # [向量权重, BM25 权重]
+    },
+    # ---- 检索后处理 ----
+    "post_retrieval": {
+        "enabled": True,
+        "deduplicate": True,
+        "rerank": False,
+        "rerank_model": "qwen3-rerank",
+        "similarity_filter": False,
+        "similarity_threshold": 0.4,
+        "compress_context": False,
+        "llm_model": "qwen-plus",
+        "reorder": False,
+    },
+})
+
+documents = rag.search("公司打卡时间？")
+for document in documents:
+    print(document.metadata["retrieval_rank"], document.metadata["context_position"])
+    print(document.page_content)
+    print("-" * 40)
+```
+
+带元数据过滤与临时 top_k：
+
+```python
+documents = rag.search(
+    "试用期规定",
+    top_k=8,
+    filters={"source": "员工手册.pdf"},          # 与 config["filters"] 以 $and 合并
+)
+```
+
+---
+
+## 配置项
+
+### 基础连接与召回
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `persist_directory` | `./chroma_db` | Chroma 目录，**相对当前工作目录**解析（支持 `~`） |
+| `collection_name` | `study` | 集合名 |
+| `embedding_model` | `text-embedding-v4` | DashScope Embedding 模型，必须与建库时一致 |
+| `top_k` | `5` | 最终返回条数 |
+| `recall_top_k` | `20` | 召回阶段条数；实际取 `max(recall_top_k, top_k)` |
+| `filters` | 无 | Chroma `where` 过滤条件，如 `{"source": "a.pdf"}` |
+
+### 检索前优化 `pre_retrieval`
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `False` | 总开关，关闭时下列子项**全部不生效** |
+| `rewrite_query` | `False` | 用 `qwen-plus` 把问题改写为独立查询，向量与 BM25 都用改写后结果 |
+| `hyde` | `False` | 用 `qwen-plus` 生成约 100 字假设答案，**仅替换向量检索的查询** |
+| `model` | `qwen-plus` | 改写 / HyDE 使用的 LLM |
+
+开启 `enabled` 后，`normalize_query`（合并多余空白）总是执行，没有单独开关。
+
+### 混合召回 `hybrid_retrieval`
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `False` | 开启后走 向量 + BM25 + RRF 融合；关闭则纯向量检索 |
+| `weights` | `[0.5, 0.5]` | `EnsembleRetriever` 权重，顺序为 `[向量, BM25]` |
+
+RRF 的 `c` 参数固定为 `60`（`rrf_fusion` 的 `rrf_k`）。
+
+### 检索后处理 `post_retrieval`
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `False` | 总开关，关闭时下列子项全部不生效 |
+| `deduplicate` | `True` | 按 `page_content` 去重 |
+| `rerank` | `False` | 调用 DashScope Rerank 重排 |
+| `rerank_model` | `qwen3-rerank` | 重排模型 |
+| `similarity_filter` | `False` | 按余弦相似度过滤 |
+| `similarity_threshold` | `0.4` | 相似度阈值，低于该值丢弃 |
+| `compress_context` | `False` | 用 `LLMChainExtractor` 抽取与问题相关的句子（表格类文档跳过） |
+| `llm_model` | `qwen-plus` | 压缩使用的 LLM |
+| `reorder` | `False` | `LongContextReorder`：把关键内容放到上下文首尾（"中间遗忘"缓解） |
+
+### 执行顺序（`search` 内部）
+
+1. 校验：问题非空、`top_k` 为正整数，否则抛 `ValueError`
+2. `count = max(recall_top_k, top_k)`
+3. 检索前：归一化 → 改写 →（可选）HyDE 生成 `dense_query`
+4. 过滤条件：`config["filters"]` 与 `search(filters=...)` 合并为 `$and`
+5. 召回：
+   - `hybrid.enabled`：`db.get(where=...)` 拉全集 → 建 `BM25Retriever`（jieba 分词）+ 向量检索器 → `EnsembleRetriever` RRF 融合
+   - 否则：`vector_search`
+6. 后处理（`post.enabled`）：去重 → 重排 `top_n=len(documents)` → 相似度过滤
+7. 截断到 `top_k`，写入 `metadata["retrieval_rank"]`（1 起）
+8. 后处理第二阶段：上下文压缩 → 重排顺序，写入 `metadata["context_position"]`
+
+---
+
+## API
+
+### `ModularRAG(config: dict)`
+
+连接知识库并初始化 Embedding 模型。`config` 中缺失的键一律走默认值。
+
+### `search(question: str, top_k: int | None = None, filters: dict | None = None) -> list[Document]`
+
+在线检索，返回按相关性排好序的 `Document` 列表。返回的 `metadata` 除知识库原始字段外，可能包含：
+
+| 字段 | 出现条件 | 含义 |
+| --- | --- | --- |
+| `chunk_id` | 纯向量检索分支 | 文档在 Chroma 中的 id |
+| `retrieval_rank` | 总是 | 截断后的最终名次（1 起） |
+| `context_position` | 总是 | 送入上下文时的位置（1 起） |
+| `cosine_similarity` | 开启 `similarity_filter` | 与问题的余弦相似度 |
+
+### 可独立复用的静态方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `normalize_query(question)` | 合并空白并去首尾空格 |
+| `rewrite_query(question, model)` | 改写为适合检索的独立查询 |
+| `generate_hyde(question, model)` | 生成假设性答案（约 100 字） |
+| `vector_search(question, db, top_k, filters)` | 稠密检索 |
+| `bm25_search(question, documents, top_k)` | 稀疏检索（需自行提供语料） |
+| `rrf_fusion(question, vector_retriever, bm25_retriever, weights, rrf_k)` | RRF 融合两路召回 |
+| `deduplicate(documents)` | 按内容去重 |
+| `rerank_documents(question, documents, top_k, model)` | DashScope 重排 |
+| `similarity_filter(question, documents, embeddings, threshold)` | 余弦相似度过滤 |
+| `compress_context(question, documents, model)` | LLM 抽取式压缩 |
+| `reorder_documents(documents)` | 长上下文重排（首尾优先） |
+
+### 异常
+
+| 场景 | 异常 |
+| --- | --- |
+| 目录下没有 `chroma.sqlite3` | `FileNotFoundError` |
+| 问题为空 / `top_k` 非正整数 | `ValueError` |
+| 集合名不存在 | `chromadb` 抛出的 `NotFoundError` 类异常 |
+| 未安装 `jieba` / `rank-bm25` 却开启混合检索 | `ImportError` |
+
+---
+
+## 已知限制与注意事项
+
+- **键名拼错不会报错**：全篇使用 `config.get(k, default)`，写错键名只会静默走默认值，排障时优先怀疑键名。
+- **总开关优先**：`pre_retrieval.enabled=False` / `post_retrieval.enabled=False` 时，其下所有子项（含默认为 `True` 的 `deduplicate`）一律不生效。
+- **路径与工作目录绑定**：`persist_directory` 相对当前工作目录解析，从不同目录启动会连到不同的库；工作区内根目录与 `day_1106/` 下各有一个 `chroma_db`。
+- **混合检索的开销**：每次查询都会 `db.get()` 全量拉取文档并重建 BM25 索引，数据量大时延迟明显，且不支持大数据集分页。
+- **重复的 Embedding 调用**：`similarity_filter` 会对每条候选文档重新调用 Embedding API（向量库里其实已存有向量），有额外耗时与费用。
+- **压缩逐条调用 LLM**：`compress_context` 对每个文档单独请求一次 `qwen-plus`，条数越多越慢。
+- **模型一致性**：`embedding_model` 必须与建库时相同，否则相似度与过滤结果都会失真。
+
+## 目录结构
+
+```
+project/
+├── demon_slaying_rag.py   # ModularRAG 类（单模块）
+├── pyproject.toml         # 打包与依赖声明
+└── README.md
+```
+
+## 打包与发布
+
+```bash
+pip install -e ".[publish]"
+python -m build
+twine check dist/*
+twine upload dist/*        # 需要 PyPI Token
+```

demon_slaying_rag-0.1.0/README.md

@@ -0,0 +1,266 @@
+# demon-slaying-rag
+
+一个可配置的**模块化 RAG 检索器**：只负责"从已有 Chroma 知识库里把最相关的片段取回来"，不包含入库、切分与答案生成。
+
+核心是 `ModularRAG` 类，把早期脚本里散落的检索参数集中成一份 `config` 字典，并按三阶段流水线执行：
+
+```
+问题
+ │
+ ├─ 检索前优化  pre_retrieval   归一化 → (可选)查询改写 → (可选)HyDE 假设答案
+ │
+ ├─ 混合召回    hybrid_retrieval 纯向量检索 或 向量+BM25 经 RRF 融合
+ │
+ └─ 检索后处理  post_retrieval   去重 → (可选)重排 → (可选)相似度过滤
+                               → 截断 top_k → (可选)上下文压缩 → (可选)重排顺序
+ │
+返回 List[Document]（带 retrieval_rank / context_position 等元数据）
+```
+
+---
+
+## 环境要求
+
+- Python >= 3.11（已在 3.13 上验证）
+- 依赖（`pip install .` 会自动安装）：
+
+| 依赖 | 用途 |
+| --- | --- |
+| `chromadb` / `langchain-chroma` | 向量库连接（`Chroma`） |
+| `langchain-core` | `Document`、`RunnableLambda` |
+| `langchain-community` | `DashScopeEmbeddings`、`BM25Retriever`、`DashScopeRerank`、`LongContextReorder` |
+| `langchain-openai` | 通过 DashScope 兼容接口调用 `qwen-plus` 做改写 / HyDE / 压缩 |
+| `langchain-classic` | `EnsembleRetriever`（RRF 融合）、`LLMChainExtractor`（上下文压缩） |
+| `dashscope` | 通义 Embedding / Rerank 的 SDK |
+| `jieba` + `rank-bm25` | 混合检索的 BM25 分词与实现（仅混合检索需要） |
+| `python-dotenv` | 读取 `.env` 中的 `DASHSCOPE_API_KEY` |
+
+## 安装
+
+本项目未发布到 PyPI，使用本地安装：
+
+```bash
+# 可编辑安装（推荐本地开发）
+pip install -e .
+
+# 或普通安装
+pip install .
+
+# 额外安装打包发布工具
+pip install -e ".[publish]"
+```
+
+## 前置条件
+
+1. **知识库必须已存在**：`persist_directory` 指向的目录下必须有 `chroma.sqlite3`，否则构造函数直接抛 `FileNotFoundError`。
+2. **不会自动建集合**：内部使用 `create_collection_if_not_exists=False`，集合不存在时报错，而不是静默创建一个空库（避免"检索结果永远为空"的排查黑洞）。
+3. **API Key**：在项目根目录放一个 `.env`，或直接设置环境变量。
+
+```bash
+# Linux / macOS
+export DASHSCOPE_API_KEY="sk-xxxx"
+
+# Windows PowerShell
+setx DASHSCOPE_API_KEY "sk-xxxx"
+```
+
+```ini
+# .env
+DASHSCOPE_API_KEY=sk-xxxx
+```
+
+> 入库（切分 + 向量化 + 写 Chroma）不在本模块职责内，请用你已有的离线建库脚本生成知识库。
+
+---
+
+## 快速开始
+
+```python
+from demon_slaying_rag import ModularRAG
+
+rag = ModularRAG({
+    # ---- 基础连接 ----
+    "persist_directory": "./chroma_db",     # Chroma 目录（含 chroma.sqlite3）
+    "collection_name": "study",
+    "embedding_model": "text-embedding-v4",
+    # ---- 召回 ----
+    "top_k": 5,
+    "recall_top_k": 20,
+    # ---- 检索前优化 ----
+    "pre_retrieval": {
+        "enabled": False,
+        "rewrite_query": False,
+        "hyde": False,
+        "model": "qwen-plus",
+    },
+    # ---- 混合召回 ----
+    "hybrid_retrieval": {
+        "enabled": True,
+        "weights": [0.5, 0.5],              # [向量权重, BM25 权重]
+    },
+    # ---- 检索后处理 ----
+    "post_retrieval": {
+        "enabled": True,
+        "deduplicate": True,
+        "rerank": False,
+        "rerank_model": "qwen3-rerank",
+        "similarity_filter": False,
+        "similarity_threshold": 0.4,
+        "compress_context": False,
+        "llm_model": "qwen-plus",
+        "reorder": False,
+    },
+})
+
+documents = rag.search("公司打卡时间？")
+for document in documents:
+    print(document.metadata["retrieval_rank"], document.metadata["context_position"])
+    print(document.page_content)
+    print("-" * 40)
+```
+
+带元数据过滤与临时 top_k：
+
+```python
+documents = rag.search(
+    "试用期规定",
+    top_k=8,
+    filters={"source": "员工手册.pdf"},          # 与 config["filters"] 以 $and 合并
+)
+```
+
+---
+
+## 配置项
+
+### 基础连接与召回
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `persist_directory` | `./chroma_db` | Chroma 目录，**相对当前工作目录**解析（支持 `~`） |
+| `collection_name` | `study` | 集合名 |
+| `embedding_model` | `text-embedding-v4` | DashScope Embedding 模型，必须与建库时一致 |
+| `top_k` | `5` | 最终返回条数 |
+| `recall_top_k` | `20` | 召回阶段条数；实际取 `max(recall_top_k, top_k)` |
+| `filters` | 无 | Chroma `where` 过滤条件，如 `{"source": "a.pdf"}` |
+
+### 检索前优化 `pre_retrieval`
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `False` | 总开关，关闭时下列子项**全部不生效** |
+| `rewrite_query` | `False` | 用 `qwen-plus` 把问题改写为独立查询，向量与 BM25 都用改写后结果 |
+| `hyde` | `False` | 用 `qwen-plus` 生成约 100 字假设答案，**仅替换向量检索的查询** |
+| `model` | `qwen-plus` | 改写 / HyDE 使用的 LLM |
+
+开启 `enabled` 后，`normalize_query`（合并多余空白）总是执行，没有单独开关。
+
+### 混合召回 `hybrid_retrieval`
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `False` | 开启后走 向量 + BM25 + RRF 融合；关闭则纯向量检索 |
+| `weights` | `[0.5, 0.5]` | `EnsembleRetriever` 权重，顺序为 `[向量, BM25]` |
+
+RRF 的 `c` 参数固定为 `60`（`rrf_fusion` 的 `rrf_k`）。
+
+### 检索后处理 `post_retrieval`
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `False` | 总开关，关闭时下列子项全部不生效 |
+| `deduplicate` | `True` | 按 `page_content` 去重 |
+| `rerank` | `False` | 调用 DashScope Rerank 重排 |
+| `rerank_model` | `qwen3-rerank` | 重排模型 |
+| `similarity_filter` | `False` | 按余弦相似度过滤 |
+| `similarity_threshold` | `0.4` | 相似度阈值，低于该值丢弃 |
+| `compress_context` | `False` | 用 `LLMChainExtractor` 抽取与问题相关的句子（表格类文档跳过） |
+| `llm_model` | `qwen-plus` | 压缩使用的 LLM |
+| `reorder` | `False` | `LongContextReorder`：把关键内容放到上下文首尾（"中间遗忘"缓解） |
+
+### 执行顺序（`search` 内部）
+
+1. 校验：问题非空、`top_k` 为正整数，否则抛 `ValueError`
+2. `count = max(recall_top_k, top_k)`
+3. 检索前：归一化 → 改写 →（可选）HyDE 生成 `dense_query`
+4. 过滤条件：`config["filters"]` 与 `search(filters=...)` 合并为 `$and`
+5. 召回：
+   - `hybrid.enabled`：`db.get(where=...)` 拉全集 → 建 `BM25Retriever`（jieba 分词）+ 向量检索器 → `EnsembleRetriever` RRF 融合
+   - 否则：`vector_search`
+6. 后处理（`post.enabled`）：去重 → 重排 `top_n=len(documents)` → 相似度过滤
+7. 截断到 `top_k`，写入 `metadata["retrieval_rank"]`（1 起）
+8. 后处理第二阶段：上下文压缩 → 重排顺序，写入 `metadata["context_position"]`
+
+---
+
+## API
+
+### `ModularRAG(config: dict)`
+
+连接知识库并初始化 Embedding 模型。`config` 中缺失的键一律走默认值。
+
+### `search(question: str, top_k: int | None = None, filters: dict | None = None) -> list[Document]`
+
+在线检索，返回按相关性排好序的 `Document` 列表。返回的 `metadata` 除知识库原始字段外，可能包含：
+
+| 字段 | 出现条件 | 含义 |
+| --- | --- | --- |
+| `chunk_id` | 纯向量检索分支 | 文档在 Chroma 中的 id |
+| `retrieval_rank` | 总是 | 截断后的最终名次（1 起） |
+| `context_position` | 总是 | 送入上下文时的位置（1 起） |
+| `cosine_similarity` | 开启 `similarity_filter` | 与问题的余弦相似度 |
+
+### 可独立复用的静态方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `normalize_query(question)` | 合并空白并去首尾空格 |
+| `rewrite_query(question, model)` | 改写为适合检索的独立查询 |
+| `generate_hyde(question, model)` | 生成假设性答案（约 100 字） |
+| `vector_search(question, db, top_k, filters)` | 稠密检索 |
+| `bm25_search(question, documents, top_k)` | 稀疏检索（需自行提供语料） |
+| `rrf_fusion(question, vector_retriever, bm25_retriever, weights, rrf_k)` | RRF 融合两路召回 |
+| `deduplicate(documents)` | 按内容去重 |
+| `rerank_documents(question, documents, top_k, model)` | DashScope 重排 |
+| `similarity_filter(question, documents, embeddings, threshold)` | 余弦相似度过滤 |
+| `compress_context(question, documents, model)` | LLM 抽取式压缩 |
+| `reorder_documents(documents)` | 长上下文重排（首尾优先） |
+
+### 异常
+
+| 场景 | 异常 |
+| --- | --- |
+| 目录下没有 `chroma.sqlite3` | `FileNotFoundError` |
+| 问题为空 / `top_k` 非正整数 | `ValueError` |
+| 集合名不存在 | `chromadb` 抛出的 `NotFoundError` 类异常 |
+| 未安装 `jieba` / `rank-bm25` 却开启混合检索 | `ImportError` |
+
+---
+
+## 已知限制与注意事项
+
+- **键名拼错不会报错**：全篇使用 `config.get(k, default)`，写错键名只会静默走默认值，排障时优先怀疑键名。
+- **总开关优先**：`pre_retrieval.enabled=False` / `post_retrieval.enabled=False` 时，其下所有子项（含默认为 `True` 的 `deduplicate`）一律不生效。
+- **路径与工作目录绑定**：`persist_directory` 相对当前工作目录解析，从不同目录启动会连到不同的库；工作区内根目录与 `day_1106/` 下各有一个 `chroma_db`。
+- **混合检索的开销**：每次查询都会 `db.get()` 全量拉取文档并重建 BM25 索引，数据量大时延迟明显，且不支持大数据集分页。
+- **重复的 Embedding 调用**：`similarity_filter` 会对每条候选文档重新调用 Embedding API（向量库里其实已存有向量），有额外耗时与费用。
+- **压缩逐条调用 LLM**：`compress_context` 对每个文档单独请求一次 `qwen-plus`，条数越多越慢。
+- **模型一致性**：`embedding_model` 必须与建库时相同，否则相似度与过滤结果都会失真。
+
+## 目录结构
+
+```
+project/
+├── demon_slaying_rag.py   # ModularRAG 类（单模块）
+├── pyproject.toml         # 打包与依赖声明
+└── README.md
+```
+
+## 打包与发布
+
+```bash
+pip install -e ".[publish]"
+python -m build
+twine check dist/*
+twine upload dist/*        # 需要 PyPI Token
+```

demon_slaying_rag-0.1.0/demon_slaying_rag.egg-info/PKG-INFO

@@ -0,0 +1,290 @@
+Metadata-Version: 2.4
+Name: demon-slaying-rag
+Version: 0.1.0
+Summary: A modular RAG retrieval class based on LangChain and Chroma
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: chromadb>=1.0
+Requires-Dist: langchain-chroma>=1.0
+Requires-Dist: langchain-core>=1.0
+Requires-Dist: langchain-community>=0.4
+Requires-Dist: langchain-openai>=1.0
+Requires-Dist: langchain-classic>=1.0
+Requires-Dist: dashscope>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: jieba>=0.42
+Requires-Dist: rank-bm25>=0.2
+Provides-Extra: publish
+Requires-Dist: build; extra == "publish"
+Requires-Dist: twine; extra == "publish"
+
+# demon-slaying-rag
+
+一个可配置的**模块化 RAG 检索器**：只负责"从已有 Chroma 知识库里把最相关的片段取回来"，不包含入库、切分与答案生成。
+
+核心是 `ModularRAG` 类，把早期脚本里散落的检索参数集中成一份 `config` 字典，并按三阶段流水线执行：
+
+```
+问题
+ │
+ ├─ 检索前优化  pre_retrieval   归一化 → (可选)查询改写 → (可选)HyDE 假设答案
+ │
+ ├─ 混合召回    hybrid_retrieval 纯向量检索 或 向量+BM25 经 RRF 融合
+ │
+ └─ 检索后处理  post_retrieval   去重 → (可选)重排 → (可选)相似度过滤
+                               → 截断 top_k → (可选)上下文压缩 → (可选)重排顺序
+ │
+返回 List[Document]（带 retrieval_rank / context_position 等元数据）
+```
+
+---
+
+## 环境要求
+
+- Python >= 3.11（已在 3.13 上验证）
+- 依赖（`pip install .` 会自动安装）：
+
+| 依赖 | 用途 |
+| --- | --- |
+| `chromadb` / `langchain-chroma` | 向量库连接（`Chroma`） |
+| `langchain-core` | `Document`、`RunnableLambda` |
+| `langchain-community` | `DashScopeEmbeddings`、`BM25Retriever`、`DashScopeRerank`、`LongContextReorder` |
+| `langchain-openai` | 通过 DashScope 兼容接口调用 `qwen-plus` 做改写 / HyDE / 压缩 |
+| `langchain-classic` | `EnsembleRetriever`（RRF 融合）、`LLMChainExtractor`（上下文压缩） |
+| `dashscope` | 通义 Embedding / Rerank 的 SDK |
+| `jieba` + `rank-bm25` | 混合检索的 BM25 分词与实现（仅混合检索需要） |
+| `python-dotenv` | 读取 `.env` 中的 `DASHSCOPE_API_KEY` |
+
+## 安装
+
+本项目未发布到 PyPI，使用本地安装：
+
+```bash
+# 可编辑安装（推荐本地开发）
+pip install -e .
+
+# 或普通安装
+pip install .
+
+# 额外安装打包发布工具
+pip install -e ".[publish]"
+```
+
+## 前置条件
+
+1. **知识库必须已存在**：`persist_directory` 指向的目录下必须有 `chroma.sqlite3`，否则构造函数直接抛 `FileNotFoundError`。
+2. **不会自动建集合**：内部使用 `create_collection_if_not_exists=False`，集合不存在时报错，而不是静默创建一个空库（避免"检索结果永远为空"的排查黑洞）。
+3. **API Key**：在项目根目录放一个 `.env`，或直接设置环境变量。
+
+```bash
+# Linux / macOS
+export DASHSCOPE_API_KEY="sk-xxxx"
+
+# Windows PowerShell
+setx DASHSCOPE_API_KEY "sk-xxxx"
+```
+
+```ini
+# .env
+DASHSCOPE_API_KEY=sk-xxxx
+```
+
+> 入库（切分 + 向量化 + 写 Chroma）不在本模块职责内，请用你已有的离线建库脚本生成知识库。
+
+---
+
+## 快速开始
+
+```python
+from demon_slaying_rag import ModularRAG
+
+rag = ModularRAG({
+    # ---- 基础连接 ----
+    "persist_directory": "./chroma_db",     # Chroma 目录（含 chroma.sqlite3）
+    "collection_name": "study",
+    "embedding_model": "text-embedding-v4",
+    # ---- 召回 ----
+    "top_k": 5,
+    "recall_top_k": 20,
+    # ---- 检索前优化 ----
+    "pre_retrieval": {
+        "enabled": False,
+        "rewrite_query": False,
+        "hyde": False,
+        "model": "qwen-plus",
+    },
+    # ---- 混合召回 ----
+    "hybrid_retrieval": {
+        "enabled": True,
+        "weights": [0.5, 0.5],              # [向量权重, BM25 权重]
+    },
+    # ---- 检索后处理 ----
+    "post_retrieval": {
+        "enabled": True,
+        "deduplicate": True,
+        "rerank": False,
+        "rerank_model": "qwen3-rerank",
+        "similarity_filter": False,
+        "similarity_threshold": 0.4,
+        "compress_context": False,
+        "llm_model": "qwen-plus",
+        "reorder": False,
+    },
+})
+
+documents = rag.search("公司打卡时间？")
+for document in documents:
+    print(document.metadata["retrieval_rank"], document.metadata["context_position"])
+    print(document.page_content)
+    print("-" * 40)
+```
+
+带元数据过滤与临时 top_k：
+
+```python
+documents = rag.search(
+    "试用期规定",
+    top_k=8,
+    filters={"source": "员工手册.pdf"},          # 与 config["filters"] 以 $and 合并
+)
+```
+
+---
+
+## 配置项
+
+### 基础连接与召回
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `persist_directory` | `./chroma_db` | Chroma 目录，**相对当前工作目录**解析（支持 `~`） |
+| `collection_name` | `study` | 集合名 |
+| `embedding_model` | `text-embedding-v4` | DashScope Embedding 模型，必须与建库时一致 |
+| `top_k` | `5` | 最终返回条数 |
+| `recall_top_k` | `20` | 召回阶段条数；实际取 `max(recall_top_k, top_k)` |
+| `filters` | 无 | Chroma `where` 过滤条件，如 `{"source": "a.pdf"}` |
+
+### 检索前优化 `pre_retrieval`
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `False` | 总开关，关闭时下列子项**全部不生效** |
+| `rewrite_query` | `False` | 用 `qwen-plus` 把问题改写为独立查询，向量与 BM25 都用改写后结果 |
+| `hyde` | `False` | 用 `qwen-plus` 生成约 100 字假设答案，**仅替换向量检索的查询** |
+| `model` | `qwen-plus` | 改写 / HyDE 使用的 LLM |
+
+开启 `enabled` 后，`normalize_query`（合并多余空白）总是执行，没有单独开关。
+
+### 混合召回 `hybrid_retrieval`
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `False` | 开启后走 向量 + BM25 + RRF 融合；关闭则纯向量检索 |
+| `weights` | `[0.5, 0.5]` | `EnsembleRetriever` 权重，顺序为 `[向量, BM25]` |
+
+RRF 的 `c` 参数固定为 `60`（`rrf_fusion` 的 `rrf_k`）。
+
+### 检索后处理 `post_retrieval`
+
+| 键 | 默认值 | 说明 |
+| --- | --- | --- |
+| `enabled` | `False` | 总开关，关闭时下列子项全部不生效 |
+| `deduplicate` | `True` | 按 `page_content` 去重 |
+| `rerank` | `False` | 调用 DashScope Rerank 重排 |
+| `rerank_model` | `qwen3-rerank` | 重排模型 |
+| `similarity_filter` | `False` | 按余弦相似度过滤 |
+| `similarity_threshold` | `0.4` | 相似度阈值，低于该值丢弃 |
+| `compress_context` | `False` | 用 `LLMChainExtractor` 抽取与问题相关的句子（表格类文档跳过） |
+| `llm_model` | `qwen-plus` | 压缩使用的 LLM |
+| `reorder` | `False` | `LongContextReorder`：把关键内容放到上下文首尾（"中间遗忘"缓解） |
+
+### 执行顺序（`search` 内部）
+
+1. 校验：问题非空、`top_k` 为正整数，否则抛 `ValueError`
+2. `count = max(recall_top_k, top_k)`
+3. 检索前：归一化 → 改写 →（可选）HyDE 生成 `dense_query`
+4. 过滤条件：`config["filters"]` 与 `search(filters=...)` 合并为 `$and`
+5. 召回：
+   - `hybrid.enabled`：`db.get(where=...)` 拉全集 → 建 `BM25Retriever`（jieba 分词）+ 向量检索器 → `EnsembleRetriever` RRF 融合
+   - 否则：`vector_search`
+6. 后处理（`post.enabled`）：去重 → 重排 `top_n=len(documents)` → 相似度过滤
+7. 截断到 `top_k`，写入 `metadata["retrieval_rank"]`（1 起）
+8. 后处理第二阶段：上下文压缩 → 重排顺序，写入 `metadata["context_position"]`
+
+---
+
+## API
+
+### `ModularRAG(config: dict)`
+
+连接知识库并初始化 Embedding 模型。`config` 中缺失的键一律走默认值。
+
+### `search(question: str, top_k: int | None = None, filters: dict | None = None) -> list[Document]`
+
+在线检索，返回按相关性排好序的 `Document` 列表。返回的 `metadata` 除知识库原始字段外，可能包含：
+
+| 字段 | 出现条件 | 含义 |
+| --- | --- | --- |
+| `chunk_id` | 纯向量检索分支 | 文档在 Chroma 中的 id |
+| `retrieval_rank` | 总是 | 截断后的最终名次（1 起） |
+| `context_position` | 总是 | 送入上下文时的位置（1 起） |
+| `cosine_similarity` | 开启 `similarity_filter` | 与问题的余弦相似度 |
+
+### 可独立复用的静态方法
+
+| 方法 | 说明 |
+| --- | --- |
+| `normalize_query(question)` | 合并空白并去首尾空格 |
+| `rewrite_query(question, model)` | 改写为适合检索的独立查询 |
+| `generate_hyde(question, model)` | 生成假设性答案（约 100 字） |
+| `vector_search(question, db, top_k, filters)` | 稠密检索 |
+| `bm25_search(question, documents, top_k)` | 稀疏检索（需自行提供语料） |
+| `rrf_fusion(question, vector_retriever, bm25_retriever, weights, rrf_k)` | RRF 融合两路召回 |
+| `deduplicate(documents)` | 按内容去重 |
+| `rerank_documents(question, documents, top_k, model)` | DashScope 重排 |
+| `similarity_filter(question, documents, embeddings, threshold)` | 余弦相似度过滤 |
+| `compress_context(question, documents, model)` | LLM 抽取式压缩 |
+| `reorder_documents(documents)` | 长上下文重排（首尾优先） |
+
+### 异常
+
+| 场景 | 异常 |
+| --- | --- |
+| 目录下没有 `chroma.sqlite3` | `FileNotFoundError` |
+| 问题为空 / `top_k` 非正整数 | `ValueError` |
+| 集合名不存在 | `chromadb` 抛出的 `NotFoundError` 类异常 |
+| 未安装 `jieba` / `rank-bm25` 却开启混合检索 | `ImportError` |
+
+---
+
+## 已知限制与注意事项
+
+- **键名拼错不会报错**：全篇使用 `config.get(k, default)`，写错键名只会静默走默认值，排障时优先怀疑键名。
+- **总开关优先**：`pre_retrieval.enabled=False` / `post_retrieval.enabled=False` 时，其下所有子项（含默认为 `True` 的 `deduplicate`）一律不生效。
+- **路径与工作目录绑定**：`persist_directory` 相对当前工作目录解析，从不同目录启动会连到不同的库；工作区内根目录与 `day_1106/` 下各有一个 `chroma_db`。
+- **混合检索的开销**：每次查询都会 `db.get()` 全量拉取文档并重建 BM25 索引，数据量大时延迟明显，且不支持大数据集分页。
+- **重复的 Embedding 调用**：`similarity_filter` 会对每条候选文档重新调用 Embedding API（向量库里其实已存有向量），有额外耗时与费用。
+- **压缩逐条调用 LLM**：`compress_context` 对每个文档单独请求一次 `qwen-plus`，条数越多越慢。
+- **模型一致性**：`embedding_model` 必须与建库时相同，否则相似度与过滤结果都会失真。
+
+## 目录结构
+
+```
+project/
+├── demon_slaying_rag.py   # ModularRAG 类（单模块）
+├── pyproject.toml         # 打包与依赖声明
+└── README.md
+```
+
+## 打包与发布
+
+```bash
+pip install -e ".[publish]"
+python -m build
+twine check dist/*
+twine upload dist/*        # 需要 PyPI Token
+```

demon_slaying_rag-0.1.0/demon_slaying_rag.egg-info/SOURCES.txt

@@ -0,0 +1,8 @@
+README.md
+demon_slaying_rag.py
+pyproject.toml
+demon_slaying_rag.egg-info/PKG-INFO
+demon_slaying_rag.egg-info/SOURCES.txt
+demon_slaying_rag.egg-info/dependency_links.txt
+demon_slaying_rag.egg-info/requires.txt
+demon_slaying_rag.egg-info/top_level.txt

demon_slaying_rag-0.1.0/demon_slaying_rag.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

demon_slaying_rag-0.1.0/demon_slaying_rag.egg-info/requires.txt

@@ -0,0 +1,14 @@
+chromadb>=1.0
+langchain-chroma>=1.0
+langchain-core>=1.0
+langchain-community>=0.4
+langchain-openai>=1.0
+langchain-classic>=1.0
+dashscope>=2.0
+python-dotenv>=1.0
+jieba>=0.42
+rank-bm25>=0.2
+
+[publish]
+build
+twine

demon_slaying_rag-0.1.0/demon_slaying_rag.egg-info/top_level.txt

@@ -0,0 +1 @@
+demon_slaying_rag

demon_slaying_rag-0.1.0/demon_slaying_rag.py

@@ -0,0 +1,301 @@
+class ModularRAG:
+    def __init__(self, config: dict):
+        import os
+        from pathlib import Path
+        from dotenv import load_dotenv
+        from langchain_chroma import Chroma
+        from langchain_community.embeddings import DashScopeEmbeddings
+
+        load_dotenv()
+        self.config = config  # 配置参数(后续写)
+        directory = config.get("persist_directory", "./chroma_db")  # 知识库目录
+        if not (Path(directory).expanduser() / "chroma.sqlite3").is_file():  # 知识库文件是否存在
+            raise FileNotFoundError(f"知识库不存在：{directory}")
+            
+        self.embeddings = DashScopeEmbeddings(  # 初始化嵌入模型
+            model=config.get("embedding_model", "text-embedding-v4"),
+            dashscope_api_key=os.getenv("DASHSCOPE_API_KEY"),
+        )
+        
+        self.db = Chroma(  # 初始化数据库
+            collection_name=config.get("collection_name", "study"),
+            persist_directory=str(Path(directory).expanduser()),
+            embedding_function=self.embeddings,
+            create_collection_if_not_exists=False,
+        )
+
+    def search(self, question: str, top_k=None, filters=None):  # 搜索
+        from langchain_core.documents import Document
+
+        if not question.strip():  # 问题不能为空
+            raise ValueError("问题不能为空")
+        limit = self.config.get("top_k", 5) if top_k is None else top_k  # top_k参数
+        if not isinstance(limit, int) or limit <= 0:  # top_k 必须是正整数
+            raise ValueError("top_k 必须是正整数")
+        count = max(self.config.get("recall_top_k", 20), limit)  # 回忆top_k参数
+        pre = self.config.get("pre_retrieval", {})  # 预检索参数
+        hybrid = self.config.get("hybrid_retrieval", {})  # 混合检索参数
+        post = self.config.get("post_retrieval", {})  # 后检索参数
+
+        query = question
+        if pre.get("enabled", False):  # 预检索是否启用
+            query = self.normalize_query(query)
+            if pre.get("rewrite_query", False):
+                query = self.rewrite_query(query, model=pre.get("model", "qwen-plus"))
+        keyword_query = query
+        dense_query = query
+        if pre.get("enabled", False) and pre.get("hyde", False):  # 预检索是否启用且使用HYDE
+            dense_query = self.generate_hyde(query, model=pre.get("model", "qwen-plus"))
+
+        conditions = []
+        for condition in (self.config.get("filters"), filters):  # 过滤条件
+            if condition:  # 过滤条件
+                conditions.extend({key: value} for key, value in condition.items())  # 过滤条件添加
+        where = None  # 过滤条件 
+        if len(conditions) == 1:  # 过滤条件
+            where = conditions[0]  # 过滤条件
+        elif len(conditions) > 1:  # 过滤条件
+            where = {"$and": conditions}  # 过滤条件
+
+        if hybrid.get("enabled", False):  # 混合检索是否启用
+            import jieba
+            from langchain_community.retrievers import BM25Retriever
+            from langchain_core.runnables import RunnableLambda
+
+            stored = self.db.get(where=where, include=["documents", "metadatas"])  # 获取数据
+            corpus = []
+            for index, text in enumerate(stored["documents"] or []):  # 文档遍历
+                corpus.append(Document(
+                    id=stored["ids"][index],  # ID
+                    page_content=text,  # 文本内容
+                    metadata=stored["metadatas"][index] or {},  # 元数据
+                ))
+            if not corpus:  # 知识库为空
+                return []
+            vector_retriever = self.db.as_retriever(  # 向量检索器
+                search_type="similarity",
+                search_kwargs={"k": count, "filter": where},  # 搜索参数
+            )
+            if dense_query != keyword_query:
+                vector_retriever = (
+                    RunnableLambda(lambda incoming_query: dense_query) | vector_retriever
+                )
+            bm25_retriever = BM25Retriever.from_documents(  # BM25检索器
+                corpus,
+                preprocess_func=lambda text: list(jieba.cut(text)),  # 预处理函数
+                k=count,  # top_k参数
+            )
+            documents = self.rrf_fusion(  # RRF融合
+                keyword_query, vector_retriever, bm25_retriever,
+                weights=hybrid.get("weights", [0.5, 0.5]),
+            )
+        else:
+            documents = self.vector_search(dense_query, self.db, count, where)  # 向量检索
+
+        if post.get("enabled", False):  # 后检索是否启用
+            if post.get("deduplicate", True):  # 去重是否启用
+                documents = self.deduplicate(documents)
+            if post.get("rerank", False):  # 重排序是否启用     
+                documents = self.rerank_documents(
+                    question, documents, top_k=len(documents),
+                    model=post.get("rerank_model", "qwen3-rerank"),
+                )
+            if post.get("similarity_filter", False):  # 相似度过滤是否启用
+                documents = self.similarity_filter(
+                    question, documents, self.embeddings,
+                    threshold=post.get("similarity_threshold", 0.4),
+                )
+
+        documents = documents[:limit]
+        for rank, document in enumerate(documents, start=1):
+            document.metadata["retrieval_rank"] = rank
+
+        if post.get("enabled", False):  # 后检索是否启用
+            if post.get("compress_context", False):  # 上下文压缩是否启用
+                documents = self.compress_context(
+                    question, documents, model=post.get("llm_model", "qwen-plus")
+                )
+            if post.get("reorder", False):  # 重排序是否启用
+                documents = self.reorder_documents(documents)
+        for position, document in enumerate(documents, start=1):
+            document.metadata["context_position"] = position
+        return documents
+        
+    @staticmethod
+    # ==================== 1. 归一化查询词：移除所有空格并首尾去空格 ====================  # 归一化查询词
+    def normalize_query(question: str):
+        import re
+        return re.sub(r"\s+", " ", question).strip() # 移除所有空格并首尾去空格
+
+    @staticmethod
+    # ==================== 2. 改写查询词：根据模型提示改写为适合知识库检索的独立查询 ====================  # 改写查询词
+    def rewrite_query(question: str, model="qwen-plus"):
+        import os
+        from dotenv import load_dotenv
+        from langchain_openai import ChatOpenAI
+
+        load_dotenv()
+        llm = ChatOpenAI(
+            model=model,
+            api_key=os.getenv("DASHSCOPE_API_KEY"),
+            base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+            temperature=0,
+        )
+        response = llm.invoke([
+            ("system", "把问题改写为适合知识库检索的独立查询。保留原意，不编造缺失上下文，只输出查询。"),
+            ("human", question),
+        ])
+        return response.content.strip()
+
+    @staticmethod
+    # ==================== 3. 生成假设性答案：根据模型提示生成约100字的假设性答案 ====================  # 生成假设性答案
+    def generate_hyde(question: str, model="qwen-plus"):
+        import os
+        from dotenv import load_dotenv
+        from langchain_openai import ChatOpenAI
+
+        load_dotenv()
+        llm = ChatOpenAI(
+            model=model,
+            api_key=os.getenv("DASHSCOPE_API_KEY"),
+            base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+            temperature=0,
+        )
+        response = llm.invoke([
+            ("system", "为问题生成约100字的假设性答案，用于语义检索。只输出假设答案，不将其视为事实证据。"),
+            ("human", question),
+        ])
+        return response.content.strip()
+
+    @staticmethod
+    # ==================== 4. 稠密：向量检索召回文档 ====================  # 稠密检索
+    def vector_search(question: str, db, top_k=5, filters=None):
+        retriever = db.as_retriever(
+            search_type="similarity",
+            search_kwargs={"k": top_k, "filter": filters},
+        )
+        documents = retriever.invoke(question)
+        for document in documents:
+            document.metadata["chunk_id"] = document.id
+        return documents
+
+    @staticmethod
+    # ==================== 5. 稀疏：BM25检索召回文档 ====================  # 稀疏检索
+    def bm25_search(question: str, documents, top_k=5):
+        import jieba
+        from langchain_community.retrievers import BM25Retriever
+
+        if not documents:
+            return []
+        bm25_retriever = BM25Retriever.from_documents(
+            documents,
+            preprocess_func=lambda text: list(jieba.cut(text)),
+            k=top_k,
+        )
+        return bm25_retriever.invoke(question)
+
+    @staticmethod
+    # ==================== 6. RRF融合召回文档 ====================  # RRF融合
+    def rrf_fusion(question: str, vector_retriever, bm25_retriever, weights=None, rrf_k=60):
+        from langchain_classic.retrievers import EnsembleRetriever
+
+        retriever = EnsembleRetriever(
+            retrievers=[vector_retriever, bm25_retriever],
+            weights=weights or [0.5, 0.5],
+            c=rrf_k,
+        )
+        return retriever.invoke(question)
+
+    @staticmethod
+    # ==================== 7. 去重：根据文档内容去重 ====================  # 去重
+    def deduplicate(documents):
+        seen = set()
+        results = []
+        for document in documents:
+            if document.page_content not in seen:
+                seen.add(document.page_content)
+                results.append(document)
+        return results
+
+    from langchain_core.documents import Document
+
+    @staticmethod
+    # ==================== 8. 重排：根据模型提示重排召回文档 ====================  # 重排
+    def rerank_documents(question: str, documents, top_k=5, model="qwen3-rerank"):
+        import os
+        from dotenv import load_dotenv
+        from langchain_community.document_compressors import DashScopeRerank
+
+        if not documents:
+            return []
+        load_dotenv()
+        reranker = DashScopeRerank(
+            model=model,
+            dashscope_api_key=os.getenv("DASHSCOPE_API_KEY"),
+            top_n=top_k,
+        )
+        return list(reranker.compress_documents(documents, question))
+
+    @staticmethod
+    # ==================== 9. 筛选：根据文档相似度筛选出相关文档 ====================  # 筛选
+    def similarity_filter(question: str, documents, embeddings, threshold=0.4):
+        import math
+
+        if not documents:
+            return []
+        query_vector = embeddings.embed_query(question)
+        vectors = embeddings.embed_documents([
+            document.page_content for document in documents
+        ])
+        query_norm = math.sqrt(sum(value * value for value in query_vector))
+
+        results = []
+        for document, vector in zip(documents, vectors):
+            vector_norm = math.sqrt(sum(value * value for value in vector))
+            if query_norm == 0 or vector_norm == 0:
+                continue
+            similarity = sum(
+                query_value * value for query_value, value in zip(query_vector, vector)
+            ) / (query_norm * vector_norm)
+            if similarity >= threshold:
+                result = document.model_copy(deep=True)
+                result.metadata["cosine_similarity"] = similarity
+                results.append(result)
+        return results
+
+    @staticmethod
+    # ==================== 10. 压缩：根据模型提示压缩文档上下文 ====================  # 压缩
+    def compress_context(question: str, documents, model="qwen-plus"):
+        import os
+        from dotenv import load_dotenv
+        from langchain_openai import ChatOpenAI
+        from langchain_classic.retrievers.document_compressors import LLMChainExtractor
+
+        if not documents:
+            return []
+        load_dotenv()
+        llm = ChatOpenAI(
+            model=model,
+            api_key=os.getenv("DASHSCOPE_API_KEY"),
+            base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+            temperature=0,
+        )
+        compressor = LLMChainExtractor.from_llm(llm)
+        results = []
+        for document in documents:
+            is_table = (
+                document.metadata.get("content_type") == "table"
+                or "<table" in document.page_content.lower()
+            )
+            if is_table:
+                results.append(document)
+            else:
+                results.extend(compressor.compress_documents([document], question))
+        return results
+
+    @staticmethod
+    # ==================== 11. 重排：根据模型提示重排文档顺序 ====================  # 重排 
+    def reorder_documents(documents):
+        from langchain_community.document_transformers import LongContextReorder
+
+        return list(LongContextReorder().transform_documents(documents))

demon_slaying_rag-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "demon-slaying-rag"
+version = "0.1.0"
+description = "A modular RAG retrieval class based on LangChain and Chroma"
+readme = { file = "README.md", content-type = "text/markdown" }
+requires-python = ">=3.11"
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "chromadb>=1.0",
+    "langchain-chroma>=1.0",
+    "langchain-core>=1.0",
+    "langchain-community>=0.4",
+    "langchain-openai>=1.0",
+    "langchain-classic>=1.0",
+    "dashscope>=2.0",
+    "python-dotenv>=1.0",
+    "jieba>=0.42",
+    "rank-bm25>=0.2",
+]
+
+[project.optional-dependencies]
+publish = ["build", "twine"]
+
+[tool.setuptools]
+py-modules = ["demon_slaying_rag"]

demon_slaying_rag-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+