1. 从服范-九添菜菜这个项目名说起一个智能体到底在解决什么问题第一次看到服范-九添菜菜大模型Agent智能体开发实战这个标题很多人会愣一下——服范是什么九添菜菜又是什么其实把名字拆开看就明白了这是一个围绕餐饮服务场景做的大模型智能体项目服范取的是服务规范、服务范式的意思九添菜菜则是项目内部给这个智能体起的拟人化代号类似给客服机器人起个花名。名字本身不重要重要的是它背后代表的一类需求把大模型的通用能力收敛到一个具体业务场景里让它能稳定、可控、可复现地完成一串任务。我在过去一年多时间里陆陆续续做过七八个智能体项目从最早的套个提示词就上线到后来老老实实搭工作流、写工具函数、做评测集踩的坑基本能写一本书。这个服范-九添菜菜项目本质上就是一个典型的垂直场景智能体用户可能是餐厅顾客、也可能是门店运营用自然语言提出需求智能体理解意图后调用一系列工具查菜单、算价格、排班、生成话术、记录反馈最后给出一个结构化或半结构化的结果。它解决的问题很具体传统餐饮服务里很多环节靠人记、靠人传、靠人判断效率低且容易出错。比如顾客问我们六个人预算三百有没有推荐一个熟练的服务员能秒答但一个新手可能要翻半天菜单。智能体要做的就是把这个熟练服务员的经验固化成可调用的能力。适合谁看这篇内容三类人一是刚接触Agent开发、想找一个完整案例练手的开发者二是业务侧想落地智能体、但不知道从哪切入的产品或运营三是已经做过Demo、但发现Demo很美好上线就翻车的同行。我会尽量把每一步的为什么讲清楚而不是只丢一堆代码。2. 智能体不是更长的提示词拆解九添菜菜的核心架构2.1 为什么单纯堆提示词一定会失败很多人做智能体的第一反应是写一个超长的System Prompt把菜单、规则、话术全塞进去然后让模型自己发挥。我早期也这么干过结果非常稳定地翻车。原因有三个第一上下文长度和注意力是有限的。你把三百道菜的做法、价格、库存全塞进提示词模型在回答推荐个清淡的时很可能被无关信息干扰推荐出一道重油重辣的菜。这不是模型笨是信息过载。第二业务规则会变提示词改起来要命。今天搞活动满减明天换菜单你不可能每次都去改那段几千字的提示词改完还要重新测一遍成本极高。第三无法保证输出格式。你希望它返回JSON它偏要给你写一段散文下游系统根本没法解析。所以九添菜菜这个项目从一开始就没有走大提示词路线而是采用了**意图识别 工具调用 状态管理**的三层结构。这也是目前主流智能体框架无论是LangChain、LangGraph还是其他的通用思路。2.2 三层结构各自负责什么第一层意图识别与路由。用户说一句话先判断他想干什么。是问菜品推荐是查营业时间是投诉还是闲聊这一层通常用一个轻量模型或规则小模型组合来完成目的是快速分流避免所有请求都走最贵的模型。第二层工具调用与执行。一旦确定意图就调用对应的工具函数。比如推荐菜品这个意图会触发一个recommend_dishes函数它接收人数、预算、口味偏好等参数去查数据库或调用内部API返回候选列表。注意这里的数据查询是确定性的不依赖模型记忆所以结果可靠。第三层状态管理与多轮对话。用户不会一次把话说全。他可能先说六个人你问预算他说三百左右你推荐完他又说有没有不辣的。这就需要维护一个对话状态记住已经收集到的信息避免重复询问。LangGraph这类框架的StateGraph就是干这个的。我用一个简化的流程来说明这三层怎么串起来# 伪代码示意非完整可运行代码 def handle_user_input(user_input, state): intent classify_intent(user_input) # 第一层 if intent recommend: params extract_params(user_input, state) # 从对话中抽取参数 if not params.get(budget): return ask_for_budget(state) # 信息不全追问 result recommend_dishes(params) # 第二层调用工具 state[last_recommendation] result return format_response(result) # 第三层结合状态生成回复 elif intent hours: return query_business_hours() # ...其他意图这段伪代码看起来简单但每一行背后都有讲究。比如classify_intent你是用规则匹配还是用模型规则快但覆盖不全模型准但慢且贵。我的经验是高频、边界清晰的意图用规则长尾、表达多样的意图用模型。九添菜菜里营业时间订座电话这种就用关键词匹配推荐搭配忌口这种就用模型分类。2.3 工具函数的设计原则别让模型做它不擅长的事这是我想重点强调的一点。很多新手会把计算总价判断库存这种事交给模型结果就是它算错、它幻觉。凡是能用代码确定性完成的绝不要交给模型。九添菜菜里有一个典型场景顾客点了一桌菜要算总价并应用满减。正确做法是写一个calculate_total(items, promotions)函数用纯代码算模型只负责把顾客的话解析成items列表。这样算出来的价格永远准确而且可以单元测试。工具函数的另一个原则是参数要明确、返回值要结构化。不要设计一个do_something(query)这种模糊接口而应该是search_menu(category, taste, price_range)这种参数清晰的函数。参数越明确模型越容易正确调用出错也越容易定位。3. 从零搭一个九添菜菜环境、选型与第一个能跑的版本3.1 模型选型不是越贵越好做智能体模型选型是第一个岔路口。我的建议是分层使用任务类型推荐模型级别理由意图分类小模型/本地模型任务简单高频调用成本敏感参数抽取中等模型需要一定理解能力但不需要太强复杂推理/生成大模型涉及多步推理、创意生成时才用格式化输出中等模型约束解码需要严格JSON可用结构化输出能力九添菜菜项目里意图分类我用的是一个7B级别的本地模型跑在一张消费级显卡上延迟低、成本几乎为零。参数抽取和最终生成用的是云端大模型API。这样整体成本能压到纯用大模型的十分之一左右。提示不要一上来就追求最强模型。先用小模型跑通流程发现哪里效果不行再针对性换大模型。这样你能清楚知道瓶颈在哪而不是盲目堆算力。3.2 框架选择LangGraph还是自己写现在智能体框架很多LangChain、LangGraph、AutoGen、Dify等等。我的看法是如果你要快速验证用Dify这类可视化平台如果你要深度定制和上线用LangGraph或自己写状态机。九添菜菜用的是LangGraph的思路但核心状态管理是自己写的。原因是我需要精确控制每一步的流转而且不想被框架的抽象层挡住调试视线。自己写状态机的好处是出问题时你能一眼看到是哪个状态、哪个转移条件出了错。一个最简的状态定义大概长这样class AgentState: def __init__(self): self.messages [] # 对话历史 self.intent None # 当前意图 self.slots {} # 已收集的参数槽位 self.pending_question None # 待追问的问题 self.tool_results [] # 工具调用结果这个结构看着朴素但它把对话和任务分开了。messages是给人看的slots是给机器用的。很多项目失败就是因为把两者混在一起导致状态混乱。3.3 第一个能跑的版本只做一件事新手最容易犯的错是贪多。一上来就想做全功能结果哪个都不完整。我的建议是第一个版本只做一个意图、一个工具、一条路径。九添菜菜的第一个可运行版本只做根据人数推荐菜品这一件事。流程是用户说我们四个人吃饭意图识别为recommend参数抽取得到people4追问预算和口味用户回答后调用recommend_dishes返回推荐结果就这六步跑通它你就理解了智能体的核心循环。之后再往上加意图、加工具、加多轮状态都是在这个骨架上扩展。我实测下来这个最小版本大概两百行代码就能搞定但它是后面所有复杂功能的基础。不要跳过这一步直接抄复杂项目你会看不懂每一行为什么这么写。4. 让九添菜菜真正能用参数抽取、追问策略与容错4.1 参数抽取从自然语言到结构化数据的惊险一跃用户说我们六个人想吃得清淡点预算别超过四百你要抽取出{people: 6, taste: 清淡, budget: 400}。这一步做不好后面全错。我的做法是用模型做抽取但用Schema约束输出。具体来说定义一个JSON Schema告诉模型必须按这个格式返回。现在很多模型API都支持结构化输出structured output能大幅降低格式错误率。{ people: integer or null, taste: string or null, budget: number or null, avoid: array of strings }注意所有字段都允许为null。因为用户可能只说了一部分信息你不能强迫模型编造。抽不到的就留空后面用追问补上。这里有个坑中文数字和模糊表达。用户说六个人俩人三四位模型有时候会抽错。我的处理是在抽取后加一层归一化把俩转成2三四转成3取最小值保守估计六转成6。这层归一化用规则做比让模型做更可靠。4.2 追问策略别像查户口一样问信息不全就要追问但追问的方式直接影响体验。我见过一些智能体像查户口一样请问几位请问预算多少请问口味偏好——用户烦都烦死了。九添菜菜的追问策略是合并追问 智能默认如果缺多个信息一次性问方便告诉我大概几位、预算多少吗口味有偏好吗如果某个信息可以从上下文推断就不问。比如用户说就我和我老婆那people直接推断为2。如果某个信息不影响核心结果可以用默认值。比如口味没提默认不限而不是非要问出来。这个策略的实现是在状态机里维护一个missing_slots列表每次生成回复前检查如果列表非空就生成一个合并的追问。追问的措辞也可以预先写好模板避免每次让模型现编。4.3 容错模型会犯错系统不能崩智能体上线后你会遇到各种意外模型返回了非法JSON、工具调用超时、用户输入了完全无关的内容。这些都必须有兜底。我的容错清单JSON解析失败重试一次如果还失败降级到规则解析或返回友好提示。工具调用超时设置超时时间比如3秒超时后返回稍等我查一下并异步重试或者直接给一个保守的默认结果。意图识别置信度低如果模型对意图的判断置信度低于阈值不要硬猜直接问您是想问菜品推荐还是其他问题用户输入无关内容识别为chitchat或unknown用预设话术引导回正题。这些兜底逻辑代码量不大但能极大提升系统的稳。我踩过的最大坑就是没做超时处理结果某个内部API挂了整个智能体卡死用户等了一分钟没反应直接关掉。5. 评测与迭代怎么知道九添菜菜是真的变好了5.1 没有评测集的智能体项目都是耍流氓这是我最想对同行说的一句话。很多人做完智能体自己试几句觉得还行就上线了。结果真实用户一用各种奇葩输入效果惨不忍睹。正确做法是在开发早期就建立评测集。九添菜菜的评测集包含三类样本正常样本标准表达比如六个人预算三百推荐几个菜。边界样本模糊表达、多意图混合、信息缺失比如随便来点、上次那个菜再来一份。对抗样本故意刁难比如你们这有没有不存在的菜、帮我算一下一加一。每类样本至少几十条覆盖主要意图和工具。每次改动提示词、换模型、加工具都跑一遍评测集看通过率变化。5.2 评测指标不只看对不对智能体的评测比传统分类任务复杂因为它是多轮的。我用的指标有指标含义目标意图准确率意图识别正确的比例95%参数抽取F1抽取参数的准确率和召回率90%任务完成率多轮对话后成功完成任务的比率85%平均轮次完成任务平均需要几轮对话越少越好幻觉率编造不存在信息的比例2%其中任务完成率是最重要的因为它反映端到端体验。一个意图识别98%但任务完成率只有60%的系统是不合格的。5.3 迭代的优先级先修高频错误拿到评测结果后不要眉毛胡子一把抓。我的做法是按错误频率排序先修出现最多的那类错误。比如九添菜菜早期最高频的错误是预算抽取错误占了所有错误的40%。那我就集中精力优化预算抽取加归一化规则、加few-shot示例、换更强的抽取模型。修完这一类整体通过率直接涨了15个百分点。这种抓大放小的迭代方式比均匀地优化每个环节效率高得多。因为长尾错误可能只占2%你花大力气修完整体提升也就2%。6. 上线之后才是真正的开始监控、反馈与持续优化6.1 日志要记什么智能体上线后日志是你的眼睛。但日志不是记得越多越好而是要记能帮你定位问题的关键信息。九添菜菜的日志包含用户原始输入脱敏后识别出的意图和置信度抽取的参数调用的工具和参数工具返回结果截断最终回复耗时分阶段有了这些当用户投诉它答非所问时你能快速定位是意图错了、参数错了、还是工具返回错了。6.2 用户反馈的收集与利用显式反馈点赞点踩要收集但更宝贵的是隐式反馈。比如用户重复问同一个问题 → 说明第一次没答好用户直接关闭对话 → 可能是不满意用户手动纠正 → 说明系统理解错了这些信号比点赞点踩更真实。九添菜菜里我会把用户连续两次表达同一意图标记为一次潜在失败纳入每周的复盘。6.3 一个真实的迭代案例上线两周后我们发现推荐菜品这个意图的完成率只有72%明显低于其他意图。查日志发现问题出在多轮对话中的指代消解。用户第一轮说推荐几个菜系统推荐了A、B、C。用户第二轮说第一个换成不辣的。系统这时候懵了——第一个指什么它没有记住上一轮的推荐列表。修复方案是在状态里显式保存last_recommendation并在参数抽取时把上一轮的推荐列表作为上下文传进去。改完之后这个意图的完成率涨到了89%。这个案例说明多轮对话的难点不在单轮理解而在跨轮的状态维护。很多智能体Demo很惊艳一进入多轮就露馅就是因为状态没管好。7. 关于智能体开发我踩过的最深的三个坑7.1 坑一把模型当数据库用早期我图省事把菜单信息直接写进提示词让模型记住。结果模型经常记混价格或者推荐已经下架的菜。后来改成工具查询问题立刻消失。教训模型是推理引擎不是存储引擎。所有事实性数据都应该放在外部通过工具查询。7.2 坑二忽视冷启动时的空状态用户第一次进来没有任何历史信息。这时候如果状态机设计得不好很容易出现系统不知道该问什么或者重复问已经问过的。我的做法是给每个意图定义一个最小信息集进入意图时先检查这个集合缺什么问什么问过的绝不重复问。7.3 坑三过度依赖单一模型有段时间我所有环节都用同一个大模型结果那个模型API一抖动整个系统就不可用。后来做了分层和降级意图分类用本地小模型抽取用中等模型生成用大模型。任何一层出问题都有降级方案。系统的可用性从看API脸色变成了基本稳定。8. 如果你现在要开始做自己的智能体最后分享一点个人体会。智能体开发这件事技术门槛其实没有想象中高真正的门槛在于对业务的理解和对细节的打磨。九添菜菜这个项目代码量不算大但每一处追问策略、每一个容错分支、每一条评测样本都是反复推敲出来的。如果你现在要开始我的建议是找一个你真正熟悉的场景哪怕很小比如帮同事订会议室或者整理每周工作汇报。先用最小版本跑通意图-工具-回复的循环然后建评测集然后一轮一轮迭代。不要一上来就追求大而全也不要迷信某个框架或某个模型。真正让智能体好用的从来不是模型有多强而是你有没有把它的能力恰当地约束在一个清晰的流程里。这个道理我在九添菜菜项目里体会得特别深。