基于RAG与语义路由的智能购物助手：从架构设计到部署实践-平芜编程栈

1. 项目概述：一个智能购物助手的诞生

最近在折腾一个挺有意思的项目，叫 ShoppingGPT。简单来说，它就是一个能跟你像朋友一样聊天的智能购物助手。你不再需要在一堆筛选框里点来点去，或者记住拗口的商品型号，直接问它就行。比如，“帮我找找有没有适合夏天穿的、透气一点的白色T恤，预算200块左右”，它就能理解你的意思，从商品库里把符合条件的都翻出来，还能顺便告诉你退货政策是啥。这个项目的核心，就是把当下几个挺火的技术——大语言模型、检索增强生成和语义路由——给揉到了一起，做了一个专门服务于电商场景的对话式应用。如果你对如何用AI给传统应用“加点智能”感兴趣，或者正想自己动手搭一个能理解复杂需求的聊天机器人，那这个项目的拆解应该能给你不少启发。

我之所以花时间研究它，是因为发现很多电商网站的搜索和客服系统还是老一套，关键词匹配不准，多条件查询更是麻烦。而大语言模型的出现，让“用自然语言精准查找商品”这件事变成了可能。ShoppingGPT 这个项目就是一个很好的实践样板，它没有追求大而全的通用AI，而是聚焦在“购物”这个垂直领域，把技术用在了刀刃上。整个项目用 Flask 搭建 Web 界面，后端用 Python 串联起各个 AI 组件，结构清晰，对于想入门 AI 应用开发的开发者来说，是个不错的练手项目。接下来，我就带你从里到外把它拆解明白，包括设计思路、每个模块是怎么工作的、如何部署，以及我趟过的一些坑。

2. 核心架构与设计思路拆解

2.1 为什么是“RAG + 路由”的双引擎模式？

看到 ShoppingGPT 的第一眼，你可能会觉得它就是个套了壳的聊天机器人。但它的核心设计巧思在于，没有把所有问题都扔给一个大语言模型去硬解。想象一下，如果你问“这件衬衫有货吗？”，这是一个需要查询实时数据库的具体问题；而如果你问“今天心情怎么样？”，这只是一个闲聊。让同一个模型去处理这两种截然不同的任务，不仅效率低，而且针对数据库查询这种有固定模式的任务，大模型的输出格式可能不稳定，也容易“胡编乱造”库存信息。

所以，项目采用了“语义路由 + 专属处理链”的双引擎模式。这就像公司前台有一个聪明的接待员（语义路由），听到你的问题后，立刻判断是该转接到技术部（购物代理）还是跟你寒暄几句（闲聊链）。这样做的好处非常明显：

精度与效率兼顾：对于商品查询、政策问答这类有明确答案的任务，用专门的工具（如数据库查询、向量检索）来获取信息，确保答案准确、实时。大模型只负责理解问题、调用工具、组织语言回答，而不是“记忆”或“编造”商品信息。
成本与性能优化：大语言模型的API调用通常是按Token（可以粗略理解为字数）收费且较慢。让大模型去处理简单的问候语，属于“大炮打蚊子”。通过路由分流，复杂的商品查询才动用大模型，简单的闲聊可以用更轻量的方式（虽然本项目仍用了LLM，但理论上可优化）或缓存处理，有效控制成本。
系统更健壮：各司其职，模块化程度高。商品搜索逻辑变了，只需修改ProductSearchTool，不会影响闲聊功能。政策文档更新了，只需重新生成向量库，路由逻辑无需变动。

这个设计模式在AI应用开发中非常普遍，可以称之为“AI Agent”或“智能体”架构。ShoppingGPT 的Shopping Agent就是一个典型的、拥有多个工具（查商品、查政策）的智能体。

2.2 技术栈选型背后的考量

项目选用了一套非常务实且高效的技术组合，每一环都有其道理：

Web框架：Flask。对于一个以API和简单前端交互为主的应用，轻量级的Flask比Django更快速、更灵活。它足够处理路由、渲染模板（聊天界面）和连接后端逻辑，没有不必要的臃肿功能。
核心大模型：Google Gemini API。选择Gemini（特别是gemini-1.5-flash版本），首先是因为其在多轮对话、上下文理解上的能力很强，且API相对稳定易用。flash版本在响应速度和成本上做了优化，非常适合需要快速交互的聊天场景。相较于直接部署开源大模型，使用API省去了昂贵的GPU硬件和复杂的运维成本，让开发者能聚焦在应用逻辑本身。
向量数据库与检索：FAISS。当需要根据政策文档的语义来查找答案时，传统的数据库关键词匹配就力不从心了。FAISS是Meta开源的向量相似性搜索库，特别擅长在内存中快速进行海量向量的最近邻搜索。把政策文档转换成向量存进FAISS，当用户问“退货怎么办？”时，系统会先将问题转换成向量，然后在FAISS里快速找到语义最相近的政策片段，作为上下文喂给大模型生成答案。这就是RAG的典型应用。
结构化数据存储：SQLite。商品信息是高度结构化的（名称、价格、库存等），用关系型数据库来管理是天经地义。SQLite无需单独安装数据库服务，一个文件搞定，简化了项目部署复杂度。对于中小型商品库，它的性能完全足够。
语义路由层：Semantic Router库。这是项目的一个亮点。它不是一个简单的关键词匹配路由器，而是利用文本嵌入（Embedding）技术。系统会预先定义好几条“路由”，比如“闲聊路由”和“购物路由”，并为每条路由计算一个代表性的向量。当用户查询进来时，同样将其转换为向量，然后计算与各条路由向量的余弦相似度。超过阈值，就判定属于该路由。这种方式比基于规则的关键词列表要聪明和健壮得多，能理解“你们这有什么好玩的？”和“推荐点商品”其实属于同类意图。

这套技术栈体现了“专业工具做专业事”的思想，平衡了能力、效率和开发难度。

3. 核心模块深度解析与实操要点

3.1 语义路由：如何听懂用户的“弦外之音”

路由模块是智能的“总开关”。它的输入是一句用户提问，输出是一个决策：该走闲聊，还是该走购物流程。

1. 原理与实现：项目使用了semantic-router这个库。其核心是“嵌入向量”和“余弦相似度”。具体步骤如下：

定义路由（Routes）：在代码中，你会看到类似这样的定义：

from semantic_router import Route chitchat_route = Route( name="chitchat", utterances=[ "你好啊", "今天天气怎么样？", "讲个笑话吧", "你是谁？" ] ) shopping_route = Route( name="shopping", utterances=[ "我想买件衬衫", "有红色的裙子吗？", "价格是多少？", "库存还有吗？" ] )

这些utterances是示例语句，用于刻画这条路由的“语义空间”。

生成路由向量：库会使用配置的嵌入模型（本项目是GoogleGenerativeAIEmbeddings），为每条路由的所有示例语句生成向量，并通常取平均或通过某种聚合方式，得到一条代表该路由的“路由向量”。
查询与匹配：当用户输入新查询时，同样用嵌入模型将其转换为“查询向量”。接着，计算查询向量与每条“路由向量”的余弦相似度。余弦相似度的值在-1到1之间，越接近1表示越相似。
阈值判断：每条路由可以设置一个激活阈值（threshold）。如果查询向量与某条路由向量的相似度超过了其阈值，则触发该路由。如果都没超过，则可以设定一个默认行为（例如，归为闲聊或要求澄清）。

2. 实操要点与坑：

示例语句的质量决定路由精度：utterances不能随便写。要尽可能覆盖用户表达同一意图的不同说法。比如购物路由，除了“买”，还应包含“找”、“看看”、“有没有”、“推荐”等词汇的例句。例句的多样性越好，路由的泛化能力越强。
阈值的调校是个细活：阈值设高了，可能导致一些本应匹配的查询无法触发路由（假阴性）；设低了，则可能把不相干的查询错误归类（假阳性）。需要在测试集上反复调整。一个实用的技巧是，先收集一批真实的用户查询，人工打好标签，然后观察路由系统在这些查询上的相似度分数分布，来确定一个合理的阈值区间。
嵌入模型的选择：本项目用了Google的嵌入模型，效果不错。你也可以尝试OpenAI的text-embedding-3-small，或者开源模型如BAAI/bge-small-zh-v1.5（针对中文）。不同的嵌入模型对语义的理解有差异，会影响路由效果。如果主要服务中文用户，强烈建议评估和测试中文嵌入模型。
处理“骑墙”查询：用户可能会问“那件红色的衬衫，今天天气好像不错？”，这种混合意图的查询如何处理？简单的路由可能难以应对。高级的策略可以是：设置优先级（如购物优先），或者设计一个更复杂的“混合意图处理”路由。在初期，可以统一路由到购物代理，让LLM在上下文中去理解和处理混合意图。

3.2 RAG系统：让AI的回答“有据可查”

RAG（检索增强生成）是解决大模型“幻觉”（胡编乱造）和知识过时问题的利器。ShoppingGPT 里其实包含了两套RAG机制，一套用于政策问答，一套用于商品搜索，但后者更偏向于精确数据库查询。

1. 政策RAG（基于FAISS向量库）：这是经典的RAG流程。

索引阶段（Indexing）：
- 读取policy.txt这类非结构化的政策文档。
- 使用文本分割器（如RecursiveCharacterTextSplitter）将长文档切成语义相对完整的小片段（chunks），比如每段200-300字，并保留一些重叠。
- 使用嵌入模型（同样是GoogleGenerativeAIEmbeddings）为每个文本片段生成向量。
- 将这些向量及其对应的文本片段，存入FAISS索引文件中。这个过程通常在项目初始化时完成（scripts/init_db.py里可能包含此步骤）。
检索与生成阶段（Retrieval & Generation）：
- 当用户提问涉及政策（如“退货需要什么？”），购物代理会调用PolicySearchTool。
- 该工具将用户问题转换为向量，在FAISS索引中执行相似度搜索，找出最相关的K个政策文本片段（例如，top-3）。
- 将这些片段作为“参考上下文”，和用户问题一起，构造成一个提示词（Prompt），发送给Gemini大模型。
- 提示词通常类似：“请基于以下上下文信息回答问题。如果上下文不包含答案，请直接说不知道。上下文：{检索到的政策文本}。问题：{用户原始问题}”。
- LLM基于提供的上下文生成最终答案，从而保证答案来源于真实文档。

2. 商品搜索（基于SQLite的“准RAG”）：商品搜索虽然也用了“检索+生成”的模式，但检索端不是语义搜索，而是更精确的数据库查询。

检索：ProductSearchTool接收来自LLM解析后的查询条件（如color=‘红色’， category=‘裙子’），构造SQL语句（例如：SELECT * FROM products WHERE color LIKE ‘%红%’ AND gender=‘女性’），在SQLite中执行，返回结构化的商品数据。
生成：将查询到的商品列表（可能是JSON或字典格式）交给LLM，让它以更自然、更友好的方式组织成一段话回复给用户。例如，LLM会说：“我找到了3款红色的裙子，分别是A款（价格XX）、B款（价格XX）……您对哪一款更感兴趣呢？” 这同样利用了LLM的文本生成能力，但信息源是精确的数据库查询结果。

3. 实操心得：

文本分块是门艺术：块太大，可能包含无关信息，干扰LLM；块太小，可能割裂了完整语义。需要根据政策文档的结构调整。对于条款清晰的政策，按章节或自然段分割效果就不错。可以尝试不同的分割器和块大小，用一些测试问题来评估检索质量。
“重排序”可以提升精度：简单的向量相似度搜索（FAISS）有时可能漏掉关键信息。一个进阶技巧是“重排序”：先用FAISS快速召回前10个或20个相关片段，再用一个更精细的、专门用于判断相关性的模型（如BAAI/bge-reranker）对这10个片段进行重新打分和排序，只取前3个最相关的送给LLM。这能显著提升上下文质量。
给LLM明确的指令：在Prompt里强调“仅根据上下文回答”和“不知道就说不知道”至关重要，这能极大抑制幻觉。可以设计更严格的Prompt模板。
SQL查询的构造：让LLM将自然语言转换为SQL条件（或函数调用参数）是关键一步。这需要清晰的指令和示例（Few-shot Prompting）。在ProductSearchTool中，应该有一个设计良好的函数描述，告诉LLM这个工具能接受哪些参数（product_name,color,price_range等），LLM在调用时就会尝试去提取这些信息。这部分如果没设计好，会导致查询失败。

3.3 智能体与工具：LLM作为“大脑”与“执行者”的协作

这是LangChain框架（或类似Agent框架）的核心思想。在ShoppingGPT中，Shopping Agent就是一个配备了工具的智能体。

1. 工作流程：

用户输入：“我想找一件适合通勤的蓝色衬衫，价格别超过300。”
路由决策：语义路由将其分类到shopping。
智能体启动：系统创建一个Shopping Agent实例，这个智能体“知道”自己可以调用两个工具：ProductSearchTool和PolicySearchTool。
规划与执行：LLM（Gemini）作为智能体的“大脑”，会分析用户请求：“用户需要通勤用的蓝色衬衫，价格<300。这需要查询商品数据库。” 于是，它决定调用ProductSearchTool，并在内心（通过函数调用规范）组织好调用参数：{“category”: “衬衫”， “color”: “蓝色”， “max_price”: 300}。注意，“适合通勤”这个语义可能无法直接映射为数据库字段，LLM可能会选择忽略，或者在生成最终答案时作为文本描述的过滤器。
工具调用：系统执行工具，即运行数据库查询，返回结果列表。
生成回复：工具执行的结果（商品列表）被返回给LLM。LLM将这些结构化数据组织成一段通顺、友好的中文回复：“为您找到了5件300元以下的蓝色衬衫，其中A款是棉质修身款，比较适合通勤……”。如果用户问“能退货吗？”，智能体则会选择调用PolicySearchTool。

2. 关键配置与经验：

工具描述（Tool Description）：定义工具时，给LLM的描述必须清晰、无歧义。要说明工具的功能、输入参数的名称、类型和含义。例如，ProductSearchTool的描述应该写明：“根据商品名称、颜色、尺寸、价格范围等条件搜索商品。参数color是字符串，表示颜色；max_price是浮点数，表示最高价格。” 这能极大提高LLM调用工具的准确率。
会话记忆（ConversationBufferMemory）：为了让对话有连续性，项目使用了ConversationBufferMemory。它会自动地将对话历史（用户消息和AI回复）保存在一个缓冲区里，并在每次新的对话中，将相关历史作为上下文提供给LLM。这样，当用户说“刚才那件红色的，有更大码吗？”，LLM就能知道“刚才那件红色的”指代的是什么。需要注意的是，记忆会消耗Token，增加成本，对于长对话需要设计更高效的记忆管理策略，如只保留最近N轮对话或总结摘要。
Agent类型：LangChain提供了多种Agent类型（如ZERO_SHOT_REACT_DESCRIPTION,OPENAI_FUNCTIONS等）。本项目可能使用的是OPENAI_FUNCTIONS或类似的兼容Gemini函数调用的类型。选择合适的Agent类型很重要，它决定了LLM如何做决策。对于工具调用清晰的任务，STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION通常是不错的选择，因为它鼓励LLM以结构化的思维链（Reasoning）来思考如何调用工具。

4. 从零开始部署与核心配置实战

4.1 环境搭建与依赖安装

让我们抛开README，从零开始走一遍，你会遇到一些README里没细说的坑。

首先，克隆项目并准备环境：

git clone https://github.com/Hoanganhvu123/ShoppingGPT.git cd ShoppingGPT python -m venv venv # 创建虚拟环境，强烈建议，避免包冲突 # Windows: venv\Scripts\activate # Linux/Mac: source venv/bin/activate

接下来安装依赖。requirements.txt是项目的依赖清单。直接pip install -r requirements.txt可能会遇到第一个坑：版本冲突。特别是像langchain,langchain-google-genai这类活跃的库，版本更新很快，API可能有变动。

避坑指南1：如果安装或运行时出现ImportError或AttributeError，很可能是版本问题。一个稳妥的做法是，先查看项目代码中 import 语句使用的包名，然后去PyPI或GitHub上找该项目最近一个稳定的版本号，手动在requirements.txt中指定。例如，你可能需要将langchain固定为langchain==0.1.0（请根据实际情况替换为稳定版本）。

安装完成后，最关键的一步是配置API密钥。在项目根目录创建.env文件：

GOOGLE_API_KEY=你的_Google_AI_Studio_API密钥

如何获取这个密钥？

访问 Google AI Studio (https://makersuite.google.com/app/apikey)。
登录你的Google账号。
点击“Create API Key”，然后复制生成的密钥。

重要提示：这个密钥等同于密码，务必不要上传到GitHub等公开仓库。.env文件已经被项目.gitignore排除，是安全的。

4.2 数据初始化：构建知识库的基石

项目运行需要两种数据：结构化的商品数据（SQLite）和非结构化的政策数据（FAISS向量库）。初始化脚本scripts/init_db.py很可能负责这两件事。

1. 初始化商品数据库：通常，这个脚本会读取一个预设的CSV或JSON文件（比如data/products.csv），然后将其插入或更新到data/products.db数据库文件中。你需要确保源数据文件存在且格式正确。如果项目没有提供示例数据，你需要自己准备一个。数据库表结构就是前面提到的包含product_code,product_name,price等字段的表。

2. 构建政策向量库：这是更容易出错的一步。脚本需要：

读取data/policy.txt（或类似文件）。
用文本分割器进行分块。
调用Google Embeddings API为每一块文本生成向量（这里会消耗API额度，且如果政策文档很长，可能需要一些时间）。
将向量和文本保存为FAISS索引文件（如policy_faiss.index）和一个存储对应文本的文件（如policy_faiss.pkl）。

避坑指南2：首次运行初始化脚本时，可能会因为网络问题或API配额问题导致嵌入生成失败。建议先用一个很小的policy.txt文件测试。另外，生成FAISS索引是本地操作，但嵌入调用是云端的，请确保.env中的API密钥有效且有足够的配额。

运行初始化命令：

python scripts/init_db.py

观察控制台输出，没有报错且提示“Database initialized successfully”或类似信息，就成功了。检查data/目录下是否生成了products.db和FAISS相关文件。

4.3 运行应用与界面交互

数据准备好后，启动应用就很简单了：

python app.py

默认情况下，Flask应用会在http://localhost:5000启动。打开浏览器访问这个地址，你应该能看到一个简洁的聊天界面。

进行测试：

闲聊测试：输入“你好”，应该会收到一个友好的问候回复。这走的是chitchat路由和链。
商品查询测试：输入“有没有黑色的裤子？”。系统应该能理解意图，并调用商品搜索工具，返回数据库中的黑色裤子信息。回复应该是结构化的商品列表，而不是一句“是的，我们有”。
政策查询测试：输入“商品坏了怎么退换？”。系统应该能从政策文档中检索相关信息，并生成包含具体条款的回复。
混合意图测试：输入“推荐一件衬衫，另外如果尺寸不合适能换吗？”。这是一个很好的集成测试，看智能体是否能先后或同时调用商品搜索和政策搜索工具，并组织成一个连贯的回答。

实操心得：在本地测试时，注意观察控制台的日志。你会看到路由决策的过程（触发了哪条路由）、智能体思考的步骤（决定调用哪个工具）、工具调用的参数以及最终的Token消耗。这些日志是调试和理解系统行为的宝贵信息。

5. 定制化开发与高级调优指南

5.1 接入你自己的商品数据

这是最常见的定制需求。你需要准备一个包含所需字段的商品列表，可以是一个CSV文件。然后，修改scripts/init_db.py或编写一个新的数据导入脚本。

关键步骤：

连接数据库：使用Python的sqlite3库连接到data/products.db。

创建表（如果尚未创建）：确保表结构匹配。SQL语句类似：

CREATE TABLE IF NOT EXISTS products ( product_code TEXT PRIMARY KEY, product_name TEXT NOT NULL, material TEXT, size TEXT, color TEXT, brand TEXT, gender TEXT, stock_quantity INTEGER, price REAL );

读取并插入数据：使用pandas读取CSV，然后遍历每一行，执行INSERT OR REPLACE语句。注意处理可能存在的空值。
建立索引：为了加速搜索，特别是对product_name,color,brand等常用查询字段，应该在数据库表上创建索引。这能大幅提升ProductSearchTool的响应速度。可以在初始化脚本中加入：
```
CREATE INDEX IF NOT EXISTS idx_product_name ON products(product_name); CREATE INDEX IF NOT EXISTS idx_color ON products(color); -- 根据需要添加其他索引
```

5.2 优化语义路由的准确性

如果你发现路由经常出错，比如把购物问题误判为闲聊，可以按以下步骤优化：

丰富示例语句：仔细检查chitchat_route和shopping_route的utterances列表。收集更多真实场景下的用户问法，特别是那些容易混淆的。例如，购物路由可以加入“这个怎么卖？”、“有货吗？”、“多少钱？”、“介绍一下这款产品”。闲聊路由可以加入“在干嘛？”、“吃了吗？”、“最近怎么样？”。
调整相似度阈值：semantic-router库允许为每条路由设置独立的阈值。通过测试集来调整。写一个测试脚本，输入一批已标注的查询，计算它们到各路由的相似度，观察分布。如果发现很多购物查询对购物路由的相似度在0.7-0.8，而对闲聊路由的相似度在0.3-0.4，那么将购物路由的阈值设在0.65左右可能比较安全。
引入“拒识”或“默认”路由：对于相似度低于所有路由阈值的查询，可以设置一个default_route，比如指向一个让用户澄清问题的处理链，或者直接归为闲聊。避免系统因为无法决策而报错。
使用更专业的分类模型：项目提到了一个Hugging Face模型hang1704/opendaisy。这是一个更重型但可能更准确的方案。你可以将这个模型集成进来，替代或辅助基于嵌入的语义路由。例如，先用这个模型做一个粗分类（购物/非购物），对于非购物类，再用语义路由细分是闲聊还是其他（如客服投诉）。这种级联结构可以提高整体精度。

5.3 提升RAG检索质量

如果政策问答的答案总是不太准，可以从检索环节入手：

优化文本分块：尝试不同的分块策略。对于政策文档，按章节或条款分块可能比固定字符长度分块更好。使用RecursiveCharacterTextSplitter并调整chunk_size（如500）和chunk_overlap（如50），保留一些上下文重叠有助于避免割裂关键信息。
尝试不同的嵌入模型：Google的嵌入模型对英文支持很好，但对中文的语义理解可能不是最优。可以尝试切换为开源的、针对中文优化的嵌入模型，如BAAI/bge-small-zh-v1.5。这需要修改初始化脚本中创建嵌入模型的部分，以及后续检索时使用的模型。注意，更换模型后，需要重新生成FAISS向量库。
实现重排序（Reranking）：如前所述，这是一个效果显著的进阶技巧。在检索到top-K（比如10个）片段后，使用一个重排序模型（Cross-Encoder）对这K个片段与问题的相关性进行精细打分，重新排序，只取前2-3个最相关的片段送入LLM。虽然增加了计算开销，但能显著提升注入上下文的精度，尤其当政策文档很长时。
优化Prompt模板：检查PolicySearchTool中构造给LLM的Prompt。确保它包含了强指令，例如：“你是一个严谨的客服助手，必须严格根据以下提供的公司政策上下文来回答问题。上下文之外的信息，一律回答‘根据现有政策，我无法提供相关信息’。请先判断用户的提问是否能在上下文中找到依据，然后再作答。” 清晰的指令能更好地约束LLM的行为。

5.4 扩展智能体的能力

现有的智能体只有“查商品”和“查政策”两个工具。你可以很容易地为它添加新工具，使其更强大。

例如，添加一个“订单状态查询”工具：

定义工具函数：编写一个函数，接收用户ID或订单号作为参数，连接你的订单数据库，返回订单状态。

def query_order_status(order_id: str) -> str: # 连接数据库，查询 order_id 的状态 # 返回格式化字符串，如“订单{order_id}当前状态为：已发货，物流单号是XXX。” pass

封装为LangChain Tool：使用StructuredTool.from_function或Tool类，将这个函数封装成一个工具，并给出清晰的描述和参数模式。

from langchain.tools import StructuredTool order_tool = StructuredTool.from_function( func=query_order_status, name="OrderStatusQuery", description="根据用户提供的订单号查询订单的当前状态（如待付款、已发货、已完成等）。输入应为有效的订单号字符串。", # args_schema 可以定义更详细的参数结构 )

将新工具加入智能体：在创建Shopping Agent时，将order_tool也加入到工具列表中。
更新路由或意图识别：用户可能会问“我的订单123456到哪了？”。你需要在语义路由中增加一个“订单查询”的意图，或者让现有的购物智能体通过LLM的判断来调用这个新工具。通常，只要工具描述清晰，LLM在理解用户问题包含订单号时，会自动尝试调用OrderStatusQuery工具。

通过这种方式，你可以不断扩展智能体的能力，比如添加“优惠券查询”、“物流跟踪”、“用户评价查询”等工具，打造一个功能更全面的购物助手。

6. 常见问题排查与性能优化实录

在实际部署和运行中，你肯定会遇到各种各样的问题。下面是我总结的一些典型问题及其解决方法。

6.1 启动与运行时错误

问题现象	可能原因	解决方案
`ModuleNotFoundError: No module named 'xxx'`	依赖未安装或虚拟环境未激活。	1. 确认虚拟环境已激活（命令行前有`(venv)`）。 2. 运行`pip install -r requirements.txt`。如失败，尝试手动安装缺失包`pip install xxx`。
`google.api_core.exceptions.PermissionDenied: 403 ...`或`Invalid API Key`	Google API密钥错误或未设置。	1. 检查`.env`文件是否存在，且`GOOGLE_API_KEY`的值正确无误，前后无空格。 2. 确认该API密钥在Google AI Studio中已启用，且未过期。 3. 确保项目已正确加载环境变量（可使用`print(os.getenv(‘GOOGLE_API_KEY’))`调试）。
`sqlite3.OperationalError: no such table: products`	数据库未初始化或初始化失败。	运行`python scripts/init_db.py`初始化数据库。检查`data/`目录下是否有`products.db`文件。
访问`localhost:5000`无响应或连接失败	Flask服务未启动或端口被占用。	1. 检查终端是否成功运行`python app.py`且无报错。 2. 检查是否有其他程序占用了5000端口（如`lsof -i:5000`或 `netstat -ano
聊天界面能打开，但发送消息后长时间无回复或报错	LLM API调用超时、网络问题或智能体逻辑错误。	1.查看控制台日志：这是最重要的调试信息源。看错误是出在路由、工具调用还是LLM生成阶段。 2.网络问题：检查是否能正常访问Google服务。如果是国内环境，可能需要配置网络。 3.Token超限：如果对话历史很长，可能超过模型上下文长度。考虑缩短`ConversationBufferMemory`的保留轮数。
政策问答总是回答“不知道”或答案不相关	FAISS向量库未正确构建或检索策略不佳。	1. 确认`scripts/init_db.py`成功运行并生成了FAISS索引文件。 2. 检查`policy.txt`文件内容是否完整。 3. 尝试调整文本分块的`chunk_size`，比如从256调到512。 4. 在代码中打印出每次检索到的top-k个文本片段，看是否真的相关。

6.2 逻辑与效果问题

问题现象	可能原因	解决方案
用户明明在问商品，却被路由到闲聊。	1. 购物路由的示例语句覆盖不足。 2. 购物路由的相似度阈值设置过高。	1. 丰富`shopping_route`的`utterances`，加入更多购物场景的多样问法。 2. 适当降低`shopping_route`的阈值。
商品搜索时，LLM无法正确提取查询条件（如颜色、尺寸）。	1.`ProductSearchTool`的函数描述不够清晰。 2. LLM（Gemini）在特定场景下表现不稳定。	1. 优化工具描述，明确每个参数的含义和格式（如`color`是字符串，`max_price`是数字）。 2. 使用Few-shot Prompting：在给LLM的指令中，提供几个“用户问题 -> 应调用工具及参数”的示例，引导它学习。
回复速度慢，尤其是第一次查询。	1. 冷启动：加载模型、连接数据库等。 2. 网络延迟（调用Google API）。 3. 数据库查询或向量检索未优化。	1.缓存：对常见的政策问答结果进行缓存。 2.数据库索引：确保商品表的关键字段已建立索引。 3.异步处理：对于耗时操作（如某些工具调用），可以考虑使用异步框架（如 Quart 替代 Flask）或后台任务，避免阻塞请求。
多轮对话中，LLM“忘记”了之前的上下文。	`ConversationBufferMemory`的缓冲区大小有限，或者记忆未被正确传递。	1. 确认记忆对象被正确添加到对话链（Chain）或智能体（Agent）中。 2. 如果对话很长，考虑使用`ConversationSummaryMemory`或`ConversationBufferWindowMemory`。前者会总结历史对话，后者只保留最近N轮，都能节省Token并保持关键记忆。
智能体在应该使用工具时，却选择了直接由LLM生成回答（导致幻觉）。	Agent的Prompt或类型设置可能未充分鼓励工具使用。	1. 在创建Agent的Prompt中，明确强调“当你需要查询商品信息、政策信息或订单状态时，必须使用相应的工具”。 2. 尝试不同的Agent类型，如`STRUCTURED_CHAT_ZERO_SHOT_REACT_DESCRIPTION`，它通常对工具调用有更好的支持。

6.3 性能与成本优化建议

减少不必要的LLM调用：闲聊路由的处理，在初期为了简单可以使用LLM。但如果流量大，可以考虑用更轻量的规则或小模型来响应简单的问候语（如“你好”、“谢谢”），从而节省成本和延迟。
优化Prompt，减少输出Token：在给LLM的指令中，要求它“回复简洁”或“用列表形式摘要回答”，可以控制它生成文本的长度。对于商品列表，可以让LLM只生成摘要，而将完整列表以结构化形式（如卡片）在前端展示。
实施速率限制和缓存：在app.py中为API端点添加简单的速率限制，防止滥用。对完全相同的政策查询（经过向量化后相似度极高）的结果进行短期缓存（如1分钟），可以大幅减少对LLM和向量检索的调用。
监控与日志：记录每个请求的路由决策、工具调用情况和Token消耗。这不仅能帮你排查问题，也是分析成本构成和优化方向的重要依据。可以考虑集成像LangSmith这样的LLM应用监控平台。

这个项目就像一个功能完整的AI应用样板间，涵盖了从意图识别、信息检索到决策生成的全流程。