一、前言

本次完成cognitive_retrieval_rag认知检索  Agent 开发，搭建一套智能路由分类 + 本地知识库检索 + 大模型增强问答的完整程序。 项目采用模块化拆分，内置发票、维修工单两套业务知，自动判断问题归属知识库并检索内容，交给大模型结合资料作答。 下面完整记录项目文件、代码、报错解决、运行效果全流程。

简短说明本文完成路由 RAG 系统，解决模块缺失、大模型忽略知识库两大核心 bug，附完整可运行源码。

本 RAG 完整执行链路： 用户输入问题 → 智能路由大模型判断问题分类（发票 / 维修 / 通用）→ 根据分类进入对应知识库检索文本 → 检索结果拼接为上下文传入 LLM → 大模型仅依据参考文档输出答案 → 记录路由分类、检索条数、总耗时。

二、项目环境准备

1. 安装依赖包

打开终端执行安装命令：pip install zhipuai python-dotenv

2.项目目录结构

所有文件必须放在同一个文件夹下，缺一不可，否则会报模块缺失错误：

main.py  # 程序入口、测试用例

 rag_agent.py # Agent核心调度类

 mock_retriever.py # 模拟向量知识库（解决No module报错）

simple_router.py # 智能路由分类模块

simple_zhipu_client.py # 智谱大模型调用封装

.env # 存放智谱API密钥

注：.env文件，填入自己在智谱开放平台申请的 key：

ZHIPUAI_API_KEY=你的智谱API Key

三、运行代码过程

1.mock_retriever.py 简易内存模拟向量库，替代真实向量数据库，用于课程演示，实现文档新增、关键词检索功能

2.  simple_router.py 轻量分类器，利用大模型实现问题自动分库，避免全库检索浪费资源。

3.simple_zhipu_client.py

4.rag_agent.py 整体调度中心，串联路由、检索、大模型三大模块，统一封装 handle 对外接口。

5.main.py

                 

四.踩坑记录：运行报错解决方案

报错 1：ModuleNotFoundError: No module named 'mock_retriever'

报错截图：

解决：在同目录新建mock_retriever.py，粘贴上方完整代码，保证所有自定义模块文件齐全。

报错 2：大模型无视检索文档，一直回复 “无法查询数据库”

LLM 调用时没有添加强制约束提示词

解决：使用本文提供的simple_zhipu_client.py，内置强约束 Prompt，强制模型基于文档作答。

本项目当前是内存 Mock 知识库，可替换 Chroma、FAISS 真实向量数据库，实现持久化向量存储

五.项目总结

本项目完整实现工程化 RAG  基础框架，核心流程： 用户提问 → 智能路由分类索引 → 知识库检索召回文本 → 上下文注入 LLM 精准问答。