# rag-retrieval - Doramagic AI Context Pack > 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。 ## 充分原则 - **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。 - **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。 ## 给宿主 AI 的使用方式 你正在读取 Doramagic 为 rag-retrieval 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。 ## Claim 消费规则 - **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。 - **事实最低状态**：`supported` - `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。 - `weak`：只能作为低置信度线索，必须要求用户继续核实。 - `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。 - `unverified`：不得作为事实使用，应明确说证据不足。 - `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。 ## 它最适合谁 - **想在安装前理解开源项目价值和边界的用户**：当前证据主要来自项目文档。 证据：`README.md` Claim：`clm_0002` supported 0.86 ## 它能做什么 - **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0001` supported 0.86 ## 怎么开始 - `pip install -r requirements.txt` 证据：`README.md` Claim：`clm_0003` supported 0.86 - `pip install rag-retrieval` 证据：`README.md` Claim：`clm_0004` supported 0.86 ## 继续前判断卡 - **当前建议**：仅建议沙盒试装 - **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。 ### 30 秒判断 - **现在怎么做**：仅建议沙盒试装 - **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装 - **先别相信**：真实输出质量不能在安装前相信。 - **继续会触碰**：命令执行、本地环境或项目文件、宿主 AI 上下文 ### 现在可以相信 - **适合人群线索：想在安装前理解开源项目价值和边界的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0002` supported 0.86 - **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86 - **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0003` supported 0.86 ### 现在还不能相信 - **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。 - **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。 - **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 - **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。 - **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 - **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。 - **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md` ### 继续会触碰什么 - **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md` - **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md` - **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。 ### 最小安全下一步 - **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。） - **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。） - **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。） ### 退出方式 - **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。 - **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。 - **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。 ## 哪些只能预览 - 解释项目适合谁和能做什么 - 基于项目文档演示典型对话流程 - 帮助用户判断是否值得安装或继续研究 ## 哪些必须安装后验证 - 真实安装 Skill、插件或 CLI - 执行脚本、修改本地文件或访问外部服务 - 验证真实输出质量、性能和兼容性 ## 边界与风险判断卡 - **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0005` inferred 0.45 - **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0006` supported 0.86 - **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。 - **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。 - **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。 ## 开工前工作上下文 ### 加载顺序 - 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。 - 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。 - 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。 - 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。 - 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。 ### 任务路由 - **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0001` supported 0.86 ### 上下文规模 - 文件总数：77 - 重要文件覆盖：40/77 - 证据索引条目：46 - 角色 / Skill 条目：12 ### 证据不足时的处理 - **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。 - **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。 - **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。 - **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。 ## Prompt Recipes ### 适配判断 - 目标：判断这个项目是否适合用户当前任务。 - 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。 ```text 请基于 rag-retrieval 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。 ``` ### 安装前体验 - 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。 - 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。 ```text 请把 rag-retrieval 当作安装前体验资产，而不是已安装工具或真实运行环境。 请严格输出四段： 1. 先问我 3 个必要问题。 2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。 3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。 4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。 硬性边界： - 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。 - 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。 - 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。 - 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。 - Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。 - 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。 ``` ### 角色 / Skill 选择 - 目标：从项目里的角色或 Skill 中挑选最匹配的资产。 - 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。 ```text 请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。 ``` ### 风险预检 - 目标：安装或引入前识别环境、权限、规则冲突和质量风险。 - 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。 ```text 请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。 ``` ### 宿主 AI 开工指令 - 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。 - 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。 ```text 请基于 rag-retrieval 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。 ``` ## 角色 / Skill 索引 - 共索引 12 个角色 / Skill / 项目文档条目。 - **Communication between communities**（project_doc）：English ./README.md 中文 ./README zh.md 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README.md` - **Myopic Trap: Positional Bias in Information Retrieval**（project_doc）：Myopic Trap: Positional Bias in Information Retrieval 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/MyopicTrap/README.md` - **通过下面的命令，将train data path的query和pos和neg中的doc，两两组成pair，得到训练好的llm模型 ckpt path 预测标签为1的score，再输出到distill train data path中。**（project_doc）：通过下面的命令，将train data path的query和pos和neg中的doc，两两组成pair，得到训练好的llm模型 ckpt path 预测标签为1的score，再输出到distill train data path中。 bash 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/distill_llm_to_bert_reranker/README.md` - **Create distill data**（project_doc）：Create distill data Refer to create distill data.sh to extract the embeddings of teacher1 and teacher2 in turn. 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/stella_embedding_distill/README.md` - **利用LLM合成训练数据**（project_doc）：我们结合一个RAG的评估工具 FlashRAG https://github.com/RUC-NLPIR/FlashRAG 进行实现和测试。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/synthetic_data_embedding/README.md` - **安装环境**（project_doc）：微调模型 在安装好依赖后，我们通过具体的示例来展示如何利用我们自己的数据来微调开源的colbert模型。 bge-m3-colbert ,或者你可以从BERT类模型 chinese-roberta-wwm-ext 开始从零训练自己的colbert模型。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`rag_retrieval/train/colbert/README.md` - **Setting Up the Environment**（project_doc）：English ./README.md 中文 ./README zh.md Setting Up the Environment 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`rag_retrieval/train/embedding/README.md` - **Environment Setup**（project_doc）：English 中文 README zh.md Environment Setup 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`rag_retrieval/train/reranker/README.md` - **社区交流**（project_doc）：RAG-Retrieval 提供了全链路的RAG检索模型微调 train 和推理 infer 以及蒸馏 distill 代码。 - 对于微调， 支持微调任意开源的RAG检索模型 ，包括向量模型（图a,bert-based,llm-based embedding）、迟交互式模型（图d,colbert）、重排序模型（图c,bert-based, llm-based reranker）。 - 对于推理，RAG-Retrieval专注于重排序 reranker ，开发了一个轻量级的python库 rag-retrieval https://pypi.org/project/rag-retrieval/ , 提供统一的方式调用任意不同的RAG排序模型 。 - 对于蒸馏， 支持向量模型和排序模型的蒸馏 ，可以从较大的模型蒸馏到较小的模型（0.5b llm or bert-base 中。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`README_zh.md` - **安装环境**（project_doc）：微调模型 在安装好依赖后，我们通过具体的示例来展示如何利用我们自己的数据来微调开源的向量模型。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`rag_retrieval/train/embedding/README_zh.md` - **安装环境**（project_doc）：在安装好依赖后，我们通过具体的示例来展示如何利用我们自己的数据来微调开源的排序模型 BAAI/bge-reranker-v2-m3 ，或者从 BERT 类模型 hfl/chinese-roberta-wwm-ext 以及 LLM 类模型 Qwen/Qwen2.5-1.5B 从零开始训练排序模型。与此同时，我们也支持将 LLM 类模型的排序能力蒸馏到较小的 BERT 模型中去。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`rag_retrieval/train/reranker/README_zh.md` - **安装**（project_doc）：欢迎使用rag retrieval库的Reranker模块，这里是一份Reranker的Tutorial,主要来介绍下Reranker的功能以及注意事项，希望您可以使用的更加得心应手。 激活提示：当用户需要理解项目结构、安装方式或边界时参考。 证据：`examples/Reranker_Tutorial.md` ## 证据索引 - 共索引 46 条证据。 - **Communication between communities**（documentation）：English ./README.md 中文 ./README zh.md 证据：`README.md` - **Myopic Trap: Positional Bias in Information Retrieval**（documentation）：Myopic Trap: Positional Bias in Information Retrieval 证据：`examples/MyopicTrap/README.md` - **通过下面的命令，将train data path的query和pos和neg中的doc，两两组成pair，得到训练好的llm模型 ckpt path 预测标签为1的score，再输出到distill train data path中。**（documentation）：通过下面的命令，将train data path的query和pos和neg中的doc，两两组成pair，得到训练好的llm模型 ckpt path 预测标签为1的score，再输出到distill train data path中。 bash 证据：`examples/distill_llm_to_bert_reranker/README.md` - **Create distill data**（documentation）：Create distill data Refer to create distill data.sh to extract the embeddings of teacher1 and teacher2 in turn. 证据：`examples/stella_embedding_distill/README.md` - **利用LLM合成训练数据**（documentation）：我们结合一个RAG的评估工具 FlashRAG https://github.com/RUC-NLPIR/FlashRAG 进行实现和测试。 证据：`examples/synthetic_data_embedding/README.md` - **安装环境**（documentation）：微调模型 在安装好依赖后，我们通过具体的示例来展示如何利用我们自己的数据来微调开源的colbert模型。 bge-m3-colbert ,或者你可以从BERT类模型 chinese-roberta-wwm-ext 开始从零训练自己的colbert模型。 证据：`rag_retrieval/train/colbert/README.md` - **Setting Up the Environment**（documentation）：English ./README.md 中文 ./README zh.md Setting Up the Environment 证据：`rag_retrieval/train/embedding/README.md` - **Environment Setup**（documentation）：English 中文 README zh.md Environment Setup 证据：`rag_retrieval/train/reranker/README.md` - **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the "Software" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE` - **社区交流**（documentation）：RAG-Retrieval 提供了全链路的RAG检索模型微调 train 和推理 infer 以及蒸馏 distill 代码。 - 对于微调， 支持微调任意开源的RAG检索模型 ，包括向量模型（图a,bert-based,llm-based embedding）、迟交互式模型（图d,colbert）、重排序模型（图c,bert-based, llm-based reranker）。 - 对于推理，RAG-Retrieval专注于重排序 reranker ，开发了一个轻量级的python库 rag-retrieval https://pypi.org/project/rag-retrieval/ , 提供统一的方式调用任意不同的RAG排序模型 。 - 对于蒸馏， 支持向量模型和排序模型的蒸馏 ，可以从较大的模型蒸馏到较小的模型（0.5b llm or bert-base 中。 证据：`README_zh.md` - **安装环境**（documentation）：微调模型 在安装好依赖后，我们通过具体的示例来展示如何利用我们自己的数据来微调开源的向量模型。 证据：`rag_retrieval/train/embedding/README_zh.md` - **安装环境**（documentation）：在安装好依赖后，我们通过具体的示例来展示如何利用我们自己的数据来微调开源的排序模型 BAAI/bge-reranker-v2-m3 ，或者从 BERT 类模型 hfl/chinese-roberta-wwm-ext 以及 LLM 类模型 Qwen/Qwen2.5-1.5B 从零开始训练排序模型。与此同时，我们也支持将 LLM 类模型的排序能力蒸馏到较小的 BERT 模型中去。 证据：`rag_retrieval/train/reranker/README_zh.md` - **Specify the Python versions you support here. In particular, ensure**（source_file）：build-system requires = "setuptools" build-backend = "setuptools.build meta" 证据：`pyproject.toml` - **Init**（source_file）：all = "Reranker" 证据：`rag_retrieval/__init__.py` - **Reranker**（source_file）：DEFAULTS MODEL CLASS TYPE={ ⋮---- DEFAULTS MODEL TYPE={ ⋮---- DEPS MAPPING = { ⋮---- model type to class = { ⋮---- model name = model name.lower model name to class={ ⋮---- model class type = get model type model name,model type ⋮---- model class type = "CorssEncoderRanker" 证据：`rag_retrieval/reranker.py` - **Requirements**（source_file）：accelerate transformers torch =2.1.0 tqdm sentence transformers 证据：`requirements.txt` - **Create Distill Data**（source_file）：def get train data train data path ⋮---- train data = ⋮---- data dic=json.loads line.strip ⋮---- input train data path = sys.argv 1 ckpt path = sys.argv 2 distill train data path = sys.argv 3 ⋮---- train data = get train data input train data path ⋮---- llm reranker = LLMGenerateDecoder.from pretrained ckpt path ⋮---- res score = llm reranker.compute score train data ⋮---- query = data 0 passage = data 1 dic = {} 证据：`examples/distill_llm_to_bert_reranker/create_distill_data.py` - **Concate Two Teacher Embedding**（source_file）：teacher1 distill train data path = sys.argv 1 teacher2 distill train data path = sys.argv 2 train data nums = sys.argv 3 teacher1 dims = sys.argv 4 teacher2 dims = sys.argv 5 two teacher distill train data path = sys.argv 6 ⋮---- train data nums = int train data nums teacher1 dims= int teacher1 dims teacher2 dims = int teacher2 dims ⋮---- teacher1 mmap array = np.memmap teacher1 distill train data path, dtype='float32', mode='r', shape= train data nums, teacher1 dims teacher2 mmap array = np.memmap teacher2 distill train data path, dtype='float32', mode='r', shape= train data nums, teacher2 dims ⋮---- two teacher mmap array = np.memmap two teacher distill train data path, dtype='float32', m… 证据：`examples/stella_embedding_distill/concate_two_teacher_embedding.py` - **Concate Two Teacher Embedding**（source_file）：train data nums=2087 teacher1 dims=1792 teacher2 dims=1792 teacher1 distill path="../../example data/t2rank 100.embedding.xiaobu-embedding-v2.mmap" teacher2 distill path="../../example data/t2rank 100.embedding.conan-embedding-v1.mmap" two teacher distill path="../../example data/t2rank 100.embedding.conan.xiaobu.mmap" python concate two teacher embedding.py \ $teacher1 distill path \ $teacher2 distill path \ $train data nums \ $teacher1 dims \ $teacher2 dims \ $two teacher distill path 证据：`examples/stella_embedding_distill/concate_two_teacher_embedding.sh` - **Create Distill Data**（source_file）：def get train data train data path ⋮---- train data = train data text = dic = set ⋮---- data dic=json.loads line.strip query = data dic 'query' ⋮---- input train data path = sys.argv 1 ckpt path = sys.argv 2 distill train data path = sys.argv 3 save text = sys.argv 4 ⋮---- embedding model = SentenceTransformer ⋮---- multi process pool = embedding model.start multi process pool ⋮---- train data embedding dim = embedding model.get sentence embedding dimension ⋮---- mmap array = np.memmap distill train data path, dtype='float32', mode='w+', shape= len train data ,train data embedding dim ⋮---- f w = open input train data path+'.text.jsonl','w' ⋮---- batch size=100000 ⋮---- batch train data = t… 证据：`examples/stella_embedding_distill/create_distill_data.py` - **Create Distill Data**（source_file）：train data path="../../example data/t2rank 100.jsonl" ckpt path="lier007/xiaobu-embedding-v2" teacher1 distill path="../../example data/t2rank 100.embedding.xiaobu-embedding-v2.mmap" save text=1 CUDA VISIBLE DEVICES="7" nohup python create distill data.py $train data path $ckpt path $teacher1 distill path $save text ./distill xiaobu.log & train data path="../../example data/t2rank 100.jsonl" ckpt path="TencentBAC/Conan-embedding-v1" teacher2 distill path="../../example data/t2rank 100.embedding.conan-embedding-v1.mmap" save text=0 CUDA VISIBLE DEVICES="7" nohup python create distill data.py $train data path $ckpt path $teacher2 distill path $save text ./distill Conan-embedding-v1.log & 证据：`examples/stella_embedding_distill/create_distill_data.sh` - **Init**（source_file）：AVAILABLE RANKERS = {} 证据：`rag_retrieval/infer/reranker_models/__init__.py` - **if device is not None and device.startswith 'cuda:' :**（source_file）：class CorssEncoderRanker BaseRanker ⋮---- if device is not None and device.startswith 'cuda:' : self.num gpus = torch.cuda.device count if self.num gpus 1: vprint f"----------using {self.num gpus} GPUs----------",self.verbose self.model = torch.nn.DataParallel self.model else: self.num gpus = 1 ⋮---- batch inference if self.num gpus 1: batch size = batch size self.num gpus ⋮---- all scores = ⋮---- sentences batch = sentence pairs start index:start index + batch size inputs = self.tokenizer ⋮---- scores = self.model inputs .logits.view -1, .float ⋮---- scores = torch.sigmoid scores ⋮---- docs = doc :128000 for doc in docs if isinstance doc, str and 0 < len doc ⋮---- doc ids = list range len… 证据：`rag_retrieval/infer/reranker_models/cross_encoder_ranker.py` - **Llm Rankers**（source_file）：def sigmoid x ⋮---- class LLMRanker BaseRanker ⋮---- model dtype = next self.model.parameters .dtype ⋮---- all scores = ⋮---- sentences batch = sentence pairs start index:start index + batch size inputs = self.get inputs sentences batch,prompt,max length inputs = inputs.to self.device ⋮---- logits = self.model inputs,return dict=True,cutoff layers=cutoff layers .logits ⋮---- scores = logits 0 :,-1 .cpu .float .tolist ⋮---- logits = self.model inputs,return dict=True .logits ⋮---- scores = logits :, -1, self.yes loc .view -1, .cpu .float .tolist ⋮---- all scores = sigmoid score for score in all scores ⋮---- docs = doc :128000 for doc in docs if isinstance doc, str and 0 < len doc ⋮---- doc i… 证据：`rag_retrieval/infer/reranker_models/llm_rankers.py` - **Ranker**（source_file）：class BaseRanker ABC 证据：`rag_retrieval/infer/reranker_models/ranker.py` - **Data**（source_file）：class ColBERTDTripletataset Dataset ⋮---- def read train data self,train data path ⋮---- train data = ⋮---- data dic=json.loads line.strip ⋮---- temp dic = {} ⋮---- num = math.ceil self.neg nums / len data dic 'neg' ⋮---- def len self ⋮---- def getitem self,idx ⋮---- def collate fn self,batch ⋮---- all querys = all pos docs = all neg docs = ⋮---- all query tokens = self.tokenizer all querys,padding='max length',truncation=True, ⋮---- all pos doc tokens = self.tokenizer all pos docs,padding='max length',truncation=True, ⋮---- all neg doc tokens = self.tokenizer all neg docs,padding='max length',truncation=True, ⋮---- toekns batch={} ⋮---- def test ColBERTDTripletataset ⋮---- train data path=… 证据：`rag_retrieval/train/colbert/data.py` - **Model**（source_file）：class ColBERT nn.Module ⋮---- mask symbol list = self.tokenizer.pad token id,self.tokenizer.cls token id ⋮---- def get embedding self,input ids,attention mask ⋮---- embedding = self.model embedding = self.linear embedding :,1: ⋮---- puntuation padding mask = self.punctuation padding mask input ids ⋮---- embedding = embedding puntuation padding mask :,1: .unsqueeze -1 embedding = F.normalize embedding,p=2,dim=-1 ⋮---- def punctuation padding mask self,input ids ⋮---- mask = input ids.unsqueeze -1 == self.mask buffer .any dim=-1 mask = ~mask .float ⋮---- def score self,query embedding,doc embedding,query attention mask ⋮---- token score = query embedding @ doc embedding.transpose -1,-2 score… 证据：`rag_retrieval/train/colbert/model.py` - **accelerator.wait for everyone**（source_file）：parameters = list model.named parameters optimizer grouped parameters = optimizer = torch.optim.AdamW optimizer grouped parameters, lr=lr ⋮---- def parse args ⋮---- parser = argparse.ArgumentParser ⋮---- args = parser.parse args ⋮---- def main ⋮---- args = parse args ⋮---- project config = ProjectConfiguration ⋮---- accelerator = Accelerator ⋮---- model = ColBERT.from pretrained ⋮---- model = accelerator.prepare model ⋮---- tokenizer = AutoTokenizer.from pretrained args.model name or path ⋮---- train datast = ColBERTDTripletataset num workers=0 train dataloader = DataLoader ⋮---- optimizer = create adamw optimizer ⋮---- total steps = lr scheduler = get cosine schedule with warmup ⋮---- trai… 证据：`rag_retrieval/train/colbert/train_colbert.py` - **Data**（source_file）：class EmbeddingDataset Dataset ⋮---- train data keys num = len self.train data 0 .keys train data keys num = train data keys num - 1 if 'prompt for query' in self.train data 0 else train data keys num ⋮---- def read train data self, train data path ⋮---- train data = ⋮---- data dic = json.loads line.strip ⋮---- temp dic = {} ⋮---- num = math.ceil self.neg nums / len data dic 'neg' ⋮---- def len self ⋮---- def getitem self, idx ⋮---- def triplet collate fn self, batch ⋮---- all querys = all pos docs = all neg docs = ⋮---- all query tokens = self.tokenizer all querys, padding='max length', truncation=True, all pos doc tokens = self.tokenizer all pos docs, padding='max length', truncation=True… 证据：`rag_retrieval/train/embedding/data.py` - **Model**（source_file）：class Embedding nn.Module ⋮---- def get embedding self, input ids, attention mask ⋮---- batch text = {'input ids': input ids, 'attention mask': attention mask} embedding = self.model batch text 'sentence embedding' ⋮---- query embeddings = self.get embedding query input ids, query attention mask ⋮---- res dict = {} ⋮---- pos doc embeddings = self.get embedding pos doc input ids, pos doc attention mask ⋮---- rank = accelerator.process index world size = accelerator.num processes B total = B world size all doc emb = accelerator.gather pos doc embeddings labels = torch.arange B, device=query embeddings.device + rank B neg mask = torch.ones B, B total , dtype=torch.bool, device=query embeddings… 证据：`rag_retrieval/train/embedding/model.py` - **self.device = device**（source_file）：class DistillEmbedding nn.Module ⋮---- def get embedding self, input ids, attention mask ⋮---- batch text = {'input ids': input ids, 'attention mask': attention mask} embedding = self.model batch text 'sentence embedding' ⋮---- student embeddings = self.get embedding query input ids, query attention mask ⋮---- res dict = {} ⋮---- teacher embeddings = F.normalize teacher embeddings, p=2, dim=-1 ⋮---- cosine loss = self.cosine embedding loss student embeddings, teacher embeddings ⋮---- teacher similarity = teacher embeddings @ teacher embeddings.transpose -1, -2 triplet label = torch.where self.get score diff teacher embeddings < 0, 1, -1 ⋮---- similarity loss = torch.tensor 0.0, device=stude… 证据：`rag_retrieval/train/embedding/model_distill.py` - **Train Embedding**（source_file）：parameters = list model.named parameters optimizer grouped parameters = optimizer = torch.optim.AdamW optimizer grouped parameters, lr=lr ⋮---- def parse args ⋮---- parser = argparse.ArgumentParser ⋮---- args = parser.parse args ⋮---- config = yaml.safe load file ⋮---- def main ⋮---- args = parse args ⋮---- project config = ProjectConfiguration ⋮---- accelerator = Accelerator ⋮---- mrl dims = list map int, args.mrl dims.split "," ⋮---- mrl dims = ⋮---- tokenizer = AutoTokenizer.from pretrained args.model name or path device = accelerator.device ⋮---- model = Embedding.from pretrained train datast = EmbeddingDataset ⋮---- val datast = EmbeddingDataset ⋮---- model = DistillEmbedding.from pret… 证据：`rag_retrieval/train/embedding/train_embedding.py` - **Train Embedding**（source_file）：if ! -d "./output" ; then mkdir -p ./output echo "mkdir output" fi if ! -d "./logs" ; then mkdir -p ./logs echo "mkdir logs" fi CUDA VISIBLE DEVICES="0,1" nohup accelerate launch \ --config file ../../../config/default fsdp.yaml \ train embedding.py \ --config ./config/training embedding.yaml \ ./logs/t2ranking 100 example bert.log & 证据：`rag_retrieval/train/embedding/train_embedding.sh` - **Only visualize the label distribution on the main process of distributed mode or in the single process mode**（source_file）：class PointwiseRankerDataset Dataset ⋮---- def init self, data path=None, label key="label", target model=None, max len=512, max label=1, min label=0, shuffle rate=0.0, tag="train" ⋮---- def read data self, data path ⋮---- data = label distribution = defaultdict int ⋮---- data dic = json.loads line.strip query = data dic "query" .strip text = data dic "content" .strip ⋮---- text = shuffle text text, self.shuffle rate label = self.map func data dic.get self.label key, 0 ⋮---- Only visualize the label distribution on the main process of distributed mode or in the single process mode ⋮---- standard output data type: query, doc, label ⋮---- def len self ⋮---- def getitem self, idx ⋮---- def col… 证据：`rag_retrieval/train/reranker/data.py` - **Train Reranker**（source_file）：parameters = list model.named parameters optimizer grouped parameters = optimizer = torch.optim.AdamW optimizer grouped parameters, lr=lr ⋮---- def parse args ⋮---- parser = argparse.ArgumentParser ⋮---- args = parser.parse args ⋮---- config = yaml.safe load file ⋮---- def main ⋮---- args = parse args ⋮---- project config = ProjectConfiguration ⋮---- accelerator = Accelerator ⋮---- model = CrossEncoder.from pretrained ⋮---- model = LLMDecoder.from pretrained ⋮---- train dataset = PointwiseRankerDataset ⋮---- train dataset = GroupedRankerDataset ⋮---- val dataset = PointwiseRankerDataset ⋮---- val dataset = GroupedRankerDataset ⋮---- num workers = 10 train dataloader = DataLoader ⋮---- val d… 证据：`rag_retrieval/train/reranker/train_reranker.py` - **安装**（documentation）：欢迎使用rag retrieval库的Reranker模块，这里是一份Reranker的Tutorial,主要来介绍下Reranker的功能以及注意事项，希望您可以使用的更加得心应手。 证据：`examples/Reranker_Tutorial.md` - **C extensions**（source_file）：Distribution / packaging .Python build/ develop-eggs/ dist/ downloads/ eggs/ .eggs/ lib/ lib64/ parts/ sdist/ var/ wheels/ share/python-wheels/ .egg-info/ .installed.cfg .egg MANIFEST 证据：`.gitignore` - **Default Fsdp**（source_file）：compute environment: LOCAL MACHINE distributed type: FSDP downcast bf16: 'no' fsdp config: fsdp auto wrap policy: TRANSFORMER BASED WRAP fsdp backward prefetch policy: NO PREFETCH fsdp offload params: false fsdp sharding strategy: 3 fsdp state dict type: FULL STATE DICT fsdp transformer layer cls to wrap: BertLayer machine rank: 0 main training function: main mixed precision: 'no' num machines: 1 num processes: 2 rdzv backend: static same network: true tpu env: tpu use cluster: false tpu use sudo: false use cpu: false 证据：`config/default_fsdp.yaml` - **Xlmroberta Default Config**（source_file）：compute environment: LOCAL MACHINE distributed type: FSDP downcast bf16: 'no' fsdp config: fsdp auto wrap policy: TRANSFORMER BASED WRAP fsdp backward prefetch policy: NO PREFETCH fsdp offload params: false fsdp sharding strategy: 3 fsdp state dict type: FULL STATE DICT fsdp transformer layer cls to wrap: XLMRobertaLayer machine rank: 0 main training function: main mixed precision: 'no' num machines: 1 num processes: 2 rdzv backend: static same network: true tpu env: tpu use cluster: false tpu use sudo: false use cpu: false 证据：`config/xlmroberta_default_config.yaml` - **Grouped Reranker Eval Data**（source_file）：{"query": "最近发表的论文中，有哪些新的化疗药物被用于治疗非小细胞肺癌（NSCLC）？", "hits": {"content": "url: https://www.163.com/dy/article/IU2JIR7O053438SI.html\n标题: 2024 ELCC｜杨彬教授：TROPION-Lung01研究最新成果揭晓，非鳞NSCLC患者迎来新希望\n发布时间: 2024年03月24日\n摘要: TROPION-Lung01研究最新结果显示，相较于多西他赛，Dato-DXd在治疗晚期经治非鳞NSCLC患者中取得了可观的PFS获益，且具有可控的安全性。 Dato-DXd已成为首个经III期研究证实的，能显著改善晚期经治非鳞NSCLC患者mPFS的ADC药物。 目前已有多项研究证实Dato-DXd兼顾疗效和安全性，为晚期NSCLC治疗带来新曙光。 2021年WCLC大会上，研究者初次公布了Dato-DXd首个人体研究——TROPION-PanTumor01研究结果。 2023年5月份，该研究的NSCLC队列的更新结果被发表在《Journal of Clinical Oncology》（影响因子50.717）上⁷。\n内容: 2024 ELCC｜杨彬教授：TROPION-Lung01研究最新成果揭晓，非鳞NSCLC患者迎来新希望 肺癌 肿瘤 单药 治疗 nsclc 靶向化疗药物 网易订阅\n 网易首页 网易号 正文 申请入驻 \n\n 2024 ELCC｜杨彬教授：TROPION-Lung01研究最新成果揭晓，非鳞NSCLC患者迎来新希望\n2024-03-… 证据：`example_data/grouped_reranker_eval_data.jsonl` - **Grouped Reranker Train Data Listwise Label**（source_file）：{"query": "当前直播电商行业的市场现状和主要特点是什么？", "hits": {"content": "url: https://m.toutiao.com/article/7166949218479768068/?upstream biz=toutiao pc\n标题: 2022年中国直播电商行业产业链上中下游市场分析\n发布时间: 2023年06月28日\n摘要: ...淘宝、抖音和快手三大 平台 垄断，三大 直播电商 巨头占据了中国 直播电商 行业99.7%的 份额 。其中抖音 市场份额 占比最大，达38.9%；其...\n内容: 中商情报网讯：直播电商是以直播为渠道来达成营销目的的新型电商形态，是数字化时代背景下直播与电商双向融合的产物。与传统电商相比，直播电商直播提供深度实时、富媒体形式的商品展示，为用户带来了更丰富、直接、实时的购物体验，拥有强互动性、强专业性与高转化率等优势。\n一、产业链\n电商直播指的是以直播为渠道来达成营销目的的电商形式，是数字化时代背景下直播与电商双向融合的产物。直播电商产业链由供应端、平台端和消费者构成，其中主要包括商家、MCN、主播、平台及用户等。\n资料来源：中商产业研究院整理\n资料来源：中商产业研究院整理\n二、上游分析\n近年来，中国网上零售额逐年增长。线上消费需求持续释放，网上零售保持较快增长。2022年10月份，社会消费品零售总额40271亿元，同比下降0.5%。1-10月份，全国网上零售额109542亿元，同比增长4.9%。其中，实物商品网上零售额94506亿元，增长7.2%，占社会消费品零售总额的比重为26.… 证据：`example_data/grouped_reranker_train_data_listwise_label.jsonl` - **Grouped Reranker Train Data Pointwise Label**（source_file）：{"query": "当前直播电商行业的市场现状和主要特点是什么？", "hits": {"content": "url: https://m.toutiao.com/article/7166949218479768068/?upstream biz=toutiao pc\n标题: 2022年中国直播电商行业产业链上中下游市场分析\n发布时间: 2023年06月28日\n摘要: ...淘宝、抖音和快手三大 平台 垄断，三大 直播电商 巨头占据了中国 直播电商 行业99.7%的 份额 。其中抖音 市场份额 占比最大，达38.9%；其...\n内容: 中商情报网讯：直播电商是以直播为渠道来达成营销目的的新型电商形态，是数字化时代背景下直播与电商双向融合的产物。与传统电商相比，直播电商直播提供深度实时、富媒体形式的商品展示，为用户带来了更丰富、直接、实时的购物体验，拥有强互动性、强专业性与高转化率等优势。\n一、产业链\n电商直播指的是以直播为渠道来达成营销目的的电商形式，是数字化时代背景下直播与电商双向融合的产物。直播电商产业链由供应端、平台端和消费者构成，其中主要包括商家、MCN、主播、平台及用户等。\n资料来源：中商产业研究院整理\n资料来源：中商产业研究院整理\n二、上游分析\n近年来，中国网上零售额逐年增长。线上消费需求持续释放，网上零售保持较快增长。2022年10月份，社会消费品零售总额40271亿元，同比下降0.5%。1-10月份，全国网上零售额109542亿元，同比增长4.9%。其中，实物商品网上零售额94506亿元，增长7.2%，占社会消费品零售总额的比重为26.… 证据：`example_data/grouped_reranker_train_data_pointwise_label.jsonl` - **Lmsft**（source_file）：{"query": "北京是中国的首都吗", "pos": "北京是中国的首都","华盛顿是美国的首都" , "scores": 0.8, 0.2 } {"query": "美国的首都是哪个城市", "pos": "华盛顿是美国的首都","北京是中国的首都" , "scores": 0.8, 0.2 } 证据：`example_data/lmsft.jsonl` - **Pointwise Reranker Eval Data**（source_file）：{"query": "最近发表的论文中，有哪些新的化疗药物被用于治疗非小细胞肺癌（NSCLC）？", "content": "url: https://www.163.com/dy/article/IU2JIR7O053438SI.html\n标题: 2024 ELCC｜杨彬教授：TROPION-Lung01研究最新成果揭晓，非鳞NSCLC患者迎来新希望\n发布时间: 2024年03月24日\n摘要: TROPION-Lung01研究最新结果显示，相较于多西他赛，Dato-DXd在治疗晚期经治非鳞NSCLC患者中取得了可观的PFS获益，且具有可控的安全性。 Dato-DXd已成为首个经III期研究证实的，能显著改善晚期经治非鳞NSCLC患者mPFS的ADC药物。 目前已有多项研究证实Dato-DXd兼顾疗效和安全性，为晚期NSCLC治疗带来新曙光。 2021年WCLC大会上，研究者初次公布了Dato-DXd首个人体研究——TROPION-PanTumor01研究结果。 2023年5月份，该研究的NSCLC队列的更新结果被发表在《Journal of Clinical Oncology》（影响因子50.717）上⁷。\n内容: 2024 ELCC｜杨彬教授：TROPION-Lung01研究最新成果揭晓，非鳞NSCLC患者迎来新希望 肺癌 肿瘤 单药 治疗 nsclc 靶向化疗药物 网易订阅\n 网易首页 网易号 正文 申请入驻 \n\n 2024 ELCC｜杨彬教授：TROPION-Lung01研究最新成果揭晓，非鳞NSCLC患者迎来新希望\n2024-03-24 18:13:… 证据：`example_data/pointwise_reranker_eval_data.jsonl` - **Pointwise Reranker Train Data**（source_file）：{"query": "当前直播电商行业的市场现状和主要特点是什么？", "content": "url: https://m.toutiao.com/article/7166949218479768068/?upstream biz=toutiao pc\n标题: 2022年中国直播电商行业产业链上中下游市场分析\n发布时间: 2023年06月28日\n摘要: ...淘宝、抖音和快手三大 平台 垄断，三大 直播电商 巨头占据了中国 直播电商 行业99.7%的 份额 。其中抖音 市场份额 占比最大，达38.9%；其...\n内容: 中商情报网讯：直播电商是以直播为渠道来达成营销目的的新型电商形态，是数字化时代背景下直播与电商双向融合的产物。与传统电商相比，直播电商直播提供深度实时、富媒体形式的商品展示，为用户带来了更丰富、直接、实时的购物体验，拥有强互动性、强专业性与高转化率等优势。\n一、产业链\n电商直播指的是以直播为渠道来达成营销目的的电商形式，是数字化时代背景下直播与电商双向融合的产物。直播电商产业链由供应端、平台端和消费者构成，其中主要包括商家、MCN、主播、平台及用户等。\n资料来源：中商产业研究院整理\n资料来源：中商产业研究院整理\n二、上游分析\n近年来，中国网上零售额逐年增长。线上消费需求持续释放，网上零售保持较快增长。2022年10月份，社会消费品零售总额40271亿元，同比下降0.5%。1-10月份，全国网上零售额109542亿元，同比增长4.9%。其中，实物商品网上零售额94506亿元，增长7.2%，占社会消费品零售总额的比重为26.2%；在实物商品网… 证据：`example_data/pointwise_reranker_train_data.jsonl` - **T2Rank 100**（source_file）：{"query": "鹦鹉吃自己的小鱼吗", "pos": "关注养鱼老道,关注更多观赏鱼实践知识,让我们简单养水、轻松养鱼!看来是我错怪了这对迷你鹦鹉鱼,极有可能是我当天看错了,人家本来是不吃孩子的,被我误认为吃了孩子,所以硬生生的给人家分了家。 当时的情况确实是看到雌鱼吞了小鱼没有吐出来 这群迷你鹦鹉小鱼苗我看到它们起水游动是在七月六号的下午,在七月七号的下午,我发现了雌鱼好像是吃了小鱼没有吐出来,在不想小鱼受到伤亡的情况下,我还是给它们分开了,并且当时分得很仔细,一条小鱼也没有和大鱼生活在一起。 我也是想着如果这样的话,很快它们就可以再生一窝,既然已经生产了,我就挨样试试,看看它们在下一窝能不能把小鱼苗顺利带大。 两天之后小鱼缸里的鱼虫喂多了 结果在把大、小鱼分缸的两天之后,也就是七月九号,我给小鱼苗有一次投喂的鱼虫太多了,全部是个体较大的鱼虫,抽底换水我也换不出来,再说了这么小的鱼苗我也不想去惊动它们。 在实在是没有办法的情况下,我也只有用小鱼网把过多的鱼虫给捞出来了,但是小鱼苗已经起水了,虽然是大部队都在鱼缸底部开始群游,必定还是有几条在水面上单独行动的,这就不好办了。 我看了看使用的小鱼网,网口比较大,当时小鱼苗还不是很大,估计捞不大上来,所以我也就没在意,因为当时的鱼虫比它们还大。 所以我就随机的在鱼缸里捞取了一下,结果因为鱼网太疏,最终也没捞到几个鱼虫子,我就直接往两条成鱼的鱼缸里一倒完事了,再也没去管它。 大鱼缸里发现了小鱼,活的好好的 因为这两个鱼缸只使用了一个鱼缸灯,大鱼的鱼缸里之前没有灯,所以这两天我只是机械性的给大鱼投喂鱼虫,其他的事情一概没管。 结… 证据：`example_data/t2rank_100.jsonl` ## 宿主 AI 必须遵守的规则 - **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `examples/MyopicTrap/README.md`, `examples/distill_llm_to_bert_reranker/README.md` - **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `examples/MyopicTrap/README.md`, `examples/distill_llm_to_bert_reranker/README.md` ## 用户开工前应该回答的问题 - 你准备在哪个宿主 AI 或本地环境中使用它？ - 你只是想先体验工作流，还是准备真实安装？ - 你最在意的是安装成本、输出质量、还是和现有规则的冲突？ ## 验收标准 - 所有能力声明都能回指到 evidence_refs 中的文件路径。 - AI_CONTEXT_PACK.md 没有把预览包装成真实运行。 - 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。 --- ## Doramagic Context Augmentation 下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。 ## Human Manual 骨架 使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。 宿主 AI 硬性规则： - 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。 - 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。 - 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。 - **项目概览、安装与目录结构**：importance `high` - source_paths: README.md, README_zh.md, requirements.txt, pyproject.toml, rag_retrieval/__init__.py - **训练流程详解（Embedding、ColBERT、Reranker）**：importance `high` - source_paths: rag_retrieval/train/embedding/README.md, rag_retrieval/train/embedding/train_embedding.py, rag_retrieval/train/embedding/train_embedding.sh, rag_retrieval/train/embedding/data.py, rag_retrieval/train/embedding/model.py - **推理库 rag-retrieval 与模型适配**：importance `high` - source_paths: rag_retrieval/reranker.py, rag_retrieval/infer/__init__.py, rag_retrieval/infer/reranker_models/__init__.py, rag_retrieval/infer/reranker_models/ranker.py, rag_retrieval/infer/reranker_models/cross_encoder_ranker.py - **蒸馏流水线、MyopicTrap 实验与社区常见问题**：importance `high` - source_paths: examples/stella_embedding_distill/README.md, examples/stella_embedding_distill/concate_two_teacher_embedding.py, examples/stella_embedding_distill/concate_two_teacher_embedding.sh, examples/stella_embedding_distill/create_distill_data.py, examples/stella_embedding_distill/create_distill_data.sh ## Repo Inspection Evidence / 源码检查证据 - repo_clone_verified: true - repo_inspection_verified: true - repo_commit: `a91c2922e669c1300720f51cf4e7e9e3896c3027` - inspected_files: `README.md`, `pyproject.toml`, `requirements.txt`, `examples/MyopicTrap/README.md`, `examples/MyopicTrap/appendix_exp_cosine_sim.py`, `examples/MyopicTrap/commercial_embedding_api.py`, `examples/MyopicTrap/exp_FineWeb-PosQ.py`, `examples/MyopicTrap/exp_SQuAD-PosQ.py`, `examples/MyopicTrap/utils.py`, `examples/Reranker_Tutorial.md`, `examples/distill_llm_to_bert_reranker/README.md`, `examples/distill_llm_to_bert_reranker/create_distill_data.py`, `examples/distill_llm_to_bert_reranker/model_llm_generate.py`, `examples/stella_embedding_distill/README.md`, `examples/stella_embedding_distill/concate_two_teacher_embedding.py`, `examples/stella_embedding_distill/create_distill_data.py`, `examples/synthetic_data_embedding/README.md`, `examples/synthetic_data_embedding/flashrag_config.yaml`, `examples/synthetic_data_embedding/get_lm_probs_dataset.py` 宿主 AI 硬性规则： - 没有 repo_clone_verified=true 时，不得声称已经读过源码。 - 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。 - 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。 ## Doramagic Pitfall Constraints / 踩坑约束 这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。 ### Constraint 1: 来源证据：训练reranker一直timeout - Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：训练reranker一直timeout - Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Why it matters: 可能增加新用户试用和生产接入成本。 - Evidence: community_evidence:github | https://github.com/NovaSearch-Team/RAG-Retrieval/issues/112 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 2: 能力判断依赖假设 - Trigger: README/documentation is current enough for a first validation pass. - Host AI rule: 将假设转成下游验证清单。 - Why it matters: 假设不成立时，用户拿不到承诺的能力。 - Evidence: capability.assumptions | https://github.com/NovaSearch-Team/RAG-Retrieval | README/documentation is current enough for a first validation pass. - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 3: 来源证据：使用的 vllm 框架而不是 hf 时 试时报错 - Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：使用的 vllm 框架而不是 hf 时 试时报错 - Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Why it matters: 可能增加新用户试用和生产接入成本。 - Evidence: community_evidence:github | https://github.com/NovaSearch-Team/RAG-Retrieval/issues/109 | 来源类型 github_issue 暴露的待验证使用条件。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 4: 维护活跃度未知 - Trigger: 未记录 last_activity_observed。 - Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。 - Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - Evidence: evidence.maintainer_signals | https://github.com/NovaSearch-Team/RAG-Retrieval | last_activity_observed missing - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 - Trigger: no_demo - Evidence: downstream_validation.risk_items | https://github.com/NovaSearch-Team/RAG-Retrieval | no_demo; severity=medium - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 6: 存在评分风险 - Trigger: no_demo - Why it matters: 风险会影响是否适合普通用户安装。 - Evidence: risks.scoring_risks | https://github.com/NovaSearch-Team/RAG-Retrieval | no_demo; severity=medium - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 7: 来源证据：AttributeError: XLMRobertaTokenizer has no attribute batch_encode_plus. Did you mean: '_encode_plus'? - Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：AttributeError: XLMRobertaTokenizer has no attribute batch_encode_plus. Did you mean: '_encode_plus'? - Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Why it matters: 可能影响授权、密钥配置或安全边界。 - Evidence: community_evidence:github | https://github.com/NovaSearch-Team/RAG-Retrieval/issues/119 | 来源类型 github_issue 暴露的待验证使用条件。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 8: 来源证据：微调Reranker问题 - Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：微调Reranker问题 - Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Why it matters: 可能影响授权、密钥配置或安全边界。 - Evidence: community_evidence:github | https://github.com/NovaSearch-Team/RAG-Retrieval/issues/105 | 来源讨论提到 node 相关条件，需在安装/试用前复核。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 9: 来源证据：📋 Documentation Enhancement Suggestion - Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：📋 Documentation Enhancement Suggestion - Host AI rule: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。 - Why it matters: 可能影响授权、密钥配置或安全边界。 - Evidence: community_evidence:github | https://github.com/NovaSearch-Team/RAG-Retrieval/issues/116 | 来源讨论提到 python 相关条件，需在安装/试用前复核。 - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。 ### Constraint 10: issue/PR 响应质量未知 - Trigger: issue_or_pr_quality=unknown。 - Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。 - Why it matters: 用户无法判断遇到问题后是否有人维护。 - Evidence: evidence.maintainer_signals | https://github.com/NovaSearch-Team/RAG-Retrieval | issue_or_pr_quality=unknown - Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。