尧图网站建设 
构建 RAG SQL 混合查询路由 Agent基于 LlamaIndex、Milvus 与 Cleanlab Codex 的可信输出实践【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub本篇技术指南基于仓库 rag-sql-router 的完整实现讲解如何构建一个既能查询向量数据库RAG 检索、又能执行结构化 SQL 查询的自定义路由 Agent。文章将从环境搭建、工具封装、路由工作流到 Streamlit 交互应用逐层展开并结合仓库源码揭示底层调用链重点剖析 Cleanlab Codex 如何为 AI 输出提供自动响应验证与可信度评分帮助读者掌握Text2SQL RAG混合智能体从 0 到 1 的实战方案。一、系统概览为什么需要路由而不是全都要传统方案往往让一个 Agent 同时绑定多个数据源但不同类型的问题本质需要不同的查询路径结构化数据问题如休斯顿的人口是多少需要精确的 SQL 聚合与过滤容错空间极小非结构化文档问题如这份报告里关于营收的结论是什么需要语义检索与片段合成答案天然具有模糊性。本项目的核心思想是把两类能力封装为两个独立工具——sql_tool与document_tool再由 LLM 依据用户问题的语义自动选择路由调用哪一个从而兼顾精确性与灵活性。仓库 README.md 明确指出该系统引导你创建一个自定义 Agent它可以查询Vector DB 索引RAG 检索也可以查询独立的 SQL 查询引擎。与此同时README 强调了整个系统最关键的组件——响应验证Response Validation当所有人都在构建 Agent 时没有人告诉你如何确保它们的输出是可靠的。 这正是 Cleanlab Codex 在本项目中的角色对每一次查询与回答进行自动校验为输出提供可信度评分并允许领域专家SME介入改进。二、技术栈一览根据 README.md 与 pyproject.toml本项目的核心依赖如下组件用途仓库中的证据LlamaIndexllama-index0.12.52Agent 编排、Query Engine、Workflow 框架workflow.pyDoclingllama-index-readers-docling简化 PDF/DOCX/PPTX 文档解析tools.pyMilvus PyMilvuspymilvus2.5.14自托管向量数据库tools.pyCleanlab Codexcleanlab-codex1.0.26响应验证与可信度保障tools.pyOpenRouter AIllama-index-llms-openrouter访问阿里 Qwen 模型app.pySQLAlchemysqlalchemy2.0.42SQLite 连接与查询tools.pyStreamlitstreamlit1.47.1交互式 Web 界面app.pyHuggingFace Embeddingsllama-index-embeddings-huggingface语义向量化BAAI/bge-small-en-v1.5app.py项目要求 Python3.12。此外还依赖nest-asyncio让 Streamlit 环境下可运行 asyncio、pandas与plotly数据库可视化、torch嵌入模型推理。三、环境搭建三步跑通3.1 启动 Milvus 向量数据库Milvus 官方提供了 Docker 容器安装脚本。按 README.md 的操作执行curl -sfL https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh -o standalone_embed.sh bash standalone_embed.sh start脚本会以 Docker 方式拉起 Milvus standalone 实例默认监听http://localhost:19530——这也是 tools.py 中setup_document_tool默认的milvus_uri参数值。如果 Milvus 未启动文档向量化与索引写入将无法完成。3.2 安装依赖仓库使用 uv 管理依赖uv sync该命令会依据 pyproject.toml 与uv.lock锁定文件创建虚拟环境并安装全部依赖。3.3 两条运行路径Jupyter Notebook 体验运行 notebook.ipynb该笔记本完整演示了路由routing、工具调用tool calling与响应验证validating responses三大主题Streamlit 应用执行以下命令启动交互界面streamlit run app.py然后在浏览器访问http://localhost:8501。四、Cleanlab Codex让 AI 输出可信的关键组件README 将 Cleanlab Codex 定位为系统最关键的组件并总结其五大价值自动检测自动识别 AI 产生的不准确/无帮助响应持续改进领域专家SME无需工程介入即可直接改进响应可信度评分为每次响应提供可靠性指标实时验证实时校验查询与响应分析追踪改进率与响应质量随时间的变化。4.1 在本系统中的工作流程README 描述了四步闭环查询处理你的查询由 Cleanlab Codex 自动验证响应验证AI 响应被评分衡量可靠性与准确性SME 介入领域专家可通过 Codex 界面改进响应持续学习系统从已验证的响应中学习服务后续查询。4.2 源码中的验证调用链从 tools.py 可以看到完整的落地实现。首先create_codex_projectL24-L44通过环境变量CODEX_API_KEY初始化客户端创建命名项目并生成访问密钥若缺少 API Key则打印警告并优雅降级Codex 验证被禁用RAG 返回基础答案。document_query_toolL191-L260是验证的核心result codex_project.validate( messagesmessages, queryquery, contextcontext_str, responseinitial_response, )validate接收完整上下文检索到的源片段拼接、用户问题与初始回答返回一个包含多维度评估结果的对象。随后代码执行最终响应选择逻辑final_response ( result.expert_answer if result.expert_answer and result.escalated_to_sme else ( fallback_response if result.should_guardrail else initial_response ) ) trust_score result.model_dump()[eval_scores][trustworthiness][score]也就是说若 Codex 判断需要升级给专家escalated_to_sme且专家已给出答案则采用专家答案若触发了护栏should_guardrail则返回兜底文案否则保留原始 RAG 响应。可信度分数从eval_scores.trustworthiness.score中提取与最终响应一并打包成字典返回供上层工作流展示。五、双工具封装SQL 引擎与文档检索引擎的源码级解析所有工具定义集中在 tools.py 中并通过 LlamaIndex 的QueryEngineTool与FunctionTool统一暴露给 Agent。5.1setup_sql_tool自然语言 → SQLdef setup_sql_tool(db_pathcity_database.sqlite, table_namecity_stats): engine create_engine(fsqlite:///{db_path}) sql_database SQLDatabase(engine) sql_query_engine NLSQLTableQueryEngine( sql_databasesql_database, tables[table_name], ) sql_tool QueryEngineTool.from_defaults( query_enginesql_query_engine, namesql_tool, description( Useful for translating a natural language query into a SQL query over a table containing: city_stats, containing the population/state of each city located in the USA. ), ) return sql_tool要点数据源为仓库自带的 city_database.sqlite其中city_stats表包含city_name、population、state三列前几条数据如 New York City / 8,336,000 / New YorkNLSQLTableQueryEngine负责把自然语言翻译成 SQL 并执行工具描述description是路由成败的关键LLM 正是依据这段描述判断人口/州类问题应交给sql_tool。5.2setup_document_toolDocling Milvus Codex 三合一def setup_document_tool(file_dir, session_idNone, milvus_urihttp://localhost:19530): reader, node_parser DoclingReader(), MarkdownNodeParser() loader SimpleDirectoryReader( input_dirfile_dir, file_extractor{.pdf: reader, .docx: reader, .pptx: reader, .txt: reader}, ) docs loader.load_data() unique_collection_id uuid.uuid4().hex collection_name frag_with_sql_{unique_collection_id} vector_store MilvusVectorStore(urimilvus_uri, dim384, overwriteTrue, collection_namecollection_name) storage_context StorageContext.from_defaults(vector_storevector_store) vector_index VectorStoreIndex.from_documents( docs, show_progressTrue, transformations[node_parser], storage_contextstorage_context, )关键实现细节环节实现说明文档解析DoclingReader统一处理 PDF/DOCX/PPTX/TXT 四种格式节点切分MarkdownNodeParser按 Markdown 结构切分节点向量存储MilvusVectorStore每个会话生成唯一 collectionrag_with_sql_uuidoverwriteTrue向量维度dim384与 bge-small-en-v1.5 输出维度一致检索策略similarity_top_k3取最相关的 3 个片段检索后使用自定义 QA 提示模板约束生成——要求模型严格基于上下文作答、不引用先验知识、上下文不足时明确说明随后进入上一节的 Codex 验证流程。最终通过FunctionTool.from_defaults封装为document_tool其描述明确引导 LLM如果用户问题与 US 城市统计人口和州无关请使用本文档检索工具。5.3 Codex 项目的会话级复用get_or_create_codex_projectL54-L69通过全局变量缓存 Codex 项目同一会话内复用新会话不同session_id才重新创建避免频繁创建项目造成资源浪费。六、RouterOutputAgentWorkflow事件驱动的路由 Agent路由编排位于 workflow.py它继承 LlamaIndex 的Workflow基类是一个基于事件Event与步骤Step的异步工作流。6.1 事件与步骤拓扑事件作用InputEvent输入事件触发 LLM 决策GatherToolsEvent携带 LLM 选中的工具调用列表ToolCallEvent单个工具调用任务ToolCallEventResult单个工具调用的结果消息四个核心步骤构成循环prepare_chat从StartEvent取出message追加到聊天历史chat调用self.llm.achat_with_tools(self.tools, ...)把两个工具交给 LLM 决策。allow_parallel_tool_callsTrue允许并行调用若没有工具调用则直接返回StopEventdispatch_calls把每个ToolSelection广播为独立的ToolCallEvent通过ctx.send_event支持并发执行call_tool从tools_dict找到对应工具并执行await tool.acall(**tool_call.tool_kwargs)。特别地当工具返回包含response与trust_score的字典时文档工具会将其拆解并写入ChatMessage.additional_kwargs把可信度分数透传到上层 UIgather使用ctx.collect_events聚合所有工具结果追加回聊天历史然后重新触发InputEvent让 Agent 基于工具结果进行下一轮推理——直到 LLM 认为无需再调用工具输出最终答案。从 workflow.py 的构造函数可见工作流支持timeout默认 10s应用层传 120s、disable_validation、verbose等参数并可从Settings.llm兜底获取 LLM。工作流的运行轨迹可通过draw_all_possible_flows可视化见 notebook.ipynb产物即为仓库中的 workflow_all_flows.html。七、Streamlit 应用从配置到交互的完整闭环app.py 提供了完整的图形化界面结构清晰可拆解为三部分。7.1 侧边栏配置面板用户需在侧边栏填入两个密钥均为密码输入框Codex API Key写入os.environ[CODEX_API_KEY]用于响应验证OpenRouter API Key用于初始化 LLM。模型初始化逻辑L372-L383为llm OpenRouter(modelqwen/qwen-turbo, api_key_api_key) embed_model HuggingFaceEmbedding(model_nameBAAI/bge-small-en-v1.5)随后赋值给全局Settings.llm与Settings.embed_model供工作流与查询引擎使用。7.2 文档上传与工作流组装应用支持一次上传多个文档pdf/docx/pptx/txt保存到临时目录后调用setup_document_tool构建文档工具。工具组装遵循SQL 优先原则L670-L686tools [setup_sql_tool()] # ... 若已上传文档则追加 document_tool之后用RouterOutputAgentWorkflow(toolstools, verboseFalse, timeout120)初始化工作流并缓存于st.session_state中当密钥或文档变化时置workflow_needs_update标记以触发重建。7.3 聊天界面与可信度可视化process_queryL438-L520通过asyncio.wait_for(..., timeout60.0)包裹工作流运行防止请求挂起。返回结果时会从聊天历史中提取工具消息判断走的是document_tool还是sql_tool并展示信任度≥70%显示 绿色≥50%显示 黄色50%显示 红色。信任度按round(trust_score * 100, 1)换算为百分比。聊天区还提供Reset Chat按钮一键清空历史并重建工作流。7.4 数据库可视化看板点击View Database可展开完整的数据洞察面板render_database_tab包括指标卡城市总数、总人口、州数量、平均人口图表Top 10 人口柱状图、州分布环形图、人口散点图Plotly 实现Schema 展示通过PRAGMA table_info读取表结构自定义 SQL内置 6 条预置查询如 Top 10 cities by population、Cities with population 1M也支持手写 SQL结果可下载为 CSV。八、运行验证路由决策的实际表现notebook.ipynb 内置了两个典型测试用例展示了路由与验证的实际效果用例 1结构化问题 → 路由到 sql_toolCalling function sql_tool with msg {input: What is the population of Houston, Texas?} Chat message: The population of Houston, Texas is 2,303,000.与city_stats表中 Houston 的记录2,303,000完全吻合验证了 Text2SQL 路径的精确性。用例 2非结构化问题 → 路由到 document_toolCalling function document_tool with msg {query: What is the weather in California?} Chat message: The provided context does not have enough information to answer the question about the weather in California.由于文档上下文中没有天气信息自定义 QA 模板的第三条规则触发——模型如实声明上下文不足以回答而不是编造答案。这正是响应验证与护栏机制的价值所在宁可拒绝也不幻觉。九、扩展思考与最佳实践从本仓库实现可以提炼出以下可复用的工程经验工具描述即路由策略LLM 完全依赖description决定调用哪个工具务必用清晰、互斥的语言描述每个工具的适用边界本项目中 SQL 工具明确限定于美国城市人口/州文档工具则声明与城市统计无关的问题用我验证层与推理层解耦RAG 检索 → Codex 验证 → 最终响应的三段式设计让生成与把关分离专家答案与护栏可以随时介入无需改动检索链路优雅降级CODEX_API_KEY缺失时系统自动退回基础 RAGMilvus 不可用时查询引擎同样会报错提示保证任何环节故障都不至于静默产出低质量答案会话隔离Milvus collection 与 Codex project 均按会话uuid隔离避免多用户数据串扰。需要说明的是本项目展示的是单表city_stats的 SQL 路由与通用文档 RAG 的组合若需扩展到多表数据库或更多知识源可在此基础上按同样的工具封装 事件工作流模式继续叠加而验证层Cleanlab Codex保持不变。十、结语rag-sql-router提供了一个完整可运行的Text2SQL RAG混合 Agent 参考实现LlamaIndex 负责编排与检索Docling 负责文档解析Milvus 提供自托管向量存储OpenRouter 接入 Qwen 模型而 Cleanlab Codex 则补齐了多数教程缺失的一环——输出可靠性保障。无论你是要构建企业级文档问答还是希望在现有 RAG 系统上叠加结构化查询能力本仓库的 tools.py、workflow.py 与 app.py 都是值得直接参考的工程范本。【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 构建 RAG + SQL 混合查询路由 Agent：基于 LlamaIndex、Milvus 与 Cleanlab Codex 的可信输出实践
构建 RAG SQL 混合查询路由 Agent基于 LlamaIndex、Milvus 与 Cleanlab Codex 的可信输出实践【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub本篇技术指南基于仓库 rag-sql-router 的完整实现讲解如何构建一个既能查询向量数据库RAG 检索、又能执行结构化 SQL 查询的自定义路由 Agent。文章将从环境搭建、工具封装、路由工作流到 Streamlit 交互应用逐层展开并结合仓库源码揭示底层调用链重点剖析 Cleanlab Codex 如何为 AI 输出提供自动响应验证与可信度评分帮助读者掌握Text2SQL RAG混合智能体从 0 到 1 的实战方案。一、系统概览为什么需要路由而不是全都要传统方案往往让一个 Agent 同时绑定多个数据源但不同类型的问题本质需要不同的查询路径结构化数据问题如休斯顿的人口是多少需要精确的 SQL 聚合与过滤容错空间极小非结构化文档问题如这份报告里关于营收的结论是什么需要语义检索与片段合成答案天然具有模糊性。本项目的核心思想是把两类能力封装为两个独立工具——sql_tool与document_tool再由 LLM 依据用户问题的语义自动选择路由调用哪一个从而兼顾精确性与灵活性。仓库 README.md 明确指出该系统引导你创建一个自定义 Agent它可以查询Vector DB 索引RAG 检索也可以查询独立的 SQL 查询引擎。与此同时README 强调了整个系统最关键的组件——响应验证Response Validation当所有人都在构建 Agent 时没有人告诉你如何确保它们的输出是可靠的。 这正是 Cleanlab Codex 在本项目中的角色对每一次查询与回答进行自动校验为输出提供可信度评分并允许领域专家SME介入改进。二、技术栈一览根据 README.md 与 pyproject.toml本项目的核心依赖如下组件用途仓库中的证据LlamaIndexllama-index0.12.52Agent 编排、Query Engine、Workflow 框架workflow.pyDoclingllama-index-readers-docling简化 PDF/DOCX/PPTX 文档解析tools.pyMilvus PyMilvuspymilvus2.5.14自托管向量数据库tools.pyCleanlab Codexcleanlab-codex1.0.26响应验证与可信度保障tools.pyOpenRouter AIllama-index-llms-openrouter访问阿里 Qwen 模型app.pySQLAlchemysqlalchemy2.0.42SQLite 连接与查询tools.pyStreamlitstreamlit1.47.1交互式 Web 界面app.pyHuggingFace Embeddingsllama-index-embeddings-huggingface语义向量化BAAI/bge-small-en-v1.5app.py项目要求 Python3.12。此外还依赖nest-asyncio让 Streamlit 环境下可运行 asyncio、pandas与plotly数据库可视化、torch嵌入模型推理。三、环境搭建三步跑通3.1 启动 Milvus 向量数据库Milvus 官方提供了 Docker 容器安装脚本。按 README.md 的操作执行curl -sfL https://raw.githubusercontent.com/milvus-io/milvus/master/scripts/standalone_embed.sh -o standalone_embed.sh bash standalone_embed.sh start脚本会以 Docker 方式拉起 Milvus standalone 实例默认监听http://localhost:19530——这也是 tools.py 中setup_document_tool默认的milvus_uri参数值。如果 Milvus 未启动文档向量化与索引写入将无法完成。3.2 安装依赖仓库使用 uv 管理依赖uv sync该命令会依据 pyproject.toml 与uv.lock锁定文件创建虚拟环境并安装全部依赖。3.3 两条运行路径Jupyter Notebook 体验运行 notebook.ipynb该笔记本完整演示了路由routing、工具调用tool calling与响应验证validating responses三大主题Streamlit 应用执行以下命令启动交互界面streamlit run app.py然后在浏览器访问http://localhost:8501。四、Cleanlab Codex让 AI 输出可信的关键组件README 将 Cleanlab Codex 定位为系统最关键的组件并总结其五大价值自动检测自动识别 AI 产生的不准确/无帮助响应持续改进领域专家SME无需工程介入即可直接改进响应可信度评分为每次响应提供可靠性指标实时验证实时校验查询与响应分析追踪改进率与响应质量随时间的变化。4.1 在本系统中的工作流程README 描述了四步闭环查询处理你的查询由 Cleanlab Codex 自动验证响应验证AI 响应被评分衡量可靠性与准确性SME 介入领域专家可通过 Codex 界面改进响应持续学习系统从已验证的响应中学习服务后续查询。4.2 源码中的验证调用链从 tools.py 可以看到完整的落地实现。首先create_codex_projectL24-L44通过环境变量CODEX_API_KEY初始化客户端创建命名项目并生成访问密钥若缺少 API Key则打印警告并优雅降级Codex 验证被禁用RAG 返回基础答案。document_query_toolL191-L260是验证的核心result codex_project.validate( messagesmessages, queryquery, contextcontext_str, responseinitial_response, )validate接收完整上下文检索到的源片段拼接、用户问题与初始回答返回一个包含多维度评估结果的对象。随后代码执行最终响应选择逻辑final_response ( result.expert_answer if result.expert_answer and result.escalated_to_sme else ( fallback_response if result.should_guardrail else initial_response ) ) trust_score result.model_dump()[eval_scores][trustworthiness][score]也就是说若 Codex 判断需要升级给专家escalated_to_sme且专家已给出答案则采用专家答案若触发了护栏should_guardrail则返回兜底文案否则保留原始 RAG 响应。可信度分数从eval_scores.trustworthiness.score中提取与最终响应一并打包成字典返回供上层工作流展示。五、双工具封装SQL 引擎与文档检索引擎的源码级解析所有工具定义集中在 tools.py 中并通过 LlamaIndex 的QueryEngineTool与FunctionTool统一暴露给 Agent。5.1setup_sql_tool自然语言 → SQLdef setup_sql_tool(db_pathcity_database.sqlite, table_namecity_stats): engine create_engine(fsqlite:///{db_path}) sql_database SQLDatabase(engine) sql_query_engine NLSQLTableQueryEngine( sql_databasesql_database, tables[table_name], ) sql_tool QueryEngineTool.from_defaults( query_enginesql_query_engine, namesql_tool, description( Useful for translating a natural language query into a SQL query over a table containing: city_stats, containing the population/state of each city located in the USA. ), ) return sql_tool要点数据源为仓库自带的 city_database.sqlite其中city_stats表包含city_name、population、state三列前几条数据如 New York City / 8,336,000 / New YorkNLSQLTableQueryEngine负责把自然语言翻译成 SQL 并执行工具描述description是路由成败的关键LLM 正是依据这段描述判断人口/州类问题应交给sql_tool。5.2setup_document_toolDocling Milvus Codex 三合一def setup_document_tool(file_dir, session_idNone, milvus_urihttp://localhost:19530): reader, node_parser DoclingReader(), MarkdownNodeParser() loader SimpleDirectoryReader( input_dirfile_dir, file_extractor{.pdf: reader, .docx: reader, .pptx: reader, .txt: reader}, ) docs loader.load_data() unique_collection_id uuid.uuid4().hex collection_name frag_with_sql_{unique_collection_id} vector_store MilvusVectorStore(urimilvus_uri, dim384, overwriteTrue, collection_namecollection_name) storage_context StorageContext.from_defaults(vector_storevector_store) vector_index VectorStoreIndex.from_documents( docs, show_progressTrue, transformations[node_parser], storage_contextstorage_context, )关键实现细节环节实现说明文档解析DoclingReader统一处理 PDF/DOCX/PPTX/TXT 四种格式节点切分MarkdownNodeParser按 Markdown 结构切分节点向量存储MilvusVectorStore每个会话生成唯一 collectionrag_with_sql_uuidoverwriteTrue向量维度dim384与 bge-small-en-v1.5 输出维度一致检索策略similarity_top_k3取最相关的 3 个片段检索后使用自定义 QA 提示模板约束生成——要求模型严格基于上下文作答、不引用先验知识、上下文不足时明确说明随后进入上一节的 Codex 验证流程。最终通过FunctionTool.from_defaults封装为document_tool其描述明确引导 LLM如果用户问题与 US 城市统计人口和州无关请使用本文档检索工具。5.3 Codex 项目的会话级复用get_or_create_codex_projectL54-L69通过全局变量缓存 Codex 项目同一会话内复用新会话不同session_id才重新创建避免频繁创建项目造成资源浪费。六、RouterOutputAgentWorkflow事件驱动的路由 Agent路由编排位于 workflow.py它继承 LlamaIndex 的Workflow基类是一个基于事件Event与步骤Step的异步工作流。6.1 事件与步骤拓扑事件作用InputEvent输入事件触发 LLM 决策GatherToolsEvent携带 LLM 选中的工具调用列表ToolCallEvent单个工具调用任务ToolCallEventResult单个工具调用的结果消息四个核心步骤构成循环prepare_chat从StartEvent取出message追加到聊天历史chat调用self.llm.achat_with_tools(self.tools, ...)把两个工具交给 LLM 决策。allow_parallel_tool_callsTrue允许并行调用若没有工具调用则直接返回StopEventdispatch_calls把每个ToolSelection广播为独立的ToolCallEvent通过ctx.send_event支持并发执行call_tool从tools_dict找到对应工具并执行await tool.acall(**tool_call.tool_kwargs)。特别地当工具返回包含response与trust_score的字典时文档工具会将其拆解并写入ChatMessage.additional_kwargs把可信度分数透传到上层 UIgather使用ctx.collect_events聚合所有工具结果追加回聊天历史然后重新触发InputEvent让 Agent 基于工具结果进行下一轮推理——直到 LLM 认为无需再调用工具输出最终答案。从 workflow.py 的构造函数可见工作流支持timeout默认 10s应用层传 120s、disable_validation、verbose等参数并可从Settings.llm兜底获取 LLM。工作流的运行轨迹可通过draw_all_possible_flows可视化见 notebook.ipynb产物即为仓库中的 workflow_all_flows.html。七、Streamlit 应用从配置到交互的完整闭环app.py 提供了完整的图形化界面结构清晰可拆解为三部分。7.1 侧边栏配置面板用户需在侧边栏填入两个密钥均为密码输入框Codex API Key写入os.environ[CODEX_API_KEY]用于响应验证OpenRouter API Key用于初始化 LLM。模型初始化逻辑L372-L383为llm OpenRouter(modelqwen/qwen-turbo, api_key_api_key) embed_model HuggingFaceEmbedding(model_nameBAAI/bge-small-en-v1.5)随后赋值给全局Settings.llm与Settings.embed_model供工作流与查询引擎使用。7.2 文档上传与工作流组装应用支持一次上传多个文档pdf/docx/pptx/txt保存到临时目录后调用setup_document_tool构建文档工具。工具组装遵循SQL 优先原则L670-L686tools [setup_sql_tool()] # ... 若已上传文档则追加 document_tool之后用RouterOutputAgentWorkflow(toolstools, verboseFalse, timeout120)初始化工作流并缓存于st.session_state中当密钥或文档变化时置workflow_needs_update标记以触发重建。7.3 聊天界面与可信度可视化process_queryL438-L520通过asyncio.wait_for(..., timeout60.0)包裹工作流运行防止请求挂起。返回结果时会从聊天历史中提取工具消息判断走的是document_tool还是sql_tool并展示信任度≥70%显示 绿色≥50%显示 黄色50%显示 红色。信任度按round(trust_score * 100, 1)换算为百分比。聊天区还提供Reset Chat按钮一键清空历史并重建工作流。7.4 数据库可视化看板点击View Database可展开完整的数据洞察面板render_database_tab包括指标卡城市总数、总人口、州数量、平均人口图表Top 10 人口柱状图、州分布环形图、人口散点图Plotly 实现Schema 展示通过PRAGMA table_info读取表结构自定义 SQL内置 6 条预置查询如 Top 10 cities by population、Cities with population 1M也支持手写 SQL结果可下载为 CSV。八、运行验证路由决策的实际表现notebook.ipynb 内置了两个典型测试用例展示了路由与验证的实际效果用例 1结构化问题 → 路由到 sql_toolCalling function sql_tool with msg {input: What is the population of Houston, Texas?} Chat message: The population of Houston, Texas is 2,303,000.与city_stats表中 Houston 的记录2,303,000完全吻合验证了 Text2SQL 路径的精确性。用例 2非结构化问题 → 路由到 document_toolCalling function document_tool with msg {query: What is the weather in California?} Chat message: The provided context does not have enough information to answer the question about the weather in California.由于文档上下文中没有天气信息自定义 QA 模板的第三条规则触发——模型如实声明上下文不足以回答而不是编造答案。这正是响应验证与护栏机制的价值所在宁可拒绝也不幻觉。九、扩展思考与最佳实践从本仓库实现可以提炼出以下可复用的工程经验工具描述即路由策略LLM 完全依赖description决定调用哪个工具务必用清晰、互斥的语言描述每个工具的适用边界本项目中 SQL 工具明确限定于美国城市人口/州文档工具则声明与城市统计无关的问题用我验证层与推理层解耦RAG 检索 → Codex 验证 → 最终响应的三段式设计让生成与把关分离专家答案与护栏可以随时介入无需改动检索链路优雅降级CODEX_API_KEY缺失时系统自动退回基础 RAGMilvus 不可用时查询引擎同样会报错提示保证任何环节故障都不至于静默产出低质量答案会话隔离Milvus collection 与 Codex project 均按会话uuid隔离避免多用户数据串扰。需要说明的是本项目展示的是单表city_stats的 SQL 路由与通用文档 RAG 的组合若需扩展到多表数据库或更多知识源可在此基础上按同样的工具封装 事件工作流模式继续叠加而验证层Cleanlab Codex保持不变。十、结语rag-sql-router提供了一个完整可运行的Text2SQL RAG混合 Agent 参考实现LlamaIndex 负责编排与检索Docling 负责文档解析Milvus 提供自托管向量存储OpenRouter 接入 Qwen 模型而 Cleanlab Codex 则补齐了多数教程缺失的一环——输出可靠性保障。无论你是要构建企业级文档问答还是希望在现有 RAG 系统上叠加结构化查询能力本仓库的 tools.py、workflow.py 与 app.py 都是值得直接参考的工程范本。【免费下载链接】ai-engineering-hubIn-depth tutorials on LLMs, RAGs and real-world AI agent applications.项目地址: https://gitcode.com/GitHub_Trending/ai/ai-engineering-hub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考