基于 LangChain 的商城智能客服落地实践

基于 LangChain 的商城智能客服落地实践项目背景api-nestNestJS 智能服务为商城小程序提供 AI 智能客服能力技术栈NestJS 11 TypeScript · LangChain 1.x · TypeORM · MySQL与 ThinkPHP 8 商城业务共享库涉及代码src/config/llm.config.ts·src/modules/ai_chat/·src/modules/ai_mall/状态一期已完成开发并实测验证通过一、技术框架简略描述1.1 LangChain 是什么LangChain 是一个面向大语言模型LLM应用开发的框架项目使用的 1.x 版本由四层抽象构成抽象层核心概念解决的问题模型层BaseChatModel及各厂商实现ChatOpenAI/ChatDeepSeek/ChatOllama屏蔽不同大模型平台的 SDK 差异统一调用接口消息层BaseMessage/ 多模态 content blocks统一 system / user / assistant 消息与图文混合内容的表示工具层tool() zod schemaStructuredTool把任意函数封装成模型可调用的工具参数强类型约束智能体层createAgent()预置智能体内建「模型思考 → 调用工具 → 回喂结果 → 继续思考」的 ReAct 循环与之同生态的还有LangGraph以状态图组织多节点、带循环与人工干预的复杂编排和LangSmith链路追踪与评估。三者是递进关系单智能体场景用 LangChain 即可编排复杂度上升再引入 LangGraph。1.2 与其他路线的定位差异「LLM 工具调用」并非只有一种做法各路线定位不同路线能力边界适用场景裸调 OpenAI 兼容 SDK单次调用与 function calling 可用但 Agent 循环、多平台适配、消息归一化均需手写一次性脚本、极简调用LlamaIndex以 RAG 数据检索为强项Agent 编排非其主场文档知识库问答LangGraph状态图编排支持循环、分支、持久化检查点多步骤工作流、多智能体协作LangChain覆盖「模型抽象 → 工具协议 → 智能体」全链路与 LangGraph/LangSmith 同栈演进单智能体 结构化工具调用的生产应用本项目的形态是单智能体 少量结构化查询工具正落在 LangChain 的甜区用最小的框架成本获得完整的 Agent 能力同时保持未来向 LangGraph 升级的路径工具与模型可直接作为图节点复用。二、项目需求应用场景2.1 业务痛点商城小程序的客服场景存在四个结构性问题痛点现状业务影响商品咨询依赖人工价格、库存、规格等问题等待客服回复响应慢夜间与高峰期咨询流失搜索体验单一仅支持关键词精确匹配口语化表达搜不到潜在成单机会流失商品信息分散名称、价格、库存、SKU 规格、分类分布在不同页面用户需多次跳转才能了解一个商品图片咨询无法处理用户截图/拍照咨询时无法识别商品纯人工处理成本高2.2 核心诉求7×24 小时即时应答商品咨询秒级响应无需人工值守数据必须精确价格、库存、销量等数字 100% 来自数据库实时查询杜绝大模型幻觉多轮对话连贯支持「第一个多少钱」「它的库存呢」这类上下文追问图文双通道文字咨询走商品问答图片咨询走视觉理解覆盖小程序主要咨询形态架构可演进后续接入订单查询、售后政策、RAG 知识库时不改主链路。2.3 技术路线决策针对「让 AI 掌握真实商品数据」候选路线有三条关键词规则机器人维护成本高、覆盖面窄、RAG 向量知识库文档有同步周期价格库存等数字易过期失真、Tool Calling 实时查库。由于商品咨询是强结构化、强实时性场景最终选定 Tool Calling 路线智能服务与商城系统共享同一 MySQL 数据库AI 在对话中实时查询零同步延迟RAG 保留为二期能力与 Tool Calling 形成结构化 非结构化互补。三、实际落地3.1 总体架构┌─────────────────────────────────────────────────────────────┐ │ 商城小程序微信 │ │ 图文聊天界面 · 消息会话 │ └───────────────────────┬─────────────────────────────────────┘ │ HTTPS ▼ ┌─────────────────────────────────────────────────────────────┐ │ api-nest 智能服务NestJS │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ ai_chat 智能客服模块 │ │ │ │ · 双通道路由文本→Agent / 图片→视觉模型 │ │ │ │ · 多轮历史管理 · 客服人设 System Prompt │ │ │ └──────────────┬──────────────────────┬──────────────────┘ │ │ │ 纯文本 │ 含图片 │ │ ▼ ▼ │ │ ┌──────────────────────────┐ ┌──────────────────────┐ │ │ │ LangChain Agent │ │ 视觉大模型 │ │ │ │ createAgent(model, │ │ 图文理解直接作答 │ │ │ │ tools, systemPrompt) │ └──────────────────────┘ │ │ └──────────────┬───────────┘ │ │ │ Tool Calling │ │ ▼ │ │ ┌───────────────────────────────────────────────────────┐ │ │ │ ai_mall 商品知识库模块只读 │ │ │ │ 4 个查询工具模糊搜索 / 商品详情 / 分类清单 / 分类浏览 │ │ │ └──────────────┬────────────────────────────────────────┘ │ └─────────────────┼─────────────────────────────────────────────┘ │ TypeORM 只读查询 ▼ ┌─────────────────────────────────────────────────────────────┐ │ MySQL 共享数据库 tb_mall与 TP8 同库 │ │ product / app_category / sku_stock 等商城表 │ └─────────────────────────────────────────────────────────────┘3.2 多平台模型工厂src/config/llm.config.ts把「选哪个大模型平台」收敛为一个环境变量LLM_PLATFORM业务代码只面对createChatModel()// dashscope默认qwen-plus 文本 / qwen3-vl-plus 视觉// deepseekdeepseek-chat纯文本// ollama本地 qwen2.5 / qwen3-vl满足数据不出内网场景constllmcreateChatModel({vision:true})// 视觉任务constagentcreateAgent({model:createChatModel(),tools,systemPrompt})BaseChatModel统一抽象使平台切换零业务代码改动密钥缺失时给出可读报错视觉标志位自动映射到平台的视觉模型。3.3 商品知识库工具集src/modules/ai_mall/ai_mall.tools.ts用tool() zod schema 定义 4 个只读查询工具工具描述面向模型编写说明用途与调用时机模型据此自主决策工具能力典型触发语search_products关键词模糊搜索在售商品名称 关键词双字段「有没有保温杯」get_product_detail按商品编号查价格、库存、SKU 规格、详情摘要「第一个多少钱」list_categories列出全部分类「你们都卖什么品类」list_products_by_category按分类浏览在售商品「手机分类下有什么」constsearchProductstool(async({keyword})JSON.stringify(awaitmallService.searchProducts(keyword)),{name:search_products,description:按关键词模糊搜索商城在售商品...,schema:z.object({keyword:z.string().describe(搜索关键词)}),},)设计要点参数强类型约束zod schema 自动转为各模型的 JSON Schema模型提取参数错误在协议层即被拦截打不到 SQL返回明确语义空结果返回「商品不存在或已下架」等可读信息避免模型误读空数组查询语义对齐商城业务统一过滤deleted 0且仅在售排序规则置顶 排序值 id 倒序对齐 TP8 现有 v1 接口——AI 看到的商品世界与用户端完全一致只读实体隔离mall 模块独立定义只读 Entity不含成本价等敏感字段AI 链路天然无法触及经营敏感数据。工具集通过 NestJS 依赖注入装配ai_mall.module.ts的MALL_TOOLS令牌 useFactory测试中可整体 mock不依赖真实模型与数据库。3.4 智能客服 Agentsrc/modules/ai_chat/ai_chat.service.ts的chat()方法是链路核心双通道路由 Agent 构造// 纯文本路径智能体 4 个商品工具 客服人设constagentcreateAgent({model:createChatModel(),tools:this.mallTools,systemPrompt,})constresultawaitagent.invoke({messages:[...historyMessages,{role:user,content:text}],})returnresult.messages.at(-1)?.content三条关键设计双通道解耦携带图片时直接调用视觉模型llm.invoke多模态消息image_urltext不挂工具——规避视觉模型 Tool Calling 不稳定的问题纯文本才走 Agent历史消息安全过滤仅接收 user/assistant 角色消息过滤工具中间态消息tool 消息需tool_call_id前端无法提供防止协议层注入场景上下文注入systemContext可选拼接到 system prompt如「用户当前咨询的商品 X」让 AI 默认按当前商品回答避免重复追问。3.5 防幻觉约束客服人设 Prompt智能体内置六条强制规则是数据可信的核心保障规则内容先查后答任何商品相关问题必须先调用工具查真实数据严禁编造查无如实查不到时如实告知并建议更换关键词编号锚定列举商品必须附上来自工具返回的真实编号ID 溯源详情查询的 ID 只能来自本轮或历史对话中工具的真实返回表达规范中文作答、简洁清晰、多商品列表化边界友好商品无关问题礼貌自然回应不生硬拒绝其中「编号锚定 ID 溯源」解决了一个实测中暴露的真问题多轮追问时「第一个多少钱」模型会编造商品 ID。通过强制要求列举商品时附带工具真实返回的编号「编号」成为多轮对话中的数据锚点模型只能引用真实存在过的 ID从机制上根除编造。3.6 一次完整对话的内部流程以「有没有保温杯第一个多少钱」为例POST /api/chat/message { message, history } │ ▼ ai_chat.chat() 判定纯文本路径 │ ▼ createAgent({ model, tools: MALL_TOOLS, systemPrompt }) │ 4 个 zod schema 已转为模型的 JSON Schema ▼ agent.invoke({ messages: [...history, user] }) │ ├─► 第 1 轮模型输出 tool_call │ → search_products(保温杯) → TypeORM 查询 tb_mall │ → JSON 结果回喂role: tool 消息由框架自动拼装 │ → 模型组织回答按约束附上真实商品编号 │ └─► 第 2 轮追问模型从历史提取真实编号 → get_product_detail(12) → 返回价格/库存/SKU → 最终回答 │ ▼ result.messages.at(-1) 取终态文本返回小程序框架自动完成了 tool_call 解析、tool_call_id配对、role: tool消息拼装、循环终止判断业务代码只写「人设 工具集 取终态」。四、技术成果与总结4.1 已交付成果成果说明图文对话接口POST /api/chat/message支持文本/图片/多轮历史/场景上下文商品知识库模块4 个只读查询工具直连共享 MySQL查询语义对齐商城 v1 接口LangChain Agent 客服三行构造代码获得完整工具调用回路零协议工程代码多平台模型工厂LLM_PLATFORM环境变量一键切换 dashscope / deepseek / ollama防幻觉机制六条人设规则 zod 参数约束 编号锚定多轮 ID 编造问题修复并回归验证画布文本节点接口POST /api/chat/text不挂工具的纯文本生成走 deepseek 平台带余额计费校验4.2 技术收益协议代码归零Agent 循环、工具协议、消息序列化全部由框架承担ai_chatai_mall两个模块的 LangChain 相关胶水代码约 30 行数据可信回答中每个数字来自当次 SQL 查询配合 pino 结构化日志「AI 查了什么」可回放审计零厂商锁定换模型平台不改业务代码本地 Ollama 部署满足数据不出内网的合规场景写入风险为零AI 链路没有任何写库路径从架构上杜绝误改商品/订单数据。4.3 演进路线阶段能力框架侧准备二期RAG 知识问答退换货政策、使用指南ai_mbti模块已用langchain/ollamaEmbeddings 跑通向量检索与 Tool Calling 互补即可上线二期小程序正式接入会话持久化 SSE 流式输出BaseChatModel.stream()原生支持三期订单/售后工具扩展新增tool()定义并注册进MALL_TOOLS主链路零改动远期多步骤编排如画布整图生成现有 Tool/Model 可直接作为 LangGraph 节点原材料同栈升级4.4 总结本项目验证了一个务实结论在「单智能体 结构化工具调用」这个复杂度甜区上LangChain 用模型抽象、工具协议、预置 Agent 三块积木把 LLM 应用的协议工程成本压到接近于零使团队精力全部投入在业务工具设计与防幻觉规则上。技术选型上没有追求「最强大的框架」而是选择了「抽象层级刚好匹配当前复杂度、且保留同栈演进路径」的方案——工具 zod 化、模型切换配置化、Agent 循环框架化这三条原则也是后续扩展RAG、订单工具、流式输出可以复用的既定范式。当编排需求真正跨过「多节点 循环 人工干预」的门槛时再引入 LangGraph届时今天的每一个 Tool 都是图节点的原材料。