实用笔记：将RAG扩展至1000万份文档 第二部分：优化策略
《实用笔记》操作指南：将 RAG 扩展至 1000 万份文档 第二部分：优化——面向采用该模式的团队提供的合同、检查项及即用代码模块。
可将此文档视为《将RAG扩展至1000万份文档第二部分：优化检索与生成》中内容的面向操作人员的重构版本：清晰的阶段划分、有序的代码模块以及便于交接时参考的恢复说明。 在“概览”阶段，若能将其视为可量化的基准，则效果最佳。在扩大范围之前，需记录一份理想的处理结果、一个故障案例以及回滚说明。 应将此阶段视为输入与经过验证的输出之间的契约。为相关成果命名，明确成功标准，绝不允许出现无声的、不完整的处理结果。
1. 多阶段检索流程
对于多阶段检索漏斗的第一阶段，在修改代码之前需明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。应在功能结果旁记录执行时间以及令牌或查询成本。提前显示成本信息，可避免在从演示环境切换到共享环境时出现意外费用。需注明实际作为答案依据的段落内容；若没有引用，操作人员就无法区分是幻觉内容还是索引缺失导致的错误。
[ 10,000,000 Total Document Chunks ]
│
▼
[ Step 1: SQL Pre-Filter ] ────────► Filter by Tenant / Dept / Role / Region
│
▼
[ ~50,000 Candidates ]
│
▼
[ Step 2: Hybrid Search ] ─────────► Dense Vectors (Qdrant) + Sparse BM25
│
▼
[ Top 100 Candidates ]
│
▼
[ Step 3: Cross-Encoder ] ───────► Cohere Rerank / BGE-Reranker
│
▼
[ Final Top 5 Chunks ] ──────────► Passed to LLM Context Window
第一阶段：关系型预过滤（硬性约束）
在阶段1的关联预过滤环节中，应在修改代码之前明确输入参数、该步骤的负责人以及结束标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 配置信息应置于应用程序代码之外。环境文件、密钥存储以及功能标志应集中存放于一个位置，以便操作人员无需查看整个系统结构即可进行审核。 需引用实际作为答案依据的段落。如果没有引用，操作人员就无法区分是虚假信息还是索引缺失导致的错误。
from qdrant_client.models import Filter, FieldCondition, MatchValue
# Restrict search space by user session permissions before distance scoring
user_access_filter = Filter(
must=[
FieldCondition(key="department", match=MatchValue(value="Engineering")),
FieldCondition(key="is_active", match=MatchValue(value=True))
]
)
阶段2：混合搜索（密集型+稀疏型融合）
在第二阶段混合搜索环节中，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 需同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都是产品功能的一部分，而非后续需要补充的内容。 必须引用实际作为答案依据的段落。没有引用的话，操作人员就无法区分是幻觉内容还是索引缺失导致的错误。 在第二阶段混合搜索环节中，修改代码之前需明确输入参数、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。 应将这一阶段视为输入与经过验证的输出之间的契约。为相关输出文件命名，明确成功判定标准，杜绝默默完成部分任务的情况。
第三阶段：交叉编码器重排序
在处理第三阶段的交叉编码器重排序时，首先明确相关要求：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 在功能结果旁记录执行时间以及令牌或查询成本。提前了解成本情况，可避免从演示环境过渡到共享环境时出现意外费用。 在调整提示词之前，先使用固定的问题集测试召回率。仅仅更换提示词很难改善较差的检索效果。
2. 条件查询路由器
在处理第二阶段的条件查询路由时，首先明确需求规范：所需的输入参数、成功信号以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改始终符合预期。 应将配置信息与应用程序代码分开。环境文件、密钥存储以及功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。 在调整提示词之前，先使用固定的问题集来测试召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。
User Query
│
▼
[ Intent Classifier / Router ]
│
├── Simple Math / Logic ──────────► Direct Calculator / Python REPL
├── Conversational / Follow-up ───► Direct LLM Memory Context
└── Domain Knowledge Request ─────► Full Hybrid RAG Pipeline
# Conceptual Router Pattern
def route_query(user_query: str) -> str:
prompt = f"""Classify the user query into one of these routes:
- RETRIEVE: Needs internal company documentation/database lookup.
- COMPUTE: Pure math, calculation, or logic.
- DIRECT: Conversational, greetings, or basic language rewrites.
Query: {user_query}
Classification:"""
# Run a fast, lightweight classifier (or small local SLM)
decision = fast_classifier(prompt).strip()
return decision
3. 超出简单RAG的范畴：多智能体协调与反馈循环
在推进“超越简单RAG”的三个阶段时，首先需明确相关约定：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 同时记录正常流程与异常恢复路径。重试机制、人工审核环节以及错误处理都属于产品功能的一部分，而非后续的优化工作。 在调整提示词之前，需先用固定的问题集来衡量召回率。仅仅更换提示词往往无法解决检索效果不佳的问题。 在推进“超越简单RAG”的三个阶段时，首先需明确相关约定：所需输入、成功标志以及部分失败时的处理方式。这样的清单能确保后续的代码修改保持一致性。 应将这一阶段视为输入与经过验证的输出之间的契约。为相关成果命名，定义成功判定标准，并杜绝无声的半完成状态。
[ Orchestrator / Planner ]
│
┌─────────────────┴─────────────────┐
▼ ▼
[ Researcher Agent ] [ Compliance Agent ]
• Retrieves 2025 Sales Data • Retrieves 2024 Regulations
• Extracts regional tables • Parses policy constraints
│ │
└─────────────────┬─────────────────┘
▼
[ Synthesis Agent ]
• Reconciles numbers
• Validates output consistency
│
Confidence Score Check
│ │
[ Low Confidence ] [ High Confidence ]
│ │
▼ ▼
Loop back & refine Final Guardrail Validation
自我修正与反馈循环
将自我修正反馈循环阶段视为可测量的对象时，其效果最佳。在扩大范围之前，先记录一份理想的转录结果、一个失败案例以及回滚说明。在功能结果旁同时记录处理时间以及令牌或查询成本。提前了解成本情况，可避免在系统从演示环境过渡到共享环境时出现意外费用。应将分块策略与检索策略分开处理，当质量指标发生变化时，修改其中一项不应迫使重新编写另一项。
4. 持续评估
将“4个持续评估阶段”视为可度量的指标体系时，其效果最佳。在扩大范围之前，先记录一份优秀的处理结果、一个失败案例以及回滚说明。 配置应与应用程序代码分开存放。环境文件、密钥存储和功能开关应集中于一个位置，以便操作人员无需查看整个系统结构即可进行审计。 分块策略与检索策略应相互独立。当质量指标发生变化时，修改其中一项不应强制要求重新编写另一项。
┌──► Faithfulness (Is the answer grounded in the retrieved chunks?)
RAG Evaluation ─┼──► Answer Relevance (Did it actually answer the user's prompt?)
├──► Context Recall (Did retrieval find all necessary reference chunks?)
└──► System Latency & Token Cost (Is it cost-effective at scale?)
6. 全流程实操：完整的检索与生成管道
在“6个端到端实战阶段”中，若将其视为可度量的对象来处理，效果会更好。在扩大范围之前，需记录一份理想状态下的输出样本、一个故障案例以及回滚说明。同时记录正常流程与恢复流程的相关信息。重试机制、人工审核环节以及错误处理方式都是产品本身的一部分，而非后续需要补充的内容。应将分块策略与检索策略分开处理；当质量指标发生变化时，修改其中一项不应强制要求重新编写另一项。在“6个端到端实战阶段”中，若将其视为可度量的对象来处理，效果会更好。在扩大范围之前，需记录一份理想状态下的输出样本、一个故障案例以及回滚说明。应将这一阶段视为输入与经过验证的输出之间的契约，为相关输出文件命名，明确成功标准，绝不允许出现无声无息的半完成状态。
from openai import OpenAI
from qdrant_client import QdrantClient
from qdrant_client.models import Filter, FieldCondition, MatchValue
# 1. Initialize Clients
# Pointing to local LM Studio running on port 8080
ai_client = OpenAI(base_url="http://127.0.0.1:8080/v1", api_key="lm-studio")
qdrant_client = QdrantClient(url="http://localhost:6333")
COLLECTION_NAME = "enterprise_knowledge_base"
EMBEDDING_MODEL = "nomic-ai/nomic-embed-text-v1.5"
def retrieve_and_generate(user_query: str, user_department: str) -> str:
print(f"\n🔍 Processing query: \"{user_query}\" for department: [{user_department}]")
# 2. Vectorize the User Query
query_resp = ai_client.embeddings.create(
input=[user_query],
model=EMBEDDING_MODEL
)
query_vector = query_resp.data[0].embedding
# 3. Stage 1 & 2: SQL Pre-Filter + Vector Search
# Filter by user department and active document status
access_filter = Filter(
must=[
FieldCondition(key="department", match=MatchValue(value=user_department))
]
)
search_results = qdrant_client.search(
collection_name=COLLECTION_NAME,
query_vector=query_vector,
query_filter=access_filter,
limit=3
)
if not search_results:
return "No relevant or authorized documents found."
# 4. Context Assembly with Breadcrumbs
context_blocks = []
for hit in search_results:
breadcrumb = hit.payload.get("breadcrumb", "General")
text = hit.payload.get("text", "")
context_blocks.append(f"[{breadcrumb}]\n{text}")
full_context = "\n\n---\n\n".join(context_blocks)
# 5. Generation via Local LLM
system_prompt = (
"You are an enterprise technical assistant. "
"Answer the user query strictly using the provided context. "
"If the context does not contain the answer, explicitly state that you do not know.\n\n"
f"Context:\n{full_context}"
)
completion = ai_client.chat.completions.create(
model="local-model",
messages=[
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_query}
],
temperature=0.1
)
return completion.choices[0].message.content
# Example Execution
if __name__ == "__main__":
response = retrieve_and_generate(
user_query="How do I enable TLS 1.3 in config.yaml?",
user_department="Engineering"
)
print("\n🤖 Final Answer:\n", response)
结论：生产环境RAG架构
在结论部分，对于生产环境中的RAG处理阶段，应在修改代码之前明确输入内容、该步骤的负责人以及终止标准。操作人员应能够从已知的检查点重新运行该步骤，而无需猜测隐藏状态。除了功能结果外，还需记录处理时间以及令牌或查询成本。提前了解成本情况可以避免在从演示环境过渡到共享环境时出现意外费用。必须注明实际用于生成答案的对应内容；如果没有引用依据，操作人员就无法区分是幻觉内容还是索引缺失导致的错误。
操作检查清单
在处理操作检查清单阶段时，首先需明确相关约定：所需输入、成功标志，以及部分失败时的处理方式。这样的检查清单能确保后续的代码修改保持一致性。
应优先选择小型、可测试的单元，而非庞大的脚本。当某个步骤出错时，故障应指向单一责任模块，而非复杂的处理流程。
在调整提示词之前，先使用固定的问题集来衡量召回率。频繁更换提示词很难解决检索效果不佳的问题。
在更改提示词或模型之前，先锁定一组基准数据。同时调整系统和评估标准会掩盖功能退化的问题。
在预算允许的情况下，利用测试环境而非真实的付费 API，在持续集成过程中添加用于检测关键路径的冒烟测试。
将配置信息与应用程序代码分开。环境文件、密钥存储和功能开关应集中存放，以便操作人员无需查看整个系统结构即可进行审计。
在推广该技术栈之前，应先冻结版本，为关键流程记录标准输出日志，并明确回滚步骤。共享环境需要设置速率限制、租户验证机制，以及负责密钥轮换的明确责任人。与其展示花哨的一次性演示，不如注重扎实的可靠性。
c42ae29c43bc 的批量处理说明：不要将提供商密钥放入代码仓库，为每个会话设置令牌使用上限，并将日志存储在评估用示例文件旁边，以便后续模型更换时仍能保持对比性。