Plano 知识库 RAG Agent 实战HTTP 过滤器链中的 8 类测试查询与检索评估指南【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano本指南围绕开源仓库 demos/filter_chains/http_filter 演示项目中的sample_queries.md展开系统梳理该 RAG Agent 内置的 8 大类共 40 条示例查询并结合 Input Guards、Query Rewriter、Context Builder 三级 HTTP 过滤器链与 RAG Agent 的源码实现说明每类查询背后的检索意图、对应的知识库文档以及如何在本地启动演示后逐条验证。读完本文你将掌握一套可复制、可扩展的 RAG 检索评估方法论能够据此为自有知识库设计覆盖单文档、跨文档、复杂分析与细节抽取的测试查询集。示例查询集的定位RAG 系统的验收测试用例在 demos/filter_chains/http_filter/README.md 描述的演示架构中系统由四个组件构成Input GuardsHTTP 过滤器端口 10500——校验查询是否属于 TechCorp 业务域拦截无关问题Query RewriterHTTP 过滤器端口 10501——用 LLM 重写查询以提升召回效果Context BuilderHTTP 过滤器端口 10502——从知识库检索相关片段并注入上下文RAG AgentREST/OpenAI端口 10505——基于增强后的上下文生成最终回答。sample_queries.md正是为这套链路准备的查询语料它不是随意的提问清单而是按照知识库中文档的类型、检索复杂度与查询意图精心编排的测试集。每一条查询都能映射到sample_knowledge_base.csv中的某一份或多份虚拟企业文档例如 TechCorp 云服务 SLA、DataSecure 隐私政策、PrecisionParts 供应链协议、EduTech 学生数据管理规范、FinanceFirst 投资咨询协议等。通过逐条发送这些查询并检查回复质量可以系统评估上下文检索是否准确、跨文档关联是否生效、细节抽取是否完整。快速启动演示环境在运行示例查询之前需要先拉起整套服务。仓库提供了自动化脚本 run_demo.shexport OPENAI_API_KEYyour-key ./run_demo.sh脚本会依次完成检查/创建.env、以planoai up config.yaml启动 Plano原生运行在宿主机 8001 与 12000 端口、再以bash start_agents.sh 拉起四个本地 Python 服务。若需要交互式聊天界面与链路追踪可追加--with-ui参数额外启动 AnythingLLMhttp://localhost:3001与 Jaegerhttp://localhost:16686。关闭演示使用./run_demo.sh down。随后即可用 curl 向 Plano 的 OpenAI 兼容端点发送查询curl -X POST http://localhost:8001/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: What is the guaranteed uptime for TechCorp?}] }请求会先进入过滤器链Input Guards → Query Rewriter → Context Builder再被转发到 RAG Agent 生成回答。该链路由 config.yaml 中的input_filters声明input_guards、query_rewriter、context_builder三个过滤器均以type: http通过普通 HTTP POST 通信。单文档查询覆盖知识库六大文档类别sample_queries.md的前六类查询分别对应知识库中的一份核心文档用于验证单文档范围内的精确检索。以下是各类查询的原文要点及对应的检索意图。服务等级协议SLA查询对应sample_knowledge_base.csv中的TechCorp_CloudServices_SLA_Agreement_2024文档5 条查询围绕合同的关键条款展开What is the guaranteed uptime percentage for TechCorps cloud services?99.9% 正常运行时间承诺What remedies are available if the API response time exceeds the agreed threshold?响应超阈值时的补偿措施How quickly must TechCorp respond to critical support issues?关键问题 1 小时内响应What monitoring and reporting requirements are specified in the SLA?实时监控与月度报告义务When was the TechCorp service agreement signed and by whom?签署时间与签署方从 CSV 源数据可以看到这些问题都能在 SLA 正文中找到确切答案例如Provider guarantees 99.9% uptime、Critical issues within 1 hour, Standard issues within 4 hours、For each full percentage point below 99.9% availability, Customer receives 10% credit。这一组查询特别适合验证数值型事实的抽取准确性。隐私政策查询对应DataSecure_Privacy_Policy_v3.2文档5 条查询覆盖数据保护的关键维度What encryption methods does DataSecure use to protect data?How long does DataSecure retain personal data after account deletion?What rights do users have regarding their personal information?Can DataSecure sell user data to third parties for marketing?Who should be contacted for privacy-related concerns at DataSecure?注意其中包含否定性/边界类问题Can DataSecure sell user data...这类查询用于检验检索系统是否能把禁止/不允许这类语义正确传递到最终回答避免仅凭关键词匹配给出相反结论。供应链协议查询对应供应链采购协议文档PrecisionParts5 条查询聚焦商业条款What types of automotive components does PrecisionParts supply?What are the payment terms and volume discount structure?What quality standards must the supplied components meet?What are the penalties for late delivery?What insurance coverage requirements apply to the supplier?学生数据管理查询对应教育科技公司EduTech的学生数据合规文档5 条查询涉及法规、安全与留存What federal laws must EduTech comply with regarding student data?What security measures are in place to protect student information?How long are student records retained after graduation?What consent is required for students under 13 years old?Who can access student educational records?这一类查询包含**年龄条件under 13**等复合约束可用于评估过滤器链在 Query Rewriter 阶段是否成功将隐含条件显式化帮助 Context Builder 命中正确片段。投资咨询查询对应金融服务公司FinanceFirst的投资咨询协议5 条查询围绕费用、监管与义务What is FinanceFirsts management fee structure?What types of investments are included in the advisory services?What regulatory body oversees FinanceFirst Advisors?How often are portfolio reviews conducted?What are the clients responsibilities under this agreement?医疗保健标准查询对应医疗机构的标准规范文档5 条查询侧重可量化的合规指标What is the target response time for emergency code teams?What hand hygiene compliance rate is required?How quickly must medical records be completed after patient encounters?What continuing education requirements apply to nursing staff?What patient safety protocols are mandatory upon admission?与 SLA 组类似这一组同样以百分比、时限等硬指标为主适合与 SLA 查询组一起作为数值检索回归测试的核心语料。跨文档查询验证多源关联检索第三类升级维度是跨文档查询共 5 条。它们不再指向单一文档而是要求系统在多个文档之间建立横向关联Which agreements include confidentiality or data protection provisions?What are the common termination notice periods across different contract types?Which documents specify insurance or liability coverage requirements?What compliance and regulatory requirements are mentioned across agreements?Which contracts include performance metrics or service level commitments?这类查询对 Context Builder 的挑战在于find_relevant_passages见 context_builder.py默认只取top_k3个片段当答案分散在多份文档中时检索阶段必须优先返回跨文档的高价值片段否则最终回答会出现遗漏。测试时可结合 Jaeger 中该请求的完整 span 链观察 Context Builder 选中了哪些文档索引从而判断 top_k 是否需要对跨文档查询场景放大。复杂分析查询评估推理与综合能力第四类共 5 条属于对系统综合能力的压力测试要求检索结果支撑对比与归纳Compare the data retention policies across the privacy policy and student data management documents.What are the different approaches to risk management across the supply chain and investment advisory agreements?How do the security measures in the healthcare standards compare to those in the privacy policy?Which agreements provide the most detailed compliance and regulatory frameworks?What common themes exist in the quality assurance requirements across different industries?这类查询的评估要点不在是否答对某一数字而在检索片段是否同时覆盖被比较的多份文档。如果回答只引用了单份文档说明 Query Rewriter 未能把compare ... across ...结构转换为并列的多目标检索。从源码看重写发生在 query_rewriter.py其 system prompt 明确要求rewrite the last user message to be more specific and context-aware因此复杂分析查询是检验重写质量最直接的探针。文档细节抽取查询深度召回与信息完整性审计最后一类共 5 条聚焦文档中所有相关细节的穷举式抽取List all the specific percentages, timeframes, and numerical requirements mentioned in the SLA.What are all the contact persons and their roles mentioned across the documents?Identify all the compliance standards and certifications referenced in the supply chain agreement.What are the specific consequences or penalties mentioned for non-compliance across agreements?List all the third-party systems, tools, or services mentioned in the documents.这类查询用于审计信息完整性。以列出 SLA 中所有百分比与时限为例正确答案应包含 99.9% 正常运行时间、200ms API 平均响应、1 小时/4 小时支持响应、10% 月度费用抵扣、5% 月度积分等全部数值。由于 Context Builder 注入上下文时会将片段截断为前 500 字符见 context_builder.py长文档的细节可能被截断此类查询恰好能暴露片段长度与 top_k 配置的不足是调优find_relevant_passages参数的直接依据。完整查询清单40 条测试用例速查将 sample_queries.md 中的全部查询整理为下表可直接作为回归测试清单类别数量核心检索意图对应知识库文档Service Level Agreement Queries5SLA 数值条款与签署信息TechCorp 云服务 SLA 协议Privacy Policy Queries5加密、留存、用户权利、数据出售边界DataSecure 隐私政策 v3.2Supply Chain Agreement Queries5供应品类、付款条款、质量标准、违约罚则PrecisionParts 供应链协议Student Data Management Queries5联邦法律、安全措施、留存期限、未成年人同意EduTech 学生数据管理规范Investment Advisory Queries5费用结构、监管机构、审查频率、客户义务FinanceFirst 投资咨询协议Healthcare Standards Queries5响应时限、合规率、病历完成时限、培训要求医疗机构标准规范Cross-Document Queries5保密条款、终止通知期、保险责任、合规要求横向对比跨多份文档Complex Analysis Queries5数据留存、风险管理、安全措施等跨文档对比跨多份文档Document-Specific Detail Queries5百分比/时限穷举、联系人、合规认证、违约后果枚举单份或多份文档测试执行建议基线测试先逐条发送全部 40 条查询将回答人工标注为完整命中 / 部分命中 / 未命中形成基线模块化定位任一查询失败时对照 Jaeger 中的链路分别检查 Input Guards 是否误拦截返回 400out_of_scope、Query Rewriter 是否丢失关键约束、Context Builder 选中的片段索引是否覆盖答案所在文档参数回归修改top_k、知识库 CSV 内容或各过滤器使用的模型gpt-4o-mini与gpt-4o的别名在 config.yaml 的model_aliases中定义后重跑清单对比命中率变化。扩展把查询集复用到你的知识库sample_queries.md的价值在于其方法论可迁移无需修改任何代码即可应用于其他知识库。只需遵循同样的设计维度单文档维度为每份重要文档设计 5 条精确事实查询数值、人名、日期、义务覆盖文档的关键章节跨文档维度设计涉及至少两份文档的横向问题验证多源召回复杂分析维度加入 compare / contrast / common themes 类问题测试综合推理细节穷举维度以list all ... mentioned句式审计信息完整性暴露检索截断与 top_k 不足。更换知识库时只需替换 src/rag_agent/sample_knowledge_base.csv 的path,content两列内容并相应调整 input_guards.py 中 TechCorp 领域白名单的 system prompt将 TechCorp 业务域描述替换为目标领域其余过滤器链代码无需改动即可得到一套面向新场景的检索评估环境。小结sample_queries.md虽然只是一个查询列表但在 Plano 的 HTTP 过滤器链演示中承担着验收测试用例集的角色单文档查询验证精确召回跨文档查询验证多源关联复杂分析查询验证综合推理细节抽取查询验证信息完整性。将它与 config.yaml、三个 HTTP 过滤器源码以及 Jaeger 追踪配合使用你可以对任何 RAG 系统的检索质量建立可量化、可回归的评估基线这也是该演示项目为知识库类应用提供的最实用的工程资产。【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Plano 知识库 RAG Agent 实战HTTP 过滤器链中的 8 类测试查询与检索评估指南【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano本指南围绕开源仓库 demos/filter_chains/http_filter 演示项目中的sample_queries.md展开系统梳理该 RAG Agent 内置的 8 大类共 40 条示例查询并结合 Input Guards、Query Rewriter、Context Builder 三级 HTTP 过滤器链与 RAG Agent 的源码实现说明每类查询背后的检索意图、对应的知识库文档以及如何在本地启动演示后逐条验证。读完本文你将掌握一套可复制、可扩展的 RAG 检索评估方法论能够据此为自有知识库设计覆盖单文档、跨文档、复杂分析与细节抽取的测试查询集。示例查询集的定位RAG 系统的验收测试用例在 demos/filter_chains/http_filter/README.md 描述的演示架构中系统由四个组件构成Input GuardsHTTP 过滤器端口 10500——校验查询是否属于 TechCorp 业务域拦截无关问题Query RewriterHTTP 过滤器端口 10501——用 LLM 重写查询以提升召回效果Context BuilderHTTP 过滤器端口 10502——从知识库检索相关片段并注入上下文RAG AgentREST/OpenAI端口 10505——基于增强后的上下文生成最终回答。sample_queries.md正是为这套链路准备的查询语料它不是随意的提问清单而是按照知识库中文档的类型、检索复杂度与查询意图精心编排的测试集。每一条查询都能映射到sample_knowledge_base.csv中的某一份或多份虚拟企业文档例如 TechCorp 云服务 SLA、DataSecure 隐私政策、PrecisionParts 供应链协议、EduTech 学生数据管理规范、FinanceFirst 投资咨询协议等。通过逐条发送这些查询并检查回复质量可以系统评估上下文检索是否准确、跨文档关联是否生效、细节抽取是否完整。快速启动演示环境在运行示例查询之前需要先拉起整套服务。仓库提供了自动化脚本 run_demo.shexport OPENAI_API_KEYyour-key ./run_demo.sh脚本会依次完成检查/创建.env、以planoai up config.yaml启动 Plano原生运行在宿主机 8001 与 12000 端口、再以bash start_agents.sh 拉起四个本地 Python 服务。若需要交互式聊天界面与链路追踪可追加--with-ui参数额外启动 AnythingLLMhttp://localhost:3001与 Jaegerhttp://localhost:16686。关闭演示使用./run_demo.sh down。随后即可用 curl 向 Plano 的 OpenAI 兼容端点发送查询curl -X POST http://localhost:8001/v1/chat/completions \ -H Content-Type: application/json \ -d { model: gpt-4o, messages: [{role: user, content: What is the guaranteed uptime for TechCorp?}] }请求会先进入过滤器链Input Guards → Query Rewriter → Context Builder再被转发到 RAG Agent 生成回答。该链路由 config.yaml 中的input_filters声明input_guards、query_rewriter、context_builder三个过滤器均以type: http通过普通 HTTP POST 通信。单文档查询覆盖知识库六大文档类别sample_queries.md的前六类查询分别对应知识库中的一份核心文档用于验证单文档范围内的精确检索。以下是各类查询的原文要点及对应的检索意图。服务等级协议SLA查询对应sample_knowledge_base.csv中的TechCorp_CloudServices_SLA_Agreement_2024文档5 条查询围绕合同的关键条款展开What is the guaranteed uptime percentage for TechCorps cloud services?99.9% 正常运行时间承诺What remedies are available if the API response time exceeds the agreed threshold?响应超阈值时的补偿措施How quickly must TechCorp respond to critical support issues?关键问题 1 小时内响应What monitoring and reporting requirements are specified in the SLA?实时监控与月度报告义务When was the TechCorp service agreement signed and by whom?签署时间与签署方从 CSV 源数据可以看到这些问题都能在 SLA 正文中找到确切答案例如Provider guarantees 99.9% uptime、Critical issues within 1 hour, Standard issues within 4 hours、For each full percentage point below 99.9% availability, Customer receives 10% credit。这一组查询特别适合验证数值型事实的抽取准确性。隐私政策查询对应DataSecure_Privacy_Policy_v3.2文档5 条查询覆盖数据保护的关键维度What encryption methods does DataSecure use to protect data?How long does DataSecure retain personal data after account deletion?What rights do users have regarding their personal information?Can DataSecure sell user data to third parties for marketing?Who should be contacted for privacy-related concerns at DataSecure?注意其中包含否定性/边界类问题Can DataSecure sell user data...这类查询用于检验检索系统是否能把禁止/不允许这类语义正确传递到最终回答避免仅凭关键词匹配给出相反结论。供应链协议查询对应供应链采购协议文档PrecisionParts5 条查询聚焦商业条款What types of automotive components does PrecisionParts supply?What are the payment terms and volume discount structure?What quality standards must the supplied components meet?What are the penalties for late delivery?What insurance coverage requirements apply to the supplier?学生数据管理查询对应教育科技公司EduTech的学生数据合规文档5 条查询涉及法规、安全与留存What federal laws must EduTech comply with regarding student data?What security measures are in place to protect student information?How long are student records retained after graduation?What consent is required for students under 13 years old?Who can access student educational records?这一类查询包含**年龄条件under 13**等复合约束可用于评估过滤器链在 Query Rewriter 阶段是否成功将隐含条件显式化帮助 Context Builder 命中正确片段。投资咨询查询对应金融服务公司FinanceFirst的投资咨询协议5 条查询围绕费用、监管与义务What is FinanceFirsts management fee structure?What types of investments are included in the advisory services?What regulatory body oversees FinanceFirst Advisors?How often are portfolio reviews conducted?What are the clients responsibilities under this agreement?医疗保健标准查询对应医疗机构的标准规范文档5 条查询侧重可量化的合规指标What is the target response time for emergency code teams?What hand hygiene compliance rate is required?How quickly must medical records be completed after patient encounters?What continuing education requirements apply to nursing staff?What patient safety protocols are mandatory upon admission?与 SLA 组类似这一组同样以百分比、时限等硬指标为主适合与 SLA 查询组一起作为数值检索回归测试的核心语料。跨文档查询验证多源关联检索第三类升级维度是跨文档查询共 5 条。它们不再指向单一文档而是要求系统在多个文档之间建立横向关联Which agreements include confidentiality or data protection provisions?What are the common termination notice periods across different contract types?Which documents specify insurance or liability coverage requirements?What compliance and regulatory requirements are mentioned across agreements?Which contracts include performance metrics or service level commitments?这类查询对 Context Builder 的挑战在于find_relevant_passages见 context_builder.py默认只取top_k3个片段当答案分散在多份文档中时检索阶段必须优先返回跨文档的高价值片段否则最终回答会出现遗漏。测试时可结合 Jaeger 中该请求的完整 span 链观察 Context Builder 选中了哪些文档索引从而判断 top_k 是否需要对跨文档查询场景放大。复杂分析查询评估推理与综合能力第四类共 5 条属于对系统综合能力的压力测试要求检索结果支撑对比与归纳Compare the data retention policies across the privacy policy and student data management documents.What are the different approaches to risk management across the supply chain and investment advisory agreements?How do the security measures in the healthcare standards compare to those in the privacy policy?Which agreements provide the most detailed compliance and regulatory frameworks?What common themes exist in the quality assurance requirements across different industries?这类查询的评估要点不在是否答对某一数字而在检索片段是否同时覆盖被比较的多份文档。如果回答只引用了单份文档说明 Query Rewriter 未能把compare ... across ...结构转换为并列的多目标检索。从源码看重写发生在 query_rewriter.py其 system prompt 明确要求rewrite the last user message to be more specific and context-aware因此复杂分析查询是检验重写质量最直接的探针。文档细节抽取查询深度召回与信息完整性审计最后一类共 5 条聚焦文档中所有相关细节的穷举式抽取List all the specific percentages, timeframes, and numerical requirements mentioned in the SLA.What are all the contact persons and their roles mentioned across the documents?Identify all the compliance standards and certifications referenced in the supply chain agreement.What are the specific consequences or penalties mentioned for non-compliance across agreements?List all the third-party systems, tools, or services mentioned in the documents.这类查询用于审计信息完整性。以列出 SLA 中所有百分比与时限为例正确答案应包含 99.9% 正常运行时间、200ms API 平均响应、1 小时/4 小时支持响应、10% 月度费用抵扣、5% 月度积分等全部数值。由于 Context Builder 注入上下文时会将片段截断为前 500 字符见 context_builder.py长文档的细节可能被截断此类查询恰好能暴露片段长度与 top_k 配置的不足是调优find_relevant_passages参数的直接依据。完整查询清单40 条测试用例速查将 sample_queries.md 中的全部查询整理为下表可直接作为回归测试清单类别数量核心检索意图对应知识库文档Service Level Agreement Queries5SLA 数值条款与签署信息TechCorp 云服务 SLA 协议Privacy Policy Queries5加密、留存、用户权利、数据出售边界DataSecure 隐私政策 v3.2Supply Chain Agreement Queries5供应品类、付款条款、质量标准、违约罚则PrecisionParts 供应链协议Student Data Management Queries5联邦法律、安全措施、留存期限、未成年人同意EduTech 学生数据管理规范Investment Advisory Queries5费用结构、监管机构、审查频率、客户义务FinanceFirst 投资咨询协议Healthcare Standards Queries5响应时限、合规率、病历完成时限、培训要求医疗机构标准规范Cross-Document Queries5保密条款、终止通知期、保险责任、合规要求横向对比跨多份文档Complex Analysis Queries5数据留存、风险管理、安全措施等跨文档对比跨多份文档Document-Specific Detail Queries5百分比/时限穷举、联系人、合规认证、违约后果枚举单份或多份文档测试执行建议基线测试先逐条发送全部 40 条查询将回答人工标注为完整命中 / 部分命中 / 未命中形成基线模块化定位任一查询失败时对照 Jaeger 中的链路分别检查 Input Guards 是否误拦截返回 400out_of_scope、Query Rewriter 是否丢失关键约束、Context Builder 选中的片段索引是否覆盖答案所在文档参数回归修改top_k、知识库 CSV 内容或各过滤器使用的模型gpt-4o-mini与gpt-4o的别名在 config.yaml 的model_aliases中定义后重跑清单对比命中率变化。扩展把查询集复用到你的知识库sample_queries.md的价值在于其方法论可迁移无需修改任何代码即可应用于其他知识库。只需遵循同样的设计维度单文档维度为每份重要文档设计 5 条精确事实查询数值、人名、日期、义务覆盖文档的关键章节跨文档维度设计涉及至少两份文档的横向问题验证多源召回复杂分析维度加入 compare / contrast / common themes 类问题测试综合推理细节穷举维度以list all ... mentioned句式审计信息完整性暴露检索截断与 top_k 不足。更换知识库时只需替换 src/rag_agent/sample_knowledge_base.csv 的path,content两列内容并相应调整 input_guards.py 中 TechCorp 领域白名单的 system prompt将 TechCorp 业务域描述替换为目标领域其余过滤器链代码无需改动即可得到一套面向新场景的检索评估环境。小结sample_queries.md虽然只是一个查询列表但在 Plano 的 HTTP 过滤器链演示中承担着验收测试用例集的角色单文档查询验证精确召回跨文档查询验证多源关联复杂分析查询验证综合推理细节抽取查询验证信息完整性。将它与 config.yaml、三个 HTTP 过滤器源码以及 Jaeger 追踪配合使用你可以对任何 RAG 系统的检索质量建立可量化、可回归的评估基线这也是该演示项目为知识库类应用提供的最实用的工程资产。【免费下载链接】planoPlano is an AI-native proxy server and data plane for agentic apps. Smart LLM routing, observability, agent orchestration, and guardrails so you stay focused on your agents core logic.项目地址: https://gitcode.com/GitHub_Trending/ar/plano创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
