给thinkphp8+mysql项目接入智能客服（技术落地）

文档定位：商城小程序 AI 智能客服建设汇报方案
配套后端：api-nest（NestJS 智能服务）· api-tp8（ThinkPHP 8 商城业务）
当前状态：核心链路已完成开发并实测验证通过

---

技术亮点：

"共享库直读"决策——相比 HTTP 同步方案，零同步开发、零延迟、数据永远最新，这是成本最低且最可靠的路线；

"编号锚定"防幻觉机制——多轮追问中模型编造商品 ID 的问题曾真实暴露，通过 Prompt 工程修复并实测验证，体现了方案的严谨迭代过程。

一、如何建设方案（建设思路）

1.1 业务背景与痛点

痛点	现状描述	对业务的影响
商品咨询依赖人工	用户询问价格、库存、规格需等待客服回复	响应慢，夜间/高峰期咨询流失
搜索体验单一	仅支持关键词精确搜索，用户表达模糊时搜不到	潜在成单机会流失
商品信息分散	名称、价格、库存、SKU 规格、分类分布在不同页面	用户需多次跳转才能了解一个商品
图片咨询无法处理	用户截图/拍照咨询商品时无法自动识别	纯人工处理，成本高

1.2 建设思路：让 AI 直接"读懂"真实业务数据

本方案的核心建设理念是 “AI 回答的每一个数据都来自真实数据库”：

• 不走"死知识库"路线：不把商品信息整理成静态文档喂给 AI（会过期、会失真），而是让 AI 在对话过程中实时查询商城数据库；
• 零数据同步延迟：智能服务与商城系统共享同一数据库，商品上下架、调价、库存变化即时反映在客服回答中，无需任何同步任务；
• 图文双通道：既支持文字咨询（走商品问答智能体），也支持图片咨询（走视觉大模型图文理解），覆盖小程序用户的主要咨询形态。

二、项目核心目标

2.1 业务目标

目标	说明	衡量方式
7×24 小时即时应答	商品咨询秒级响应，无需人工值守	接口响应时长、夜间咨询承接率
提升商品触达	用"对话式导购"替代搜索框，模糊表达也能找到商品	客服会话引导的商品曝光量
降低人工客服成本	标准化商品问题（价格/库存/规格/分类）由 AI 承接	人工客服工单占比下降
增强用户体验	支持图文多模态咨询，回答附带商品编号便于追问	用户满意度、会话轮次

2.2 技术目标

1. 数据准确率 100%：所有价格、库存、销量回答均来自数据库实时查询，杜绝大模型"幻觉"；
2. 多轮对话连贯：支持上下文追问（如"第一个多少钱？"“它的库存还有多少？”），无需重复描述；
3. 架构可演进：预留 Tool Calling 工具扩展点，后续接入订单、物流、售后只需新增工具，不改主链路。

---

三、技术路线选择（技术栈决策）

3.1 三条候选路线对比

针对"让 AI 掌握真实商品数据"，业界主流有三条路线：

对比维度	路线 A：传统关键词/规则机器人	路线 B：RAG 向量检索知识库	路线 C：Tool Calling 实时查库（本方案）
数据实时性	依赖人工维护话术，严重滞后	依赖文档重新切片入库，存在同步周期	实时，每次对话直查数据库
数字精确性	精确但覆盖面窄	弱（价格/库存等数字易检索失真）	精确（结构化 SQL 查询）
自然语言理解	无（只能命中关键词）	强	强（大模型自主决策）
维护成本	高（话术库人工维护）	中（文档更新需重建索引）	低（无额外知识库维护）
建设成本	低	中（需向量库基建）	低（复用现有数据库与后端框架）
适用场景	固定 FAQ	政策、帮助文档等非结构化知识	强数据依赖的结构化业务问答

3.2 决策结论

商品咨询属于强结构化、强实时性场景（价格库存随时变化、数字必须精确），路线 B 的 RAG 在此类场景存在"检索到的数字可能已过期"的固有缺陷。

最终选定：路线 C —— 共享数据库直读 + LLM Tool Calling（工具调用）智能体，理由：

1. 智能服务与商城系统共享同一 MySQL 数据库，天然免同步、零延迟；
2. Tool Calling 让大模型"自主决定查什么"：用户说"有没有便宜点的保温杯"，模型自己选择搜索工具、提取关键词、查询后组织回答；
3. RAG 路线保留为二期能力，用于接入退换货政策、使用指南等非结构化知识，与 Tool Calling 形成互补。

---

四、技术架构概览（技术落地）

4.1 总体架构图

┌─────────────────────────────────────────────────────────────────┐
│                        商城小程序（微信）                          │
│                     图文聊天界面 · 消息会话                        │
└───────────────────────────┬─────────────────────────────────────┘
                            │ HTTPS（JWT 鉴权）
                            ▼
┌─────────────────────────────────────────────────────────────────┐
│              api-nest 智能服务（NestJS）                          │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  ai_chat 智能客服模块                                       │  │
│  │  · 图文双通道路由（文本→智能体 / 图片→视觉模型）              │  │
│  │  · 多轮对话历史管理                                         │  │
│  │  · 客服人设 System Prompt（防幻觉约束）                      │  │
│  └──────────────┬────────────────────────┬───────────────────┘  │
│                 │ 纯文本                  │ 含图片               │
│                 ▼                        ▼                      │
│  ┌──────────────────────────┐   ┌──────────────────────┐        │
│  │ LangChain Agent 智能体    │   │ 视觉大模型            │        │
│  │ （意图识别 + 工具调用）    │   │ （图片理解直接作答）   │        │
│  └──────────────┬───────────┘   └──────────────────────┘        │
│                 │ Tool Calling                                   │
│                 ▼                                                │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │  mall 商品知识库模块（只读）                                 │  │
│  │  4 个查询工具：模糊搜索 / 商品详情 / 分类清单 / 分类浏览      │  │
│  └──────────────┬────────────────────────────────────────────┘  │
└─────────────────┼────────────────────────────────────────────────┘
                  │ TypeORM 只读查询（内网直连）
                  ▼
┌─────────────────────────────────────────────────────────────────┐
│                  MySQL 共享数据库 tp8_admin                       │
│          product / app_category / sku_stock 等商城表              │
└─────────────────▲────────────────────────────────────────────────┘
                  │ 读写（业务正常通道）
┌─────────────────┴────────────────────────────────────────────────┐
│              api-tp8 商城业务服务（ThinkPHP 8）                    │
│           商品管理 · 订单 · 用户 · 小程序业务接口                    │
└──────────────────────────────────────────────────────────────────┘

4.2 关键落地决策

决策点	方案	收益
NestJS ↔ TP8 通信方式	共享数据库只读直连（替代 HTTP 接口同步）	免开发同步接口、免维护同步任务、数据零延迟
只读实体隔离	mall 模块独立定义只读 Entity，不含成本价等敏感字段	权限收敛，防止 AI 链路泄露经营敏感数据
查询语义对齐	过滤条件与排序规则对齐商城现有 v1 接口（deleted=0、仅在售、置顶优先）	AI 看到的商品世界与用户端完全一致
图片消息处理	视觉大模型独立通道，不挂载查库工具	规避视觉模型 Tool Calling 不稳定问题，图文理解更可靠
可观测性	nestjs-pino 结构化日志 + TypeORM SQL 日志/慢查询监控	每轮对话的查库轨迹可审计、可回放

4.3 一次完整对话的落地流程

以用户问"你们家有没有保温杯？第一个多少钱？"为例：

1. 小程序携带消息 + 历史对话 + JWT 令牌调用 POST /api/chat/message；
2. ai_chat 模块判定为纯文本路径，构造 LangChain Agent（客服人设 + 4 个商品工具）；
3. 第一轮：模型识别"找商品"意图 → 自主调用 search_products(keyword="保温杯") → mall 模块模糊匹配数据库 → 返回在售商品列表（附商品编号）；
4. 模型组织自然语言回答，按约束在名称后附上商品编号；
5. 第二轮（用户追问）：模型从历史对话中提取上轮工具返回的真实编号 → 调用 get_product_detail → 返回价格、库存、SKU 规格 → 作答；
6. 全程 SQL 查询均有日志留痕，回答中每个数字都来自当次查询。

---

五、核心技术方案（技术栈选型）

5.1 分层技术选型总表

层次	选型	选型理由
智能服务框架	NestJS 10 + TypeScript	模块化依赖注入、装饰器路由，与 LangChain 生态无缝集成
AI 编排框架	LangChain 1.x（createAgent + tool）	Agent 编排成熟稳定，工具定义用 zod Schema 强类型约束，模型调用参数零出错
大模型接入	多平台工厂模式：阿里云百炼（qwen-plus / qwen3-vl-plus）、DeepSeek、本地 Ollama	一个环境变量切换平台；云端满足效果，本地 Ollama 满足内网隔离与降本场景
图片理解	视觉多模态大模型（qwen3-vl 系列）	支持 data URL / 网络图直传，免自建 OCR
数据访问	TypeORM 只读实体	直连共享 MySQL，实体按表最小化建模，排除敏感列
数据库	MySQL 8.0（tp8_admin 共享库）	与商城业务库物理同库、逻辑只读隔离
业务后端	ThinkPHP 8（现有商城）	零改造，商品/订单/用户业务保持原状
鉴权安全	JWT 全局守卫	与现有账号体系打通，AI 接口不裸奔
日志与可观测	nestjs-pino + TypeORM SQL/慢查询日志	结构化日志便于检索，慢查询阈值监控保障查库性能
前端验证	Vue3 图文聊天页（管理后台已集成 Tiptap 富文本与对话 Demo）	开箱即用的联调与演示环境

5.2 商品知识库工具集（AI 的"手"）

mall 模块向智能体暴露 4 个查询工具，工具描述面向大模型编写，模型据此自主选择：

工具	能力	典型触发语
search_products	按关键词模糊搜索在售商品（名称 + 关键词双字段匹配）	“有没有保温杯”“iPhone 多少钱”
get_product_detail	按商品编号查完整详情：价格、库存、销量、SKU 规格、商品介绍	“第一个多少钱”“详细说说编号 12”
list_categories	列出全部商品分类	“你们都卖什么品类”
list_products_by_category	按分类浏览在售商品	“手机分类下有什么”

工具设计要点：

• 入参用 zod Schema 定义并附自然语言描述，模型提取参数不会出错；
• 返回统一 JSON 结构，空结果返回明确语义（“商品不存在或已下架”），避免模型误读；
• 所有查询强制过滤"未删除 + 在售"，AI 与用户看到的商品范围一致。

5.3 大模型平台策略

              ┌────────────── LLM_PLATFORM 环境变量 ──────────────┐
              │                    一键切换                        │
   ┌──────────▼─────────┐   ┌──────────────┐   ┌────────────────▼──┐
   │ 阿里云百炼 DashScope │   │   DeepSeek   │   │   本地 Ollama     │
   │ qwen-plus（问答）    │   │ deepseek-chat│   │ qwen2.5（纯文本） │
   │ qwen3-vl-plus（视觉）│   │ （纯文本）    │   │ qwen3-vl（视觉）  │
   └────────────────────┘   └──────────────┘   └───────────────────┘
        效果优先                成本备选            内网隔离/离线场景

• 生产推荐云端平台（效果与视觉能力最佳），密钥仅存于服务器环境变量；
• 若后续有数据不出内网的合规要求，可切换本地 Ollama 部署，架构零改动。

---

六、核心功能模块：意图识别与多轮对话管理

6.1 意图识别：由大模型 Agent 驱动，替代传统规则引擎

传统客服机器人依赖"关键词 → 话术"规则表，意图覆盖率低、维护成本高。本方案将意图识别交给大模型智能体：

用户输入 ──► 大模型理解语义 ──► 自主决策 ──┬──► 需要数据？调用对应查询工具
                                          ├──► 追问上轮商品？引用历史返回的编号
                                          └──► 闲聊/无关问题？礼貌自然回应

意图覆盖示例：

用户表达（模糊/口语化）	识别出的意图	智能体动作
“保温杯有货吗”	商品搜索 + 库存咨询	模糊搜索 → 汇总价格库存作答
“都卖些什么”	分类浏览	列出分类清单
“手机那一类有啥”	按分类浏览	定位分类 id → 列出在售商品
“第一个多少钱”	上下文指代 + 详情查询	从上轮工具结果取真实编号 → 查详情
“这个图里的东西你们有吗”	图片理解	走视觉模型通道识别图片内容

6.2 多轮对话管理

1. 对话历史透传：小程序端维护会话消息列表，每轮请求携带历史（user/assistant 消息），模型获得完整上下文，支持指代消解（“它”“第一个”）；
2. 跨轮数据锚定：System Prompt 强制要求列举商品时附商品编号，使"编号"成为多轮对话中的数据锚点——用户追问详情时，模型只能引用工具真实返回过的编号，从机制上根除多轮对话中模型编造商品 ID 的问题（该问题已在实测中暴露并通过约束修复验证）；
3. 历史消息安全过滤：仅接受 user/assistant 角色消息，过滤工具中间态消息，防止协议层注入。

6.3 防幻觉与安全约束（客服人设 Prompt 工程）

智能客服内置六条强制规则，是本方案数据可信的核心保障：

规则	内容
先查后答	任何商品相关问题必须先调用工具查真实数据，严禁编造
查无如实	查不到时如实告知，并建议更换关键词
编号锚定	列举商品必须附上来自工具返回的真实编号
ID 溯源	详情查询的 ID 只能来自本轮或历史对话中工具的真实返回
表达规范	中文作答、简洁清晰、多商品列表化
边界友好	商品无关问题礼貌自然回应，不生硬拒绝

6.4 图文双通道

通道	触发条件	处理链路
文本通道	仅文字消息	LangChain Agent + 商品工具查库作答
图文通道	携带图片（base64 / data URL / 网络图自适应）	视觉多模态模型图文理解直接作答

图片入参做了统一归一化：纯 base64 自动拼装 data URL，兼容小程序多种上传形态。

---

七、安全、稳定与可观测

维度	措施
数据安全	mall 模块只读实体、不暴露成本价等敏感列；API Key 仅存服务器环境变量
接口安全	JWT 全局鉴权守卫，AI 接口纳入统一账号体系
写入风险	AI 链路无任何写库路径，天然杜绝误改商品/订单数据
性能监控	TypeORM 慢查询阈值监控，超限 SQL 自动告警，保障查库工具不拖慢对话
可审计	nestjs-pino 结构化日志记录每轮请求，SQL 日志可回放"AI 查了什么"
容错	工具返回结构化空语义；模型服务异常时接口统一错误响应，不影响商城主业务

---

八、实施进展与演进规划

8.1 当前进展（一期已完成并实测通过）

• ai_chat 图文对话接口（文本 + 图片 + 多轮历史）
• mall 商品知识库模块（4 个查询工具，只读直连共享库）
• LangChain Agent 集成与客服人设 Prompt 约束
• 多轮对话 ID 编造问题修复与回归验证（链式查询：分类浏览 → 取编号 → 精确查详情）
• 多平台大模型工厂（dashscope / deepseek / ollama 一键切换）
• 管理后台图文对话调试页（可视化联调）

8.2 后续演进路线

阶段	能力	说明
一期（已完成）	商品问答智能客服	本方案内容，实测通过
二期	RAG 知识问答	接入退换货政策、使用指南等文档知识库，与 Tool Calling 形成"结构化 + 非结构化"互补
二期	小程序端正式接入	商城小程序聊天入口上线，会话持久化
三期	订单/售后工具扩展	新增订单查询、物流跟踪工具，Agent 主链路零改动
三期	流式输出与会话体验升级	SSE 流式回答、打字机效果、快捷问题推荐

---

附：一句话总结

本方案以 “共享数据库只读直连 + 大模型 Tool Calling 智能体” 为核心架构，让商城小程序获得一位 7×24 小时在线、回答全部来自真实数据的图文智能客服；一期已开发完成并实测验证，具备向订单、售后、知识问答平滑演进的能力。